@teneo-protocol/sdk 1.0.0

package/dist/utils/event-waiter.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Event Waiter Utility
+ * Provides a clean Promise-based API for waiting for events with timeout and filtering
+ * Eliminates callback hell and ensures proper cleanup of listeners and timers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitForEvent = waitForEvent;
+exports.waitForAnyEvent = waitForAnyEvent;
+exports.waitForAllEvents = waitForAllEvents;
+/**
+ * Wait for an event to be emitted with automatic timeout and cleanup
+ *
+ * This utility encapsulates the complex pattern of:
+ * - Setting up event listeners
+ * - Managing timeouts
+ * - Cleaning up listeners and timers in all code paths
+ * - Filtering events
+ *
+ * All cleanup is guaranteed to happen, preventing memory leaks.
+ *
+ * @param emitter - The EventEmitter to listen to
+ * @param eventName - The name of the event to wait for
+ * @param options - Configuration options
+ * @returns Promise that resolves with the event data or rejects on timeout
+ *
+ * @example
+ * ```typescript
+ * // Simple usage: wait for any 'data' event
+ * const data = await waitForEvent(emitter, 'data', { timeout: 5000 });
+ *
+ * // With filter: wait for specific event
+ * const response = await waitForEvent(wsClient, 'agent:response', {
+ *   timeout: 30000,
+ *   filter: (r) => r.taskId === myTaskId,
+ *   timeoutMessage: 'Agent did not respond in time'
+ * });
+ * ```
+ */
+async function waitForEvent(emitter, eventName, options) {
+    return new Promise((resolve, reject) => {
+        let timeoutHandle;
+        let eventHandler;
+        let cleaned = false;
+        // Cleanup function - ensures we only clean up once
+        const cleanup = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+                timeoutHandle = undefined;
+            }
+            if (eventHandler) {
+                emitter.off(eventName, eventHandler);
+                eventHandler = undefined;
+            }
+        };
+        // Event handler - filters and resolves
+        eventHandler = (data) => {
+            // If filter is provided, check if this event matches
+            if (options.filter && !options.filter(data)) {
+                // Not the event we're looking for, keep waiting
+                return;
+            }
+            // This is the event we want!
+            cleanup();
+            resolve(data);
+        };
+        // Timeout handler - rejects after timeout
+        timeoutHandle = setTimeout(() => {
+            cleanup();
+            const message = options.timeoutMessage || `Timeout waiting for event '${eventName}' after ${options.timeout}ms`;
+            reject(new Error(message));
+        }, options.timeout);
+        // Start listening
+        emitter.on(eventName, eventHandler);
+    });
+}
+/**
+ * Wait for multiple events simultaneously (race condition)
+ * Resolves with the first event that fires and matches its filter
+ *
+ * @param waiters - Array of event waiter configurations
+ * @returns Promise that resolves with the first matching event
+ *
+ * @example
+ * ```typescript
+ * // Wait for either success or error
+ * const result = await waitForAnyEvent([
+ *   { emitter: client, eventName: 'auth:success', options: { timeout: 5000 } },
+ *   { emitter: client, eventName: 'auth:error', options: { timeout: 5000 } }
+ * ]);
+ * ```
+ */
+async function waitForAnyEvent(waiters) {
+    return Promise.race(waiters.map(({ emitter, eventName, options }) => waitForEvent(emitter, eventName, options)));
+}
+/**
+ * Wait for all events to fire (all must complete)
+ * Useful when you need multiple events to occur before proceeding
+ *
+ * @param waiters - Array of event waiter configurations
+ * @returns Promise that resolves with array of all event data
+ *
+ * @example
+ * ```typescript
+ * // Wait for both auth and connection
+ * const [authState, connState] = await waitForAllEvents([
+ *   { emitter: client, eventName: 'auth:success', options: { timeout: 5000 } },
+ *   { emitter: client, eventName: 'connection:open', options: { timeout: 5000 } }
+ * ]);
+ * ```
+ */
+async function waitForAllEvents(waiters) {
+    return Promise.all(waiters.map(({ emitter, eventName, options }) => waitForEvent(emitter, eventName, options)));
+}
+//# sourceMappingURL=event-waiter.js.map

