@wildix/xbees-conversations-utils 4.0.1 → 4.0.2

package/dist-es/streamRateLimitHandlingProxy/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/streamRateLimitHandlingProxy/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 = (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) || limitMs <= 0) {
+        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/streamRateLimitHandlingProxy/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/streamRateLimitHandlingProxy/helpers/processStreamRateLimitHeaders.js

@@ -0,0 +1,42 @@
+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 computeSoftThrottleUsage(limit, remaining) {
+    if (limit <= 0) {
+        return 0;
+    }
+    return Math.max(0, 1 - remaining / limit);
+}
+function computeSoftThrottleDelayMs(limit, remaining) {
+    const usage = computeSoftThrottleUsage(limit, remaining);
+    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 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,
+        });
+        return;
+    }
+    await RedisCooldown.clear(STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, context, {
+        keyPrefix: STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX,
+    });
+}

package/dist-es/streamRateLimitHandlingProxy/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/streamRateLimitHandlingProxy/helpers/registerStreamInterceptors.js

@@ -0,0 +1,60 @@
+import { processStreamBudgetHeaders } from './processStreamBudgetHeaders';
+import { processStreamRateLimitHeaders } from './processStreamRateLimitHeaders';
+const attachedInterceptors = new WeakSet();
+function hasResponseInterceptors(value) {
+    return ((typeof value === 'object' || typeof value === 'function') &&
+        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 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);
+    try {
+        axiosInstance.interceptors.response.use(async (response) => {
+            try {
+                await processStreamBudgetHeaders(response?.headers, context);
+                await processStreamRateLimitHeaders(response?.headers, context);
+            }
+            catch (error) {
+                logger.warn('Failed to process Stream response headers in interceptor', { error });
+            }
+            return response;
+        }, async (error) => {
+            try {
+                await processStreamBudgetHeaders(error?.response?.headers, context);
+                await processStreamRateLimitHeaders(error?.response?.headers, context);
+            }
+            catch (interceptorError) {
+                logger.warn('Failed to process Stream error headers in interceptor', { error: interceptorError });
+            }
+            return Promise.reject(error);
+        });
+    }
+    catch (error) {
+        attachedInterceptors.delete(axiosInstance);
+        logger.warn('Failed to register Stream response interceptors', { error });
+    }
+}

package/dist-es/streamRateLimitHandlingProxy/helpers/sleep.js

@@ -0,0 +1,4 @@
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export default sleep;

package/dist-es/streamRateLimitHandlingProxy/helpers/splitCallArgsAndOptions.js

@@ -0,0 +1,17 @@
+import { STREAM_RATE_LIMIT_OPTIONS_MARKER } from '../constants';
+function isStreamRateLimitOptionsToken(value) {
+    return typeof value === 'object' && value !== null && STREAM_RATE_LIMIT_OPTIONS_MARKER in value;
+}
+export function splitCallArgsAndOptions(args) {
+    if (args.length === 0) {
+        return { callArgs: args, callOptions: {} };
+    }
+    const lastArg = args[args.length - 1];
+    if (isStreamRateLimitOptionsToken(lastArg)) {
+        return {
+            callArgs: args.slice(0, -1),
+            callOptions: lastArg[STREAM_RATE_LIMIT_OPTIONS_MARKER],
+        };
+    }
+    return { callArgs: args, callOptions: {} };
+}

package/dist-es/streamRateLimitHandlingProxy/index.js

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

package/dist-es/streamRateLimitHandlingProxy/types.js

@@ -0,0 +1 @@
+import { STREAM_RATE_LIMIT_OPTIONS_MARKER } from './constants';

package/dist-es/streamRateLimitHandlingProxy/withStreamRateLimitOptions.js

@@ -0,0 +1,6 @@
+import { STREAM_RATE_LIMIT_OPTIONS_MARKER } from './constants';
+export function withStreamRateLimitOptions(options) {
+    return {
+        [STREAM_RATE_LIMIT_OPTIONS_MARKER]: options,
+    };
+}

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

