@teneo-protocol/sdk 1.0.0 → 1.0.1

package/src/managers/room-manager.ts

@@ -5,7 +5,14 @@
 
 import { EventEmitter } from "eventemitter3";
 import { WebSocketClient } from "../core/websocket-client";
-import { Room, createSubscribe, createUnsubscribe, createListRooms, Logger, RoomInfo } from "../types";
+import {
+  Room,
+  createSubscribe,
+  createUnsubscribe,
+  createListRooms,
+  Logger,
+  RoomInfo
+} from "../types";
 import { SDKEvents, SDKError } from "../types/events";
 import { ErrorCode } from "../types/error-codes";
 import { RoomIdSchema } from "../types/validation";
@@ -98,7 +105,7 @@ export class RoomManager extends EventEmitter<SDKEvents> {
    */
   public updateSubscriptions(subscriptions: string[]): void {
     this.subscribedRooms.clear();
-    subscriptions.forEach(roomId => this.subscribedRooms.add(roomId));
+    subscriptions.forEach((roomId) => this.subscribedRooms.add(roomId));
     this.logger.debug("RoomManager: Subscriptions updated", {
       count: subscriptions.length,
       rooms: subscriptions

package/src/teneo-sdk.ts

@@ -290,8 +290,11 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
    * });
    * ```
    */
-  public async sendDirectCommand(command: AgentCommand): Promise<FormattedResponse | void> {
-    return this.messages.sendDirectCommand(command);
+  public async sendDirectCommand(
+    command: AgentCommand,
+    waitForResponse: boolean = false
+  ): Promise<FormattedResponse | void> {
+    return this.messages.sendDirectCommand(command, waitForResponse);
   }
 
   /**
@@ -719,6 +722,39 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
     };
   }
 
+  /**
+   * Gets the current message deduplication cache status (CB-4).
+   * Returns statistics about the deduplication cache including size, TTL, and capacity.
+   * Useful for monitoring deduplication behavior and cache health.
+   * Returns undefined if deduplication is not configured or disabled.
+   *
+   * @returns Deduplication cache status object, or undefined if not configured
+   * @returns {number} returns.cacheSize - Number of message IDs currently cached
+   * @returns {number} returns.ttl - Time-to-live for cache entries in milliseconds
+   * @returns {number} returns.maxSize - Maximum cache size capacity
+   *
+   * @example
+   * ```typescript
+   * const status = sdk.getDeduplicationStatus();
+   * if (status) {
+   *   console.log(`Cache: ${status.cacheSize}/${status.maxSize}`);
+   *   console.log(`Utilization: ${(status.cacheSize / status.maxSize * 100).toFixed(1)}%`);
+   *   console.log(`TTL: ${status.ttl}ms`);
+   * } else {
+   *   console.log('Deduplication not enabled');
+   * }
+   * ```
+   */
+  public getDeduplicationStatus():
+    | {
+        cacheSize: number;
+        ttl: number;
+        maxSize: number;
+      }
+    | undefined {
+    return this.wsClient.getDeduplicationStatus();
+  }
+
   /**
    * Retries all failed webhook deliveries in the queue.
    * Resets attempt counters and immediately attempts to deliver all failed webhooks.
@@ -953,14 +989,10 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
       this.agents.updateAgents(agents);
     });
 
-    // Forward room events from WebSocketClient (emitted by handlers)
+    // Forward room events from WebSocketClient (emitted by room subscription handlers)
     this.wsClient.on("room:subscribed", (data) => this.emit("room:subscribed", data));
     this.wsClient.on("room:unsubscribed", (data) => this.emit("room:unsubscribed", data));
 
-    // Forward room events from RoomManager (if any direct emissions are added later)
-    this.rooms.on("room:subscribed", (data) => this.emit("room:subscribed", data));
-    this.rooms.on("room:unsubscribed", (data) => this.emit("room:unsubscribed", data));
-
     // Forward webhook events from WebhookHandler
     this.webhookHandler.on("webhook:sent", (payload, url) =>
       this.emit("webhook:sent", payload, url)

package/src/types/config.ts

@@ -47,7 +47,9 @@ const PrivateKeySchema = z.union([
   z.custom<SecurePrivateKey>(
     (val) => {
       // Check if it's a SecurePrivateKey instance
-      return val && typeof val === 'object' && 'use' in val && 'destroy' in val && 'isDestroyed' in val;
+      return (
+        val && typeof val === "object" && "use" in val && "destroy" in val && "isDestroyed" in val
+      );
     },
     { message: "Must be a string or SecurePrivateKey instance" }
   )

package/src/types/validation.ts

@@ -24,7 +24,10 @@ export const RoomIdSchema = z
   .string()
   .min(1, "Room ID cannot be empty")
   .max(100, "Room ID must be 100 characters or less")
-  .regex(/^[a-zA-Z0-9_\- ]+$/, "Room ID can only contain letters, numbers, spaces, dashes, and underscores")
+  .regex(
+    /^[a-zA-Z0-9_ -]+$/,
+    "Room ID can only contain letters, numbers, spaces, dashes, and underscores"
+  )
   .trim();
 
 /**

package/src/utils/bounded-queue.ts

@@ -11,9 +11,9 @@
  * Strategy for handling queue overflow when at max capacity
  */
 export type OverflowStrategy =
-  | 'drop-oldest'  // Remove oldest item to make room (FIFO eviction)
-  | 'drop-newest'  // Reject new item, keep existing (preserve old data)
-  | 'reject';      // Throw error, let caller handle (fail-fast)
+  | "drop-oldest" // Remove oldest item to make room (FIFO eviction)
+  | "drop-newest" // Reject new item, keep existing (preserve old data)
+  | "reject"; // Throw error, let caller handle (fail-fast)
 
 /**
  * A queue with a maximum size limit and configurable overflow behavior
@@ -48,10 +48,10 @@ export class BoundedQueue<T> {
    */
   constructor(
     private readonly maxSize: number,
-    private readonly strategy: OverflowStrategy = 'drop-oldest'
+    private readonly strategy: OverflowStrategy = "drop-oldest"
   ) {
     if (maxSize < 1) {
-      throw new Error('BoundedQueue maxSize must be at least 1');
+      throw new Error("BoundedQueue maxSize must be at least 1");
     }
   }
 
@@ -165,17 +165,17 @@ export class BoundedQueue<T> {
    */
   private handleOverflow(item: T): boolean {
     switch (this.strategy) {
-      case 'drop-oldest':
+      case "drop-oldest":
         // Remove oldest item and add new one
         this.queue.shift();
         this.queue.push(item);
         return true;
 
-      case 'drop-newest':
+      case "drop-newest":
         // Reject the new item
         return false;
 
-      case 'reject':
+      case "reject":
         // Throw error - let caller handle
         throw new QueueOverflowError(
           `Queue is full (max size: ${this.maxSize}). Cannot add more items.`
@@ -195,7 +195,7 @@ export class BoundedQueue<T> {
 export class QueueOverflowError extends Error {
   constructor(message: string) {
     super(message);
-    this.name = 'QueueOverflowError';
+    this.name = "QueueOverflowError";
 
     // Maintains proper stack trace for where error was thrown (V8 only)
     if (Error.captureStackTrace) {

package/src/utils/circuit-breaker.ts

@@ -31,7 +31,10 @@ export interface CircuitBreakerOptions {
  * Error thrown when circuit is open
  */
 export class CircuitBreakerError extends Error {
-  constructor(message: string, public readonly state: CircuitState) {
+  constructor(
+    message: string,
+    public readonly state: CircuitState
+  ) {
     super(message);
     this.name = "CircuitBreakerError";
 

package/src/utils/deduplication-cache.test.ts

@@ -25,15 +25,11 @@ describe("DeduplicationCache", () => {
     });
 
     it("should throw error if TTL is less than 1000ms", () => {
-      expect(() => new DeduplicationCache(999)).toThrow(
-        "TTL must be at least 1000ms"
-      );
+      expect(() => new DeduplicationCache(999)).toThrow("TTL must be at least 1000ms");
     });
 
     it("should throw error if maxSize is less than 1", () => {
-      expect(() => new DeduplicationCache(5000, 0)).toThrow(
-        "maxSize must be at least 1"
-      );
+      expect(() => new DeduplicationCache(5000, 0)).toThrow("maxSize must be at least 1");
     });
   });
 

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

@@ -376,6 +376,9 @@ describe("waitForAllEvents", () => {
     emitter.emit("data", { id: 1, value: "first" });
 
     const results = await promise;
-    expect(results).toEqual([{ id: 1, value: "first" }, { id: 2, value: "second" }]);
+    expect(results).toEqual([
+      { id: 1, value: "first" },
+      { id: 2, value: "second" }
+    ]);
   });
 });

package/src/utils/event-waiter.ts

@@ -102,7 +102,9 @@ export async function waitForEvent<T = any>(
     // Timeout handler - rejects after timeout
     timeoutHandle = setTimeout(() => {
       cleanup();
-      const message = options.timeoutMessage || `Timeout waiting for event '${eventName}' after ${options.timeout}ms`;
+      const message =
+        options.timeoutMessage ||
+        `Timeout waiting for event '${eventName}' after ${options.timeout}ms`;
       reject(new Error(message));
     }, options.timeout);
 
@@ -135,9 +137,7 @@ export async function waitForAnyEvent<T = any>(
   }>
 ): Promise<T> {
   return Promise.race(
-    waiters.map(({ emitter, eventName, options }) =>
-      waitForEvent<T>(emitter, eventName, options)
-    )
+    waiters.map(({ emitter, eventName, options }) => waitForEvent<T>(emitter, eventName, options))
   );
 }
 
@@ -165,8 +165,6 @@ export async function waitForAllEvents<T = any>(
   }>
 ): Promise<T[]> {
   return Promise.all(
-    waiters.map(({ emitter, eventName, options }) =>
-      waitForEvent<T>(emitter, eventName, options)
-    )
+    waiters.map(({ emitter, eventName, options }) => waitForEvent<T>(emitter, eventName, options))
   );
 }

package/src/utils/rate-limiter.test.ts

@@ -17,21 +17,15 @@ describe("TokenBucketRateLimiter", () => {
     });
 
     it("should throw error if tokensPerSecond is less than 1", () => {
-      expect(() => new TokenBucketRateLimiter(0, 10)).toThrow(
-        "tokensPerSecond must be at least 1"
-      );
+      expect(() => new TokenBucketRateLimiter(0, 10)).toThrow("tokensPerSecond must be at least 1");
       expect(() => new TokenBucketRateLimiter(-1, 10)).toThrow(
         "tokensPerSecond must be at least 1"
       );
     });
 
     it("should throw error if maxBurst is less than 1", () => {
-      expect(() => new TokenBucketRateLimiter(10, 0)).toThrow(
-        "maxBurst must be at least 1"
-      );
-      expect(() => new TokenBucketRateLimiter(10, -1)).toThrow(
-        "maxBurst must be at least 1"
-      );
+      expect(() => new TokenBucketRateLimiter(10, 0)).toThrow("maxBurst must be at least 1");
+      expect(() => new TokenBucketRateLimiter(10, -1)).toThrow("maxBurst must be at least 1");
     });
   });
 
@@ -159,9 +153,7 @@ describe("TokenBucketRateLimiter", () => {
       // Reset and try again to verify error message
       limiter.reset();
       limiter.tryConsume();
-      await expect(limiter.consume(10)).rejects.toThrow(
-        /Rate limit timeout/
-      );
+      await expect(limiter.consume(10)).rejects.toThrow(/Rate limit timeout/);
     });
 
     it("should succeed within timeout if token becomes available", async () => {
@@ -309,11 +301,7 @@ describe("TokenBucketRateLimiter", () => {
       limiter.tryConsume();
 
       // Start multiple blocking consume calls
-      const promises = [
-        limiter.consume(1000),
-        limiter.consume(1000),
-        limiter.consume(1000)
-      ];
+      const promises = [limiter.consume(1000), limiter.consume(1000), limiter.consume(1000)];
 
       // All should eventually succeed as tokens refill
       await expect(Promise.all(promises)).resolves.toBeDefined();

package/src/utils/rate-limiter.ts

@@ -13,7 +13,7 @@
 export class RateLimitError extends Error {
   constructor(message: string) {
     super(message);
-    this.name = 'RateLimitError';
+    this.name = "RateLimitError";
 
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, RateLimitError);
@@ -64,10 +64,10 @@ export class TokenBucketRateLimiter {
     private readonly maxBurst: number
   ) {
     if (tokensPerSecond < 1) {
-      throw new Error('TokenBucketRateLimiter tokensPerSecond must be at least 1');
+      throw new Error("TokenBucketRateLimiter tokensPerSecond must be at least 1");
     }
     if (maxBurst < 1) {
-      throw new Error('TokenBucketRateLimiter maxBurst must be at least 1');
+      throw new Error("TokenBucketRateLimiter maxBurst must be at least 1");
     }
 
     this.tokens = maxBurst; // Start with full bucket
@@ -131,17 +131,14 @@ export class TokenBucketRateLimiter {
       // Check timeout
       const elapsed = Date.now() - startTime;
       if (timeout !== undefined && elapsed >= timeout) {
-        throw new RateLimitError(
-          `Rate limit timeout: no token available after ${timeout}ms`
-        );
+        throw new RateLimitError(`Rate limit timeout: no token available after ${timeout}ms`);
       }
 
       // Calculate wait time until next token
       // If timeout is specified, don't wait longer than remaining timeout
       const baseWaitTime = Math.min(this.refillInterval, 100);
-      const waitTime = timeout !== undefined
-        ? Math.min(baseWaitTime, timeout - elapsed)
-        : baseWaitTime;
+      const waitTime =
+        timeout !== undefined ? Math.min(baseWaitTime, timeout - elapsed) : baseWaitTime;
 
       // If waitTime is very small or negative, check timeout immediately
       if (waitTime <= 0) {