@unito/integration-sdk 0.1.11 → 1.0.1

package/src/httpErrors.ts

@@ -1,48 +1,78 @@
+/**
+ * Error class meant to be returned by integrations in case of exceptions. These errors will be caught and handled
+ * appropriately. Any other error would result in an unhandled server error accompanied by a 500 status code.
+ *
+ * @field message - The error message
+ * @field status - The HTTP status code to return
+ */
 export class HttpError extends Error {
   readonly status: number;
 
   constructor(message: string, status: number) {
     super(message);
     this.status = status;
+    this.name = this.constructor.name;
   }
 }
 
+/**
+ * Used to generate a 400 Bad Request. Usually used when something is missing to properly handle the request.
+ */
 export class BadRequestError extends HttpError {
   constructor(message?: string) {
     super(message || 'Bad request', 400);
   }
 }
 
+/**
+ * Used to generate a 401 Unauthorized. Usually used when the credentials are missing or invalid.
+ */
 export class UnauthorizedError extends HttpError {
   constructor(message?: string) {
     super(message || 'Unauthorized', 401);
   }
 }
 
+/**
+ * Used to generate a 404 Not Found. Usually used when the requested `Item` is not found.
+ */
 export class NotFoundError extends HttpError {
   constructor(message?: string) {
     super(message || 'Not found', 404);
   }
 }
 
+/**
+ * Used to generate a 408 Timeout Error. Usually used when the call length exceeds the received Operation Deadline.
+ */
 export class TimeoutError extends HttpError {
   constructor(message?: string) {
     super(message || 'Not found', 408);
   }
 }
 
+/**
+ * Used to generate a 410 Resource Gone.
+ */
 export class ResourceGoneError extends HttpError {
   constructor(message?: string) {
     super(message || 'Resource gone or unavailable', 410);
   }
 }
 
+/**
+ * Used to generate a 422 Unprocessable Entity. Usually used when an operation is invalid.
+ */
 export class UnprocessableEntityError extends HttpError {
   constructor(message?: string) {
     super(message || 'Unprocessable Entity', 422);
   }
 }
 
