@teneo-protocol/sdk 1.0.0

package/src/managers/message-router.ts

@@ -0,0 +1,349 @@
+/**
+ * MessageRouter - Manages message sending and routing
+ * Handles user messages, direct commands, and message-response patterns
+ */
+
+import { EventEmitter } from "eventemitter3";
+import { v4 as uuidv4 } from "uuid";
+import { WebSocketClient } from "../core/websocket-client";
+import { WebhookHandler } from "../handlers/webhook-handler";
+import { ResponseFormatter, FormattedResponse } from "../formatters/response-formatter";
+import {
+  UserMessage,
+  createUserMessage,
+  Logger,
+  ResponseFormat,
+  TaskResponseMessage
+} from "../types";
+import { SDKEvents, SDKError, ValidationError, AgentResponse } from "../types/events";
+import { ErrorCode } from "../types/error-codes";
+import { TIMEOUTS } from "../constants";
+import {
+  MessageContentSchema,
+  AgentIdSchema,
+  AgentCommandContentSchema
+} from "../types/validation";
+import { waitForEvent } from "../utils/event-waiter";
+
+export interface SendMessageOptions {
+  room: string;
+  from?: string;
+  waitForResponse?: boolean;
+  timeout?: number;
+  format?: ResponseFormat | "raw" | "humanized";
+}
+
+export interface AgentCommand {
+  agent: string;
+  command: string;
+  room: string;
+}
+
+export class MessageRouter extends EventEmitter<SDKEvents> {
+  private readonly wsClient: WebSocketClient;
+  private readonly webhookHandler: WebhookHandler;
+  private readonly responseFormatter: ResponseFormatter;
+  private readonly logger: Logger;
+  private readonly messageTimeout: number;
+  private readonly responseFormat: ResponseFormat;
+
+  constructor(
+    wsClient: WebSocketClient,
+    webhookHandler: WebhookHandler,
+    responseFormatter: ResponseFormatter,
+    logger: Logger,
+    config: {
+      messageTimeout?: number;
+      responseFormat?: ResponseFormat;
+    }
+  ) {
+    super();
+    this.wsClient = wsClient;
+    this.webhookHandler = webhookHandler;
+    this.responseFormatter = responseFormatter;
+    this.logger = logger;
+    this.messageTimeout = config.messageTimeout ?? TIMEOUTS.DEFAULT_MESSAGE_TIMEOUT;
+    this.responseFormat = config.responseFormat ?? "humanized";
+
+    this.setupEventForwarding();
+  }
+
+  /**
+   * Sends a message to agents via the coordinator.
+   * The coordinator intelligently selects the most appropriate agent.
+   * Supports optional response waiting with configurable timeout and format.
+   *
+   * @param content - The message content to send
+   * @param options - Configuration for message sending
+   * @param options.room - Room to send to (required)
+   * @param options.from - Sender address (defaults to authenticated wallet)
+   * @param options.waitForResponse - Whether to wait for response (default: false)
+   * @param options.timeout - Response timeout in ms (default: 60000)
+   * @param options.format - Response format: 'raw', 'humanized', or 'both'
+   * @returns Promise resolving to FormattedResponse if waiting, void otherwise
+   * @throws {SDKError} If not connected
+   * @throws {ValidationError} If content is empty, room not specified, or options invalid
+   * @throws {TimeoutError} If waitForResponse and timeout exceeded
+   *
+   * @example
+   * ```typescript
+   * // Fire and forget
+   * await messageRouter.sendMessage('What is the weather?', { room: 'general' });
+   *
+   * // Wait for response
+   * const response = await messageRouter.sendMessage('Calculate 2+2', {
+   *   room: 'general',
+   *   waitForResponse: true,
+   *   timeout: 30000
+   * });
+   * console.log(response.humanized);
+   * ```
+   */
+  public async sendMessage(
+    content: string,
+    options: SendMessageOptions
+  ): Promise<FormattedResponse | void> {
+    if (!this.wsClient.isConnected) {
+      throw new SDKError("Not connected to Teneo network", ErrorCode.NOT_CONNECTED);
+    }
+
+    // Validate content
+    const validatedContent = MessageContentSchema.parse(content);
+
+    const room = options.room;
+    if (!room) {
+      throw new ValidationError("Room parameter is required");
+    }
+
+    // Use custom 'from' address if provided, otherwise use wallet address from auth state
+    const authState = this.wsClient.getAuthState();
+    const fromAddress = options.from ?? authState.walletAddress;
+
+    const message = createUserMessage(validatedContent, room, fromAddress);
+
+    this.logger.debug("MessageRouter: Sending message", {
+      content: validatedContent,
+      room,
+      from: fromAddress
+    });
+
+    if (options.waitForResponse) {
+      return await this.sendMessageAndWaitForResponse(message, options);
+    } else {
+      await this.wsClient.sendMessage(message);
+      await this.webhookHandler.sendMessageWebhook(message);
+    }
+  }
+
+  /**
+   * Sends a direct command to a specific agent, bypassing the coordinator.
+   * Formats command as "@agentName command" internally.
+   *
+   * @param command - The direct agent command configuration
+   * @param command.agent - Agent ID or name to send command to
+   * @param command.command - Command text to send
+   * @param command.room - Room to send in (required)
+   * @returns Promise that resolves when command is sent
+   * @throws {SDKError} If not connected
+   * @throws {ValidationError} If agent/command empty or room not specified
+   *
+   * @example
+   * ```typescript
+   * await messageRouter.sendDirectCommand({
+   *   agent: 'weather-agent',
+   *   command: 'Get forecast for Tokyo',
+   *   room: 'general'
+   * });
+   * ```
+   */
+  public async sendDirectCommand(command: AgentCommand): Promise<FormattedResponse | void> {
+    if (!this.wsClient.isConnected) {
+      throw new SDKError("Not connected to Teneo network", ErrorCode.NOT_CONNECTED);
+    }
+
+    // Validate command
+    const validatedAgent = AgentIdSchema.parse(command.agent);
+    const validatedCommand = AgentCommandContentSchema.parse(command.command);
+
+    const room = command.room;
+    if (!room) {
+      throw new ValidationError("Room parameter is required");
+    }
+
+    // Get wallet address from auth state
+    const authState = this.wsClient.getAuthState();
+    const walletAddress = authState.walletAddress;
+
+    // Format as direct command
+    const content = `@${validatedAgent} ${validatedCommand}`;
+    const message = createUserMessage(content, room, walletAddress);
+
+    this.logger.debug("MessageRouter: Sending direct command", {
+      agent: validatedAgent,
+      command: validatedCommand,
+      room,
+      from: walletAddress
+    });
+
+    await this.wsClient.sendMessage(message);
+    await this.webhookHandler.sendMessageWebhook(message);
+  }
+
+
+
+  /**
+   * Send message and wait for agent response
+   * Uses event-waiter utility for clean Promise-based waiting with automatic cleanup
+   */
+  private async sendMessageAndWaitForResponse(
+    message: UserMessage,
+    options: SendMessageOptions
+  ): Promise<FormattedResponse> {
+    // Generate unique request ID for correlation
+    const requestId = uuidv4();
+    const timeout = options.timeout ?? this.messageTimeout;
+    const format = options.format ?? this.responseFormat;
+
+    // Add client_request_id to message data for server-side correlation
+    const messageWithId: UserMessage = {
+      ...message,
+      data: {
+        ...(message.data || {}),
+        client_request_id: requestId
+      }
+    };
+
+    this.logger.debug("Sending message with request tracking", { requestId });
+
+    // Send message first (fail fast if send fails)
+    await this.wsClient.sendMessage(messageWithId);
+
+    // Wait for agent response with automatic timeout and cleanup
+    // The filter ensures we only match responses for THIS specific request
+    const response = await waitForEvent<AgentResponse>(this.wsClient, "agent:response", {
+      timeout,
+      filter: (r) => {
+        // Try to match by client_request_id if server echoes it back
+        const responseRequestId =
+          r.raw?.data && "client_request_id" in r.raw.data
+            ? (r.raw.data as any).client_request_id
+            : undefined;
+
+        return responseRequestId === requestId;
+      },
+      timeoutMessage: `Message timeout - no response received after ${timeout}ms (requestId: ${requestId})`
+    });
+
+    // Format response according to requested format
+    if (format === "raw" && response.raw) {
+      return response.raw as unknown as FormattedResponse;
+    }
+    return response as FormattedResponse;
+  }
+
+  /**
+   * Set up event forwarding from WebSocket client
+   */
+  private setupEventForwarding(): void {
+    // Forward message events
+    this.wsClient.on("message:sent", (message) => {
+      this.emit("message:sent", message);
+      // Fire and forget - don't block event emission
+      this.webhookHandler.sendMessageWebhook(message).catch((error) => {
+        this.logger.error("Failed to send webhook for message:sent", error);
+      });
+    });
+
+    this.wsClient.on("message:received", (message) => {
+      this.emit("message:received", message);
+
+      // Send webhook for received messages (fire-and-forget)
+      if (message.type !== "ping" && message.type !== "pong") {
+        this.webhookHandler.sendMessageWebhook(message).catch((error) => {
+          this.logger.error("Failed to send webhook for message:received", error);
+        });
+      }
+    });
+
+    this.wsClient.on("message:error", (error, message) =>
+      this.emit("message:error", error, message)
+    );
+
+    // Forward agent events
+    this.wsClient.on("agent:selected", (data) => {
+      this.emit("agent:selected", data);
+      // Fire and forget - don't block event emission
+      this.webhookHandler
+        .sendWebhook("agent_selected", data, {
+          agentId: data.agentId
+        })
+        .catch((error) => {
+          this.logger.error("Failed to send webhook for agent:selected", error);
+        });
+    });
+
+    this.wsClient.on("agent:response", (response) => {
+      // Format response only if raw message is available
+      let enhancedResponse = response;
+
+      if (response.raw) {
+        try {
+          const formatted = this.responseFormatter.formatTaskResponse(
+            response.raw as TaskResponseMessage
+          );
+          enhancedResponse = {
+            ...response,
+            ...formatted
+          };
+        } catch (error) {
+          this.logger.debug("Could not format response, using original", {
+            error
+          });
+        }
+      }
+
+      // Emit event (waitForEvent listeners will receive this)
+      this.emit("agent:response", enhancedResponse);
+
+      // Fire and forget - don't block event emission
+      this.webhookHandler
+        .sendWebhook("task_response", enhancedResponse, {
+          agentId: response.agentId,
+          taskId: response.taskId
+        })
+        .catch((error) => {
+          this.logger.error("Failed to send webhook for agent:response", error);
+        });
+    });
+
+    // Forward coordinator events
+    this.wsClient.on("coordinator:processing", (request) =>
+      this.emit("coordinator:processing", request)
+    );
+    this.wsClient.on("coordinator:selected", (agentId, reasoning) =>
+      this.emit("coordinator:selected", agentId, reasoning)
+    );
+    this.wsClient.on("coordinator:error", (error) => this.emit("coordinator:error", error));
+  }
+
+  /**
+   * Destroys the message router and cleans up resources.
+   * Removes all event listeners and marks the router as destroyed.
+   * After destruction, the router cannot be reused.
+   *
+   * Note: Any pending waitForEvent calls will automatically timeout and clean up.
+   *
+   * @example
+   * ```typescript
+   * messageRouter.destroy();
+   * console.log('Message router destroyed');
+   * ```
+   */
+  public destroy(): void {
+    this.logger.info("MessageRouter: Destroying");
+
+    // Remove all event listeners
+    // Any pending waitForEvent calls will automatically timeout and clean up
+    this.removeAllListeners();
+  }
+}

