@envoy/envoy-integrations-sdk

Envoy Node.js SDK

The SDK exports several classes and functions, however the most typical way to integrate the SDK is as middleware. The middleware() function call returns a middleware that attaches an instance of EnvoyPluginSDK to the req object and verifies that the request came from Envoy. It is available as req.envoy.

Installation

npm install --save @envoy/envoy-integrations-sdk

Environment Variables

The SDK relies on a few environment variables:

• ENVOY_CLIENT_ID - can be found in the Integration Builder
• ENVOY_CLIENT_SECRET - can be found in the Integration Builder
• ENVOY_BASE_URL - (optional in production) the URL to Envoy's API
• JWT_SECRET - (optional) used if encoding/decoding JWTs

Locally, these environment variables can be set using a .env file.

Getting Started

View our Node.js quickstart guide.

Usage

Here's the typical SDK usage at a glance.

const express = require('express');
const { middleware, errorMiddleware, asyncHandler } = require('@envoy/envoy-integrations-sdk');

const app = express();
/**
 * "middleware()" returns an instance of bodyParser.json,
 * that also verifies the Envoy signature in addition to
 * parsing the request body as JSON.
 */
app.use(middleware());

app.post('/url-to-a-route-or-worker', asyncHandler(async (req, res) => {

 /**
  * @type EnvoyPluginSDK
  */
  const { envoy } = req;  // "envoy" is the SDK
  const {
    meta, // the platform event request_meta object
    payload, // the platform event request_body object
    userAPI, // user-scoped API calls, used in routes
    pluginAPI, // plugin-scoped API calls, for plugin services
    installStorage, // install-scoped storage
    globalStorage, // global-scoped storage
    job, // update the job (if in a worker)
    jwt, // helper to encode/decode jwts
  } = envoy;

  /**
  * User API usage
  */
  const visitorTypes = await userAPI.flows(locationId);

  /**
  * Storage usage
  * The below can be used both at the install level or global level
  */
  await installStorage.set('foo', 'bar'); // sets foo=bar in storage for this install
  const { value } = await installStorage.setUnique('foo'); // creates and returns a unique text value for foo
  const { value } = await installStorage.setUniqueNum('foo'); // creates and returns a unique number for foo
  const { value } = await installStorage.get('foo'); // also gets the current value of foo
  await installStorage.unset('foo'); // deletes foo
  /**
  * You can also send multiple commands at once,
  * to be executed in the same transaction.
  * The response will be an array of the results of each command, in order.
  */
  const results = await installStorage.pipeline().set('foo1', 'bar').unset('foo2').get('foo3').execute();

  /**
  * Job updates
  * Note that job.complete can take any number of attachments after the first argument.
  */
  await job.complete('Credentials provisioned.', { label: 'password', value: 'password' });
  await job.ignore('No credentials provisioned.', 'Email was not supplied.');
  await job.fail('Could not provision credentials.', 'Server could not be reached.');
  /**
  * You can also just attach things without completing the job.
  * Attach more things by providing more arguments.
  */
  await job.attach({ type: 'text', label: 'foo', value: 'bar' });
  /**
  * If the job is some multi-step process,
  * you can update it's message without changing the status.
  * You can also optionally attach things by providing more arguments.
  */
  await job.update('Still working...');

  /**
  * JWT usage
  */
  const token = await jwt.encode(visitorId, '30m');
  const { sub: visitorId } = await jwt.decode(token);

  /**
  * If in a validation URL:
  */
  res.send({ foo: 'bar' }); // will save foo in the installation config.
  // or
  res.sendFailed('This step has failed validation.'); // prevent the installer from progressing.

  /**
  * If in an options URL:
  */
  res.send([ { label: 'Foo', value: 1 }, { label: 'Bar', value: 2 } ]); // display these options in the dropdown.

  /**
  * If in a worker:
  */
  res.send({ hello: 'world' }); // the job was a success, and here's some data about it.
  // or
  res.sendOngoing({ hello: 'world' }); // the job is still ongoing, but here's some data about it.
  // or
  res.sendIgnored("We're not gonna do this one, sorry.", { hello: 'world' }); // doesnt meet the requirements to continue.
  // or
  res.sendFailed('We tried, but failed.', { hello: 'world' }); // we cant continue with this job.

}));

app.use(errorMiddleware());

SDK Reference

For completeness, here is a list of each module exported by the SDK package.

Name	Type
EnvoyAPI	EnvoyAPI
EnvoyJWT	EnvoyJWT
EnvoyPluginJob	EnvoyPluginJob
EnvoyPluginSDK	EnvoyPluginSDK
EnvoyPluginStorage	EnvoyPluginStorage
EnvoyPluginStoragePipeline	EnvoyPluginStoragePipeline
EnvoySignatureVerifier	EnvoySignatureVerifier
middleware	middleware
errorMiddleware	errorMiddleware
asyncHandler	asyncHandler

Contributing

We're happy to accept contributions. Submit a PR.