@@ -1,2 +1,3 @@
+export declare const ANONYMOUS_EMAIL_DOMAIN = "anonymous.wildix.com";
 export declare function generateAnonymousUserEmailOrThrowError(streamId: string): string;
 export declare function isAnonymousUserEmail(value: string): boolean;

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

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

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

@@ -0,0 +1,29 @@
+import { StreamRateLimitRetryOptions } from './types';
+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 declare const DEFAULT_MAX_DELAY_MS = 5000;
+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_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;
+export declare const BUDGET_DELAY_MAX_MS = 60000;
+export declare const BUDGET_CLEAR_USAGE_THRESHOLD = 0.6;
+export declare const BUDGET_RELAXED_USAGE_THRESHOLD = 0.7;
+export declare const BUDGET_RELAXED_DELAY_MIN_MS = 5000;
+export declare const BUDGET_RELAXED_DELAY_MAX_MS = 10000;
+export declare const BUDGET_MINIMAL_DELAY_MIN_MS = 1000;
+export declare const BUDGET_MINIMAL_DELAY_MAX_MS = 2000;
+export declare const BUDGET_COOLDOWN_SLEEP_CHUNK_MS = 3000;
+export declare const SOFT_THROTTLE_USAGE_LOW = 0.7;
+export declare const SOFT_THROTTLE_USAGE_MEDIUM = 0.85;
+export declare const SOFT_THROTTLE_USAGE_HIGH = 0.95;
+export declare const SOFT_THROTTLE_DELAY_LOW_MS = 500;
+export declare const SOFT_THROTTLE_DELAY_MEDIUM_MS = 1500;
+export declare const SOFT_THROTTLE_DELAY_HIGH_MS = 3000;
+export declare const DEFAULT_OPTIONS: StreamRateLimitRetryOptions;

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

@@ -0,0 +1,11 @@
+import { StreamChat } from 'stream-chat';
+import { StreamType } from '../stream';
+import { LoggerContext, MethodWithRateLimitOptions, RedisContext } from './types';
+export type RateLimited<T extends object> = {
+    [Key in keyof T]: MethodWithRateLimitOptions<T[Key]>;
+};
+/**
+ * Creates a proxy around a Stream client that transparently applies rate-limit handling
+ * to method calls and recursively wraps returned channel objects with the same behavior.
+ */
+export declare function createRateLimitedStreamProxy(stream: StreamChat<StreamType>, context: LoggerContext & RedisContext): RateLimited<StreamChat<StreamType>>;

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

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

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

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

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

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

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

