@unito/integration-sdk 0.1.6 → 0.1.8

package/dist/test/resources/provider.test.js

@@ -41,7 +41,7 @@ describe('Provider', () => {
                 },
             },
         ]);
-        assert.deepEqual(actualResponse, { status: 200, headers: response.headers, data: { data: 'value' } });
+        assert.deepEqual(actualResponse, { status: 200, headers: response.headers, body: { data: 'value' } });
     });
     it('post with url encoded body', async (context) => {
         const response = new Response('{"data": "value"}', {
@@ -71,7 +71,7 @@ describe('Provider', () => {
                 },
             },
         ]);
-        assert.deepEqual(actualResponse, { status: 201, headers: response.headers, data: { data: 'value' } });
+        assert.deepEqual(actualResponse, { status: 201, headers: response.headers, body: { data: 'value' } });
     });
     it('put with json body', async (context) => {
         const response = new Response('{"data": "value"}', {
@@ -102,7 +102,7 @@ describe('Provider', () => {
                 },
             },
         ]);
-        assert.deepEqual(actualResponse, { status: 201, headers: response.headers, data: { data: 'value' } });
+        assert.deepEqual(actualResponse, { status: 201, headers: response.headers, body: { data: 'value' } });
     });
     it('patch with query params', async (context) => {
         const response = new Response('{"data": "value"}', {
@@ -133,7 +133,7 @@ describe('Provider', () => {
                 },
             },
         ]);
-        assert.deepEqual(actualResponse, { status: 201, headers: response.headers, data: { data: 'value' } });
+        assert.deepEqual(actualResponse, { status: 201, headers: response.headers, body: { data: 'value' } });
     });
     it('delete', async (context) => {
         const response = new Response(undefined, {
@@ -161,7 +161,7 @@ describe('Provider', () => {
                 },
             },
         ]);
-        assert.deepEqual(actualResponse, { status: 204, headers: response.headers, data: undefined });
+        assert.deepEqual(actualResponse, { status: 204, headers: response.headers, body: undefined });
     });
     it('uses rate limiter if provided', async (context) => {
         const mockRateLimiter = context.mock.fn((_context, request) => Promise.resolve(request()));
@@ -205,7 +205,7 @@ describe('Provider', () => {
                 },
             },
         ]);
