@wildix/xbees-conversations-utils 1.1.86 → 1.1.88

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

@@ -70,7 +70,7 @@ async function executeWithRateLimitHandling(execute, operation, context, options
         }
         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) {
-            logger.debug('Delaying stream request due to active soft rate-limit cooldown', {
+            logger.info('Delaying stream request due to active soft rate-limit cooldown', {
                 operation,
                 cooldown: softCooldownMs,
             });

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

@@ -26,14 +26,28 @@ function computeSoftThrottleDelayMs(limit, remaining) {
     }
     return 0;
 }
-async function processStreamRateLimitHeaders(headers, context) {
+async function processStreamRateLimitHeaders(headers, context, requestUrl) {
     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) {
+        logger.info('Observed Stream soft throttle rate-limit state', {
+            requestUrl,
+            rateLimit: limit,
+            rateLimitRemaining: remaining,
+            rateLimitUsagePercent: undefined,
+            softThrottleHeadersAvailable: false,
+        });
         return;
     }
     if (limit <= 0 || remaining < 0) {
+        logger.info('Observed Stream soft throttle rate-limit state', {
+            requestUrl,
+            rateLimit: limit,
+            rateLimitRemaining: remaining,
+            rateLimitUsagePercent: undefined,
+            softThrottleHeadersAvailable: false,
+        });
         return;
     }
     const usage = computeSoftThrottleUsage(limit, remaining);
@@ -42,11 +56,20 @@ async function processStreamRateLimitHeaders(headers, context) {
     const currentCooldownMs = await RedisCooldown_1.RedisCooldown.getRemainingMs(constants_1.STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, context, {
         keyPrefix: constants_1.STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX,
     });
+    logger.info('Observed Stream soft throttle rate-limit state', {
+        requestUrl,
+        rateLimit: limit,
+        rateLimitRemaining: remaining,
+        rateLimitUsage: usage,
+        rateLimitUsagePercent: usagePercent,
+        softThrottleCooldownMs: delayMs,
+        softThrottleActive: delayMs > 0,
+    });
     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(currentCooldownMs > 0 ? 'Updating soft stream rate-limit cooldown' : 'Enabling soft stream rate-limit cooldown', {
+        logger.info(currentCooldownMs > 0 ? 'Updating soft stream rate-limit cooldown' : 'Enabling soft stream rate-limit cooldown', {
             rateLimit: limit,
             rateLimitRemaining: remaining,
             rateLimitUsage: usage,
@@ -60,7 +83,7 @@ async function processStreamRateLimitHeaders(headers, context) {
         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', {
+        logger.info('Clearing soft stream rate-limit cooldown', {
             rateLimit: limit,
             rateLimitRemaining: remaining,
             rateLimitUsage: usage,

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

@@ -11,34 +11,73 @@ function hasResponseInterceptors(value) {
 }
 function resolveAxiosInstance(stream) {
     if (hasResponseInterceptors(stream)) {
-        return stream;
+        return {
+            axiosInstance: stream,
+            source: 'stream',
+        };
     }
     if (typeof stream !== 'object' || stream === null) {
-        return;
+        return {};
     }
     const maybeStream = stream;
     if (hasResponseInterceptors(maybeStream.axiosInstance)) {
-        return maybeStream.axiosInstance;
+        return {
+            axiosInstance: maybeStream.axiosInstance,
+            source: 'stream.axiosInstance',
+        };
     }
     if (hasResponseInterceptors(maybeStream._client?.axiosInstance)) {
-        return maybeStream._client?.axiosInstance;
+        return {
+            axiosInstance: maybeStream._client?.axiosInstance,
+            source: 'stream._client.axiosInstance',
+        };
+    }
+    return {};
+}
+function getOwnKeysPreview(value) {
+    if (typeof value !== 'object' || value === null) {
+        return;
     }
+    return Object.keys(value).slice(0, 20);
+}
+function resolveRequestUrl(responseOrError) {
+    return responseOrError.config?.url ?? responseOrError.response?.config?.url;
 }
 function registerStreamInterceptors(stream, context) {
     const { logger } = context;
-    const axiosInstance = resolveAxiosInstance(stream);
+    const { axiosInstance, source } = resolveAxiosInstance(stream);
     if (!axiosInstance || !axiosInstance.interceptors?.response?.use) {
-        logger.warn('Unable to register stream budget & rate limit interceptors: axios instance not found');
+        logger.warn('Unable to register stream budget & rate limit interceptors: axios instance not found', {
+            streamConstructorName: typeof stream === 'object' && stream !== null ? stream.constructor?.name : undefined,
+            streamKeysPreview: getOwnKeysPreview(stream),
+            hasAxiosInstanceField: typeof stream === 'object' && stream !== null && 'axiosInstance' in stream,
+            hasNestedClientField: typeof stream === 'object' && stream !== null && '_client' in stream,
+            nestedClientKeysPreview: typeof stream === 'object' && stream !== null
+                ? getOwnKeysPreview(stream._client)
+                : undefined,
+        });
         return;
     }
+    logger.info('Resolved axios instance for Stream interceptors', {
+        source,
+        streamConstructorName: typeof stream === 'object' && stream !== null ? stream.constructor?.name : undefined,
+        axiosConstructorName: typeof axiosInstance === 'object' && axiosInstance !== null ? axiosInstance.constructor?.name : undefined,
+        axiosKeysPreview: getOwnKeysPreview(axiosInstance),
+    });
     if (attachedInterceptors.has(axiosInstance)) {
+        logger.info('Stream interceptors already attached', {
+            source,
+        });
         return;
     }
     attachedInterceptors.add(axiosInstance);
+    logger.info('Attaching Stream response interceptors', {
+        source,
+    });
     axiosInstance.interceptors.response.use(async (response) => {
         try {
             await (0, processStreamBudgetHeaders_1.processStreamBudgetHeaders)(response?.headers, context);
-            await (0, processStreamRateLimitHeaders_1.processStreamRateLimitHeaders)(response?.headers, context);
+            await (0, processStreamRateLimitHeaders_1.processStreamRateLimitHeaders)(response?.headers, context, resolveRequestUrl(response));
         }
         catch (error) {
             logger.warn('Failed to process Stream response headers in interceptor', { error });
@@ -47,12 +86,15 @@ function registerStreamInterceptors(stream, context) {
     }, async (error) => {
         try {
             await (0, processStreamBudgetHeaders_1.processStreamBudgetHeaders)(error?.response?.headers, context);
-            await (0, processStreamRateLimitHeaders_1.processStreamRateLimitHeaders)(error?.response?.headers, context);
+            await (0, processStreamRateLimitHeaders_1.processStreamRateLimitHeaders)(error?.response?.headers, context, resolveRequestUrl(error));
         }
         catch (interceptorError) {
             logger.warn('Failed to process Stream error headers in interceptor', { error: interceptorError });
         }
         return Promise.reject(error);
     });
+    logger.info('Stream response interceptors attached', {
+        source,
+    });
 }
 exports.registerStreamInterceptors = registerStreamInterceptors;

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

@@ -67,7 +67,7 @@ export async function executeWithRateLimitHandling(execute, operation, context,
         }
         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', {
+            logger.info('Delaying stream request due to active soft rate-limit cooldown', {
                 operation,
                 cooldown: softCooldownMs,
             });

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

@@ -23,14 +23,28 @@ function computeSoftThrottleDelayMs(limit, remaining) {
     }
     return 0;
 }
-export async function processStreamRateLimitHeaders(headers, context) {
+export async function processStreamRateLimitHeaders(headers, context, requestUrl) {
     const { logger } = context;
     const limit = parseHeaderNumber(headers ?? {}, 'x-ratelimit-limit');
     const remaining = parseHeaderNumber(headers ?? {}, 'x-ratelimit-remaining');
     if (limit === undefined || remaining === undefined) {
+        logger.info('Observed Stream soft throttle rate-limit state', {
+            requestUrl,
+            rateLimit: limit,
+            rateLimitRemaining: remaining,
+            rateLimitUsagePercent: undefined,
+            softThrottleHeadersAvailable: false,
+        });
         return;
     }
     if (limit <= 0 || remaining < 0) {
+        logger.info('Observed Stream soft throttle rate-limit state', {
+            requestUrl,
+            rateLimit: limit,
+            rateLimitRemaining: remaining,
+            rateLimitUsagePercent: undefined,
+            softThrottleHeadersAvailable: false,
+        });
         return;
     }
     const usage = computeSoftThrottleUsage(limit, remaining);
@@ -39,11 +53,20 @@ export async function processStreamRateLimitHeaders(headers, context) {
     const currentCooldownMs = await RedisCooldown.getRemainingMs(STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, context, {
         keyPrefix: STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX,
     });
+    logger.info('Observed Stream soft throttle rate-limit state', {
+        requestUrl,
+        rateLimit: limit,
+        rateLimitRemaining: remaining,
+        rateLimitUsage: usage,
+        rateLimitUsagePercent: usagePercent,
+        softThrottleCooldownMs: delayMs,
+        softThrottleActive: delayMs > 0,
+    });
     if (delayMs > 0) {
         await RedisCooldown.setRemainingMs(STREAM_RATE_LIMIT_SOFT_COOLDOWN_KEY, delayMs, context, {
             keyPrefix: STREAM_RATE_LIMIT_COOLDOWN_KEY_PREFIX,
         });
-        logger.debug(currentCooldownMs > 0 ? 'Updating soft stream rate-limit cooldown' : 'Enabling soft stream rate-limit cooldown', {
+        logger.info(currentCooldownMs > 0 ? 'Updating soft stream rate-limit cooldown' : 'Enabling soft stream rate-limit cooldown', {
             rateLimit: limit,
             rateLimitRemaining: remaining,
             rateLimitUsage: usage,
@@ -57,7 +80,7 @@ export async function processStreamRateLimitHeaders(headers, context) {
         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', {
+        logger.info('Clearing soft stream rate-limit cooldown', {
             rateLimit: limit,
             rateLimitRemaining: remaining,
             rateLimitUsage: usage,

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

@@ -8,34 +8,73 @@ function hasResponseInterceptors(value) {
 }
 function resolveAxiosInstance(stream) {
     if (hasResponseInterceptors(stream)) {
-        return stream;
+        return {
+            axiosInstance: stream,
+            source: 'stream',
+        };
     }
     if (typeof stream !== 'object' || stream === null) {
-        return;
+        return {};
     }
     const maybeStream = stream;
     if (hasResponseInterceptors(maybeStream.axiosInstance)) {
-        return maybeStream.axiosInstance;
+        return {
+            axiosInstance: maybeStream.axiosInstance,
+            source: 'stream.axiosInstance',
+        };
     }
     if (hasResponseInterceptors(maybeStream._client?.axiosInstance)) {
-        return maybeStream._client?.axiosInstance;
+        return {
+            axiosInstance: maybeStream._client?.axiosInstance,
+            source: 'stream._client.axiosInstance',
+        };
+    }
+    return {};
+}
+function getOwnKeysPreview(value) {
+    if (typeof value !== 'object' || value === null) {
+        return;
     }
+    return Object.keys(value).slice(0, 20);
+}
+function resolveRequestUrl(responseOrError) {
+    return responseOrError.config?.url ?? responseOrError.response?.config?.url;
 }
 export function registerStreamInterceptors(stream, context) {
     const { logger } = context;
-    const axiosInstance = resolveAxiosInstance(stream);
+    const { axiosInstance, source } = resolveAxiosInstance(stream);
     if (!axiosInstance || !axiosInstance.interceptors?.response?.use) {
-        logger.warn('Unable to register stream budget & rate limit interceptors: axios instance not found');
+        logger.warn('Unable to register stream budget & rate limit interceptors: axios instance not found', {
+            streamConstructorName: typeof stream === 'object' && stream !== null ? stream.constructor?.name : undefined,
+            streamKeysPreview: getOwnKeysPreview(stream),
+            hasAxiosInstanceField: typeof stream === 'object' && stream !== null && 'axiosInstance' in stream,
+            hasNestedClientField: typeof stream === 'object' && stream !== null && '_client' in stream,
+            nestedClientKeysPreview: typeof stream === 'object' && stream !== null
+                ? getOwnKeysPreview(stream._client)
+                : undefined,
+        });
         return;
     }
+    logger.info('Resolved axios instance for Stream interceptors', {
+        source,
+        streamConstructorName: typeof stream === 'object' && stream !== null ? stream.constructor?.name : undefined,
+        axiosConstructorName: typeof axiosInstance === 'object' && axiosInstance !== null ? axiosInstance.constructor?.name : undefined,
+        axiosKeysPreview: getOwnKeysPreview(axiosInstance),
+    });
     if (attachedInterceptors.has(axiosInstance)) {
+        logger.info('Stream interceptors already attached', {
+            source,
+        });
         return;
     }
     attachedInterceptors.add(axiosInstance);
+    logger.info('Attaching Stream response interceptors', {
+        source,
+    });
     axiosInstance.interceptors.response.use(async (response) => {
         try {
             await processStreamBudgetHeaders(response?.headers, context);
-            await processStreamRateLimitHeaders(response?.headers, context);
+            await processStreamRateLimitHeaders(response?.headers, context, resolveRequestUrl(response));
         }
         catch (error) {
             logger.warn('Failed to process Stream response headers in interceptor', { error });
@@ -44,11 +83,14 @@ export function registerStreamInterceptors(stream, context) {
     }, async (error) => {
         try {
             await processStreamBudgetHeaders(error?.response?.headers, context);
-            await processStreamRateLimitHeaders(error?.response?.headers, context);
+            await processStreamRateLimitHeaders(error?.response?.headers, context, resolveRequestUrl(error));
         }
         catch (interceptorError) {
             logger.warn('Failed to process Stream error headers in interceptor', { error: interceptorError });
         }
         return Promise.reject(error);
     });
+    logger.info('Stream response interceptors attached', {
+        source,
+    });
 }

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

@@ -3,4 +3,4 @@ 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>;
+export declare function processStreamRateLimitHeaders(headers: StreamHeaders | undefined, context: LoggerContext & RedisContext, requestUrl?: string): Promise<void>;

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

@@ -30,6 +30,9 @@ export type RedisCooldownOptions = {
 };
 /** Generic HTTP headers shape returned by the Stream SDK transport layer. */
 export type StreamHeaders = Record<string, unknown>;
+export type StreamRequestConfig = {
+    url?: string;
+};
 /** Parsed GetStream budget headers used to manage app-wide cooldown. */
 export type StreamBudgetHeaders = {
     limitMs?: number;
@@ -44,9 +47,11 @@ export type StreamRateLimitSnapshot = {
 /** Axios response shape used by budget interceptor. */
 export type StreamBudgetInterceptorResponse = {
     headers?: StreamHeaders;
+    config?: StreamRequestConfig;
 };
 /** Axios error shape used by budget interceptor. */
 export type StreamBudgetInterceptorError = {
+    config?: StreamRequestConfig;
     response?: StreamBudgetInterceptorResponse;
 };
 /** Minimal axios response interceptor manager contract required by this package. */

package/package.json

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