@wildix/xbees-conversations-utils 1.1.55 → 1.1.56

package/dist-cjs/index.js

@@ -4,3 +4,4 @@ const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./types"), exports);
 tslib_1.__exportStar(require("./normalization"), exports);
 tslib_1.__exportStar(require("./stream"), exports);
+tslib_1.__exportStar(require("./rateLimits"), exports);

package/dist-cjs/rateLimits/RedisCooldown.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisCooldown = void 0;
+const constants_1 = require("./constants");
+class RedisCooldown {
+    static async getRemainingMs(cooldownKey, context) {
+        const { redis, logger } = context;
+        try {
+            const ttlMs = await redis.pttl(`${constants_1.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX}${cooldownKey}`);
+            if (ttlMs > 0) {
+                return ttlMs;
+            }
+        }
+        catch (error) {
+            logger.warn('Failed to read stream rate-limit cooldown from Redis', {
+                cooldownKey,
+                error,
+            });
+        }
+        return 0;
+    }
+    static async setRemainingMs(cooldownKey, cooldownMs, context) {
+        if (cooldownMs <= 0) {
+            return;
+        }
+        const { redis, logger } = context;
+        const redisKey = `${constants_1.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX}${cooldownKey}`;
+        try {
+            await redis.eval(`
+        local key = KEYS[1]
+        local new_ttl = tonumber(ARGV[1])
+        local current_ttl = redis.call('PTTL', key)
+
+        if current_ttl == -2 then
+          redis.call('SET', key, '1', 'PX', new_ttl)
+          return 1
+        end
+
+        if current_ttl == -1 or current_ttl < new_ttl then
+          redis.call('PEXPIRE', key, new_ttl)
+          return 2
+        end
+
+        return 0
+      `, 1, redisKey, cooldownMs.toString());
+        }
+        catch (error) {
+            logger.warn('Failed to write stream rate-limit cooldown to Redis', {
+                cooldownKey,
+                cooldownMs,
+                error,
+            });
+        }
+    }
+}
+exports.RedisCooldown = RedisCooldown;

package/dist-cjs/rateLimits/constants.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_OPTS_3_ATTEMPTS_WITH_COOLDOWN = exports.DEFAULT_OPTS_1_ATTEMPT_NO_COOLDOWN = exports.DEFAULT_RETRY_AFTER_MS = exports.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX = exports.RETRY_AFTER_BUFFER_MS = exports.DEFAULT_JITTER_MS = exports.DEFAULT_MAX_RETRYABLE_DELAY_MS = exports.DEFAULT_MAX_DELAY_MS = exports.DEFAULT_FIXED_RATE_LIMIT_DELAY_MS = void 0;
+exports.DEFAULT_FIXED_RATE_LIMIT_DELAY_MS = 15000;
+exports.DEFAULT_MAX_DELAY_MS = 15000;
+exports.DEFAULT_MAX_RETRYABLE_DELAY_MS = 5000;
+exports.DEFAULT_JITTER_MS = 150;
+exports.RETRY_AFTER_BUFFER_MS = 1000;
+exports.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX = 'stream-rate-limit-cooldown:';
+exports.DEFAULT_RETRY_AFTER_MS = 10000;
+exports.DEFAULT_OPTS_1_ATTEMPT_NO_COOLDOWN = {
+    maxAttempts: 1,
+    enableCooldown: false,
+    maxDelayMs: exports.DEFAULT_MAX_DELAY_MS,
+    maxRetryableDelayMs: exports.DEFAULT_MAX_RETRYABLE_DELAY_MS,
+};
+exports.DEFAULT_OPTS_3_ATTEMPTS_WITH_COOLDOWN = {
+    maxAttempts: 3,
+    enableCooldown: true,
+    maxDelayMs: exports.DEFAULT_MAX_DELAY_MS,
+    maxRetryableDelayMs: exports.DEFAULT_MAX_RETRYABLE_DELAY_MS,
+};

