@unito/integration-sdk 2.3.14 → 2.4.0

package/dist/src/httpErrors.d.ts

@@ -4,10 +4,14 @@
  *
  * @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 declare class HttpError extends Error {
     readonly status: number;
-    constructor(message: string, status: number);
+    readonly retryAfter: number | undefined;
+    constructor(message: string, status: number, options?: {
+        retryAfter?: number;
+    });
 }
 /**
  * Used to generate a 400 Bad Request. Usually used when something is missing to properly handle the request.
@@ -57,12 +61,16 @@ export declare class UnprocessableEntityError extends HttpError {
  * Used to generate a 423 Provider Instance Locked.
  */
 export declare class ProviderInstanceLockedError extends HttpError {
-    constructor(message?: string);
+    constructor(message?: string, options?: {
+        retryAfter?: number;
+    });
 }
 /**
  * Used to generate a 429 Rate Limit Exceeded. Usually used when an operation triggers or would trigger a rate limit
  * error on the provider's side.
  */
 export declare class RateLimitExceededError extends HttpError {
-    constructor(message?: string);
+    constructor(message?: string, options?: {
+        retryAfter?: number;
+    });
 }

package/dist/src/httpErrors.js

@@ -4,13 +4,16 @@
  *
  * @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 {
     status;
-    constructor(message, status) {
+    retryAfter = undefined;
+    constructor(message, status, options = {}) {
         super(message);
         this.status = status;
         this.name = this.constructor.name;
+        this.retryAfter = options.retryAfter;
     }
 }
 /**
@@ -75,8 +78,8 @@ export class UnprocessableEntityError extends HttpError {
  * Used to generate a 423 Provider Instance Locked.
  */
 export class ProviderInstanceLockedError extends HttpError {
-    constructor(message) {
-        super(message || 'Provider instance locked or unavailable', 423);
+    constructor(message, options = {}) {
+        super(message || 'Provider instance locked or unavailable', 423, options);
     }
 }
 /**
@@ -84,7 +87,7 @@ export class ProviderInstanceLockedError extends HttpError {
  * error on the provider's side.
  */
 export class RateLimitExceededError extends HttpError {
-    constructor(message) {
-        super(message || 'Rate Limit Exceeded', 429);
+    constructor(message, options = {}) {
+        super(message || 'Rate Limit Exceeded', 429, options);
     }
 }

package/dist/src/index.cjs

@@ -264,99 +264,29 @@ class Logger {
 const NULL_LOGGER = new Logger({}, true);
 
 /**
- * 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.
  */
-class Cache {
-    cacheInstance;
-    constructor(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
-     */
-    getOrFetchValue(key, ttl, fetcher, lockTtl, shouldCacheError) {
-        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.
-     */
-    getValue(key) {
-        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.
-     */
-    setValue(key, value, ttl) {
-        return this.cacheInstance.setValue(key, value, ttl);
-    }
-    /**
-     * Delete a value from the cache.
-     * @param key — The key of the value to set.
-     */
-    delValue(key) {
-        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.
-     */
-    getTtl(key) {
-        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.
-     */
-    static create(redisUrl) {
-        const cacheInstance = redisUrl ? new cachette.RedisCache(redisUrl) : new cachette.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) {
+    const cacheInstance = redisUrl ? new cachette.RedisCache(redisUrl) : new cachette.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;
 }
+const Cache = { create };
 
 /**
  * Error class meant to be returned by integrations in case of exceptions. These errors will be caught and handled
@@ -364,13 +294,16 @@ class Cache {
  *
  * @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.
  */
 class HttpError extends Error {
     status;
-    constructor(message, status) {
+    retryAfter = undefined;
+    constructor(message, status, options = {}) {
         super(message);
         this.status = status;
         this.name = this.constructor.name;
+        this.retryAfter = options.retryAfter;
     }
 }
 /**
@@ -435,8 +368,8 @@ class UnprocessableEntityError extends HttpError {
  * Used to generate a 423 Provider Instance Locked.
  */
 class ProviderInstanceLockedError extends HttpError {
-    constructor(message) {
-        super(message || 'Provider instance locked or unavailable', 423);
+    constructor(message, options = {}) {
+        super(message || 'Provider instance locked or unavailable', 423, options);
     }
 }
 /**
@@ -444,8 +377,8 @@ class ProviderInstanceLockedError extends HttpError {
  * error on the provider's side.
  */
 class RateLimitExceededError extends HttpError {
-    constructor(message) {
-        super(message || 'Rate Limit Exceeded', 429);
+    constructor(message, options = {}) {
+        super(message || 'Rate Limit Exceeded', 429, options);
     }
 }
 
@@ -876,6 +809,9 @@ function onError(err, _req, res, next) {
     }
     let error;
     if (err instanceof HttpError) {
+        if (err.retryAfter) {
+            res.setHeader('Retry-After', String(err.retryAfter));
+        }
         error = {
             code: err.status.toString(),
             message: err.message,
@@ -1369,6 +1305,21 @@ class Provider {
                     request.on('error', error => {
                         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) {
@@ -1423,6 +1374,7 @@ class Provider {
                         path: urlObj.pathname + urlObj.search,
                         method: 'POST',
                         headers,
+                        timeout: 0,
                     };
                     const request = https.request(requestOptions, response => {
                         response.setEncoding('utf8');
@@ -1462,6 +1414,21 @@ class Provider {
                         request.destroy();
                         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);
                 }

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 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 { Provider, type Response as ProviderResponse, type RequestOptions as ProviderRequestOptions, type RateLimiter, } from './resources/provider.js';

package/dist/src/middlewares/errors.js

@@ -5,6 +5,9 @@ function onError(err, _req, res, next) {
     }
     let error;
     if (err instanceof HttpError) {
+        if (err.retryAfter) {
+            res.setHeader('Retry-After', String(err.retryAfter));
+        }
         error = {
             code: err.status.toString(),
             message: err.message,

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

@@ -1,67 +1,12 @@
-import { FetchingFunction, CachableValue } from 'cachette';
+import { CacheInstance } from 'cachette';
 /**
- * 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 declare class Cache {
-    private cacheInstance;
-    private constructor();
-    /**
-     * 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
-     */
-    getOrFetchValue<F extends FetchingFunction = FetchingFunction>(key: string, ttl: number, fetcher: F, lockTtl?: number, shouldCacheError?: (err: Error) => boolean): Promise<ReturnType<F>>;
-    /**
-     * 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.
-     */
-    getValue(key: string): Promise<CachableValue>;
-    /**
-     * 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.
-     */
-    setValue(key: string, value: CachableValue, ttl?: number): Promise<boolean>;
-    /**
-     * Delete a value from the cache.
-     * @param key — The key of the value to set.
-     */
-    delValue(key: string): Promise<void>;
-    /**
-     * 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.
-     */
-    getTtl(key: string): Promise<number | undefined>;
-    /**
-     * 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.
-     */
-    static create(redisUrl?: string): Cache;
-}
+declare function create(redisUrl?: string): CacheInstance;
+export declare const Cache: {
+    create: typeof create;
+};
+export type { CacheInstance };

package/dist/src/resources/cache.js

@@ -2,96 +2,26 @@ import { LocalCache, 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 {
-    cacheInstance;
-    constructor(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
-     */
-    getOrFetchValue(key, ttl, fetcher, lockTtl, shouldCacheError) {
-        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.
-     */
-    getValue(key) {
-        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.
-     */
-    setValue(key, value, ttl) {
-        return this.cacheInstance.setValue(key, value, ttl);
-    }
-    /**
-     * Delete a value from the cache.
-     * @param key — The key of the value to set.
-     */
-    delValue(key) {
-        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.
-     */
-    getTtl(key) {
-        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.
-     */
-    static create(redisUrl) {
-        const 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) {
+    const 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 };

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

@@ -17,7 +17,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>(options: {

package/dist/src/resources/provider.js

@@ -150,6 +150,21 @@ export class Provider {
                     request.on('error', error => {
                         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) {
@@ -204,6 +219,7 @@ export class Provider {
                         path: urlObj.pathname + urlObj.search,
                         method: 'POST',
                         headers,
+                        timeout: 0,
                     };
                     const request = https.request(requestOptions, response => {
                         response.setEncoding('utf8');
@@ -243,6 +259,21 @@ export class Provider {
                         request.destroy();
                         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);
                 }

package/dist/test/middlewares/errors.test.js

@@ -1,7 +1,7 @@
 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', () => {
         let actualStatus;
@@ -41,6 +41,29 @@ describe('errors middleware', () => {
         assert.strictEqual(actualStatus, 429);
         assert.deepEqual(actualJson, { code: '429', message: 'httpError' });
     });
+    it('handles retry-after header', () => {
+        let actualStatus;
+        let actualJson;
+        const response = {
+            headersSent: false,
+            status: (code) => {
+                actualStatus = code;
+                return {
+                    json: (json) => {
+                        actualJson = json;
+                    },
+                };
+            },
+            locals: { logger: { error: () => undefined } },
+            setHeader: (name, value) => {
+                assert.strictEqual(name, 'Retry-After');
+                assert.strictEqual(value, '1234');
+            },
+        };
+        onError(new RateLimitExceededError('httpError', { retryAfter: 1234 }), {}, response, () => { });
+        assert.strictEqual(actualStatus, 429);
+        assert.deepEqual(actualJson, { code: '429', message: 'httpError' });
+    });
     it('handles other error', () => {
         let actualStatus;
         let actualJson;

package/dist/test/resources/cache.test.js

@@ -6,9 +6,8 @@ describe('Cache', () => {
     describe('initializeCache', () => {
         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);
-            await cache['cacheInstance'].quit();
+            assert.ok(cache instanceof LocalCache);
+            await cache.quit();
         });
         it('redis url tries to return a RedisCache', () => {
             assert.throws(() => Cache.create('fakeredis'), Error, 'Invalid redis url fakereis.');