@teneo-protocol/sdk 1.0.0

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

@@ -0,0 +1,239 @@
+/**
+ * Message Handler Registry
+ * Central registry for message handlers - eliminates shotgun surgery when adding new message types
+ */
+
+import { BaseMessage, MessageType, Logger } from "../types";
+import {
+  MessageHandler,
+  HandlerContext,
+  HandlerRegistrationOptions
+} from "./message-handlers/types";
+import { ValidationError } from "../types/events";
+
+/**
+ * Registry for message handlers
+ * Stores handlers by message type and routes messages to appropriate handlers
+ */
+export class MessageHandlerRegistry {
+  private readonly handlers = new Map<MessageType, MessageHandler>();
+  private readonly logger: Logger;
+
+  constructor(logger: Logger) {
+    this.logger = logger;
+  }
+
+  /**
+   * Registers a message handler for a specific message type.
+   * Prevents duplicate registration unless replace option is true.
+   * Enables extensible message processing following Open/Closed Principle.
+   *
+   * @param handler - The handler to register (must have unique type)
+   * @param options - Registration options
+   * @param options.replace - Whether to replace existing handler (default: false)
+   *
+   * @example
+   * ```typescript
+   * const customHandler = new CustomMessageHandler();
+   * registry.register(customHandler);
+   *
+   * // Replace existing handler
+   * registry.register(newHandler, { replace: true });
+   * ```
+   */
+  public register(handler: MessageHandler, options: HandlerRegistrationOptions = {}): void {
+    const { replace = false } = options;
+
+    // Check if handler already exists
+    if (this.handlers.has(handler.type) && !replace) {
+      this.logger.warn(
+        `Handler for ${handler.type} already registered, skipping. Use replace:true to override.`
+      );
+      return;
+    }
+
+    this.handlers.set(handler.type, handler);
+    this.logger.debug(`Registered handler for message type: ${handler.type}`);
+  }
+
+  /**
+   * Registers multiple message handlers at once.
+   * Convenient for bulk registration of default or custom handlers.
+   * Uses same registration logic as register() for each handler.
+   *
+   * @param handlers - Array of handlers to register
+   * @param options - Registration options applied to all handlers
+   *
+   * @example
+   * ```typescript
+   * const handlers = [
+   *   new TaskResponseHandler(),
+   *   new AgentSelectedHandler(),
+   *   new ErrorHandler()
+   * ];
+   * registry.registerAll(handlers);
+   * ```
+   */
+  public registerAll(handlers: MessageHandler[], options: HandlerRegistrationOptions = {}): void {
+    for (const handler of handlers) {
+      this.register(handler, options);
+    }
+  }
+
+  /**
+   * Unregisters a handler for a specific message type.
+   * Returns whether a handler was actually removed.
+   *
+   * @param type - The message type to unregister
+   * @returns True if handler was removed, false if no handler existed
+   *
+   * @example
+   * ```typescript
+   * const removed = registry.unregister('task_response');
+   * if (removed) {
+   *   console.log('Handler removed successfully');
+   * }
+   * ```
+   */
+  public unregister(type: MessageType): boolean {
+    const result = this.handlers.delete(type);
+    if (result) {
+      this.logger.debug(`Unregistered handler for message type: ${type}`);
+    }
+    return result;
+  }
+
+  /**
+   * Checks if a handler is registered for a specific message type.
+   * Useful for conditional logic based on handler availability.
+   *
+   * @param type - The message type to check
+   * @returns True if handler exists, false otherwise
+   *
+   * @example
+   * ```typescript
+   * if (registry.has('task_response')) {
+   *   console.log('Task response handler is registered');
+   * }
+   * ```
+   */
+  public has(type: MessageType): boolean {
+    return this.handlers.has(type);
+  }
+
+  /**
+   * Gets a registered handler for a specific message type.
+   * Returns undefined if no handler is registered for the type.
+   *
+   * @param type - The message type to get handler for
+   * @returns The handler if found, undefined otherwise
+   *
+   * @example
+   * ```typescript
+   * const handler = registry.get('task_response');
+   * if (handler) {
+   *   console.log(`Handler found: ${handler.type}`);
+   * }
+   * ```
+   */
+  public get(type: MessageType): MessageHandler | undefined {
+    return this.handlers.get(type);
+  }
+
+  /**
+   * Routes a message to its appropriate handler based on message type.
+   * Validates handler can process the message before delegating.
+   * Catches and logs handler errors, wrapping them in ValidationError.
+   *
+   * @param message - The message to handle
+   * @param context - Handler context with dependencies (logger, emit, etc.)
+   * @returns Promise that resolves when message is handled
+   * @throws {ValidationError} If handler throws an error during processing
+   *
+   * @example
+   * ```typescript
+   * const message = { type: 'task_response', ... };
+   * const context = createHandlerContext();
+   * await registry.handle(message, context);
+   * ```
+   */
+  public async handle(message: BaseMessage, context: HandlerContext): Promise<void> {
+    // Check for pending message responses first (handled by caller)
+    if (message.id) {
+      // Let caller handle response matching
+      this.logger.debug(
+        `Message ${message.id} may be a response - caller should check pending messages`
+      );
+    }
+
+    // Find handler for this message type
+    const handler = this.handlers.get(message.type);
+
+    if (!handler) {
+      this.logger.debug(`No handler registered for message type: ${message.type}`);
+      // Not an error - some message types don't need handling
+      return;
+    }
+
+    // Verify handler can handle this message
+    if (!handler.canHandle(message)) {
+      this.logger.warn(`Handler for ${message.type} returned false for canHandle()`);
+      return;
+    }
+
+    // Delegate to handler
+    this.logger.debug(`Routing ${message.type} message to handler`);
+    try {
+      await handler.handle(message, context);
+    } catch (error) {
+      this.logger.error(`Handler for ${message.type} threw error`, error);
+      throw new ValidationError(`Handler for ${message.type} failed`, error);
+    }
+  }
+
+  /**
+   * Gets an array of all currently registered message types.
+   * Useful for introspection and debugging handler configuration.
+   *
+   * @returns Array of message types that have registered handlers
+   *
+   * @example
+   * ```typescript
+   * const types = registry.getRegisteredTypes();
+   * console.log(`Registered handlers: ${types.join(', ')}`);
+   * ```
+   */
+  public getRegisteredTypes(): MessageType[] {
+    return Array.from(this.handlers.keys());
+  }
+
+  /**
+   * Gets the total number of registered handlers.
+   * Convenience getter for handler count.
+   *
+   * @returns Number of registered handlers
+   *
+   * @example
+   * ```typescript
+   * console.log(`${registry.size} handlers registered`);
+   * ```
+   */
+  public get size(): number {
+    return this.handlers.size;
+  }
+
+  /**
+   * Clears all registered handlers from the registry.
+   * Useful for testing or resetting handler configuration.
+   *
+   * @example
+   * ```typescript
+   * registry.clear();
+   * console.log('All handlers cleared');
+   * ```
+   */
+  public clear(): void {
+    this.handlers.clear();
+    this.logger.debug("Cleared all message handlers");
+  }
+}

