@wildix/xbees-conversations-utils 1.1.69 → 1.1.71

package/dist-cjs/rateLimits/constants.js

@@ -1,12 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_OPTIONS = exports.CHANNEL_SYNC_PROXY_RESULT_METHOD_NAMES = exports.CHANNEL_SYNC_METHOD_NAMES = exports.STREAM_SYNC_METHOD_NAMES = exports.STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES = exports.STREAM_RATE_LIMIT_OPTIONS_MARKER = exports.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX = exports.RETRY_AFTER_BUFFER_MS = exports.DEFAULT_JITTER_MS = exports.DEFAULT_RETRY_AFTER_MS = exports.DEFAULT_MAX_DELAY_MS = void 0;
+exports.DEFAULT_OPTIONS = exports.CHANNEL_SYNC_PROXY_RESULT_METHOD_NAMES = exports.CHANNEL_SYNC_METHOD_NAMES = exports.STREAM_SYNC_METHOD_NAMES = exports.STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES = exports.BUDGET_DELAY_MAX_MS = exports.BUDGET_DELAY_MIN_MS = exports.BUDGET_THRESHOLD = exports.STREAM_BUDGET_COOLDOWN_KEY = exports.STREAM_RATE_LIMIT_OPTIONS_MARKER = exports.STREAM_BUDGET_COOLDOWN_KEY_PREFIX = exports.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX = exports.RETRY_AFTER_BUFFER_MS = exports.DEFAULT_JITTER_MS = exports.DEFAULT_RETRY_AFTER_MS = exports.DEFAULT_MAX_DELAY_MS = void 0;
 exports.DEFAULT_MAX_DELAY_MS = 5000;
 exports.DEFAULT_RETRY_AFTER_MS = 10000;
 exports.DEFAULT_JITTER_MS = 150;
 exports.RETRY_AFTER_BUFFER_MS = 1000;
 exports.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX = 'stream-rate-limit-cooldown:';
+exports.STREAM_BUDGET_COOLDOWN_KEY_PREFIX = 'stream-budget-cooldown:';
 exports.STREAM_RATE_LIMIT_OPTIONS_MARKER = '__xbsRateLimitOptions';
