@unito/integration-sdk 0.1.11 → 1.0.0

package/dist/src/index.cjs

@@ -33,6 +33,9 @@ var LogLevel;
     LogLevel["LOG"] = "log";
     LogLevel["DEBUG"] = "debug";
 })(LogLevel || (LogLevel = {}));
+/**
+ * Logger class that can be configured with metadata add creation and when logging to add additional context to your logs.
+ */
 class Logger {
     metadata;
     constructor(metadata = {}) {
@@ -85,12 +88,26 @@ class Logger {
     decorate(metadata) {
         this.metadata = { ...this.metadata, ...metadata };
     }
+    /**
+     * Return a copy of the Logger's metadata.
+     * @returns The  {@link Metadata} associated with the logger.
+     */
     getMetadata() {
         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.
+     */
     setMetadata(key, value) {
         this.metadata[key] = value;
     }
+    /**
+     * Clears the Logger's metadata.
+     */
     clearMetadata() {
         this.metadata = {};
     }
@@ -118,28 +135,78 @@ class Logger {
     }
 }
 
+/**
+ * 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}
+ */
 class Cache {
     cacheInstance;
     constructor(cacheInstance) {
         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
+     */
     getOrFetchValue(key, ttl, fetcher, lockTtl, shouldCacheError) {
         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.
+     */
     getValue(key) {
         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.
+     */
     setValue(key, value, ttl) {
         return this.cacheInstance.setValue(key, value, ttl);
     }
+    /**
+     * Delete a value from the cache.
+     * @param key — The key of the value to set.
+     */
     delValue(key) {
         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.
+     */
     getTtl(key) {
         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.
@@ -163,43 +230,73 @@ class Cache {
     }
 }
 
+/**
+ * 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
+ */
 class HttpError extends Error {
     status;
     constructor(message, status) {
         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.
+ */
 class BadRequestError extends HttpError {
     constructor(message) {
         super(message || 'Bad request', 400);
     }
 }
+/**
+ * Used to generate a 401 Unauthorized. Usually used when the credentials are missing or invalid.
+ */
 class UnauthorizedError extends HttpError {
     constructor(message) {
         super(message || 'Unauthorized', 401);
     }
 }
+/**
+ * Used to generate a 404 Not Found. Usually used when the requested `Item` is not found.
+ */
 class NotFoundError extends HttpError {
     constructor(message) {
         super(message || 'Not found', 404);
     }
 }
+/**
+ * Used to generate a 408 Timeout Error. Usually used when the call length exceeds the received Operation Deadline.
+ */
 class TimeoutError extends HttpError {
     constructor(message) {
         super(message || 'Not found', 408);
     }
 }
+/**
+ * Used to generate a 410 Resource Gone.
+ */
 class ResourceGoneError extends HttpError {
     constructor(message) {
         super(message || 'Resource gone or unavailable', 410);
     }
 }
+/**
+ * Used to generate a 422 Unprocessable Entity. Usually used when an operation is invalid.
+ */
 class UnprocessableEntityError extends HttpError {
     constructor(message) {
         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.
+ */
 class RateLimitExceededError extends HttpError {
     constructor(message) {
         super(message || 'Rate Limit Exceeded', 429);
@@ -256,13 +353,13 @@ function buildHttpError(responseStatus, message) {
     return httpError;
 }
 
-const middleware$7 = (req, res, next) => {
+const middleware$8 = (req, res, next) => {
     res.locals.correlationId = req.header('X-Unito-Correlation-Id') ?? uuid__namespace.v4();
     next();
 };
 
 const ADDITIONAL_CONTEXT_HEADER = 'X-Unito-Additional-Logging-Context';
-const middleware$6 = (req, res, next) => {
+const middleware$7 = (req, res, next) => {
     const logger = new Logger({ correlation_id: res.locals.correlationId });
     res.locals.logger = logger;
     const rawAdditionalContext = req.header(ADDITIONAL_CONTEXT_HEADER);
@@ -279,7 +376,7 @@ const middleware$6 = (req, res, next) => {
 };
 
 const CREDENTIALS_HEADER = 'X-Unito-Credentials';
-const middleware$5 = (req, res, next) => {
+const middleware$6 = (req, res, next) => {
     const credentialsHeader = req.header(CREDENTIALS_HEADER);
     if (credentialsHeader) {
         let credentials;
@@ -294,6 +391,27 @@ const middleware$5 = (req, res, next) => {
     next();
 };
 
+const OPERATION_DEADLINE_HEADER = 'X-Unito-Operation-Deadline';
+const middleware$5 = (req, res, next) => {
+    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();
+};
+
 const SECRETS_HEADER = 'X-Unito-Secrets';
 const middleware$4 = (req, res, next) => {
     const secretsHeader = req.header(SECRETS_HEADER);
@@ -491,6 +609,7 @@ class Handler {
                     selects: res.locals.selects,
                     filters: res.locals.filters,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                 });
@@ -510,6 +629,7 @@ class Handler {
                     secrets: res.locals.secrets,
                     body: req.body,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                 });
@@ -527,6 +647,7 @@ class Handler {
                     credentials: res.locals.credentials,
                     secrets: res.locals.secrets,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                 });
@@ -546,6 +667,7 @@ class Handler {
                     secrets: res.locals.secrets,
                     body: req.body,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                 });
@@ -563,6 +685,7 @@ class Handler {
                     credentials: res.locals.credentials,
                     secrets: res.locals.secrets,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                 });
@@ -580,6 +703,7 @@ class Handler {
                     credentials: res.locals.credentials,
                     secrets: res.locals.secrets,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                 });
@@ -594,6 +718,7 @@ class Handler {
                 const response = await handler({
                     secrets: res.locals.secrets,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                     body: req.body,
@@ -609,6 +734,7 @@ class Handler {
                 const response = await handler({
                     secrets: res.locals.secrets,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                     body: req.body,
@@ -629,6 +755,7 @@ class Handler {
                     credentials: res.locals.credentials,
                     body: req.body,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                 });
@@ -645,14 +772,56 @@ function printErrorMessage(message) {
     console.error(`\x1b[31m Oops! Something went wrong! \x1b[0m`);
     console.error(message);
 }
+/**
+ * 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.
+ */
 class Integration {
     handlers;
     instance = undefined;
     port;
+    /**
+     * 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 = {}) {
         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.
+     */
     addHandler(path, handlers) {
         if (this.instance) {
             printErrorMessage(`
@@ -685,6 +854,13 @@ class Integration {
             process.exit(1);
         }
     }
+    /**
+     * 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.
+     */
     start() {
         // Express Server initialization
         const app = express();
@@ -693,11 +869,12 @@ class Integration {
         app.use(express.json());
         // Must be one of the first handlers (to catch all the errors).
         app.use(middleware$1);
+        app.use(middleware$8);
         app.use(middleware$7);
         app.use(middleware$6);
-        app.use(middleware$5);
         app.use(middleware$4);
         app.use(middleware$3);
+        app.use(middleware$5);
         // Load handlers as needed.
         if (this.handlers.length) {
             for (const handler of this.handlers) {
@@ -721,11 +898,21 @@ class Integration {
     }
 }
 
+/**
+ * The Provider class is a wrapper around the fetch function to call a provider's HTTP API.
+ *
+ * Defines methods for the following HTTP methods: GET, POST, PUT, PATCH, DELETE.
+ *
+ * Needs to be initialized with a prepareRequest function to define the Provider's base URL and any specific headers to
+ * add to the requests, and can also be configured to use a provided rate limiting function.
+ * @see {@link RateLimiter}
+ * @see {@link prepareRequest}
+ */
 class Provider {
     rateLimiter = undefined;
     prepareRequest;
     /**
-     * Initialize a Provider with the given options.
+     * Initializes a Provider with the given options.
      *
      * @property prepareRequest - function to define the Provider's base URL and specific headers to add to the request.
      * @property rateLimiter - function to limit the rate of calls to the provider based on the caller's credentials.
@@ -734,52 +921,108 @@ class Provider {
         this.prepareRequest = options.prepareRequest;
         this.rateLimiter = options.rateLimiter;
     }
+    /**
+     * Performs a GET request to the provider.
+     *
+     * Uses the prepareRequest function to get the base URL and any specific headers to add to the request and by default
+     * adds the following headers:
+     * - Accept: application/json
+     *
+     * @param endpoint Path to the provider's resource. Will be added to the URL returned by the prepareRequest function.
+     * @param options RequestOptions used to adjust the call made to the provider (use to override default headers).
+     * @returns The {@link Response} extracted from the provider.
+     */
     async get(endpoint, options) {
         return this.fetchWrapper(endpoint, null, {
             ...options,
             method: 'GET',
             defaultHeaders: {
-                'Content-Type': 'application/json',
                 Accept: 'application/json',
             },
         });
     }
+    /**
+     * Performs a POST request to the provider.
+     *
+     * Uses the prepareRequest function to get the base URL and any specific headers to add to the request and by default
+     * adds the following headers:
+     * - Content-Type: application/json',
+     * - Accept: application/json
+     *
+     * @param endpoint Path to the provider's resource. Will be added to the URL returned by the prepareRequest function.
+     * @param options RequestOptions used to adjust the call made to the provider (use to override default headers).
+     * @returns The {@link Response} extracted from the provider.
+     */
     async post(endpoint, body, options) {
         return this.fetchWrapper(endpoint, body, {
             ...options,
             method: 'POST',
             defaultHeaders: {
-                'Content-Type': 'application/x-www-form-urlencoded',
+                'Content-Type': 'application/json',
                 Accept: 'application/json',
             },
         });
     }
+    /**
+     * Performs a PUT request to the provider.
+     *
+     * Uses the prepareRequest function to get the base URL and any specific headers to add to the request and by default
+     * adds the following headers:
+     * - Content-Type: application/json',
+     * - Accept: application/json
+     *
+     * @param endpoint Path to the provider's resource. Will be added to the URL returned by the prepareRequest function.
+     * @param options RequestOptions used to adjust the call made to the provider (use to override default headers).
+     * @returns The {@link Response} extracted from the provider.
+     */
     async put(endpoint, body, options) {
         return this.fetchWrapper(endpoint, body, {
             ...options,
             method: 'PUT',
             defaultHeaders: {
-                'Content-Type': 'application/x-www-form-urlencoded',
+                'Content-Type': 'application/json',
                 Accept: 'application/json',
             },
         });
     }
+    /**
+     * Performs a PATCH request to the provider.
+     *
+     * Uses the prepareRequest function to get the base URL and any specific headers to add to the request and by default
+     * adds the following headers:
+     * - Content-Type: application/json',
+     * - Accept: application/json
+     *
+     * @param endpoint Path to the provider's resource. Will be added to the URL returned by the prepareRequest function.
+     * @param options RequestOptions used to adjust the call made to the provider (use to override default headers).
+     * @returns The {@link Response} extracted from the provider.
+     */
     async patch(endpoint, body, options) {
         return this.fetchWrapper(endpoint, body, {
             ...options,
             method: 'PATCH',
             defaultHeaders: {
-                'Content-Type': 'application/x-www-form-urlencoded',
+                'Content-Type': 'application/json',
                 Accept: 'application/json',
             },
         });
     }
+    /**
+     * Performs a DELETE request to the provider.
+     *
+     * Uses the prepareRequest function to get the base URL and any specific headers to add to the request and by default
+     * adds the following headers:
+     * - Accept: application/json
+     *
+     * @param endpoint Path to the provider's resource. Will be added to the URL returned by the prepareRequest function.
+     * @param options RequestOptions used to adjust the call made to the provider (use to override default headers).
+     * @returns The {@link Response} extracted from the provider.
+     */
     async delete(endpoint, options) {
         return this.fetchWrapper(endpoint, null, {
             ...options,
             method: 'DELETE',
             defaultHeaders: {
-                'Content-Type': 'application/x-www-form-urlencoded',
                 Accept: 'application/json',
             },
         });
@@ -801,11 +1044,26 @@ class Provider {
             }
         }
         const callToProvider = async () => {
-            const response = await fetch(absoluteUrl, {
-                method: options.method,
-                headers,
-                body: stringifiedBody,
-            });
+            let response;
+            try {
+                response = await fetch(absoluteUrl, {
+                    method: options.method,
+                    signal: options.signal,
+                    headers,
+                    body: stringifiedBody,
+                });
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    switch (error.name) {
+                        case 'AbortError':
+                            throw buildHttpError(408, 'Request aborted');
+                        case 'TimeoutError':
+                            throw buildHttpError(408, 'Request timeout');
+                    }
+                }
+                throw buildHttpError(500, `Unexpected error while calling the provider: "${error}"`);
+            }
             if (response.status >= 400) {
                 const textResult = await response.text();
                 throw buildHttpError(response.status, textResult);

package/dist/src/index.d.ts

@@ -7,3 +7,4 @@ 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';

package/dist/src/integration.d.ts

@@ -2,12 +2,61 @@ import { HandlersInput } from './handler.js';
 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;
     private instance;
     private port;
+    /**
+     * 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);
+    /**
+     * 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.
+     */
     addHandler(path: string, handlers: HandlersInput): void;
+    /**
+     * 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.
+     */
     start(): void;
 }
 export {};