@envoy/envoy-integrations-sdk 2.0.1-beta.5 → 2.0.2

package/src/sdk/loggers.ts

@@ -0,0 +1,165 @@
+import { AxiosError, AxiosRequestConfig, AxiosResponse } from 'axios';
+import chalk from 'chalk';
+import util from 'util';
+
+function envoyAxiosRequestLogger(config: AxiosRequestConfig) {
+  const log = console.log;
+  log('---------------- Axios Request ----------------\n');
+  if (config?.method) {
+    const boldMethodText = chalk.bold('Method:');
+    const method = config.method.toUpperCase();
+    switch (method) {
+      case 'GET':
+        log(`${boldMethodText} ${chalk.green(method)}\n`);
+        break;
+      case 'PUT':
+        log(`${boldMethodText} ${chalk.yellow(method)}\n`);
+        break;
+      case 'PATCH':
+        log(`${boldMethodText} ${chalk.yellow(method)}\n`);
+        break;
+      case 'POST':
+        log(`${boldMethodText} ${chalk.blue(method)}\n`);
+        break;
+      case 'DELETE':
+        log(`${boldMethodText} ${chalk.red(method)}\n`);
+        break;
+      default:
+        log(`${boldMethodText} ${method}\n`);
+        break;
+    };
+  }
+  if (config?.baseURL && config?.url) {
+    log(`${chalk.bold('URL')}: ${config.baseURL}/${config.url}\n`);
+  }
+
+  if (config?.headers) {
+    log(`${chalk.bold('Headers:')} ${util.inspect(config?.headers)}\n`);
+  }
+
+  if (config?.auth) {
+    log(`${chalk.bold('Auth:')} ${util.inspect(config?.auth)}\n`);
+  }
+
+  if (config?.params) {
+    log(`${chalk.bold('Params:')} ${util.inspect(config?.params)}\n`);
+  }
+
+  if (config?.data) {
+    log(`${chalk.bold('Request Data:')} ${util.inspect(config?.data)}\n`);
+  }
+
+  log('------------ End Of Axios Request ------------\n');
+
+  return config;
+}
+
+function envoyAxiosResponseLogger(response: AxiosResponse) {
+  const log = console.log;
+  log('---------------- Axios Response ----------------\n');
+  if (response?.request?.method) {
+    const boldMethodText = chalk.bold('Method:');
+    const method = response.request.method;
+    switch (method) {
+      case 'GET':
+        log(`${boldMethodText} ${chalk.green(method)}\n`);
+        break;
+      case 'PUT':
+        log(`${boldMethodText} ${chalk.yellow(method)}\n`);
+        break;
+      case 'PATCH':
+        log(`${boldMethodText} ${chalk.yellow(method)}\n`);
+        break;
+      case 'POST':
+        log(`${boldMethodText} ${chalk.blue(method)}\n`);
+        break;
+      case 'DELETE':
+        log(`${boldMethodText} ${chalk.red(method)}\n`);
+        break;
+      default:
+        log(`${boldMethodText} ${method}\n`);
+        break;
+    };
+  }
+  if (response?.request?.baseURL && response?.request?.url) {
+    log(`${chalk.bold('Request URL')}: ${response.request.baseURL}/${response.request.url}\n`);
+  }
+
+  if (response?.status && response?.statusText) {
+    const boldStatusTitle = chalk.bold('Status:');
+    const boldStatusTextTitle = chalk.bold('Status Text:');
+    const status = response.status;
+    const statusText = response.statusText;
+    if (199 < status && status < 300) {
+      log(`${boldStatusTitle} ${chalk.green(status)}\n`);
+      log(`${boldStatusTextTitle} ${chalk.green(statusText)}\n`);
+    } else {
+      log(`${boldStatusTitle} ${chalk.red(status)}\n`);
+      log(`${boldStatusTextTitle} ${chalk.red(statusText)}\n`);
+    }
+  }
+
+  if (response?.data) {
+    log(`${chalk.bold('Response Data:')} ${util.inspect(response?.data)}\n`);
+  }
+
+  log('------------ End Of Axios Response ------------\n');
+
+  return response;
+}
+
+function envoyAxiosErrorLogger(error: AxiosError) {
+  const log = console.log;
+  log('---------------- Axios Error ----------------\n');
+  if (error?.request?.method) {
+    const boldMethodText = chalk.bold('Method:');
+    const method = error.request.method;
+    switch (method) {
+      case 'GET':
+        log(`${boldMethodText} ${chalk.green(method)}\n`);
+        break;
+      case 'PUT':
+        log(`${boldMethodText} ${chalk.yellow(method)}\n`);
+        break;
+      case 'PATCH':
+        log(`${boldMethodText} ${chalk.yellow(method)}\n`);
+        break;
+      case 'POST':
+        log(`${boldMethodText} ${chalk.blue(method)}\n`);
+        break;
+      case 'DELETE':
+        log(`${boldMethodText} ${chalk.red(method)}\n`);
+        break;
+      default:
+        log(`${boldMethodText} ${method}\n`);
+        break;
+    };
+  }
+  if (error?.request?.baseURL && error?.request?.url) {
+    log(`${chalk.bold('Request URL')}: ${error.request.baseURL}/${error.request.url}\n`);
+  }
+
+  if (error?.response?.status && error?.response?.statusText) {
+    const boldStatusTitle = chalk.bold('Status:');
+    const boldStatusTextTitle = chalk.bold('Status Text:');
+    const status = error.response.status;
+    const statusText = error.response.statusText;
+    if (199 < status && status < 300) {
+      log(`${boldStatusTitle} ${chalk.green(status)}\n`);
+      log(`${boldStatusTextTitle} ${chalk.green(statusText)}\n`);
+    } else {
+      log(`${boldStatusTitle} ${chalk.red(status)}\n`);
+      log(`${boldStatusTextTitle} ${chalk.red(statusText)}\n`);
+    }
+  }
+
+  if (error.response?.data) {
+    log(`${chalk.bold('Response Data:')} ${util.inspect(error.response.data)}\n`);
+  }
+
+  log('------------ End Of Axios Error ------------\n');
+
+  throw error;
+}
+
+export { envoyAxiosRequestLogger, envoyAxiosResponseLogger, envoyAxiosErrorLogger };

