@unito/integration-sdk 0.1.0 → 0.1.2

package/README.md

@@ -6,7 +6,7 @@ This SDK can be used to produce integrations that are compliant with the Integra
 ## Getting started
 
 ```sh
-npm install --save @unitoio/integration-sdk
+npm install --save @unito/integration-sdk
 ```
 
 ## Terms and Conditions

package/dist/src/errors.d.ts

@@ -1,3 +1,4 @@
+import * as HttpErrors from './httpErrors.js';
 export declare class NoIntegrationFoundError extends Error {
 }
 export declare class NoConfigurationFileError extends Error {
@@ -7,9 +8,9 @@ export declare class ConfigurationMalformed extends Error {
 export declare class InvalidHandler extends Error {
 }
 /**
- * Processes provider response codes and throw corresponding errors to be translated further in our responses
+ * Processes provider response codes and returns the corresponding errors to be translated further in our responses
  *
  * @param responseStatus the reponseStatus of the request. Any HTTP response code passed here will result in an error!
  * @param message The message returned by the provider
  */
-export declare function handleErrorResponse(responseStatus: number, message: string): void;
+export declare function buildHttpError(responseStatus: number, message: string): HttpErrors.HttpError;

package/dist/src/errors.js

@@ -8,32 +8,34 @@ export class ConfigurationMalformed extends Error {
 export class InvalidHandler extends Error {
 }
 /**
- * Processes provider response codes and throw corresponding errors to be translated further in our responses
+ * Processes provider response codes and returns the corresponding errors to be translated further in our responses
  *
  * @param responseStatus the reponseStatus of the request. Any HTTP response code passed here will result in an error!
  * @param message The message returned by the provider
  */
 // Keep in errors.ts instead of httpErrors.ts because we do not need to export it outside of the sdk
-export function handleErrorResponse(responseStatus, message) {
+export function buildHttpError(responseStatus, message) {
+    let httpError;
     if (responseStatus === 400) {
-        throw new HttpErrors.BadRequestError(message);
+        httpError = new HttpErrors.BadRequestError(message);
     }
     else if (responseStatus === 401 || responseStatus === 403) {
-        throw new HttpErrors.UnauthorizedError(message);
+        httpError = new HttpErrors.UnauthorizedError(message);
     }
     else if (responseStatus === 404) {
-        throw new HttpErrors.NotFoundError(message);
+        httpError = new HttpErrors.NotFoundError(message);
     }
     else if (responseStatus === 408) {
-        throw new HttpErrors.TimeoutError(message);
+        httpError = new HttpErrors.TimeoutError(message);
     }
     else if (responseStatus === 422) {
-        throw new HttpErrors.UnprocessableEntityError(message);
+        httpError = new HttpErrors.UnprocessableEntityError(message);
     }
     else if (responseStatus === 429) {
-        throw new HttpErrors.RateLimitExceededError(message);
+        httpError = new HttpErrors.RateLimitExceededError(message);
     }
     else {
-        throw new HttpErrors.HttpError(message, responseStatus);
+        httpError = new HttpErrors.HttpError(message, responseStatus);
     }
+    return httpError;
 }

package/dist/src/handler.js

@@ -9,6 +9,17 @@ function assertValidPath(path) {
         throw new InvalidHandler(`The provided path '${path}' is invalid. Paths must not end with a '/'.`);
     }
 }
+function assertValidConfiguration(path, pathWithIdentifier, handlers) {
+    if (path === pathWithIdentifier) {
+        const individualHandlers = ['getItem', 'updateItem', 'deleteItem'];
+        const collectionHandlers = ['getCollection', 'createItem'];
+        const hasIndividualHandlers = individualHandlers.some(handler => handler in handlers);
+        const hasCollectionHandlers = collectionHandlers.some(handler => handler in handlers);
+        if (hasIndividualHandlers && hasCollectionHandlers) {
+            throw new InvalidHandler(`The provided path '${path}' doesn't differentiate between individual and collection level operation, so you cannot define both. `);
+        }
+    }
+}
 function parsePath(path) {
     const pathParts = path.split('/');
     const lastPart = pathParts.at(-1);
@@ -60,9 +71,9 @@ export class Handler {
     pathWithIdentifier;
     handlers;
     constructor(inputPath, handlers) {
-        // Build paths.
         assertValidPath(inputPath);
         const { pathWithIdentifier, path } = parsePath(inputPath);
+        assertValidConfiguration(path, pathWithIdentifier, handlers);
         this.pathWithIdentifier = pathWithIdentifier;
         this.path = path;
         this.handlers = handlers;

package/dist/src/httpErrors.d.ts

@@ -20,3 +20,6 @@ export declare class UnprocessableEntityError extends HttpError {
 export declare class RateLimitExceededError extends HttpError {
     constructor(message?: string);
 }
+export declare class WouldExceedLimitError extends HttpError {
+    constructor(message?: string);
+}

package/dist/src/httpErrors.js

@@ -32,6 +32,11 @@ export class UnprocessableEntityError extends HttpError {
 }
 export class RateLimitExceededError extends HttpError {
     constructor(message) {
-        super(message || 'Unprocessable Entity', 429);
+        super(message || 'Rate Limit Exceeded', 429);
+    }
+}
+export class WouldExceedLimitError extends HttpError {
+    constructor(message) {
+        super(message || 'Would Exceed Limit', 429);
     }
 }

package/dist/src/index.d.ts

@@ -1,6 +1,7 @@
 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 { Provider, type Response as ProviderResponse, type RequestOptions as ProviderRequestOptions, type RateLimiter, } from './resources/provider.js';
+export type { Credentials } from './middlewares/credentials.js';
 export * as HttpErrors from './httpErrors.js';
 export * from './resources/context.js';

package/dist/src/index.js

@@ -1,6 +1,8 @@
+/* c8 ignore start */
 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';
+/* c8 ignore stop */

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

@@ -6,6 +6,9 @@ declare global {
         }
     }
 }
-export type Credentials = Record<string, unknown>;
+export type Credentials = {
+    accessToken?: string;
+    [keys: string]: unknown;
+};
 declare const middleware: (req: Request, res: Response, next: NextFunction) => void;
 export default middleware;

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

@@ -1,36 +1,59 @@
 import { Credentials } from '../middlewares/credentials.js';
+/**
+ * RateLimiter is a wrapper function that you can provide to limit the rate of calls to the provider based on the
+ * caller's credentials.
+ *
+ * When necessary, the Provider's Response headers can be inspected to update the rate limit before being returned.
+ *
+ * NOTE: make sure to return one of the supported HttpErrors from the SDK, otherwise the error will be translated to a
+ * generic server (500) error.
+ *
+ * @param context - The credentials of the caller.
+ * @param targetFunction - The function to call the provider.
+ * @returns The response from the provider.
+ * @throws RateLimitExceededError when the rate limit is exceeded.
+ * @throws WouldExceedRateLimitError when the next call would exceed the rate limit.
+ * @throws HttpError when the provider returns an error.
+ */
+export type RateLimiter = <T>(context: {
+    credentials: Credentials;
+}, targetFunction: () => Promise<Response<T>>) => Promise<Response<T>>;
 export interface RequestOptions {
     credentials: Credentials;
     queryParams?: {
         [key: string]: string;
     };
-    body?: Record<string, unknown>;
     additionnalheaders?: {
         [key: string]: string;
     };
 }
 export interface Response<T> {
-    data: T;
+    data: T | undefined;
+    status: number;
     headers: Headers;
 }
 export declare class Provider {
-    protected prepareRequest: ((context: {
+    protected rateLimiter: RateLimiter | undefined;
+    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;
+    };
+    /**
+     * Initialize 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.
+     */
     constructor(options: {
         prepareRequest: typeof Provider.prototype.prepareRequest;
+        rateLimiter?: RateLimiter;
     });
     get<T>(endpoint: string, options: RequestOptions): Promise<Response<T>>;
-    post<T>(endpoint: string, options: RequestOptions): Promise<Response<T>>;
-    patch<T>(endpoint: string, options: RequestOptions): Promise<Response<T>>;
+    post<T>(endpoint: string, body: Record<string, unknown>, options: RequestOptions): Promise<Response<T>>;
+    put<T>(endpoint: string, body: Record<string, unknown>, options: RequestOptions): Promise<Response<T>>;
+    patch<T>(endpoint: string, body: Record<string, unknown>, options: RequestOptions): Promise<Response<T>>;
+    delete<T>(endpoint: string, options: RequestOptions): Promise<Response<T>>;
     private fetchWrapper;
 }

package/dist/src/resources/provider.js

@@ -1,11 +1,19 @@
-import { handleErrorResponse as throwHttpError } from '../errors.js';
+import { buildHttpError } from '../errors.js';
 export class Provider {
-    prepareRequest = undefined;
+    rateLimiter = undefined;
+    prepareRequest;
+    /**
+     * Initialize 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.
+     */
     constructor(options) {
         this.prepareRequest = options.prepareRequest;
+        this.rateLimiter = options.rateLimiter;
     }
     async get(endpoint, options) {
-        return this.fetchWrapper(endpoint, {
+        return this.fetchWrapper(endpoint, null, {
             ...options,
             method: 'GET',
             defaultHeaders: {
@@ -14,8 +22,8 @@ export class Provider {
             },
         });
     }
-    async post(endpoint, options) {
-        return this.fetchWrapper(endpoint, {
+    async post(endpoint, body, options) {
+        return this.fetchWrapper(endpoint, body, {
             ...options,
             method: 'POST',
             defaultHeaders: {
@@ -24,8 +32,18 @@ export class Provider {
             },
         });
     }
-    async patch(endpoint, options) {
-        return this.fetchWrapper(endpoint, {
+    async put(endpoint, body, options) {
+        return this.fetchWrapper(endpoint, body, {
+            ...options,
+            method: 'PUT',
+            defaultHeaders: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Accept: 'application/json',
+            },
+        });
+    }
+    async patch(endpoint, body, options) {
+        return this.fetchWrapper(endpoint, body, {
             ...options,
             method: 'PATCH',
             defaultHeaders: {
@@ -34,43 +52,50 @@ export class Provider {
             },
         });
     }
-    async fetchWrapper(endpoint, options) {
-        if (!this.prepareRequest) {
-            throw new Error('Provider not initialized');
-        }
+    async delete(endpoint, options) {
+        return this.fetchWrapper(endpoint, null, {
+            ...options,
+            method: 'DELETE',
+            defaultHeaders: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Accept: 'application/json',
+            },
+        });
+    }
+    async fetchWrapper(endpoint, body, options) {
         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 = null;
-        if (options.body) {
+        let stringifiedBody = null;
+        if (body) {
             if (headers['Content-Type'] === 'application/x-www-form-urlencoded') {
-                body = new URLSearchParams(options.body).toString(); // this doesn't support objects!
+                stringifiedBody = new URLSearchParams(body).toString();
             }
             else if (headers['Content-Type'] === 'application/json') {
-                body = JSON.stringify(options.body);
+                stringifiedBody = JSON.stringify(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 };
+        const callToProvider = async () => {
+            const response = await fetch(absoluteUrl, {
+                method: options.method,
+                headers,
+                body: stringifiedBody,
+            });
+            if (response.status >= 400) {
+                const textResult = await response.text();
+                throw buildHttpError(response.status, textResult);
+            }
+            try {
+                const data = response.body ? await response.json() : undefined;
+                return { status: response.status, headers: response.headers, data };
+            }
+            catch {
+                throw buildHttpError(400, 'Invalid JSON response');
+            }
+        };
+        return this.rateLimiter ? this.rateLimiter(options, callToProvider) : callToProvider();
     }
 }

package/dist/test/errors.test.js

@@ -4,13 +4,12 @@ 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);
+        assert.ok(errors.buildHttpError(401, 'unauthorized') instanceof httpErrors.UnauthorizedError);
+        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(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/dist/test/handler.test.js

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import { afterEach, beforeEach, describe, it, mock } from 'node:test';
-import { Handler } from '../src/handler.js';
+import { Handler, } from '../src/handler.js';
 import { BadRequestError } from '../src/httpErrors.js';
 describe('Handler', () => {
     beforeEach(() => {
@@ -13,7 +13,7 @@ describe('Handler', () => {
     describe('constructor', () => {
         it('returns a Handler', () => {
             const itemHandler = new Handler('/', {});
-            assert.equal(itemHandler instanceof Handler, true);
+            assert.ok(itemHandler instanceof Handler);
         });
         it('validates path', () => {
             const paths = [
@@ -36,6 +36,30 @@ describe('Handler', () => {
                 }
             }
         });
+        it('validates configuration', () => {
+            const getItem = (() => { });
+            const updateItem = (() => { });
+            const deleteItem = (() => { });
+            const getCollection = (() => { });
+            const createItem = (() => { });
+            const paths = [
+                ['/foo', { getItem }, true],
+                ['/foo', { getCollection }, true],
+                ['/foo', { getItem, getCollection }, false],
+                ['/foo', { updateItem, createItem }, false],
+                ['/foo', { deleteItem, createItem }, false],
+                ['/foo/:bar', { getItem, getCollection }, true],
+                ['/foo/:bar', { getItem, updateItem, deleteItem, createItem, getCollection }, true],
+            ];
+            for (const [path, handlers, valid] of paths) {
+                if (valid) {
+                    assert.doesNotThrow(() => new Handler(path, handlers));
+                }
+                else {
+                    assert.throws(() => new Handler(path, handlers));
+                }
+            }
+        });
     });
     describe('generate', () => {
         async function executeHandler(handler, request = {}) {

package/dist/test/resources/provider.test.d.ts

@@ -0,0 +1 @@
+export {};