@@ -0,0 +1,11 @@
+/**
+ * This file is auto-generated by `scripts/generateRateLimitMethodNames.mjs`.
+ * Do not edit manually.
+ */
+export declare const STREAM_METHOD_NAMES: readonly ["_addChannelConfig", "_buildWSPayload", "_callClientListeners", "_createImport", "_createImportURL", "_deleteUserMessageReference", "_enrichAxiosOptions", "_getConnectionID", "_getImport", "_getToken", "_handleClientEvent", "_handleUserEvent", "_hasConnectionID", "_isUsingServerAuth", "_listImports", "_logApiError", "_logApiRequest", "_logApiResponse", "_muteStatus", "_normalizeDate", "_normalizeExpiration", "_queryFlagReports", "_queryFlags", "_reviewFlagReport", "_sayHi", "_setToken", "_setupConnection", "_setUser", "_startCleaning", "_unblockMessage", "_updateMemberWatcherReferences", "_updateUserMessageReferences", "_updateUserReferences", "_validateAndGetMessageId", "addDevice", "banUser", "channel", "closeConnection", "commitMessage", "connect", "connectAnonymousUser", "connectUser", "createAbortControllerForNextRequest", "createBlockList", "createCampaign", "createChannelType", "createCommand", "createPermission", "createRole", "createSegment", "createToken", "deactivateUser", "deactivateUsers", "delete", "deleteBlockList", "deleteCampaign", "deleteChannels", "deleteChannelType", "deleteCommand", "deleteMessage", "deletePermission", "deletePushProvider", "deleteRole", "deleteSegment", "deleteUser", "deleteUsers", "devToken", "disconnect", "disconnectUser", "dispatchEvent", "doAxiosRequest", "enrichURL", "errorFromResponse", "exportChannel", "exportChannels", "exportUser", "exportUsers", "flagMessage", "flagUser", "get", "getAppSettings", "getAuthType", "getBlockList", "getCallToken", "getChannelById", "getChannelByMembers", "getChannelType", "getCommand", "getDevices", "getExportChannelStatus", "getMessage", "getPermission", "getRateLimits", "getTask", "getUnreadCount", "getUserAgent", "handleEvent", "handleResponse", "hydrateActiveChannels", "listBlockLists", "listChannelTypes", "listCommands", "listPermissions", "listPushProviders", "listRoles", "markAllRead", "markChannelsRead", "muteUser", "off", "on", "openConnection", "partialUpdateMessage", "partialUpdateUser", "partialUpdateUsers", "patch", "pinMessage", "post", "put", "queryBannedUsers", "queryCampaigns", "queryChannels", "queryMessageFlags", "queryRecipients", "querySegments", "queryUsers", "reactivateUser", "reactivateUsers", "recoverState", "removeDevice", "removeShadowBan", "restoreUsers", "resumeCampaign", "revokeTokens", "revokeUsersToken", "revokeUserToken", "scheduleCampaign", "search", "sendFile", "sendUserCustomEvent", "setAnonymousUser", "setBaseURL", "setGuestUser", "setLocalDevice", "setUser", "setUserAgent", "shadowBan", "stopCampaign", "sync", "testCampaign", "testPushSettings", "testSQSSettings", "translateMessage", "unbanUser", "unblockMessage", "unflagMessage", "unflagUser", "unmuteUser", "unpinMessage", "updateAppSettings", "updateBlockList", "updateCampaign", "updateChannelType", "updateCommand", "updateMessage", "updatePermission", "updateSegment", "updateUser", "updateUsers", "upsertPushProvider", "upsertUser", "upsertUsers", "userMuteStatus", "verifyWebhook"];
+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 STREAM_CHANNEL_RESULT_METHOD_NAMES: readonly ["channel", "getChannelById", "getChannelByMembers", "hydrateActiveChannels", "queryChannels"];
+export declare const STREAM_SYNC_CHANNEL_RESULT_METHOD_NAMES: readonly ["channel", "getChannelById", "getChannelByMembers", "hydrateActiveChannels"];
+export declare const CHANNEL_METHOD_NAMES: readonly ["_callChannelListeners", "_channelURL", "_checkInitialized", "_countMessageAsUnread", "_disconnect", "_extendEventWithOwnReactions", "_handleChannelEvent", "_initializeState", "_update", "acceptInvite", "addMembers", "addModerators", "assignRoles", "banUser", "clean", "countUnread", "countUnreadMentions", "create", "createCall", "delete", "deleteFile", "deleteImage", "deleteReaction", "demoteModerators", "disableSlowMode", "enableSlowMode", "getClient", "getConfig", "getMessagesById", "getPinnedMessages", "getReactions", "getReplies", "hide", "inviteMembers", "keystroke", "lastMessage", "lastRead", "markRead", "markUnread", "mute", "muteStatus", "off", "on", "query", "queryMembers", "rejectInvite", "removeMembers", "removeShadowBan", "search", "sendAction", "sendEvent", "sendFile", "sendImage", "sendMessage", "sendReaction", "shadowBan", "show", "stopTyping", "stopWatching", "truncate", "unbanUser", "unmute", "update", "updatePartial", "watch"];
+export declare const CHANNEL_SYNC_METHOD_NAMES: readonly ["_callChannelListeners", "_channelURL", "_checkInitialized", "_countMessageAsUnread", "_disconnect", "_extendEventWithOwnReactions", "_handleChannelEvent", "_initializeState", "clean", "countUnread", "countUnreadMentions", "getConfig", "lastMessage", "lastRead", "muteStatus", "off", "on"];
+export declare const CHANNEL_SYNC_PROXY_RESULT_METHOD_NAMES: readonly ["getClient"];

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