package/src/sdk/middleware.ts

@@ -0,0 +1,101 @@
+import bodyParser from 'body-parser';
+import {
+  Request,
+  Response,
+  NextFunction,
+  ErrorRequestHandler,
+  RequestHandler,
+} from 'express';
+
+import HttpStatus from '../internal/HttpStatus';
+import EnvoySignatureVerifier, { EnvoySignatureVerifierOptions } from '../util/EnvoySignatureVerifier';
+import EnvoyRequest, { VERIFIED, VerifiedRequest } from './EnvoyRequest';
+import EnvoyResponse from './EnvoyResponse';
+import EnvoyPluginJobAttachment from './EnvoyPluginJobAttachment';
+import EnvoyPluginSDK from './EnvoyPluginSDK';
+import EnvoyPluginAPI from './EnvoyPluginAPI';
+
+/**
+ * Sets up an {@link EnvoyPluginSDK} object in the path `req.envoy`.
+ * Modifies the `res` object to include Envoy's helpers, per {@link EnvoyResponse}.
+ *
+ * Also verifies that the request is coming from Envoy,
+ * as well as managing the plugin access token lifecycle.
+ *
+ * @category Middleware
+ */
+export function envoyMiddleware(options?: EnvoySignatureVerifierOptions): RequestHandler {
+  const signatureVerifier = new EnvoySignatureVerifier(options);
+  const verify = (req: VerifiedRequest, res: Response, rawBody: Buffer) => {
+    req[VERIFIED] = signatureVerifier.verify(req, rawBody);
+  };
+  const json = bodyParser.json({ verify });
+  let accessToken: string | null = null;
+  let threshold = 0;
+
+  return (req: Request, res: Response, next: NextFunction) => {
+    json(req, res, async (err) => {
+      if (err) {
+        return next(err);
+      }
+      try {
+        const now = Date.now();
+        if (now > threshold) {
+          const { access_token: rawAccessToken, expires_in: expiresIn } = await EnvoyPluginAPI.loginAsPlugin();
+          accessToken = rawAccessToken;
+          threshold = now + (expiresIn * 1000) - (1000 * 60 * 10);
+        }
+        const envoyRequest = req as EnvoyRequest;
+        const envoyResponse = res as EnvoyResponse;
+        envoyRequest.envoy = new EnvoyPluginSDK(envoyRequest.body, envoyRequest[VERIFIED], accessToken);
+
+        /**
+         * Respond with "ongoing" for long jobs.
+         */
+        envoyResponse.sendOngoing = (message = '', debugInfo: unknown = {}) => {
+          envoyResponse.statusCode = HttpStatus.ONGOING;
+          envoyResponse.setHeader('Content-Type', 'application/json');
+          envoyResponse.end(JSON.stringify({ message, debugInfo }));
+        };
+
+        /**
+         * Respond with "ignored" if no action will be performed.
+         */
+        envoyResponse.sendIgnored = (message = '', debugInfo: unknown = {}, ...attachments: Array<EnvoyPluginJobAttachment>) => {
+          envoyResponse.statusCode = HttpStatus.IGNORED;
+          envoyResponse.setHeader('Content-Type', 'application/json');
+          envoyResponse.end(JSON.stringify({ message, debugInfo, attachments }));
+        };
+
+        /**
+         * Respond with "failed" in case of errors.
+         */
+        envoyResponse.sendFailed = (message = '', debugInfo: unknown = {}, ...attachments: Array<EnvoyPluginJobAttachment>) => {
+          envoyResponse.statusCode = HttpStatus.FAILED;
+          envoyResponse.setHeader('Content-Type', 'application/json');
+          envoyResponse.end(JSON.stringify({ message, debugInfo, attachments }));
+        };
+        next();
+      } catch (error) {
+        next(error);
+      }
+    });
+  };
+}
+
+/**
+ * Catches errors and sets the proper status code.
+ *
+ * @category Middleware
+ */
+export function errorMiddleware(onError: (err: Error) => void = () => {}): ErrorRequestHandler {
+  return (err: Error, req: Request, res: Response, next: NextFunction): void => {
+    onError(err);
+    if (res.headersSent) {
+      return next(err);
+    }
+    res.statusCode = HttpStatus.UNEXPECTED_FAILURE;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify({ message: err.message }));
+  };
+}

