Update client library to support entitlements

[ELepolt]

Add Entitlements support to library. Callable by account.entitlements()

[lsfernandes92]

From the client lib perspective, do we really want to respond with the resource link? I mean, I know that the entitlements API endpoint already responds with the granted_by node with one array that contains the resource links, but there it makes sense because, in my opinion, it's better to keep the API response clean and it is easy to navigate and check out the resource(by just click into the resource link, for example). But for the client lib, we should expect that someone is embedding calls from this lib into their code. For example:

try {
  $entitlements = Recurly_EntitlementList::get('<ACCOUNT_CODE>');
  foreach ($entitlements as $entitlement) {
    print "Entitlement: {$entitlement->granted_by}\n";
  }
} catch (Recurly_NotFoundError $e) {
  print "Invalid account code: $e";
}

So what the consumer of this lib is supposed to do with the subscription/external subscription resource link? Isn't better to respond with the full subscription or external subscription object?

[ELepolt]

I somewhat disagree with the client lib doing more than the API response. Why would they be any different? If we wanted the user to have more detail we would include it in the presenter.

When the API discussion occurred the idea was that if the merchant wanted more details, they would make the request themselves. I think that the logic process is "First and foremost does this user have this entitlement?" and that typically the answer is yes or no and that's the end.

If the merchant thinks the user shouldn't have it, then they can go digging on which granted_by is giving them the details.

I see this as a similar way that we show plan_codes in the coupon request. We simply return the plan_code and no other details about the plan.

[lsfernandes92]

Why would they be any different?

I don't know really and I am just questioning hehehehe. Why does the merchant prefer to use the client lib instead of just requesting the entitlements API?

What's the value of having the resource link in the client lib response? What really matters here is the subscriptions IDs.

[ELepolt]

The value is that they don't have to write their own API wrapper. In theory what we publish is 'official' and won't break, unlike a piece of code written by a dev who leaves a year later and no one understands it.

I think the point is that we as developers don't actually know what the client wants or what the value is, we rely on Chris and Dom to figure that out for us.