@wildix/xbees-conversations-utils 1.1.78 → 1.1.80

package/dist-cjs/rateLimits/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_OPTIONS = exports.SOFT_THROTTLE_DELAY_HIGH_MS = exports.SOFT_THROTTLE_DELAY_MEDIUM_MS = exports.SOFT_THROTTLE_DELAY_LOW_MS = exports.SOFT_THROTTLE_USAGE_HIGH = exports.SOFT_THROTTLE_USAGE_MEDIUM = exports.SOFT_THROTTLE_USAGE_LOW = exports.BUDGET_COOLDOWN_SLEEP_CHUNK_MS = exports.BUDGET_MINIMAL_DELAY_MAX_MS = exports.BUDGET_MINIMAL_DELAY_MIN_MS = exports.BUDGET_RELAXED_DELAY_MAX_MS = exports.BUDGET_RELAXED_DELAY_MIN_MS = exports.BUDGET_RELAXED_USAGE_THRESHOLD = exports.BUDGET_CLEAR_USAGE_THRESHOLD = exports.BUDGET_DELAY_MAX_MS = exports.BUDGET_DELAY_MIN_MS = exports.BUDGET_THRESHOLD = exports.STREAM_BUDGET_COOLDOWN_KEY = exports.STREAM_RATE_LIMIT_SOFT_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 = exports.STREAM_SYNC_METHOD_NAMES = exports.STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES = exports.STREAM_METHOD_NAMES = exports.STREAM_CHANNEL_RESULT_METHOD_NAMES = exports.CHANNEL_SYNC_PROXY_RESULT_METHOD_NAMES = exports.CHANNEL_SYNC_METHOD_NAMES = exports.CHANNEL_METHOD_NAMES = void 0;
+exports.DEFAULT_OPTIONS = exports.SOFT_THROTTLE_DELAY_HIGH_MS = exports.SOFT_THROTTLE_DELAY_MEDIUM_MS = exports.SOFT_THROTTLE_DELAY_LOW_MS = exports.SOFT_THROTTLE_USAGE_HIGH = exports.SOFT_THROTTLE_USAGE_MEDIUM = exports.SOFT_THROTTLE_USAGE_LOW = exports.BUDGET_COOLDOWN_SLEEP_CHUNK_MS = exports.BUDGET_MINIMAL_DELAY_MAX_MS = exports.BUDGET_MINIMAL_DELAY_MIN_MS = exports.BUDGET_RELAXED_DELAY_MAX_MS = exports.BUDGET_RELAXED_DELAY_MIN_MS = exports.BUDGET_RELAXED_USAGE_THRESHOLD = exports.BUDGET_CLEAR_USAGE_THRESHOLD = exports.BUDGET_DELAY_MAX_MS = exports.BUDGET_DELAY_MIN_MS = exports.BUDGET_THRESHOLD = exports.STREAM_BUDGET_COOLDOWN_KEY = exports.STREAM_RATE_LIMIT_METADATA_KEY_SUFFIX = exports.STREAM_RATE_LIMIT_SOFT_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 = exports.STREAM_SYNC_METHOD_NAMES = exports.STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES = exports.STREAM_METHOD_NAMES = exports.STREAM_CHANNEL_RESULT_METHOD_NAMES = exports.CHANNEL_SYNC_PROXY_RESULT_METHOD_NAMES = exports.CHANNEL_SYNC_METHOD_NAMES = exports.CHANNEL_METHOD_NAMES = void 0;
 var generatedMethodNames_1 = require("./generatedMethodNames");
 Object.defineProperty(exports, "CHANNEL_METHOD_NAMES", { enumerable: true, get: function () { return generatedMethodNames_1.CHANNEL_METHOD_NAMES; } });
 Object.defineProperty(exports, "CHANNEL_SYNC_METHOD_NAMES", { enumerable: true, get: function () { return generatedMethodNames_1.CHANNEL_SYNC_METHOD_NAMES; } });
@@ -17,6 +17,7 @@ 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_RATE_LIMIT_SOFT_COOLDOWN_KEY = 'stream-rate-limit-soft-global';
+exports.STREAM_RATE_LIMIT_METADATA_KEY_SUFFIX = ':meta';
 exports.STREAM_BUDGET_COOLDOWN_KEY = 'stream-budget-global';
 exports.BUDGET_THRESHOLD = 0.8;
 exports.BUDGET_DELAY_MIN_MS = 30000;

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