package/src/util/EnvoyJWT.ts

@@ -0,0 +1,51 @@
+import jwt, { SignOptions, Algorithm, VerifyOptions } from 'jsonwebtoken';
+import { jwtSecret } from '../constants';
+
+export type EnvoyJWTAlgorithm = Algorithm;
+export type EnvoyJWTDecodeOptions = VerifyOptions;
+/**
+ * Helper to encode and decode JWTs.
+ *
+ * @category Helper
+ * @category Request Object
+ */
+export default class EnvoyJWT {
+  private secret: string;
+
+  private algorithm: Algorithm;
+
+  constructor(secret = jwtSecret, algorithm: EnvoyJWTAlgorithm = 'HS256') {
+    if (!secret) {
+      throw new Error('JWT secret missing. Have you set the `JWT_SECRET` environment variable?');
+    }
+    this.secret = secret;
+    this.algorithm = algorithm;
+  }
+
+  encode(
+    subject: string | number | null,
+    expiresIn: string | number | null,
+    payload: Record<string, unknown> = {},
+  ): string {
+    const { secret, algorithm } = this;
+    const options: SignOptions = { algorithm };
+    if (subject) {
+      options.subject = `${subject}`;
+    }
+    if (expiresIn) {
+      options.expiresIn = expiresIn;
+    }
+
+    return jwt.sign(payload, secret, options);
+  }
+
+  decode(token: string, options: EnvoyJWTDecodeOptions = {}): Record<string, unknown> {
+    const { secret, algorithm } = this;
+    return jwt.verify(token, secret, {
+      ignoreExpiration: false,
+      ignoreNotBefore: false,
+      ...options,
+      algorithms: [algorithm], // force the algorithm
+    }) as Record<string, unknown>;
+  }
+}

package/src/util/EnvoySignatureVerifier.ts