-        assert.deepEqual(actualResponse, { status: 204, headers: response.headers, data: undefined });
+        assert.deepEqual(actualResponse, { status: 204, headers: response.headers, body: undefined });
     });
     it('throws on invalid json response', async (context) => {
         const response = new Response('{invalidJSON}', {

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@unito/integration-sdk",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Integration SDK",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "exports": {
     "./package.json": "./package.json",
-    ".": "./dist/src/index.js"
+    ".": {
+      "import": "./dist/src/index.js",
+      "require": "./dist/src/index.cjs"
+    }
   },
   "license": "LicenseRef-LICENSE",
   "engines": {
@@ -21,8 +24,10 @@
     "prepublishOnly": "npm run lint && npm run test",
     "prepare": "npm run compile",
     "lint": "eslint --fix src test --ext .ts && prettier --write src test",
-    "compile": "tsc --build",
-    "compile:watch": "npm run compile -- --watch",
+    "compile": "npm run compile:esm && npm run compile:cjs",
+    "compile:watch": "nodemon --watch \"src/**\" --ext js,ts --exec \"npm run compile\"",
+    "compile:esm": "tsc --build",
+    "compile:cjs": "rollup dist/src/index.js --file dist/src/index.cjs --format cjs",
     "test": "NODE_ENV=test node --test --no-warnings --loader ts-node/esm --test-name-pattern=${ONLY:-.*} $(find test -type f -name '*.test.ts')",
     "test:debug": "NODE_ENV=test node --test --loader ts-node/esm --test-name-pattern=${ONLY:-.*} --inspect-brk $(find test -type f -name '*.test.ts')",
     "ci:test": "npm run test"
@@ -36,7 +41,9 @@
     "c8": "9.x",
     "eslint": "8.x",
     "prettier": "3.x",
+    "rollup": "4.x",
     "ts-node": "10.x",
+    "nodemon": "3.x",
     "typescript": "5.x"
   },
   "dependencies": {

package/src/errors.ts

@@ -1,11 +1,5 @@
 import * as HttpErrors from './httpErrors.js';
 
-export class NoIntegrationFoundError extends Error {}
-
-export class NoConfigurationFileError extends Error {}
-
-export class ConfigurationMalformed extends Error {}
-
 export class InvalidHandler extends Error {}
 
 /**
@@ -25,6 +19,8 @@ export function buildHttpError(responseStatus: number, message: string): HttpErr
     httpError = new HttpErrors.NotFoundError(message);
   } else if (responseStatus === 408) {
     httpError = new HttpErrors.TimeoutError(message);
+  } else if (responseStatus === 410) {
+    httpError = new HttpErrors.ResourceGoneError(message);
   } else if (responseStatus === 422) {
     httpError = new HttpErrors.UnprocessableEntityError(message);
   } else if (responseStatus === 429) {

package/src/httpErrors.ts

@@ -31,20 +31,20 @@ export class TimeoutError extends HttpError {
   }
 }
 
-export class UnprocessableEntityError extends HttpError {
+export class ResourceGoneError extends HttpError {
   constructor(message?: string) {
-    super(message || 'Unprocessable Entity', 422);
+    super(message || 'Resource gone or unavailable', 410);
   }
 }
 
-export class RateLimitExceededError extends HttpError {
+export class UnprocessableEntityError extends HttpError {
   constructor(message?: string) {
-    super(message || 'Rate Limit Exceeded', 429);
+    super(message || 'Unprocessable Entity', 422);
   }
 }
 
-export class WouldExceedLimitError extends HttpError {
+export class RateLimitExceededError extends HttpError {
   constructor(message?: string) {
-    super(message || 'Would Exceed Limit', 429);
+    super(message || 'Rate Limit Exceeded', 429);
   }
 }

package/src/index.ts

@@ -1,5 +1,6 @@
 /* c8 ignore start */
 export * as Api from '@unito/integration-api';
+export { Cache } from './resources/cache.js';
 export { default as Integration } from './integration.js';
 export * from './handler.js';
 export {

package/src/integration.ts

@@ -9,7 +9,7 @@ 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 { shutdownCaches } from './resources/cache.js';
 import { HandlersInput, Handler } from './handler.js';
 
 function printErrorMessage(message: string) {
@@ -27,8 +27,6 @@ export default class Integration {
 
   private instance: Server<typeof IncomingMessage, typeof ServerResponse> | undefined = undefined;
 
-  private cache: Cache | undefined = undefined;
-
   private port: number;
 
   constructor(options: Options = {}) {
@@ -69,9 +67,6 @@ export default class Integration {
   }
 
   public start() {
-    // Initialize the cache.
-    this.cache = initializeCache();
-
     // Express Server initialization
     const app: express.Application = express();
 
@@ -121,9 +116,7 @@ export default class Integration {
             this.instance.close();
           }
 
-          if (this.cache) {
-            await this.cache.quit();
-          }
+          await shutdownCaches();
         } catch (e) {
           console.error('Failed to gracefully exit', e);
         }

package/src/middlewares/errors.ts

@@ -1,30 +1,55 @@
 import { Request, Response, NextFunction } from 'express';
-import { Error as APIError } from '@unito/integration-api';
+import { Error as ApiError } from '@unito/integration-api';
+
 import { HttpError } from '../httpErrors.js';
 
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Locals {
+      error?: ApiError;
+    }
+  }
+}
+
 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);
-  }
+  let error: ApiError;
 
   if (err instanceof HttpError) {
-    return res.status(err.status).json(err.message);
+    error = {
+      code: err.status.toString(),
+      message: err.message,
+      details: {
+        stack: err.stack,
+      },
+    };
+  } else {
+    error = {
+      code: '500',
+      message: 'Oops! Something went wrong',
+      originalError: {
+        code: err.name,
+        message: err.message,
+        details: {
+          stack: err.stack,
+        },
+      },
+    };
   }
 
-  const originalError: APIError = {
-    code: err.name,
-    message: err.message,
-  };
+  res.locals.error = structuredClone(error);
+
+  // Keep the stack details in development for the Debugger
+  if (process.env.NODE_ENV !== 'development') {
+    delete error.details;
+    delete error.originalError?.details;
+  }
 
-  res.status(500).json({
-    code: '500',
-    message: 'Oops! Something went wrong',
-    originalError,
-  } as APIError);
+  res.status(Number(error.code)).json(error);
 };
 
 export default middleware;

package/src/middlewares/finish.ts

@@ -1,11 +1,13 @@
 import { Request, Response, NextFunction } from 'express';
-import Logger from '../resources/logger.js';
+import { Error as ApiError } from '@unito/integration-api';
+import { default as Logger, Metadata } from '../resources/logger.js';
 
 declare global {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace Express {
     interface Locals {
       logger: Logger;
+      error?: ApiError;
     }
   }
 }
@@ -13,8 +15,31 @@ declare global {
 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}`);
+      const error = res.locals.error;
+
+      const message = `${req.method} ${req.originalUrl} ${res.statusCode}`;
+      const metadata: Metadata = {
+        // Use reserved and standard attributes of Datadog
+        // https://app.datadoghq.com/logs/pipelines/standard-attributes
+        http: { method: req.method, status_code: res.statusCode, url_details: { path: req.originalUrl } },
+        ...(error
+          ? {
+              error: {
+                kind: error.message,
+                stack: (error.originalError?.details?.stack ?? error.details?.stack) as string,
+                message: error.originalError?.message ?? error.message,
+              },
+            }
+          : {}),
+      };
+
+      if ([404, 429].includes(res.statusCode)) {
+        res.locals.logger.warn(message, metadata);
+      } else if (res.statusCode >= 400) {
+        res.locals.logger.error(message, metadata);
+      } else {
+        res.locals.logger.info(message, metadata);
+      }
     });
   }
 

package/src/resources/cache.ts

@@ -1,34 +1,77 @@
-import { WriteThroughCache, LocalCache, CacheInstance } from 'cachette';
-import { createHash } from 'node:crypto';
+import { WriteThroughCache, LocalCache, CacheInstance, FetchingFunction, CachableValue } from 'cachette';
 import * as uuid from 'uuid';
 import Logger from './logger.js';
 
-export type Cache = CacheInstance;
+/**
+ * Array of created caches kept to allow for graceful shutdown on exit signals.
+ */
+const caches: CacheInstance[] = [];
 
-export function initializeCache(): Cache {
-  const cacheInstance: Cache = process.env.REDIS_URL ? new WriteThroughCache(process.env.REDIS_URL) : new LocalCache();
+export const shutdownCaches = async () => {
+  return Promise.allSettled(caches.map(cache => cache.quit()));
+};
 
-  // Intended: the correlation id will be the same for all logs of Cachette.
-  const correlationId = uuid.v4();
+export class Cache {
+  private cacheInstance: CacheInstance;
 
-  const logger = new Logger({ correlation_id: correlationId });
+  private constructor(cacheInstance: CacheInstance) {
+    this.cacheInstance = cacheInstance;
+  }
 
-  cacheInstance
-    .on('info', message => {
-      logger.info(message);
-    })
-    .on('warn', message => {
-      logger.warn(message);
-    })
-    .on('error', message => {
-      logger.error(message);
-    });
+  public getOrFetchValue<F extends FetchingFunction = FetchingFunction>(
+    key: string,
+    ttl: number,
+    fetcher: F,
+    lockTtl?: number,
+    shouldCacheError?: (err: Error) => boolean,
+  ): Promise<ReturnType<F>> {
+    return this.cacheInstance.getOrFetchValue(key, ttl, fetcher, lockTtl, shouldCacheError);
+  }
 
-  return cacheInstance;
-}
+  public getValue(key: string): Promise<CachableValue> {
+    return this.cacheInstance.getValue(key);
+  }
+
+  public setValue(key: string, value: CachableValue, ttl?: number): Promise<boolean> {
+    return this.cacheInstance.setValue(key, value, ttl);
+  }
+
+  public delValue(key: string): Promise<void> {
+    return this.cacheInstance.delValue(key);
+  }
+
+  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.
+   *
+   * @param redisUrl - The redis url to connect to (optional).
+   * @returns A cache instance.
+   */
+  public static create(redisUrl?: string): Cache {
+    const cacheInstance: CacheInstance = redisUrl ? new WriteThroughCache(redisUrl) : new LocalCache();
+
+    // Push to the array of caches for graceful shutdown on exit signals.
+    caches.push(cacheInstance);
+
+    // Intended: the correlation id will be the same for all logs of Cachette.
+    const correlationId = uuid.v4();
+
+    const logger = new Logger({ correlation_id: correlationId });
 
-const shake256 = createHash('shake256');
+    cacheInstance
+      .on('info', message => {
+        logger.info(message);
+      })
+      .on('warn', message => {
+        logger.warn(message);
+      })
+      .on('error', message => {
+        logger.error(message);
+      });
 
-export function generateCacheKey(value: string): string {
-  return shake256.update(value).digest('hex');
+    return new Cache(cacheInstance);
+  }
 }

package/src/resources/logger.ts

@@ -1,4 +1,4 @@
-enum LogLevel {
+const enum LogLevel {
   ERROR = 'error',
   WARN = 'warn',
   INFO = 'info',
@@ -6,52 +6,112 @@ enum LogLevel {
   DEBUG = 'debug',
 }
 
-export default class Logger {
-  private metadata: Record<string, unknown> = {};
+type PrimitiveValue = undefined | null | string | string[] | number | number[] | boolean | boolean[];
+type Value = {
+  [key: string]: PrimitiveValue | Value;
+};
 
-  constructor(metadata?: Record<string, unknown>) {
-    if (metadata) {
-      this.metadata = structuredClone(metadata);
-    }
-  }
+export type Metadata = Value & { message?: never };
+type ForbidenMetadataKey = 'message';
 
-  private send(logLevel: LogLevel, message: unknown) {
-    console[logLevel](JSON.stringify({ message, ...this.metadata }));
+export default class Logger {
+  private metadata: Metadata;
+
+  constructor(metadata: Metadata = {}) {
+    this.metadata = structuredClone(metadata);
   }
 
-  public log(data: unknown) {
-    this.send(LogLevel.LOG, data);
+  /**
+   * Logs a message with the 'log' log level.
+   * @param message The message to be logged.
+   * @param metadata Optional metadata to be associated with the log message.
+   */
+  public log(message: string, metadata?: Metadata): void {
+    this.send(LogLevel.LOG, message, metadata);
   }
 
-  public error(data: unknown) {
-    this.send(LogLevel.ERROR, data);
+  /**
+   * Logs an error message with the 'error' log level.
+   * @param message The error message to be logged.
+   * @param metadata Optional metadata to be associated with the log message.
+   */
+  public error(message: string, metadata?: Metadata): void {
+    this.send(LogLevel.ERROR, message, metadata);
   }
 
-  public warn(data: unknown) {
-    this.send(LogLevel.WARN, data);
+  /**
+   * Logs a warning message with the 'warn' log level.
+   * @param message The warning message to be logged.
+   * @param metadata Optional metadata to be associated with the log message.
+   */
+  public warn(message: string, metadata?: Metadata): void {
+    this.send(LogLevel.WARN, message, metadata);
   }
 
-  public info(data: unknown) {
-    this.send(LogLevel.INFO, data);
+  /**
+   * Logs an informational message with the 'info' log level.
+   * @param message The informational message to be logged.
+   * @param metadata Optional metadata to be associated with the log message.
+   */
+  public info(message: string, metadata?: Metadata): void {
+    this.send(LogLevel.INFO, message, metadata);
   }
 
-  public debug(data: unknown) {
-    this.send(LogLevel.DEBUG, data);
+  /**
+   * Logs a debug message with the 'debug' log level.
+   * @param message The debug message to be logged.
+   * @param metadata Optional metadata to be associated with the log message.
+   */
+  public debug(message: string, metadata?: Metadata): void {
+    this.send(LogLevel.DEBUG, message, metadata);
   }
 
-  public decorate(metadata: Record<string, unknown>) {
+  /**
+   * Decorates the logger with additional metadata.
+   * @param metadata Additional metadata to be added to the logger.
+   */
+  public decorate(metadata: Metadata): void {
     this.metadata = { ...this.metadata, ...metadata };
   }
 
-  public getMetadata() {
+  public getMetadata(): Metadata {
     return structuredClone(this.metadata);
   }
 
-  public setMetadata(key: string, value: unknown) {
+  public setMetadata<Key extends string>(
+    key: Key extends ForbidenMetadataKey ? never : Key,
+    value: PrimitiveValue | Value,
+  ): void {
     this.metadata[key] = value;
   }
 
-  public clearMetadata() {
+  public clearMetadata(): void {
     this.metadata = {};
   }
+
+  private send(logLevel: LogLevel, message: string, metadata?: Metadata): void {
+    const processedMessage = this.snakifyKeys({
+      ...this.metadata,
+      ...metadata,
+      message,
+    });
+
+    if (process.env.NODE_ENV === 'development') {
+      console[logLevel](JSON.stringify(processedMessage, null, 2));
+    } else {
+      console[logLevel](JSON.stringify(processedMessage));
+    }
+  }
+
+  private snakifyKeys<T extends Value>(value: T): T {
+    const result: Value = {};
+
+    for (const key in value) {
+      const deepValue = typeof value[key] === 'object' ? this.snakifyKeys(value[key] as Value) : value[key];
+      const snakifiedKey = key.replace(/[\w](?<!_)([A-Z])/g, k => `${k[0]}_${k[1]}`).toLowerCase();
+      result[snakifiedKey] = deepValue;
+    }
+
+    return result as T;
+  }
 }

package/src/resources/provider.ts

@@ -31,7 +31,7 @@ export interface RequestOptions {
 }
 
 export interface Response<T> {
-  data: T;
+  body: T;
   status: number;
   headers: Headers;
 }
@@ -151,8 +151,8 @@ export class Provider {
       }
 
       try {
-        const data: T = response.body ? await response.json() : undefined;
-        return { status: response.status, headers: response.headers, data };
+        const body: T = response.body ? await response.json() : undefined;
+        return { status: response.status, headers: response.headers, body };
       } catch {
         throw buildHttpError(400, 'Invalid JSON response');
       }

package/test/errors.test.ts

@@ -9,6 +9,7 @@ describe('handleErrorResponse', () => {
     assert.ok(errors.buildHttpError(403, 'forbidden') instanceof httpErrors.UnauthorizedError);
     assert.ok(errors.buildHttpError(404, 'not found') instanceof httpErrors.NotFoundError);
     assert.ok(errors.buildHttpError(408, 'timeout') instanceof httpErrors.TimeoutError);
+    assert.ok(errors.buildHttpError(410, 'resource gone') instanceof httpErrors.ResourceGoneError);
     assert.ok(errors.buildHttpError(422, 'unprocessable entity') instanceof httpErrors.UnprocessableEntityError);
     assert.ok(errors.buildHttpError(429, 'rate limit exceeded') instanceof httpErrors.RateLimitExceededError);
     assert.ok(errors.buildHttpError(500, 'internal server error') instanceof httpErrors.HttpError);

package/test/middlewares/errors.test.ts

@@ -49,7 +49,7 @@ describe('errors middleware', () => {
     middleware(new HttpError('httpError', 429), {} as express.Request, response, () => {});
 
     assert.strictEqual(actualStatus, 429);
-    assert.strictEqual(actualJson, 'httpError');
+    assert.deepEqual(actualJson, { code: '429', message: 'httpError' });
   });
 
   it('handles other error', () => {

package/test/resources/cache.test.ts

@@ -1,31 +1,21 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import { LocalCache } from 'cachette';
-import { generateCacheKey, initializeCache } from '../../src/resources/cache.js';
+import { Cache, shutdownCaches } from '../../src/resources/cache.js';
 
 describe('Cache', () => {
   describe('initializeCache', () => {
-    it('no redis url returns LocalCache', () => {
-      const cache = initializeCache();
+    it('no redis url returns Cache with a inner LocalCache', async () => {
+      const cache = Cache.create();
 
-      assert.equal(cache instanceof LocalCache, true);
+      assert.ok(cache instanceof Cache);
+      assert.ok(cache['cacheInstance'] instanceof LocalCache);
 
-      cache.quit();
+      await shutdownCaches();
     });
 
     it('redis url returns (tries) WriteThroughCache', () => {
-      process.env.REDIS_URL = 'fakeredis'; //'redis://localhost:6379';
-      assert.throws(() => initializeCache(), Error, 'Invalid redis url fakereis.');
-    });
-  });
-
-  describe('generateCacheKey', () => {
-    it('hashes string and returns hex value', () => {
-      const value = 'test';
-      const hash = generateCacheKey(value);
-
-      assert.equal(typeof hash, 'string');
-      assert.equal(hash.length, 64);
+      assert.throws(() => Cache.create('fakeredis'), Error, 'Invalid redis url fakereis.');
     });
   });
 });