package/src/managers/room-manager.ts

@@ -0,0 +1,248 @@
+/**
+ * RoomManager - Manages room state and operations
+ * Handles joining, leaving, and tracking rooms
+ */
+
+import { EventEmitter } from "eventemitter3";
+import { WebSocketClient } from "../core/websocket-client";
+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";
+
+export class RoomManager extends EventEmitter<SDKEvents> {
+  private readonly wsClient: WebSocketClient;
+  private readonly logger: Logger;
+  private readonly rooms = new Map<string, Room>();
+  private readonly subscribedRooms = new Set<string>();
+
+  constructor(wsClient: WebSocketClient, logger: Logger) {
+    super();
+    this.wsClient = wsClient;
+    this.logger = logger;
+  }
+
+  /**
+   * Subscribes to a public room in the Teneo network.
+   * Validates room ID and sends subscribe message to the server.
+   * The actual subscription state is updated when the server confirms via room:subscribed event.
+   *
+   * @param roomId - The ID of the room to subscribe to
+   * @returns Promise that resolves when subscribed
+   * @throws {SDKError} If not connected to the network
+   * @throws {ValidationError} If roomId is empty or invalid
+   *
+   * @example
+   * ```typescript
+   * await roomManager.subscribeToRoom('general');
+   * console.log('Subscription request sent to general room');
+   * ```
+   */
+  public async subscribeToRoom(roomId: string): Promise<void> {
+    if (!this.wsClient.isConnected) {
+      throw new SDKError("Not connected to Teneo network", ErrorCode.NOT_CONNECTED);
+    }
+
+    // Validate room ID
+    const validatedRoomId = RoomIdSchema.parse(roomId);
+
+    this.logger.info("RoomManager: Subscribing to room", { roomId: validatedRoomId });
+
+    const message = createSubscribe(validatedRoomId);
+    await this.wsClient.sendMessage(message);
+  }
+
+  /**
+   * Unsubscribes from a room in the Teneo network.
+   * Validates room ID and sends unsubscribe message to the server.
+   * The actual subscription state is updated when the server confirms via room:unsubscribed event.
+   *
+   * @param roomId - The ID of the room to unsubscribe from
+   * @returns Promise that resolves when unsubscribed
+   * @throws {SDKError} If not connected to the network
+   * @throws {ValidationError} If roomId is empty or invalid
+   *
+   * @example
+   * ```typescript
+   * await roomManager.unsubscribeFromRoom('general');
+   * console.log('Unsubscription request sent for general room');
+   * ```
+   */
+  public async unsubscribeFromRoom(roomId: string): Promise<void> {
+    if (!this.wsClient.isConnected) {
+      throw new SDKError("Not connected to Teneo network", ErrorCode.NOT_CONNECTED);
+    }
+
+    // Validate room ID
+    const validatedRoomId = RoomIdSchema.parse(roomId);
+
+    this.logger.info("RoomManager: Unsubscribing from room", { roomId: validatedRoomId });
+
+    const message = createUnsubscribe(validatedRoomId);
+    await this.wsClient.sendMessage(message);
+  }
+
+  /**
+   * Updates the subscription state from server response.
+   * This is the authoritative source of which rooms you're subscribed to.
+   * Called internally when receiving subscribe/unsubscribe responses.
+   *
+   * @internal
+   * @param subscriptions - Array of room IDs from server response
+   *
+   * @example
+   * ```typescript
+   * // Internal SDK usage
+   * roomManager.updateSubscriptions(['general', 'support', 'trading']);
+   * ```
+   */
+  public updateSubscriptions(subscriptions: string[]): void {
+    this.subscribedRooms.clear();
+    subscriptions.forEach(roomId => this.subscribedRooms.add(roomId));
+    this.logger.debug("RoomManager: Subscriptions updated", {
+      count: subscriptions.length,
+      rooms: subscriptions
+    });
+  }
+
+  /**
+   * Gets all rooms currently subscribed to.
+   * Returns array of room IDs that you're actively listening to.
+   *
+   * @returns Array of subscribed room IDs
+   *
+   * @example
+   * ```typescript
+   * const rooms = roomManager.getSubscribedRooms();
+   * console.log(`Subscribed to ${rooms.length} rooms:`, rooms);
+   * ```
+   */
+  public getSubscribedRooms(): string[] {
+    return Array.from(this.subscribedRooms);
+  }
+
+  /**
+   * Gets a list of all available rooms.
+   * Returns rooms the user has access to based on authentication.
+   * Returns a read-only array with defensive copies to prevent external modification.
+   *
+   * @returns Read-only array of room copies
+   *
+   * @example
+   * ```typescript
+   * const rooms = roomManager.getRooms();
+   * rooms.forEach(room => console.log(`${room.id}: ${room.name}`));
+   * ```
+   */
+  public getRooms(): ReadonlyArray<Readonly<Room>> {
+    return Array.from(this.rooms.values()).map((room) => ({ ...room }));
+  }
+
+  /**
+   * Gets a specific room by its ID.
+   * Returns a defensive copy to prevent external modification of room state.
+   * Returns undefined if room doesn't exist or user doesn't have access.
+   *
+   * @param roomId - The ID of the room to retrieve
+   * @returns Copy of the room object if found, undefined otherwise
+   *
+   * @example
+   * ```typescript
+   * const room = roomManager.getRoom('general');
+   * if (room) {
+   *   console.log(`Room: ${room.name}`);
+   *   console.log(`Members: ${room.members?.length ?? 0}`);
+   * }
+   * ```
+   */
+  public getRoom(roomId: string): Readonly<Room> | undefined {
+    const room = this.rooms.get(roomId);
+    return room ? { ...room } : undefined;
+  }
+
+  /**
+   * Fetches the list of rooms from the server.
+   * Sends list_rooms message and waits for response from server.
+   * Returns array of rooms the user owns or has access to.
+   *
+   * @returns Promise that resolves to array of room information
+   * @throws {SDKError} If not connected to the network
+   *
+   * @example
+   * ```typescript
+   * const rooms = await roomManager.listRooms();
+   * rooms.forEach(room => {
+   *   console.log(`${room.name} (${room.is_public ? 'public' : 'private'})`);
+   *   console.log(`Owner: ${room.is_owner}`);
+   * });
+   * ```
+   */
+  public async listRooms(): Promise<RoomInfo[]> {
+    if (!this.wsClient.isConnected) {
+      throw new SDKError("Not connected to Teneo network", ErrorCode.NOT_CONNECTED);
+    }
+
+    this.logger.info("RoomManager: Listing rooms");
+
+    const message = createListRooms();
+    await this.wsClient.sendMessage(message);
+
+    // Room list will be received via list_rooms response handler
+    // For now, return empty array as this is async
+    // TODO: Implement response waiting mechanism
+    return [];
+  }
+
+  /**
+   * Updates the room list from authentication state.
+   * Called internally after successful authentication to populate accessible rooms.
+   *
+   * @internal This method is for internal SDK use
+   * @param rooms - Array of rooms to update in the manager
+   *
+   * @example
+   * ```typescript
+   * // Internal SDK usage after auth
+   * roomManager.updateRoomsFromAuth(authState.roomObjects);
+   * ```
+   */
+  public updateRoomsFromAuth(rooms: Room[]): void {
+    this.logger.debug("RoomManager: Updating rooms from auth", { count: rooms.length });
+
+    for (const room of rooms) {
+      this.rooms.set(room.id, room);
+    }
+  }
+
+  /**
+   * Clears all rooms from the manager.
+   * Clears subscription state.
+   *
+   * @example
+   * ```typescript
+   * roomManager.clear();
+   * console.log('All rooms cleared');
+   * ```
+   */
+  public clear(): void {
+    this.rooms.clear();
+    this.subscribedRooms.clear();
+  }
+
+  /**
+   * Destroys the room manager and cleans up resources.
+   * Clears all rooms and removes all event listeners.
+   * After destruction, the manager cannot be reused.
+   *
+   * @example
+   * ```typescript
+   * roomManager.destroy();
+   * console.log('Room manager destroyed');
+   * ```
+   */
+  public destroy(): void {
+    this.logger.info("RoomManager: Destroying");
+    this.clear();
+    this.removeAllListeners();
+  }
+}