@unito/integration-sdk 0.1.0

package/src/middlewares/filters.ts

@@ -0,0 +1,51 @@
+import { OperatorType } from '@unito/integration-api';
+import { Request, Response, NextFunction } from 'express';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Locals {
+      filters: Filter[];
+    }
+  }
+}
+
+export interface 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
+// a subset of the symbol of another operator.
+//
+// For example, the symbol "=" (EQUAL) is a subset of the symbol "!=" (NOT_EQUAL).
+const ORDERED_OPERATORS = Object.values(OperatorType).sort((o1, o2) => o1.length - o2.length);
+
+const middleware = (req: Request, res: Response, next: NextFunction) => {
+  const rawFilters = req.query.filter;
+
+  res.locals.filters = [];
+
+  if (typeof rawFilters === 'string') {
+    for (const rawFilter of rawFilters.split(',')) {
+      for (const operator of ORDERED_OPERATORS) {
+        if (rawFilter.includes(operator)) {
+          const [field, valuesRaw] = rawFilter.split(operator, 2);
+          const values = valuesRaw ? valuesRaw.split('|').map(decodeURIComponent) : [];
+
+          res.locals.filters.push({ field: field!, operator, values });
+
+          break;
+        }
+      }
+    }
+  }
+
+  next();
+};
+
+export default middleware;

package/src/middlewares/finish.ts

@@ -0,0 +1,24 @@
+import { Request, Response, NextFunction } from 'express';
+import Logger from '../resources/logger.js';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Locals {
+      logger: Logger;
+    }
+  }
+}
+
+const middleware = (req: Request, res: Response, next: NextFunction) => {
+  if (req.originalUrl !== '/health') {
+    res.on('finish', function () {
+      const loggerLevel = res.statusCode >= 500 ? 'error' : 'info';
+      res.locals.logger[loggerLevel](`${req.method} ${req.originalUrl} ${res.statusCode}`);
+    });
+  }
+
+  next();
+};
+
+export default middleware;

package/src/middlewares/logger.ts

@@ -0,0 +1,36 @@
+import { Request, Response, NextFunction } from 'express';
+import Logger from '../resources/logger.js';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Locals {
+      correlationId: string;
+      logger: Logger;
+    }
+  }
+}
+
+const ADDITIONAL_CONTEXT_HEADER = 'X-Unito-Additional-Logging-Context';
+
+const middleware = (req: Request, res: Response, next: NextFunction) => {
+  const logger = new Logger({ correlation_id: res.locals.correlationId });
+
+  res.locals.logger = logger;
+
+  const rawAdditionalContext = req.header(ADDITIONAL_CONTEXT_HEADER);
+
+  if (typeof rawAdditionalContext === 'string') {
+    try {
+      const additionalContext = JSON.parse(Buffer.from(rawAdditionalContext, 'base64').toString('utf8'));
+
+      logger.decorate(additionalContext);
+    } catch (error) {
+      logger.warn(`Malformed HTTP header ${ADDITIONAL_CONTEXT_HEADER}: ${rawAdditionalContext}`);
+    }
+  }
+
+  next();
+};
+
+export default middleware;

package/src/middlewares/notFound.ts

@@ -0,0 +1,13 @@
+import { Request, Response, NextFunction } from 'express';
+import { Error as APIError } from '@unito/integration-api';
+
+const middleware = (req: Request, res: Response, _next: NextFunction) => {
+  const error: APIError = {
+    code: '404',
+    message: `Path ${req.path} not found.`,
+  };
+
+  res.status(404).json(error);
+};
+
+export default middleware;

package/src/middlewares/selects.ts

@@ -0,0 +1,31 @@
+import { Request, Response, NextFunction } from 'express';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Locals {
+      // When the query params contains...
+      //
+      //   select=name,department.name
+      //
+      // ... it becomes available as follow in handlers:
+      //
+      //   ['name', 'department.name']
+      selects: string[];
+    }
+  }
+}
+
+const middleware = (req: Request, res: Response, next: NextFunction) => {
+  const rawSelect = req.query.select;
+
+  if (typeof rawSelect === 'string') {
+    res.locals.selects = rawSelect.split(',');
+  } else {
+    res.locals.selects = [];
+  }
+
+  next();
+};
+
+export default middleware;