package/dist-cjs/rateLimits/createRateLimitedStreamProxy.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRateLimitedStreamProxy = exports.withStreamRateLimitOptions = void 0;
+const constants_1 = require("./constants");
+const executeStreamRequestWithRateLimitHandling_1 = require("./executeStreamRequestWithRateLimitHandling");
+const STREAM_RATE_LIMIT_OPTIONS_MARKER = '__xbsRateLimitOptions';
+const STREAM_RATE_LIMIT_PROXY_MARKER = Symbol('xbsStreamRateLimitProxy');
+const OPERATION_DEFAULT_OPTIONS = {
+    queryChannels: constants_1.DEFAULT_OPTS_3_ATTEMPTS_WITH_COOLDOWN,
+};
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function hasFunctionProperty(value, key) {
+    return key in value && typeof value[key] === 'function';
+}
+function isStreamChannelLike(value) {
+    if (!isObject(value)) {
+        return false;
+    }
+    return (hasFunctionProperty(value, 'sendMessage') &&
+        hasFunctionProperty(value, 'queryMembers') &&
+        hasFunctionProperty(value, 'updatePartial'));
+}
+function isStreamRateLimitOptionsToken(value) {
+    return isObject(value) && STREAM_RATE_LIMIT_OPTIONS_MARKER in value;
+}
+function splitCallArgsAndOptions(args) {
+    if (args.length === 0) {
+        return { callArgs: args, callOptions: {} };
+    }
+    const lastArg = args[args.length - 1];
+    if (isStreamRateLimitOptionsToken(lastArg)) {
+        return {
+            callArgs: args.slice(0, -1),
+            callOptions: lastArg[STREAM_RATE_LIMIT_OPTIONS_MARKER],
+        };
+    }
+    return { callArgs: args, callOptions: {} };
+}
+function withStreamRateLimitOptions(options) {
+    return {
+        [STREAM_RATE_LIMIT_OPTIONS_MARKER]: options,
+    };
+}
+exports.withStreamRateLimitOptions = withStreamRateLimitOptions;
+function createRateLimitedProxy(target, context, cache) {
+    const cached = cache.get(target);
+    if (cached) {
+        return cached;
+    }
+    const wrapResult = (result) => {
+        if (Array.isArray(result)) {
+            return result.map((item) => wrapResult(item));
+        }
+        if (!isStreamChannelLike(result)) {
+            return result;
+        }
+        const cachedResult = cache.get(result);
+        if (cachedResult) {
+            return cachedResult;
+        }
+        return createRateLimitedProxy(result, context, cache);
+    };
+    const proxy = new Proxy(target, {
+        get: (originalTarget, property, receiver) => {
+            if (property === STREAM_RATE_LIMIT_PROXY_MARKER) {
+                return true;
+            }
+            const value = Reflect.get(originalTarget, property, receiver);
+            if (typeof property !== 'string' || typeof value !== 'function') {
+                return value;
+            }
+            if (property === 'channel') {
+                return (...args) => {
+                    const channel = Reflect.apply(value, originalTarget, args);
+                    return wrapResult(channel);
+                };
+            }
+            return async (...args) => {
+                const { callArgs, callOptions } = splitCallArgsAndOptions(args);
+                const operation = property;
+                const defaultOptions = OPERATION_DEFAULT_OPTIONS[operation] || {};
+                const result = await (0, executeStreamRequestWithRateLimitHandling_1.executeStreamRequestWithRateLimitHandling)(() => Reflect.apply(value, originalTarget, callArgs), operation, context, {
+                    ...defaultOptions,
+                    ...callOptions,
+                });
+                return wrapResult(result);
+            };
+        },
+    });
+    cache.set(target, proxy);
+    return proxy;
+}
+function createRateLimitedStreamProxy(stream, context) {
+    const cache = new WeakMap();
+    return createRateLimitedProxy(stream, context, cache);
+}
+exports.createRateLimitedStreamProxy = createRateLimitedStreamProxy;

