@unito/integration-sdk 2.3.14 → 2.4.0

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

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import { Readable } from 'stream';
 import nock from 'nock';
+import https from 'https';
 import { Provider } from '../../src/resources/provider.js';
 import * as HttpErrors from '../../src/httpErrors.js';
 import Logger from '../../src/resources/logger.js';
@@ -23,6 +24,21 @@ describe('Provider', () => {
         },
     });
     const logger = new Logger();
+    // Helper to spy on https.request and capture options
+    const spyOnHttpsRequest = () => {
+        let capturedOptions;
+        const originalRequest = https.request;
+        https.request = function (options, callback) {
+            capturedOptions = options;
+            return originalRequest.call(https, options, callback);
+        };
+        return {
+            getCapturedOptions: () => capturedOptions,
+            restore: () => {
+                https.request = originalRequest;
+            },
+        };
+    };
     it('get', async (context) => {
         const response = new Response('{"data": "value"}', {
             status: 200,
@@ -941,4 +957,212 @@ describe('Provider', () => {
             unitoCredentialId: '123',
         });
     });
+    it('postStream sets timeout to 0 (no timeout)', async () => {
+        const streamProvider = new Provider({
+            prepareRequest: requestOptions => ({
+                url: `https://www.myApi.com`,
+                headers: {
+                    'X-Custom-Provider-Header': 'value',
+                    'X-Provider-Credential-Header': requestOptions.credentials.apiKey,
+                },
+            }),
+        });
+        const testData = 'timeout test data';
+        const stream = Readable.from([testData]);
+        const spy = spyOnHttpsRequest();
+        const scope = nock('https://www.myApi.com').post('/upload', testData).reply(201, { success: true });
+        try {
+            await streamProvider.postStream('/upload', stream, {
+                credentials: { apiKey: 'apikey#1111', unitoCredentialId: '123' },
+                logger,
+            });
+            assert.ok(scope.isDone());
+            assert.equal(spy.getCapturedOptions().timeout, 0, 'Timeout should be set to 0 (no timeout)');
+        }
+        finally {
+            spy.restore();
+        }
+    });
+    it('postStream handles AbortSignal for request cancellation', async () => {
+        const streamProvider = new Provider({
+            prepareRequest: requestOptions => ({
+                url: `https://www.myApi.com`,
+                headers: {
+                    'X-Custom-Provider-Header': 'value',
+                    'X-Provider-Credential-Header': requestOptions.credentials.apiKey,
+                },
+            }),
+        });
+        const stream = Readable.from(['abort signal test']);
+        const abortController = new AbortController();
+        // Simulate aborting the request immediately
+        abortController.abort();
+        let error;
+        try {
+            await streamProvider.postStream('/upload', stream, {
+                credentials: { apiKey: 'apikey#1111', unitoCredentialId: '123' },
+                logger,
+                signal: abortController.signal,
+            });
+        }
+        catch (e) {
+            error = e;
+        }
+        assert.ok(error instanceof HttpErrors.TimeoutError);
+        assert.equal(error.message, 'Timeout');
+    });
+    it('postStream handles AbortSignal timeout during request', async () => {
+        const streamProvider = new Provider({
+            prepareRequest: requestOptions => ({
+                url: `https://www.myApi.com`,
+                headers: {
+                    'X-Custom-Provider-Header': 'value',
+                    'X-Provider-Credential-Header': requestOptions.credentials.apiKey,
+                },
+            }),
+        });
+        const stream = Readable.from(['timeout during request test']);
+        const abortController = new AbortController();
+        // Delay response to simulate a slow server
+        nock('https://www.myApi.com').post('/upload').delayConnection(100).reply(201, { success: true });
+        // Abort after 50ms
+        setTimeout(() => abortController.abort(), 50);
+        let error;
+        try {
+            await streamProvider.postStream('/upload', stream, {
+                credentials: { apiKey: 'apikey#1111', unitoCredentialId: '123' },
+                logger,
+                signal: abortController.signal,
+            });
+        }
+        catch (e) {
+            error = e;
+        }
+        assert.ok(error instanceof HttpErrors.TimeoutError);
+        assert.equal(error.message, 'Timeout');
+    });
+    it('postStream cleans up AbortSignal listener on success', async () => {
+        const streamProvider = new Provider({
+            prepareRequest: requestOptions => ({
+                url: `https://www.myApi.com`,
+                headers: {
+                    'X-Custom-Provider-Header': 'value',
+                    'X-Provider-Credential-Header': requestOptions.credentials.apiKey,
+                },
+            }),
+        });
+        const testData = 'cleanup test';
+        const stream = Readable.from([testData]);
+        const abortController = new AbortController();
+        const scope = nock('https://www.myApi.com').post('/upload', testData).reply(201, { success: true });
+        const response = await streamProvider.postStream('/upload', stream, {
+            credentials: { apiKey: 'apikey#1111', unitoCredentialId: '123' },
+            logger,
+            signal: abortController.signal,
+        });
+        assert.ok(scope.isDone());
+        assert.equal(response.status, 201);
+        // Verify the listener was removed by checking that aborting after completion
+        // doesn't cause any side effects (if listener wasn't removed, this could cause issues)
+        assert.doesNotThrow(() => {
+            abortController.abort();
+        }, 'Aborting after completion should not throw or cause issues');
+        // Verify the signal is indeed aborted
+        assert.ok(abortController.signal.aborted, 'Signal should be aborted');
+    });
+    it('postForm handles AbortSignal for request cancellation', async () => {
+        const FormData = (await import('form-data')).default;
+        const formProvider = new Provider({
+            prepareRequest: requestOptions => ({
+                url: `https://www.myApi.com`,
+                headers: {
+                    'X-Custom-Provider-Header': 'value',
+                    'X-Provider-Credential-Header': requestOptions.credentials.apiKey,
+                },
+            }),
+        });
+        const form = new FormData();
+        form.append('field1', 'value1');
+        form.append('field2', 'value2');
+        const abortController = new AbortController();
+        // Simulate aborting the request immediately
+        abortController.abort();
+        let error;
+        try {
+            await formProvider.postForm('/upload-form', form, {
+                credentials: { apiKey: 'apikey#1111', unitoCredentialId: '123' },
+                logger,
+                signal: abortController.signal,
+            });
+        }
+        catch (e) {
+            error = e;
+        }
+        assert.ok(error instanceof HttpErrors.TimeoutError);
+        assert.equal(error.message, 'Timeout');
+    });
+    it('postForm handles AbortSignal timeout during request', async () => {
+        const FormData = (await import('form-data')).default;
+        const formProvider = new Provider({
+            prepareRequest: requestOptions => ({
+                url: `https://www.myApi.com`,
+                headers: {
+                    'X-Custom-Provider-Header': 'value',
+                    'X-Provider-Credential-Header': requestOptions.credentials.apiKey,
+                },
+            }),
+        });
+        const form = new FormData();
+        form.append('field1', 'value1');
+        const abortController = new AbortController();
+        // Mock a delayed response
+        nock('https://www.myApi.com').post('/upload-form').delayConnection(100).reply(201, { success: true, id: '12345' });
+        // Abort after 50ms
+        setTimeout(() => abortController.abort(), 50);
+        let error;
+        try {
+            await formProvider.postForm('/upload-form', form, {
+                credentials: { apiKey: 'apikey#1111', unitoCredentialId: '123' },
+                logger,
+                signal: abortController.signal,
+            });
+        }
+        catch (e) {
+            error = e;
+        }
+        assert.ok(error instanceof HttpErrors.TimeoutError);
+        assert.equal(error.message, 'Timeout');
+    });
+    it('postForm successfully completes with AbortSignal provided', async () => {
+        const FormData = (await import('form-data')).default;
+        const formProvider = new Provider({
+            prepareRequest: requestOptions => ({
+                url: `https://www.myApi.com`,
+                headers: {
+                    'X-Custom-Provider-Header': 'value',
+                    'X-Provider-Credential-Header': requestOptions.credentials.apiKey,
+                },
+            }),
+        });
+        const form = new FormData();
+        form.append('field1', 'value1');
+        form.append('field2', 'value2');
+        const abortController = new AbortController();
+        const scope = nock('https://www.myApi.com').post('/upload-form').reply(201, { success: true, id: '12345' });
+        const response = await formProvider.postForm('/upload-form', form, {
+            credentials: { apiKey: 'apikey#1111', unitoCredentialId: '123' },
+            logger,
+            signal: abortController.signal,
+        });
+        assert.ok(scope.isDone());
+        assert.equal(response.status, 201);
+        assert.deepEqual(response.body, { success: true, id: '12345' });
+        // Verify the listener was removed by checking that aborting after completion
+        // doesn't cause any side effects
+        assert.doesNotThrow(() => {
+            abortController.abort();
+        }, 'Aborting after completion should not throw or cause issues');
+        // Verify the signal is indeed aborted
+        assert.ok(abortController.signal.aborted, 'Signal should be aborted');
+    });
 });

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/errors.ts","../src/handler.ts","../src/helpers.ts","../src/httpErrors.ts","../src/index.ts","../src/integration.ts","../src/middlewares/correlationId.ts","../src/middlewares/credentials.ts","../src/middlewares/errors.ts","../src/middlewares/filters.ts","../src/middlewares/finish.ts","../src/middlewares/health.ts","../src/middlewares/logger.ts","../src/middlewares/notFound.ts","../src/middlewares/relations.ts","../src/middlewares/search.ts","../src/middlewares/secrets.ts","../src/middlewares/selects.ts","../src/middlewares/signal.ts","../src/middlewares/start.ts","../src/resources/cache.ts","../src/resources/context.ts","../src/resources/logger.ts","../src/resources/provider.ts","../test/errors.test.ts","../test/handler.test.ts","../test/helpers.test.ts","../test/integration.test.ts","../test/middlewares/correlationId.test.ts","../test/middlewares/credentials.test.ts","../test/middlewares/errors.test.ts","../test/middlewares/filters.test.ts","../test/middlewares/finish.test.ts","../test/middlewares/health.test.ts","../test/middlewares/logger.test.ts","../test/middlewares/notFound.test.ts","../test/middlewares/relations.test.ts","../test/middlewares/search.test.ts","../test/middlewares/secrets.test.ts","../test/middlewares/selects.test.ts","../test/middlewares/signal.test.ts","../test/middlewares/start.test.ts","../test/resources/cache.test.ts","../test/resources/logger.test.ts","../test/resources/provider.test.ts"],"version":"5.8.3"}
+{"root":["../src/errors.ts","../src/handler.ts","../src/helpers.ts","../src/httpErrors.ts","../src/index.ts","../src/integration.ts","../src/middlewares/correlationId.ts","../src/middlewares/credentials.ts","../src/middlewares/errors.ts","../src/middlewares/filters.ts","../src/middlewares/finish.ts","../src/middlewares/health.ts","../src/middlewares/logger.ts","../src/middlewares/notFound.ts","../src/middlewares/relations.ts","../src/middlewares/search.ts","../src/middlewares/secrets.ts","../src/middlewares/selects.ts","../src/middlewares/signal.ts","../src/middlewares/start.ts","../src/resources/cache.ts","../src/resources/context.ts","../src/resources/logger.ts","../src/resources/provider.ts","../test/errors.test.ts","../test/handler.test.ts","../test/helpers.test.ts","../test/integration.test.ts","../test/middlewares/correlationId.test.ts","../test/middlewares/credentials.test.ts","../test/middlewares/errors.test.ts","../test/middlewares/filters.test.ts","../test/middlewares/finish.test.ts","../test/middlewares/health.test.ts","../test/middlewares/logger.test.ts","../test/middlewares/notFound.test.ts","../test/middlewares/relations.test.ts","../test/middlewares/search.test.ts","../test/middlewares/secrets.test.ts","../test/middlewares/selects.test.ts","../test/middlewares/signal.test.ts","../test/middlewares/start.test.ts","../test/resources/cache.test.ts","../test/resources/logger.test.ts","../test/resources/provider.test.ts"],"version":"5.9.3"}

