@unito/integration-sdk 1.0.9 → 1.0.11

package/dist/src/index.cjs

@@ -953,22 +953,46 @@ class Integration {
  * 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.
+ * add to the requests, can also be configured to use a provided rate limiting function, and custom error handler.
+ *
+ * Multiple `Provider` instances can be created, with different configurations to call different providers APIs with
+ * different rateLimiting functions, as needed.
  * @see {@link RateLimiter}
  * @see {@link prepareRequest}
+ * @see {@link customErrorHandler}
  */
 class Provider {
+    /**
+     * The Rate Limiter function to use to limit the rate of calls made to the provider based on the caller's credentials.
+     */
     rateLimiter = undefined;
+    /**
+     * Function called before each request to define the Provider's base URL and any specific headers to add to the requests.
+     *
+     * This is applied at large to all requests made to the provider. If you need to add specific headers to a single request,
+     * pass it through the RequestOptions object when calling the Provider's methods.
+     */
     prepareRequest;
+    /**
+     * (Optional) Custom error handler to handle specific errors returned by the provider.
+     *
+     * If provided, this method should only care about custom errors returned by the provider and return the corresponding
+     * HttpError from the SDK. If the error encountered is a standard error, it should return undefined and let the SDK handle it.
+     *
+     * @see buildHttpError for the list of standard errors the SDK can handle.
+     */
+    customErrorHandler;
     /**
      * 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.
+     * @property customErrorHandler - function to handle specific errors returned by the provider.
      */
     constructor(options) {
         this.prepareRequest = options.prepareRequest;
         this.rateLimiter = options.rateLimiter;
+        this.customErrorHandler = options.customErrorHandler;
     }
     /**
      * Performs a GET request to the provider.
@@ -1132,16 +1156,16 @@ class Provider {
                 if (error instanceof Error) {
                     switch (error.name) {
                         case 'AbortError':
-                            throw buildHttpError(408, 'Request aborted');
+                            throw this.handleError(408, 'Request aborted');
                         case 'TimeoutError':
-                            throw buildHttpError(408, 'Request timeout');
+                            throw this.handleError(408, 'Request timeout');
                     }
                 }
-                throw buildHttpError(500, `Unexpected error while calling the provider: "${error}"`);
+                throw this.handleError(500, `Unexpected error while calling the provider: "${error}"`);
             }
             if (response.status >= 400) {
                 const textResult = await response.text();
-                throw buildHttpError(response.status, textResult);
+                throw this.handleError(response.status, textResult);
             }
             const responseContentType = response.headers.get('content-type');
             let body;
@@ -1150,13 +1174,13 @@ class Provider {
                 // (Provider's response Content-Type might be more specific, e.g. application/json;charset=utf-8)
                 // Default to application/json if no Content-Type header is provided
                 if (responseContentType && !responseContentType.includes('application/json')) {
-                    throw buildHttpError(500, `Unsupported content-type. Expected 'application/json', got '${responseContentType}'`);
+                    throw this.handleError(500, `Unsupported content-type. Expected 'application/json', got '${responseContentType}'`);
                 }
                 try {
                     body = response.body ? await response.json() : undefined;
                 }
                 catch (err) {
-                    throw buildHttpError(500, `Invalid JSON response`);
+                    throw this.handleError(500, `Invalid JSON response`);
                 }
             }
             else if (headers.Accept == 'application/octet-stream') {
@@ -1164,12 +1188,16 @@ class Provider {
                 body = response.body;
             }
             else {
-                throw buildHttpError(500, 'Unsupported accept header');
+                throw this.handleError(500, 'Unsupported accept header');
             }
             return { status: response.status, headers: response.headers, body };
         };
         return this.rateLimiter ? this.rateLimiter(options, callToProvider) : callToProvider();
     }
+    handleError(responseStatus, message) {
+        const customError = this.customErrorHandler?.(responseStatus, message);
+        return customError ?? buildHttpError(responseStatus, message);
+    }
 }
 
 /**

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

@@ -1,3 +1,4 @@
+import * as HttpErrors from '../httpErrors.js';
 import { Credentials } from '../middlewares/credentials.js';
 import Logger from '../resources/logger.js';
 /**
@@ -58,12 +59,25 @@ export type Response<T> = {
  * 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.
+ * add to the requests, can also be configured to use a provided rate limiting function, and custom error handler.
+ *
+ * Multiple `Provider` instances can be created, with different configurations to call different providers APIs with
+ * different rateLimiting functions, as needed.
  * @see {@link RateLimiter}
  * @see {@link prepareRequest}
+ * @see {@link customErrorHandler}
  */
 export declare class Provider {
+    /**
+     * The Rate Limiter function to use to limit the rate of calls made to the provider based on the caller's credentials.
+     */
     protected rateLimiter: RateLimiter | undefined;
+    /**
+     * Function called before each request to define the Provider's base URL and any specific headers to add to the requests.
+     *
+     * This is applied at large to all requests made to the provider. If you need to add specific headers to a single request,
+     * pass it through the RequestOptions object when calling the Provider's methods.
+     */
     protected prepareRequest: (options: {
         credentials: Credentials;
         logger: Logger;
@@ -71,15 +85,26 @@ export declare class Provider {
         url: string;
         headers: Record<string, string>;
     };
+    /**
+     * (Optional) Custom error handler to handle specific errors returned by the provider.
+     *
+     * If provided, this method should only care about custom errors returned by the provider and return the corresponding
+     * HttpError from the SDK. If the error encountered is a standard error, it should return undefined and let the SDK handle it.
+     *
+     * @see buildHttpError for the list of standard errors the SDK can handle.
+     */
+    protected customErrorHandler: ((responseStatus: number, message: string) => HttpErrors.HttpError | undefined) | undefined;
     /**
      * 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.
+     * @property customErrorHandler - function to handle specific errors returned by the provider.
      */
     constructor(options: {
         prepareRequest: typeof Provider.prototype.prepareRequest;
-        rateLimiter?: RateLimiter;
+        rateLimiter?: RateLimiter | undefined;
+        customErrorHandler?: typeof Provider.prototype.customErrorHandler;
     });
     /**
      * Performs a GET request to the provider.
@@ -157,4 +182,5 @@ export declare class Provider {
      */
     delete<T = undefined>(endpoint: string, options: RequestOptions): Promise<Response<T>>;
     private fetchWrapper;
+    private handleError;
 }

package/dist/src/resources/provider.js

@@ -5,22 +5,46 @@ import { buildHttpError } from '../errors.js';
  * 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.
+ * add to the requests, can also be configured to use a provided rate limiting function, and custom error handler.
+ *
+ * Multiple `Provider` instances can be created, with different configurations to call different providers APIs with
+ * different rateLimiting functions, as needed.
  * @see {@link RateLimiter}
  * @see {@link prepareRequest}
+ * @see {@link customErrorHandler}
  */
 export class Provider {
+    /**
+     * The Rate Limiter function to use to limit the rate of calls made to the provider based on the caller's credentials.
+     */
     rateLimiter = undefined;
+    /**
+     * Function called before each request to define the Provider's base URL and any specific headers to add to the requests.
+     *
+     * This is applied at large to all requests made to the provider. If you need to add specific headers to a single request,
+     * pass it through the RequestOptions object when calling the Provider's methods.
+     */
     prepareRequest;
+    /**
+     * (Optional) Custom error handler to handle specific errors returned by the provider.
+     *
+     * If provided, this method should only care about custom errors returned by the provider and return the corresponding
+     * HttpError from the SDK. If the error encountered is a standard error, it should return undefined and let the SDK handle it.
+     *
+     * @see buildHttpError for the list of standard errors the SDK can handle.
+     */
+    customErrorHandler;
     /**
      * 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.
+     * @property customErrorHandler - function to handle specific errors returned by the provider.
      */
     constructor(options) {
         this.prepareRequest = options.prepareRequest;
         this.rateLimiter = options.rateLimiter;
+        this.customErrorHandler = options.customErrorHandler;
     }
     /**
      * Performs a GET request to the provider.
@@ -184,16 +208,16 @@ export class Provider {
                 if (error instanceof Error) {
                     switch (error.name) {
                         case 'AbortError':
-                            throw buildHttpError(408, 'Request aborted');
+                            throw this.handleError(408, 'Request aborted');
                         case 'TimeoutError':
-                            throw buildHttpError(408, 'Request timeout');
+                            throw this.handleError(408, 'Request timeout');
                     }
                 }
-                throw buildHttpError(500, `Unexpected error while calling the provider: "${error}"`);
+                throw this.handleError(500, `Unexpected error while calling the provider: "${error}"`);
             }
             if (response.status >= 400) {
                 const textResult = await response.text();
-                throw buildHttpError(response.status, textResult);
+                throw this.handleError(response.status, textResult);
             }
             const responseContentType = response.headers.get('content-type');
             let body;
@@ -202,13 +226,13 @@ export class Provider {
                 // (Provider's response Content-Type might be more specific, e.g. application/json;charset=utf-8)
                 // Default to application/json if no Content-Type header is provided
                 if (responseContentType && !responseContentType.includes('application/json')) {
-                    throw buildHttpError(500, `Unsupported content-type. Expected 'application/json', got '${responseContentType}'`);
+                    throw this.handleError(500, `Unsupported content-type. Expected 'application/json', got '${responseContentType}'`);
                 }
                 try {
                     body = response.body ? await response.json() : undefined;
                 }
                 catch (err) {
-                    throw buildHttpError(500, `Invalid JSON response`);
+                    throw this.handleError(500, `Invalid JSON response`);
                 }
             }
             else if (headers.Accept == 'application/octet-stream') {
@@ -216,10 +240,14 @@ export class Provider {
                 body = response.body;
             }
             else {
-                throw buildHttpError(500, 'Unsupported accept header');
+                throw this.handleError(500, 'Unsupported accept header');
             }
             return { status: response.status, headers: response.headers, body };
         };
         return this.rateLimiter ? this.rateLimiter(options, callToProvider) : callToProvider();
     }
+    handleError(responseStatus, message) {
+        const customError = this.customErrorHandler?.(responseStatus, message);
+        return customError ?? buildHttpError(responseStatus, message);
+    }
 }

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

@@ -249,6 +249,78 @@ describe('Provider', () => {
         ]);
         assert.deepEqual(actualResponse, { status: 204, headers: response.headers, body: undefined });
     });
+    it('uses custom error handler if provided', async (context) => {
+        const rateLimitedProvider = new Provider({
+            prepareRequest: requestOptions => {
+                return {
+                    url: `www.${requestOptions.credentials.domain ?? 'myApi.com'}`,
+                    headers: {
+                        'X-Custom-Provider-Header': 'value',
+                        'X-Provider-Credential-Header': requestOptions.credentials.apiKey,
+                    },
+                };
+            },
+            rateLimiter: undefined,
+            // Change from normal behavior 400 -> 429
+            customErrorHandler: (responseStatus) => responseStatus === 400 ? new HttpErrors.RateLimitExceededError('Weird provider behavior') : undefined,
+        });
+        const response = new Response(undefined, {
+            status: 400,
+            headers: { 'Content-Type': 'application/json' },
+        });
+        context.mock.method(global, 'fetch', () => Promise.resolve(response));
+        const options = {
+            credentials: { apiKey: 'apikey#1111' },
+            logger: logger,
+            signal: new AbortController().signal,
+            additionnalheaders: { 'X-Additional-Header': 'value1' },
+        };
+        let error;
+        try {
+            await rateLimitedProvider.delete('/endpoint/123', options);
+        }
+        catch (e) {
+            error = e;
+        }
+        assert.ok(error instanceof HttpErrors.HttpError);
+        assert.equal(error.message, 'Weird provider behavior');
+    });
+    it('uses default behavior if custom error handler returns undefined', async (context) => {
+        const rateLimitedProvider = new Provider({
+            prepareRequest: requestOptions => {
+                return {
+                    url: `www.${requestOptions.credentials.domain ?? 'myApi.com'}`,
+                    headers: {
+                        'X-Custom-Provider-Header': 'value',
+                        'X-Provider-Credential-Header': requestOptions.credentials.apiKey,
+                    },
+                };
+            },
+            rateLimiter: undefined,
+            // Custom Error Handler returning undefined (default behavior should apply)
+            customErrorHandler: () => undefined,
+        });
+        const response = new Response(undefined, {
+            status: 404,
+            headers: { 'Content-Type': 'application/json' },
+        });
+        context.mock.method(global, 'fetch', () => Promise.resolve(response));
+        const options = {
+            credentials: { apiKey: 'apikey#1111' },
+            logger: logger,
+            signal: new AbortController().signal,
+            additionnalheaders: { 'X-Additional-Header': 'value1' },
+        };
+        let error;
+        try {
+            await rateLimitedProvider.delete('/endpoint/123', options);
+        }
+        catch (e) {
+            error = e;
+        }
+        assert.ok(error instanceof HttpErrors.HttpError);
+        assert.equal(error.message, 'Not found');
+    });
     it('returns valid json response', async (context) => {
         const response = new Response(`{ "validJson": true }`, {
             status: 200,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unito/integration-sdk",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "Integration SDK",
   "type": "module",
   "types": "dist/src/index.d.ts",

package/src/resources/provider.ts

@@ -1,4 +1,5 @@
 import { buildHttpError } from '../errors.js';
+import * as HttpErrors from '../httpErrors.js';
 import { Credentials } from '../middlewares/credentials.js';
 import Logger from '../resources/logger.js';
 
@@ -59,26 +60,56 @@ export type Response<T> = {
  * 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.
+ * add to the requests, can also be configured to use a provided rate limiting function, and custom error handler.
+ *
+ * Multiple `Provider` instances can be created, with different configurations to call different providers APIs with
+ * different rateLimiting functions, as needed.
  * @see {@link RateLimiter}
  * @see {@link prepareRequest}
+ * @see {@link customErrorHandler}
  */
 export class Provider {
+  /**
+   * The Rate Limiter function to use to limit the rate of calls made to the provider based on the caller's credentials.
+   */
   protected rateLimiter: RateLimiter | undefined = undefined;
+  /**
+   * Function called before each request to define the Provider's base URL and any specific headers to add to the requests.
+   *
+   * This is applied at large to all requests made to the provider. If you need to add specific headers to a single request,
+   * pass it through the RequestOptions object when calling the Provider's methods.
+   */
   protected prepareRequest: (options: { credentials: Credentials; logger: Logger }) => {
     url: string;
     headers: Record<string, string>;
   };
+  /**
+   * (Optional) Custom error handler to handle specific errors returned by the provider.
+   *
+   * If provided, this method should only care about custom errors returned by the provider and return the corresponding
+   * HttpError from the SDK. If the error encountered is a standard error, it should return undefined and let the SDK handle it.
+   *
+   * @see buildHttpError for the list of standard errors the SDK can handle.
+   */
+  protected customErrorHandler:
+    | ((responseStatus: number, message: string) => HttpErrors.HttpError | undefined)
+    | undefined;
 
   /**
    * 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.
+   * @property customErrorHandler - function to handle specific errors returned by the provider.
    */
-  constructor(options: { prepareRequest: typeof Provider.prototype.prepareRequest; rateLimiter?: RateLimiter }) {
+  constructor(options: {
+    prepareRequest: typeof Provider.prototype.prepareRequest;
+    rateLimiter?: RateLimiter | undefined;
+    customErrorHandler?: typeof Provider.prototype.customErrorHandler;
+  }) {
     this.prepareRequest = options.prepareRequest;
     this.rateLimiter = options.rateLimiter;
+    this.customErrorHandler = options.customErrorHandler;
   }
 
   /**
@@ -262,18 +293,18 @@ export class Provider {
         if (error instanceof Error) {
           switch (error.name) {
             case 'AbortError':
-              throw buildHttpError(408, 'Request aborted');
+              throw this.handleError(408, 'Request aborted');
             case 'TimeoutError':
-              throw buildHttpError(408, 'Request timeout');
+              throw this.handleError(408, 'Request timeout');
           }
         }
 
-        throw buildHttpError(500, `Unexpected error while calling the provider: "${error}"`);
+        throw this.handleError(500, `Unexpected error while calling the provider: "${error}"`);
       }
 
       if (response.status >= 400) {
         const textResult = await response.text();
-        throw buildHttpError(response.status, textResult);
+        throw this.handleError(response.status, textResult);
       }
 
       const responseContentType = response.headers.get('content-type');
@@ -284,7 +315,7 @@ export class Provider {
         // (Provider's response Content-Type might be more specific, e.g. application/json;charset=utf-8)
         // Default to application/json if no Content-Type header is provided
         if (responseContentType && !responseContentType.includes('application/json')) {
-          throw buildHttpError(
+          throw this.handleError(
             500,
             `Unsupported content-type. Expected 'application/json', got '${responseContentType}'`,
           );
@@ -293,13 +324,13 @@ export class Provider {
         try {
           body = response.body ? await response.json() : undefined;
         } catch (err) {
-          throw buildHttpError(500, `Invalid JSON response`);
+          throw this.handleError(500, `Invalid JSON response`);
         }
       } else if (headers.Accept == 'application/octet-stream') {
         // When we expect octet-stream, we accept any Content-Type the provider sends us, we just want to stream it.
         body = response.body as T;
       } else {
-        throw buildHttpError(500, 'Unsupported accept header');
+        throw this.handleError(500, 'Unsupported accept header');
       }
 
       return { status: response.status, headers: response.headers, body };
@@ -307,4 +338,10 @@ export class Provider {
 
     return this.rateLimiter ? this.rateLimiter(options, callToProvider) : callToProvider();
   }
+
+  private handleError(responseStatus: number, message: string): HttpErrors.HttpError {
+    const customError = this.customErrorHandler?.(responseStatus, message);
+
+    return customError ?? buildHttpError(responseStatus, message);
+  }
 }

package/test/resources/provider.test.ts

@@ -297,6 +297,89 @@ describe('Provider', () => {
     assert.deepEqual(actualResponse, { status: 204, headers: response.headers, body: undefined });
   });
 
+  it('uses custom error handler if provided', async context => {
+    const rateLimitedProvider = new Provider({
+      prepareRequest: requestOptions => {
+        return {
+          url: `www.${requestOptions.credentials.domain ?? 'myApi.com'}`,
+          headers: {
+            'X-Custom-Provider-Header': 'value',
+            'X-Provider-Credential-Header': requestOptions.credentials.apiKey as string,
+          },
+        };
+      },
+      rateLimiter: undefined,
+      // Change from normal behavior 400 -> 429
+      customErrorHandler: (responseStatus: number) =>
+        responseStatus === 400 ? new HttpErrors.RateLimitExceededError('Weird provider behavior') : undefined,
+    });
+
+    const response = new Response(undefined, {
+      status: 400,
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    context.mock.method(global, 'fetch', () => Promise.resolve(response));
+
+    const options = {
+      credentials: { apiKey: 'apikey#1111' },
+      logger: logger,
+      signal: new AbortController().signal,
+      additionnalheaders: { 'X-Additional-Header': 'value1' },
+    };
+
+    let error;
+    try {
+      await rateLimitedProvider.delete('/endpoint/123', options);
+    } catch (e) {
+      error = e;
+    }
+
+    assert.ok(error instanceof HttpErrors.HttpError);
+    assert.equal(error.message, 'Weird provider behavior');
+  });
+
+  it('uses default behavior if custom error handler returns undefined', async context => {
+    const rateLimitedProvider = new Provider({
+      prepareRequest: requestOptions => {
+        return {
+          url: `www.${requestOptions.credentials.domain ?? 'myApi.com'}`,
+          headers: {
+            'X-Custom-Provider-Header': 'value',
+            'X-Provider-Credential-Header': requestOptions.credentials.apiKey as string,
+          },
+        };
+      },
+      rateLimiter: undefined,
+      // Custom Error Handler returning undefined (default behavior should apply)
+      customErrorHandler: () => undefined,
+    });
+
+    const response = new Response(undefined, {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    context.mock.method(global, 'fetch', () => Promise.resolve(response));
+
+    const options = {
+      credentials: { apiKey: 'apikey#1111' },
+      logger: logger,
+      signal: new AbortController().signal,
+      additionnalheaders: { 'X-Additional-Header': 'value1' },
+    };
+
+    let error;
+    try {
+      await rateLimitedProvider.delete('/endpoint/123', options);
+    } catch (e) {
+      error = e;
+    }
+
+    assert.ok(error instanceof HttpErrors.HttpError);
+    assert.equal(error.message, 'Not found');
+  });
+
   it('returns valid json response', async context => {
     const response = new Response(`{ "validJson": true }`, {
       status: 200,