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

package/src/sdk/EnvoyPluginSDK.ts

@@ -0,0 +1,185 @@
+import EnvoyMeta, { EnvoyEventMeta, EnvoyRouteMeta } from './EnvoyMeta';
+import EnvoyPluginStorage from './EnvoyPluginStorage';
+import EnvoyPluginJob from './EnvoyPluginJob';
+import EnvoyJWT from '../util/EnvoyJWT';
+import EnvoyUserAPI from './EnvoyUserAPI';
+import EnvoyPluginAPI from './EnvoyPluginAPI';
+import JSONAPIData from '../util/json-api/JSONAPIData';
+import EntryPayload, { normalizeEntryPayload } from '../payloads/EntryPayload';
+import InvitePayload, { normalizeInvitePayload } from '../payloads/InvitePayload';
+
+/**
+ * Every Envoy request has a `meta` and `payload`.
+ * @category Request
+ */
+export interface EnvoyRequestBody<Meta, Payload> {
+  meta: Meta,
+  payload: Payload,
+}
+
+/**
+ * Sets up all relevant Envoy functions.
+ * Attaches itself to every request object using our {@link middleware},
+ * to allow for easy access to Envoy functions.
+ *
+ * @category SDK
+ */
+export default class EnvoyPluginSDK<Meta = unknown, Payload = unknown> {
+  /**
+   * Body of the request.
+   * use `meta` or `payload` to access the relevant properties,
+   * instead of this directly.
+   */
+  private readonly body: EnvoyRequestBody<Meta, Payload>;
+
+  /**
+   * Verified that the request comes from Envoy.
+   */
+  private readonly isVerified: boolean;
+
+  /**
+   * The internally managed plugin access token.
+   * Use the `pluginAPI` instead of this directly.
+   */
+  private readonly pluginAccessToken: string | null = null;
+
+  /**
+   * Don't create an instance of this class directly.
+   *
+   * Instead, use {@link middleware} to automatically attach an instance to `req` on every request.
+   * @param body - Request body
+   * @param isVerified - If the request has been verified via {@link EnvoySignatureVerifier}
+   * @param pluginAccessToken - An access token from {@link EnvoyPluginAPI.loginAsPlugin}
+   */
+  constructor(body: EnvoyRequestBody<Meta, Payload>, isVerified = false, pluginAccessToken: string | null = null) {
+    this.body = body;
+    this.isVerified = isVerified;
+    this.pluginAccessToken = pluginAccessToken;
+  }
+
+  /**
+   * The metadata for the request.
+   * Either an {@link EnvoyEventMeta}} or {@link EnvoyRouteMeta}.
+   */
+  get meta(): Meta {
+    if (!this.isVerified) {
+      throw new Error('Could not verify meta.');
+    }
+    return this.body.meta;
+  }
+
+  /**
+   * The payload for the request.
+   * For events, it's some Envoy event payload, like an {@link EntryPayload} or {@link InvitePayload}.
+   * For setup step validation URLs, it's the form submitted values for a validation URL.
+   */
+  get payload(): Payload {
+    if (!this.isVerified) {
+      throw new Error('Could not verify payload.');
+    }
+    const payload = this.body.payload as unknown as JSONAPIData;
+    switch (payload.type) {
+      case 'entries':
+        return normalizeEntryPayload(payload as unknown as EntryPayload) as unknown as Payload;
+      case 'invites':
+        return normalizeInvitePayload(payload as unknown as InvitePayload) as unknown as Payload;
+      default:
+        return payload as unknown as Payload;
+    }
+  }
+
+  /**
+   * Envoy API scoped to the user.
+   * Used only in routes.
+   */
+  get userAPI(): EnvoyUserAPI {
+    const meta = this.meta as unknown as EnvoyRouteMeta;
+    const { auth } = meta;
+    let accessToken: string | undefined = auth?.access_token;
+    if (!accessToken && ('forwarded_bearer_token' in meta)) {
+      accessToken = meta.forwarded_bearer_token;
+    }
+    if (!accessToken) {
+      throw new Error("This user's API token was not found. Either no scopes were asked for, or this is a route.");
+    }
+    return new EnvoyUserAPI(accessToken);
+  }
+
+  /**
+   * Envoy API scoped to the plugin.
+   * Used to perform storage or job operations.
+   */
+  get pluginAPI(): EnvoyPluginAPI {
+    const { pluginAccessToken } = this;
+    if (!pluginAccessToken) {
+      throw new Error('No API token found. Are your Envoy client ID and secret set?');
+    }
+    return new EnvoyPluginAPI(pluginAccessToken);
+  }
+
+  /**
+   * A function that returns an instance of EnvoyPluginStorage,
+   * optionally scoped to an install ID.
+   *
+   * Use {@link installStorage} or {@link globalStorage} instead of this directly.
+   */
+  private get getStorage(): (installId?: string) => EnvoyPluginStorage {
+    return (installId?) => new EnvoyPluginStorage(this.pluginAPI, installId);
+  }
+
+  /**
+   * Storage scoped to the install.
+   */
+  get installStorage(): EnvoyPluginStorage {
+    const { install_id: installId } = this.meta as unknown as EnvoyMeta;
+    if (!installId) {
+      throw new Error('No install ID found in meta.');
+    }
+    return this.getStorage(installId);
+  }
+
+  /**
+   * Storage scoped globally (across installs).
+   */
+  get globalStorage(): EnvoyPluginStorage {
+    return this.getStorage();
+  }
+
+  /**
+   * Returns a job based on an ID.
+   */
+  get getJob(): (jobId: string) => EnvoyPluginJob {
+    return (jobId: string) => new EnvoyPluginJob(this.pluginAPI, jobId);
+  }
+
+  /**
+   * Returns the current job's ID.
+   */
+  get jobId(): string | null {
+    const { meta } = this;
+    if ('job' in meta) {
+      return (meta as unknown as EnvoyEventMeta).job.id;
+    }
+    return null;
+  }
+
+  /**
+   * Perform operations on the current job.
+   */
+  get job(): EnvoyPluginJob {
+    const { jobId } = this;
+    if (!jobId) {
+      throw new Error('No job found in meta. Are you in a worker?');
+    }
+    return this.getJob(jobId);
+  }
+
+  /**
+   * A utility to encode and decode JWTs.
+   * Useful for verifiable communications between plugin endpoints.
+   */
+  // eslint-disable-next-line class-methods-use-this
+  get jwt(): EnvoyJWT {
+    return new EnvoyJWT();
+  }
+}

