Prospector JavaScript Client Library (Experimental)

Install

$ npm install --save prospector-js-sdk superagent

Usage

Importing

The prospector-js-sdk package is static; nothing needs to be constructed.

import * as sdk from 'prospector-js-sdk'

Base URL

All API functions allow you to specify the baseUrl of the request. However, to avoid having to pass that every time, you can call setBaseUrl to statically set the base URL for every API call.

sdk.setBaseUrl('http://localhost:3000/api/v1') // Use the applicable base url for your environment

You can always override this by explicitly passing baseUrl to the API function.

Token strategies

Automatic (recommended)

By default, prospector-js-sdk will first look for a token query parameter in the URL, then it will look for a token cookie. If neither are found, it will throw an error.

// Make a call with default automatic token management.
const { json: editor } = await sdk.getEditor({ editorId })

Provide your own token

Every API function also allows you to explicitly provide a token. This will override the automatic token management.

// Make a call with a token you manage.
const { json: editor } = await sdk.getEditor({ token: someToken, editorId })

Set your own automatic strategy

If the default token management strategy doesn't suit your application, you can provide your own. prospector-js-sdk will then use that to retrieve tokens for API calls.

sdk.setTokenStrategy = async () => {
  // Obtain a Prospector token by whatever means you need.
  return someToken
}

// Then you don't need to provide a token.
const { json: editor } = await sdk.getEditor({ editorId })

If you would like to use the default token management strategy but the details of your application differ, you can wrap the manageToken function and provide overrides.

sdk.setTokenStrategy = () => {
  return sdk.manageToken({
    baseUrl: 'some-other-base-url',
    paramName: 'jwt',
    tokenName: 'jwt',
    path: '/super/special/cookie/path'
  })
}

const { json: editor } = await sdk.getEditor({ editorId })

Deployment

An alpha release is automatically created when opening a PR into dev.

Releases are found on NPM.

To make an official version release:

1. Check out dev
2. Run npm version with patch, minor, or major
3. Push dev and the newly created version tag
4. Go to Releases in Github and create a release
5. For good hygiene, make a PR and merge dev into main to keep them up to date (it doesn't functionally do anything)

At some point we would like to just use main and delete the dev branch to simplify this.