package/dist-cjs/rateLimits/exception/createRateLimitExceededException.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRateLimitExceededException = void 0;
+const xbees_conversations_client_1 = require("@wildix/xbees-conversations-client");
+const constants_1 = require("../constants");
+function createRateLimitExceededException(options = {}) {
+    const { rateLimit, message, operation, retryAfterMs = constants_1.DEFAULT_RETRY_AFTER_MS } = options;
+    const defaultMessage = operation ? `Rate limit exceeded for ${operation}` : 'Rate limit exceeded';
+    return new xbees_conversations_client_1.RateLimitExceededException({
+        $metadata: {},
+        message: message || defaultMessage,
+        rateLimitRemaining: rateLimit?.remaining || 0,
+        retryAfter: rateLimit?.reset ? rateLimit.reset - Date.now() : retryAfterMs,
+        rateLimit: rateLimit?.limit?.toString() || 'unknown',
+        rateLimitReset: rateLimit?.reset || Date.now() + retryAfterMs,
+    });
+}
+exports.createRateLimitExceededException = createRateLimitExceededException;

package/dist-cjs/rateLimits/exception/processStreamRateLimitException.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processStreamRateLimitException = void 0;
+const createRateLimitExceededException_1 = require("./createRateLimitExceededException");
+function isStreamException(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'metadata' in error &&
+        typeof error.metadata === 'object' &&
+        error.metadata !== null &&
+        'responseCode' in error.metadata);
+}
+function isStreamAPIException(error) {
+    return typeof error === 'object' && !!error.code;
+}
+function processStreamRateLimitException(error, logger) {
+    if (isStreamException(error) && error.metadata?.responseCode === 429) {
+        const rateLimit = error.metadata?.rateLimit;
+        logger.warn('Stream rate limit exceeded [StreamException]', { rateLimit });
+        return (0, createRateLimitExceededException_1.createRateLimitExceededException)({ rateLimit, message: error.message || 'Rate limit exceeded' });
+    }
+    if (isStreamAPIException(error) && (error.code === 429 || error.StatusCode === 429)) {
+        logger.warn('Stream rate limit exceeded [StreamAPIException]', { code: error.code, StatusCode: error.StatusCode });
+        return (0, createRateLimitExceededException_1.createRateLimitExceededException)({ message: error.message || 'Rate limit exceeded' });
+    }
+    if (typeof error === 'object' && error !== null && 'status' in error && error.status === 429) {
+        logger.warn('Stream rate limit exceeded [error.status === 429]');
+        return (0, createRateLimitExceededException_1.createRateLimitExceededException)({ message: 'Rate limit exceeded' });
+    }
+}
+exports.processStreamRateLimitException = processStreamRateLimitException;

