@teneo-protocol/sdk 1.0.0

package/src/utils/event-waiter.test.ts

@@ -0,0 +1,381 @@
+/**
+ * Tests for Event Waiter Utility
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { EventEmitter } from "eventemitter3";
+import { waitForEvent, waitForAnyEvent, waitForAllEvents } from "./event-waiter";
+
+describe("waitForEvent", () => {
+  let emitter: EventEmitter;
+
+  beforeEach(() => {
+    emitter = new EventEmitter();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  describe("basic functionality", () => {
+    it("should resolve when event is emitted", async () => {
+      const eventData = { message: "test data" };
+
+      // Start waiting
+      const promise = waitForEvent(emitter, "test:event", { timeout: 5000 });
+
+      // Emit the event
+      emitter.emit("test:event", eventData);
+
+      // Should resolve with the event data
+      await expect(promise).resolves.toEqual(eventData);
+    });
+
+    it("should resolve with the correct event data type", async () => {
+      interface TestData {
+        id: number;
+        name: string;
+      }
+
+      const eventData: TestData = { id: 123, name: "test" };
+
+      const promise = waitForEvent<TestData>(emitter, "typed:event", {
+        timeout: 5000
+      });
+
+      emitter.emit("typed:event", eventData);
+
+      const result = await promise;
+      expect(result.id).toBe(123);
+      expect(result.name).toBe("test");
+    });
+
+    it("should work with multiple sequential waits", async () => {
+      const promise1 = waitForEvent(emitter, "event1", { timeout: 5000 });
+      emitter.emit("event1", "data1");
+      await expect(promise1).resolves.toBe("data1");
+
+      const promise2 = waitForEvent(emitter, "event2", { timeout: 5000 });
+      emitter.emit("event2", "data2");
+      await expect(promise2).resolves.toBe("data2");
+    });
+  });
+
+  describe("timeout handling", () => {
+    it("should reject after timeout", async () => {
+      const promise = waitForEvent(emitter, "never:happens", { timeout: 1000 });
+
+      // Advance time past timeout
+      vi.advanceTimersByTime(1001);
+
+      await expect(promise).rejects.toThrow(/Timeout waiting for event/);
+    });
+
+    it("should use custom timeout message", async () => {
+      const customMessage = "Custom timeout error";
+      const promise = waitForEvent(emitter, "never:happens", {
+        timeout: 1000,
+        timeoutMessage: customMessage
+      });
+
+      vi.advanceTimersByTime(1001);
+
+      await expect(promise).rejects.toThrow(customMessage);
+    });
+
+    it("should not timeout if event arrives in time", async () => {
+      const promise = waitForEvent(emitter, "quick:event", { timeout: 5000 });
+
+      // Emit before timeout
+      vi.advanceTimersByTime(2000);
+      emitter.emit("quick:event", "success");
+
+      await expect(promise).resolves.toBe("success");
+    });
+  });
+
+  describe("filtering", () => {
+    it("should filter events and wait for matching one", async () => {
+      interface Task {
+        taskId: string;
+        result: string;
+      }
+
+      const promise = waitForEvent<Task>(emitter, "task:response", {
+        timeout: 5000,
+        filter: (data) => data.taskId === "task-123"
+      });
+
+      // Emit non-matching events
+      emitter.emit("task:response", { taskId: "task-999", result: "wrong" });
+      emitter.emit("task:response", { taskId: "task-888", result: "wrong" });
+
+      // Emit matching event
+      emitter.emit("task:response", { taskId: "task-123", result: "correct" });
+
+      const result = await promise;
+      expect(result.taskId).toBe("task-123");
+      expect(result.result).toBe("correct");
+    });
+
+    it("should timeout if no matching event arrives", async () => {
+      const promise = waitForEvent(emitter, "filtered:event", {
+        timeout: 1000,
+        filter: (data: any) => data.id === 999
+      });
+
+      // Emit non-matching events
+      emitter.emit("filtered:event", { id: 1 });
+      emitter.emit("filtered:event", { id: 2 });
+      emitter.emit("filtered:event", { id: 3 });
+
+      // Advance past timeout
+      vi.advanceTimersByTime(1001);
+
+      await expect(promise).rejects.toThrow(/Timeout/);
+    });
+
+    it("should handle complex filter logic", async () => {
+      interface Response {
+        requestId: string;
+        status: number;
+        data?: any;
+      }
+
+      const promise = waitForEvent<Response>(emitter, "response", {
+        timeout: 5000,
+        filter: (r) => r.requestId === "req-123" && r.status === 200 && r.data !== undefined
+      });
+
+      // Non-matching: wrong requestId
+      emitter.emit("response", { requestId: "req-999", status: 200, data: "test" });
+
+      // Non-matching: wrong status
+      emitter.emit("response", { requestId: "req-123", status: 404, data: "test" });
+
+      // Non-matching: no data
+      emitter.emit("response", { requestId: "req-123", status: 200 });
+
+      // Matching
+      emitter.emit("response", { requestId: "req-123", status: 200, data: "success" });
+
+      await expect(promise).resolves.toMatchObject({
+        requestId: "req-123",
+        status: 200,
+        data: "success"
+      });
+    });
+  });
+
+  describe("cleanup", () => {
+    it("should remove event listener after success", async () => {
+      const promise = waitForEvent(emitter, "cleanup:test", { timeout: 5000 });
+
+      // Check listener count before
+      expect(emitter.listenerCount("cleanup:test")).toBe(1);
+
+      // Emit event
+      emitter.emit("cleanup:test", "data");
+      await promise;
+
+      // Check listener count after
+      expect(emitter.listenerCount("cleanup:test")).toBe(0);
+    });
+
+    it("should remove event listener after timeout", async () => {
+      const promise = waitForEvent(emitter, "cleanup:timeout", { timeout: 1000 });
+
+      // Check listener count before
+      expect(emitter.listenerCount("cleanup:timeout")).toBe(1);
+
+      // Timeout
+      vi.advanceTimersByTime(1001);
+
+      await promise.catch(() => {}); // Ignore rejection
+
+      // Check listener count after
+      expect(emitter.listenerCount("cleanup:timeout")).toBe(0);
+    });
+
+    it("should clear timeout after success", async () => {
+      const clearTimeoutSpy = vi.spyOn(global, "clearTimeout");
+
+      const promise = waitForEvent(emitter, "timeout:clear", { timeout: 5000 });
+
+      emitter.emit("timeout:clear", "data");
+      await promise;
+
+      // clearTimeout should have been called
+      expect(clearTimeoutSpy).toHaveBeenCalled();
+    });
+
+    it("should not leak listeners with filter", async () => {
+      const promise = waitForEvent(emitter, "filter:cleanup", {
+        timeout: 5000,
+        filter: (data: any) => data.id === 5
+      });
+
+      // Emit multiple non-matching events
+      emitter.emit("filter:cleanup", { id: 1 });
+      emitter.emit("filter:cleanup", { id: 2 });
+      emitter.emit("filter:cleanup", { id: 3 });
+
+      // Check listener is still there
+      expect(emitter.listenerCount("filter:cleanup")).toBe(1);
+
+      // Emit matching event
+      emitter.emit("filter:cleanup", { id: 5 });
+      await promise;
+
+      // Listener should be removed
+      expect(emitter.listenerCount("filter:cleanup")).toBe(0);
+    });
+
+    it("should handle multiple concurrent waits and cleanup correctly", async () => {
+      const promise1 = waitForEvent(emitter, "concurrent", {
+        timeout: 5000,
+        filter: (data: any) => data.id === 1
+      });
+
+      const promise2 = waitForEvent(emitter, "concurrent", {
+        timeout: 5000,
+        filter: (data: any) => data.id === 2
+      });
+
+      // Should have 2 listeners
+      expect(emitter.listenerCount("concurrent")).toBe(2);
+
+      // Resolve first
+      emitter.emit("concurrent", { id: 1 });
+      await promise1;
+
+      // Should have 1 listener left
+      expect(emitter.listenerCount("concurrent")).toBe(1);
+
+      // Resolve second
+      emitter.emit("concurrent", { id: 2 });
+      await promise2;
+
+      // Should have 0 listeners
+      expect(emitter.listenerCount("concurrent")).toBe(0);
+    });
+  });
+});
+
+describe("waitForAnyEvent", () => {
+  let emitter: EventEmitter;
+
+  beforeEach(() => {
+    emitter = new EventEmitter();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  it("should resolve with first event that fires", async () => {
+    const promise = waitForAnyEvent([
+      { emitter, eventName: "event1", options: { timeout: 5000 } },
+      { emitter, eventName: "event2", options: { timeout: 5000 } },
+      { emitter, eventName: "event3", options: { timeout: 5000 } }
+    ]);
+
+    // Emit second event first
+    emitter.emit("event2", "second");
+
+    await expect(promise).resolves.toBe("second");
+  });
+
+  it("should reject if all events timeout", async () => {
+    const promise = waitForAnyEvent([
+      { emitter, eventName: "never1", options: { timeout: 1000 } },
+      { emitter, eventName: "never2", options: { timeout: 1000 } }
+    ]);
+
+    vi.advanceTimersByTime(1001);
+
+    await expect(promise).rejects.toThrow();
+  });
+
+  it("should work with different emitters", async () => {
+    const emitter1 = new EventEmitter();
+    const emitter2 = new EventEmitter();
+
+    const promise = waitForAnyEvent([
+      { emitter: emitter1, eventName: "event", options: { timeout: 5000 } },
+      { emitter: emitter2, eventName: "event", options: { timeout: 5000 } }
+    ]);
+
+    emitter2.emit("event", "from emitter2");
+
+    await expect(promise).resolves.toBe("from emitter2");
+  });
+});
+
+describe("waitForAllEvents", () => {
+  let emitter: EventEmitter;
+
+  beforeEach(() => {
+    emitter = new EventEmitter();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  it("should resolve when all events fire", async () => {
+    const promise = waitForAllEvents([
+      { emitter, eventName: "event1", options: { timeout: 5000 } },
+      { emitter, eventName: "event2", options: { timeout: 5000 } },
+      { emitter, eventName: "event3", options: { timeout: 5000 } }
+    ]);
+
+    // Emit all events
+    emitter.emit("event1", "first");
+    emitter.emit("event2", "second");
+    emitter.emit("event3", "third");
+
+    const results = await promise;
+    expect(results).toEqual(["first", "second", "third"]);
+  });
+
+  it("should reject if any event times out", async () => {
+    const promise = waitForAllEvents([
+      { emitter, eventName: "event1", options: { timeout: 5000 } },
+      { emitter, eventName: "never", options: { timeout: 1000 } }
+    ]);
+
+    emitter.emit("event1", "data");
+    vi.advanceTimersByTime(1001);
+
+    await expect(promise).rejects.toThrow();
+  });
+
+  it("should work with filters on all events", async () => {
+    const promise = waitForAllEvents([
+      {
+        emitter,
+        eventName: "data",
+        options: { timeout: 5000, filter: (d: any) => d.id === 1 }
+      },
+      {
+        emitter,
+        eventName: "data",
+        options: { timeout: 5000, filter: (d: any) => d.id === 2 }
+      }
+    ]);
+
+    // Emit in reverse order
+    emitter.emit("data", { id: 2, value: "second" });
+    emitter.emit("data", { id: 1, value: "first" });
+
+    const results = await promise;
+    expect(results).toEqual([{ id: 1, value: "first" }, { id: 2, value: "second" }]);
+  });
+});

package/src/utils/event-waiter.ts

@@ -0,0 +1,172 @@
+/**
+ * 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 async function waitForEvent<T = any>(
+  emitter: EventEmitter,
+  eventName: string,
+  options: WaitForEventOptions<T>
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    let timeoutHandle: NodeJS.Timeout | undefined;
+    let eventHandler: ((data: T) => void) | undefined;
+    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: T) => {
+      // 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 } }
+ * ]);
+ * ```
+ */
+export async function waitForAnyEvent<T = any>(
+  waiters: Array<{
+    emitter: EventEmitter;
+    eventName: string;
+    options: WaitForEventOptions<T>;
+  }>
+): Promise<T> {
+  return Promise.race(
+    waiters.map(({ emitter, eventName, options }) =>
+      waitForEvent<T>(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 } }
+ * ]);
+ * ```
+ */
+export async function waitForAllEvents<T = any>(
+  waiters: Array<{
+    emitter: EventEmitter;
+    eventName: string;
+    options: WaitForEventOptions<T>;
+  }>
+): Promise<T[]> {
+  return Promise.all(
+    waiters.map(({ emitter, eventName, options }) =>
+      waitForEvent<T>(emitter, eventName, options)
+    )
+  );
+}

package/src/utils/index.ts

@@ -0,0 +1,74 @@
+/**
+ * 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";

package/src/utils/logger.ts

@@ -0,0 +1,87 @@
+/**
+ * Logger utility for Teneo Protocol SDK
+ * Provides pino-based logging with structured output and optional pretty printing
+ */
+
+import pino from "pino";
+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 function createPinoLogger(level: LogLevel, name?: string): Logger {
+  // Map 'silent' to pino's 'silent' level
+  const pinoLevel = level === "silent" ? "silent" : level;
+
+  // Create pino logger with optional pretty printing for development
+  const pinoLogger = pino({
+    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: string, data?: any) => {
+      if (data !== undefined) {
+        pinoLogger.debug(data, message);
+      } else {
+        pinoLogger.debug(message);
+      }
+    },
+    info: (message: string, data?: any) => {
+      if (data !== undefined) {
+        pinoLogger.info(data, message);
+      } else {
+        pinoLogger.info(message);
+      }
+    },
+    warn: (message: string, data?: any) => {
+      if (data !== undefined) {
+        pinoLogger.warn(data, message);
+      } else {
+        pinoLogger.warn(message);
+      }
+    },
+    error: (message: string, data?: any) => {
+      if (data !== undefined) {
+        pinoLogger.error(data, message);
+      } else {
+        pinoLogger.error(message);
+      }
+    }
+  };
+}