@wildix/xbees-conversations-utils 1.2.2 → 1.2.4

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

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeResetToEpochMs = exports.parseHeaderNumber = exports.getHeaderCaseInsensitive = void 0;
+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;
+        }
+    }
+}
+exports.getHeaderCaseInsensitive = getHeaderCaseInsensitive;
+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;
+        }
+    }
+}
+exports.parseHeaderNumber = parseHeaderNumber;
+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);
+}
+exports.normalizeResetToEpochMs = normalizeResetToEpochMs;

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

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isStreamChannelLike = void 0;
+const stream_chat_1 = require("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';
+}
+function isStreamChannelLike(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    if (value instanceof stream_chat_1.Channel) {
+        return true;
+    }
+    return (hasStringProperty(value, 'cid') &&
+        hasFunctionProperty(value, 'sendMessage') &&
+        hasFunctionProperty(value, 'queryMembers') &&
+        hasFunctionProperty(value, 'updatePartial'));
+}
+exports.isStreamChannelLike = isStreamChannelLike;

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

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processStreamBudgetHeaders = void 0;
+const constants_1 = require("../constants");
+const headerUtils_1 = require("./headerUtils");
+const RedisCooldown_1 = require("./RedisCooldown");
+function extractBudgetHeaders(headers) {
+    return {
+        limitMs: (0, headerUtils_1.parseHeaderNumber)(headers ?? {}, 'x-budget-limit-ms'),
+        remainingMs: (0, headerUtils_1.parseHeaderNumber)(headers ?? {}, 'x-budget-remaining-ms'),
+        usedMs: (0, headerUtils_1.parseHeaderNumber)(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 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;
+}
+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(constants_1.BUDGET_DELAY_MIN_MS, constants_1.BUDGET_DELAY_MAX_MS);
+        await RedisCooldown_1.RedisCooldown.setRemainingMsExact(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,
+            budgetUsage: usage,
+            cooldownMs: delayMs,
+        });
+        return;
+    }
+    if (usage < constants_1.BUDGET_CLEAR_USAGE_THRESHOLD) {
+        await RedisCooldown_1.RedisCooldown.clear(constants_1.STREAM_BUDGET_COOLDOWN_KEY, context, {
+            keyPrefix: constants_1.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 >= constants_1.BUDGET_RELAXED_USAGE_THRESHOLD
+        ? getRandomDelayInRange(constants_1.BUDGET_RELAXED_DELAY_MIN_MS, constants_1.BUDGET_RELAXED_DELAY_MAX_MS)
+        : getRandomDelayInRange(constants_1.BUDGET_MINIMAL_DELAY_MIN_MS, constants_1.BUDGET_MINIMAL_DELAY_MAX_MS);
+    await RedisCooldown_1.RedisCooldown.setRemainingMsExact(constants_1.STREAM_BUDGET_COOLDOWN_KEY, delayMs, context, {
+        keyPrefix: constants_1.STREAM_BUDGET_COOLDOWN_KEY_PREFIX,
+    });
+    logger.info('Stream budget is below threshold, reducing cooldown', {
+        budgetLimitMs: limitMs,
+        budgetRemainingMs: remainingMs,
+        budgetUsedMs: usedMs,
+        budgetUsage: usage,
+        cooldownMs: delayMs,
+    });
+}
+exports.processStreamBudgetHeaders = processStreamBudgetHeaders;

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

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processStreamRateLimitException = void 0;
+const createRateLimitExceededException_1 = require("./createRateLimitExceededException");
+const headerUtils_1 = require("./headerUtils");
+function parseRetryAfterMs(headers) {
+    const retryAfter = (0, headerUtils_1.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 = (0, headerUtils_1.parseHeaderNumber)(headers, 'x-ratelimit-limit');
+    const remaining = (0, headerUtils_1.parseHeaderNumber)(headers, 'x-ratelimit-remaining');
+    const resetRaw = (0, headerUtils_1.parseHeaderNumber)(headers, 'x-ratelimit-reset');
+    if (limit === undefined || remaining === undefined || resetRaw === undefined) {
+        return;
+    }
+    return {
+        limit,
+        remaining,
+        reset: (0, headerUtils_1.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)));
+}
+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 (0, createRateLimitExceededException_1.createRateLimitExceededException)({
+            rateLimit,
+            retryAfterMs,
+            message,
+        });
+    }
+}
+exports.processStreamRateLimitException = processStreamRateLimitException;

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

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processStreamRateLimitHeaders = void 0;
+const constants_1 = require("../constants");
+const headerUtils_1 = require("./headerUtils");
+const RedisCooldown_1 = require("./RedisCooldown");
+function computeSoftThrottleDelayMs(limit, remaining) {
+    if (limit <= 0) {
+        return 0;
+    }
+    const usage = 1 - remaining / limit;
+    if (usage >= constants_1.SOFT_THROTTLE_USAGE_HIGH) {
+        return constants_1.SOFT_THROTTLE_DELAY_HIGH_MS;
+    }
+    if (usage >= constants_1.SOFT_THROTTLE_USAGE_MEDIUM) {
+        return constants_1.SOFT_THROTTLE_DELAY_MEDIUM_MS;
+    }
+    if (usage >= constants_1.SOFT_THROTTLE_USAGE_LOW) {
+        return constants_1.SOFT_THROTTLE_DELAY_LOW_MS;
+    }
+    return 0;
+}
+async function processStreamRateLimitHeaders(headers, context) {
+    const { logger } = context;
+    const limit = (0, headerUtils_1.parseHeaderNumber)(headers ?? {}, 'x-ratelimit-limit');
+    const remaining = (0, headerUtils_1.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_1.RedisCooldown.setRemainingMs(constants_1.STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, delayMs, context, {
+            keyPrefix: constants_1.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX,
+        });
+        logger.debug('Enabling soft stream rate-limit cooldown', {
+            rateLimit: limit,
+            rateLimitRemaining: remaining,
+            cooldownMs: delayMs,
+        });
+        return;
+    }
+    await RedisCooldown_1.RedisCooldown.clear(constants_1.STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, context, {
+        keyPrefix: constants_1.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX,
+    });
+    logger.debug('Clearing soft stream rate-limit cooldown');
+}
+exports.processStreamRateLimitHeaders = processStreamRateLimitHeaders;

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

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerStreamBudgetInterceptors = void 0;
+const processStreamBudgetHeaders_1 = require("./processStreamBudgetHeaders");
+const processStreamRateLimitHeaders_1 = require("./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;
+    }
+}
+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);
+        await (0, processStreamRateLimitHeaders_1.processStreamRateLimitHeaders)(response?.headers, context);
+        return response;
+    }, async (error) => {
+        await (0, processStreamBudgetHeaders_1.processStreamBudgetHeaders)(error?.response?.headers, context);
+        await (0, processStreamRateLimitHeaders_1.processStreamRateLimitHeaders)(error?.response?.headers, context);
+        return Promise.reject(error);
+    });
+    attachedInterceptors.add(axiosInstance);
+}
+exports.registerStreamBudgetInterceptors = registerStreamBudgetInterceptors;

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

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerStreamInterceptors = void 0;
+const processStreamBudgetHeaders_1 = require("./processStreamBudgetHeaders");
+const processStreamRateLimitHeaders_1 = require("./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;
+    }
+}
+function registerStreamInterceptors(stream, context) {
+    const { logger } = context;
+    const axiosInstance = resolveAxiosInstance(stream);
+    if (!axiosInstance || !axiosInstance.interceptors?.response?.use) {
+        logger.warn('Unable to register stream budget & rate limit interceptors: axios instance not found');
+        return;
+    }
+    if (attachedInterceptors.has(axiosInstance)) {
+        return;
+    }
+    attachedInterceptors.add(axiosInstance);
+    axiosInstance.interceptors.response.use(async (response) => {
+        try {
+            await (0, processStreamBudgetHeaders_1.processStreamBudgetHeaders)(response?.headers, context);
+            await (0, processStreamRateLimitHeaders_1.processStreamRateLimitHeaders)(response?.headers, context);
+        }
+        catch (error) {
+            logger.warn('Failed to process Stream response headers in interceptor', { error });
+        }
+        return response;
+    }, async (error) => {
+        try {
+            await (0, processStreamBudgetHeaders_1.processStreamBudgetHeaders)(error?.response?.headers, context);
+            await (0, processStreamRateLimitHeaders_1.processStreamRateLimitHeaders)(error?.response?.headers, context);
+        }
+        catch (interceptorError) {
+            logger.warn('Failed to process Stream error headers in interceptor', { error: interceptorError });
+        }
+        return Promise.reject(error);
+    });
+}
+exports.registerStreamInterceptors = registerStreamInterceptors;

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

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitCallArgsAndOptions = void 0;
+const constants_1 = require("../constants");
+function isStreamRateLimitOptionsToken(value) {
+    return typeof value === 'object' && value !== null && constants_1.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[constants_1.STREAM_RATE_LIMIT_OPTIONS_MARKER],
+        };
+    }
+    return { callArgs: args, callOptions: {} };
+}
+exports.splitCallArgsAndOptions = splitCallArgsAndOptions;