package/dist-cjs/rateLimits/executeStreamRequestWithRateLimitHandling.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeStreamRequestWithRateLimitHandling = void 0;
+const promises_1 = require("node:timers/promises");
+const constants_1 = require("./constants");
+const createRateLimitExceededException_1 = require("./exception/createRateLimitExceededException");
+const processStreamRateLimitException_1 = require("./exception/processStreamRateLimitException");
+const RedisCooldown_1 = require("./RedisCooldown");
+function calculateRateLimitDelayMs(error, maxDelayMs) {
+    const retryAfterMs = typeof error.retryAfter === 'number' ? error.retryAfter + constants_1.RETRY_AFTER_BUFFER_MS : constants_1.DEFAULT_RETRY_AFTER_MS;
+    if (retryAfterMs > 0) {
+        const jitterMs = Math.floor(Math.random() * constants_1.DEFAULT_JITTER_MS);
+        return Math.min(maxDelayMs, retryAfterMs + jitterMs);
+    }
+    return Math.min(maxDelayMs, constants_1.DEFAULT_FIXED_RATE_LIMIT_DELAY_MS);
+}
+async function executeStreamRequestWithRateLimitHandling(execute, operation, context, options = {}) {
+    const { logger, redis } = context;
+    const { enableCooldown, maxAttempts, maxDelayMs, maxRetryableDelayMs } = {
+        ...constants_1.DEFAULT_OPTS_1_ATTEMPT_NO_COOLDOWN,
+        ...options,
+    };
+    let attempt = 1;
+    if (enableCooldown) {
+        const cooldownMs = await RedisCooldown_1.RedisCooldown.getRemainingMs(operation, { redis, logger });
+        if (cooldownMs > 0) {
+            logger.warn('Skipping stream request due to active rate-limit cooldown', {
+                operation,
+                cooldown: cooldownMs,
+            });
+            throw (0, createRateLimitExceededException_1.createRateLimitExceededException)({ operation, retryAfterMs: cooldownMs });
+        }
+    }
+    for (;;) {
+        try {
+            return await execute();
+        }
+        catch (error) {
+            const rateLimitError = (0, processStreamRateLimitException_1.processStreamRateLimitException)(error, logger);
+            if (!rateLimitError) {
+                throw error;
+            }
+            const retryAfterMs = calculateRateLimitDelayMs(rateLimitError, maxDelayMs);
+            if (enableCooldown) {
+                await RedisCooldown_1.RedisCooldown.setRemainingMs(operation, retryAfterMs, { redis, logger });
+            }
+            if (attempt < maxAttempts && retryAfterMs <= maxRetryableDelayMs) {
+                logger.warn('Retrying stream request after rate limit', {
+                    operation,
+                    attempt,
+                    maxAttempts,
+                    retryAfterMs,
+                    rateLimit: rateLimitError.rateLimit,
+                    rateLimitRemaining: rateLimitError.rateLimitRemaining,
+                    rateLimitReset: rateLimitError.rateLimitReset,
+                });
+                await (0, promises_1.setTimeout)(retryAfterMs);
+                attempt++;
+                continue;
+            }
+            logger.warn('Propagating stream rate limit w/o retry', {
+                operation,
+                attempt,
+                maxAttempts,
+                retryAfterMs,
+                maxRetryableDelayMs,
+                rateLimit: rateLimitError.rateLimit,
+                rateLimitRemaining: rateLimitError.rateLimitRemaining,
+                rateLimitReset: rateLimitError.rateLimitReset,
+            });
+            throw rateLimitError;
+        }
+    }
+}
+exports.executeStreamRequestWithRateLimitHandling = executeStreamRequestWithRateLimitHandling;

package/dist-cjs/rateLimits/index.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./createRateLimitedStreamProxy"), exports);

package/dist-cjs/rateLimits/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist-es/index.js

@@ -1,3 +1,4 @@
 export * from './types';
 export * from './normalization';
 export * from './stream';
+export * from './rateLimits';

package/dist-es/rateLimits/RedisCooldown.js

@@ -0,0 +1,52 @@
+import { STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX } from './constants';
+export class RedisCooldown {
+    static async getRemainingMs(cooldownKey, context) {
+        const { redis, logger } = context;
+        try {
+            const ttlMs = await redis.pttl(`${STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX}${cooldownKey}`);
+            if (ttlMs > 0) {
+                return ttlMs;
+            }
+        }
+        catch (error) {
+            logger.warn('Failed to read stream rate-limit cooldown from Redis', {
+                cooldownKey,
+                error,
+            });
+        }
+        return 0;
+    }
+    static async setRemainingMs(cooldownKey, cooldownMs, context) {
+        if (cooldownMs <= 0) {
+            return;
+        }
+        const { redis, logger } = context;
+        const redisKey = `${STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX}${cooldownKey}`;
+        try {
+            await redis.eval(`
+        local key = KEYS[1]
+        local new_ttl = tonumber(ARGV[1])
+        local current_ttl = redis.call('PTTL', key)
+
+        if current_ttl == -2 then
+          redis.call('SET', key, '1', 'PX', new_ttl)
+          return 1
+        end
+
+        if current_ttl == -1 or current_ttl < new_ttl then
+          redis.call('PEXPIRE', key, new_ttl)
+          return 2
+        end
+
+        return 0
+      `, 1, redisKey, cooldownMs.toString());
+        }
+        catch (error) {
+            logger.warn('Failed to write stream rate-limit cooldown to Redis', {
+                cooldownKey,
+                cooldownMs,
+                error,
+            });
+        }
+    }
+}

package/dist-es/rateLimits/constants.js