package/src/resources/cache.ts

@@ -0,0 +1,34 @@
+import { WriteThroughCache, LocalCache, CacheInstance } from 'cachette';
+import { createHash } from 'node:crypto';
+import * as uuid from 'uuid';
+import Logger from './logger.js';
+
+export type Cache = CacheInstance;
+
+export function initializeCache(): Cache {
+  const cacheInstance: Cache = process.env.REDIS_URL ? new WriteThroughCache(process.env.REDIS_URL) : new LocalCache();
+
+  // Intended: the correlation id will be the same for all logs of Cachette.
+  const correlationId = uuid.v4();
+
+  const logger = new Logger({ correlation_id: correlationId });
+
+  cacheInstance
+    .on('info', message => {
+      logger.info(message);
+    })
+    .on('warn', message => {
+      logger.warn(message);
+    })
+    .on('error', message => {
+      logger.error(message);
+    });
+
+  return cacheInstance;
+}
+
+const shake256 = createHash('shake256');
+
+export function generateCacheKey(value: string): string {
+  return shake256.update(value).digest('hex');
+}

package/src/resources/context.ts

@@ -0,0 +1,113 @@
+/* c8 ignore start */
+import * as API from '@unito/integration-api';
+
+import Logger from './logger.js';
+import { Credentials } from '../middlewares/credentials.js';
+import { Filter } from '../middlewares/filters.js';
+
+type Context<P extends Record<string, string>, Q extends ParsedQueryString> = {
+  /**
+   * The parsed credentials associated with the request through the X-Unito-Credentials header.
+   *
+   * Will contain the keys for the variables defined in the corresponding configuration's authorization.
+   */
+  credentials: Credentials;
+  /**
+   * The logger pre decorated with the correlation ID and the additionnal metadata provided through the request headers.
+   */
+  logger: Logger;
+  /**
+   * The request params.
+   *
+   * A call to `/customers/:customerId/subscriptions/:subscriptionId` => `/customers/123/subscriptions/2` will yield:
+   *
+   * {
+   *  customerId: '123',
+   *  subscriptionId: '2'
+   * }
+   */
+  params: P;
+  /**
+   * The raw query string parsed as an object.
+   */
+  query: Q;
+};
+
+export type GetItemContext<
+  P extends Record<string, string> = Record<string, never>,
+  Q extends Record<string, string> = Record<string, never>,
+> = 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> & {
+  /**
+   * Parsed filter query param yielding a list of filters.
+   *
+   *  Given a filter query param:
+   *  `filter=name=John,department.name=Engineering`
+   *
+   *  Context.filters will be:
+   *  [
+   *    { field: 'name', operator: 'EQUAL', values: ['John'] },
+   *    { field: 'department.name', operator: 'EQUAL', values: ['Engineering'] }
+   *  ]
+   */
+  filters: Filter[];
+  /**
+   * Parsed select query param yielding a list of fields to select.
+   *
+   *  Given a select query param:
+   *  `select=name,department.name`
+   *
+   *  Context.selects will be:
+   *  ['name', 'department.name']
+   */
+  selects: string[];
+};
+
+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,
+> = 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,
+> = 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 GetCredentialAccountContext<
+  P extends Record<string, string> = Record<string, never>,
+  Q extends Record<string, string> = Record<string, never>,
+> = Context<P, Q>;
+
+export type ParseWebhooksContext<
+  P extends Record<string, string> = Record<string, never>,
+  Q extends Record<string, string> = Record<string, never>,
+  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>,
+  B extends API.WebhookSubscriptionRequestPayload = API.WebhookSubscriptionRequestPayload,
+> = Context<P, Q> & { body: B };
+
+export type AckknowledgeWebhooksContext<
+  P extends Record<string, string> = Record<string, never>,
+  Q extends Record<string, string> = Record<string, never>,
+  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

