Paylike low-level request helper

For a higher-level client see https://www.npmjs.com/package/@paylike/client.

This is a low-level library used for making HTTP(s) requests to Paylike APIs. It incorporates the conventions described in the Paylike API reference.

This function is usually put behind a retry mechanism. Paylike APIs will expect any client to gracefully handle a rate limiting response and expects them to retry.

A retry mechanism is not included in this package because it is highly specific to the project and is difficult to implement for streaming requests without further context.

Example

// swap esm.sh for any "npm CJS to ESM CDN"
import request from 'https://esm.sh/@paylike/request@3.1.0'

const token = request('vault.paylike.io', {
  version: 1,
  data: {type: 'pcn', value: '1000 0000 0000 0000'.replaceAll(' ', '')},
}).first()

request

This package's default export is a function:

request(
  endpoint, // String, required
  {
    log: () => {},
    fetch: globalThis.fetch, // required in older Node.js
    timeout: 10000, // 0 = disabled

    version: String, // required
    query: Object,
    data: Object,

    // mostly relevant during testing
    clock: {
      setTimeout,
      clearTimeout,
    },
  }
})

request returns a pull-stream source (a function):

pull(request(/* ... */), collect(console.log))

For most cases, the below shortcut functions can be used:

request(/* ... */).first().then(console.log, console.error)

request(/* ... */).toArray().then(console.log, console.error)

request(/* ... */).forEach(console.log).catch(console.error)

Error handling

request may throw any of the following error classes as well as any error thrown by the fetch implementation by rejecting the promise returned by a shortcut function or by the error mechanism of a pull-stream.

All error classes can be accessed as request.<error class>, for instance request.RateLimitError.

Example

retry(
  () => request(/* ... */).first(),
  (err, attempts) => {
    if (attempts > 5 || !(err instanceof request.RateLimitError)) return false
    return err.retryAfter || 2 ** attempts * 5000
  }
).then(console.log, console.error)

function retry(fn, should, attempts = 0) {
  return fn().catch((err) => {
    const retryAfter = should(err, attempts)
    if (retryAfter === false) throw err

    return new Promise((resolve) =>
      setTimeout(() => resolve(retry(fn, attempts + 1)), retryAfter)
    )
  })
}

Error classes

• RateLimitError

  May have a retryAfter (milliseconds) property if sent by the server specifying the minimum delay.

• TimeoutError

  Has a timeout (milliseconds) property specifying the time waited.

• ServerError

  Has status and headers properties copied from the fetch response.

• ResponseError

  These errors correspond to status codes from the API reference. They have at least a code and message property, but may also have other useful properties relevant to the specific error code, such as a minimum and maximum for amounts.

Custom fetch (e.g. Node.js v16 and older)

It is built to work in any JavaScript environment (Node.js, browser) by accepting a Fetch implementation as input. Minor tweaks are implemented to support the node-fetch implementation even though it is not entirely compatible.