@unito/integration-sdk 0.1.0

package/src/handler.ts

@@ -0,0 +1,404 @@
+import { Router } from 'express';
+import * as API from '@unito/integration-api';
+import { InvalidHandler } from './errors.js';
+import { UnauthorizedError, BadRequestError } from './httpErrors.js';
+import {
+  GetItemContext,
+  GetCollectionContext,
+  CreateItemContext,
+  UpdateItemContext,
+  DeleteItemContext,
+  GetCredentialAccountContext,
+  ParseWebhooksContext,
+  UpdateWebhookSubscriptionsContext,
+  AckknowledgeWebhooksContext,
+} from './resources/context.js';
+
+/**
+ * Handler called to get an individual item.
+ */
+export type GetItemHandler = (context: GetItemContext<any, any>) => Promise<API.Item>;
+
+/**
+ * Handler called to retrieve a collection of items.
+ */
+export type GetCollectionHandler = (context: GetCollectionContext<any, any>) => Promise<API.Collection>;
+
+/**
+ * Handler called to create an item.
+ */
+export type CreateItemHandler = (context: CreateItemContext<any, any, any>) => Promise<API.ItemSummary>;
+
+/**
+ * Handler called to update an item.
+ */
+export type UpdateItemHandler = (context: UpdateItemContext<any, any, any>) => Promise<API.Item>;
+
+/**
+ * Handler called to delete an item.
+ */
+export type DeleteItemHandler = (context: DeleteItemContext<any, any>) => Promise<void>;
+
+/**
+ * Handler called to retrieve the account details associated with the credentials.
+ */
+export type GetCredentialAccountHandler = (
+  context: GetCredentialAccountContext<any, any>,
+) => Promise<API.CredentialAccount>;
+
+/**
+ * Handler called to parse the content of an incoming webhook.
+ */
+export type ParseWebhooksHandler = (
+  context: ParseWebhooksContext<any, any, any>,
+) => Promise<API.WebhookParseResponsePayload>;
+
+/**
+ * Handler called to subscribe or unsubscribe to a particular webhook.
+ */
+export type UpdateWebhookSubscriptionsHandler = (
+  context: UpdateWebhookSubscriptionsContext<any, any, any>,
+) => Promise<void>;
+
+/**
+ * Handler called to acknowledge the reception of a webhook.
+ */
+export type AckknowledgeWebhooksHandler = (
+  context: AckknowledgeWebhooksContext<any, any, any>,
+) => Promise<API.WebhookAcknowledgeResponsePayload>;
+
+type ItemHandlers = {
+  getItem?: GetItemHandler;
+  getCollection?: GetCollectionHandler;
+  createItem?: CreateItemHandler;
+  updateItem?: UpdateItemHandler;
+  deleteItem?: DeleteItemHandler;
+};
+
+type CredentialAccountHandlers = {
+  getCredentialAccount: GetCredentialAccountHandler;
+};
+
+type ParseWebhookHandlers = {
+  parseWebhooks: ParseWebhooksHandler;
+};
+
+type WebhookSubscriptionHandlers = {
+  updateWebhookSubscriptions: UpdateWebhookSubscriptionsHandler;
+};
+
+type AcknowledgeWebhookHandlers = {
+  acknowledgeWebhooks?: AckknowledgeWebhooksHandler;
+};
+
+export type HandlersInput =
+  | ItemHandlers
+  | CredentialAccountHandlers
+  | ParseWebhookHandlers
+  | WebhookSubscriptionHandlers
+  | AcknowledgeWebhookHandlers;
+
+type Handlers = Partial<
+  ItemHandlers &
+    CredentialAccountHandlers &
+    ParseWebhookHandlers &
+    WebhookSubscriptionHandlers &
+    AcknowledgeWebhookHandlers
+>;
+
+type Path = string & { __brand: 'Path' };
+
+function assertValidPath(path: string): asserts path is Path {
+  if (!path.startsWith('/')) {
+    throw new InvalidHandler(`The provided path '${path}' is invalid. All paths must start with a '/'.`);
+  }
+
+  if (path.length > 1 && path.endsWith('/')) {
+    throw new InvalidHandler(`The provided path '${path}' is invalid. Paths must not end with a '/'.`);
+  }
+}
+
+function parsePath(path: Path) {
+  const pathParts = path.split('/');
+
+  const lastPart = pathParts.at(-1);
+
+  if (pathParts.length > 1 && lastPart && lastPart.startsWith(':')) {
+    pathParts.pop();
+  }
+
+  return { pathWithIdentifier: path, path: pathParts.join('/') as Path };
+}
+
+function assertCreateItemRequestPayload(body: unknown): asserts body is API.CreateItemRequestPayload {
+  if (typeof body !== 'object' || body === null) {
+    throw new BadRequestError('Invalid CreateItemRequestPayload');
+  }
+}
+
+function assertUpdateItemRequestPayload(body: unknown): asserts body is API.UpdateItemRequestPayload {
+  if (typeof body !== 'object' || body === null) {
+    throw new BadRequestError('Invalid UpdateItemRequestPayload');
+  }
+}
+
+function assertWebhookParseRequestPayload(body: unknown): asserts body is API.WebhookParseRequestPayload {
+  if (typeof body !== 'object' || body === null) {
+    throw new BadRequestError('Invalid WebhookParseRequestPayload');
+  }
+
+  if (!('payload' in body) || body.payload !== 'string') {
+    throw new BadRequestError("Missing required 'payload' property in WebhookParseRequestPayload");
+  }
+
+  if (!('url' in body) || body.url !== 'string') {
+    throw new BadRequestError("Missing required 'url' property in WebhookParseRequestPayload");
+  }
+}
+
+function assertWebhookSubscriptionRequestPayload(body: unknown): asserts body is API.WebhookSubscriptionRequestPayload {
+  if (typeof body !== 'object' || body === null) {
+    throw new BadRequestError('Invalid WebhookSubscriptionRequestPayload');
+  }
+
+  if (!('itemPath' in body) || body.itemPath !== 'string') {
+    throw new BadRequestError("Missing required 'itemPath' property in WebhookSubscriptionRequestPayload");
+  }
+
+  if (!('targetUrl' in body) || body.targetUrl !== 'string') {
+    throw new BadRequestError("Missing required 'targetUrl' property in WebhookSubscriptionRequestPayload");
+  }
+
+  if (!('action' in body) || body.action !== 'string') {
+    throw new BadRequestError("Missing required 'action' property in WebhookSubscriptionRequestPayload");
+  }
+
+  if (!['start', 'stop'].includes(body.action)) {
+    throw new BadRequestError("Invalid value for 'action' property in WebhookSubscriptionRequestPayload");
+  }
+}
+
+export class Handler {
+  private path: Path;
+  private pathWithIdentifier: Path;
+
+  private handlers: Handlers;
+
+  constructor(inputPath: string, handlers: HandlersInput) {
+    // Build paths.
+    assertValidPath(inputPath);
+
+    const { pathWithIdentifier, path } = parsePath(inputPath);
+
+    this.pathWithIdentifier = pathWithIdentifier;
+    this.path = path;
+
+    this.handlers = handlers;
+  }
+
+  public generate(): Router {
+    const router: Router = Router({ caseSensitive: true });
+
+    console.debug(`\x1b[33mMounting handler at path ${this.pathWithIdentifier}`);
+
+    if (this.handlers.getCollection) {
+      const handler = this.handlers.getCollection;
+
+      console.debug(`  Enabling GET ${this.path}`);
+
+      router.get(this.path, async (req, res) => {
+        if (!res.locals.credentials) {
+          throw new UnauthorizedError();
+        }
+
+        const collection = await handler({
+          credentials: res.locals.credentials,
+          selects: res.locals.selects,
+          filters: res.locals.filters,
+          logger: res.locals.logger,
+          params: req.params,
+          query: req.query,
+        });
+
+        res.status(200).send(collection);
+      });
+    }
+
+    if (this.handlers.createItem) {
+      const handler = this.handlers.createItem;
+
+      console.debug(`  Enabling POST ${this.path}`);
+
+      router.post(this.path, async (req, res) => {
+        if (!res.locals.credentials) {
+          throw new UnauthorizedError();
+        }
+
+        assertCreateItemRequestPayload(req.body);
+
+        const createItemSummary = await handler({
+          credentials: res.locals.credentials,
+          body: req.body,
+          logger: res.locals.logger,
+          params: req.params,
+          query: req.query,
+        });
+
+        res.status(201).send(createItemSummary);
+      });
+    }
+
+    if (this.handlers.getItem) {
+      const handler = this.handlers.getItem;
+
+      console.debug(`  Enabling GET ${this.pathWithIdentifier}`);
+
+      router.get(this.pathWithIdentifier, async (req, res) => {
+        if (!res.locals.credentials) {
+          throw new UnauthorizedError();
+        }
+
+        const item = await handler({
+          credentials: res.locals.credentials,
+          logger: res.locals.logger,
+          params: req.params,
+          query: req.query,
+        });
+
+        res.status(200).send(item);
+      });
+    }
+
+    if (this.handlers.updateItem) {
+      const handler = this.handlers.updateItem;
+
+      console.debug(`  Enabling PATCH ${this.pathWithIdentifier}`);
+
+      router.patch(this.pathWithIdentifier, async (req, res) => {
+        if (!res.locals.credentials) {
+          throw new UnauthorizedError();
+        }
+
+        assertUpdateItemRequestPayload(req.body);
+
+        const item = await handler({
+          credentials: res.locals.credentials,
+          body: req.body,
+          logger: res.locals.logger,
+          params: req.params,
+          query: req.query,
+        });
+
+        res.status(200).send(item);
+      });
+    }
+
+    if (this.handlers.deleteItem) {
+      const handler = this.handlers.deleteItem;
+
+      console.debug(`  Enabling DELETE ${this.pathWithIdentifier}`);
+
+      router.delete(this.pathWithIdentifier, async (req, res) => {
+        if (!res.locals.credentials) {
+          throw new UnauthorizedError();
+        }
+
+        await handler({
+          credentials: res.locals.credentials,
+          logger: res.locals.logger,
+          params: req.params,
+          query: req.query,
+        });
+
+        res.status(204).send(null);
+      });
+    }
+
+    if (this.handlers.getCredentialAccount) {
+      const handler = this.handlers.getCredentialAccount;
+
+      console.debug(`  Enabling GET ${this.pathWithIdentifier}`);
+
+      router.get(this.pathWithIdentifier, async (req, res) => {
+        if (!res.locals.credentials) {
+          throw new UnauthorizedError();
+        }
+
+        const credentialAccount = await handler({
+          credentials: res.locals.credentials,
+          logger: res.locals.logger,
+          params: req.params,
+          query: req.query,
+        });
+
+        res.status(200).send(credentialAccount);
+      });
+    }
+
+    if (this.handlers.acknowledgeWebhooks) {
+      const handler = this.handlers.acknowledgeWebhooks;
+
+      console.debug(`  Enabling POST ${this.pathWithIdentifier}`);
+
+      router.post(this.pathWithIdentifier, async (req, res) => {
+        assertWebhookParseRequestPayload(req.body);
+
+        const response = await handler({
+          logger: res.locals.logger,
+          params: req.params,
+          query: req.query,
+          body: req.body,
+        });
+
+        res.status(200).send(response);
+      });
+    }
+
+    if (this.handlers.parseWebhooks) {
+      const handler = this.handlers.parseWebhooks;
+
+      console.debug(`  Enabling POST ${this.pathWithIdentifier}`);
+
+      router.post(this.pathWithIdentifier, async (req, res) => {
+        assertWebhookParseRequestPayload(req.body);
+
+        const response = await handler({
+          logger: res.locals.logger,
+          params: req.params,
+          query: req.query,
+          body: req.body,
+        });
+
+        res.status(200).send(response);
+      });
+    }
+
+    if (this.handlers.updateWebhookSubscriptions) {
+      const handler = this.handlers.updateWebhookSubscriptions;
+
+      console.debug(`  Enabling PUT ${this.pathWithIdentifier}`);
+
+      router.put(this.pathWithIdentifier, async (req, res) => {
+        if (!res.locals.credentials) {
+          throw new UnauthorizedError();
+        }
+
+        assertWebhookSubscriptionRequestPayload(req.body);
+
+        const response = await handler({
+          credentials: res.locals.credentials,
+          body: req.body,
+          logger: res.locals.logger,
+          params: req.params,
+          query: req.query,
+        });
+
+        res.status(204).send(response);
+      });
+    }
+
+    console.debug(`\x1b[0m`);
+
+    return router;
+  }
+}

