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,
  client: {id, secret},
  session: {refresh_token, access_token, expires},
  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

The object provided in session should have either refresh_token or access_token and optionally expires. expires should be a timestamp in milliseconds on which the access_ token expires. It is checked before a request to avoid a pointless request and instead immediately trigger a refresh. The object will be modified if a new access_token is obtained.

client is relevant only if refresh_token is provided.

The default retry strategy is a minute delay for RateLimitError, 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 → {refresh_token, access_token, expires}

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