package/package.json

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

package/src/httpErrors.ts

@@ -4,14 +4,17 @@
  *
  * @field message - The error message
  * @field status - The HTTP status code to return
+ * @field retryAfter - The minimum number of seconds to wait before retrying the request.
  */
 export class HttpError extends Error {
   readonly status: number;
+  readonly retryAfter: number | undefined = undefined;
 
-  constructor(message: string, status: number) {
+  constructor(message: string, status: number, options: { retryAfter?: number } = {}) {
     super(message);
     this.status = status;
     this.name = this.constructor.name;
+    this.retryAfter = options.retryAfter;
   }
 }
 
@@ -84,8 +87,8 @@ export class UnprocessableEntityError extends HttpError {
  * Used to generate a 423 Provider Instance Locked.
  */
 export class ProviderInstanceLockedError extends HttpError {
-  constructor(message?: string) {
-    super(message || 'Provider instance locked or unavailable', 423);
+  constructor(message?: string, options: { retryAfter?: number } = {}) {
+    super(message || 'Provider instance locked or unavailable', 423, options);
   }
 }
 
@@ -94,7 +97,7 @@ export class ProviderInstanceLockedError extends HttpError {
  * error on the provider's side.
  */
 export class RateLimitExceededError extends HttpError {
-  constructor(message?: string) {
-    super(message || 'Rate Limit Exceeded', 429);
+  constructor(message?: string, options: { retryAfter?: number } = {}) {
+    super(message || 'Rate Limit Exceeded', 429, options);
   }
 }

package/src/index.ts

@@ -1,7 +1,7 @@
 /* c8 ignore start */
 export * as Api from '@unito/integration-api';
 
-export { Cache } from './resources/cache.js';
+export { Cache, type CacheInstance } from './resources/cache.js';
 export { default as Integration } from './integration.js';
 export * from './handler.js';
 export {

package/src/middlewares/errors.ts

@@ -20,6 +20,10 @@ function onError(err: Error, _req: Request, res: Response, next: NextFunction) {
   let error: ApiError;
 
   if (err instanceof HttpError) {
+    if (err.retryAfter) {
+      res.setHeader('Retry-After', String(err.retryAfter));
+    }
+
     error = {
       code: err.status.toString(),
       message: err.message,

package/src/resources/cache.ts

@@ -1,115 +1,34 @@
-import { LocalCache, CacheInstance, FetchingFunction, CachableValue, RedisCache } from 'cachette';
+import { LocalCache, CacheInstance, RedisCache } from 'cachette';
 import crypto from 'crypto';
 import Logger from './logger.js';
 
 /**
- * The Cache class provides caching capabilities that can be used across your integration.
- * It can be backed by a Redis instance (by passing it a URL to the instance) or a local cache.
+ * Initializes a Cache backed by the Redis instance at the provided url if present, or a LocalCache otherwise.
  *
- * @see {@link Cache.create}
+ * @param redisUrl - The redis url to connect to (optional).
+ * @returns A cache instance.
  */
-export class Cache {
-  private cacheInstance: CacheInstance;
-
-  private constructor(cacheInstance: CacheInstance) {
-    this.cacheInstance = cacheInstance;
-  }
-
-  /**
-   * Get or fetch a value
-   *
-   * @param key     The key of the value to get
-   * @param ttl     The time to live of the value in seconds.
-   * @param fetchFn The function that can retrieve the original value
-   * @param lockTtl Global distributed lock TTL (in seconds) protecting fetching.
-   *                If undefined, 0 or falsy, locking is not preformed
-   * @param shouldCacheError A callback being passed errors, controlling whether
-   *                         to cache or not errors. Defaults to never cache.
-   *
-   * @returns       The cached or fetched value
-   */
-  public getOrFetchValue<F extends FetchingFunction = FetchingFunction>(
-    key: string,
-    ttl: number,
-    fetcher: F,
-    lockTtl?: number,
-    shouldCacheError?: (err: Error) => boolean,
-  ): Promise<ReturnType<F>> {
-    return this.cacheInstance.getOrFetchValue(key, ttl, fetcher, lockTtl, shouldCacheError);
-  }
-
-  /**
-   * Get a value from the cache.
-   *
-   * @param key   The key of the value to get.
-   *
-   * @return      The value associated with the key, or undefined if
-   *              no such value exists.
-   */
-  public getValue(key: string): Promise<CachableValue> {
-    return this.cacheInstance.getValue(key);
-  }
-
-  /**
-   * Set a value in the cache.
-   *
-   * @param key        The key of the value to set.
-   * @param value      The value to set.
-   * @param ttl        The time to live of the value in seconds.
-   *                   By default, the value will not expire
-   *
-   * @return true if the value was stored, false otherwise.
-   */
-  public setValue(key: string, value: CachableValue, ttl?: number): Promise<boolean> {
-    return this.cacheInstance.setValue(key, value, ttl);
-  }
-
-  /**
-   * Delete a value from the cache.
-   * @param key — The key of the value to set.
-   */
-  public delValue(key: string): Promise<void> {
-    return this.cacheInstance.delValue(key);
-  }
-
-  /**
-   * Get the TTL of an entry, in ms
-   *
-   * @param key   The key of the entry whose ttl to retrieve
-   *
-   * @return      The remaining TTL on the entry, in ms.
-   *              undefined if the entry does not exist.
-   *              0 if the entry does not expire.
-   */
-  public getTtl(key: string): Promise<number | undefined> {
-    return this.cacheInstance.getTtl(key);
-  }
-
-  /**
-   * Initializes a Cache backed by the Redis instance at the provided url if present, or a LocalCache otherwise.
-   *
-   * @param redisUrl - The redis url to connect to (optional).
-   * @returns A cache instance.
-   */
-  public static create(redisUrl?: string): Cache {
-    const cacheInstance: CacheInstance = redisUrl ? new RedisCache(redisUrl) : new LocalCache();
-
-    // Intended: the correlation id will be the same for all logs of Cachette.
-    const correlationId = crypto.randomUUID();
-
-    const logger = new Logger({ correlation_id: correlationId });
-
-    cacheInstance
-      .on('info', message => {
-        logger.info(message);
-      })
-      .on('warn', message => {
-        logger.warn(message);
-      })
-      .on('error', message => {
-        logger.error(message);
-      });
-
-    return new Cache(cacheInstance);
-  }
+function create(redisUrl?: string): CacheInstance {
+  const cacheInstance: CacheInstance = redisUrl ? new RedisCache(redisUrl) : new LocalCache();
+
+  // Intended: the correlation id will be the same for all logs of Cachette.
+  const correlationId = crypto.randomUUID();
+
+  const logger = new Logger({ correlation_id: correlationId });
+
+  cacheInstance
+    .on('info', message => {
+      logger.info(message);
+    })
+    .on('warn', message => {
+      logger.warn(message);
+    })
+    .on('error', message => {
+      logger.error(message);
+    });
+
+  return cacheInstance;
 }
+
+export const Cache = { create };
+export type { CacheInstance };

package/src/resources/provider.ts

@@ -21,7 +21,6 @@ import Logger from '../resources/logger.js';
  * @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>(
@@ -243,6 +242,25 @@ export class Provider {
             reject(this.handleError(400, `Error while calling the provider: "${error}"`, options));
           });
 
+          if (options.signal) {
+            const abortHandler = () => {
+              request.destroy();
+              reject(this.handleError(408, 'Timeout', options));
+            };
+
+            if (options.signal.aborted) {
+              abortHandler();
+            }
+
+            options.signal.addEventListener('abort', abortHandler);
+
+            request.on('close', () => {
+              if (options.signal) {
+                options.signal.removeEventListener('abort', abortHandler);
+              }
+            });
+          }
+
           form.pipe(request);
         } catch (error) {
           reject(this.handleError(500, `Unexpected error while calling the provider: "${error}"`, options));
@@ -303,6 +321,7 @@ export class Provider {
             path: urlObj.pathname + urlObj.search,
             method: 'POST',
             headers,
+            timeout: 0,
           };
 
           const request = https.request(requestOptions, response => {
@@ -350,6 +369,25 @@ export class Provider {
             safeReject(this.handleError(500, `Stream error: "${error}"`, options));
           });
 
+          if (options.signal) {
+            const abortHandler = () => {
+              request.destroy();
+              safeReject(this.handleError(408, 'Timeout', options));
+            };
+
+            if (options.signal.aborted) {
+              abortHandler();
+            }
+
+            options.signal.addEventListener('abort', abortHandler);
+
+            request.on('close', () => {
+              if (options.signal) {
+                options.signal.removeEventListener('abort', abortHandler);
+              }
+            });
+          }
+
           // Stream the data directly without buffering
           stream.pipe(request);
         } catch (error) {

package/test/middlewares/errors.test.ts

@@ -2,7 +2,7 @@ import express from 'express';
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import onError from '../../src/middlewares/errors.js';
-import { HttpError } from '../../src/httpErrors.js';
+import { HttpError, RateLimitExceededError } from '../../src/httpErrors.js';
 
 describe('errors middleware', () => {
   it('headers sent, do nothing', () => {
@@ -52,6 +52,33 @@ describe('errors middleware', () => {
     assert.deepEqual(actualJson, { code: '429', message: 'httpError' });
   });
 
+  it('handles retry-after header', () => {
+    let actualStatus: number | undefined;
+    let actualJson: Record<string, unknown> | undefined;
+
+    const response = {
+      headersSent: false,
+      status: (code: number) => {
+        actualStatus = code;
+
+        return {
+          json: (json: Record<string, unknown>) => {
+            actualJson = json;
+          },
+        };
+      },
+      locals: { logger: { error: () => undefined } },
+      setHeader: (name: string, value: string) => {
+        assert.strictEqual(name, 'Retry-After');
+        assert.strictEqual(value, '1234');
+      },
+    } as unknown as express.Response;
+    onError(new RateLimitExceededError('httpError', { retryAfter: 1234 }), {} as express.Request, response, () => {});
+
+    assert.strictEqual(actualStatus, 429);
+    assert.deepEqual(actualJson, { code: '429', message: 'httpError' });
+  });
+
   it('handles other error', () => {
     let actualStatus: number | undefined;
     let actualJson: Record<string, unknown> | undefined;

package/test/resources/cache.test.ts

@@ -8,10 +8,9 @@ describe('Cache', () => {
     it('no redis url returns Cache with a inner LocalCache', async () => {
       const cache = Cache.create();
 
-      assert.ok(cache instanceof Cache);
-      assert.ok(cache['cacheInstance'] instanceof LocalCache);
+      assert.ok(cache instanceof LocalCache);
 
-      await cache['cacheInstance'].quit();
+      await cache.quit();
     });
 
     it('redis url tries to return a RedisCache', () => {