@wildix/xbees-conversations-utils 1.3.0 → 1.3.1

package/README.md

@@ -1,118 +1,18 @@
-# `streamRateLimitHandlingProxy`
+# `xbees-conversations-utils`
 
-This package wraps a `StreamChat` client into a proxy that adds shared rate-limit protection around Stream SDK calls without changing the normal sync API contract. Async calls go through retry / cooldown handling, while sync methods stay sync. If a proxied call returns a channel-like object, that object is wrapped too, so the same protection continues on nested channel operations.
+Utility helpers for working with x-bees conversations data.
 
-## Public entry points
+## Included modules
 
-- `createRateLimitedStreamProxy(stream, {redis, logger})`
-  Creates the proxy, attaches response interceptors once, and returns a rate-limit-aware `StreamChat` instance.
-  Code: `src/streamRateLimitHandlingProxy/createRateLimitedStreamProxy.ts`
-- `withStreamRateLimitOptions(options)`
-  Builds a marker token that can be passed as the last argument of a proxied async call to override retry behavior for that single call.
-  Code: `src/streamRateLimitHandlingProxy/withStreamRateLimitOptions.ts`
-- Public exports are re-exported from `src/streamRateLimitHandlingProxy/index.ts` and then from `src/index.ts`.
+- `anonymousEmail`
+  Helpers for generating and validating anonymous user emails.
+- `normalization`
+  Helpers for normalizing and localizing Stream payloads into `@wildix/xbees-conversations-client` models.
+- `stream`
+  Shared Stream Chat types used by normalization helpers and downstream consumers.
+- `types`
+  Localized conversation and presence-related TypeScript types.
 
-## How it works
+## Notes
 