@@ -0,0 +1,19 @@
+export const DEFAULT_FIXED_RATE_LIMIT_DELAY_MS = 15000;
+export const DEFAULT_MAX_DELAY_MS = 15000;
+export const DEFAULT_MAX_RETRYABLE_DELAY_MS = 5000;
+export const DEFAULT_JITTER_MS = 150;
+export const RETRY_AFTER_BUFFER_MS = 1000;
+export const STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX = 'stream-rate-limit-cooldown:';
+export const DEFAULT_RETRY_AFTER_MS = 10000;
+export const DEFAULT_OPTS_1_ATTEMPT_NO_COOLDOWN = {
+    maxAttempts: 1,
+    enableCooldown: false,
+    maxDelayMs: DEFAULT_MAX_DELAY_MS,
+    maxRetryableDelayMs: DEFAULT_MAX_RETRYABLE_DELAY_MS,
+};
+export const DEFAULT_OPTS_3_ATTEMPTS_WITH_COOLDOWN = {
+    maxAttempts: 3,
+    enableCooldown: true,
+    maxDelayMs: DEFAULT_MAX_DELAY_MS,
+    maxRetryableDelayMs: DEFAULT_MAX_RETRYABLE_DELAY_MS,
+};

package/dist-es/rateLimits/createRateLimitedStreamProxy.js

@@ -0,0 +1,94 @@
+import { DEFAULT_OPTS_3_ATTEMPTS_WITH_COOLDOWN } from './constants';
+import { executeStreamRequestWithRateLimitHandling } from './executeStreamRequestWithRateLimitHandling';
+const STREAM_RATE_LIMIT_OPTIONS_MARKER = '__xbsRateLimitOptions';
+const STREAM_RATE_LIMIT_PROXY_MARKER = Symbol('xbsStreamRateLimitProxy');
+const OPERATION_DEFAULT_OPTIONS = {
+    queryChannels: DEFAULT_OPTS_3_ATTEMPTS_WITH_COOLDOWN,
+};
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function hasFunctionProperty(value, key) {
+    return key in value && typeof value[key] === 'function';
+}
+function isStreamChannelLike(value) {
+    if (!isObject(value)) {
+        return false;
+    }
+    return (hasFunctionProperty(value, 'sendMessage') &&
+        hasFunctionProperty(value, 'queryMembers') &&
+        hasFunctionProperty(value, 'updatePartial'));
+}
+function isStreamRateLimitOptionsToken(value) {
+    return isObject(value) && STREAM_RATE_LIMIT_OPTIONS_MARKER in value;
+}
+function splitCallArgsAndOptions(args) {
+    if (args.length === 0) {
+        return { callArgs: args, callOptions: {} };
+    }
+    const lastArg = args[args.length - 1];
+    if (isStreamRateLimitOptionsToken(lastArg)) {
+        return {
+            callArgs: args.slice(0, -1),
+            callOptions: lastArg[STREAM_RATE_LIMIT_OPTIONS_MARKER],
+        };
+    }
+    return { callArgs: args, callOptions: {} };
+}
+export function withStreamRateLimitOptions(options) {
+    return {
+        [STREAM_RATE_LIMIT_OPTIONS_MARKER]: options,
+    };
+}
+function createRateLimitedProxy(target, context, cache) {
+    const cached = cache.get(target);
+    if (cached) {
+        return cached;
+    }
+    const wrapResult = (result) => {
+        if (Array.isArray(result)) {
+            return result.map((item) => wrapResult(item));
+        }
+        if (!isStreamChannelLike(result)) {
+            return result;
+        }
+        const cachedResult = cache.get(result);
+        if (cachedResult) {
+            return cachedResult;
+        }
+        return createRateLimitedProxy(result, context, cache);
+    };
+    const proxy = new Proxy(target, {
+        get: (originalTarget, property, receiver) => {
+            if (property === STREAM_RATE_LIMIT_PROXY_MARKER) {
+                return true;
+            }
+            const value = Reflect.get(originalTarget, property, receiver);
+            if (typeof property !== 'string' || typeof value !== 'function') {
+                return value;
+            }
+            if (property === 'channel') {
+                return (...args) => {
+                    const channel = Reflect.apply(value, originalTarget, args);
+                    return wrapResult(channel);
+                };
+            }
+            return async (...args) => {
+                const { callArgs, callOptions } = splitCallArgsAndOptions(args);
+                const operation = property;
+                const defaultOptions = OPERATION_DEFAULT_OPTIONS[operation] || {};
+                const result = await executeStreamRequestWithRateLimitHandling(() => Reflect.apply(value, originalTarget, callArgs), operation, context, {
+                    ...defaultOptions,
+                    ...callOptions,
+                });
+                return wrapResult(result);
+            };
+        },
+    });
+    cache.set(target, proxy);
+    return proxy;
+}
+export function createRateLimitedStreamProxy(stream, context) {
+    const cache = new WeakMap();
+    return createRateLimitedProxy(stream, context, cache);
+}

