Neolithic Prancing Minotaurs

    @envoy/envoy-integrations-sdk

    1.3.0 • Public • Published

    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.

    Keywords

    none

    Install

    npm i @envoy/envoy-integrations-sdk

    DownloadsWeekly Downloads

    79

    Version

    1.3.0

    License

    ISC

    Unpacked Size

    60.4 kB

    Total Files

    27

    Last publish

    Collaborators

    • envoy-npm
    • kamalf
    • esbanarango
    • shaunpersad
    • elbertninja
    • pixelhandler