Add JavaScript-style "links"

[Pimm]

API

To get the refunds for a payment, you can do:

const payment = await mollieClient.payments.get('tr_bT5VxTvBtB');
const refunds = await mollieClient.paymentRefunds.list({ paymentId: payment.id });

Or^*:

const payment = await mollieClient.payments.get('tr_bT5VxTvBtB', { embed: PaymentEmbed.refunds });
const refunds = payment._embedded?.refunds;

Or (booo! don't do this! ❌):

const payment = await mollieClient.payments.get('tr_bT5VxTvBtB');
const refunds = await fetch(payment._links.refunds.href, …);

Now, you can also do it in a way more native to JavaScript:

const payment = await mollieClient.payments.get('tr_bT5VxTvBtB');
const refunds = await payment.getRefunds();

This makes _links and _embedded redundant entirely ‒ and candidates for removal in 4.0.0.

[*] the version with _embedded is not great, as it can produce undefined; whereas the first and last versions will always produce a (potentially empty) array.

Internal

getRefunds internally uses the embedded refunds if present, or fetches them if not.

Caveats

• Because getRefunds "sometimes" uses refunds which were embedded when the payment was fetched, refunds which were created in the timeframe between the payments.get and getRefunds calls might or might not appear in the array. This might be confusing. However, this library doesn't guarantee to keep any data "fresh". I feel consumers of this library should be aware that data they keep in memory for longer periods of time becomes stale, in general.
• If getRefunds ends up calling the endpoint (because no refunds were embedded), that endpoint will return a limited number of refunds as it applies pagination. This might be unexpected. I am currently unsure how this compares to embedding refunds. Does the API return all refunds when embedded? I'll look into this before releasing.
• Because there is no endpoint which returns all payments for an order (of which I know), order.getPayments() has an odd implementation.

[edorivai]

LGTM