package/src/sdk/EnvoyPluginStorage.ts

@@ -0,0 +1,83 @@
+import EnvoyPluginStoragePipeline from '../base/EnvoyPluginStoragePipeline';
+import { EnvoyStorageSetUniqueNumOptions, EnvoyStorageSetUniqueOptions } from '../internal/EnvoyStorageCommand';
+import EnvoyStorageItem from './EnvoyStorageItem';
+import EnvoyPluginAPI from './EnvoyPluginAPI';
+
+/**
+ * A key-value storage that can be scoped to a specific install,
+ * or to the plugin itself.
+ *
+ * @category Storage
+ * @category Request Object
+ */
+export default class EnvoyPluginStorage {
+  protected readonly api: EnvoyPluginAPI;
+
+  readonly installId: string | undefined;
+
+  constructor(pluginAPI: EnvoyPluginAPI, installId?: string) {
+    this.api = pluginAPI;
+    this.installId = installId;
+  }
+
+  /**
+   * Creates a new pipeline instance.
+   */
+  pipeline(): EnvoyPluginStoragePipeline {
+    return new EnvoyPluginStoragePipeline(this.api, this.installId);
+  }
+
+  /**
+   * Gets a single {@link EnvoyStorageItem} from storage.
+   *
+   * Wrapper for single pipeline get.
+   */
+  get<Value = unknown>(key: string) {
+    return this.pipeline().get(key).executeSingle<EnvoyStorageItem<Value> | { key: string, 'value': undefined }>();
+  }
+
+  /**
+   * Sets a single {@link EnvoyStorageItem} from storage.
+   *
+   * Wrapper for single pipeline set.
+   */
+  set<Value = unknown>(key: string, value: Value) {
+    return this.pipeline().set(key, value).executeSingle<EnvoyStorageItem<Value>>();
+  }
+
+  /**
+   * Sets a single unique string {@link EnvoyStorageItem} from storage.
+   *
+   * Wrapper for single pipeline setUnique.
+   */
+  setUnique(key: string, options: EnvoyStorageSetUniqueOptions = {}) {
+    return this.pipeline().setUnique(key, options).executeSingle<EnvoyStorageItem<string> | { key: string, 'value': undefined }>();
+  }
+
+  /**
+   * Sets a single unique number {@link EnvoyStorageItem} from storage.
+   *
+   * Wrapper for single pipeline setUnique.
+   */
+  setUniqueNum(key: string, options: EnvoyStorageSetUniqueNumOptions = {}) {
+    return this.pipeline().setUniqueNum(key, options).executeSingle<EnvoyStorageItem<number> | { key: string, 'value': undefined }>();
+  }
+
+  /**
+   * Unsets an {@link EnvoyStorageItem} from storage. Returns null if the item did not previously exist.
+   *
+   * Wrapper for single pipeline unset.
+   */
+  unset<Value = unknown>(key: string) {
+    return this.pipeline().unset(key).executeSingle<EnvoyStorageItem<Value> | { key: string, 'value': undefined }>();
+  }
+
+  /**
+   * Returns an array of {@link EnvoyStorageItem} from storage.
+   *
+   * Wrapper for single pipeline list.
+   */
+  list<Value = unknown>(page = 1) {
+    return this.pipeline().list(page).executeSingle<Array<EnvoyStorageItem<Value>>>();
+  }
+}