package/dist-es/rateLimits/exception/createRateLimitExceededException.js

@@ -0,0 +1,14 @@
+import { RateLimitExceededException } from '@wildix/xbees-conversations-client';
+import { DEFAULT_RETRY_AFTER_MS } from '../constants';
+export function createRateLimitExceededException(options = {}) {
+    const { rateLimit, message, operation, retryAfterMs = DEFAULT_RETRY_AFTER_MS } = options;
+    const defaultMessage = operation ? `Rate limit exceeded for ${operation}` : 'Rate limit exceeded';
+    return new RateLimitExceededException({
+        $metadata: {},
+        message: message || defaultMessage,
+        rateLimitRemaining: rateLimit?.remaining || 0,
+        retryAfter: rateLimit?.reset ? rateLimit.reset - Date.now() : retryAfterMs,
+        rateLimit: rateLimit?.limit?.toString() || 'unknown',
+        rateLimitReset: rateLimit?.reset || Date.now() + retryAfterMs,
+    });
+}

package/dist-es/rateLimits/exception/processStreamRateLimitException.js

@@ -0,0 +1,27 @@
+import { createRateLimitExceededException } from './createRateLimitExceededException';
+function isStreamException(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'metadata' in error &&
+        typeof error.metadata === 'object' &&
+        error.metadata !== null &&
+        'responseCode' in error.metadata);
+}
+function isStreamAPIException(error) {
+    return typeof error === 'object' && !!error.code;
+}
+export function processStreamRateLimitException(error, logger) {
+    if (isStreamException(error) && error.metadata?.responseCode === 429) {
+        const rateLimit = error.metadata?.rateLimit;
+        logger.warn('Stream rate limit exceeded [StreamException]', { rateLimit });
+        return createRateLimitExceededException({ rateLimit, message: error.message || 'Rate limit exceeded' });
+    }
+    if (isStreamAPIException(error) && (error.code === 429 || error.StatusCode === 429)) {
+        logger.warn('Stream rate limit exceeded [StreamAPIException]', { code: error.code, StatusCode: error.StatusCode });
+        return createRateLimitExceededException({ message: error.message || 'Rate limit exceeded' });
+    }
+    if (typeof error === 'object' && error !== null && 'status' in error && error.status === 429) {
+        logger.warn('Stream rate limit exceeded [error.status === 429]');
+        return createRateLimitExceededException({ message: 'Rate limit exceeded' });
+    }
+}

package/dist-es/rateLimits/executeStreamRequestWithRateLimitHandling.js