@@ -0,0 +1,61 @@
+import crypto, { BinaryToTextEncoding } from 'crypto';
+import { Request } from 'express';
+import { envoyClientSecret } from '../constants';
+
+/**
+ * @category Helper
+ */
+export type EnvoySignatureVerifierOptions = {
+  algorithm: 'sha256' | string,
+  encoding: BinaryToTextEncoding,
+  secret: string,
+  header: 'x-envoy-signature' | string,
+};
+
+const defaultOptions: EnvoySignatureVerifierOptions = {
+  algorithm: 'sha256',
+  encoding: 'base64',
+  secret: envoyClientSecret,
+  header: 'x-envoy-signature',
+};
+
+/**
+ * Verifies that a request is coming from Envoy.
+ *
+ * @category Helper
+ */
+export default class EnvoySignatureVerifier {
+  private readonly options: EnvoySignatureVerifierOptions;
+
+  constructor(options: EnvoySignatureVerifierOptions = defaultOptions) {
+    this.options = { ...defaultOptions, ...options };
+
+    if (!this.options.secret) {
+      throw new Error('No client secret found in the ENVOY_CLIENT_SECRET environment variable.');
+    }
+  }
+
+  /**
+   * Verifies that the signature provided matches the request body.
+   */
+  verify(req: Request, rawBody: Buffer): boolean {
+    const {
+      algorithm,
+      encoding,
+      secret,
+      header,
+    } = this.options;
+
+    if (!req.headers[header]) {
+      return false;
+    }
+    const receivedDigest = req.headers[header] as string;
+    const computedHmac = crypto.createHmac(algorithm, secret);
+    computedHmac.update(rawBody);
+
+    return crypto.timingSafeEqual(
+      Buffer.from(receivedDigest),
+      Buffer.from(computedHmac.digest(encoding)),
+    );
+  }
+}

package/src/util/axiosConstructor.ts

@@ -0,0 +1,46 @@
+import axios, { AxiosError, AxiosHeaders, AxiosInstance, AxiosRequestConfig } from 'axios';
+import { ensureError } from './errorHandling';
+
+export function sanitizeAxiosError(error: unknown): Error {
+  if (!axios.isAxiosError(error)) {
+    return ensureError(error);
+  }
+
+  const safeError = new AxiosError(
+    error.message,
+    error.code,
+    {
+      url: error.config?.url,
+      method: error.config?.method,
+      baseURL: error.config?.baseURL,
+      headers: new AxiosHeaders(),
+    },
+    {
+      url: error.request?.url,
+      method: error.request?.method,
+      baseURL: error.request?.baseURL,
+      data: error.request?.data,
+    },
+    {
+      data: error.response?.data,
+      status: error.response?.status ?? 0,
+      statusText: error.response?.statusText ?? '',
+      headers: new AxiosHeaders(),
+      config: {
+        headers: new AxiosHeaders(),
+      },
+    },
+  );
+  safeError.stack = error.stack;
+  return safeError;
+}
+
+export function createAxiosClient(config?: AxiosRequestConfig | undefined): AxiosInstance {
+  const client = axios.create(config);
+  client.interceptors.response.use(
+    (response) => response,
+    (error) => Promise.reject(sanitizeAxiosError(error)),
+  );
+
+  return client;
+}

package/src/util/errorHandling.ts

@@ -0,0 +1,15 @@
+export function ensureError(value: unknown): Error {
+  if (value instanceof Error) {
+    return value;
+  }
+
+  let stringified = '[Unable to stringify the thrown value]';
+  try {
+    stringified = JSON.stringify(value);
+  } catch {
+    // ignore
+  }
+
+  const error = new Error(`This value was thrown as is, not through an Error: ${stringified}`);
+  return error;
+}

package/src/util/json-api/JSONAPIData.ts

@@ -0,0 +1,4 @@
+export default interface JSONAPIData<Type = string, ID = string> {
+  id: ID;
+  type: Type;
+}

package/src/util/json-api/JSONAPIFilterParams.ts

@@ -0,0 +1,5 @@
+import JSONAPIParams from './JSONAPIParams';
+
+export default interface JSONAPIFilterParams<FilterFields> extends JSONAPIParams {
+  filter?: FilterFields;
+}

package/src/util/json-api/JSONAPIModel.ts

@@ -0,0 +1,10 @@
+import JSONAPIData from './JSONAPIData';
+
+export default interface JSONAPIModel<Attributes, Relationships extends string, Type = string, ID = string> extends JSONAPIData<Type, ID> {
+  attributes: Attributes;
+  relationships: {
+    [key in Relationships]: {
+      data: JSONAPIData & Array<JSONAPIData>
+    };
+  }
+}

package/src/util/json-api/JSONAPIPaginationParams.ts

@@ -0,0 +1,12 @@
+import JSONAPIFilterParams from './JSONAPIFilterParams';
+
+export default interface JSONAPIPaginationParams<FilterFields, SortFields extends string>
+  extends JSONAPIFilterParams<FilterFields> {
+
+  page?: {
+    offset?: number;
+    limit?: number;
+  }
+
+  sort?: SortFields;
+}