package/src/sdk/EnvoyRequest.ts

@@ -0,0 +1,145 @@
+import { Request } from 'express';
+import EnvoyPluginSDK from './EnvoyPluginSDK';
+import EnvoyMeta, { EnvoyEventMeta, EnvoyRouteMeta } from './EnvoyMeta';
+import EntryPayload from '../payloads/EntryPayload';
+import InvitePayload from '../payloads/InvitePayload';
+import LocationPayload from '../payloads/LocationPayload';
+import NotificationPayload from '../payloads/NotificationPayload';
+import EnvoyEntryEvent from '../internal/EnvoyEntryEvent';
+import EnvoyInviteEvent from '../internal/EnvoyInviteEvent';
+import EnvoyLocationEvent from '../internal/EnvoyLocationEvent';
+import EnvoyOptionsRouteResponseBody from '../internal/EnvoyOptionsRouteResponseBody';
+import EnvoyOptionsRouteParams from '../internal/EnvoyOptionsRouteParams';
+import EnvoySelectedValuesRouteResponseBody from '../internal/EnvoySelectedValuesRouteResponseBody';
+import EnvoySelectedValuesRouteParams from '../internal/EnvoySelectedValuesRouteParams';
+import EnvoyRemoteValueRouteResponseBody from '../internal/EnvoyRemoteValueRouteResponseBody';
+
+/**
+ * @internal
+ */
+export const VERIFIED = Symbol('verified');
+
+/**
+ * @internal
+ */
+export interface VerifiedRequest extends Request {
+  [VERIFIED]: boolean
+}
+
+/**
+ * Base type for Envoy requests.
+ * You probably won't need to use this type directly.
+ * For routes, use {@link EnvoyRouteRequest},
+ * and for events, use {@link EnvoyEntryEventRequest} or {@link EnvoyInviteEventRequest}.
+ *
+ * @category Base
+ */
+export interface EnvoyBaseRequest<Meta = EnvoyMeta, Payload = unknown> extends VerifiedRequest {
+  envoy: EnvoyPluginSDK<Meta, Payload>
+}
+
+/**
+ * Use to type your `req` object in Envoy route handlers such as validation URLs.
+ *
+ * @category Request
+ */
+export type EnvoyRouteRequest<
+  Payload = unknown,
+  Config = Record<string, unknown>,
+  Params = Record<string, unknown>,
+  > = EnvoyBaseRequest<EnvoyRouteMeta<Config, Params>, Payload>;
+
+/**
+ * Use to type your `req` object in Envoy "migration" route handlers.
+ *
+ * @category Request
+ */
+export type EnvoyMigrationRouteRequest<OldConfig = Record<string, unknown>> =
+  EnvoyRouteRequest<never, OldConfig, never>;
+
+/**
+ * Use to type your `req` object in Envoy "options URL" route handlers.
+ *
+ * @category Request
+ */
+export type EnvoyOptionsRouteRequest<Config = Record<string, unknown>> =
+  EnvoyRouteRequest<EnvoyOptionsRouteResponseBody, Config, EnvoyOptionsRouteParams>;
+
+/**
+ * Use to type your `req` object in Envoy "selected values URL" route handlers.
+ *
+ * @category Request
+ */
+export type EnvoySelectedValuesRouteRequest<Config = Record<string, unknown>> =
+  EnvoyRouteRequest<EnvoySelectedValuesRouteResponseBody, Config, EnvoySelectedValuesRouteParams>;
+
+/**
+ * Use to type your `req` object in Envoy "remote value URL" route handlers.
+ *
+ * @category Request
+ */
+export type EnvoyRemoteValueRouteRequest<Config = Record<string, unknown>> =
+  EnvoyRouteRequest<EnvoyRemoteValueRouteResponseBody, Config, never>;
+
+/**
+ * Use to type your `req` object in Envoy "validation URL" route handlers.
+ *
+ * @category Request
+ */
+export type EnvoyValidationRouteRequest<Payload = Record<string, unknown>, Config = Record<string, unknown>> =
+  EnvoyRouteRequest<Payload, Config, never>;
+
+/**
+ * Base type for event requests.
+ * You should use {@link EnvoyEntryEventRequest} or {@link EnvoyInviteEventRequest}.
+ *
+ * @category Request
+ */
+export type EnvoyEventRequest<Event extends string = string, Payload = unknown, Config = Record<string, unknown>> =
+  EnvoyBaseRequest<EnvoyEventMeta<Event, Config>, Payload>;
+
+/**
+ * Use to type your `req` object in entry event handlers,
+ * such as handlers for `entry_sign_in`.
+ *
+ * @category Request
+ */
+export type EnvoyEntryEventRequest<Config = Record<string, unknown>> =
+  EnvoyEventRequest<EnvoyEntryEvent, EntryPayload, Config>;
+
+/**
+ * Use to type your `req` object in invite event handlers,
+ * such as handlers for `invite_created` or `upcoming_visit`.
+ *
+ * @category Request
+ */
+export type EnvoyInviteEventRequest<Config = Record<string, unknown>> =
+  EnvoyEventRequest<EnvoyInviteEvent, InvitePayload, Config>;
+
+/**
+ * Use to type your `req` object in location event handlers,
+ * such as handlers for `location_capacity_updated`.
+ *
+ * @category Request
+ */
+export type EnvoyLocationEventRequest<Config = Record<string, unknown>> =
+  EnvoyEventRequest<EnvoyLocationEvent, LocationPayload, Config>;
+
+/**
+ * Use to type your `req` object in your notification event handler.
+ *
+ * @category Request
+ */
+export type EnvoyNotificationEventRequest<Config = Record<string, unknown>> =
+  EnvoyEventRequest<string, NotificationPayload, Config>;
+
+/**
+ * You probably won't need to use this type directly.
+ * For routes, use {@link EnvoyRouteRequest},
+ * and for events, use {@link EnvoyEntryEventRequest} or {@link EnvoyInviteEventRequest}.
+ *
+ * @category Base
+ */
+type EnvoyRequest<Payload = unknown, Config = Record<string, unknown>> =
+  EnvoyBaseRequest<EnvoyRouteMeta<Config> | EnvoyEventMeta<string, Config>, Payload>;
+export default EnvoyRequest;

