@unito/integration-sdk 0.1.0

package/dist/src/handler.js

@@ -0,0 +1,224 @@
+import { Router } from 'express';
+import { InvalidHandler } from './errors.js';
+import { UnauthorizedError, BadRequestError } from './httpErrors.js';
+function assertValidPath(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) {
+    const pathParts = path.split('/');
+    const lastPart = pathParts.at(-1);
+    if (pathParts.length > 1 && lastPart && lastPart.startsWith(':')) {
+        pathParts.pop();
+    }
+    return { pathWithIdentifier: path, path: pathParts.join('/') };
+}
+function assertCreateItemRequestPayload(body) {
+    if (typeof body !== 'object' || body === null) {
+        throw new BadRequestError('Invalid CreateItemRequestPayload');
+    }
+}
+function assertUpdateItemRequestPayload(body) {
+    if (typeof body !== 'object' || body === null) {
+        throw new BadRequestError('Invalid UpdateItemRequestPayload');
+    }
+}
+function assertWebhookParseRequestPayload(body) {
+    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) {
+    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 {
+    path;
+    pathWithIdentifier;
+    handlers;
+    constructor(inputPath, handlers) {
+        // Build paths.
+        assertValidPath(inputPath);
+        const { pathWithIdentifier, path } = parsePath(inputPath);
+        this.pathWithIdentifier = pathWithIdentifier;
+        this.path = path;
+        this.handlers = handlers;
+    }
+    generate() {
+        const 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/dist/src/httpErrors.d.ts

@@ -0,0 +1,22 @@
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare class BadRequestError extends HttpError {
+    constructor(message?: string);
+}
+export declare class UnauthorizedError extends HttpError {
+    constructor(message?: string);
+}
+export declare class NotFoundError extends HttpError {
+    constructor(message?: string);
+}
+export declare class TimeoutError extends HttpError {
+    constructor(message?: string);
+}
+export declare class UnprocessableEntityError extends HttpError {
+    constructor(message?: string);
+}
+export declare class RateLimitExceededError extends HttpError {
+    constructor(message?: string);
+}

package/dist/src/httpErrors.js

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

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+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/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/src/index.js

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

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/src/integration.d.ts

@@ -0,0 +1,9 @@
+import { HandlersInput } from './handler.js';
+export default class Integration {
+    private handlers;
+    private instance;
+    private cache;
+    constructor();
+    addHandler(path: string, handlers: HandlersInput): void;
+    start(): void;
+}

package/dist/src/integration.js

@@ -0,0 +1,108 @@
+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 } from './resources/cache.js';
+import { Handler } from './handler.js';
+function printErrorMessage(message) {
+    console.error();
+    console.error(`\x1b[31m Oups! Something went wrong! \x1b[0m`);
+    console.error(message);
+}
+export default class Integration {
+    handlers;
+    instance = undefined;
+    cache = undefined;
+    constructor() {
+        this.handlers = [];
+    }
+    addHandler(path, handlers) {
+        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.message}
+        `);
+            }
+            process.exit(1);
+        }
+    }
+    start() {
+        // Initialize the cache.
+        this.cache = initializeCache();
+        // Express Server initialization
+        const app = 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/dist/src/middlewares/correlationId.d.ts

@@ -0,0 +1,10 @@
+import { Request, Response, NextFunction } from 'express';
+declare global {
+    namespace Express {
+        interface Locals {
+            correlationId: string;
+        }
+    }
+}
+declare const middleware: (req: Request, res: Response, next: NextFunction) => void;
+export default middleware;

package/dist/src/middlewares/correlationId.js

@@ -0,0 +1,6 @@
+import * as uuid from 'uuid';
+const middleware = (req, res, next) => {
+    res.locals.correlationId = req.header('X-Unito-Correlation-Id') ?? uuid.v4();
+    next();
+};
+export default middleware;

package/dist/src/middlewares/credentials.d.ts

@@ -0,0 +1,11 @@
+import { Request, Response, NextFunction } from 'express';
+declare global {
+    namespace Express {
+        interface Locals {
+            credentials: Credentials;
+        }
+    }
+}
+export type Credentials = Record<string, unknown>;
+declare const middleware: (req: Request, res: Response, next: NextFunction) => void;
+export default middleware;

package/dist/src/middlewares/credentials.js

@@ -0,0 +1,17 @@
+import { BadRequestError } from '../httpErrors.js';
+const CREDENTIALS_HEADER = 'X-Unito-Credentials';
+const middleware = (req, res, next) => {
+    const credentialsHeader = req.header(CREDENTIALS_HEADER);
+    if (credentialsHeader) {
+        let 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/dist/src/middlewares/errors.d.ts

@@ -0,0 +1,3 @@
+import { Request, Response, NextFunction } from 'express';
+declare const middleware: (err: Error, _req: Request, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;
+export default middleware;

package/dist/src/middlewares/errors.js

@@ -0,0 +1,22 @@
+import { HttpError } from '../httpErrors.js';
+const middleware = (err, _req, res, next) => {
+    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 = {
+        code: err.name,
+        message: err.message,
+    };
+    res.status(500).json({
+        code: '500',
+        message: 'Oops! Something went wrong',
+        originalError,
+    });
+};
+export default middleware;

package/dist/src/middlewares/filters.d.ts

@@ -0,0 +1,16 @@
+import { OperatorType } from '@unito/integration-api';
+import { Request, Response, NextFunction } from 'express';
+declare global {
+    namespace Express {
+        interface Locals {
+            filters: Filter[];
+        }
+    }
+}
+export interface Filter {
+    field: string;
+    operator: OperatorType;
+    values: string[] | undefined;
+}
+declare const middleware: (req: Request, res: Response, next: NextFunction) => void;
+export default middleware;

package/dist/src/middlewares/filters.js

@@ -0,0 +1,25 @@
+import { OperatorType } from '@unito/integration-api';
+// 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, res, next) => {
+    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/dist/src/middlewares/finish.d.ts

@@ -0,0 +1,11 @@
+import { Request, Response, NextFunction } from 'express';
+import Logger from '../resources/logger.js';
+declare global {
+    namespace Express {
+        interface Locals {
+            logger: Logger;
+        }
+    }
+}
+declare const middleware: (req: Request, res: Response, next: NextFunction) => void;
+export default middleware;

package/dist/src/middlewares/finish.js

@@ -0,0 +1,10 @@
+const middleware = (req, res, next) => {
+    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/dist/src/middlewares/logger.d.ts

@@ -0,0 +1,12 @@
+import { Request, Response, NextFunction } from 'express';
+import Logger from '../resources/logger.js';
+declare global {
+    namespace Express {
+        interface Locals {
+            correlationId: string;
+            logger: Logger;
+        }
+    }
+}
+declare const middleware: (req: Request, res: Response, next: NextFunction) => void;
+export default middleware;

package/dist/src/middlewares/logger.js

@@ -0,0 +1,18 @@
+import Logger from '../resources/logger.js';
+const ADDITIONAL_CONTEXT_HEADER = 'X-Unito-Additional-Logging-Context';
+const middleware = (req, res, next) => {
+    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/dist/src/middlewares/notFound.d.ts

@@ -0,0 +1,3 @@
+import { Request, Response, NextFunction } from 'express';
+declare const middleware: (req: Request, res: Response, _next: NextFunction) => void;
+export default middleware;

package/dist/src/middlewares/notFound.js

@@ -0,0 +1,8 @@
+const middleware = (req, res, _next) => {
+    const error = {
+        code: '404',
+        message: `Path ${req.path} not found.`,
+    };
+    res.status(404).json(error);
+};
+export default middleware;

package/dist/src/middlewares/selects.d.ts

@@ -0,0 +1,10 @@
+import { Request, Response, NextFunction } from 'express';
+declare global {
+    namespace Express {
+        interface Locals {
+            selects: string[];
+        }
+    }
+}
+declare const middleware: (req: Request, res: Response, next: NextFunction) => void;
+export default middleware;

package/dist/src/middlewares/selects.js

@@ -0,0 +1,11 @@
+const middleware = (req, res, next) => {
+    const rawSelect = req.query.select;
+    if (typeof rawSelect === 'string') {
+        res.locals.selects = rawSelect.split(',');
+    }
+    else {
+        res.locals.selects = [];
+    }
+    next();
+};
+export default middleware;

package/dist/src/resources/cache.d.ts

@@ -0,0 +1,4 @@
+import { CacheInstance } from 'cachette';
+export type Cache = CacheInstance;
+export declare function initializeCache(): Cache;
+export declare function generateCacheKey(value: string): string;

package/dist/src/resources/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/resources/cache.ts"],"names":[],"mappings":";AAAA,OAAO,EAAiC,aAAa,EAAE,MAAM,UAAU,CAAC;AAMxE,eAAO,IAAI,QAAQ,EAAE,aAAa,CAAC;AACnC,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AACxD,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,CAAC;AAElF,wBAAgB,eAAe,IAAI,aAAa,CAyB/C;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,GAAE,iBAA2B,GAAG,MAAM,CAwBnG"}