@@ -0,0 +1,57 @@
+enum LogLevel {
+  ERROR = 'error',
+  WARN = 'warn',
+  INFO = 'info',
+  LOG = 'log',
+  DEBUG = 'debug',
+}
+
+export default class Logger {
+  private metadata: Record<string, unknown> = {};
+
+  constructor(metadata?: Record<string, unknown>) {
+    if (metadata) {
+      this.metadata = structuredClone(metadata);
+    }
+  }
+
+  private send(logLevel: LogLevel, message: unknown) {
+    console[logLevel](JSON.stringify({ message, ...this.metadata }));
+  }
+
+  public log(data: unknown) {
+    this.send(LogLevel.LOG, data);
+  }
+
+  public error(data: unknown) {
+    this.send(LogLevel.ERROR, data);
+  }
+
+  public warn(data: unknown) {
+    this.send(LogLevel.WARN, data);
+  }
+
+  public info(data: unknown) {
+    this.send(LogLevel.INFO, data);
+  }
+
+  public debug(data: unknown) {
+    this.send(LogLevel.DEBUG, data);
+  }
+
+  public decorate(metadata: Record<string, unknown>) {
+    this.metadata = { ...this.metadata, ...metadata };
+  }
+
+  public getMetadata() {
+    return structuredClone(this.metadata);
+  }
+
+  public setMetadata(key: string, value: unknown) {
+    this.metadata[key] = value;
+  }
+
+  public clearMetadata() {
+    this.metadata = {};
+  }
+}

package/src/resources/provider.ts

@@ -0,0 +1,120 @@
+import { handleErrorResponse as throwHttpError } from '../errors.js';
+import { Credentials } from '../middlewares/credentials.js';
+
+export interface RequestOptions {
+  credentials: Credentials;
+  queryParams?: { [key: string]: string };
+  body?: Record<string, unknown>;
+  additionnalheaders?: { [key: string]: string };
+}
+
+export interface Response<T> {
+  data: T;
+  headers: Headers;
+}
+
+export class Provider {
+  protected prepareRequest:
+    | ((context: { credentials: Credentials }) => {
+        /**
+         * The base URL of the provider.
+         */
+        url: string;
+        /**
+         * The additional headers to add to the request.
+         */
+        headers: Record<string, string>;
+      })
+    | undefined = undefined;
+
+  constructor(options: { prepareRequest: typeof Provider.prototype.prepareRequest }) {
+    this.prepareRequest = options.prepareRequest;
+  }
+
+  public async get<T>(endpoint: string, options: RequestOptions): Promise<Response<T>> {
+    return this.fetchWrapper<T>(endpoint, {
+      ...options,
+      method: 'GET',
+      defaultHeaders: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+    });
+  }
+
+  public async post<T>(endpoint: string, options: RequestOptions): Promise<Response<T>> {
+    return this.fetchWrapper<T>(endpoint, {
+      ...options,
+      method: 'POST',
+      defaultHeaders: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+      },
+    });
+  }
+
+  public async patch<T>(endpoint: string, options: RequestOptions): Promise<Response<T>> {
+    return this.fetchWrapper<T>(endpoint, {
+      ...options,
+      method: 'PATCH',
+      defaultHeaders: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+      },
+    });
+  }
+
+  private async fetchWrapper<T>(
+    endpoint: string,
+    options: RequestOptions & { defaultHeaders: { 'Content-Type': string; Accept: string }; method: string },
+  ): Promise<Response<T>> {
+    if (!this.prepareRequest) {
+      throw new Error('Provider not initialized');
+    }
+
+    const { url: providerUrl, headers: providerHeaders } = this.prepareRequest({ credentials: options.credentials });
+
+    let absoluteUrl = [providerUrl, endpoint.charAt(0) === '/' ? endpoint.substring(1) : endpoint].join('/');
+
+    if (options.queryParams) {
+      absoluteUrl = `${absoluteUrl}?${new URLSearchParams(options.queryParams)}`;
+    }
+
+    const headers = { ...options.defaultHeaders, ...providerHeaders, ...options.additionnalheaders };
+
+    let body: string | null = null;
+
+    if (options.body) {
+      if (headers['Content-Type'] === 'application/x-www-form-urlencoded') {
+        body = new URLSearchParams(options.body as Record<string, string>).toString(); // this doesn't support objects!
+      } else if (headers['Content-Type'] === 'application/json') {
+        body = JSON.stringify(options.body);
+      }
+    }
+
+    const callToProvider = async () =>
+      await fetch(absoluteUrl, {
+        method: options.method,
+        headers,
+        body: body,
+      });
+
+    // TODO: add back rate limiter
+    const response = await callToProvider();
+
+    if (response.status >= 400) {
+      const textResult = await response.text();
+      throwHttpError(response.status, textResult);
+    }
+
+    let data;
+
+    try {
+      data = await response.json();
+    } catch {
+      throwHttpError(400, 'Invalid JSON response');
+    }
+
+    return { headers: response.headers, data };
+  }
+}