@@ -0,0 +1,71 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { DEFAULT_FIXED_RATE_LIMIT_DELAY_MS, DEFAULT_JITTER_MS, DEFAULT_OPTS_1_ATTEMPT_NO_COOLDOWN, DEFAULT_RETRY_AFTER_MS, RETRY_AFTER_BUFFER_MS, } from './constants';
+import { createRateLimitExceededException } from './exception/createRateLimitExceededException';
+import { processStreamRateLimitException } from './exception/processStreamRateLimitException';
+import { RedisCooldown } from './RedisCooldown';
+function calculateRateLimitDelayMs(error, maxDelayMs) {
+    const retryAfterMs = typeof error.retryAfter === 'number' ? error.retryAfter + RETRY_AFTER_BUFFER_MS : DEFAULT_RETRY_AFTER_MS;
+    if (retryAfterMs > 0) {
+        const jitterMs = Math.floor(Math.random() * DEFAULT_JITTER_MS);
+        return Math.min(maxDelayMs, retryAfterMs + jitterMs);
+    }
+    return Math.min(maxDelayMs, DEFAULT_FIXED_RATE_LIMIT_DELAY_MS);
+}
+export async function executeStreamRequestWithRateLimitHandling(execute, operation, context, options = {}) {
+    const { logger, redis } = context;
+    const { enableCooldown, maxAttempts, maxDelayMs, maxRetryableDelayMs } = {
+        ...DEFAULT_OPTS_1_ATTEMPT_NO_COOLDOWN,
+        ...options,
+    };
+    let attempt = 1;
+    if (enableCooldown) {
+        const cooldownMs = await RedisCooldown.getRemainingMs(operation, { redis, logger });
+        if (cooldownMs > 0) {
+            logger.warn('Skipping stream request due to active rate-limit cooldown', {
+                operation,
+                cooldown: cooldownMs,
+            });
+            throw createRateLimitExceededException({ operation, retryAfterMs: cooldownMs });
+        }
+    }
+    for (;;) {
+        try {
+            return await execute();
+        }
+        catch (error) {
+            const rateLimitError = processStreamRateLimitException(error, logger);
+            if (!rateLimitError) {
+                throw error;
+            }
+            const retryAfterMs = calculateRateLimitDelayMs(rateLimitError, maxDelayMs);
+            if (enableCooldown) {
+                await RedisCooldown.setRemainingMs(operation, retryAfterMs, { redis, logger });
+            }
+            if (attempt < maxAttempts && retryAfterMs <= maxRetryableDelayMs) {
+                logger.warn('Retrying stream request after rate limit', {
+                    operation,
+                    attempt,
+                    maxAttempts,
+                    retryAfterMs,
+                    rateLimit: rateLimitError.rateLimit,
+                    rateLimitRemaining: rateLimitError.rateLimitRemaining,
+                    rateLimitReset: rateLimitError.rateLimitReset,
+                });
+                await sleep(retryAfterMs);
+                attempt++;
+                continue;
+            }
+            logger.warn('Propagating stream rate limit w/o retry', {
+                operation,
+                attempt,
+                maxAttempts,
+                retryAfterMs,
+                maxRetryableDelayMs,
+                rateLimit: rateLimitError.rateLimit,
+                rateLimitRemaining: rateLimitError.rateLimitRemaining,
+                rateLimitReset: rateLimitError.rateLimitReset,
+            });
+            throw rateLimitError;
+        }
+    }
+}

package/dist-es/rateLimits/index.js

@@ -0,0 +1 @@
+export * from './createRateLimitedStreamProxy';

package/dist-es/rateLimits/types.js

@@ -0,0 +1 @@
+export {};

package/dist-types/index.d.ts

@@ -1,3 +1,4 @@
 export * from './types';
 export * from './normalization';
 export * from './stream';
+export * from './rateLimits';

package/dist-types/rateLimits/RedisCooldown.d.ts

@@ -0,0 +1,5 @@
+import { LoggerContext, RedisContext } from "./types";
+export declare class RedisCooldown {
+    static getRemainingMs(cooldownKey: string, context: RedisContext & LoggerContext): Promise<number>;
+    static setRemainingMs(cooldownKey: string, cooldownMs: number, context: RedisContext & LoggerContext): Promise<void>;
+}

package/dist-types/rateLimits/constants.d.ts

@@ -0,0 +1,10 @@
+import { StreamRateLimitRetryOptions } from './types';
+export declare const DEFAULT_FIXED_RATE_LIMIT_DELAY_MS = 15000;
+export declare const DEFAULT_MAX_DELAY_MS = 15000;
+export declare const DEFAULT_MAX_RETRYABLE_DELAY_MS = 5000;
+export declare const DEFAULT_JITTER_MS = 150;
+export declare const RETRY_AFTER_BUFFER_MS = 1000;
+export declare const STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX = "stream-rate-limit-cooldown:";
+export declare const DEFAULT_RETRY_AFTER_MS = 10000;
+export declare const DEFAULT_OPTS_1_ATTEMPT_NO_COOLDOWN: StreamRateLimitRetryOptions;
+export declare const DEFAULT_OPTS_3_ATTEMPTS_WITH_COOLDOWN: StreamRateLimitRetryOptions;