package/dist/utils/event-waiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-waiter.js","sourceRoot":"","sources":["../../src/utils/event-waiter.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AA0DH,oCAiDC;AAkBD,0CAYC;AAkBD,4CAYC;AA1ID;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACI,KAAK,UAAU,YAAY,CAChC,OAAqB,EACrB,SAAiB,EACjB,OAA+B;IAE/B,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,IAAI,aAAyC,CAAC;QAC9C,IAAI,YAA6C,CAAC;QAClD,IAAI,OAAO,GAAG,KAAK,CAAC;QAEpB,mDAAmD;QACnD,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YAEf,IAAI,aAAa,EAAE,CAAC;gBAClB,YAAY,CAAC,aAAa,CAAC,CAAC;gBAC5B,aAAa,GAAG,SAAS,CAAC;YAC5B,CAAC;YAED,IAAI,YAAY,EAAE,CAAC;gBACjB,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;gBACrC,YAAY,GAAG,SAAS,CAAC;YAC3B,CAAC;QACH,CAAC,CAAC;QAEF,uCAAuC;QACvC,YAAY,GAAG,CAAC,IAAO,EAAE,EAAE;YACzB,qDAAqD;YACrD,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5C,gDAAgD;gBAChD,OAAO;YACT,CAAC;YAED,6BAA6B;YAC7B,OAAO,EAAE,CAAC;YACV,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC,CAAC;QAEF,0CAA0C;QAC1C,aAAa,GAAG,UAAU,CAAC,GAAG,EAAE;YAC9B,OAAO,EAAE,CAAC;YACV,MAAM,OAAO,GAAG,OAAO,CAAC,cAAc,IAAI,8BAA8B,SAAS,WAAW,OAAO,CAAC,OAAO,IAAI,CAAC;YAChH,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7B,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QAEpB,kBAAkB;QAClB,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACI,KAAK,UAAU,eAAe,CACnC,OAIE;IAEF,OAAO,OAAO,CAAC,IAAI,CACjB,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,EAAE,CAC9C,YAAY,CAAI,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,CAC7C,CACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACI,KAAK,UAAU,gBAAgB,CACpC,OAIE;IAEF,OAAO,OAAO,CAAC,GAAG,CAChB,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,EAAE,CAC9C,YAAY,CAAI,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,CAC7C,CACF,CAAC;AACJ,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Utility functions and helpers for the Teneo Protocol SDK
+ */
+/**
+ * Logger creation utilities
+ */
+export { createPinoLogger } from "./logger";
+/**
+ * SSRF protection utilities for webhook URL validation
+ * Prevents Server-Side Request Forgery attacks
+ */
+export { validateWebhookUrl, isPrivateIP, isCloudMetadataEndpoint } from "./ssrf-validator";
+/**
+ * Event waiting utilities for async event handling
+ * Wait for specific events with timeout support
+ */
+export { waitForEvent, waitForAnyEvent, waitForAllEvents, type WaitForEventOptions } from "./event-waiter";
+/**
+ * Memory-safe bounded queue with overflow strategies
+ * Prevents unbounded memory growth
+ */
+export { BoundedQueue, QueueOverflowError, type OverflowStrategy } from "./bounded-queue";
+/**
+ * Token bucket rate limiter for request throttling
+ */
+export { TokenBucketRateLimiter, RateLimitError } from "./rate-limiter";
+/**
+ * Circuit breaker pattern for fault tolerance
+ * Prevents cascading failures with automatic recovery
+ */
+export { CircuitBreaker, CircuitBreakerError, type CircuitState } from "./circuit-breaker";
+/**
+ * Message deduplication cache with TTL support
+ */
+export { DeduplicationCache } from "./deduplication-cache";
+/**
+ * Ethereum signature verification utilities (SEC-2)
+ * ECDSA signature validation for message authenticity
+ */
+export { SignatureVerifier, type SignatureVerificationOptions, type VerificationResult } from "./signature-verifier";
+/**
+ * Secure private key storage with AES-256-GCM encryption (SEC-3)
+ * Protects private keys from memory dumps
+ */
+export { SecurePrivateKey } from "./secure-private-key";
+/**
+ * Configurable retry strategies for resilient operations (REL-3)
+ * Supports exponential, linear, and constant backoff
+ */
+export { RetryPolicy, RetryStrategySchema, type RetryStrategy, type RetryStrategyType } from "./retry-policy";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C;;;GAGG;AACH,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE5F;;;GAGG;AACH,OAAO,EACL,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,KAAK,mBAAmB,EACzB,MAAM,gBAAgB,CAAC;AAExB;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE1F;;GAEG;AACH,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAExE;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE3F;;GAEG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;GAGG;AACH,OAAO,EACL,iBAAiB,EACjB,KAAK,4BAA4B,EACjC,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B;;;GAGG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;GAGG;AACH,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACvB,MAAM,gBAAgB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Utility functions and helpers for the Teneo Protocol SDK
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryStrategySchema = exports.RetryPolicy = exports.SecurePrivateKey = exports.SignatureVerifier = exports.DeduplicationCache = exports.CircuitBreakerError = exports.CircuitBreaker = exports.RateLimitError = exports.TokenBucketRateLimiter = exports.QueueOverflowError = exports.BoundedQueue = exports.waitForAllEvents = exports.waitForAnyEvent = exports.waitForEvent = exports.isCloudMetadataEndpoint = exports.isPrivateIP = exports.validateWebhookUrl = exports.createPinoLogger = void 0;
+/**
+ * Logger creation utilities
+ */
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "createPinoLogger", { enumerable: true, get: function () { return logger_1.createPinoLogger; } });
+/**
+ * SSRF protection utilities for webhook URL validation
+ * Prevents Server-Side Request Forgery attacks
+ */
+var ssrf_validator_1 = require("./ssrf-validator");
+Object.defineProperty(exports, "validateWebhookUrl", { enumerable: true, get: function () { return ssrf_validator_1.validateWebhookUrl; } });
+Object.defineProperty(exports, "isPrivateIP", { enumerable: true, get: function () { return ssrf_validator_1.isPrivateIP; } });
+Object.defineProperty(exports, "isCloudMetadataEndpoint", { enumerable: true, get: function () { return ssrf_validator_1.isCloudMetadataEndpoint; } });
+/**
+ * Event waiting utilities for async event handling
+ * Wait for specific events with timeout support
+ */
+var event_waiter_1 = require("./event-waiter");
+Object.defineProperty(exports, "waitForEvent", { enumerable: true, get: function () { return event_waiter_1.waitForEvent; } });
+Object.defineProperty(exports, "waitForAnyEvent", { enumerable: true, get: function () { return event_waiter_1.waitForAnyEvent; } });
+Object.defineProperty(exports, "waitForAllEvents", { enumerable: true, get: function () { return event_waiter_1.waitForAllEvents; } });
+/**
+ * Memory-safe bounded queue with overflow strategies
+ * Prevents unbounded memory growth
+ */
+var bounded_queue_1 = require("./bounded-queue");
+Object.defineProperty(exports, "BoundedQueue", { enumerable: true, get: function () { return bounded_queue_1.BoundedQueue; } });
+Object.defineProperty(exports, "QueueOverflowError", { enumerable: true, get: function () { return bounded_queue_1.QueueOverflowError; } });
+/**
+ * Token bucket rate limiter for request throttling
+ */
+var rate_limiter_1 = require("./rate-limiter");
+Object.defineProperty(exports, "TokenBucketRateLimiter", { enumerable: true, get: function () { return rate_limiter_1.TokenBucketRateLimiter; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return rate_limiter_1.RateLimitError; } });
+/**
+ * Circuit breaker pattern for fault tolerance
+ * Prevents cascading failures with automatic recovery
+ */
+var circuit_breaker_1 = require("./circuit-breaker");
+Object.defineProperty(exports, "CircuitBreaker", { enumerable: true, get: function () { return circuit_breaker_1.CircuitBreaker; } });
+Object.defineProperty(exports, "CircuitBreakerError", { enumerable: true, get: function () { return circuit_breaker_1.CircuitBreakerError; } });
+/**
+ * Message deduplication cache with TTL support
+ */
+var deduplication_cache_1 = require("./deduplication-cache");
+Object.defineProperty(exports, "DeduplicationCache", { enumerable: true, get: function () { return deduplication_cache_1.DeduplicationCache; } });
+/**
+ * Ethereum signature verification utilities (SEC-2)
+ * ECDSA signature validation for message authenticity
+ */
+var signature_verifier_1 = require("./signature-verifier");
+Object.defineProperty(exports, "SignatureVerifier", { enumerable: true, get: function () { return signature_verifier_1.SignatureVerifier; } });
+/**
+ * Secure private key storage with AES-256-GCM encryption (SEC-3)
+ * Protects private keys from memory dumps
+ */
+var secure_private_key_1 = require("./secure-private-key");
+Object.defineProperty(exports, "SecurePrivateKey", { enumerable: true, get: function () { return secure_private_key_1.SecurePrivateKey; } });
+/**
+ * Configurable retry strategies for resilient operations (REL-3)
+ * Supports exponential, linear, and constant backoff
+ */
+var retry_policy_1 = require("./retry-policy");
+Object.defineProperty(exports, "RetryPolicy", { enumerable: true, get: function () { return retry_policy_1.RetryPolicy; } });
+Object.defineProperty(exports, "RetryStrategySchema", { enumerable: true, get: function () { return retry_policy_1.RetryStrategySchema; } });
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH;;GAEG;AACH,mCAA4C;AAAnC,0GAAA,gBAAgB,OAAA;AAEzB;;;GAGG;AACH,mDAA4F;AAAnF,oHAAA,kBAAkB,OAAA;AAAE,6GAAA,WAAW,OAAA;AAAE,yHAAA,uBAAuB,OAAA;AAEjE;;;GAGG;AACH,+CAKwB;AAJtB,4GAAA,YAAY,OAAA;AACZ,+GAAA,eAAe,OAAA;AACf,gHAAA,gBAAgB,OAAA;AAIlB;;;GAGG;AACH,iDAA0F;AAAjF,6GAAA,YAAY,OAAA;AAAE,mHAAA,kBAAkB,OAAA;AAEzC;;GAEG;AACH,+CAAwE;AAA/D,sHAAA,sBAAsB,OAAA;AAAE,8GAAA,cAAc,OAAA;AAE/C;;;GAGG;AACH,qDAA2F;AAAlF,iHAAA,cAAc,OAAA;AAAE,sHAAA,mBAAmB,OAAA;AAE5C;;GAEG;AACH,6DAA2D;AAAlD,yHAAA,kBAAkB,OAAA;AAE3B;;;GAGG;AACH,2DAI8B;AAH5B,uHAAA,iBAAiB,OAAA;AAKnB;;;GAGG;AACH,2DAAwD;AAA/C,sHAAA,gBAAgB,OAAA;AAEzB;;;GAGG;AACH,+CAKwB;AAJtB,2GAAA,WAAW,OAAA;AACX,mHAAA,mBAAmB,OAAA"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Logger utility for Teneo Protocol SDK
+ * Provides pino-based logging with structured output and optional pretty printing
+ */
+import type { Logger, LogLevel } from "../types";
+/**
+ * Creates a pino-based logger that conforms to the SDK Logger interface.
+ * Automatically configures pretty printing for development environments.
+ *
+ * @param level - Log level (debug, info, warn, error, silent)
+ * @param name - Logger name for identifying log source (e.g., "TeneoSDK", "WebSocketClient")
+ * @returns Logger instance compatible with SDK Logger interface
+ *
+ * @example
+ * ```typescript
+ * const logger = createPinoLogger('info', 'TeneoSDK');
+ * logger.info('SDK initialized', { wsUrl: 'wss://example.com' });
+ * logger.error('Connection failed', { code: 'CONN_FAILED', attempt: 3 });
+ * ```
+ */
+export declare function createPinoLogger(level: LogLevel, name?: string): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CA+DvE"}