@@ -0,0 +1,11 @@
+import { LoggerContext, RedisContext, RedisCooldownOptions } from '../types';
+export declare class RedisCooldown {
+    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 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/createRateLimitExceededException.d.ts

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

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

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

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

@@ -0,0 +1,4 @@
+import { StreamHeaders } from '../types';
+export declare function getHeaderCaseInsensitive(headers: StreamHeaders | Record<string, unknown> | undefined, key: string): unknown;
+export declare function parseHeaderNumber(headers: StreamHeaders | Record<string, unknown>, key: string): number | undefined;
+export declare function normalizeResetToEpochMs(reset: number): number;

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

@@ -0,0 +1,6 @@
+/**
+ * Detects Stream channel-like objects.
+ * These objects should be correctly wrapped to keep rate-limit behavior
+ * on methods returned from other proxied calls.
+ */
+export declare function isStreamChannelLike(value: unknown): value is object;

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

@@ -0,0 +1,9 @@
+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 usage is between 60% and 80%, keeps a shorter cooldown.
+ * - If usage drops below 60%, clears 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/processStreamRateLimitException.d.ts

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

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

@@ -0,0 +1,6 @@
+import { LoggerContext, RedisContext, StreamHeaders } from '../types';
+/**
+ * Applies soft global throttle from x-ratelimit-* headers to smooth bursts
+ * before hard 429 throttling starts.
+ */
+export declare function processStreamRateLimitHeaders(headers: StreamHeaders | undefined, context: LoggerContext & RedisContext): 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/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/helpers/registerStreamInterceptors.d.ts

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

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

@@ -0,0 +1,6 @@
+import { ArgsAndOptions } from '../types';
+/**
+ * Splits original call args and optional rate-limit options token.
+ * If no token is provided, options fallback to an empty object.
+ */
+export declare function splitCallArgsAndOptions(args: unknown[]): ArgsAndOptions;

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

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

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

@@ -0,0 +1,68 @@
+import Redis from 'ioredis';
+import { StreamChat } from 'stream-chat';
+import { StreamChannel, StreamType } from '../stream';
+import { STREAM_RATE_LIMIT_OPTIONS_MARKER } from './constants';
+import { Logger } from '@aws-lambda-powertools/logger';
+export type StreamOperationType = keyof StreamChat<StreamType> | keyof StreamChannel;
+export interface StreamRateLimitRetryOptions {
+    enableCooldown: boolean;
+    maxAttempts: number;
+    maxDelayMs: number;
+    maxRetryableDelayMs: number;
+}
+export type StreamRateLimitOptionsToken = {
+    [STREAM_RATE_LIMIT_OPTIONS_MARKER]: Partial<StreamRateLimitRetryOptions>;
+};
+export type MethodWithRateLimitOptions<T> = T extends (...args: infer Args) => infer Result ? T & ((...args: [...Args, StreamRateLimitOptionsToken?]) => Result) : T;
+export type RedisContext = {
+    redis: Redis;
+};
+export type LoggerContext = {
+    logger: Logger;
+};
+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;
+};
+export type StreamRateLimitSnapshot = {
+    limit: number;
+    remaining: number;
+    reset: 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/dist-types/rateLimits/withStreamRateLimitOptions.d.ts

@@ -0,0 +1,6 @@
+import { StreamRateLimitOptionsToken, StreamRateLimitRetryOptions } from './types';
+/**
+ * Creates a marker token that can be passed as the last argument to proxied Stream methods.
+ * The proxy strips this token from original method args and uses it as per-call retry options.
+ */
+export declare function withStreamRateLimitOptions(options: Partial<StreamRateLimitRetryOptions>): StreamRateLimitOptionsToken;