@unito/integration-sdk 0.1.11 → 1.0.1

package/src/resources/provider.ts

@@ -23,19 +23,46 @@ export type RateLimiter = <T>(
   targetFunction: () => Promise<Response<T>>,
 ) => Promise<Response<T>>;
 
-export interface RequestOptions {
+/**
+ * RequestOptions are the options passed to the Provider's call.
+ *
+ * @property credentials - The credentials to use for the call.
+ * @property logger - The logger to use during the call.
+ * @property queryParams - The query parameters to add when calling the provider.
+ * @property additionnalheaders - The headers to add when calling the provider.
+ */
+export type RequestOptions = {
   credentials: Credentials;
   logger: Logger;
+  signal: AbortSignal;
   queryParams?: { [key: string]: string };
   additionnalheaders?: { [key: string]: string };
-}
+};
 
-export interface Response<T> {
+/**
+ * Response object returned by the Provider's method.
+ *
+ * Contains;
+ * - the body typed as specified when calling the method
+ * - the status code of the response
+ * - the headers of the response.
+ */
+export type Response<T> = {
   body: T;
   status: number;
   headers: Headers;
-}
+};
 
+/**
+ * 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 {
   protected rateLimiter: RateLimiter | undefined = undefined;
   protected prepareRequest: (options: { credentials: Credentials; logger: Logger }) => {
@@ -44,7 +71,7 @@ export class Provider {
   };
 
   /**
-   * 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.
@@ -54,39 +81,85 @@ export class Provider {
     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.
+   */
   public async get<T>(endpoint: string, options: RequestOptions): Promise<Response<T>> {
     return this.fetchWrapper<T>(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.
+   */
   public async post<T>(endpoint: string, body: Record<string, unknown>, options: RequestOptions): Promise<Response<T>> {
     return this.fetchWrapper<T>(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.
+   */
   public async put<T>(endpoint: string, body: Record<string, unknown>, options: RequestOptions): Promise<Response<T>> {
     return this.fetchWrapper<T>(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.
+   */
   public async patch<T>(
     endpoint: string,
     body: Record<string, unknown>,
@@ -96,18 +169,28 @@ export class Provider {
       ...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.
+   */
   public async delete<T = undefined>(endpoint: string, options: RequestOptions): Promise<Response<T>> {
     return this.fetchWrapper<T>(endpoint, null, {
       ...options,
       method: 'DELETE',
       defaultHeaders: {
-        'Content-Type': 'application/x-www-form-urlencoded',
         Accept: 'application/json',
       },
     });
@@ -116,7 +199,7 @@ export class Provider {
   private async fetchWrapper<T>(
     endpoint: string,
     body: Record<string, unknown> | null,
-    options: RequestOptions & { defaultHeaders: { 'Content-Type': string; Accept: string }; method: string },
+    options: RequestOptions & { defaultHeaders: { 'Content-Type'?: string; Accept?: string }; method: string },
   ): Promise<Response<T>> {
     const { url: providerUrl, headers: providerHeaders } = this.prepareRequest(options);
 
@@ -139,11 +222,27 @@ export class Provider {
     }
 
     const callToProvider = async (): Promise<Response<T>> => {
-      const response = await fetch(absoluteUrl, {
-        method: options.method,
-        headers,
-        body: stringifiedBody,
-      });
+      let response: globalThis.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();

package/test/middlewares/signal.test.ts

@@ -0,0 +1,28 @@
+import express from 'express';
+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: string) => deadline } as unknown as express.Request;
+    const response = { locals: {} } as express.Response;
+
+    middleware(request, response, () => {});
+
+    assert.ok(response.locals.signal instanceof AbortSignal);
+    assert.equal(response.locals.signal.aborted, false);
+  });
+
+  it('defaults', () => {
+    const request = { header: (_key: string) => undefined } as unknown as express.Request;
+    const response = { locals: {} } as express.Response;
+
+    middleware(request, response, () => {});
+
+    assert.ok(response.locals.signal instanceof AbortSignal);
+    assert.equal(response.locals.signal.aborted, false);
+  });
+});

package/test/resources/provider.test.ts

@@ -2,6 +2,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', () => {
@@ -30,6 +31,7 @@ describe('Provider', () => {
     const actualResponse = await provider.get('/endpoint', {
       credentials: { apiKey: 'apikey#1111' },
       logger: logger,
+      signal: new AbortController().signal,
       additionnalheaders: { 'X-Additional-Header': 'value1' },
     });
 
@@ -39,8 +41,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',
@@ -67,7 +69,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' },
       },
     );
 
@@ -77,6 +80,7 @@ describe('Provider', () => {
       {
         method: 'POST',
         body: 'data=createdItemInfo',
+        signal: new AbortController().signal,
         headers: {
           'Content-Type': 'application/x-www-form-urlencoded',
           Accept: 'application/json',
@@ -106,6 +110,7 @@ describe('Provider', () => {
       {
         credentials: { apiKey: 'apikey#1111' },
         logger: logger,
+        signal: new AbortController().signal,
         additionnalheaders: { 'X-Additional-Header': 'value1', 'Content-Type': 'application/json' },
       },
     );
@@ -116,6 +121,7 @@ describe('Provider', () => {
       {
         method: 'PUT',
         body: JSON.stringify({ data: 'updatedItemInfo' }),
+        signal: new AbortController().signal,
         headers: {
           'Content-Type': 'application/json',
           Accept: 'application/json',
@@ -144,8 +150,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' },
       },
     );
 
@@ -155,6 +162,7 @@ describe('Provider', () => {
       {
         method: 'PATCH',
         body: JSON.stringify({ data: 'updatedItemInfo' }),
+        signal: new AbortController().signal,
         headers: {
           'Content-Type': 'application/json',
           Accept: 'application/json',
@@ -178,7 +186,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);
@@ -187,8 +196,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',
@@ -225,7 +234,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);
@@ -238,8 +248,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',
@@ -257,41 +267,132 @@ describe('Provider', () => {
 
     context.mock.method(global, 'fetch', () => Promise.resolve(response));
 
-    assert.rejects(() =>
-      provider.get('/endpoint/123', {
+    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', {
+    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', {
+    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');
   });
 });