@@ -72,6 +72,92 @@ class RedisCooldown {
             });
         }
     }
+    static async getValue(cooldownKey, context, options) {
+        const { redis, logger } = context;
+        try {
+            const value = await redis.get(RedisCooldown.resolveRedisKey(cooldownKey, options));
+            if (typeof value === 'string' && value.length > 0) {
+                return value;
+            }
+        }
+        catch (error) {
+            logger.warn('Failed to read stream rate-limit metadata from Redis', {
+                cooldownKey,
+                error,
+            });
+        }
+    }
+    static async setValueWithRemainingMs(cooldownKey, value, cooldownMs, context, options) {
+        if (value.length === 0 || cooldownMs <= 0) {
+            return;
+        }
+        const { redis, logger } = context;
+        try {
+            await redis.eval(`
+        local key = KEYS[1]
+        local value = ARGV[1]
+        local new_ttl = tonumber(ARGV[2])
+        local current_ttl = redis.call('PTTL', key)
+
+        if current_ttl == -2 then
+          redis.call('SET', key, value, 'PX', new_ttl)
+          return 1
+        end
+
+        if current_ttl == -1 or current_ttl < new_ttl then
+          redis.call('SET', key, value, 'PX', new_ttl)
+          return 2
+        end
+
+        redis.call('SET', key, value, 'KEEPTTL')
+        return 0
+      `, 1, RedisCooldown.resolveRedisKey(cooldownKey, options), value, cooldownMs.toString());
+        }
+        catch (error) {
+            logger.warn('Failed to write stream rate-limit metadata to Redis', {
+                cooldownKey,
+                cooldownMs,
+                error,
+            });
+        }
+    }
+    static async setRemainingMsWithValue(cooldownKey, valueKey, value, cooldownMs, context, options) {
+        if (value.length === 0 || cooldownMs <= 0) {
+            return;
+        }
+        const { redis, logger } = context;
+        const cooldownRedisKey = RedisCooldown.resolveRedisKey(cooldownKey, options);
+        const valueRedisKey = RedisCooldown.resolveRedisKey(valueKey, options);
+        try {
+            await redis.eval(`
+        local cooldown_key = KEYS[1]
+        local value_key = KEYS[2]
+        local value = ARGV[1]
+        local new_ttl = tonumber(ARGV[2])
+        local current_ttl = redis.call('PTTL', cooldown_key)
+        local final_ttl = new_ttl
+
+        if current_ttl == -2 then
+          redis.call('SET', cooldown_key, '1', 'PX', new_ttl)
+        elseif current_ttl == -1 or current_ttl < new_ttl then
+          redis.call('PEXPIRE', cooldown_key, new_ttl)
+        else
+          final_ttl = current_ttl
+        end
+
+        redis.call('SET', value_key, value, 'PX', final_ttl)
+        return final_ttl
+      `, 2, cooldownRedisKey, valueRedisKey, value, cooldownMs.toString());
+        }
+        catch (error) {
+            logger.warn('Failed to write stream rate-limit cooldown and metadata to Redis', {
+                cooldownKey,
+                valueKey,
+                cooldownMs,
+                error,
+            });
+        }
+    }
     static async clear(cooldownKey, context, options) {
         const { redis, logger } = context;
         try {

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

@@ -4,6 +4,7 @@ exports.executeWithRateLimitHandling = void 0;
 const promises_1 = require("node:timers/promises");
 const constants_1 = require("../constants");
 const createRateLimitExceededException_1 = require("./createRateLimitExceededException");
+const rateLimitSnapshot_1 = require("./rateLimitSnapshot");
 const processStreamRateLimitException_1 = require("./processStreamRateLimitException");
 const RedisCooldown_1 = require("./RedisCooldown");
 function calculateRateLimitDelayMs(error, maxDelayMs) {
@@ -20,6 +21,34 @@ function calculateRateLimitDelayMs(error, maxDelayMs) {
     }
     return Math.min(maxDelayMs, constants_1.DEFAULT_MAX_DELAY_MS);
 }
+function getRateLimitMetadataKey(operation) {
+    return `${operation}${constants_1.STREAM_RATE_LIMIT_METADATA_KEY_SUFFIX}`;
+}
+function toCooldownRateLimit(snapshot, cooldownMs) {
+    return {
+        limit: snapshot.limit,
+        remaining: snapshot.remaining,
+        reset: Math.max(snapshot.reset, Date.now() + cooldownMs),
+    };
+}
+function toRateLimitSnapshot(error) {
+    const limit = Number(error.rateLimit);
+    const remaining = error.rateLimitRemaining;
+    const resetMs = error.rateLimitReset;
+    if (!Number.isFinite(limit) ||
+        typeof remaining !== 'number' ||
+        !Number.isFinite(remaining) ||
+        typeof resetMs !== 'number' ||
+        !Number.isFinite(resetMs) ||
+        resetMs <= 0) {
+        return;
+    }
+    return {
+        limit,
+        remaining,
+        reset: Date.now() + resetMs,
+    };
+}
 async function executeWithRateLimitHandling(execute, operation, context, options) {
     const { logger, redis } = context;
     const { enableCooldown, maxAttempts, maxDelayMs, maxRetryableDelayMs } = options;
@@ -27,11 +56,17 @@ async function executeWithRateLimitHandling(execute, operation, context, options
     if (enableCooldown) {
         const cooldownMs = await RedisCooldown_1.RedisCooldown.getRemainingMs(operation, { redis, logger });
         if (cooldownMs > 0) {
+            const rateLimitSnapshot = (0, rateLimitSnapshot_1.parseRateLimitSnapshot)(await RedisCooldown_1.RedisCooldown.getValue(getRateLimitMetadataKey(operation), { redis, logger }));
             logger.warn('Skipping stream request due to active rate-limit cooldown', {
                 operation,
                 cooldown: cooldownMs,
+                rateLimitSnapshot,
+            });
+            throw (0, createRateLimitExceededException_1.createRateLimitExceededException)({
+                operation,
+                retryAfterMs: cooldownMs,
+                rateLimit: rateLimitSnapshot ? toCooldownRateLimit(rateLimitSnapshot, cooldownMs) : undefined,
             });
-            throw (0, createRateLimitExceededException_1.createRateLimitExceededException)({ operation, retryAfterMs: cooldownMs });
         }
         const softCooldownMs = await RedisCooldown_1.RedisCooldown.getRemainingMs(constants_1.STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, { redis, logger }, { keyPrefix: constants_1.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX });
         if (softCooldownMs > 0) {
@@ -70,7 +105,13 @@ async function executeWithRateLimitHandling(execute, operation, context, options
             }
             const retryAfterMs = calculateRateLimitDelayMs(rateLimitError, maxDelayMs);
             if (enableCooldown) {
-                await RedisCooldown_1.RedisCooldown.setRemainingMs(operation, retryAfterMs, { redis, logger });
+                const rateLimitSnapshot = toRateLimitSnapshot(rateLimitError);
+                if (rateLimitSnapshot) {
+                    await RedisCooldown_1.RedisCooldown.setRemainingMsWithValue(operation, getRateLimitMetadataKey(operation), (0, rateLimitSnapshot_1.serializeRateLimitSnapshot)(rateLimitSnapshot), retryAfterMs, { redis, logger });
+                }
+                else {
+                    await RedisCooldown_1.RedisCooldown.setRemainingMs(operation, retryAfterMs, { redis, logger });
+                }
             }
             if (attempt < maxAttempts && retryAfterMs <= maxRetryableDelayMs) {
                 logger.warn('Retrying stream request after rate limit', {

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

@@ -45,7 +45,6 @@ function isStreamHttpRateLimitError(error) {
 function processStreamRateLimitException(error, logger) {
     if (isStreamHttpRateLimitError(error)) {
         const headers = error.response?.headers ?? {};
-        logger.warn(`rate limit headers`, { headers });
         const rateLimit = getRateLimitFromHeaders(headers);
         const retryAfterMs = parseRetryAfterMs(headers);
         const message = error.response?.data?.message || error.message || 'Rate limit exceeded';

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

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRateLimitSnapshot = exports.serializeRateLimitSnapshot = void 0;
+const RATE_LIMIT_SNAPSHOT_PARTS_COUNT = 3;
+function serializeRateLimitSnapshot(snapshot) {
+    return `${snapshot.limit},${snapshot.remaining},${snapshot.reset}`;
+}
+exports.serializeRateLimitSnapshot = serializeRateLimitSnapshot;
+function parseRateLimitSnapshot(snapshot) {
+    if (typeof snapshot !== 'string' || snapshot.length === 0) {
+        return;
+    }
+    const parts = snapshot.split(',');
+    if (parts.length !== RATE_LIMIT_SNAPSHOT_PARTS_COUNT) {
+        return;
+    }
+    const [limitRaw, remainingRaw, resetRaw] = parts;
+    const limit = Number(limitRaw);
+    const remaining = Number(remainingRaw);
+    const reset = Number(resetRaw);
+    if (!Number.isFinite(limit) ||
+        !Number.isFinite(remaining) ||
+        !Number.isFinite(reset) ||
+        limit < 0 ||
+        remaining < 0 ||
+        reset <= 0) {
+        return;
+    }
+    return { limit, remaining, reset };
+}
+exports.parseRateLimitSnapshot = parseRateLimitSnapshot;

package/dist-es/rateLimits/constants.js

@@ -7,6 +7,7 @@ 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_RATE_LIMIT_SOFT_COOLDOWN_KEY = 'stream-rate-limit-soft-global';
+export const STREAM_RATE_LIMIT_METADATA_KEY_SUFFIX = ':meta';
 export const STREAM_BUDGET_COOLDOWN_KEY = 'stream-budget-global';
 export const BUDGET_THRESHOLD = 0.8;
 export const BUDGET_DELAY_MIN_MS = 30000;

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

@@ -69,6 +69,92 @@ export class RedisCooldown {
             });
         }
     }
+    static async getValue(cooldownKey, context, options) {
+        const { redis, logger } = context;
+        try {
+            const value = await redis.get(RedisCooldown.resolveRedisKey(cooldownKey, options));
+            if (typeof value === 'string' && value.length > 0) {
+                return value;
+            }
+        }
+        catch (error) {
+            logger.warn('Failed to read stream rate-limit metadata from Redis', {
+                cooldownKey,
+                error,
+            });
+        }
+    }
+    static async setValueWithRemainingMs(cooldownKey, value, cooldownMs, context, options) {
+        if (value.length === 0 || cooldownMs <= 0) {
+            return;
+        }
+        const { redis, logger } = context;
+        try {
+            await redis.eval(`
+        local key = KEYS[1]
+        local value = ARGV[1]
+        local new_ttl = tonumber(ARGV[2])
+        local current_ttl = redis.call('PTTL', key)
+
+        if current_ttl == -2 then
+          redis.call('SET', key, value, 'PX', new_ttl)
+          return 1
+        end
+
+        if current_ttl == -1 or current_ttl < new_ttl then
+          redis.call('SET', key, value, 'PX', new_ttl)
+          return 2
+        end
+
+        redis.call('SET', key, value, 'KEEPTTL')
+        return 0
+      `, 1, RedisCooldown.resolveRedisKey(cooldownKey, options), value, cooldownMs.toString());
+        }
+        catch (error) {
+            logger.warn('Failed to write stream rate-limit metadata to Redis', {
+                cooldownKey,
+                cooldownMs,
+                error,
+            });
+        }
+    }
+    static async setRemainingMsWithValue(cooldownKey, valueKey, value, cooldownMs, context, options) {
+        if (value.length === 0 || cooldownMs <= 0) {
+            return;
+        }
+        const { redis, logger } = context;
+        const cooldownRedisKey = RedisCooldown.resolveRedisKey(cooldownKey, options);
+        const valueRedisKey = RedisCooldown.resolveRedisKey(valueKey, options);
+        try {
+            await redis.eval(`
+        local cooldown_key = KEYS[1]
+        local value_key = KEYS[2]
+        local value = ARGV[1]
+        local new_ttl = tonumber(ARGV[2])
+        local current_ttl = redis.call('PTTL', cooldown_key)
+        local final_ttl = new_ttl
+
+        if current_ttl == -2 then
+          redis.call('SET', cooldown_key, '1', 'PX', new_ttl)
+        elseif current_ttl == -1 or current_ttl < new_ttl then
+          redis.call('PEXPIRE', cooldown_key, new_ttl)
+        else
+          final_ttl = current_ttl
+        end
+
+        redis.call('SET', value_key, value, 'PX', final_ttl)
+        return final_ttl
+      `, 2, cooldownRedisKey, valueRedisKey, value, cooldownMs.toString());
+        }
+        catch (error) {
+            logger.warn('Failed to write stream rate-limit cooldown and metadata to Redis', {
+                cooldownKey,
+                valueKey,
+                cooldownMs,
+                error,
+            });
+        }
+    }
     static async clear(cooldownKey, context, options) {
         const { redis, logger } = context;
         try {

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

@@ -1,6 +1,7 @@
 import { setTimeout as sleep } from 'node:timers/promises';
-import { BUDGET_COOLDOWN_SLEEP_CHUNK_MS, BUDGET_DELAY_MAX_MS, DEFAULT_JITTER_MS, DEFAULT_MAX_DELAY_MS, DEFAULT_RETRY_AFTER_MS, RETRY_AFTER_BUFFER_MS, STREAM_BUDGET_COOLDOWN_KEY, STREAM_BUDGET_COOLDOWN_KEY_PREFIX, STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX, STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, } from '../constants';
+import { BUDGET_COOLDOWN_SLEEP_CHUNK_MS, BUDGET_DELAY_MAX_MS, DEFAULT_JITTER_MS, DEFAULT_MAX_DELAY_MS, DEFAULT_RETRY_AFTER_MS, RETRY_AFTER_BUFFER_MS, STREAM_BUDGET_COOLDOWN_KEY, STREAM_BUDGET_COOLDOWN_KEY_PREFIX, STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX, STREAM_RATE_LIMIT_METADATA_KEY_SUFFIX, STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, } from '../constants';
 import { createRateLimitExceededException } from './createRateLimitExceededException';
+import { parseRateLimitSnapshot, serializeRateLimitSnapshot } from './rateLimitSnapshot';
 import { processStreamRateLimitException } from './processStreamRateLimitException';
 import { RedisCooldown } from './RedisCooldown';
 function calculateRateLimitDelayMs(error, maxDelayMs) {
@@ -17,6 +18,34 @@ function calculateRateLimitDelayMs(error, maxDelayMs) {
     }
     return Math.min(maxDelayMs, DEFAULT_MAX_DELAY_MS);
 }
+function getRateLimitMetadataKey(operation) {
+    return `${operation}${STREAM_RATE_LIMIT_METADATA_KEY_SUFFIX}`;
+}
+function toCooldownRateLimit(snapshot, cooldownMs) {
+    return {
+        limit: snapshot.limit,
+        remaining: snapshot.remaining,
+        reset: Math.max(snapshot.reset, Date.now() + cooldownMs),
+    };
+}
+function toRateLimitSnapshot(error) {
+    const limit = Number(error.rateLimit);
+    const remaining = error.rateLimitRemaining;
+    const resetMs = error.rateLimitReset;
+    if (!Number.isFinite(limit) ||
+        typeof remaining !== 'number' ||
+        !Number.isFinite(remaining) ||
+        typeof resetMs !== 'number' ||
+        !Number.isFinite(resetMs) ||
+        resetMs <= 0) {
+        return;
+    }
+    return {
+        limit,
+        remaining,
+        reset: Date.now() + resetMs,
+    };
+}
 export async function executeWithRateLimitHandling(execute, operation, context, options) {
     const { logger, redis } = context;
     const { enableCooldown, maxAttempts, maxDelayMs, maxRetryableDelayMs } = options;
@@ -24,11 +53,17 @@ export async function executeWithRateLimitHandling(execute, operation, context,
     if (enableCooldown) {
         const cooldownMs = await RedisCooldown.getRemainingMs(operation, { redis, logger });
         if (cooldownMs > 0) {
+            const rateLimitSnapshot = parseRateLimitSnapshot(await RedisCooldown.getValue(getRateLimitMetadataKey(operation), { redis, logger }));
             logger.warn('Skipping stream request due to active rate-limit cooldown', {
                 operation,
                 cooldown: cooldownMs,
+                rateLimitSnapshot,
+            });
+            throw createRateLimitExceededException({
+                operation,
+                retryAfterMs: cooldownMs,
+                rateLimit: rateLimitSnapshot ? toCooldownRateLimit(rateLimitSnapshot, cooldownMs) : undefined,
             });
-            throw createRateLimitExceededException({ operation, retryAfterMs: cooldownMs });
         }
         const softCooldownMs = await RedisCooldown.getRemainingMs(STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, { redis, logger }, { keyPrefix: STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX });
         if (softCooldownMs > 0) {
@@ -67,7 +102,13 @@ export async function executeWithRateLimitHandling(execute, operation, context,
             }
             const retryAfterMs = calculateRateLimitDelayMs(rateLimitError, maxDelayMs);
             if (enableCooldown) {
-                await RedisCooldown.setRemainingMs(operation, retryAfterMs, { redis, logger });
+                const rateLimitSnapshot = toRateLimitSnapshot(rateLimitError);
+                if (rateLimitSnapshot) {
+                    await RedisCooldown.setRemainingMsWithValue(operation, getRateLimitMetadataKey(operation), serializeRateLimitSnapshot(rateLimitSnapshot), retryAfterMs, { redis, logger });
+                }
+                else {
+                    await RedisCooldown.setRemainingMs(operation, retryAfterMs, { redis, logger });
+                }
             }
             if (attempt < maxAttempts && retryAfterMs <= maxRetryableDelayMs) {
                 logger.warn('Retrying stream request after rate limit', {

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

@@ -42,7 +42,6 @@ function isStreamHttpRateLimitError(error) {
 export function processStreamRateLimitException(error, logger) {
     if (isStreamHttpRateLimitError(error)) {
         const headers = error.response?.headers ?? {};
-        logger.warn(`rate limit headers`, { headers });
         const rateLimit = getRateLimitFromHeaders(headers);
         const retryAfterMs = parseRetryAfterMs(headers);
         const message = error.response?.data?.message || error.message || 'Rate limit exceeded';

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

@@ -0,0 +1,26 @@
+const RATE_LIMIT_SNAPSHOT_PARTS_COUNT = 3;
+export function serializeRateLimitSnapshot(snapshot) {
+    return `${snapshot.limit},${snapshot.remaining},${snapshot.reset}`;
+}
+export function parseRateLimitSnapshot(snapshot) {
+    if (typeof snapshot !== 'string' || snapshot.length === 0) {
+        return;
+    }
+    const parts = snapshot.split(',');
+    if (parts.length !== RATE_LIMIT_SNAPSHOT_PARTS_COUNT) {
+        return;
+    }
+    const [limitRaw, remainingRaw, resetRaw] = parts;
+    const limit = Number(limitRaw);
+    const remaining = Number(remainingRaw);
+    const reset = Number(resetRaw);
+    if (!Number.isFinite(limit) ||
+        !Number.isFinite(remaining) ||
+        !Number.isFinite(reset) ||
+        limit < 0 ||
+        remaining < 0 ||
+        reset <= 0) {
+        return;
+    }
+    return { limit, remaining, reset };
+}

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

@@ -8,6 +8,7 @@ export declare const STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX = "stream-rate-limit-
 export declare const STREAM_BUDGET_COOLDOWN_KEY_PREFIX = "stream-budget-cooldown:";
 export declare const STREAM_RATE_LIMIT_OPTIONS_MARKER = "__xbsRateLimitOptions";
 export declare const STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY = "stream-rate-limit-soft-global";
+export declare const STREAM_RATE_LIMIT_METADATA_KEY_SUFFIX = ":meta";
 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;

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

@@ -4,5 +4,8 @@ export declare class RedisCooldown {
     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 setRemainingMsExact(cooldownKey: string, cooldownMs: number, context: RedisContext & LoggerContext, options?: RedisCooldownOptions): Promise<void>;
+    static getValue(cooldownKey: string, context: RedisContext & LoggerContext, options?: RedisCooldownOptions): Promise<string | undefined>;
+    static setValueWithRemainingMs(cooldownKey: string, value: string, cooldownMs: number, context: RedisContext & LoggerContext, options?: RedisCooldownOptions): Promise<void>;
+    static setRemainingMsWithValue(cooldownKey: string, valueKey: string, value: 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/rateLimitSnapshot.d.ts

@@ -0,0 +1,3 @@
+import { StreamRateLimitSnapshot } from '../types';
+export declare function serializeRateLimitSnapshot(snapshot: StreamRateLimitSnapshot): string;
+export declare function parseRateLimitSnapshot(snapshot: string | null | undefined): StreamRateLimitSnapshot | undefined;

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

@@ -36,6 +36,11 @@ export type StreamBudgetHeaders = {
     remainingMs?: number;
     usedMs?: number;
 };
+export type StreamRateLimitSnapshot = {
+    limit: number;
+    remaining: number;
+    reset: number;
+};
 /** Axios response shape used by budget interceptor. */
 export type StreamBudgetInterceptorResponse = {
     headers?: StreamHeaders;

package/package.json

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