-1. `createRateLimitedStreamProxy(...)` tries to register axios response interceptors on the underlying Stream transport.
-2. The proxy classifies Stream methods into groups generated in `generatedMethodNames.ts`:
-   - pure sync methods: returned as-is;
-   - sync methods returning channel/client objects: returned sync, but results are re-wrapped;
-   - async methods: executed through the rate-limit handler.
-3. Every async call is normalized through `executeWithRateLimitHandling(...)`.
-4. Returned channel-like objects are detected and wrapped again, so calls like `stream.channel(...).sendMessage(...)` stay protected end to end.
-
-If the underlying Stream SDK transport does not expose an axios instance, the proxy still works, but shared protection driven by response headers becomes less effective because no interceptors can be attached.
-
-## Protection layers
-
-### 1. Soft global throttle
-
-The interceptor reads `x-ratelimit-limit` and `x-ratelimit-remaining`. When usage becomes high, it enables a short shared Redis cooldown before real 429 responses start happening. This smooths bursts instead of waiting for hard throttling.
-
-- Trigger source: response headers on successful or failed requests
-- Effect:
-  - usage `>= 95%`: delay next requests by `3000ms`;
-  - usage between `85%` and `95%`: delay by `1500ms`;
-  - usage between `70%` and `85%`: delay by `500ms`;
-  - usage `< 70%`: clear soft throttle.
-- Scope: global shared throttle
-- Code: `helpers/processStreamRateLimitHeaders.ts`
-
-### 2. Hard per-operation 429 cooldown
-
-If Stream returns HTTP 429, the handler converts that error into `RateLimitExceededException`, calculates retry delay from `retry-after` or fallback values, stores a Redis cooldown for the specific operation, and optionally retries the call.
-
-If another worker hits the same operation while that cooldown is still active, the request is short-circuited locally before touching Stream. To keep that synthetic error useful, the latest real `x-ratelimit-*` snapshot is cached in Redis next to the cooldown and reused in the locally generated exception.
-
-- Trigger source: HTTP 429 / `retry-after` / `x-ratelimit-*`
-- Effect: per-operation block, optional retry, synthetic local short-circuit when cooldown is already known
-- Scope: operation-level
-- Code:
-  - execution flow: `helpers/executeWithRateLimitHandling.ts`
-  - 429 parsing: `helpers/processStreamRateLimitException.ts`
-  - exception creation: `helpers/createRateLimitExceededException.ts`
-  - snapshot serialization: `helpers/rateLimitSnapshot.ts`
-
-### 3. App-wide budget cooldown
-
-The interceptor also reads `x-budget-*` headers. If overall Stream app budget usage becomes high, it enables a global Redis cooldown. While this cooldown is active, requests are delayed in small sleep chunks so they can resume early if a fresher response lowers the cooldown.
-
-- Trigger source: `x-budget-limit-ms`, `x-budget-remaining-ms`, `x-budget-used-ms`
-- Effect:
-  - usage `>= 80%`: enable strong cooldown (`30s-60s`);
-  - usage between `70%` and `80%`: keep a relaxed cooldown (`5s-10s`);
-  - usage between `60%` and `70%`: keep a minimal cooldown (`1s-2s`);
-  - usage `< 60%`: clear cooldown.
-- Scope: whole application, not a single operation
-- Code: `helpers/processStreamBudgetHeaders.ts`
-
-## Retry and cooldown behavior
-
-- Local preflight checks happen before request execution when `enableCooldown` is on:
-  - active per-operation cooldown: fail fast with a synthetic `RateLimitExceededException`;
-  - active soft throttle: delay request briefly;
-  - active budget cooldown: delay request globally.
-- Real 429 responses can still be retried if:
-  - `attempt < maxAttempts`;
-  - computed delay `<= maxRetryableDelayMs`.
-- Delay calculation rules:
-  - if Stream provides `Retry-After` / reset information, that server value is preferred even if it is larger than `maxDelayMs`;
-  - `maxDelayMs` only caps fallback delay when server retry timing is missing or malformed;
-  - `maxRetryableDelayMs` decides whether that computed delay is still retryable or should be propagated immediately.
-- If retry is not allowed, the processed rate-limit exception is propagated to the caller.
-
-Core logic: `src/streamRateLimitHandlingProxy/helpers/executeWithRateLimitHandling.ts`
-
-## Configuration
-
-Default behavior is defined in `src/streamRateLimitHandlingProxy/constants.ts`:
-
-- `maxAttempts = 3`
-- `enableCooldown = true`
-- `maxDelayMs = 5000`
-- `maxRetryableDelayMs = 10000`
-
-The same file also contains:
-
-- Redis key prefixes for hard cooldown, soft throttle, and budget cooldown
-- fallback retry values and jitter
-- budget thresholds and cooldown ranges
-- soft-throttle thresholds and delays
-
-Notes:
-
-- `enableCooldown` controls local Redis-based preflight checks and shared cooldown reuse.
-- `maxDelayMs` is a fallback cap, not a hard upper bound for server-provided `Retry-After`.
-- Missing / invalid rate-limit headers do not break the proxy, but they reduce how much shared throttling state can be inferred.
-
-Per-call overrides are passed as the last argument:
-
-```ts
-stream.queryChannels(filters, sort, options, withStreamRateLimitOptions({
-  maxAttempts: 1,
-  maxRetryableDelayMs: 0,
-}));
-```
-
-Argument extraction is implemented in `helpers/splitCallArgsAndOptions.ts`.
+The Stream rate-limit handling proxy was moved into the dedicated `@wildix/stream-proxy` package.

package/dist-cjs/index.js

@@ -4,5 +4,4 @@ const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./anonymousEmail"), exports);
 tslib_1.__exportStar(require("./normalization"), exports);
 tslib_1.__exportStar(require("./stream"), exports);
-tslib_1.__exportStar(require("./streamRateLimitHandlingProxy"), exports);
 tslib_1.__exportStar(require("./types"), exports);

package/dist-es/index.js

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

package/dist-types/index.d.ts

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

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@wildix/xbees-conversations-utils",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "",
   "main": "./dist-cjs/index.js",
   "module": "./dist-es/index.js",
   "types": "./dist-types/index.d.ts",
   "scripts": {
-    "prebuild": "node ./scripts/generateRateLimitMethodNames.mjs",
     "build": "concurrently 'yarn:build:cjs' 'yarn:build:es' 'yarn:build:types'",
     "build:cjs": "tsc -p tsconfig.cjs.json",
     "build:es": "tsc -p tsconfig.es.json",
@@ -25,9 +24,7 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@aws-lambda-powertools/logger": "2.18.0",
     "@wildix/xbees-conversations-client": "1.2.13",
-    "ioredis": "5.10.0",
     "stream-chat": "8.12.1",
     "tslib": "2.5.0"
   },