package/src/httpErrors.ts

@@ -0,0 +1,44 @@
+export class HttpError extends Error {
+  readonly status: number;
+
+  constructor(message: string, status: number) {
+    super(message);
+    this.status = status;
+  }
+}
+
+export class BadRequestError extends HttpError {
+  constructor(message?: string) {
+    super(message || 'Bad request', 400);
+  }
+}
+
+export class UnauthorizedError extends HttpError {
+  constructor(message?: string) {
+    super(message || 'Unauthorized', 401);
+  }
+}
+
+export class NotFoundError extends HttpError {
+  constructor(message?: string) {
+    super(message || 'Not found', 404);
+  }
+}
+
+export class TimeoutError extends HttpError {
+  constructor(message?: string) {
+    super(message || 'Not found', 408);
+  }
+}
+
+export class UnprocessableEntityError extends HttpError {
+  constructor(message?: string) {
+    super(message || 'Unprocessable Entity', 422);
+  }
+}
+
+export class RateLimitExceededError extends HttpError {
+  constructor(message?: string) {
+    super(message || 'Unprocessable Entity', 429);
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * as Api from '@unito/integration-api';
+export { default as Integration } from './integration.js';
+export * from './handler.js';
+export {
+  Provider,
+  type Response as ProviderResponse,
+  type RequestOptions as ProviderRequestOptions,
+} from './resources/provider.js';
+export * as HttpErrors from './httpErrors.js';
+export * from './resources/context.js';

package/src/integration.ts

@@ -0,0 +1,129 @@
+import { Server, IncomingMessage, ServerResponse } from 'http';
+import express from 'express';
+
+import { InvalidHandler } from './errors.js';
+import correlationIdMiddleware from './middlewares/correlationId.js';
+import loggerMiddleware from './middlewares/logger.js';
+import credentialsMiddleware from './middlewares/credentials.js';
+import selectsMiddleware from './middlewares/selects.js';
+import errorsMiddleware from './middlewares/errors.js';
+import finishMiddleware from './middlewares/finish.js';
+import notFoundMiddleware from './middlewares/notFound.js';
+import { initializeCache, Cache } from './resources/cache.js';
+import { HandlersInput, Handler } from './handler.js';
+
+function printErrorMessage(message: string) {
+  console.error();
+  console.error(`\x1b[31m Oups! Something went wrong! \x1b[0m`);
+  console.error(message);
+}
+
+export default class Integration {
+  private handlers: Handler[];
+
+  private instance: Server<typeof IncomingMessage, typeof ServerResponse> | undefined = undefined;
+
+  private cache: Cache | undefined = undefined;
+
+  constructor() {
+    this.handlers = [];
+  }
+
+  public addHandler(path: string, handlers: HandlersInput): void {
+    if (this.instance) {
+      printErrorMessage(`
+  It seems like you're trying to add a handler after the server has already started. This is probably
+  a mistake as calling the start() function essentially starts the server and ignore any further change.
+  To fix this error, move all your addHandler() calls before the start() function.
+      `);
+      process.exit(1);
+    }
+
+    try {
+      this.handlers.push(new Handler(path, handlers));
+    } catch (error) {
+      if (error instanceof InvalidHandler) {
+        printErrorMessage(`
+  It seems like you're trying to add an invalid handler. The exact error message is:
+
+  > ${error.message}
+
+  You must address this issue before trying again.
+        `);
+      } else {
+        printErrorMessage(`
+  An unexpected error happened as we were trying to add your handler. The exact error message is;
+
+  >  ${(error as Error).message}
+        `);
+      }
+      process.exit(1);
+    }
+  }
+
+  public start() {
+    // Initialize the cache.
+    this.cache = initializeCache();
+
+    // Express Server initialization
+    const app: express.Application = express();
+
+    // Parse query strings with https://github.com/ljharb/qs.
+    app.set('query parser', 'extended');
+
+    app.use(express.json());
+
+    // Must be one of the first handlers (to catch all the errors).
+    app.use(finishMiddleware);
+
+    app.use(correlationIdMiddleware);
+    app.use(loggerMiddleware);
+    app.use(credentialsMiddleware);
+    app.use(selectsMiddleware);
+
+    // Load handlers as needed.
+    if (this.handlers.length) {
+      for (const handler of this.handlers) {
+        app.use(handler.generate());
+      }
+    } else {
+      printErrorMessage(`
+  It seems like you're trying to start the server without any handler. This is probably a mistake as the
+  server wouldn't expose any route. To fix this error, add at least one handler before calling the start()
+  function.
+      `);
+      process.exit(1);
+    }
+
+    // Must be the (last - 1) handler.
+    app.use(errorsMiddleware);
+
+    // Must be the last handler.
+    app.use(notFoundMiddleware);
+
+    this.instance = app.listen(process.env.PORT || 9200, () =>
+      console.info(`Server started on port ${process.env.PORT || 9200}.`),
+    );
+
+    // Trap exit signals.
+    ['SIGTERM', 'SIGINT', 'SIGUSR2'].forEach(signalType => {
+      process.once(signalType, async () => {
+        console.info(`Received termination signal ${signalType}. Exiting.`);
+
+        try {
+          if (this.instance) {
+            this.instance.close();
+          }
+
+          if (this.cache) {
+            await this.cache.quit();
+          }
+        } catch (e) {
+          console.error('Failed to gracefully exit', e);
+        }
+
+        process.exit();
+      });
+    });
+  }
+}

package/src/middlewares/correlationId.ts

@@ -0,0 +1,19 @@
+import { Request, Response, NextFunction } from 'express';
+import * as uuid from 'uuid';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Locals {
+      correlationId: string;
+    }
+  }
+}
+
+const middleware = (req: Request, res: Response, next: NextFunction) => {
+  res.locals.correlationId = req.header('X-Unito-Correlation-Id') ?? uuid.v4();
+
+  next();
+};
+
+export default middleware;

