@teneo-protocol/sdk 1.0.0 → 2.0.0

package/src/handlers/message-handlers/agent-status-update-handler.ts

@@ -0,0 +1,58 @@
+/**
+ * Handler for agent_status_update messages (v2.0.0)
+ * Processes real-time agent status updates for rooms
+ */
+
+import {
+  AgentStatusUpdateMessage,
+  AgentStatusUpdateMessageSchema
+} from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class AgentStatusUpdateHandler extends BaseMessageHandler<AgentStatusUpdateMessage> {
+  readonly type = "agent_status_update" as const;
+  readonly schema = AgentStatusUpdateMessageSchema;
+
+  protected handleValidated(
+    message: AgentStatusUpdateMessage,
+    context: HandlerContext
+  ): void {
+    const { room_id, agent_id, status, agent } = message.data;
+
+    context.logger.debug("Handling agent_status_update", {
+      roomId: room_id,
+      agentId: agent_id,
+      status,
+      hasAgent: !!agent
+    });
+
+    // Invalidate cache for this room via agent room manager
+    const agentRoomManager = (context as any).agentRoomManager;
+    if (agentRoomManager && typeof agentRoomManager.handleStatusUpdate === "function") {
+      agentRoomManager.handleStatusUpdate(room_id, agent_id, status);
+    }
+
+    context.logger.info("Agent status updated", {
+      roomId: room_id,
+      agentId: agent_id,
+      status
+    });
+
+    // Emit status update event
+    this.emit(context, "agent_room:status_update", {
+      roomId: room_id,
+      agentId: agent_id,
+      status,
+      agent
+    });
+
+    // Send webhook
+    this.sendWebhook(context, "agent_status_update", {
+      room_id,
+      agent_id,
+      status,
+      agent
+    });
+  }
+}

package/src/handlers/message-handlers/auth-message-handler.ts

@@ -26,8 +26,27 @@ export class AuthMessageHandler extends BaseMessageHandler<AuthMessage> {
         isCachedAuth ? "Using cached authentication" : "Authentication successful"
       );
 
-      // Extract rooms
-      const rooms = this.extractRooms(message.data?.rooms);
+      // Extract rooms from both 'rooms' (public) and 'private_rooms' (owned private) arrays
+      const publicRooms = this.extractRooms(message.data?.rooms);
+      const privateRooms = this.extractRooms(message.data?.private_rooms);
+
+      // Combine all rooms, ensuring correct ownership flags
+      // Public rooms from 'rooms' array are NOT owned by the user
+      // Private rooms from 'private_rooms' array ARE owned by the user
+      const allRooms = [
+        ...publicRooms.map((r) => ({
+          ...r,
+          is_owner: false, // Explicitly set to false - public rooms are not owned
+          is_public: r.is_public !== undefined ? r.is_public : true // Ensure is_public is set
+        })),
+        ...privateRooms.map((r) => ({
+          ...r,
+          is_owner: true, // Explicitly set to true - private_rooms array means owned
+          is_public: r.is_public !== undefined ? r.is_public : false // Ensure is_public is set
+        }))
+      ];
+
+      const { privateRoomIds, sharedRoomIds } = this.categorizeRooms(allRooms);
 
       // Update connection state
       this.updateConnectionState(context, { authenticated: true });
@@ -40,11 +59,37 @@ export class AuthMessageHandler extends BaseMessageHandler<AuthMessage> {
         isWhitelisted: message.data?.is_whitelisted,
         isAdmin: message.data?.is_admin_whitelisted,
         nftVerified: message.data?.nft_verified,
-        rooms: rooms.map((r) => r.id),
-        roomObjects: rooms,
-        privateRoomId: message.data?.private_room_id
+        rooms: allRooms.map((r) => r.id),
+        roomObjects: allRooms,
+        privateRoomId: message.data?.private_room_id,
+        // v2.0.0: New fields
+        privateRoomIds, // Rooms user owns
+        sharedRoomIds, // Rooms user is member of
+        maxPrivateRooms: message.data?.max_private_rooms // Max rooms user can create
       });
 