package/dist-cjs/rateLimits/index.js

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

package/dist-cjs/rateLimits/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const constants_1 = require("./constants");

package/dist-cjs/rateLimits/withStreamRateLimitOptions.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withStreamRateLimitOptions = void 0;
+const constants_1 = require("./constants");
+function withStreamRateLimitOptions(options) {
+    return {
+        [constants_1.STREAM_RATE_LIMIT_OPTIONS_MARKER]: options,
+    };
+}
+exports.withStreamRateLimitOptions = withStreamRateLimitOptions;

package/dist-es/anonymousEmail/index.js

@@ -0,0 +1,16 @@
+const ANONYMOUS_EMAIL_DOMAIN = 'wildix.com';
+const ANONYMOUS_EMAIL_PREFIX = 'anonymous-';
+const ANONYMOUS_STREAM_ID_REGEXP = /^[0-9A-Za-z]{12}$/;
+const ANONYMOUS_USER_EMAIL_REGEXP = /^anonymous-[0-9A-Za-z]{12}@wildix\.com$/;
+export function generateAnonymousUserEmailOrThrowError(streamId) {
+    if (!streamId.trim()) {
+        throw new Error('Anonymous stream id must not be empty');
+    }
+    if (!ANONYMOUS_STREAM_ID_REGEXP.test(streamId)) {
+        throw new Error('Anonymous stream id must contain only uppercase letters, lowercase letters, digits, and have 12 symbols length');
+    }
+    return `${ANONYMOUS_EMAIL_PREFIX}${streamId}@${ANONYMOUS_EMAIL_DOMAIN}`;
+}
+export function isAnonymousUserEmail(value) {
+    return ANONYMOUS_USER_EMAIL_REGEXP.test(value);
+}

