@unito/integration-sdk 2.3.15 → 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,

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/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.');

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.15",
+  "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>(

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', () => {