@unito/integration-sdk 0.1.11 → 1.0.0

package/dist/src/resources/provider.js

@@ -1,9 +1,19 @@
 import { buildHttpError } from '../errors.js';
+/**
+ * The Provider class is a wrapper around the fetch function to call a provider's HTTP API.
+ *
+ * Defines methods for the following HTTP methods: GET, POST, PUT, PATCH, DELETE.
+ *
+ * Needs to be initialized with a prepareRequest function to define the Provider's base URL and any specific headers to
+ * add to the requests, and can also be configured to use a provided rate limiting function.
+ * @see {@link RateLimiter}
+ * @see {@link prepareRequest}
+ */
 export class Provider {
     rateLimiter = undefined;
     prepareRequest;
     /**
-     * Initialize a Provider with the given options.
+     * Initializes 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.
@@ -12,52 +22,108 @@ export class Provider {
         this.prepareRequest = options.prepareRequest;
         this.rateLimiter = options.rateLimiter;
     }
+    /**
+     * Performs a GET request to the provider.
+     *
+     * Uses the prepareRequest function to get the base URL and any specific headers to add to the request and by default
+     * adds the following headers:
+     * - Accept: application/json
+     *
+     * @param endpoint Path to the provider's resource. Will be added to the URL returned by the prepareRequest function.
+     * @param options RequestOptions used to adjust the call made to the provider (use to override default headers).
+     * @returns The {@link Response} extracted from the provider.
+     */
     async get(endpoint, options) {
         return this.fetchWrapper(endpoint, null, {
             ...options,
             method: 'GET',
             defaultHeaders: {
-                'Content-Type': 'application/json',
                 Accept: 'application/json',
             },
         });
     }
+    /**
+     * Performs a POST request to the provider.
+     *
+     * Uses the prepareRequest function to get the base URL and any specific headers to add to the request and by default
+     * adds the following headers:
+     * - Content-Type: application/json',
+     * - Accept: application/json
+     *
+     * @param endpoint Path to the provider's resource. Will be added to the URL returned by the prepareRequest function.
+     * @param options RequestOptions used to adjust the call made to the provider (use to override default headers).
+     * @returns The {@link Response} extracted from the provider.
+     */
     async post(endpoint, body, options) {
         return this.fetchWrapper(endpoint, body, {
             ...options,
             method: 'POST',
             defaultHeaders: {
-                'Content-Type': 'application/x-www-form-urlencoded',
+                'Content-Type': 'application/json',
                 Accept: 'application/json',
             },
         });
     }
+    /**
+     * Performs a PUT request to the provider.
+     *
+     * Uses the prepareRequest function to get the base URL and any specific headers to add to the request and by default
+     * adds the following headers:
+     * - Content-Type: application/json',
+     * - Accept: application/json
+     *
+     * @param endpoint Path to the provider's resource. Will be added to the URL returned by the prepareRequest function.
+     * @param options RequestOptions used to adjust the call made to the provider (use to override default headers).
+     * @returns The {@link Response} extracted from the provider.
+     */
     async put(endpoint, body, options) {
         return this.fetchWrapper(endpoint, body, {
             ...options,
             method: 'PUT',
             defaultHeaders: {
-                'Content-Type': 'application/x-www-form-urlencoded',
+                'Content-Type': 'application/json',
                 Accept: 'application/json',
             },
         });
     }
+    /**
+     * Performs a PATCH request to the provider.
+     *
+     * Uses the prepareRequest function to get the base URL and any specific headers to add to the request and by default
+     * adds the following headers:
+     * - Content-Type: application/json',
+     * - Accept: application/json
+     *
+     * @param endpoint Path to the provider's resource. Will be added to the URL returned by the prepareRequest function.
+     * @param options RequestOptions used to adjust the call made to the provider (use to override default headers).
+     * @returns The {@link Response} extracted from the provider.
+     */
     async patch(endpoint, body, options) {
         return this.fetchWrapper(endpoint, body, {
             ...options,
             method: 'PATCH',
             defaultHeaders: {
-                'Content-Type': 'application/x-www-form-urlencoded',
+                'Content-Type': 'application/json',
                 Accept: 'application/json',
             },
         });
     }
+    /**
+     * Performs a DELETE request to the provider.
+     *
+     * Uses the prepareRequest function to get the base URL and any specific headers to add to the request and by default
+     * adds the following headers:
+     * - Accept: application/json
+     *
+     * @param endpoint Path to the provider's resource. Will be added to the URL returned by the prepareRequest function.
+     * @param options RequestOptions used to adjust the call made to the provider (use to override default headers).
+     * @returns The {@link Response} extracted from the provider.
+     */
     async delete(endpoint, options) {
         return this.fetchWrapper(endpoint, null, {
             ...options,
             method: 'DELETE',
             defaultHeaders: {
-                'Content-Type': 'application/x-www-form-urlencoded',
                 Accept: 'application/json',
             },
         });
@@ -79,11 +145,26 @@ export class Provider {
             }
         }
         const callToProvider = async () => {
-            const response = await fetch(absoluteUrl, {
-                method: options.method,
-                headers,
-                body: stringifiedBody,
-            });
+            let response;
+            try {
+                response = await fetch(absoluteUrl, {
+                    method: options.method,
+                    signal: options.signal,
+                    headers,
+                    body: stringifiedBody,
+                });
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    switch (error.name) {
+                        case 'AbortError':
+                            throw buildHttpError(408, 'Request aborted');
+                        case 'TimeoutError':
+                            throw buildHttpError(408, 'Request timeout');
+                    }
+                }
+                throw buildHttpError(500, `Unexpected error while calling the provider: "${error}"`);
+            }
             if (response.status >= 400) {
                 const textResult = await response.text();
                 throw buildHttpError(response.status, textResult);

package/dist/test/middlewares/signal.test.d.ts

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

package/dist/test/middlewares/signal.test.js

@@ -0,0 +1,20 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import middleware from '../../src/middlewares/signal.js';
+describe('signal middleware', () => {
+    it('uses header', () => {
+        const deadline = Math.floor((Date.now() + 5000) / 1000);
+        const request = { header: (_key) => deadline };
+        const response = { locals: {} };
+        middleware(request, response, () => { });
+        assert.ok(response.locals.signal instanceof AbortSignal);
+        assert.equal(response.locals.signal.aborted, false);
+    });
+    it('defaults', () => {
+        const request = { header: (_key) => undefined };
+        const response = { locals: {} };
+        middleware(request, response, () => { });
+        assert.ok(response.locals.signal instanceof AbortSignal);
+        assert.equal(response.locals.signal.aborted, false);
+    });
+});

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

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import { Provider } from '../../src/resources/provider.js';
+import * as HttpErrors from '../../src/httpErrors.js';
 import Logger from '../../src/resources/logger.js';
 describe('Provider', () => {
     const provider = new Provider({
@@ -24,6 +25,7 @@ describe('Provider', () => {
         const actualResponse = await provider.get('/endpoint', {
             credentials: { apiKey: 'apikey#1111' },
             logger: logger,
+            signal: new AbortController().signal,
             additionnalheaders: { 'X-Additional-Header': 'value1' },
         });
         assert.equal(fetchMock.mock.calls.length, 1);
@@ -32,8 +34,8 @@ describe('Provider', () => {
             {
                 method: 'GET',
                 body: null,
+                signal: new AbortController().signal,
                 headers: {
-                    'Content-Type': 'application/json',
                     Accept: 'application/json',
                     'X-Custom-Provider-Header': 'value',
                     'X-Provider-Credential-Header': 'apikey#1111',
@@ -54,7 +56,8 @@ describe('Provider', () => {
         }, {
             credentials: { apiKey: 'apikey#1111' },
             logger: logger,
-            additionnalheaders: { 'X-Additional-Header': 'value1' },
+            signal: new AbortController().signal,
+            additionnalheaders: { 'Content-Type': 'application/x-www-form-urlencoded', 'X-Additional-Header': 'value1' },
         });
         assert.equal(fetchMock.mock.calls.length, 1);
         assert.deepEqual(fetchMock.mock.calls[0]?.arguments, [
@@ -62,6 +65,7 @@ describe('Provider', () => {
             {
                 method: 'POST',
                 body: 'data=createdItemInfo',
+                signal: new AbortController().signal,
                 headers: {
                     'Content-Type': 'application/x-www-form-urlencoded',
                     Accept: 'application/json',
@@ -85,6 +89,7 @@ describe('Provider', () => {
         }, {
             credentials: { apiKey: 'apikey#1111' },
             logger: logger,
+            signal: new AbortController().signal,
             additionnalheaders: { 'X-Additional-Header': 'value1', 'Content-Type': 'application/json' },
         });
         assert.equal(fetchMock.mock.calls.length, 1);
@@ -93,6 +98,7 @@ describe('Provider', () => {
             {
                 method: 'PUT',
                 body: JSON.stringify({ data: 'updatedItemInfo' }),
+                signal: new AbortController().signal,
                 headers: {
                     'Content-Type': 'application/json',
                     Accept: 'application/json',
@@ -115,8 +121,9 @@ describe('Provider', () => {
         }, {
             credentials: { apiKey: 'apikey#1111' },
             logger: logger,
+            signal: new AbortController().signal,
             queryParams: { param1: 'value1', param2: 'value2' },
-            additionnalheaders: { 'X-Additional-Header': 'value1', 'Content-Type': 'application/json' },
+            additionnalheaders: { 'X-Additional-Header': 'value1' },
         });
         assert.equal(fetchMock.mock.calls.length, 1);
         assert.deepEqual(fetchMock.mock.calls[0]?.arguments, [
@@ -124,6 +131,7 @@ describe('Provider', () => {
             {
                 method: 'PATCH',
                 body: JSON.stringify({ data: 'updatedItemInfo' }),
+                signal: new AbortController().signal,
                 headers: {
                     'Content-Type': 'application/json',
                     Accept: 'application/json',
@@ -144,7 +152,8 @@ describe('Provider', () => {
         const actualResponse = await provider.delete('/endpoint/123', {
             credentials: { apiKey: 'apikey#1111' },
             logger: logger,
-            additionnalheaders: { 'X-Additional-Header': 'value1', 'Content-Type': 'application/json' },
+            signal: new AbortController().signal,
+            additionnalheaders: { 'X-Additional-Header': 'value1' },
         });
         assert.equal(fetchMock.mock.calls.length, 1);
         assert.deepEqual(fetchMock.mock.calls[0]?.arguments, [
@@ -152,8 +161,8 @@ describe('Provider', () => {
             {
                 method: 'DELETE',
                 body: null,
+                signal: new AbortController().signal,
                 headers: {
-                    'Content-Type': 'application/json',
                     Accept: 'application/json',
                     'X-Custom-Provider-Header': 'value',
                     'X-Provider-Credential-Header': 'apikey#1111',
@@ -185,7 +194,8 @@ describe('Provider', () => {
         const options = {
             credentials: { apiKey: 'apikey#1111' },
             logger: logger,
-            additionnalheaders: { 'X-Additional-Header': 'value1', 'Content-Type': 'application/json' },
+            signal: new AbortController().signal,
+            additionnalheaders: { 'X-Additional-Header': 'value1' },
         };
         const actualResponse = await rateLimitedProvider.delete('/endpoint/123', options);
         assert.equal(mockRateLimiter.mock.calls.length, 1);
@@ -196,8 +206,8 @@ describe('Provider', () => {
             {
                 method: 'DELETE',
                 body: null,
+                signal: new AbortController().signal,
                 headers: {
-                    'Content-Type': 'application/json',
                     Accept: 'application/json',
                     'X-Custom-Provider-Header': 'value',
                     'X-Provider-Credential-Header': 'apikey#1111',
@@ -212,29 +222,114 @@ describe('Provider', () => {
             status: 200,
         });
         context.mock.method(global, 'fetch', () => Promise.resolve(response));
-        assert.rejects(() => provider.get('/endpoint/123', {
-            credentials: { apiKey: 'apikey#1111' },
-            logger: logger,
-        }));
+        let error;
+        try {
+            await provider.get('/endpoint/123', {
+                credentials: { apiKey: 'apikey#1111' },
+                logger: logger,
+                signal: new AbortController().signal,
+            });
+        }
+        catch (e) {
+            error = e;
+        }
+        assert.ok(error instanceof HttpErrors.BadRequestError);
+        assert.equal(error.message, 'Invalid JSON response');
     });
     it('throws on status 400', async (context) => {
-        const response = new Response(undefined, {
+        const response = new Response('response body', {
             status: 400,
         });
         context.mock.method(global, 'fetch', () => Promise.resolve(response));
-        assert.rejects(() => provider.get('/endpoint/123', {
-            credentials: { apiKey: 'apikey#1111' },
-            logger: logger,
-        }));
+        let error;
+        try {
+            await provider.get('/endpoint/123', {
+                credentials: { apiKey: 'apikey#1111' },
+                signal: new AbortController().signal,
+                logger: logger,
+            });
+        }
+        catch (e) {
+            error = e;
+        }
+        assert.ok(error instanceof HttpErrors.BadRequestError);
+        assert.equal(error.message, 'response body');
+    });
+    it('throws on timeout', async (context) => {
+        context.mock.method(global, 'fetch', () => {
+            const error = new Error();
+            error.name = 'TimeoutError';
+            throw error;
+        });
+        let error;
+        try {
+            await provider.get('/endpoint/123', {
+                credentials: { apiKey: 'apikey#1111' },
+                signal: new AbortController().signal,
+                logger: logger,
+            });
+        }
+        catch (e) {
+            error = e;
+        }
+        assert.ok(error instanceof HttpErrors.TimeoutError);
+        assert.equal(error.message, 'Request timeout');
+    });
+    it('throws on abort', async (context) => {
+        context.mock.method(global, 'fetch', () => {
+            const error = new Error();
+            error.name = 'AbortError';
+            throw error;
+        });
+        let error;
+        try {
+            await provider.get('/endpoint/123', {
+                credentials: { apiKey: 'apikey#1111' },
+                signal: new AbortController().signal,
+                logger: logger,
+            });
+        }
+        catch (e) {
+            error = e;
+        }
+        assert.ok(error instanceof HttpErrors.TimeoutError);
+        assert.equal(error.message, 'Request aborted');
+    });
+    it('throws on unknown errors', async (context) => {
+        context.mock.method(global, 'fetch', () => {
+            throw new Error('foo');
+        });
+        let error;
+        try {
+            await provider.get('/endpoint/123', {
+                credentials: { apiKey: 'apikey#1111' },
+                signal: new AbortController().signal,
+                logger: logger,
+            });
+        }
+        catch (e) {
+            error = e;
+        }
+        assert.ok(error instanceof HttpErrors.HttpError);
+        assert.equal(error.message, 'Unexpected error while calling the provider: "Error: foo"');
     });
     it('throws on status 429', async (context) => {
-        const response = new Response(undefined, {
+        const response = new Response('response body', {
             status: 429,
         });
         context.mock.method(global, 'fetch', () => Promise.resolve(response));
-        assert.rejects(() => provider.get('/endpoint/123', {
-            credentials: { apiKey: 'apikey#1111' },
-            logger: logger,
-        }));
+        let error;
+        try {
+            await provider.get('/endpoint/123', {
+                credentials: { apiKey: 'apikey#1111' },
+                signal: new AbortController().signal,
+                logger: logger,
+            });
+        }
+        catch (e) {
+            error = e;
+        }
+        assert.ok(error instanceof HttpErrors.RateLimitExceededError);
+        assert.equal(error.message, 'response body');
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unito/integration-sdk",
-  "version": "0.1.11",
+  "version": "1.0.0",
   "description": "Integration SDK",
   "type": "module",
   "types": "dist/src/index.d.ts",
@@ -36,8 +36,8 @@
     "@types/express": "4.x",
     "@types/node": "20.x",
     "@types/uuid": "9.x",
-    "@typescript-eslint/eslint-plugin": "6.x",
-    "@typescript-eslint/parser": "6.x",
+    "@typescript-eslint/eslint-plugin": "7.x",
+    "@typescript-eslint/parser": "7.x",
     "c8": "9.x",
     "eslint": "8.x",
     "prettier": "3.x",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@unito/integration-api": "0.x",
-    "cachette": "1.x",
+    "cachette": "2.x",
     "express": "^5.0.0-beta.1",
     "uuid": "9.x"
   },

package/src/handler.ts

@@ -16,31 +16,48 @@ import {
 
 /**
  * Handler called to get an individual item.
+ *
+ * @param context {@link GetItemContext}
+ * @returns The requested {@link API.Item}.
  */
 export type GetItemHandler = (context: GetItemContext<any, any>) => Promise<API.Item>;
 
 /**
  * Handler called to retrieve a collection of items.
+ *
+ * @param context {@link GetCollectionContext}
+ * @return An {@link API.Collection} containing requested items and a link to the next page, if applicable.
  */
 export type GetCollectionHandler = (context: GetCollectionContext<any, any>) => Promise<API.Collection>;
 
 /**
  * Handler called to create an item.
+ *
+ * @param context {@link CreateItemContext}
+ * @returns An {@link API.ItemSummary} containing a path to the created item.
  */
 export type CreateItemHandler = (context: CreateItemContext<any, any, any>) => Promise<API.ItemSummary>;
 
 /**
  * Handler called to update an item.
+ *
+ * @param context {@link UpdateItemContext}
+ * @returns The updated {@link API.Item}.
  */
 export type UpdateItemHandler = (context: UpdateItemContext<any, any, any>) => Promise<API.Item>;
 
 /**
  * Handler called to delete an item.
+ *
+ * @param context {@link DeleteItemContext}
  */
 export type DeleteItemHandler = (context: DeleteItemContext<any, any>) => Promise<void>;
 
 /**
  * Handler called to retrieve the account details associated with the credentials.
+ *
+ * @param context {@link GetCredentialAccountContext}
+ * @returns The {@link API.CredentialAccount} associated with the credentials.
  */
 export type GetCredentialAccountHandler = (
   context: GetCredentialAccountContext<any, any>,
@@ -48,6 +65,9 @@ export type GetCredentialAccountHandler = (
 
 /**
  * Handler called to parse the content of an incoming webhook.
+ *
+ * @param context {@link ParseWebhooksContext}
+ * @returns The parsed content of the webhook as a {@link API.WebhookParseResponsePayload}.
  */
 export type ParseWebhooksHandler = (
   context: ParseWebhooksContext<any, any, any>,
@@ -55,6 +75,8 @@ export type ParseWebhooksHandler = (
 
 /**
  * Handler called to subscribe or unsubscribe to a particular webhook.
+ *
+ * @param context {@link UpdateWebhookSubscriptionsContext}
  */
 export type UpdateWebhookSubscriptionsHandler = (
   context: UpdateWebhookSubscriptionsContext<any, any, any>,
@@ -62,11 +84,28 @@ export type UpdateWebhookSubscriptionsHandler = (
 
 /**
  * Handler called to acknowledge the reception of a webhook.
+ *
+ * @param context {@link AcknowledgeWebhooksContext}
+ * @returns The {@link API.WebhookAcknowledgeResponsePayload} to be sent back to the webhook provider.
  */
 export type AcknowledgeWebhooksHandler = (
   context: AcknowledgeWebhooksContext<any, any, any>,
 ) => Promise<API.WebhookAcknowledgeResponsePayload>;
 
+/**
+ * Defines the implementation of the operations available for a given `Item`.
+ * - In some cases (e.g. defining the `root` or {@link https://dev.unito.io/docs/connectors/apiSpecification/credentialAccount | me}
+ *   handlers), only a {@link GetItemHandler | getItem} handler is necessary.
+ * - In most cases, you will want to define {@link GetCollectionHandler | getCollection},
+ *   most likely {@link GetItemHandler | getItem}, and any other handlers relevant to the item.
+ *
+ * The `ItemHandlers` object can contain any of the following:
+ * - {@link GetItemHandler | getItem}: A handler called to get an individual item.
+ * - {@link GetCollectionHandler | getCollection}: A handler called to retrieve a collection of items.
+ * - {@link CreateItemHandler | createItem}: A handler called to create an item.
+ * - {@link UpdateItemHandler | updateItem}: A handler called to update an item.
+ * - {@link DeleteItemHandler | deleteItem}: A handler called to delete an item.
+ */
 export type ItemHandlers = {
   getItem?: GetItemHandler;
   getCollection?: GetCollectionHandler;
@@ -234,6 +273,7 @@ export class Handler {
           selects: res.locals.selects,
           filters: res.locals.filters,
           logger: res.locals.logger,
+          signal: res.locals.signal,
           params: req.params,
           query: req.query,
         });
@@ -259,6 +299,7 @@ export class Handler {
           secrets: res.locals.secrets,
           body: req.body,
           logger: res.locals.logger,
+          signal: res.locals.signal,
           params: req.params,
           query: req.query,
         });
@@ -281,6 +322,7 @@ export class Handler {
           credentials: res.locals.credentials,
           secrets: res.locals.secrets,
           logger: res.locals.logger,
+          signal: res.locals.signal,
           params: req.params,
           query: req.query,
         });
@@ -306,6 +348,7 @@ export class Handler {
           secrets: res.locals.secrets,
           body: req.body,
           logger: res.locals.logger,
+          signal: res.locals.signal,
           params: req.params,
           query: req.query,
         });
@@ -328,6 +371,7 @@ export class Handler {
           credentials: res.locals.credentials,
           secrets: res.locals.secrets,
           logger: res.locals.logger,
+          signal: res.locals.signal,
           params: req.params,
           query: req.query,
         });
@@ -350,6 +394,7 @@ export class Handler {
           credentials: res.locals.credentials,
           secrets: res.locals.secrets,
           logger: res.locals.logger,
+          signal: res.locals.signal,
           params: req.params,
           query: req.query,
         });
@@ -369,6 +414,7 @@ export class Handler {
         const response = await handler({
           secrets: res.locals.secrets,
           logger: res.locals.logger,
+          signal: res.locals.signal,
           params: req.params,
           query: req.query,
           body: req.body,
@@ -389,6 +435,7 @@ export class Handler {
         const response = await handler({
           secrets: res.locals.secrets,
           logger: res.locals.logger,
+          signal: res.locals.signal,
           params: req.params,
           query: req.query,
           body: req.body,
@@ -415,6 +462,7 @@ export class Handler {
           credentials: res.locals.credentials,
           body: req.body,
           logger: res.locals.logger,
+          signal: res.locals.signal,
           params: req.params,
           query: req.query,
         });