+exports.STREAM_BUDGET_COOLDOWN_KEY = 'stream-budget-global';
+exports.BUDGET_THRESHOLD = 0.8;
+exports.BUDGET_DELAY_MIN_MS = 30000;
+exports.BUDGET_DELAY_MAX_MS = 60000;
 exports.STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES = [
     'channel',
     'getChannelById',

package/dist-cjs/rateLimits/createRateLimitedStreamProxy.js

@@ -4,6 +4,7 @@ exports.createRateLimitedStreamProxy = void 0;
 const constants_1 = require("./constants");
 const executeWithRateLimitHandling_1 = require("./helpers/executeWithRateLimitHandling");
 const isStreamChannelLike_1 = require("./helpers/isStreamChannelLike");
+const registerStreamBudgetInterceptors_1 = require("./helpers/registerStreamBudgetInterceptors");
 const splitCallArgsAndOptions_1 = require("./helpers/splitCallArgsAndOptions");
 const STREAM_SYNC_METHODS = new Set(constants_1.STREAM_SYNC_METHOD_NAMES);
 const STREAM_SYNC_CHANNEL_RESULT_METHODS = new Set(constants_1.STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES);
@@ -64,6 +65,7 @@ function wrapTarget(target, dependencies) {
     return proxy;
 }
 function createRateLimitedStreamProxy(stream, context) {
+    (0, registerStreamBudgetInterceptors_1.registerStreamBudgetInterceptors)(stream, context);
     return wrapTarget(stream, {
         context,
         cache: new WeakMap(),

package/dist-cjs/rateLimits/helpers/RedisCooldown.js

@@ -3,10 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RedisCooldown = void 0;
 const constants_1 = require("../constants");
 class RedisCooldown {
-    static async getRemainingMs(cooldownKey, context) {
+    static resolveRedisKey(cooldownKey, options) {
+        const keyPrefix = options?.keyPrefix ?? constants_1.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX;
+        return `${keyPrefix}${cooldownKey}`;
+    }
+    static async getRemainingMs(cooldownKey, context, options) {
         const { redis, logger } = context;
         try {
-            const ttlMs = await redis.pttl(`${constants_1.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX}${cooldownKey}`);
+            const ttlMs = await redis.pttl(RedisCooldown.resolveRedisKey(cooldownKey, options));
             if (ttlMs > 0) {
                 return ttlMs;
             }
@@ -19,12 +23,12 @@ class RedisCooldown {
         }
         return 0;
     }
-    static async setRemainingMs(cooldownKey, cooldownMs, context) {
+    static async setRemainingMs(cooldownKey, cooldownMs, context, options) {
         if (cooldownMs <= 0) {
             return;
         }
         const { redis, logger } = context;
-        const redisKey = `${constants_1.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX}${cooldownKey}`;
+        const redisKey = RedisCooldown.resolveRedisKey(cooldownKey, options);
         try {
             await redis.eval(`
         local key = KEYS[1]
@@ -52,5 +56,17 @@ class RedisCooldown {
             });
         }
     }
+    static async clear(cooldownKey, context, options) {
+        const { redis, logger } = context;
+        try {
+            await redis.del(RedisCooldown.resolveRedisKey(cooldownKey, options));
+        }
+        catch (error) {
+            logger.warn('Failed to clear stream rate-limit cooldown from Redis', {
+                cooldownKey,
+                error,
+            });
+        }
+    }
 }
 exports.RedisCooldown = RedisCooldown;

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

@@ -3,16 +3,23 @@ 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 toPositiveSeconds(milliseconds) {
+    return Math.max(0, Math.ceil(milliseconds / 1000));
+}
 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';
+    const retryAfterFromResetMs = rateLimit?.reset ? rateLimit.reset - Date.now() : undefined;
+    const effectiveRetryAfterMs = retryAfterFromResetMs ?? retryAfterMs;
+    const retryAfterSeconds = toPositiveSeconds(effectiveRetryAfterMs);
+    const rateLimitResetSeconds = rateLimit?.reset ? toPositiveSeconds(retryAfterFromResetMs ?? 0) : retryAfterSeconds;
     return new xbees_conversations_client_1.RateLimitExceededException({
         $metadata: {},
         message: message || defaultMessage,
         rateLimitRemaining: rateLimit?.remaining || 0,
-        retryAfter: rateLimit?.reset ? rateLimit.reset - Date.now() : retryAfterMs,
+        retryAfter: retryAfterSeconds,
         rateLimit: rateLimit?.limit?.toString() || 'unknown',
-        rateLimitReset: rateLimit?.reset || Date.now() + retryAfterMs,
+        rateLimitReset: rateLimitResetSeconds,
     });
 }
 exports.createRateLimitExceededException = createRateLimitExceededException;

package/dist-cjs/rateLimits/helpers/executeWithRateLimitHandling.js

@@ -8,7 +8,8 @@ const processStreamRateLimitException_1 = require("./processStreamRateLimitExcep
 const RedisCooldown_1 = require("./RedisCooldown");
 function calculateRateLimitDelayMs(error, maxDelayMs) {
     const hasServerRetryAfter = typeof error.retryAfter === 'number' && error.retryAfter > 0;
-    const baseDelayMs = hasServerRetryAfter ? error.retryAfter + constants_1.RETRY_AFTER_BUFFER_MS : constants_1.DEFAULT_RETRY_AFTER_MS;
+    const retryAfterMsFromError = hasServerRetryAfter ? Math.round(error.retryAfter * 1000) : 0;
+    const baseDelayMs = hasServerRetryAfter ? retryAfterMsFromError + constants_1.RETRY_AFTER_BUFFER_MS : constants_1.DEFAULT_RETRY_AFTER_MS;
     if (baseDelayMs > 0) {
         const jitterMs = Math.floor(Math.random() * constants_1.DEFAULT_JITTER_MS);
         const computedDelayMs = baseDelayMs + jitterMs;
@@ -24,6 +25,14 @@ async function executeWithRateLimitHandling(execute, operation, context, options
     const { enableCooldown, maxAttempts, maxDelayMs, maxRetryableDelayMs } = options;
     let attempt = 1;
     if (enableCooldown) {
+        const budgetCooldownMs = await RedisCooldown_1.RedisCooldown.getRemainingMs(constants_1.STREAM_BUDGET_COOLDOWN_KEY, { redis, logger }, { keyPrefix: constants_1.STREAM_BUDGET_COOLDOWN_KEY_PREFIX });
+        if (budgetCooldownMs > 0) {
+            logger.warn('Delaying stream request due to active budget cooldown', {
+                operation,
+                cooldown: budgetCooldownMs,
+            });
+            await (0, promises_1.setTimeout)(budgetCooldownMs);
+        }
         const cooldownMs = await RedisCooldown_1.RedisCooldown.getRemainingMs(operation, { redis, logger });
         if (cooldownMs > 0) {
             logger.warn('Skipping stream request due to active rate-limit cooldown', {

package/dist-cjs/rateLimits/helpers/processStreamBudgetHeaders.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processStreamBudgetHeaders = void 0;
+const constants_1 = require("../constants");
+const RedisCooldown_1 = require("./RedisCooldown");
+function parseHeaderNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+}
+function getHeaderCaseInsensitive(headers, key) {
+    if (!headers) {
+        return;
+    }
+    const direct = headers[key];
+    if (direct !== undefined) {
+        return direct;
+    }
+    const normalizedKey = key.toLowerCase();
+    for (const [headerKey, headerValue] of Object.entries(headers)) {
+        if (headerKey.toLowerCase() === normalizedKey) {
+            return headerValue;
+        }
+    }
+}
+function extractBudgetHeaders(headers) {
+    return {
+        limitMs: parseHeaderNumber(getHeaderCaseInsensitive(headers, 'x-budget-limit-ms')),
+        remainingMs: parseHeaderNumber(getHeaderCaseInsensitive(headers, 'x-budget-remaining-ms')),
+        usedMs: parseHeaderNumber(getHeaderCaseInsensitive(headers, 'x-budget-used-ms')),
+    };
+}
+function isBudgetThresholdReached(limitMs, remainingMs, usedMs) {
+    if (limitMs <= 0) {
+        return false;
+    }
+    if (typeof usedMs === 'number' && usedMs / limitMs >= constants_1.BUDGET_THRESHOLD) {
+        return true;
+    }
+    if (typeof remainingMs === 'number') {
+        const remainingThreshold = Math.ceil((1 - constants_1.BUDGET_THRESHOLD) * limitMs);
+        return remainingMs <= remainingThreshold;
+    }
+    return false;
+}
+function getBudgetDelayMs() {
+    return Math.round(constants_1.BUDGET_DELAY_MIN_MS + Math.random() * (constants_1.BUDGET_DELAY_MAX_MS - constants_1.BUDGET_DELAY_MIN_MS));
+}
+async function processStreamBudgetHeaders(headers, context) {
+    const { logger } = context;
+    const { limitMs, remainingMs, usedMs } = extractBudgetHeaders(headers);
+    if (limitMs === undefined && remainingMs === undefined && usedMs === undefined) {
+        return;
+    }
+    if (typeof limitMs !== 'number' || !Number.isFinite(limitMs)) {
+        return;
+    }
+    const thresholdReached = isBudgetThresholdReached(limitMs, remainingMs, usedMs);
+    if (thresholdReached) {
+        const delayMs = getBudgetDelayMs();
+        await RedisCooldown_1.RedisCooldown.setRemainingMs(constants_1.STREAM_BUDGET_COOLDOWN_KEY, delayMs, context, {
+            keyPrefix: constants_1.STREAM_BUDGET_COOLDOWN_KEY_PREFIX,
+        });
+        logger.warn('Stream budget threshold reached, enabling cooldown', {
+            budgetLimitMs: limitMs,
+            budgetRemainingMs: remainingMs,
+            budgetUsedMs: usedMs,
+            cooldownMs: delayMs,
+        });
+        return;
+    }
+    await RedisCooldown_1.RedisCooldown.clear(constants_1.STREAM_BUDGET_COOLDOWN_KEY, context, {
+        keyPrefix: constants_1.STREAM_BUDGET_COOLDOWN_KEY_PREFIX,
+    });
+    logger.warn('Stream budget is below threshold, disabling cooldown', {
+        budgetLimitMs: limitMs,
+        budgetRemainingMs: remainingMs,
+        budgetUsedMs: usedMs,
+    });
+}
+exports.processStreamBudgetHeaders = processStreamBudgetHeaders;

package/dist-cjs/rateLimits/helpers/registerStreamBudgetInterceptors.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerStreamBudgetInterceptors = void 0;
+const processStreamBudgetHeaders_1 = require("./processStreamBudgetHeaders");
+const attachedInterceptors = new WeakSet();
+function hasResponseInterceptors(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.interceptors?.response?.use === 'function');
+}
+function resolveAxiosInstance(stream) {
+    if (hasResponseInterceptors(stream)) {
+        return stream;
+    }
+    if (typeof stream !== 'object' || stream === null) {
+        return;
+    }
+    const maybeStream = stream;
+    if (hasResponseInterceptors(maybeStream.axiosInstance)) {
+        return maybeStream.axiosInstance;
+    }
+    if (hasResponseInterceptors(maybeStream._client?.axiosInstance)) {
+        return maybeStream._client?.axiosInstance;
+    }
+}
+function registerStreamBudgetInterceptors(stream, context) {
+    const { logger } = context;
+    const axiosInstance = resolveAxiosInstance(stream);
+    if (!axiosInstance || !axiosInstance.interceptors?.response?.use) {
+        logger.warn('Unable to register stream budget interceptor: axios instance not found');
+        return;
+    }
+    if (attachedInterceptors.has(axiosInstance)) {
+        return;
+    }
+    axiosInstance.interceptors.response.use(async (response) => {
+        await (0, processStreamBudgetHeaders_1.processStreamBudgetHeaders)(response?.headers, context);
+        return response;
+    }, async (error) => {
+        await (0, processStreamBudgetHeaders_1.processStreamBudgetHeaders)(error?.response?.headers, context);
+        return Promise.reject(error);
+    });
+    attachedInterceptors.add(axiosInstance);
+}
+exports.registerStreamBudgetInterceptors = registerStreamBudgetInterceptors;

package/dist-cjs/rateLimits/index.js

@@ -2,6 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./createRateLimitedStreamProxy"), exports);
-tslib_1.__exportStar(require("./withStreamRateLimitOptions"), exports);
 tslib_1.__exportStar(require("./helpers/createRateLimitExceededException"), exports);
 tslib_1.__exportStar(require("./helpers/processStreamRateLimitException"), exports);
+tslib_1.__exportStar(require("./withStreamRateLimitOptions"), exports);

package/dist-es/rateLimits/constants.js

@@ -3,7 +3,12 @@ export const DEFAULT_RETRY_AFTER_MS = 10000;
 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 STREAM_BUDGET_COOLDOWN_KEY_PREFIX = 'stream-budget-cooldown:';
 export const STREAM_RATE_LIMIT_OPTIONS_MARKER = '__xbsRateLimitOptions';
+export const STREAM_BUDGET_COOLDOWN_KEY = 'stream-budget-global';
+export const BUDGET_THRESHOLD = 0.8;
+export const BUDGET_DELAY_MIN_MS = 30000;
+export const BUDGET_DELAY_MAX_MS = 60000;
 export const STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES = [
     'channel',
     'getChannelById',

package/dist-es/rateLimits/createRateLimitedStreamProxy.js

@@ -1,6 +1,7 @@
 import { CHANNEL_SYNC_METHOD_NAMES, CHANNEL_SYNC_PROXY_RESULT_METHOD_NAMES, DEFAULT_OPTIONS, STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES, STREAM_SYNC_METHOD_NAMES, } from './constants';
 import { executeWithRateLimitHandling } from './helpers/executeWithRateLimitHandling';
 import { isStreamChannelLike } from './helpers/isStreamChannelLike';
+import { registerStreamBudgetInterceptors } from './helpers/registerStreamBudgetInterceptors';
 import { splitCallArgsAndOptions } from './helpers/splitCallArgsAndOptions';
 const STREAM_SYNC_METHODS = new Set(STREAM_SYNC_METHOD_NAMES);
 const STREAM_SYNC_CHANNEL_RESULT_METHODS = new Set(STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES);
@@ -61,6 +62,7 @@ function wrapTarget(target, dependencies) {
     return proxy;
 }
 export function createRateLimitedStreamProxy(stream, context) {
+    registerStreamBudgetInterceptors(stream, context);
     return wrapTarget(stream, {
         context,
         cache: new WeakMap(),

package/dist-es/rateLimits/helpers/RedisCooldown.js

@@ -1,9 +1,13 @@
 import { STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX } from '../constants';
 export class RedisCooldown {
-    static async getRemainingMs(cooldownKey, context) {
+    static resolveRedisKey(cooldownKey, options) {
+        const keyPrefix = options?.keyPrefix ?? STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX;
+        return `${keyPrefix}${cooldownKey}`;
+    }
+    static async getRemainingMs(cooldownKey, context, options) {
         const { redis, logger } = context;
         try {
-            const ttlMs = await redis.pttl(`${STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX}${cooldownKey}`);
+            const ttlMs = await redis.pttl(RedisCooldown.resolveRedisKey(cooldownKey, options));
             if (ttlMs > 0) {
                 return ttlMs;
             }
@@ -16,12 +20,12 @@ export class RedisCooldown {
         }
         return 0;
     }
-    static async setRemainingMs(cooldownKey, cooldownMs, context) {
+    static async setRemainingMs(cooldownKey, cooldownMs, context, options) {
         if (cooldownMs <= 0) {
             return;
         }
         const { redis, logger } = context;
-        const redisKey = `${STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX}${cooldownKey}`;
+        const redisKey = RedisCooldown.resolveRedisKey(cooldownKey, options);
         try {
             await redis.eval(`
         local key = KEYS[1]
@@ -49,4 +53,16 @@ export class RedisCooldown {
             });
         }
     }
+    static async clear(cooldownKey, context, options) {
+        const { redis, logger } = context;
+        try {
+            await redis.del(RedisCooldown.resolveRedisKey(cooldownKey, options));
+        }
+        catch (error) {
+            logger.warn('Failed to clear stream rate-limit cooldown from Redis', {
+                cooldownKey,
+                error,
+            });
+        }
+    }
 }

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

@@ -1,14 +1,21 @@
 import { RateLimitExceededException } from '@wildix/xbees-conversations-client';
 import { DEFAULT_RETRY_AFTER_MS } from '../constants';
+function toPositiveSeconds(milliseconds) {
+    return Math.max(0, Math.ceil(milliseconds / 1000));
+}
 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';
+    const retryAfterFromResetMs = rateLimit?.reset ? rateLimit.reset - Date.now() : undefined;
+    const effectiveRetryAfterMs = retryAfterFromResetMs ?? retryAfterMs;
+    const retryAfterSeconds = toPositiveSeconds(effectiveRetryAfterMs);
+    const rateLimitResetSeconds = rateLimit?.reset ? toPositiveSeconds(retryAfterFromResetMs ?? 0) : retryAfterSeconds;
     return new RateLimitExceededException({
         $metadata: {},
         message: message || defaultMessage,
         rateLimitRemaining: rateLimit?.remaining || 0,
-        retryAfter: rateLimit?.reset ? rateLimit.reset - Date.now() : retryAfterMs,
+        retryAfter: retryAfterSeconds,
         rateLimit: rateLimit?.limit?.toString() || 'unknown',
-        rateLimitReset: rateLimit?.reset || Date.now() + retryAfterMs,
+        rateLimitReset: rateLimitResetSeconds,
     });
 }

package/dist-es/rateLimits/helpers/executeWithRateLimitHandling.js

@@ -1,11 +1,12 @@
 import { setTimeout as sleep } from 'node:timers/promises';
-import { DEFAULT_MAX_DELAY_MS, DEFAULT_JITTER_MS, DEFAULT_RETRY_AFTER_MS, RETRY_AFTER_BUFFER_MS, } from '../constants';
+import { DEFAULT_JITTER_MS, DEFAULT_MAX_DELAY_MS, DEFAULT_RETRY_AFTER_MS, RETRY_AFTER_BUFFER_MS, STREAM_BUDGET_COOLDOWN_KEY, STREAM_BUDGET_COOLDOWN_KEY_PREFIX, } from '../constants';
 import { createRateLimitExceededException } from './createRateLimitExceededException';
 import { processStreamRateLimitException } from './processStreamRateLimitException';
 import { RedisCooldown } from './RedisCooldown';
 function calculateRateLimitDelayMs(error, maxDelayMs) {
     const hasServerRetryAfter = typeof error.retryAfter === 'number' && error.retryAfter > 0;
-    const baseDelayMs = hasServerRetryAfter ? error.retryAfter + RETRY_AFTER_BUFFER_MS : DEFAULT_RETRY_AFTER_MS;
+    const retryAfterMsFromError = hasServerRetryAfter ? Math.round(error.retryAfter * 1000) : 0;
+    const baseDelayMs = hasServerRetryAfter ? retryAfterMsFromError + RETRY_AFTER_BUFFER_MS : DEFAULT_RETRY_AFTER_MS;
     if (baseDelayMs > 0) {
         const jitterMs = Math.floor(Math.random() * DEFAULT_JITTER_MS);
         const computedDelayMs = baseDelayMs + jitterMs;
@@ -21,6 +22,14 @@ export async function executeWithRateLimitHandling(execute, operation, context,
     const { enableCooldown, maxAttempts, maxDelayMs, maxRetryableDelayMs } = options;
     let attempt = 1;
     if (enableCooldown) {
+        const budgetCooldownMs = await RedisCooldown.getRemainingMs(STREAM_BUDGET_COOLDOWN_KEY, { redis, logger }, { keyPrefix: STREAM_BUDGET_COOLDOWN_KEY_PREFIX });
+        if (budgetCooldownMs > 0) {
+            logger.warn('Delaying stream request due to active budget cooldown', {
+                operation,
+                cooldown: budgetCooldownMs,
+            });
+            await sleep(budgetCooldownMs);
+        }
         const cooldownMs = await RedisCooldown.getRemainingMs(operation, { redis, logger });
         if (cooldownMs > 0) {
             logger.warn('Skipping stream request due to active rate-limit cooldown', {

package/dist-es/rateLimits/helpers/processStreamBudgetHeaders.js

@@ -0,0 +1,83 @@
+import { BUDGET_DELAY_MAX_MS, BUDGET_DELAY_MIN_MS, BUDGET_THRESHOLD, STREAM_BUDGET_COOLDOWN_KEY, STREAM_BUDGET_COOLDOWN_KEY_PREFIX, } from '../constants';
+import { RedisCooldown } from './RedisCooldown';
+function parseHeaderNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+}
+function getHeaderCaseInsensitive(headers, key) {
+    if (!headers) {
+        return;
+    }
+    const direct = headers[key];
+    if (direct !== undefined) {
+        return direct;
+    }
+    const normalizedKey = key.toLowerCase();
+    for (const [headerKey, headerValue] of Object.entries(headers)) {
+        if (headerKey.toLowerCase() === normalizedKey) {
+            return headerValue;
+        }
+    }
+}
+function extractBudgetHeaders(headers) {
+    return {
+        limitMs: parseHeaderNumber(getHeaderCaseInsensitive(headers, 'x-budget-limit-ms')),
+        remainingMs: parseHeaderNumber(getHeaderCaseInsensitive(headers, 'x-budget-remaining-ms')),
+        usedMs: parseHeaderNumber(getHeaderCaseInsensitive(headers, 'x-budget-used-ms')),
+    };
+}
+function isBudgetThresholdReached(limitMs, remainingMs, usedMs) {
+    if (limitMs <= 0) {
+        return false;
+    }
+    if (typeof usedMs === 'number' && usedMs / limitMs >= BUDGET_THRESHOLD) {
+        return true;
+    }
+    if (typeof remainingMs === 'number') {
+        const remainingThreshold = Math.ceil((1 - BUDGET_THRESHOLD) * limitMs);
+        return remainingMs <= remainingThreshold;
+    }
+    return false;
+}
+function getBudgetDelayMs() {
+    return Math.round(BUDGET_DELAY_MIN_MS + Math.random() * (BUDGET_DELAY_MAX_MS - BUDGET_DELAY_MIN_MS));
+}
+export async function processStreamBudgetHeaders(headers, context) {
+    const { logger } = context;
+    const { limitMs, remainingMs, usedMs } = extractBudgetHeaders(headers);
+    if (limitMs === undefined && remainingMs === undefined && usedMs === undefined) {
+        return;
+    }
+    if (typeof limitMs !== 'number' || !Number.isFinite(limitMs)) {
+        return;
+    }
+    const thresholdReached = isBudgetThresholdReached(limitMs, remainingMs, usedMs);
+    if (thresholdReached) {
+        const delayMs = getBudgetDelayMs();
+        await RedisCooldown.setRemainingMs(STREAM_BUDGET_COOLDOWN_KEY, delayMs, context, {
+            keyPrefix: STREAM_BUDGET_COOLDOWN_KEY_PREFIX,
+        });
+        logger.warn('Stream budget threshold reached, enabling cooldown', {
+            budgetLimitMs: limitMs,
+            budgetRemainingMs: remainingMs,
+            budgetUsedMs: usedMs,
+            cooldownMs: delayMs,
+        });
+        return;
+    }
+    await RedisCooldown.clear(STREAM_BUDGET_COOLDOWN_KEY, context, {
+        keyPrefix: STREAM_BUDGET_COOLDOWN_KEY_PREFIX,
+    });
+    logger.warn('Stream budget is below threshold, disabling cooldown', {
+        budgetLimitMs: limitMs,
+        budgetRemainingMs: remainingMs,
+        budgetUsedMs: usedMs,
+    });
+}

package/dist-es/rateLimits/helpers/registerStreamBudgetInterceptors.js

@@ -0,0 +1,41 @@
+import { processStreamBudgetHeaders } from './processStreamBudgetHeaders';
+const attachedInterceptors = new WeakSet();
+function hasResponseInterceptors(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.interceptors?.response?.use === 'function');
+}
+function resolveAxiosInstance(stream) {
+    if (hasResponseInterceptors(stream)) {
+        return stream;
+    }
+    if (typeof stream !== 'object' || stream === null) {
+        return;
+    }
+    const maybeStream = stream;
+    if (hasResponseInterceptors(maybeStream.axiosInstance)) {
+        return maybeStream.axiosInstance;
+    }
+    if (hasResponseInterceptors(maybeStream._client?.axiosInstance)) {
+        return maybeStream._client?.axiosInstance;
+    }
+}
+export function registerStreamBudgetInterceptors(stream, context) {
+    const { logger } = context;
+    const axiosInstance = resolveAxiosInstance(stream);
+    if (!axiosInstance || !axiosInstance.interceptors?.response?.use) {
+        logger.warn('Unable to register stream budget interceptor: axios instance not found');
+        return;
+    }
+    if (attachedInterceptors.has(axiosInstance)) {
+        return;
+    }
+    axiosInstance.interceptors.response.use(async (response) => {
+        await processStreamBudgetHeaders(response?.headers, context);
+        return response;
+    }, async (error) => {
+        await processStreamBudgetHeaders(error?.response?.headers, context);
+        return Promise.reject(error);
+    });
+    attachedInterceptors.add(axiosInstance);
+}

package/dist-es/rateLimits/index.js

@@ -1,4 +1,4 @@
 export * from './createRateLimitedStreamProxy';
-export * from './withStreamRateLimitOptions';
 export * from './helpers/createRateLimitExceededException';
 export * from './helpers/processStreamRateLimitException';
+export * from './withStreamRateLimitOptions';

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

@@ -4,7 +4,12 @@ export declare const DEFAULT_RETRY_AFTER_MS = 10000;
 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 STREAM_BUDGET_COOLDOWN_KEY_PREFIX = "stream-budget-cooldown:";
 export declare const STREAM_RATE_LIMIT_OPTIONS_MARKER = "__xbsRateLimitOptions";
+export declare const STREAM_BUDGET_COOLDOWN_KEY = "stream-budget-global";
+export declare const BUDGET_THRESHOLD = 0.8;
+export declare const BUDGET_DELAY_MIN_MS = 30000;
+export declare const BUDGET_DELAY_MAX_MS = 60000;
 export declare const STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES: readonly ["channel", "getChannelById", "getChannelByMembers", "hydrateActiveChannels"];
 export declare const STREAM_SYNC_METHOD_NAMES: readonly ["_addChannelConfig", "_buildWSPayload", "_callClientListeners", "_deleteUserMessageReference", "_enrichAxiosOptions", "_getConnectionID", "_getToken", "_handleClientEvent", "_handleUserEvent", "_hasConnectionID", "_isUsingServerAuth", "_logApiError", "_logApiRequest", "_logApiResponse", "_muteStatus", "_normalizeDate", "_normalizeExpiration", "_sayHi", "_setUser", "_startCleaning", "_updateMemberWatcherReferences", "_updateUserMessageReferences", "_updateUserReferences", "_validateAndGetMessageId", "createAbortControllerForNextRequest", "createToken", "devToken", "dispatchEvent", "errorFromResponse", "getAuthType", "getUserAgent", "handleEvent", "handleResponse", "off", "on", "setBaseURL", "setLocalDevice", "setUserAgent", "userMuteStatus", "verifyWebhook"];
 export declare const CHANNEL_SYNC_METHOD_NAMES: readonly ["_channelURL", "countUnread", "countUnreadMentions", "getConfig", "lastMessage", "lastRead", "muteStatus", "off", "on"];

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

@@ -1,5 +1,7 @@
-import { LoggerContext, RedisContext } from '../types';
+import { LoggerContext, RedisContext, RedisCooldownOptions } 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>;
+    private static resolveRedisKey;
+    static getRemainingMs(cooldownKey: string, context: RedisContext & LoggerContext, options?: RedisCooldownOptions): Promise<number>;
+    static setRemainingMs(cooldownKey: string, cooldownMs: number, context: RedisContext & LoggerContext, options?: RedisCooldownOptions): Promise<void>;
+    static clear(cooldownKey: string, context: RedisContext & LoggerContext, options?: RedisCooldownOptions): Promise<void>;
 }

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

@@ -0,0 +1,8 @@
+import { LoggerContext, RedisContext, StreamHeaders } from '../types';
+/**
+ * Updates app-wide Stream budget cooldown in Redis based on x-budget-* headers.
+ * - If budget usage reaches the threshold (>=80%), enables cooldown for 30-60s.
+ * - If headers indicate usage is below threshold, disables existing cooldown.
+ * - If headers are missing/invalid, leaves current cooldown unchanged.
+ */
+export declare function processStreamBudgetHeaders(headers: StreamHeaders | undefined, context: LoggerContext & RedisContext): Promise<void>;

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

@@ -0,0 +1,2 @@
+import { LoggerContext, RedisContext } from '../types';
+export declare function registerStreamBudgetInterceptors(stream: unknown, context: LoggerContext & RedisContext): void;

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

@@ -1,4 +1,4 @@
 export * from './createRateLimitedStreamProxy';
-export * from './withStreamRateLimitOptions';
 export * from './helpers/createRateLimitExceededException';
 export * from './helpers/processStreamRateLimitException';
+export * from './withStreamRateLimitOptions';

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

@@ -24,3 +24,40 @@ export type ArgsAndOptions = {
     callArgs: unknown[];
     callOptions: Partial<StreamRateLimitRetryOptions>;
 };
+/** Optional Redis key namespace override for cooldown records. */
+export type RedisCooldownOptions = {
+    keyPrefix?: string;
+};
+/** Generic HTTP headers shape returned by the Stream SDK transport layer. */
+export type StreamHeaders = Record<string, unknown>;
+/** Parsed GetStream budget headers used to manage app-wide cooldown. */
+export type StreamBudgetHeaders = {
+    limitMs?: number;
+    remainingMs?: number;
+    usedMs?: number;
+};
+/** Axios response shape used by budget interceptor. */
+export type StreamBudgetInterceptorResponse = {
+    headers?: StreamHeaders;
+};
+/** Axios error shape used by budget interceptor. */
+export type StreamBudgetInterceptorError = {
+    response?: StreamBudgetInterceptorResponse;
+};
+/** Minimal axios response interceptor manager contract required by this package. */
+export type AxiosResponseInterceptorManagerLike = {
+    use: (onFulfilled?: (response: StreamBudgetInterceptorResponse) => unknown | Promise<unknown>, onRejected?: (error: StreamBudgetInterceptorError) => unknown | Promise<unknown>) => unknown;
+};
+/** Minimal axios instance contract required to register budget interceptors. */
+export type AxiosLikeWithResponseInterceptors = {
+    interceptors?: {
+        response?: AxiosResponseInterceptorManagerLike;
+    };
+};
+/** Stream client variants where axios transport can be discovered. */
+export type StreamClientWithAxiosCandidates = {
+    axiosInstance?: unknown;
+    _client?: {
+        axiosInstance?: unknown;
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildix/xbees-conversations-utils",
-  "version": "1.1.69",
+  "version": "1.1.71",
   "description": "",
   "main": "./dist-cjs/index.js",
   "module": "./dist-es/index.js",