+/**
+ * Used to generate a 429 Unprocessable Entity. Usually used when an operation triggers or would trigger a rate limit
+ * error on the provider's side.
+ */
 export class RateLimitExceededError extends HttpError {
   constructor(message?: string) {
     super(message || 'Rate Limit Exceeded', 429);

package/src/index.ts

@@ -13,4 +13,5 @@ export type { Secrets } from './middlewares/secrets.js';
 export type { Credentials } from './middlewares/credentials.js';
 export * as HttpErrors from './httpErrors.js';
 export * from './resources/context.js';
+export { type default as Logger } from './resources/logger.js';
 /* c8 ignore stop */

package/src/integration.ts

@@ -5,6 +5,7 @@ import { InvalidHandler } from './errors.js';
 import correlationIdMiddleware from './middlewares/correlationId.js';
 import loggerMiddleware from './middlewares/logger.js';
 import credentialsMiddleware from './middlewares/credentials.js';
+import signalMiddleware from './middlewares/signal.js';
 import secretsMiddleware from './middlewares/secrets.js';
 import selectsMiddleware from './middlewares/selects.js';
 import errorsMiddleware from './middlewares/errors.js';
@@ -22,6 +23,18 @@ type Options = {
   port?: number;
 };
 
+/**
+ * Main class for the Integration SDK providing an abstraction layer between the Integration's Graph definition
+ * and the underlying HTTP server.
+ *
+ * An `Integration` instance can have multiple handlers configured to handle different routes. Upon receiving a request,
+ * the Integration will parse the request to extract meaninful information, match the request to the appropriate handler
+ * method and forward that information in the form a {@link Context} object.
+ * The Integration also offer standardized error handling and logging to help you build a robust
+ * and reliable Integration.
+ *
+ * See our {@link https://dev.unito.io/docs/ | documentation} for more examples on how to build an integration.
+ */
 export default class Integration {
   private handlers: Handler[];
 
@@ -29,11 +42,41 @@ export default class Integration {
 
   private port: number;
 
+  /**
+   * Creates a new Integration instance with default port set to 9200.
+   *
+   * @param options The {@link Options} to configure the Integration instance. Can be used to override the default port.
+   */
   constructor(options: Options = {}) {
     this.port = options.port || 9200;
     this.handlers = [];
   }
 
+  /**
+   * Adds a group of common handlers to the integration.
+   *
+   * Handlers added to the integration can be one of the following:
+   * - `ItemHandlers`: A group of handlers defining the implementation of the Operations available for a given item.
+   * - `CredentialAccountHandlers`: A handler returning the CredentialAccount linked to the caller's credentials.
+   * - `ParseWebhookHandlers`: A handler parsing the content of an incoming webhook.
+   * - `WebhookSubscriptionHandlers`: A handler subscribing or unsubscribing to a particular webhook.
+   * - `AcknowledgeWebhookHandlers`: A handler acknowledging the reception of a webhook.
+   *
+   * To accomodate the fact that ItemHandlers may specify multiple operations, some at the collection level, some at the
+   * item level, we need a way to define the route for each of these operations.
+   * To achieve this, we assume that if the last part of the path is a variable, then it is the item identifier.
+   *
+   * @example The following path: `/trainer/:trainerId/pokemons/:pokemonId` will lead to the following
+   * routes:
+   * - getCollection will be called for `GET /trainer/:trainerId/pokemons/` requests
+   * - getItem will be called for `GET /trainer/:trainerId/pokemons/:pokemonId` requests
+   * - createItem will be called for `POST /trainer/:trainerId/pokemons/` requests
+   * - updateItem will be called for `PATCH /trainer/:trainerId/pokemons/:pokemonId` requests
+   * - deleteItem will be called for `DELETE /trainer/:trainerId/pokemons/:pokemonId` requests
+   *
+   * @param path The path to be used as Route for the handlers.
+   * @param handlers The Handlers definition.
+   */
   public addHandler(path: string, handlers: HandlersInput): void {
     if (this.instance) {
       printErrorMessage(`
@@ -66,6 +109,13 @@ export default class Integration {
     }
   }
 
+  /**
+   * Starts the server and listens on the specified port (default to 9200).
+   *
+   * @remarks
+   * This function should be called after all the handlers have been added to the integration
+   * and any other configuration is completed.
+   */
   public start() {
     // Express Server initialization
     const app: express.Application = express();
@@ -83,6 +133,7 @@ export default class Integration {
     app.use(credentialsMiddleware);
     app.use(secretsMiddleware);
     app.use(selectsMiddleware);
+    app.use(signalMiddleware);
 
     // Load handlers as needed.
     if (this.handlers.length) {

package/src/middlewares/filters.ts

@@ -10,13 +10,22 @@ declare global {
   }
 }
 
-export interface Filter {
+/**
+ * Represents one filter parsed from the filters query param.
+ *
+ *  Given a filters query param containing:
+ *  `filters=[...],name=John,[...]`
+ *
+ *  Filter for `name=John` will be:
+ * `{ field: 'name', operator: 'EQUAL', values: ['John'] }`
+ */
+export type Filter = {
   field: string;
   operator: OperatorType;
   // Without the schema of the item,
   // we can't determine the types of the values (number, boolean, etc).
   values: string[] | undefined;
-}
+};
 
 // The operators are ordered by their symbol length, in descending order.
 // This is necessary because the symbol of an operator can be

package/src/middlewares/secrets.ts

@@ -10,6 +10,11 @@ declare global {
   }
 }
 
+/**
+ * Represents the secrets parsed from the X-Unito-Secrets header.
+ *
+ * This is the decrypted payload of the secrets defined in the integration's configuration.
+ */
 export type Secrets = { [keys: string]: unknown };
 
 const SECRETS_HEADER = 'X-Unito-Secrets';

package/src/middlewares/signal.ts

@@ -0,0 +1,41 @@
+import { Request, Response, NextFunction } from 'express';
+import { TimeoutError } from '../httpErrors.js';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Locals {
+      /**
+       * An AbortSignal instantiated with the X-Unito-Operation-Deadline header. This header contains the timestamp
+       * after which Unito will consider the operation to be timed out. You can use this signal to abort any
+       * operation that would exceed this time frame.
+       */
+      signal: AbortSignal;
+    }
+  }
+}
+
+const OPERATION_DEADLINE_HEADER = 'X-Unito-Operation-Deadline';
+
+const middleware = (req: Request, res: Response, next: NextFunction) => {
+  const operationDeadlineHeader = Number(req.header(OPERATION_DEADLINE_HEADER));
+
+  if (operationDeadlineHeader) {
+    // `operationDeadlineHeader` represents a timestamp in the future, in seconds.
+    // We need to convert it to a number of milliseconds.
+    const deadline = operationDeadlineHeader * 1000 - Date.now();
+
+    if (deadline > 0) {
+      res.locals.signal = AbortSignal.timeout(deadline);
+    } else {
+      throw new TimeoutError('Request already timed out upon reception');
+    }
+  } else {
+    // Default to 20s, which is the maximum time frame allowed for an operation by Unito.
+    res.locals.signal = AbortSignal.timeout(20000);
+  }
+
+  next();
+};
+
+export default middleware;

package/src/resources/cache.ts

@@ -2,6 +2,12 @@ import { WriteThroughCache, LocalCache, CacheInstance, FetchingFunction, Cachabl
 import * as uuid from 'uuid';
 import Logger from './logger.js';
 
+/**
+ * The Cache class provides caching capabilities that can be used across your integration.
+ * It can be backed by a Redis instance (by passing it a URL to the instance) or a local cache.
+ *
+ * @see {@link Cache.create}
+ */
 export class Cache {
   private cacheInstance: CacheInstance;
 
@@ -9,6 +15,19 @@ export class Cache {
     this.cacheInstance = cacheInstance;
   }
 
+  /**
+   * Get or fetch a value
+   *
+   * @param key     The key of the value to get
+   * @param ttl     The time to live of the value in seconds.
+   * @param fetchFn The function that can retrieve the original value
+   * @param lockTtl Global distributed lock TTL (in seconds) protecting fetching.
+   *                If undefined, 0 or falsy, locking is not preformed
+   * @param shouldCacheError A callback being passed errors, controlling whether
+   *                         to cache or not errors. Defaults to never cache.
+   *
+   * @returns       The cached or fetched value
+   */
   public getOrFetchValue<F extends FetchingFunction = FetchingFunction>(
     key: string,
     ttl: number,
@@ -19,24 +38,55 @@ export class Cache {
     return this.cacheInstance.getOrFetchValue(key, ttl, fetcher, lockTtl, shouldCacheError);
   }
 
+  /**
+   * Get a value from the cache.
+   *
+   * @param key   The key of the value to get.
+   *
+   * @return      The value associated with the key, or undefined if
+   *              no such value exists.
+   */
   public getValue(key: string): Promise<CachableValue> {
     return this.cacheInstance.getValue(key);
   }
 
+  /**
+   * Set a value in the cache.
+   *
+   * @param key        The key of the value to set.
+   * @param value      The value to set.
+   * @param ttl        The time to live of the value in seconds.
+   *                   By default, the value will not expire
+   *
+   * @return true if the value was stored, false otherwise.
+   */
   public setValue(key: string, value: CachableValue, ttl?: number): Promise<boolean> {
     return this.cacheInstance.setValue(key, value, ttl);
   }
 
+  /**
+   * Delete a value from the cache.
+   * @param key — The key of the value to set.
+   */
   public delValue(key: string): Promise<void> {
     return this.cacheInstance.delValue(key);
   }
 
+  /**
+   * Get the TTL of an entry, in ms
+   *
+   * @param key   The key of the entry whose ttl to retrieve
+   *
+   * @return      The remaining TTL on the entry, in ms.
+   *              undefined if the entry does not exist.
+   *              0 if the entry does not expire.
+   */
   public getTtl(key: string): Promise<number | undefined> {
     return this.cacheInstance.getTtl(key);
   }
 
   /**
-   * Initializes a WriteThroughCache instance with the provided redis url if present, or a LocalCache otherwise.
+   * Initializes a Cache backed by the Redis instance at the provided url if present, or a LocalCache otherwise.
    *
    * @param redisUrl - The redis url to connect to (optional).
    * @returns A cache instance.

package/src/resources/context.ts

@@ -6,7 +6,21 @@ import { Credentials } from '../middlewares/credentials.js';
 import { Secrets } from 'src/middlewares/secrets.js';
 import { Filter } from '../middlewares/filters.js';
 
-export type Context<P extends Record<string, string>, Q extends ParsedQueryString> = {
+type Maybe<T> = T | null;
+type Empty = Record<string, never>;
+type Params = Record<string, string>;
+type Query = {
+  [key: string]: undefined | string | string[] | Query | Query[];
+};
+type CreateItemBody = API.CreateItemRequestPayload;
+type UpdateItemBody = API.UpdateItemRequestPayload;
+
+/**
+ * The base context object is passed to every handler function.
+ *
+ * It contains the parsed request params, query string, credentials, secrets, etc.
+ */
+export type Context<P extends Maybe<Params> = Params, Q extends Maybe<Query> = Query> = {
   /**
    * The parsed credentials associated with the request through the X-Unito-Credentials header.
    *
@@ -23,6 +37,12 @@ export type Context<P extends Record<string, string>, Q extends ParsedQueryStrin
    * The logger pre decorated with the correlation ID and the additionnal metadata provided through the request headers.
    */
   logger: Logger;
+  /**
+   * Each request is expected to complete within a certain time frame. This signal object has been instantiated with the
+   * X-Unito-Operation-Deadline header. This header contains the timestamp after which Unito will consider the operation
+   * to be timed out. You can use this signal to abort any operation that would exceed this time frame.
+   */
+  signal: AbortSignal;
   /**
    * The request params.
    *
@@ -40,15 +60,20 @@ export type Context<P extends Record<string, string>, Q extends ParsedQueryStrin
   query: Q;
 };
 
-export type GetItemContext<
-  P extends Record<string, string> = Record<string, never>,
-  Q extends Record<string, string> = Record<string, never>,
-> = Context<P, Q>;
+/**
+ * Context received by the `GetItemHandler`.
+ *
+ * @see {@link Context}
+ */
+export type GetItemContext<P extends Maybe<Params> = Empty, Q extends Query = Empty> = Context<P, Q>;
 
-export type GetCollectionContext<
-  P extends Record<string, string> = Record<string, never>,
-  Q extends Record<string, string> = Record<string, never>,
-> = Context<P, Q> & {
+/**
+ * Context received by the `GetCollectionHandler`.
+ *
+ * @filters Array of {@link Filter} representing the filterss parsed from the query params
+ * @see {@link Context} for base params
+ */
+export type GetCollectionContext<P extends Maybe<Params> = Empty, Q extends Query = Empty> = Context<P, Q> & {
   /**
    * Parsed filter query param yielding a list of filters.
    *
@@ -60,6 +85,8 @@ export type GetCollectionContext<
    *    { field: 'name', operator: 'EQUAL', values: ['John'] },
    *    { field: 'department.name', operator: 'EQUAL', values: ['Engineering'] }
    *  ]
+   *
+   * @see {@link Filter}
    */
   filters: Filter[];
   /**
@@ -75,46 +102,36 @@ export type GetCollectionContext<
 };
 
 export type CreateItemContext<
-  P extends Record<string, string> = Record<string, never>,
-  Q extends Record<string, string> = Record<string, never>,
-  B extends API.CreateItemRequestPayload = API.CreateItemRequestPayload,
+  P extends Maybe<Params> = Empty,
+  Q extends Maybe<Query> = Empty,
+  B extends CreateItemBody = API.CreateItemRequestPayload,
 > = Context<P, Q> & { body: B };
 
 export type UpdateItemContext<
-  P extends Record<string, string> = Record<string, never>,
-  Q extends Record<string, string> = Record<string, never>,
-  B extends API.UpdateItemRequestPayload = API.UpdateItemRequestPayload,
+  P extends Maybe<Params> = Empty,
+  Q extends Maybe<Query> = Empty,
+  B extends UpdateItemBody = API.UpdateItemRequestPayload,
 > = Context<P, Q> & { body: B };
 
-export type DeleteItemContext<
-  P extends Record<string, string> = Record<string, never>,
-  Q extends Record<string, string> = Record<string, never>,
-> = Context<P, Q>;
+export type DeleteItemContext<P extends Maybe<Params> = Empty, Q extends Query = Empty> = Context<P, Q>;
 
-export type GetCredentialAccountContext<
-  P extends Record<string, string> = Record<string, never>,
-  Q extends Record<string, string> = Record<string, never>,
-> = Context<P, Q>;
+export type GetCredentialAccountContext<P extends Maybe<Params> = Empty, Q extends Query = Empty> = Context<P, Q>;
 
 export type ParseWebhooksContext<
-  P extends Record<string, string> = Record<string, never>,
-  Q extends Record<string, string> = Record<string, never>,
+  P extends Maybe<Params> = Empty,
+  Q extends Maybe<Query> = Empty,
   B extends API.WebhookParseRequestPayload = API.WebhookParseRequestPayload,
 > = Omit<Context<P, Q>, 'credentials'> & { body: B };
 
 export type UpdateWebhookSubscriptionsContext<
-  P extends Record<string, string> = Record<string, never>,
-  Q extends Record<string, string> = Record<string, never>,
+  P extends Maybe<Params> = Empty,
+  Q extends Maybe<Query> = Empty,
   B extends API.WebhookSubscriptionRequestPayload = API.WebhookSubscriptionRequestPayload,
 > = Context<P, Q> & { body: B };
 
 export type AcknowledgeWebhooksContext<
-  P extends Record<string, string> = Record<string, never>,
-  Q extends Record<string, string> = Record<string, never>,
+  P extends Maybe<Params> = Empty,
+  Q extends Maybe<Query> = Empty,
   B extends API.WebhookParseRequestPayload = API.WebhookParseRequestPayload,
 > = Omit<Context<P, Q>, 'credentials'> & { body: B };
-
-interface ParsedQueryString {
-  [key: string]: undefined | string | string[] | ParsedQueryString | ParsedQueryString[];
-}
 /* c8 ignore stop */

package/src/resources/logger.ts

@@ -14,6 +14,9 @@ type Value = {
 export type Metadata = Value & { message?: never };
 type ForbidenMetadataKey = 'message';
 
+/**
+ * Logger class that can be configured with metadata add creation and when logging to add additional context to your logs.
+ */
 export default class Logger {
   private metadata: Metadata;
 
@@ -74,10 +77,21 @@ export default class Logger {
     this.metadata = { ...this.metadata, ...metadata };
   }
 
+  /**
+   * Return a copy of the Logger's metadata.
+   * @returns The  {@link Metadata} associated with the logger.
+   */
   public getMetadata(): Metadata {
     return structuredClone(this.metadata);
   }
 
+  /**
+   * Sets a key-value pair in the metadata. If the key already exists, it will be overwritten.
+   *
+   * @param key Key of the metadata to be set.
+   * May be any string other than 'message', which is reserved for the actual message logged.
+   * @param value Value of the metadata to be set.
+   */
   public setMetadata<Key extends string>(
     key: Key extends ForbidenMetadataKey ? never : Key,
     value: PrimitiveValue | Value,
@@ -85,6 +99,9 @@ export default class Logger {
     this.metadata[key] = value;
   }
 
+  /**
+   * Clears the Logger's metadata.
+   */
   public clearMetadata(): void {
     this.metadata = {};
   }