Podio client

A utility for working with the Podio API. The functionality is:

• Maintain (refresh) the access token when needed (lazily)
• Provide a retry mechanism with sane defaults
• Wrap common errors in easy-to-catch classes
• Provide a helper for paginating through results
• Provide a helper for formatting dates to Podio format

request({
  log = noop,

  // at least one of
  client: {id, secret, refreshToken},
  session: {
    // optional, use an empty object for reuse across requests
    token,
    expiry,
  },

  method, // defaults to POST/GET depending on "data"
  path,
  query,
  data,
  retry = defaultRetry, // fn(err, retries) → true for "now", false for "no", integer for delay (ms)
})
// → Promise → parsed JSON data from the API

expires is optional but should be a timestamp in milliseconds on which token is regarded expired. It is checked prior to a request to avoid pointless requests and will immediately trigger a refresh. The session object will be modified if a new token is obtained.

client is required for token refreshes.

The default retry strategy is a minute delay for RateLimitError, immediately for TokenExpiredError, ten seconds delay for UnexpectedHttpStatusError and any Node.js system error, and fail in all other situations. Be aware that retrying may result in duplicate processing of your request. You should disable it where that is not tolerable.

authenticate({
  log = noop,
  client,
  // `username` and `password` if authenticating as a user
  username,
  password,
  // `appId` and `appToken` if authenticating as an app
  appId,
  appToken,
})
// → Promise → {refreshToken, accessToken, expiry}

Used to obtain a session object from a username and password or app ID and app token.

paginate(batchSize, limit, scroll)
// → source pull-stream

// Example
pull(
  paginate(500 /* Podio max */, Infinity, (offset, limit) =>
    podio
      .request({
        client,
        session,
        path: `/item/app/${appId}/filter`,
        json: {
          sort_by: 'created_on',
          sort_desc: false,
          offset,
          limit,
        },
      })
      .then((r) => r.items)
  ),
  map((i) => i.itemId),
  drain(console.log, (err) => err && console.error(err))
)

Proxies formatPeriod from podio-fetch for Date formatting to Podio format

Errors

TokenExpiredError
RateLimitError
UnexpectedHttpStatusError
UnexpectedHttpContentTypeError
InvalidJsonBodyError