package/src/middlewares/credentials.ts

@@ -0,0 +1,35 @@
+import { Request, Response, NextFunction } from 'express';
+import { BadRequestError } from '../httpErrors.js';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Locals {
+      credentials: Credentials;
+    }
+  }
+}
+
+export type Credentials = Record<string, unknown>;
+
+const CREDENTIALS_HEADER = 'X-Unito-Credentials';
+
+const middleware = (req: Request, res: Response, next: NextFunction) => {
+  const credentialsHeader = req.header(CREDENTIALS_HEADER);
+
+  if (credentialsHeader) {
+    let credentials: Credentials;
+
+    try {
+      credentials = JSON.parse(Buffer.from(credentialsHeader, 'base64').toString('utf8'));
+    } catch {
+      throw new BadRequestError(`Malformed HTTP header ${CREDENTIALS_HEADER}`);
+    }
+
+    res.locals.credentials = credentials;
+  }
+
+  next();
+};
+
+export default middleware;

package/src/middlewares/errors.ts

@@ -0,0 +1,30 @@
+import { Request, Response, NextFunction } from 'express';
+import { Error as APIError } from '@unito/integration-api';
+import { HttpError } from '../httpErrors.js';
+
+const middleware = (err: Error, _req: Request, res: Response, next: NextFunction) => {
+  if (res.headersSent) {
+    return next(err);
+  }
+
+  if (process.env.NODE_ENV !== 'production') {
+    res.locals.logger.error(err);
+  }
+
+  if (err instanceof HttpError) {
+    return res.status(err.status).json(err.message);
+  }
+
+  const originalError: APIError = {
+    code: err.name,
+    message: err.message,
+  };
+
+  res.status(500).json({
+    code: '500',
+    message: 'Oops! Something went wrong',
+    originalError,
+  } as APIError);
+};
+
+export default middleware;