package/dist-types/rateLimits/createRateLimitedStreamProxy.d.ts

@@ -0,0 +1,15 @@
+import { StreamChat } from 'stream-chat';
+import { LoggerContext, RedisContext } from './types';
+import { StreamRateLimitRetryOptions } from './types';
+import { StreamType } from "../stream";
+declare const STREAM_RATE_LIMIT_OPTIONS_MARKER = "__xbsRateLimitOptions";
+type StreamRateLimitOptionsToken = {
+    [STREAM_RATE_LIMIT_OPTIONS_MARKER]: Partial<StreamRateLimitRetryOptions>;
+};
+type MethodWithRateLimitOptions<T> = T extends (...args: infer Args) => infer Result ? T & ((...args: [...Args, StreamRateLimitOptionsToken?]) => Result) : T;
+export type RateLimited<T extends object> = {
+    [Key in keyof T]: MethodWithRateLimitOptions<T[Key]>;
+};
+export declare function withStreamRateLimitOptions(options: Partial<StreamRateLimitRetryOptions>): StreamRateLimitOptionsToken;
+export declare function createRateLimitedStreamProxy(stream: StreamChat<StreamType>, context: LoggerContext & RedisContext): RateLimited<StreamChat<StreamType>>;
+export {};

package/dist-types/rateLimits/exception/createRateLimitExceededException.d.ts

@@ -0,0 +1,10 @@
+import { RateLimitExceededException } from '@wildix/xbees-conversations-client';
+import { RateLimitsInfo } from 'stream-chat';
+type Options = {
+    rateLimit?: RateLimitsInfo;
+    message?: string;
+    operation?: string;
+    retryAfterMs?: number;
+};
+export declare function createRateLimitExceededException(options?: Options): RateLimitExceededException;
+export {};

package/dist-types/rateLimits/exception/processStreamRateLimitException.d.ts

@@ -0,0 +1,3 @@
+import { RateLimitExceededException } from '@wildix/xbees-conversations-client';
+import { Logger } from '@aws-lambda-powertools/logger';
+export declare function processStreamRateLimitException(error: unknown, logger: Logger): RateLimitExceededException | undefined;

package/dist-types/rateLimits/executeStreamRequestWithRateLimitHandling.d.ts

@@ -0,0 +1,2 @@
+import { LoggerContext, RedisContext, StreamOperationType, StreamRateLimitRetryOptions } from './types';
+export declare function executeStreamRequestWithRateLimitHandling<T>(execute: () => Promise<T>, operation: StreamOperationType, context: LoggerContext & RedisContext, options?: Partial<StreamRateLimitRetryOptions>): Promise<T>;

package/dist-types/rateLimits/index.d.ts

@@ -0,0 +1 @@
+export * from './createRateLimitedStreamProxy';

package/dist-types/rateLimits/types.d.ts

@@ -0,0 +1,17 @@
+import { StreamChat } from 'stream-chat';
+import { StreamChannel, StreamType } from "../stream";
+import Redis from 'ioredis';
+import { Logger } from "@aws-lambda-powertools/logger";
+export type StreamOperationType = keyof StreamChat<StreamType> | keyof StreamChannel;
+export interface StreamRateLimitRetryOptions {
+    maxAttempts: number;
+    maxDelayMs: number;
+    maxRetryableDelayMs: number;
+    enableCooldown: boolean;
+}
+export type RedisContext = {
+    redis: Redis;
+};
+export type LoggerContext = {
+    logger: Logger;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildix/xbees-conversations-utils",
-  "version": "1.1.55",
+  "version": "1.1.56",
   "description": "",
   "main": "./dist-cjs/index.js",
   "module": "./dist-es/index.js",
@@ -21,8 +21,10 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
+    "@aws-lambda-powertools/logger": "^2.31.0",
     "@wildix/xbees-conversations-client": "1.2.5",
-    "stream-chat": "8.60.0",
+    "ioredis": "^5.10.0",
+    "stream-chat": "8.12.1",
     "tslib": "^2.5.0"
   },
   "devDependencies": {