@teneo-protocol/sdk 1.0.0

package/dist/utils/circuit-breaker.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * Circuit Breaker Pattern Implementation
+ * Provides fault tolerance by preventing cascading failures
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Failure threshold exceeded, requests fail fast
+ * - HALF_OPEN: Testing if service recovered, limited requests allowed
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreaker = exports.CircuitBreakerError = void 0;
+/**
+ * Error thrown when circuit is open
+ */
+class CircuitBreakerError extends Error {
+    constructor(message, state) {
+        super(message);
+        this.state = state;
+        this.name = "CircuitBreakerError";
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, CircuitBreakerError);
+        }
+    }
+}
+exports.CircuitBreakerError = CircuitBreakerError;
+/**
+ * Circuit breaker for fault tolerance
+ * Prevents cascading failures by failing fast when errors are detected
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 5,
+ *   timeout: 60000
+ * });
+ *
+ * try {
+ *   await breaker.execute(async () => {
+ *     return await fetch('https://api.example.com/data');
+ *   });
+ * } catch (error) {
+ *   if (error instanceof CircuitBreakerError) {
+ *     console.log('Circuit is open, failing fast');
+ *   }
+ * }
+ * ```
+ */
+class CircuitBreaker {
+    /**
+     * Creates a new circuit breaker
+     *
+     * @param options - Configuration options
+     * @throws {Error} If thresholds are less than 1
+     *
+     * @example
+     * ```typescript
+     * const breaker = new CircuitBreaker({
+     *   failureThreshold: 5,  // Open after 5 failures
+     *   successThreshold: 2,  // Close after 2 successes
+     *   timeout: 60000,       // Wait 60s before trying again
+     *   windowSize: 60000     // Track failures in 60s window
+     * });
+     * ```
+     */
+    constructor(options = {}) {
+        this.state = "CLOSED";
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.failures = []; // Timestamps of failures
+        this.failureThreshold = options.failureThreshold ?? 5;
+        this.successThreshold = options.successThreshold ?? 2;
+        this.timeout = options.timeout ?? 60000;
+        this.windowSize = options.windowSize ?? 60000;
+        if (this.failureThreshold < 1) {
+            throw new Error("CircuitBreaker failureThreshold must be at least 1");
+        }
+        if (this.successThreshold < 1) {
+            throw new Error("CircuitBreaker successThreshold must be at least 1");
+        }
+    }
+    /**
+     * Execute an operation through the circuit breaker
+     *
+     * @template T - Return type of the operation
+     * @param operation - Async operation to execute
+     * @returns Promise resolving to operation result
+     * @throws {CircuitBreakerError} If circuit is open
+     * @throws Operation error if operation fails
+     *
+     * @example
+     * ```typescript
+     * const result = await breaker.execute(async () => {
+     *   const response = await fetch(url);
+     *   return await response.json();
+     * });
+     * ```
+     */
+    async execute(operation) {
+        // Check if we should try to close the circuit
+        this.tryTransitionToHalfOpen();
+        // If circuit is open, fail fast
+        if (this.state === "OPEN") {
+            throw new CircuitBreakerError("Circuit breaker is OPEN", this.state);
+        }
+        try {
+            const result = await operation();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure();
+            throw error;
+        }
+    }
+    /**
+     * Get current circuit breaker state and metrics
+     *
+     * @returns State object with status and counters
+     */
+    getState() {
+        return {
+            state: this.state,
+            failureCount: this.failureCount,
+            successCount: this.successCount,
+            lastFailureTime: this.lastFailureTime,
+            nextAttemptTime: this.nextAttemptTime
+        };
+    }
+    /**
+     * Get circuit breaker configuration
+     */
+    getConfig() {
+        return {
+            failureThreshold: this.failureThreshold,
+            successThreshold: this.successThreshold,
+            timeout: this.timeout,
+            windowSize: this.windowSize
+        };
+    }
+    /**
+     * Manually reset the circuit breaker to CLOSED state
+     * Useful for recovery scenarios or testing
+     */
+    reset() {
+        this.state = "CLOSED";
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.lastFailureTime = undefined;
+        this.nextAttemptTime = undefined;
+        this.failures.length = 0;
+    }
+    /**
+     * Try to transition from OPEN to HALF_OPEN if timeout has passed
+     */
+    tryTransitionToHalfOpen() {
+        if (this.state === "OPEN" && this.nextAttemptTime) {
+            if (Date.now() >= this.nextAttemptTime) {
+                this.state = "HALF_OPEN";
+                this.successCount = 0;
+            }
+        }
+    }
+    /**
+     * Handle successful operation
+     */
+    onSuccess() {
+        if (this.state === "HALF_OPEN") {
+            this.successCount++;
+            if (this.successCount >= this.successThreshold) {
+                // Close the circuit - service has recovered
+                this.state = "CLOSED";
+                this.failureCount = 0;
+                this.successCount = 0;
+                this.failures.length = 0;
+                this.lastFailureTime = undefined;
+                this.nextAttemptTime = undefined;
+            }
+        }
+        else if (this.state === "CLOSED") {
+            // Reset failure count on success in CLOSED state
+            this.failureCount = Math.max(0, this.failureCount - 1);
+        }
+    }
+    /**
+     * Handle failed operation
+     */
+    onFailure() {
+        const now = Date.now();
+        this.lastFailureTime = now;
+        if (this.state === "HALF_OPEN") {
+            // Failed while testing - reopen circuit
+            this.state = "OPEN";
+            this.nextAttemptTime = now + this.timeout;
+            this.successCount = 0;
+            return;
+        }
+        // Track failure with timestamp
+        this.failures.push(now);
+        // Remove failures outside the window
+        const windowStart = now - this.windowSize;
+        while (this.failures.length > 0 && this.failures[0] < windowStart) {
+            this.failures.shift();
+        }
+        // Count failures in current window
+        this.failureCount = this.failures.length;
+        // Open circuit if threshold exceeded
+        if (this.failureCount >= this.failureThreshold) {
+            this.state = "OPEN";
+            this.nextAttemptTime = now + this.timeout;
+        }
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/utils/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../../src/utils/circuit-breaker.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAqBH;;GAEG;AACH,MAAa,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAe,EAAkB,KAAmB;QAC9D,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,UAAK,GAAL,KAAK,CAAc;QAE9D,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAElC,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;CACF;AATD,kDASC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAa,cAAc;IAazB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,UAAiC,EAAE;QA5BvC,UAAK,GAAiB,QAAQ,CAAC;QAC/B,iBAAY,GAAG,CAAC,CAAC;QACjB,iBAAY,GAAG,CAAC,CAAC;QAGR,aAAQ,GAAa,EAAE,CAAC,CAAC,yBAAyB;QAwBjE,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,CAAC,CAAC;QACtD,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,CAAC,CAAC;QACtD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,KAAK,CAAC;QACxC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,KAAK,CAAC;QAE9C,IAAI,IAAI,CAAC,gBAAgB,GAAG,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;QACD,IAAI,IAAI,CAAC,gBAAgB,GAAG,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACI,KAAK,CAAC,OAAO,CAAI,SAA2B;QACjD,8CAA8C;QAC9C,IAAI,CAAC,uBAAuB,EAAE,CAAC;QAE/B,gCAAgC;QAChC,IAAI,IAAI,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAC1B,MAAM,IAAI,mBAAmB,CAAC,yBAAyB,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACvE,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,SAAS,EAAE,CAAC;YACjB,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,SAAS,EAAE,CAAC;YACjB,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;OAIG;IACI,QAAQ;QAOb,OAAO;YACL,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,eAAe,EAAE,IAAI,CAAC,eAAe;SACtC,CAAC;IACJ,CAAC;IAED;;OAEG;IACI,SAAS;QAMd,OAAO;YACL,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,IAAI,CAAC,UAAU;SAC5B,CAAC;IACJ,CAAC;IAED;;;OAGG;IACI,KAAK;QACV,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;QACtB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,eAAe,GAAG,SAAS,CAAC;QACjC,IAAI,CAAC,eAAe,GAAG,SAAS,CAAC;QACjC,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED;;OAEG;IACK,uBAAuB;QAC7B,IAAI,IAAI,CAAC,KAAK,KAAK,MAAM,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YAClD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;gBACvC,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC;gBACzB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACK,SAAS;QACf,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAC/B,IAAI,CAAC,YAAY,EAAE,CAAC;YACpB,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;gBAC/C,4CAA4C;gBAC5C,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;gBACtB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;gBACtB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;gBACtB,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;gBACzB,IAAI,CAAC,eAAe,GAAG,SAAS,CAAC;gBACjC,IAAI,CAAC,eAAe,GAAG,SAAS,CAAC;YACnC,CAAC;QACH,CAAC;aAAM,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACnC,iDAAiD;YACjD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;IAED;;OAEG;IACK,SAAS;QACf,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,CAAC,eAAe,GAAG,GAAG,CAAC;QAE3B,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAC/B,wCAAwC;YACxC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;YACpB,IAAI,CAAC,eAAe,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC;YAC1C,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;YACtB,OAAO;QACT,CAAC;QAED,+BAA+B;QAC/B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAExB,qCAAqC;QACrC,MAAM,WAAW,GAAG,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC;QAC1C,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAE,GAAG,WAAW,EAAE,CAAC;YACnE,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC;QAED,mCAAmC;QACnC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QAEzC,qCAAqC;QACrC,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC/C,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;YACpB,IAAI,CAAC,eAAe,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5C,CAAC;IACH,CAAC;CACF;AApMD,wCAoMC"}

package/dist/utils/deduplication-cache.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Deduplication Cache with TTL
+ * Prevents duplicate processing of messages/events
+ *
+ * Uses time-to-live (TTL) for automatic cleanup of old entries
+ * without requiring external cleanup timers.
+ */
+/**
+ * TTL-based cache for detecting duplicates
+ * Automatically expires entries after configured TTL
+ *
+ * @example
+ * ```typescript
+ * const cache = new DeduplicationCache(60000); // 60 second TTL
+ *
+ * // Check and add in one operation
+ * if (!cache.has('message-123')) {
+ *   cache.add('message-123');
+ *   // Process message
+ * } else {
+ *   // Duplicate - skip processing
+ * }
+ * ```
+ */
+export declare class DeduplicationCache {
+    private readonly ttl;
+    private readonly maxSize;
+    private cache;
+    /**
+     * Creates a new deduplication cache
+     *
+     * @param ttl - Time-to-live in milliseconds (default: 300000 / 5 minutes)
+     * @param maxSize - Maximum cache size before cleanup (default: 10000)
+     * @throws {Error} If TTL is less than 1000ms or maxSize is less than 1
+     *
+     * @example
+     * ```typescript
+     * // 5 minute TTL, max 10k entries
+     * const cache = new DeduplicationCache(300000, 10000);
+     * ```
+     */
+    constructor(ttl?: number, maxSize?: number);
+    /**
+     * Check if a key exists and hasn't expired
+     *
+     * @param key - Key to check
+     * @returns true if key exists and is not expired, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (cache.has('message-id')) {
+     *   console.log('Duplicate message detected');
+     * }
+     * ```
+     */
+    has(key: string): boolean;
+    /**
+     * Add a key to the cache with current timestamp
+     *
+     * @param key - Key to add
+     * @returns true if added, false if already exists
+     *
+     * @example
+     * ```typescript
+     * if (cache.add('message-id')) {
+     *   // Process message
+     * } else {
+     *   // Already processed
+     * }
+     * ```
+     */
+    add(key: string): boolean;
+    /**
+     * Remove a specific key from the cache
+     *
+     * @param key - Key to remove
+     * @returns true if key was removed, false if didn't exist
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Get current cache size
+     *
+     * @returns Number of entries in cache
+     */
+    size(): number;
+    /**
+     * Get cache configuration
+     */
+    getConfig(): {
+        ttl: number;
+        maxSize: number;
+    };
+    /**
+     * Clean up expired entries if cache is getting large
+     * Called automatically by has() and add()
+     */
+    private cleanupIfNeeded;
+    /**
+     * Force cleanup of all expired entries
+     * Usually not needed as cleanup is automatic
+     *
+     * @returns Number of entries removed
+     */
+    cleanup(): number;
+}
+//# sourceMappingURL=deduplication-cache.d.ts.map

package/dist/utils/deduplication-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deduplication-cache.d.ts","sourceRoot":"","sources":["../../src/utils/deduplication-cache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,kBAAkB;IAiB3B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAjB1B,OAAO,CAAC,KAAK,CAAiC;IAE9C;;;;;;;;;;;;OAYG;gBAEgB,GAAG,GAAE,MAAe,EACpB,OAAO,GAAE,MAAc;IAU1C;;;;;;;;;;;;OAYG;IACI,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAiBhC;;;;;;;;;;;;;;OAcG;IACI,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAahC;;;;;OAKG;IACI,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAInC;;OAEG;IACI,KAAK,IAAI,IAAI;IAIpB;;;;OAIG;IACI,IAAI,IAAI,MAAM;IAIrB;;OAEG;IACI,SAAS,IAAI;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAOpD;;;OAGG;IACH,OAAO,CAAC,eAAe;IAoBvB;;;;;OAKG;IACI,OAAO,IAAI,MAAM;CAgBzB"}

package/dist/utils/deduplication-cache.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * Deduplication Cache with TTL
+ * Prevents duplicate processing of messages/events
+ *
+ * Uses time-to-live (TTL) for automatic cleanup of old entries
+ * without requiring external cleanup timers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeduplicationCache = void 0;
+/**
+ * TTL-based cache for detecting duplicates
+ * Automatically expires entries after configured TTL
+ *
+ * @example
+ * ```typescript
+ * const cache = new DeduplicationCache(60000); // 60 second TTL
+ *
+ * // Check and add in one operation
+ * if (!cache.has('message-123')) {
+ *   cache.add('message-123');
+ *   // Process message
+ * } else {
+ *   // Duplicate - skip processing
+ * }
+ * ```
+ */
+class DeduplicationCache {
+    /**
+     * Creates a new deduplication cache
+     *
+     * @param ttl - Time-to-live in milliseconds (default: 300000 / 5 minutes)
+     * @param maxSize - Maximum cache size before cleanup (default: 10000)
+     * @throws {Error} If TTL is less than 1000ms or maxSize is less than 1
+     *
+     * @example
+     * ```typescript
+     * // 5 minute TTL, max 10k entries
+     * const cache = new DeduplicationCache(300000, 10000);
+     * ```
+     */
+    constructor(ttl = 300000, maxSize = 10000) {
+        this.ttl = ttl;
+        this.maxSize = maxSize;
+        this.cache = new Map();
+        if (ttl < 1000) {
+            throw new Error("DeduplicationCache TTL must be at least 1000ms");
+        }
+        if (maxSize < 1) {
+            throw new Error("DeduplicationCache maxSize must be at least 1");
+        }
+    }
+    /**
+     * Check if a key exists and hasn't expired
+     *
+     * @param key - Key to check
+     * @returns true if key exists and is not expired, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (cache.has('message-id')) {
+     *   console.log('Duplicate message detected');
+     * }
+     * ```
+     */
+    has(key) {
+        this.cleanupIfNeeded();
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        // Check if expired
+        if (Date.now() - entry.timestamp > this.ttl) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Add a key to the cache with current timestamp
+     *
+     * @param key - Key to add
+     * @returns true if added, false if already exists
+     *
+     * @example
+     * ```typescript
+     * if (cache.add('message-id')) {
+     *   // Process message
+     * } else {
+     *   // Already processed
+     * }
+     * ```
+     */
+    add(key) {
+        if (this.has(key)) {
+            return false;
+        }
+        this.cache.set(key, {
+            timestamp: Date.now()
+        });
+        this.cleanupIfNeeded();
+        return true;
+    }
+    /**
+     * Remove a specific key from the cache
+     *
+     * @param key - Key to remove
+     * @returns true if key was removed, false if didn't exist
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Clear all entries from the cache
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get current cache size
+     *
+     * @returns Number of entries in cache
+     */
+    size() {
+        return this.cache.size;
+    }
+    /**
+     * Get cache configuration
+     */
+    getConfig() {
+        return {
+            ttl: this.ttl,
+            maxSize: this.maxSize
+        };
+    }
+    /**
+     * Clean up expired entries if cache is getting large
+     * Called automatically by has() and add()
+     */
+    cleanupIfNeeded() {
+        // Only cleanup if approaching max size
+        if (this.cache.size < this.maxSize * 0.9) {
+            return;
+        }
+        const now = Date.now();
+        const keysToDelete = [];
+        for (const [key, entry] of this.cache.entries()) {
+            if (now - entry.timestamp > this.ttl) {
+                keysToDelete.push(key);
+            }
+        }
+        for (const key of keysToDelete) {
+            this.cache.delete(key);
+        }
+    }
+    /**
+     * Force cleanup of all expired entries
+     * Usually not needed as cleanup is automatic
+     *
+     * @returns Number of entries removed
+     */
+    cleanup() {
+        const now = Date.now();
+        const keysToDelete = [];
+        for (const [key, entry] of this.cache.entries()) {
+            if (now - entry.timestamp > this.ttl) {
+                keysToDelete.push(key);
+            }
+        }
+        for (const key of keysToDelete) {
+            this.cache.delete(key);
+        }
+        return keysToDelete.length;
+    }
+}
+exports.DeduplicationCache = DeduplicationCache;
+//# sourceMappingURL=deduplication-cache.js.map

package/dist/utils/deduplication-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deduplication-cache.js","sourceRoot":"","sources":["../../src/utils/deduplication-cache.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAMH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,kBAAkB;IAG7B;;;;;;;;;;;;OAYG;IACH,YACmB,MAAc,MAAM,EACpB,UAAkB,KAAK;QADvB,QAAG,GAAH,GAAG,CAAiB;QACpB,YAAO,GAAP,OAAO,CAAgB;QAjBlC,UAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;QAmB5C,IAAI,GAAG,GAAG,IAAI,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QACD,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;OAYG;IACI,GAAG,CAAC,GAAW;QACpB,IAAI,CAAC,eAAe,EAAE,CAAC;QAEvB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,KAAK,CAAC;QACf,CAAC;QAED,mBAAmB;QACnB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC5C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACI,GAAG,CAAC,GAAW;QACpB,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAClB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC,CAAC;QAEH,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,GAAW;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED;;OAEG;IACI,KAAK;QACV,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACI,IAAI;QACT,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED;;OAEG;IACI,SAAS;QACd,OAAO;YACL,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC;IACJ,CAAC;IAED;;;OAGG;IACK,eAAe;QACrB,uCAAuC;QACvC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC;YACzC,OAAO;QACT,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,YAAY,GAAa,EAAE,CAAC;QAElC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;YAChD,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBACrC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAED,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAC/B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACI,OAAO;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,YAAY,GAAa,EAAE,CAAC;QAElC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;YAChD,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBACrC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAED,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAC/B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC;QAED,OAAO,YAAY,CAAC,MAAM,CAAC;IAC7B,CAAC;CACF;AAxKD,gDAwKC"}

package/dist/utils/event-waiter.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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
+ */
+import { EventEmitter } from "eventemitter3";
+/**
+ * Options for waiting for an event
+ */
+export interface WaitForEventOptions<T> {
+    /**
+     * Timeout in milliseconds
+     */
+    timeout: number;
+    /**
+     * Optional filter function to match specific events
+     * If provided, only events that pass the filter will resolve the promise
+     *
+     * @param data - The event data
+     * @returns true if this is the event we're waiting for, false to keep waiting
+     */
+    filter?: (data: T) => boolean;
+    /**
+     * Optional custom timeout error message
+     * If not provided, a default message will be used
+     */
+    timeoutMessage?: string;
+}
+/**
+ * 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'
+ * });
+ * ```
+ */
+export declare function waitForEvent<T = any>(emitter: EventEmitter, eventName: string, options: WaitForEventOptions<T>): Promise<T>;
+/**
+ * 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 } }
+ * ]);
+ * ```
+ */
+export declare function waitForAnyEvent<T = any>(waiters: Array<{
+    emitter: EventEmitter;
+    eventName: string;
+    options: WaitForEventOptions<T>;
+}>): Promise<T>;
+/**
+ * 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 } }
+ * ]);
+ * ```
+ */
+export declare function waitForAllEvents<T = any>(waiters: Array<{
+    emitter: EventEmitter;
+    eventName: string;
+    options: WaitForEventOptions<T>;
+}>): Promise<T[]>;
+//# sourceMappingURL=event-waiter.d.ts.map

package/dist/utils/event-waiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-waiter.d.ts","sourceRoot":"","sources":["../../src/utils/event-waiter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;IAE9B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,GAAG,EACxC,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,CAAC,CAAC,CA6CZ;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,CAAC,GAAG,GAAG,EAC3C,OAAO,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;CACjC,CAAC,GACD,OAAO,CAAC,CAAC,CAAC,CAMZ;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,GAAG,GAAG,EAC5C,OAAO,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;CACjC,CAAC,GACD,OAAO,CAAC,CAAC,EAAE,CAAC,CAMd"}