+      // Initialize room management manager with room data (v2.0.0)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const roomMgmt = (context as any).roomManagementManager;
+      if (roomMgmt) {
+        // Set room limit
+        if (message.data?.max_private_rooms) {
+          roomMgmt.setRoomLimit(message.data.max_private_rooms);
+        }
+
+        // Categorize and cache rooms
+        const ownedRooms = allRooms.filter((r) => r.is_owner === true);
+        const sharedRooms = allRooms.filter((r) => r.is_owner === false);
+        roomMgmt.setOwnedRooms(ownedRooms);
+        roomMgmt.setSharedRooms(sharedRooms);
+
+        context.logger.debug("Room management initialized from auth message", {
+          owned: ownedRooms.length,
+          shared: sharedRooms.length,
+          limit: message.data?.max_private_rooms
+        });
+      }
+
       // Get updated auth state
       const authState = context.getAuthState();
 
@@ -63,4 +108,27 @@ export class AuthMessageHandler extends BaseMessageHandler<AuthMessage> {
     }
     return rooms;
   }
+
+  /**
+   * Categorize rooms into owned vs member rooms based on is_owner flag
+   * @param rooms - Array of room info objects
+   * @returns Object with privateRoomIds (owned) and sharedRoomIds (member)
+   */
+  private categorizeRooms(rooms: Room[]): {
+    privateRoomIds: string[];
+    sharedRoomIds: string[];
+  } {
+    const privateRoomIds: string[] = [];
+    const sharedRoomIds: string[] = [];
+
+    for (const room of rooms) {
+      if (room.is_owner) {
+        if (room.id) privateRoomIds.push(room.id);
+      } else {
+        if (room.id) sharedRoomIds.push(room.id);
+      }
+    }
+
+    return { privateRoomIds, sharedRoomIds };
+  }
 }

package/src/handlers/message-handlers/auth-success-handler.ts

@@ -4,7 +4,7 @@
  */
 
 import { z } from "zod";
-import { AuthSuccessMessage, AuthSuccessMessageSchema, Room } from "../../types";
+import { AuthSuccessMessage, AuthSuccessMessageSchema, RoomInfo } from "../../types";
 import { BaseMessageHandler } from "./base-handler";
 import { HandlerContext } from "./types";
 
@@ -18,8 +18,9 @@ export class AuthSuccessHandler extends BaseMessageHandler<AuthSuccessMessage> {
   ): Promise<void> {
     context.logger.info("Authentication successful");
 
-    // Extract rooms
+    // Extract and categorize rooms
     const rooms = this.extractRooms(message.data.rooms);
+    const { privateRoomIds, sharedRoomIds } = this.categorizeRooms(rooms);
 
     // Update connection state
     this.updateConnectionState(context, { authenticated: true });
@@ -32,14 +33,42 @@ export class AuthSuccessHandler extends BaseMessageHandler<AuthSuccessMessage> {
       isWhitelisted: message.data.is_whitelisted,
       isAdmin: message.data.is_admin_whitelisted,
       nftVerified: message.data.nft_verified,
-      rooms: rooms.map((r) => r.id),
-      roomObjects: rooms,
-      privateRoomId: message.data.private_room_id
+
+      // Backward compatibility: deprecated fields
+      rooms: rooms.map((r) => r.id), // All room IDs
+      privateRoomId: message.data.private_room_id, // DEPRECATED: single private room ID
+
+      // v2.0.0: New fields
+      roomObjects: rooms, // Full room objects with is_owner field
+      privateRoomIds, // Rooms user owns
+      sharedRoomIds, // Rooms user is member of
+      maxPrivateRooms: message.data.max_private_rooms // Max rooms user can create
     });
 
     // Get updated auth state
     const authState = context.getAuthState();
 
+    // Initialize room management manager with room data (v2.0.0)
+    const roomMgmt = (context as any).roomManagementManager;
+    if (roomMgmt) {
+      // Set room limit
+      if (message.data.max_private_rooms) {
+        roomMgmt.setRoomLimit(message.data.max_private_rooms);
+      }
+
+      // Categorize and cache rooms
+      const ownedRooms = rooms.filter((r) => r.is_owner);
+      const sharedRooms = rooms.filter((r) => !r.is_owner);
+      roomMgmt.setOwnedRooms(ownedRooms);
+      roomMgmt.setSharedRooms(sharedRooms);
+
+      context.logger.debug("Room management initialized", {
+        owned: ownedRooms.length,
+        shared: sharedRooms.length,
+        limit: message.data.max_private_rooms
+      });
+    }
+
     // Emit events
     this.emit(context, "auth:success", authState);
     this.emit(context, "ready");