package/test/errors.test.ts

@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as errors from '../src/errors.js';
+import * as httpErrors from '../src/httpErrors.js';
+
+describe('handleErrorResponse', () => {
+  it('returns correct httpError given status code', () => {
+    assert.throws(() => errors.handleErrorResponse(400, 'bad request'), httpErrors.BadRequestError);
+    assert.throws(() => errors.handleErrorResponse(401, 'unauthorized'), httpErrors.UnauthorizedError);
+    assert.throws(() => errors.handleErrorResponse(403, 'forbidden'), httpErrors.UnauthorizedError);
+    assert.throws(() => errors.handleErrorResponse(404, 'not found'), httpErrors.NotFoundError);
+    assert.throws(() => errors.handleErrorResponse(408, 'timeout'), httpErrors.TimeoutError);
+    assert.throws(() => errors.handleErrorResponse(422, 'unprocessable entity'), httpErrors.UnprocessableEntityError);
+    assert.throws(() => errors.handleErrorResponse(429, 'rate limit exceeded'), httpErrors.RateLimitExceededError);
+    assert.throws(() => errors.handleErrorResponse(500, 'internal server error'), httpErrors.HttpError);
+  });
+});

package/test/handler.test.ts

@@ -0,0 +1,178 @@
+import { Request, Response } from 'express';
+import assert from 'node:assert/strict';
+import { afterEach, beforeEach, describe, it, mock } from 'node:test';
+import { Handler } from '../src/handler.js';
+import { BadRequestError } from '../src/httpErrors.js';
+
+describe('Handler', () => {
+  beforeEach(() => {
+    // Disable debug logging to keep the test output clean.
+    mock.method(global.console, 'debug', () => {});
+  });
+
+  afterEach(() => {
+    mock.reset();
+  });
+
+  describe('constructor', () => {
+    it('returns a Handler', () => {
+      const itemHandler = new Handler('/', {});
+
+      assert.equal(itemHandler instanceof Handler, true);
+    });
+
+    it('validates path', () => {
+      const paths: [string, boolean][] = [
+        ['', false],
+        ['invalid', false],
+        ['/', true],
+        ['/bar', true],
+        ['/bar/', false],
+        ['/foo/:bar', true],
+        ['/foo/:bar/', false],
+        ['/foo/:bar/spam/:baz', true],
+        ['/foo/:bar/:spam', true],
+      ];
+
+      for (const [path, valid] of paths) {
+        if (valid) {
+          assert.doesNotThrow(() => new Handler(path, {}));
+        } else {
+          assert.throws(() => new Handler(path, {}));
+        }
+      }
+    });
+  });
+
+  describe('generate', () => {
+    async function executeHandler(
+      handler: (req: Request, res: Response) => Promise<void>,
+      request: Record<string, unknown> = {},
+    ) {
+      let body: Record<string, unknown> = {};
+      let statusCode = 0;
+
+      const response = {
+        status: (receivedStatusCode: number) => ({
+          send: (receivedBody: Record<string, unknown>) => {
+            body = receivedBody;
+            statusCode = receivedStatusCode;
+          },
+        }),
+        statusCode: 0,
+        locals: {
+          credentials: { foo: 'bar' },
+        },
+      } as unknown as Response;
+
+      await handler(request as unknown as Request, response);
+
+      return { body, statusCode };
+    }
+
+    it('returns a router', async () => {
+      const handler = new Handler('/foo/:bar', {
+        getCollection: () => Promise.resolve({ info: {}, data: [] }),
+        getItem: () => Promise.resolve({ fields: {}, relations: [] }),
+        createItem: () => Promise.resolve({ fields: {}, path: '/' }),
+        updateItem: () => Promise.resolve({ fields: {}, relations: [] }),
+        deleteItem: () => Promise.resolve(),
+      });
+
+      const router = handler.generate();
+      const routes = router.stack;
+
+      assert.equal(routes.length, 5);
+      assert.equal(routes[0].route.path, '/foo');
+      assert.equal(routes[0].route.methods.get, true);
+      assert.equal(routes[1].route.path, '/foo');
+      assert.equal(routes[1].route.methods.post, true);
+      assert.equal(routes[2].route.path, '/foo/:bar');
+      assert.equal(routes[2].route.methods.get, true);
+      assert.equal(routes[3].route.path, '/foo/:bar');
+      assert.equal(routes[3].route.methods.patch, true);
+      assert.equal(routes[4].route.path, '/foo/:bar');
+      assert.equal(routes[4].route.methods.delete, true);
+
+      // GetCollection.
+      assert.deepEqual(await executeHandler(routes[0].route.stack[0].handle), {
+        body: { info: {}, data: [] },
+        statusCode: 200,
+      });
+
+      // CreateItem.
+      assert.deepEqual(await executeHandler(routes[1].route.stack[0].handle, { body: { foo: 'bar' } }), {
+        body: { fields: {}, path: '/' },
+        statusCode: 201,
+      });
+
+      // GetItem.
+      assert.deepEqual(await executeHandler(routes[2].route.stack[0].handle), {
+        body: { fields: {}, relations: [] },
+        statusCode: 200,
+      });
+
+      // UpdateItem.
+      assert.deepEqual(await executeHandler(routes[3].route.stack[0].handle, { body: { foo: 'bar' } }), {
+        body: { fields: {}, relations: [] },
+        statusCode: 200,
+      });
+
+      // DeleteItem.
+      assert.deepEqual(await executeHandler(routes[4].route.stack[0].handle), {
+        body: null,
+        statusCode: 204,
+      });
+    });
+
+    it('uses pathWithIdentifier as is when appropriate', async () => {
+      const handler = new Handler('/foo/:bar/baz', {
+        getCollection: () => Promise.resolve({ info: {}, data: [] }),
+      });
+
+      const router = handler.generate();
+      const routes = router.stack;
+
+      assert.equal(routes.length, 1);
+      assert.equal(routes[0].route.path, '/foo/:bar/baz');
+      assert.equal(routes[0].route.methods.get, true);
+
+      // GetCollection.
+      assert.deepEqual(await executeHandler(routes[0].route.stack[0].handle), {
+        body: { info: {}, data: [] },
+        statusCode: 200,
+      });
+    });
+
+    it('undefined handlers', async () => {
+      const handler = new Handler('/foo/:bar', {});
+
+      const router = handler.generate();
+      const routes = router.stack;
+
+      assert.equal(routes.length, 0);
+    });
+
+    it('returns a 400 for invalid request payloads', async () => {
+      const handler = new Handler('/foo/:bar', {
+        createItem: () => Promise.resolve({ fields: {}, path: '/' }),
+        updateItem: () => Promise.resolve({ fields: {}, relations: [] }),
+      });
+
+      const router = handler.generate();
+      const routes = router.stack;
+
+      // CreateItemRequestPayload.
+      const createHandler = routes[0].route.stack[0].handle;
+      await assert.doesNotReject(async () => await executeHandler(createHandler, { body: { foo: 'bar' } }));
+      await assert.rejects(async () => await executeHandler(createHandler, { body: null }), BadRequestError);
+      await assert.rejects(async () => await executeHandler(createHandler, { body: 'not json' }), BadRequestError);
+
+      // UpdateItemRequestPayload.
+      const updateHandler = routes[0].route.stack[0].handle;
+      await assert.doesNotReject(async () => await executeHandler(updateHandler, { body: { foo: 'bar' } }));
+      await assert.rejects(async () => await executeHandler(updateHandler, { body: null }), BadRequestError);
+      await assert.rejects(async () => await executeHandler(updateHandler, { body: 'not json' }), BadRequestError);
+    });
+  });
+});