package/dist-es/index.js

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

package/dist-es/normalization.js

@@ -192,7 +192,7 @@ export function localizeStreamChannel(streamChannel) {
     const { data, state } = streamChannel;
     const wid = streamChannel.getClient().userID || '';
     const createdAt = new Date(normalizedChannel.createdAt);
-    const updatedAt = new Date(normalizedChannel.updatedAt || normalizedChannel?.createdBy);
+    const updatedAt = new Date(normalizedChannel.updatedAt || normalizedChannel?.createdAt);
     const members = Object.values(state.members).filter(({ user_id }) => user_id !== wid);
     const userId = data?.type === ChannelType.DIRECT && members.length > 0 ? members[0].user_id : null;
     const unread = state.read[wid]?.unread_messages || 0;

package/dist-es/rateLimits/RedisCooldown.js

@@ -0,0 +1,62 @@
+import {STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX} from './constants';
+
+export class RedisCooldown {
+  static async getRemainingMs(cooldownKey, context) {
+    const {redis} = context;
+
+    try {
+      const ttlMs = await redis.pttl(`${STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX}${cooldownKey}`);
+
+      if (ttlMs > 0) {
+        return ttlMs;
+      }
+    } catch (error) {
+      console.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} = 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) {
+      console.warn('Failed to write stream rate-limit cooldown to Redis', {
+        cooldownKey,
+        cooldownMs,
+        error,
+      });
+    }
+  }
+}

package/dist-es/rateLimits/constants.js

@@ -0,0 +1,33 @@
+export { CHANNEL_METHOD_NAMES, CHANNEL_SYNC_METHOD_NAMES, CHANNEL_SYNC_PROXY_RESULT_METHOD_NAMES, STREAM_CHANNEL_RESULT_METHOD_NAMES, STREAM_METHOD_NAMES, STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES, STREAM_SYNC_METHOD_NAMES, } from './generatedMethodNames';
+export const DEFAULT_MAX_DELAY_MS = 5000;
+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_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;
+export const BUDGET_DELAY_MAX_MS = 60000;
+export const BUDGET_CLEAR_USAGE_THRESHOLD = 0.6;
+export const BUDGET_RELAXED_USAGE_THRESHOLD = 0.7;
+export const BUDGET_RELAXED_DELAY_MIN_MS = 5000;
+export const BUDGET_RELAXED_DELAY_MAX_MS = 10000;
+export const BUDGET_MINIMAL_DELAY_MIN_MS = 1000;
+export const BUDGET_MINIMAL_DELAY_MAX_MS = 2000;
+export const BUDGET_COOLDOWN_SLEEP_CHUNK_MS = 3000;
+export const SOFT_THROTTLE_USAGE_LOW = 0.7;
+export const SOFT_THROTTLE_USAGE_MEDIUM = 0.85;
+export const SOFT_THROTTLE_USAGE_HIGH = 0.95;
+export const SOFT_THROTTLE_DELAY_LOW_MS = 500;
+export const SOFT_THROTTLE_DELAY_MEDIUM_MS = 1500;
+export const SOFT_THROTTLE_DELAY_HIGH_MS = 3000;
+export const DEFAULT_OPTIONS = {
+    maxAttempts: 3,
+    enableCooldown: true,
+    maxDelayMs: 5000,
+    maxRetryableDelayMs: 10000,
+};