@@ -48,10 +77,33 @@ export class AuthSuccessHandler extends BaseMessageHandler<AuthSuccessMessage> {
   /**
    * Extract and normalize rooms from auth data
    */
-  private extractRooms(rooms?: Room[]): Room[] {
+  private extractRooms(rooms?: RoomInfo[] | null): RoomInfo[] {
     if (!rooms || !Array.isArray(rooms)) {
       return [];
     }
     return rooms;
   }
+
+  /**
+   * Categorize rooms into owned vs member rooms based on is_owner flag
+   * @param rooms - Array of room info objects
+   * @returns Object with privateRoomIds (owned) and sharedRoomIds (member)
+   */
+  private categorizeRooms(rooms: RoomInfo[]): {
+    privateRoomIds: string[];
+    sharedRoomIds: string[];
+  } {
+    const privateRoomIds: string[] = [];
+    const sharedRoomIds: string[] = [];
+
+    for (const room of rooms) {
+      if (room.is_owner) {
+        privateRoomIds.push(room.id);
+      } else {
+        sharedRoomIds.push(room.id);
+      }
+    }
+
+    return { privateRoomIds, sharedRoomIds };
+  }
 }

package/src/handlers/message-handlers/index.ts

@@ -22,6 +22,11 @@ export { PingHandler, PongHandler } from "./ping-pong-handler";
 export { SubscribeResponseHandler } from "./subscribe-response-handler";
 export { UnsubscribeResponseHandler } from "./unsubscribe-response-handler";
 export { ListRoomsResponseHandler } from "./list-rooms-response-handler";
+export { RoomOperationResponseHandler } from "./room-operation-response-handler";
+export { AgentRoomOperationResponseHandler } from "./agent-room-operation-response-handler";
+export { ListRoomAgentsHandler } from "./list-room-agents-handler";
+export { ListAvailableAgentsHandler } from "./list-available-agents-handler";
+export { AgentStatusUpdateHandler } from "./agent-status-update-handler";
 
 // Import for convenience function
 import { TaskResponseHandler } from "./task-response-handler";
@@ -38,6 +43,11 @@ import { PingHandler, PongHandler } from "./ping-pong-handler";
 import { SubscribeResponseHandler } from "./subscribe-response-handler";
 import { UnsubscribeResponseHandler } from "./unsubscribe-response-handler";
 import { ListRoomsResponseHandler } from "./list-rooms-response-handler";
+import { RoomOperationResponseHandler } from "./room-operation-response-handler";
+import { AgentRoomOperationResponseHandler } from "./agent-room-operation-response-handler";
+import { ListRoomAgentsHandler } from "./list-room-agents-handler";
+import { ListAvailableAgentsHandler } from "./list-available-agents-handler";
+import { AgentStatusUpdateHandler } from "./agent-status-update-handler";
 import { MessageHandler } from "./types";
 
 /**
@@ -70,6 +80,15 @@ export function getDefaultHandlers(
     new UnsubscribeResponseHandler(),
     new ListRoomsResponseHandler(),
 
+    // Room Management handlers (v2.0.0)
+    new RoomOperationResponseHandler(),
+
+    // Agent Room Management handlers (v2.0.0)
+    new AgentRoomOperationResponseHandler(),
+    new ListRoomAgentsHandler(),
+    new ListAvailableAgentsHandler(),
+    new AgentStatusUpdateHandler(),
+
     // Keepalive handlers
     new PingHandler(),
     new PongHandler()

package/src/handlers/message-handlers/list-available-agents-handler.ts

@@ -0,0 +1,41 @@
+/**
+ * Handler for available_agents_response messages (v2.0.0)
+ * Processes responses from list_available_agents requests
+ */
+
+import { AvailableAgentsResponse, AvailableAgentsResponseSchema } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+import { AgentRoomInfo } from "../../managers/agent-room-manager";
+
+export class ListAvailableAgentsHandler extends BaseMessageHandler<AvailableAgentsResponse> {
+  readonly type = "available_agents_response" as const;
+  readonly schema = AvailableAgentsResponseSchema;
+
+  protected handleValidated(message: AvailableAgentsResponse, context: HandlerContext): void {
+    const { agents } = message.data;
+
+    context.logger.debug("Handling available_agents_response", {
+      agentCount: agents?.length || 0
+    });
+
+    // Parse agents array (handle undefined as empty array)
+    const agentList: AgentRoomInfo[] = agents || [];
+
+    context.logger.info("Available agents listed", {
+      count: agentList.length
+    });
+
+    // Note: We don't cache this globally since it's room-specific
+    // The AgentRoomManager will cache it with the room context
+
+    // Emit success event
+    this.emit(context, "agent_room:available_agents_listed", agentList);
+
+    // Send webhook
+    this.sendWebhook(context, "available_agents_listed", {
+      agents: agentList,
+      count: agentList.length
+    });
+  }
+}

package/src/handlers/message-handlers/list-room-agents-handler.ts

@@ -0,0 +1,61 @@
+/**
+ * Handler for room_agents_response messages (v2.0.0)
+ * Processes responses from list_room_agents requests
+ */
+
+import { RoomAgentsResponse, RoomAgentsResponseSchema } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+import { SDKError } from "../../types/events";
+import { ErrorCode } from "../../types/error-codes";
+import { AgentRoomInfo } from "../../managers/agent-room-manager";
+
+export class ListRoomAgentsHandler extends BaseMessageHandler<RoomAgentsResponse> {
+  readonly type = "room_agents_response" as const;
+  readonly schema = RoomAgentsResponseSchema;
+
+  protected handleValidated(
+    message: RoomAgentsResponse,
+    context: HandlerContext
+  ): void {
+    const { room_id, agents } = message.data;
+
+    context.logger.debug("Handling room_agents_response", {
+      roomId: room_id,
+      agentCount: agents?.length || 0
+    });
+
+    if (!room_id) {
+      const error = new SDKError(
+        "Room agents response missing room_id",
+        ErrorCode.VALIDATION_ERROR
+      );
+      this.emit(context, "agent_room:list_error", error, undefined);
+      return;
+    }
+
+    // Parse agents array (handle undefined as empty array)
+    const agentList: AgentRoomInfo[] = agents || [];
+
+    context.logger.info("Room agents listed", {
+      roomId: room_id,
+      count: agentList.length
+    });
+
+    // Cache via agent room manager if available
+    const agentRoomManager = (context as any).agentRoomManager;
+    if (agentRoomManager && typeof agentRoomManager.cacheRoomAgents === "function") {
+      agentRoomManager.cacheRoomAgents(room_id, agentList);
+    }
+
+    // Emit success event
+    this.emit(context, "agent_room:agents_listed", room_id, agentList);
+
+    // Send webhook
+    this.sendWebhook(context, "room_agents_listed", {
+      room_id,
+      agents: agentList,
+      count: agentList.length
+    });
+  }
+}

package/src/handlers/message-handlers/regular-message-handler.ts

@@ -54,6 +54,7 @@ export class RegularMessageHandler extends BaseMessageHandler<UserMessage> {
         contentType: message.content_type || "text/plain",
         success: true,
         timestamp: new Date(),
+        raw: message as any, // Include raw message for request correlation
         humanized:
           typeof message.content === "string" ? message.content : JSON.stringify(message.content)
       };

package/src/handlers/message-handlers/room-operation-response-handler.ts

@@ -0,0 +1,105 @@
+/**
+ * Handler for room_operation_response messages (v2.0.0)
+ * Processes responses from room CRUD operations (create, update, delete)
+ */
+
+import { RoomOperationResponse, RoomOperationResponseSchema } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+import { SDKError } from "../../types/events";
+import { ErrorCode } from "../../types/error-codes";
+
+export class RoomOperationResponseHandler extends BaseMessageHandler<RoomOperationResponse> {
+  readonly type = "room_operation_response" as const;
+  readonly schema = RoomOperationResponseSchema;
+
+  protected handleValidated(
+    message: RoomOperationResponse,
+    context: HandlerContext
+  ): void {
+    const { success, message: errorMessage, room_id, room } = message.data;
+
+    context.logger.debug("Handling room_operation_response", {
+      success,
+      roomId: room_id,
+      hasRoom: !!room
+    });
+
+    if (!success) {
+      // Operation failed - emit error event
+      const error = new SDKError(
+        errorMessage || "Room operation failed",
+        ErrorCode.OPERATION_FAILED
+      );
+
+      // Try to determine operation type from message
+      // Note: Server should ideally send operation type in response
+      // For now we emit generic errors and specific listeners will catch relevant ones
+      this.emit(context, "room:create_error", error);
+      this.emit(context, "room:update_error", error, room_id);
+      this.emit(context, "room:delete_error", error, room_id);
+
+      // Send webhook
+      this.sendWebhook(context, "room_operation_error", {
+        success: false,
+        message: errorMessage,
+        room_id
+      });
+
+      return;
+    }
+
+    // Operation succeeded
+    if (room) {
+      // Create or Update operation (includes room object)
+      context.logger.info("Room operation succeeded", {
+        roomId: room.id,
+        roomName: room.name
+      });
+
+      // Determine if this was create or update based on whether we have the room cached
+      // Note: Ideally server would send operation type in response
+      // For now, handlers will emit both and listeners filter by room_id
+
+      // Update cache via room management manager if available
+      const roomManager = (context as any).roomManagementManager;
+      if (roomManager && typeof roomManager.upsertRoom === "function") {
+        roomManager.upsertRoom(room);
+      }
+
+      // Emit success events
+      // The promise handlers in RoomManagementManager will filter by room_id
+      this.emit(context, "room:created", room);
+      this.emit(context, "room:updated", room);
+
+      // Send webhook
+      this.sendWebhook(context, "room_operation", {
+        success: true,
+        room,
+        message: "Room operation completed successfully"
+      });
+    } else if (room_id) {
+      // Delete operation (only has room_id, no room object)
+      context.logger.info("Room deleted", { roomId: room_id });
+
+      // Remove from cache
+      const roomManager = (context as any).roomManagementManager;
+      if (roomManager && typeof roomManager.removeRoom === "function") {
+        roomManager.removeRoom(room_id);
+      }
+
+      // Emit delete success
+      this.emit(context, "room:deleted", room_id);
+
+      // Send webhook
+      this.sendWebhook(context, "room_deleted", {
+        success: true,
+        room_id,
+        message: "Room deleted successfully"
+      });
+    } else {
+      // Unexpected: success but no room or room_id
+      context.logger.warn("Room operation succeeded but no room data provided");
+    }
+  }
+}

package/src/handlers/message-handlers/types.ts

@@ -34,6 +34,12 @@ export interface HandlerContext {
   // Room manager for subscription updates (optional)
   roomManager?: any;
 
+  // Room management manager for CRUD operations (v2.0.0, optional)
+  roomManagementManager?: any;
+
+  // Agent room manager for agent-room operations (v2.0.0, optional)
+  agentRoomManager?: any;
+
   // Account for signing (optional, for auth handlers)
   account?: PrivateKeyAccount;
 

package/src/handlers/webhook-handler.test.ts

@@ -118,7 +118,10 @@ describe("WebhookHandler", () => {
       expect(queue[0].payload.timestamp).toBeDefined();
       expect(queue[1].payload.timestamp).toBeDefined();
       // Each webhook gets unique timestamp
-      expect(queue[0].payload.timestamp !== queue[1].payload.timestamp || queue[0].payload.data.content !== queue[1].payload.data.content).toBe(true);
+      expect(
+        queue[0].payload.timestamp !== queue[1].payload.timestamp ||
+          queue[0].payload.data.content !== queue[1].payload.data.content
+      ).toBe(true);
     });
 
     it("should include timestamp in webhook payload", async () => {
@@ -584,20 +587,17 @@ describe("WebhookHandler", () => {
 
     describe("Protocol Validation", () => {
       it("should reject HTTP for non-localhost without allowInsecureWebhooks", () => {
-        const urls = [
-          "http://example.com/webhook"
-        ];
+        const urls = ["http://example.com/webhook"];
 
         urls.forEach((url) => {
           expect(() => (handler as any).validateWebhookUrl(url)).toThrow(WebhookError);
-          expect(() => (handler as any).validateWebhookUrl(url)).toThrow(/must use HTTPS|Only HTTPS/i);
+          expect(() => (handler as any).validateWebhookUrl(url)).toThrow(
+            /must use HTTPS|Only HTTPS/i
+          );
         });
 
         // Private IPs are blocked for different reason (private IP, not HTTPS requirement)
-        const privateUrls = [
-          "http://192.168.1.1/webhook",
-          "http://10.0.0.1/webhook"
-        ];
+        const privateUrls = ["http://192.168.1.1/webhook", "http://10.0.0.1/webhook"];
         privateUrls.forEach((url) => {
           expect(() => (handler as any).validateWebhookUrl(url)).toThrow(WebhookError);
           expect(() => (handler as any).validateWebhookUrl(url)).toThrow(/private IP/i);
@@ -720,7 +720,10 @@ describe("WebhookHandler", () => {
         vi.advanceTimersByTime(10000);
       }
 
-      expect(errorHandler).toHaveBeenCalledWith(expect.any(Error), "https://webhook.example.com/events");
+      expect(errorHandler).toHaveBeenCalledWith(
+        expect.any(Error),
+        "https://webhook.example.com/events"
+      );
     });
   });