package/src/sdk/EnvoyResponse.ts

@@ -0,0 +1,46 @@
+import { Response } from 'express';
+import EnvoyPluginJobAttachment from './EnvoyPluginJobAttachment';
+import EnvoyOptionsRouteResponseBody from '../internal/EnvoyOptionsRouteResponseBody';
+import EnvoySelectedValuesRouteResponseBody from '../internal/EnvoySelectedValuesRouteResponseBody';
+import EnvoyRemoteValueRouteResponseBody from '../internal/EnvoyRemoteValueRouteResponseBody';
+
+/**
+ * Use to type your `res` object in Envoy event handlers.
+ * @category Response
+ */
+export default interface EnvoyResponse<Body = unknown> extends Response {
+  send: (body?: Body) => this;
+  /**
+   * Marks the job as "ongoing". This is useful for long-running event handling.
+   * Later on, you should update the job using
+   * {@link EnvoyPluginJob.complete}, {@link EnvoyPluginJob.fail}, or {@link EnvoyPluginJob.ignore}.
+   */
+  sendOngoing: (debugInfo?: unknown) => void;
+  /**
+   * Marks the job as "ignored". Useful when you explicitly do not want to handle the event.
+   */
+  sendIgnored: (message: string, debugInfo?: unknown, ...attachments: Array<EnvoyPluginJobAttachment>) => void;
+
+  /**
+   * Marks the job as "failed". The message will be communicated to the Envoy Dashboard user.
+   */
+  sendFailed: (message: string, debugInfo?: unknown, ...attachments: Array<EnvoyPluginJobAttachment>) => void;
+}
+
+/**
+ * Use to type your `res` object in Envoy "options URL" route handlers.
+ * @category Response
+ */
+export type EnvoyOptionsRouteResponse = EnvoyResponse<EnvoyOptionsRouteResponseBody>;
+
+/**
+ * Use to type your `res` object in Envoy "remote value URL" route handlers.
+ * @category Response
+ */
+export type EnvoyRemoteValueRouteResponse = EnvoyResponse<EnvoyRemoteValueRouteResponseBody>;
+
+/**
+ * Use to type your `res` object in Envoy "selected values URL" route handlers.
+ * @category Response
+ */
+export type EnvoySelectedValuesRouteResponse = EnvoyResponse<EnvoySelectedValuesRouteResponseBody>;

package/src/sdk/EnvoyStorageItem.ts

@@ -0,0 +1,9 @@
+/**
+ * @category Storage
+ */
+type EnvoyStorageItem<Value = unknown> = {
+  key: string,
+  value: Value,
+};
+
+export default EnvoyStorageItem;