package/src/handlers/message-handlers/agent-selected-handler.ts

@@ -0,0 +1,40 @@
+/**
+ * Handler for agent_selected messages
+ * Processes coordinator's agent selection
+ */
+
+import { AgentSelectedMessage, AgentSelectedMessageSchema } from "../../types";
+import { AgentSelectedData } from "../../types/events";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class AgentSelectedHandler extends BaseMessageHandler<AgentSelectedMessage> {
+  readonly type = "agent_selected" as const;
+  readonly schema = AgentSelectedMessageSchema;
+
+  protected handleValidated(message: AgentSelectedMessage, context: HandlerContext): void {
+    context.logger.debug("Handling agent_selected message", {
+      agentId: message.data.agent_id,
+      agentName: message.data.agent_name
+    });
+
+    // Build agent selected data
+    const data: AgentSelectedData = {
+      agentId: message.data.agent_id,
+      agentName: message.data.agent_name,
+      reasoning: message.reasoning || "",
+      userRequest: message.data.user_request,
+      command: message.data.command,
+      commandReasoning: message.data.command_reasoning,
+      capabilities: message.data.capabilities
+    };
+
+    // Emit agent:selected event
+    this.emit(context, "agent:selected", data);
+
+    // Send webhook (fire-and-forget)
+    this.sendWebhook(context, "agent_selected", data, {
+      agentId: data.agentId
+    });
+  }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Handler for agents list messages
+ * Processes agent list updates from the server
+ */
+
+import { z } from "zod";
+import { AgentsListMessage, AgentsListMessageSchema } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class AgentsListHandler extends BaseMessageHandler<AgentsListMessage> {
+  readonly type = "agents" as const;
+  readonly schema = AgentsListMessageSchema as z.ZodSchema<AgentsListMessage>;
+
+  protected async handleValidated(
+    message: AgentsListMessage,
+    context: HandlerContext
+  ): Promise<void> {
+    context.logger.debug("Handling agents list message", {
+      count: message.data.length
+    });
+
+    // Emit agent:list event with the agents array
+    this.emit(context, "agent:list", message.data);
+  }
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Handler for auth_error messages
+ * Handles authentication errors
+ */
+
+import { AuthErrorMessage, AuthErrorMessageSchema } from "../../types";
+import { AuthenticationError } from "../../types/events";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class AuthErrorHandler extends BaseMessageHandler<AuthErrorMessage> {
+  readonly type = "auth_error" as const;
+  readonly schema = AuthErrorMessageSchema;
+
+  protected async handleValidated(
+    message: AuthErrorMessage,
+    context: HandlerContext
+  ): Promise<void> {
+    const error = message.data.error || "Authentication failed";
+    context.logger.error("Authentication failed", { error });
+
+    // Update states
+    this.updateAuthState(context, { authenticated: false });
+    this.updateConnectionState(context, {
+      lastError: new AuthenticationError(error)
+    });
+
+    // Emit error event
+    this.emit(context, "auth:error", error);
+  }
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Handler for auth messages
+ * Handles authentication response from server (both fresh and cached)
+ */
+
+import { z } from "zod";
+import { AuthMessage, AuthMessageSchema, Room } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class AuthMessageHandler extends BaseMessageHandler<AuthMessage> {
+  readonly type = "auth" as const;
+  readonly schema = AuthMessageSchema as z.ZodSchema<AuthMessage>;
+
+  protected async handleValidated(message: AuthMessage, context: HandlerContext): Promise<void> {
+    context.logger.info("Handling auth message", {
+      hasData: !!message.data,
+      dataKeys: message.data ? Object.keys(message.data) : [],
+      to: message.to
+    });
+
+    // Check if this is a successful auth response by looking for required fields
+    if (message.data?.id || message.data?.address || message.data?.cached_auth || message.to) {
+      const isCachedAuth = !!message.data?.cached_auth;
+      context.logger.info(
+        isCachedAuth ? "Using cached authentication" : "Authentication successful"
+      );
+
+      // Extract rooms
+      const rooms = this.extractRooms(message.data?.rooms);
+
+      // Update connection state
+      this.updateConnectionState(context, { authenticated: true });
+
+      // Update auth state
+      this.updateAuthState(context, {
+        authenticated: true,
+        clientId: message.data?.id || message.to || "",
+        walletAddress: message.data?.address || "",
+        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
+      });
+
+      // Get updated auth state
+      const authState = context.getAuthState();
+
+      // Emit events
+      this.emit(context, "auth:success", authState);
+      this.emit(context, "ready");
+    }
+  }
+
+  /**
+   * Extract and normalize rooms from auth data
+   */
+  private extractRooms(rooms?: Room[]): Room[] {
+    if (!rooms || !Array.isArray(rooms)) {
+      return [];
+    }
+    return rooms;
+  }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Handler for auth_required messages
+ * Server is requesting authentication
+ */
+
+import { AuthRequiredMessage, AuthRequiredMessageSchema } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class AuthRequiredHandler extends BaseMessageHandler<AuthRequiredMessage> {
+  readonly type = "auth_required" as const;
+  readonly schema = AuthRequiredMessageSchema;
+
+  protected async handleValidated(
+    _message: AuthRequiredMessage,
+    context: HandlerContext
+  ): Promise<void> {
+    context.logger.debug("Server requesting authentication");
+
+    // Emit auth:required event
+    this.emit(context, "auth:required");
+  }
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Handler for auth_success messages
+ * Legacy support for explicit auth_success message type
+ */
+
+import { z } from "zod";
+import { AuthSuccessMessage, AuthSuccessMessageSchema, Room } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class AuthSuccessHandler extends BaseMessageHandler<AuthSuccessMessage> {
+  readonly type = "auth_success" as const;
+  readonly schema = AuthSuccessMessageSchema as z.ZodSchema<AuthSuccessMessage>;
+
+  protected async handleValidated(
+    message: AuthSuccessMessage,
+    context: HandlerContext
+  ): Promise<void> {
+    context.logger.info("Authentication successful");
+
+    // Extract rooms
+    const rooms = this.extractRooms(message.data.rooms);
+
+    // Update connection state
+    this.updateConnectionState(context, { authenticated: true });
+
+    // Update auth state
+    this.updateAuthState(context, {
+      authenticated: true,
+      clientId: message.data.id,
+      walletAddress: message.data.address,
+      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
+    });
+
+    // Get updated auth state
+    const authState = context.getAuthState();
+
+    // Emit events
+    this.emit(context, "auth:success", authState);
+    this.emit(context, "ready");
+  }
+
+  /**
+   * Extract and normalize rooms from auth data
+   */
+  private extractRooms(rooms?: Room[]): Room[] {
+    if (!rooms || !Array.isArray(rooms)) {
+      return [];
+    }
+    return rooms;
+  }
+}

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

@@ -0,0 +1,101 @@
+/**
+ * Base abstract class for message handlers
+ * Implements the template method pattern for consistent message handling
+ */
+
+import { z } from "zod";
+import { BaseMessage, MessageType } from "../../types";
+import { MessageHandler, HandlerContext } from "./types";
+
+/**
+ * Abstract base class for message handlers
+ * Provides common functionality and enforces consistent structure
+ */
+export abstract class BaseMessageHandler<T extends BaseMessage = BaseMessage>
+  implements MessageHandler<T>
+{
+  // Subclasses must define these
+  abstract readonly type: MessageType;
+  abstract readonly schema: z.ZodSchema<T>;
+
+  /**
+   * Check if this handler can handle the given message
+   */
+  public canHandle(message: BaseMessage): boolean {
+    return message.type === this.type;
+  }
+
+  /**
+   * Main handle method - implements template method pattern
+   * 1. Validates message
+   * 2. Calls handleValidated (implemented by subclasses)
+   * 3. Handles errors
+   */
+  public async handle(message: BaseMessage, context: HandlerContext): Promise<void> {
+    try {
+      // Validate message with Zod schema
+      const validated = this.validate(message);
+
+      // Call subclass implementation
+      await this.handleValidated(validated, context);
+    } catch (error) {
+      context.logger.error(`Error handling ${this.type} message`, error);
+      this.onError(error, message, context);
+    }
+  }
+
+  /**
+   * Validate message against schema
+   */
+  protected validate(message: BaseMessage): T {
+    const result = this.schema.safeParse(message);
+    if (!result.success) {
+      throw new Error(`Invalid ${this.type} message: ${result.error.message}`);
+    }
+    return result.data;
+  }
+
+  /**
+   * Handle validated message - implemented by subclasses
+   */
+  protected abstract handleValidated(message: T, context: HandlerContext): Promise<void> | void;
+
+  /**
+   * Handle errors - can be overridden by subclasses
+   */
+  protected onError(error: unknown, message: BaseMessage, context: HandlerContext): void {
+    // Default: emit error event
+    context.emit("message:error", error, message);
+  }
+
+  /**
+   * Helper: emit event
+   */
+  protected emit(context: HandlerContext, event: string, ...args: any[]): void {
+    context.emit(event, ...args);
+  }
+
+  /**
+   * Helper: send webhook (fire-and-forget pattern)
+   */
+  protected sendWebhook(context: HandlerContext, type: string, data: any, metadata?: any): void {
+    // Fire and forget - don't block event emission
+    context.sendWebhook(type as any, data, metadata).catch((error) => {
+      context.logger.error(`Failed to send webhook for ${this.type}`, error);
+    });
+  }
+
+  /**
+   * Helper: update connection state
+   */
+  protected updateConnectionState(context: HandlerContext, update: any): void {
+    context.updateConnectionState(update);
+  }
+
+  /**
+   * Helper: update auth state
+   */
+  protected updateAuthState(context: HandlerContext, update: any): void {
+    context.updateAuthState(update);
+  }
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Handler for challenge messages
+ * Handles authentication challenge-response flow
+ */
+
+import { ChallengeMessage, ChallengeMessageSchema, createAuth } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class ChallengeHandler extends BaseMessageHandler<ChallengeMessage> {
+  readonly type = "challenge" as const;
+  readonly schema = ChallengeMessageSchema;
+  private clientType: "user" | "agent" | "coordinator";
+
+  constructor(clientType: "user" | "agent" | "coordinator" = "user") {
+    super();
+    this.clientType = clientType;
+  }
+
+  protected async handleValidated(
+    message: ChallengeMessage,
+    context: HandlerContext
+  ): Promise<void> {
+    if (!context.account) {
+      context.logger.error("Received challenge but no account configured");
+      return;
+    }
+
+    const challenge = message.data.challenge;
+    context.logger.debug("Received authentication challenge");
+
+    // Update auth state with challenge
+    this.updateAuthState(context, {
+      challenge,
+      challengeTimestamp: message.data.timestamp
+    });
+
+    // Emit challenge event
+    this.emit(context, "auth:challenge", challenge);
+
+    try {
+      // Sign challenge
+      const messageToSign = `Teneo authentication challenge: ${challenge}`;
+      const signature = await context.account.signMessage({
+        message: messageToSign
+      });
+
+      // Send authentication
+      await context.sendMessage(
+        createAuth(context.account.address, signature, messageToSign, this.clientType)
+      );
+    } catch (error) {
+      context.logger.error("Failed to sign challenge", error);
+      this.emit(context, "auth:error", "Failed to sign challenge");
+    }
+  }
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Handler for error messages
+ * Processes error messages from the server
+ */
+
+import { ErrorMessage, ErrorMessageSchema } from "../../types";
+import { MessageError } from "../../types/events";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class ErrorMessageHandler extends BaseMessageHandler<ErrorMessage> {
+  readonly type = "error" as const;
+  readonly schema = ErrorMessageSchema;
+
+  protected async handleValidated(message: ErrorMessage, context: HandlerContext): Promise<void> {
+    context.logger.error("Received error message from server", {
+      code: message.data.code,
+      message: message.data.message
+    });
+
+    // Create error object
+    const error = new MessageError(message.content || message.data.message, message.data);
+
+    // Emit error event
+    this.emit(context, "error", error);
+  }
+}