Vouchsafe Node.js library

The Vouchsafe Node library provides convenient, typed access to the Vouchsafe API for applications written in server-side JavaScript.

Requirements

Node 18 or better.

Installation

npm install @vouchsafe/node
# or
yarn add  @vouchsafe/node

Usage

The SDK needs a client ID and secret, which is available in the Vouchsafe dashboard. Replace the values below:

import { VouchsafeClient } from "@vouchsafe/node"

const client = new VouchsafeClient({
  client_id: "YOUR_CLIENT_ID",
  client_secret: "YOUR_CLIENT_SECRET",
})

// Request a verification
const res = await client.requestVerification({
  email: "[email protected]",
})

console.log(res.id) // Trackable verification session ID
console.log(res.url) // Redirect the user here

List verifications

const res = await client.listVerifications({
  status: "InProgress", // Or any other supported status
})

Get a specific verification

const res = await client.getVerification({
  id: "ID",
})

List verification flows

const res = await client.listFlows()

Sandbox mode

Use a sandbox rather than a live client secret to activate sandbox mode on methods that support it.

Re-authentication

The client will automatically cache your access token and insert it into every request, and fetch a new one upon expiry.

If a request fails with a 401 Unauthorised error, it will fetch a new access token and retry once before throwing an error.

Multi-instance use

For best performance, you should instantiate the client once and share it across your app as a singleton.

Each time a new access token is requested using the same client credentials, it invalidates the old one.

Instantiating multiple clients can lead to:

• over-writing each other's tokens
• unnecessary retries and re-authentications.

For high-concurrency use cases, you should store the access token in a shared key-value store instead.

Handling errors

Client methods will throw an instance of VouchsafeApiError if the API returns a bad response.

You can catch them like this:

try {
  const res = await client.getVerification({
    id: "non-existent",
  })
} catch (err) {
  if (err instanceof VouchsafeApiError) {
    console.log(err.statusCode, err.message)
  }
}

Development

See the contribution guidelines for this project

Contributions including issues and pull requests are welcome.

To run the project locally, clone the repo and run:

npm install
npm run generate # regenerate from API spec
npm run build # compile typescript

Further reading

• Developer docs
• Full API endpoint reference
• 3-minute video guide