package/dist/utils/logger.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Logger utility for Teneo Protocol SDK
+ * Provides pino-based logging with structured output and optional pretty printing
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPinoLogger = createPinoLogger;
+const pino_1 = __importDefault(require("pino"));
+/**
+ * Creates a pino-based logger that conforms to the SDK Logger interface.
+ * Automatically configures pretty printing for development environments.
+ *
+ * @param level - Log level (debug, info, warn, error, silent)
+ * @param name - Logger name for identifying log source (e.g., "TeneoSDK", "WebSocketClient")
+ * @returns Logger instance compatible with SDK Logger interface
+ *
+ * @example
+ * ```typescript
+ * const logger = createPinoLogger('info', 'TeneoSDK');
+ * logger.info('SDK initialized', { wsUrl: 'wss://example.com' });
+ * logger.error('Connection failed', { code: 'CONN_FAILED', attempt: 3 });
+ * ```
+ */
+function createPinoLogger(level, name) {
+    // Map 'silent' to pino's 'silent' level
+    const pinoLevel = level === "silent" ? "silent" : level;
+    // Create pino logger with optional pretty printing for development
+    const pinoLogger = (0, pino_1.default)({
+        level: pinoLevel,
+        name: name || "TeneoSDK",
+        // Use pino-pretty in development for readable logs
+        transport: process.env.NODE_ENV !== "production"
+            ? {
+                target: "pino-pretty",
+                options: {
+                    colorize: true,
+                    ignore: "pid,hostname",
+                    translateTime: "HH:MM:ss.l",
+                    singleLine: false
+                }
+            }
+            : undefined,
+        // Production: fast JSON logs
+        formatters: process.env.NODE_ENV === "production"
+            ? {
+                level: (label) => {
+                    return { level: label };
+                }
+            }
+            : undefined
+    });
+    // Adapt pino's API to match our Logger interface
+    return {
+        debug: (message, data) => {
+            if (data !== undefined) {
+                pinoLogger.debug(data, message);
+            }
+            else {
+                pinoLogger.debug(message);
+            }
+        },
+        info: (message, data) => {
+            if (data !== undefined) {
+                pinoLogger.info(data, message);
+            }
+            else {
+                pinoLogger.info(message);
+            }
+        },
+        warn: (message, data) => {
+            if (data !== undefined) {
+                pinoLogger.warn(data, message);
+            }
+            else {
+                pinoLogger.warn(message);
+            }
+        },
+        error: (message, data) => {
+            if (data !== undefined) {
+                pinoLogger.error(data, message);
+            }
+            else {
+                pinoLogger.error(message);
+            }
+        }
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;AAoBH,4CA+DC;AAjFD,gDAAwB;AAGxB;;;;;;;;;;;;;;GAcG;AACH,SAAgB,gBAAgB,CAAC,KAAe,EAAE,IAAa;IAC7D,wCAAwC;IACxC,MAAM,SAAS,GAAG,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC;IAExD,mEAAmE;IACnE,MAAM,UAAU,GAAG,IAAA,cAAI,EAAC;QACtB,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,IAAI,IAAI,UAAU;QACxB,mDAAmD;QACnD,SAAS,EACP,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;YACnC,CAAC,CAAC;gBACE,MAAM,EAAE,aAAa;gBACrB,OAAO,EAAE;oBACP,QAAQ,EAAE,IAAI;oBACd,MAAM,EAAE,cAAc;oBACtB,aAAa,EAAE,YAAY;oBAC3B,UAAU,EAAE,KAAK;iBAClB;aACF;YACH,CAAC,CAAC,SAAS;QACf,6BAA6B;QAC7B,UAAU,EACR,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;YACnC,CAAC,CAAC;gBACE,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE;oBACf,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;gBAC1B,CAAC;aACF;YACH,CAAC,CAAC,SAAS;KAChB,CAAC,CAAC;IAEH,iDAAiD;IACjD,OAAO;QACL,KAAK,EAAE,CAAC,OAAe,EAAE,IAAU,EAAE,EAAE;YACrC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAClC,CAAC;iBAAM,CAAC;gBACN,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;QACD,IAAI,EAAE,CAAC,OAAe,EAAE,IAAU,EAAE,EAAE;YACpC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YACjC,CAAC;iBAAM,CAAC;gBACN,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,IAAI,EAAE,CAAC,OAAe,EAAE,IAAU,EAAE,EAAE;YACpC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YACjC,CAAC;iBAAM,CAAC;gBACN,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,KAAK,EAAE,CAAC,OAAe,EAAE,IAAU,EAAE,EAAE;YACrC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAClC,CAAC;iBAAM,CAAC;gBACN,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/utils/rate-limiter.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Token Bucket Rate Limiter
+ * Prevents message flooding and ensures fair resource usage
+ *
+ * Uses the token bucket algorithm: tokens are added at a constant rate,
+ * and each operation consumes one token. When no tokens are available,
+ * operations must wait until tokens are replenished.
+ */
+/**
+ * Error thrown when rate limit is exceeded with tryConsume()
+ */
+export declare class RateLimitError extends Error {
+    constructor(message: string);
+}
+/**
+ * Token bucket rate limiter for controlling operation frequency
+ *
+ * @example
+ * ```typescript
+ * // Allow 10 messages per second with burst of 20
+ * const limiter = new TokenBucketRateLimiter(10, 20);
+ *
+ * // Non-blocking check
+ * if (limiter.tryConsume()) {
+ *   await sendMessage(msg);
+ * } else {
+ *   console.log('Rate limit exceeded');
+ * }
+ *
+ * // Blocking wait (auto-waits for token)
+ * await limiter.consume();
+ * await sendMessage(msg);
+ * ```
+ */
+export declare class TokenBucketRateLimiter {
+    private readonly tokensPerSecond;
+    private readonly maxBurst;
+    private tokens;
+    private lastRefill;
+    private readonly refillInterval;
+    /**
+     * Creates a new token bucket rate limiter
+     *
+     * @param tokensPerSecond - Rate at which tokens are added (operations per second)
+     * @param maxBurst - Maximum tokens that can accumulate (burst capacity)
+     * @throws {Error} If tokensPerSecond or maxBurst is less than 1
+     *
+     * @example
+     * ```typescript
+     * // 10 ops/sec, burst up to 20
+     * const limiter = new TokenBucketRateLimiter(10, 20);
+     * ```
+     */
+    constructor(tokensPerSecond: number, maxBurst: number);
+    /**
+     * Try to consume one token without blocking
+     *
+     * @returns true if token was consumed, false if no tokens available
+     *
+     * @example
+     * ```typescript
+     * if (limiter.tryConsume()) {
+     *   // Proceed with operation
+     * } else {
+     *   // Rate limited - handle accordingly
+     * }
+     * ```
+     */
+    tryConsume(): boolean;
+    /**
+     * Consume one token, waiting if necessary until a token is available
+     *
+     * @param timeout - Optional max wait time in ms (default: no timeout)
+     * @returns Promise that resolves when token is consumed
+     * @throws {RateLimitError} If timeout is exceeded
+     *
+     * @example
+     * ```typescript
+     * // Wait indefinitely for token
+     * await limiter.consume();
+     *
+     * // Wait max 5 seconds
+     * try {
+     *   await limiter.consume(5000);
+     * } catch (error) {
+     *   console.log('Timeout waiting for rate limit');
+     * }
+     * ```
+     */
+    consume(timeout?: number): Promise<void>;
+    /**
+     * Get the number of tokens currently available
+     * Refills tokens before returning count
+     *
+     * @returns Number of tokens available (may be fractional before consumption)
+     */
+    getAvailableTokens(): number;
+    /**
+     * Get rate limiter configuration
+     *
+     * @returns Configuration object with rate and burst capacity
+     */
+    getConfig(): {
+        tokensPerSecond: number;
+        maxBurst: number;
+    };
+    /**
+     * Reset the rate limiter to full capacity
+     * Useful for testing or manual reset scenarios
+     */
+    reset(): void;
+    /**
+     * Refill tokens based on elapsed time since last refill
+     * Called automatically before token consumption
+     */
+    private refill;
+    /**
+     * Sleep helper for async waiting
+     */
+    private sleep;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/utils/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/utils/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAQ5B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,sBAAsB;IAmB/B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAnB3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAExC;;;;;;;;;;;;OAYG;gBAEgB,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,MAAM;IAcnC;;;;;;;;;;;;;OAaG;IACI,UAAU,IAAI,OAAO;IAW5B;;;;;;;;;;;;;;;;;;;OAmBG;IACU,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCrD;;;;;OAKG;IACI,kBAAkB,IAAI,MAAM;IAKnC;;;;OAIG;IACI,SAAS,IAAI;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAOjE;;;OAGG;IACI,KAAK,IAAI,IAAI;IAKpB;;;OAGG;IACH,OAAO,CAAC,MAAM;IAcd;;OAEG;IACH,OAAO,CAAC,KAAK;CAGd"}