package/src/util/json-api/JSONAPIParams.ts

@@ -0,0 +1,3 @@
+export default interface JSONAPIParams {
+  include?: string;
+}

package/src/util/json-api/JSONAPIResponse.ts

@@ -0,0 +1,5 @@
+export default interface JSONAPIResponse<Model> {
+  data: Model,
+  included?: Array<unknown>,
+  meta?: Array<unknown>
+}

package/.eslintrc.js

@@ -1,46 +0,0 @@
-module.exports = {
-  env: {
-    commonjs: true,
-    es6: true,
-    node: true,
-  },
-  extends: 'airbnb-base',
-  globals: {
-    Atomics: 'readonly',
-    SharedArrayBuffer: 'readonly',
-  },
-  parserOptions: {
-    ecmaVersion: 2018,
-  },
-  rules: {
-    'no-trailing-spaces': 'off',
-    'padded-blocks': 'off',
-    'no-console': 'off',
-    'arrow-parens': 'off',
-    'no-return-assign': 'off',
-    'no-empty': 'off',
-    'consistent-return': 'off',
-    'no-shadow': 'off',
-    'no-plusplus': 'off',
-    'no-case-declarations': 'off',
-    'class-methods-use-this': 'off'
-  },
-  overrides: [
-    {
-      files: [
-        'tests/**/*.test.js'
-      ],
-      env: {
-        mocha: true
-      },
-      rules: {
-        'prefer-arrow-callback': 'off',
-        'func-names': 'off',
-        'no-loop-func': 'off',
-        'no-await-in-loop': 'off',
-        'no-restricted-syntax': 'off',
-        'max-len': 'off'
-      }
-    }
-  ]
-};

package/.github/workflows/package.yaml

@@ -1,43 +0,0 @@
-name: Node.js Package
-on:
-  release:
-    types: [created]
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-
-      - uses: actions/setup-node@v2
-        with:
-          registry-url: "https://registry.npmjs.org"
-
-      - name: Get Node.js version
-        id: node-version
-        run: |
-          echo "::set-output name=version::$(node --version)"
-      - name: Cache node_modules
-        uses: actions/cache@v2
-        id: cache-node-modules
-        with:
-          path: node_modules
-          key: v1-node-${{ steps.node-version.outputs.version }}-modules-${{ hashFiles('package-lock.json') }}
-
-      - name: Install dependencies
-        run: npm install
-        if: steps.cache-node-modules.outputs.cache-hit != 'true'
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.ENVOYBOT_PERSONAL_ACCESS_TOKEN }}
-
-      - run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.ENVOY_NPM_AUTOMATION_TOKEN }}
-
-      # Setup .npmrc file to publish to npm
-      - uses: actions/setup-node@v2
-        with:
-          registry-url: "https://npm.pkg.github.com"
-
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/test.yaml

@@ -1,15 +0,0 @@
-name: Test
-
-on:
-  push:
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
-        with:
-          node-version: '16'
-      - run: npm install
-      - run: npm run test

package/asynchandler.md

@@ -1,46 +0,0 @@
----
-description: >-
-  Use this wrapper around your `async` endpoint handlers to catch Promise-based
-  errors.
----
-
-# asyncHandler
-
-## Example
-
-```javascript
-const express = require('express');
-const { middleware, asyncHandler } = require('envoy-integrations-sdk-nodejs');
-
-const app = express();
-app.use(middleware());
-app.post('/foo', asyncHandler(async (req, res) => {
-  await somePromiseThatThrowsAnError();
-}));
-```
-
-## Functions
-
-### asyncHandler\(handler\) ⇒ `connectHandler`
-
-Returns a wrapped handler that catches Promise-based errors.
-
-**Kind**: global function
-
-| Param | Type |
-| :--- | :--- |
-| handler | `connectHandler` |
-
-### Related Functions and Classes
-
-### connectHandler : `function`
-
-Express/connect middleware.
-
-**Kind**: global typedef
-
-| Param | Type |
-| :--- | :--- |
-| req | [http://expressjs.com/en/4x/api.html\#req](http://expressjs.com/en/4x/api.html#req) |
-| res | [http://expressjs.com/en/4x/api.html\#res](http://expressjs.com/en/4x/api.html#res) |
-