@wildix/xbees-conversations-utils 1.2.1 → 1.2.3

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

@@ -0,0 +1,170 @@
+import { STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX } from '../constants';
+export class RedisCooldown {
+    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(RedisCooldown.resolveRedisKey(cooldownKey, options));
+            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, options) {
+        if (cooldownMs <= 0) {
+            return;
+        }
+        const { redis, logger } = context;
+        const redisKey = RedisCooldown.resolveRedisKey(cooldownKey, options);
+        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,
+            });
+        }
+    }
+    static async setRemainingMsExact(cooldownKey, cooldownMs, context, options) {
+        if (cooldownMs <= 0) {
+            return;
+        }
+        const { redis, logger } = context;
+        try {
+            await redis.set(RedisCooldown.resolveRedisKey(cooldownKey, options), '1', 'PX', cooldownMs);
+        }
+        catch (error) {
+            logger.warn('Failed to write exact stream rate-limit cooldown to Redis', {
+                cooldownKey,
+                cooldownMs,
+                error,
+            });
+        }
+    }
+    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 {
+            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

@@ -0,0 +1,28 @@
+import { RateLimitExceededException } from '@wildix/xbees-conversations-client';
+import { DEFAULT_RETRY_AFTER_MS } from '../constants';
+const RETRY_AFTER_HEADER_PADDING_MS = 3000;
+function toPositiveMilliseconds(milliseconds) {
+    return Math.max(0, Math.ceil(milliseconds));
+}
+function toEpochSecondsFromNow(delayMs) {
+    return Math.ceil((Date.now() + toPositiveMilliseconds(delayMs)) / 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 retryAfterMilliseconds = toPositiveMilliseconds(effectiveRetryAfterMs);
+    const rateLimitResetMilliseconds = rateLimit?.reset
+        ? toPositiveMilliseconds(retryAfterFromResetMs ?? 0)
+        : retryAfterMilliseconds;
+    const retryAfterEpochSeconds = toEpochSecondsFromNow(effectiveRetryAfterMs + RETRY_AFTER_HEADER_PADDING_MS);
+    return new RateLimitExceededException({
+        $metadata: {},
+        message: message || defaultMessage,
+        rateLimitRemaining: rateLimit?.remaining || 0,
+        retryAfter: retryAfterEpochSeconds,
+        rateLimit: rateLimit?.limit?.toString() || 'unknown',
+        rateLimitReset: rateLimitResetMilliseconds,
+    });
+}

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

@@ -0,0 +1,140 @@
+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_METADATA_KEY_SUFFIX, STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, } from '../constants';
+import { createRateLimitExceededException } from './createRateLimitExceededException';
+import { processStreamRateLimitException } from './processStreamRateLimitException';
+import { parseRateLimitSnapshot, serializeRateLimitSnapshot } from './rateLimitSnapshot';
+import { RedisCooldown } from './RedisCooldown';
+function calculateRateLimitDelayMs(error, maxDelayMs) {
+    const retryAfterMs = typeof error.rateLimitReset === 'number' && error.rateLimitReset > 0 ? error.rateLimitReset : 0;
+    const hasServerRetryAfter = retryAfterMs > 0;
+    const baseDelayMs = hasServerRetryAfter ? retryAfterMs + RETRY_AFTER_BUFFER_MS : DEFAULT_RETRY_AFTER_MS;
+    if (baseDelayMs > 0) {
+        const jitterMs = Math.floor(Math.random() * DEFAULT_JITTER_MS);
+        const computedDelayMs = baseDelayMs + jitterMs;
+        if (hasServerRetryAfter) {
+            return computedDelayMs;
+        }
+        return Math.min(maxDelayMs, computedDelayMs);
+    }
+    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;
+    let attempt = 1;
+    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,
+            });
+        }
+        const softCooldownMs = await RedisCooldown.getRemainingMs(STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, { redis, logger }, { keyPrefix: STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX });
+        if (softCooldownMs > 0) {
+            logger.debug('Delaying stream request due to active soft rate-limit cooldown', {
+                operation,
+                cooldown: softCooldownMs,
+            });
+            await sleep(softCooldownMs);
+        }
+        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,
+            });
+            let totalBudgetWaitMs = 0;
+            for (;;) {
+                const waitMs = await RedisCooldown.getRemainingMs(STREAM_BUDGET_COOLDOWN_KEY, { redis, logger }, { keyPrefix: STREAM_BUDGET_COOLDOWN_KEY_PREFIX });
+                if (waitMs <= 0 || totalBudgetWaitMs >= BUDGET_DELAY_MAX_MS) {
+                    break;
+                }
+                const chunkMs = Math.min(waitMs, BUDGET_COOLDOWN_SLEEP_CHUNK_MS);
+                await sleep(chunkMs);
+                totalBudgetWaitMs += chunkMs;
+            }
+        }
+    }
+    for (;;) {
+        try {
+            return await execute();
+        }
+        catch (error) {
+            const rateLimitError = processStreamRateLimitException(error, logger);
+            if (!rateLimitError) {
+                throw error;
+            }
+            const retryAfterMs = calculateRateLimitDelayMs(rateLimitError, maxDelayMs);
+            if (enableCooldown) {
+                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', {
+                    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/helpers/headerUtils.js

@@ -0,0 +1,34 @@
+export 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;
+        }
+    }
+}
+export function parseHeaderNumber(headers, key) {
+    const raw = getHeaderCaseInsensitive(headers, key);
+    if (typeof raw === 'number' && Number.isFinite(raw)) {
+        return raw;
+    }
+    if (typeof raw === 'string') {
+        const parsed = Number(raw);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+}
+export function normalizeResetToEpochMs(reset) {
+    if (reset < 10000)
+        return Date.now() + Math.round(reset * 1000);
+    if (reset < 10000000000)
+        return Math.round(reset * 1000);
+    return Math.round(reset);
+}

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

@@ -0,0 +1,19 @@
+import { Channel } from 'stream-chat';
+function hasFunctionProperty(value, key) {
+    return key in value && typeof value[key] === 'function';
+}
+function hasStringProperty(value, key) {
+    return key in value && typeof value[key] === 'string';
+}
+export function isStreamChannelLike(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    if (value instanceof Channel) {
+        return true;
+    }
+    return (hasStringProperty(value, 'cid') &&
+        hasFunctionProperty(value, 'sendMessage') &&
+        hasFunctionProperty(value, 'queryMembers') &&
+        hasFunctionProperty(value, 'updatePartial'));
+}

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

@@ -0,0 +1,89 @@
+import { BUDGET_CLEAR_USAGE_THRESHOLD, BUDGET_DELAY_MAX_MS, BUDGET_DELAY_MIN_MS, BUDGET_MINIMAL_DELAY_MAX_MS, BUDGET_MINIMAL_DELAY_MIN_MS, BUDGET_RELAXED_DELAY_MAX_MS, BUDGET_RELAXED_DELAY_MIN_MS, BUDGET_RELAXED_USAGE_THRESHOLD, BUDGET_THRESHOLD, STREAM_BUDGET_COOLDOWN_KEY, STREAM_BUDGET_COOLDOWN_KEY_PREFIX, } from '../constants';
+import { parseHeaderNumber } from './headerUtils';
+import { RedisCooldown } from './RedisCooldown';
+function extractBudgetHeaders(headers) {
+    return {
+        limitMs: parseHeaderNumber(headers ?? {}, 'x-budget-limit-ms'),
+        remainingMs: parseHeaderNumber(headers ?? {}, 'x-budget-remaining-ms'),
+        usedMs: parseHeaderNumber(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 getRandomDelayInRange(minMs, maxMs) {
+    return Math.round(minMs + Math.random() * (maxMs - minMs));
+}
+function getBudgetUsage(limitMs, remainingMs, usedMs) {
+    if (limitMs <= 0) {
+        return 0;
+    }
+    if (typeof usedMs === 'number' && Number.isFinite(usedMs) && usedMs >= 0) {
+        return usedMs / limitMs;
+    }
+    if (typeof remainingMs === 'number' && Number.isFinite(remainingMs)) {
+        return Math.max(0, 1 - remainingMs / limitMs);
+    }
+    return 0;
+}
+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 usage = getBudgetUsage(limitMs, remainingMs, usedMs);
+    const thresholdReached = isBudgetThresholdReached(limitMs, remainingMs, usedMs);
+    if (thresholdReached) {
+        const delayMs = getRandomDelayInRange(BUDGET_DELAY_MIN_MS, BUDGET_DELAY_MAX_MS);
+        await RedisCooldown.setRemainingMsExact(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,
+            budgetUsage: usage,
+            cooldownMs: delayMs,
+        });
+        return;
+    }
+    if (usage < BUDGET_CLEAR_USAGE_THRESHOLD) {
+        await RedisCooldown.clear(STREAM_BUDGET_COOLDOWN_KEY, context, {
+            keyPrefix: STREAM_BUDGET_COOLDOWN_KEY_PREFIX,
+        });
+        logger.info('Stream budget is low, clearing cooldown', {
+            budgetLimitMs: limitMs,
+            budgetRemainingMs: remainingMs,
+            budgetUsedMs: usedMs,
+            budgetUsage: usage,
+        });
+        return;
+    }
+    const delayMs = usage >= BUDGET_RELAXED_USAGE_THRESHOLD
+        ? getRandomDelayInRange(BUDGET_RELAXED_DELAY_MIN_MS, BUDGET_RELAXED_DELAY_MAX_MS)
+        : getRandomDelayInRange(BUDGET_MINIMAL_DELAY_MIN_MS, BUDGET_MINIMAL_DELAY_MAX_MS);
+    await RedisCooldown.setRemainingMsExact(STREAM_BUDGET_COOLDOWN_KEY, delayMs, context, {
+        keyPrefix: STREAM_BUDGET_COOLDOWN_KEY_PREFIX,
+    });
+    logger.info('Stream budget is below threshold, reducing cooldown', {
+        budgetLimitMs: limitMs,
+        budgetRemainingMs: remainingMs,
+        budgetUsedMs: usedMs,
+        budgetUsage: usage,
+        cooldownMs: delayMs,
+    });
+}

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

@@ -0,0 +1,59 @@
+import { createRateLimitExceededException } from './createRateLimitExceededException';
+import { getHeaderCaseInsensitive, normalizeResetToEpochMs, parseHeaderNumber } from './headerUtils';
+function parseRetryAfterMs(headers) {
+    const retryAfter = getHeaderCaseInsensitive(headers, 'retry-after');
+    if (typeof retryAfter === 'number' && Number.isFinite(retryAfter) && retryAfter >= 0) {
+        return Math.round(retryAfter * 1000);
+    }
+    if (typeof retryAfter !== 'string') {
+        return;
+    }
+    const asSeconds = Number(retryAfter);
+    if (Number.isFinite(asSeconds) && asSeconds >= 0) {
+        return Math.round(asSeconds * 1000);
+    }
+    const asDateMs = Date.parse(retryAfter);
+    if (!Number.isNaN(asDateMs)) {
+        return Math.max(0, asDateMs - Date.now());
+    }
+}
+function getRateLimitFromHeaders(headers) {
+    const limit = parseHeaderNumber(headers, 'x-ratelimit-limit');
+    const remaining = parseHeaderNumber(headers, 'x-ratelimit-remaining');
+    const resetRaw = parseHeaderNumber(headers, 'x-ratelimit-reset');
+    if (limit === undefined || remaining === undefined || resetRaw === undefined) {
+        return;
+    }
+    return {
+        limit,
+        remaining,
+        reset: normalizeResetToEpochMs(resetRaw),
+    };
+}
+function isStreamHttpRateLimitError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        (('status' in error && error.status === 429) ||
+            ('response' in error &&
+                typeof error.response === 'object' &&
+                error.response !== null &&
+                error.response?.status === 429)));
+}
+export function processStreamRateLimitException(error, logger) {
+    if (isStreamHttpRateLimitError(error)) {
+        const headers = error.response?.headers ?? {};
+        const rateLimit = getRateLimitFromHeaders(headers);
+        const retryAfterMs = parseRetryAfterMs(headers);
+        const message = error.response?.data?.message || error.message || 'Rate limit exceeded';
+        logger.warn('Stream rate limit exceeded [HTTP 429]', {
+            status: error.status ?? error.response?.status,
+            retryAfterMs,
+            rateLimit,
+        });
+        return createRateLimitExceededException({
+            rateLimit,
+            retryAfterMs,
+            message,
+        });
+    }
+}

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

@@ -0,0 +1,46 @@
+import { SOFT_THROTTLE_DELAY_HIGH_MS, SOFT_THROTTLE_DELAY_LOW_MS, SOFT_THROTTLE_DELAY_MEDIUM_MS, SOFT_THROTTLE_USAGE_HIGH, SOFT_THROTTLE_USAGE_LOW, SOFT_THROTTLE_USAGE_MEDIUM, STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX, STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, } from '../constants';
+import { parseHeaderNumber } from './headerUtils';
+import { RedisCooldown } from './RedisCooldown';
+function computeSoftThrottleDelayMs(limit, remaining) {
+    if (limit <= 0) {
+        return 0;
+    }
+    const usage = 1 - remaining / limit;
+    if (usage >= SOFT_THROTTLE_USAGE_HIGH) {
+        return SOFT_THROTTLE_DELAY_HIGH_MS;
+    }
+    if (usage >= SOFT_THROTTLE_USAGE_MEDIUM) {
+        return SOFT_THROTTLE_DELAY_MEDIUM_MS;
+    }
+    if (usage >= SOFT_THROTTLE_USAGE_LOW) {
+        return SOFT_THROTTLE_DELAY_LOW_MS;
+    }
+    return 0;
+}
+export async function processStreamRateLimitHeaders(headers, context) {
+    const { logger } = context;
+    const limit = parseHeaderNumber(headers ?? {}, 'x-ratelimit-limit');
+    const remaining = parseHeaderNumber(headers ?? {}, 'x-ratelimit-remaining');
+    if (limit === undefined || remaining === undefined) {
+        return;
+    }
+    if (limit <= 0 || remaining < 0) {
+        return;
+    }
+    const delayMs = computeSoftThrottleDelayMs(limit, remaining);
+    if (delayMs > 0) {
+        await RedisCooldown.setRemainingMs(STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, delayMs, context, {
+            keyPrefix: STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX,
+        });
+        logger.debug('Enabling soft stream rate-limit cooldown', {
+            rateLimit: limit,
+            rateLimitRemaining: remaining,
+            cooldownMs: delayMs,
+        });
+        return;
+    }
+    await RedisCooldown.clear(STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, context, {
+        keyPrefix: STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX,
+    });
+    logger.debug('Clearing soft stream rate-limit cooldown');
+}

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-es/rateLimits/helpers/registerStreamBudgetInterceptors.js

@@ -0,0 +1,44 @@
+import { processStreamBudgetHeaders } from './processStreamBudgetHeaders';
+import { processStreamRateLimitHeaders } from './processStreamRateLimitHeaders';
+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);
+        await processStreamRateLimitHeaders(response?.headers, context);
+        return response;
+    }, async (error) => {
+        await processStreamBudgetHeaders(error?.response?.headers, context);
+        await processStreamRateLimitHeaders(error?.response?.headers, context);
+        return Promise.reject(error);
+    });
+    attachedInterceptors.add(axiosInstance);
+}