@teneo-protocol/sdk 2.2.1 → 3.0.0

package/dist/teneo-sdk.js

@@ -4,6 +4,39 @@
  * Provides a unified interface for external platforms to interact with Teneo agents
  * Uses manager classes to follow Single Responsibility Principle
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TeneoSDK = exports.AgentCommandSchema = exports.SendMessageOptionsSchema = void 0;
 const eventemitter3_1 = require("eventemitter3");
@@ -19,6 +52,7 @@ const managers_1 = require("./managers");
 const logger_1 = require("./utils/logger");
 const validation_1 = require("./types/validation");
 const secure_private_key_1 = require("./utils/secure-private-key");
+const payments_1 = require("./payments");
 // Zod schemas for SDK-specific interfaces
 exports.SendMessageOptionsSchema = zod_1.z.object({
     room: validation_1.RoomIdSchema.optional(),
@@ -58,7 +92,7 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      * @param config.wsUrl - WebSocket URL to connect to (e.g., 'wss://teneo.example.com')
      * @param config.privateKey - Optional Ethereum private key for wallet-based authentication
      * @param config.walletAddress - Optional wallet address (derived from privateKey if not provided)
-     * @param config.autoJoinRooms - Optional array of room IDs to subscribe to automatically on connection
+     * @param config.autoJoinPublicRooms - Optional array of public room IDs to subscribe to automatically on connection (private rooms are auto-available)
      * @param config.webhookUrl - Optional webhook URL for receiving event notifications
      * @param config.reconnect - Enable automatic reconnection (default: true)
      * @param config.logLevel - Logging level: 'debug', 'info', 'warn', 'error', 'silent' (default: 'info')
@@ -78,7 +112,7 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      * const sdk = new TeneoSDK({
      *   wsUrl: 'wss://teneo.example.com',
      *   privateKey: '0x...',
-     *   autoJoinRooms: ['general', 'announcements'],
+     *   autoJoinPublicRooms: ['public-room-1', 'public-room-2'], // Public rooms only
      *   webhookUrl: 'https://api.example.com/webhooks',
      *   logLevel: 'debug',
      *   responseFormat: 'both',
@@ -87,11 +121,12 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      * });
      *
      * // Using builder pattern (recommended for complex configs)
-     * const sdk = TeneoSDK.builder()
-     *   .wsUrl('wss://teneo.example.com')
-     *   .privateKey('0x...')
-     *   .withAutoJoinRooms(['general'])
+     * const config = TeneoSDK.builder()
+     *   .withWebSocketUrl('wss://teneo.example.com')
+     *   .withAuthentication('0x...')
+     *   .withAutoJoinPublicRooms(['public-room-1', 'public-room-2'])
      *   .build();
+     * const sdk = new TeneoSDK(config);
      * ```
      *
      * @see {@link SDKConfigBuilder} for fluent configuration API
@@ -145,16 +180,10 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
                 quoteTimeout: this.config.quoteTimeout,
                 wsUrl: this.config.wsUrl,
                 paymentNetwork: this.config.paymentNetwork,
-                paymentAsset: this.config.paymentAsset
+                paymentAsset: this.config.paymentAsset,
+                network: this.config.network // Network name from withNetwork()
             });
-            // Set up payment client if private key is configured (v2.2.0)
-            if (this.config.privateKey) {
-                const secureKey = this.config.privateKey instanceof secure_private_key_1.SecurePrivateKey
-                    ? this.config.privateKey
-                    : new secure_private_key_1.SecurePrivateKey(this.config.privateKey);
-                const walletAddress = this.config.walletAddress || this.deriveWalletAddress(this.config.privateKey);
-                this.messages.setPaymentClient(secureKey, walletAddress);
-            }
+            // NOTE: Payment client is set up in connect() after networks are initialized
             // Set up event forwarding
             this.setupEventForwarding();
             this.logger.info("TeneoSDK initialized", { wsUrl: this.config.wsUrl });
@@ -189,11 +218,27 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
         }
         try {
             this.logger.info("Connecting to Teneo Protocol");
+            // Initialize network configurations from backend before connecting
+            (0, payments_1.setNetworkConfigUrl)(this.config.wsUrl);
+            await (0, payments_1.initializeNetworks)();
+            // Verify networks are fully loaded before payment setup
+            const { NETWORKS } = await Promise.resolve().then(() => __importStar(require("./payments/networks")));
+            if (Object.keys(NETWORKS).length === 0) {
+                throw new events_1.SDKError("Failed to initialize networks from backend", error_codes_1.ErrorCode.CONFIG_ERROR, null, true);
+            }
+            // Set up payment client now that networks are initialized (v2.2.0)
+            if (this.config.privateKey) {
+                const secureKey = this.config.privateKey instanceof secure_private_key_1.SecurePrivateKey
+                    ? this.config.privateKey
+                    : new secure_private_key_1.SecurePrivateKey(this.config.privateKey);
+                const walletAddress = this.config.walletAddress || this.deriveWalletAddress(this.config.privateKey);
+                this.messages.setPaymentClient(secureKey, walletAddress);
+            }
             await this.connection.connect();
-            // Auto-join rooms if configured
-            if (this.config.autoJoinRooms && this.config.autoJoinRooms.length > 0) {
-                for (const room of this.config.autoJoinRooms) {
-                    await this.rooms.subscribeToRoom(room);
+            // Auto-join public rooms if configured
+            if (this.config.autoJoinPublicRooms && this.config.autoJoinPublicRooms.length > 0) {
+                for (const room of this.config.autoJoinPublicRooms) {
+                    await this.rooms.subscribeToPublicRoom(room);
                 }
             }
             this.logger.info("Successfully connected to Teneo Protocol");
@@ -260,7 +305,9 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      * @param command.agent - The agent ID or name to send the command to
      * @param command.command - The command text to send to the agent
      * @param command.room - Room to send command to (defaults to configured default room)
-     * @returns Promise that resolves when the command is sent
+     * @param command.network - Optional per-request network override (e.g., "base", "avalanche", or chain ID 8453)
+     * @param waitForResponse - Whether to wait for the agent's response (default: false)
+     * @returns Promise resolving to FormattedResponse if waitForResponse is true, void otherwise
      * @throws {SDKError} If not connected to the network (ErrorCode.NOT_CONNECTED)
      * @throws {ValidationError} If agent or command are empty, or room is not configured
      *
@@ -270,8 +317,16 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      * await sdk.sendDirectCommand({
      *   agent: 'weather-agent',
      *   command: 'Get forecast for New York',
-     *   room: 'general'
+     *   room: 'room-id'
      * });
+     *
+     * // With per-request network override
+     * const response = await sdk.sendDirectCommand({
+     *   agent: 'x-agent-enterprise-v2',
+     *   command: 'user @elonmusk',
+     *   room: 'room-id',
+     *   network: 'base'  // Pay on Base for this request
+     * }, true);
      * ```
      */
     async sendDirectCommand(command, waitForResponse = false) {
@@ -282,8 +337,8 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      * The quote includes agent selection, pricing, and expiration.
      * Does NOT auto-approve - use confirmQuote() to execute.
      */
-    async requestQuote(content, room) {
-        return this.messages.requestQuote(content, room);
+    async requestQuote(content, room, networkOverride) {
+        return this.messages.requestQuote(content, room, networkOverride);
     }
     /**
      * Confirms a pending quote and executes the task with payment.
@@ -311,14 +366,26 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      * @example
      * ```typescript
      * // Subscribe to a public room
-     * await sdk.subscribeToRoom('public-announcements');
+     * await sdk.subscribeToPublicRoom('public-room-id');
      * console.log('Subscribed to public room');
      *
      * // Note: Private rooms don't need subscription - you're always subscribed
      * ```
      */
+    async subscribeToPublicRoom(roomId) {
+        return this.rooms.subscribeToPublicRoom(roomId);
+    }
+    /**
+     * @deprecated Use subscribeToPublicRoom() instead. This method only affects public rooms.
+     * Private rooms are automatically available after authentication without subscription.
+     *
+     * Subscribes to a public room in the Teneo Protocol.
+     *
+     * @param roomId - The ID of the public room to subscribe to
+     * @returns Promise that resolves when the room has been subscribed
+     */
     async subscribeToRoom(roomId) {
-        return this.rooms.subscribeToRoom(roomId);
+        return this.subscribeToPublicRoom(roomId);
     }
     /**
      * Unsubscribes from a public room in the Teneo Protocol.
@@ -334,12 +401,24 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      *
      * @example
      * ```typescript
-     * await sdk.unsubscribeFromRoom('public-announcements');
+     * await sdk.unsubscribeFromPublicRoom('public-room-id');
      * console.log('Unsubscribed from public room');
      * ```
      */
+    async unsubscribeFromPublicRoom(roomId) {
+        return this.rooms.unsubscribeFromPublicRoom(roomId);
+    }
+    /**
+     * @deprecated Use unsubscribeFromPublicRoom() instead. This method only affects public rooms.
+     * Private rooms cannot be unsubscribed from.
+     *
+     * Unsubscribes from a public room in the Teneo Protocol.
+     *
+     * @param roomId - The ID of the public room to unsubscribe from
+     * @returns Promise that resolves when the room has been unsubscribed
+     */
     async unsubscribeFromRoom(roomId) {
-        return this.rooms.unsubscribeFromRoom(roomId);
+        return this.unsubscribeFromPublicRoom(roomId);
     }
     /**
      * Lists all rooms available to the user.
@@ -371,7 +450,7 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      * ```typescript
      * const rooms = sdk.getSubscribedRooms();
      * console.log(`Subscribed to ${rooms.length} rooms:`, rooms);
-     * // Example output: Subscribed to 3 rooms: ['general', 'support', 'trading']
+     * // Example output: Subscribed to 3 rooms: ['room-id-1', 'room-id-2', 'room-id-3']
      * ```
      */
     getSubscribedRooms() {
@@ -418,18 +497,18 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
         return this.agents.getAgent(agentId);
     }
     /**
-     * Finds all agents that have a specific capability using O(1) indexed lookup (PERF-3).
+     * Finds all available agents (network-wide) that have a specific capability using O(1) indexed lookup (PERF-3).
      * Much faster than filtering through all agents manually.
      * Uses capability index for constant-time lookups regardless of agent count.
      *
      * @param capability - The capability name to search for (case-insensitive)
-     * @returns Read-only array of agents with the specified capability
+     * @returns Read-only array of available agents with the specified capability
      * @throws {ValidationError} If capability name is invalid
      *
      * @example
      * ```typescript
-     * // Find all weather-capable agents
-     * const weatherAgents = sdk.findAgentsByCapability('weather-forecast');
+     * // Find all weather-capable agents available on the network
+     * const weatherAgents = sdk.findAvailableAgentsByCapability('weather-forecast');
      * console.log(`Found ${weatherAgents.length} weather agents`);
      *
      * weatherAgents.forEach(agent => {
@@ -437,51 +516,84 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      * });
      * ```
      */
-    findAgentsByCapability(capability) {
+    findAvailableAgentsByCapability(capability) {
         return this.agents.findByCapability(capability);
     }
     /**
-     * Finds agents by name using O(k) token-based search (PERF-3).
+     * @deprecated Use findAvailableAgentsByCapability() instead. This searches all available agents network-wide.
+     *
+     * Finds all agents that have a specific capability.
+     *
+     * @param capability - The capability name to search for
+     * @returns Read-only array of agents with the specified capability
+     */
+    findAgentsByCapability(capability) {
+        return this.findAvailableAgentsByCapability(capability);
+    }
+    /**
+     * Finds available agents (network-wide) by name using O(k) token-based search (PERF-3).
      * Supports partial matching - searches for tokens within agent names.
      * Tokenizes both the search query and agent names for flexible matching.
      *
      * @param name - Name or partial name to search for (case-insensitive)
-     * @returns Read-only array of agents matching the search
+     * @returns Read-only array of available agents matching the search
      * @throws {ValidationError} If name is invalid
      *
      * @example
      * ```typescript
-     * // Find all agents with "weather" in their name
-     * const agents = sdk.findAgentsByName('weather');
+     * // Find all available agents with "weather" in their name
+     * const agents = sdk.findAvailableAgentsByName('weather');
      * // Matches: "Weather Agent", "Weather Forecast Bot", "Advanced Weather API", etc.
      *
      * console.log(`Found ${agents.length} agents matching 'weather'`);
      * ```
      */
-    findAgentsByName(name) {
+    findAvailableAgentsByName(name) {
         return this.agents.findByName(name);
     }
     /**
-     * Finds all agents with a specific status using O(1) indexed lookup (PERF-3).
+     * @deprecated Use findAvailableAgentsByName() instead. This searches all available agents network-wide.
+     *
+     * Finds agents by name.
+     *
+     * @param name - Name or partial name to search for
+     * @returns Read-only array of agents matching the search
+     */
+    findAgentsByName(name) {
+        return this.findAvailableAgentsByName(name);
+    }
+    /**
+     * Finds all available agents (network-wide) with a specific status using O(1) indexed lookup (PERF-3).
      * Uses status index for constant-time lookups regardless of agent count.
      *
      * @param status - Agent status: 'online' or 'offline' (case-insensitive)
-     * @returns Read-only array of agents with the specified status
+     * @returns Read-only array of available agents with the specified status
      * @throws {ValidationError} If status is invalid
      *
      * @example
      * ```typescript
-     * // Get all online agents
-     * const onlineAgents = sdk.findAgentsByStatus('online');
+     * // Get all online agents available on the network
+     * const onlineAgents = sdk.findAvailableAgentsByStatus('online');
      * console.log(`${onlineAgents.length} agents are currently online`);
      *
      * // Get offline agents
-     * const offlineAgents = sdk.findAgentsByStatus('offline');
+     * const offlineAgents = sdk.findAvailableAgentsByStatus('offline');
      * ```
      */
-    findAgentsByStatus(status) {
+    findAvailableAgentsByStatus(status) {
         return this.agents.findByStatus(status);
     }
+    /**
+     * @deprecated Use findAvailableAgentsByStatus() instead. This searches all available agents network-wide.
+     *
+     * Finds all agents with a specific status.
+     *
+     * @param status - Agent status: 'online' or 'offline'
+     * @returns Read-only array of agents with the specified status
+     */
+    findAgentsByStatus(status) {
+        return this.findAvailableAgentsByStatus(status);
+    }
     /**
      * Fetches detailed information about a specific agent from the server.
      * Makes a request to the server for full agent details including capabilities,
@@ -572,7 +684,15 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      * ```
      */
     getRooms() {
-        return this.rooms.getRooms();
+        const managerRooms = this.rooms.getRooms();
+        // Fall back to auth state if RoomManager hasn't been updated yet (race condition after connect)
+        if (managerRooms.length === 0) {
+            const authState = this.connection.getAuthState();
+            if (authState.roomObjects && authState.roomObjects.length > 0) {
+                return authState.roomObjects;
+            }
+        }
+        return managerRooms;
     }
     /**
      * Gets a specific room by its unique ID.
@@ -583,7 +703,7 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      *
      * @example
      * ```typescript
-     * const room = sdk.getRoom('general');
+     * const room = sdk.getRoom('room-id');
      * if (room) {
      *   console.log(`Found room: ${room.name}`);
      *   console.log(`Members: ${room.members?.length ?? 0}`);
@@ -593,7 +713,13 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      * ```
      */
     getRoom(roomId) {
-        return this.rooms.getRoom(roomId);
+        const room = this.rooms.getRoom(roomId);
+        // Fall back to auth state if RoomManager hasn't been updated yet (race condition after connect)
+        if (!room) {
+            const authState = this.connection.getAuthState();
+            return authState.roomObjects?.find((r) => r.id === roomId);
+        }
+        return room;
     }
     // ============================================================================
     // ROOM MANAGEMENT API (v2.0.0)
@@ -829,26 +955,9 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
     async listRoomAgents(roomId, useCache = true) {
         return this.agentRoom.listRoomAgents(roomId, useCache);
     }
-    /**
-     * Lists all agents available to be added to a room.
-     * Shows agents not currently in the room.
-     * Results are cached for 5 minutes for performance.
-     * Emits 'agent_room:available_agents_listed' when list is received.
-     *
-     * @param roomId - ID of the room to check available agents for
-     * @param useCache - Whether to use cached data if available (default: true)
-     * @returns Promise that resolves to array of available agents
-     * @throws {SDKError} If not connected
-     *
-     * @example
-     * ```typescript
-     * const available = await sdk.listAvailableAgents('room-123');
-     * console.log(`${available.length} agents available to add`);
-     * ```
-     */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    async listAvailableAgents(roomId, useCache = true) {
-        return this.agentRoom.listAvailableAgents(roomId, useCache);
+    async listAvailableAgents(roomId, useCacheOrOptions) {
+        return this.agentRoom.listAvailableAgents(roomId, useCacheOrOptions);
     }
     /**
      * Gets agents in a room from cache (synchronous).
@@ -859,7 +968,7 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      *
      * @example
      * ```typescript
-     * const agents = sdk.getRoomAgents('room-123');
+     * const agents = sdk.getCachedRoomAgents('room-123');
      * if (agents) {
      *   console.log(`${agents.length} agents (cached)`);
      * } else {
@@ -868,8 +977,21 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      * ```
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getCachedRoomAgents(roomId) {
+        return this.agentRoom.getCachedRoomAgents(roomId);
+    }
+    /**
+     * @deprecated Use getCachedRoomAgents() instead. This method returns cached data only.
+     * Use listRoomAgents() to fetch fresh data from server.
+     *
+     * Gets agents in a room from cache (synchronous).
+     *
+     * @param roomId - ID of the room
+     * @returns Array of agents if cached, undefined otherwise
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     getRoomAgents(roomId) {
-        return this.agentRoom.getRoomAgents(roomId);
+        return this.getCachedRoomAgents(roomId);
     }
     /**
      * Gets available agents for a room from cache (synchronous).
@@ -880,15 +1002,28 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      *
      * @example
      * ```typescript
-     * const available = sdk.getAvailableAgents('room-123');
+     * const available = sdk.getCachedAvailableAgents('room-123');
      * if (available) {
      *   console.log(`${available.length} agents available (cached)`);
      * }
      * ```
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getCachedAvailableAgents(roomId) {
+        return this.agentRoom.getCachedAvailableAgents(roomId);
+    }
+    /**
+     * @deprecated Use getCachedAvailableAgents() instead. This method returns cached data only.
+     * Use listAvailableAgents() to fetch fresh data from server.
+     *
+     * Gets available agents for a room from cache (synchronous).
+     *
+     * @param roomId - ID of the room
+     * @returns Array of available agents if cached, undefined otherwise
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     getAvailableAgents(roomId) {
-        return this.agentRoom.getAvailableAgents(roomId);
+        return this.getCachedAvailableAgents(roomId);
     }
     /**
      * Checks if an agent is in a room (synchronous, from cache).
@@ -900,18 +1035,31 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      *
      * @example
      * ```typescript
-     * const inRoom = sdk.isAgentInRoom('room-123', 'weather-agent');
+     * const inRoom = sdk.checkAgentInRoom('room-123', 'weather-agent');
      * if (inRoom === true) {
      *   console.log('Agent is in room');
      * } else if (inRoom === false) {
      *   console.log('Agent is not in room');
      * } else {
-     *   console.log('Room data not cached');
+     *   console.log('Room data not cached - need to fetch');
      * }
      * ```
      */
+    checkAgentInRoom(roomId, agentId) {
+        return this.agentRoom.checkAgentInRoom(roomId, agentId);
+    }
+    /**
+     * @deprecated Use checkAgentInRoom() instead. The 'is*' naming convention implies boolean-only,
+     * but this method returns boolean | undefined to indicate cache validity.
+     *
+     * Checks if an agent is in a room (synchronous, from cache).
+     *
+     * @param roomId - ID of the room
+     * @param agentId - ID of the agent
+     * @returns True if agent is in room, false if not, undefined if not cached
+     */
     isAgentInRoom(roomId, agentId) {
-        return this.agentRoom.isAgentInRoom(roomId, agentId);
+        return this.checkAgentInRoom(roomId, agentId);
     }
     /**
      * Gets the count of agents in a room (synchronous, from cache).
@@ -922,14 +1070,26 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      *
      * @example
      * ```typescript
-     * const count = sdk.getRoomAgentCount('room-123');
+     * const count = sdk.getCachedRoomAgentCount('room-123');
      * if (count !== undefined) {
      *   console.log(`Room has ${count} agents`);
      * }
      * ```
      */
+    getCachedRoomAgentCount(roomId) {
+        return this.agentRoom.getCachedRoomAgentCount(roomId);
+    }
+    /**
+     * @deprecated Use getCachedRoomAgentCount() instead. This method returns cached data only.
+     * Use listRoomAgents() to fetch fresh data from server.
+     *
+     * Gets the count of agents in a room (synchronous, from cache).
+     *
+     * @param roomId - ID of the room
+     * @returns Number of agents in room, or undefined if not cached
+     */
     getRoomAgentCount(roomId) {
-        return this.agentRoom.getRoomAgentCount(roomId);
+        return this.getCachedRoomAgentCount(roomId);
     }
     /**
      * Invalidates the agent-room cache for a specific room.
@@ -1007,6 +1167,109 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
             });
         });
     }
+    /**
+     * Sends the result of an on-chain transaction back to the server.
+     * Used in response to a "wallet:tx_requested" event after the user
+     * has confirmed, rejected, or encountered a failure with the transaction.
+     *
+     * @param taskId - The task ID from the wallet:tx_requested event
+     * @param status - Transaction result: "confirmed", "rejected", or "failed"
+     * @param txHash - The on-chain transaction hash (required for "confirmed" status)
+     * @param error - Error message (optional, for "failed" status)
+     * @throws {SDKError} If the SDK has been destroyed or not connected
+     *
+     * @example
+     * ```typescript
+     * sdk.on("wallet:tx_requested", async (data) => {
+     *   try {
+     *     const txHash = await wallet.sendTransaction(data.tx);
+     *     await sdk.sendTxResult(data.taskId, "confirmed", txHash);
+     *   } catch (err) {
+     *     await sdk.sendTxResult(data.taskId, "failed", undefined, err.message);
+     *   }
+     * });
+     * ```
+     */
+    async sendTxResult(taskId, status, txHash, error) {
+        if (this.isDestroyed) {
+            throw new events_1.SDKError("SDK has been destroyed", error_codes_1.ErrorCode.SDK_DESTROYED, null, false);
+        }
+        if (!this.wsClient.isConnected) {
+            throw new events_1.SDKError("Not connected to Teneo Protocol", error_codes_1.ErrorCode.NOT_CONNECTED);
+        }
+        const message = {
+            type: "tx_result",
+            data: {
+                task_id: taskId,
+                status,
+                ...(txHash && { tx_hash: txHash }),
+                ...(error && { error })
+            }
+        };
+        await this.wsClient.sendMessage(message);
+    }
+    /**
+     * Sets the API key preference for the current user.
+     * Controls whether custom API keys are used for agent interactions.
+     *
+     * @param useCustomKeys - Whether to use custom API keys
+     * @throws {SDKError} If the SDK has been destroyed or not connected
+     *
+     * @example
+     * ```typescript
+     * // Enable custom API keys
+     * await sdk.setApiKeyPreference(true);
+     *
+     * // Disable custom API keys
+     * await sdk.setApiKeyPreference(false);
+     * ```
+     */
+    async setApiKeyPreference(useCustomKeys) {
+        if (this.isDestroyed) {
+            throw new events_1.SDKError("SDK has been destroyed", error_codes_1.ErrorCode.SDK_DESTROYED, null, false);
+        }
+        if (!this.wsClient.isConnected) {
+            throw new events_1.SDKError("Not connected to Teneo Protocol", error_codes_1.ErrorCode.NOT_CONNECTED);
+        }
+        const message = {
+            type: "set_api_key_preference",
+            data: {
+                use_custom_keys: useCustomKeys
+            }
+        };
+        await this.wsClient.sendMessage(message);
+    }
+    /**
+     * Send a room ping to get live user count
+     * Server responds with room_pong message containing current live user count
+     *
+     * @param roomId - The room ID to ping
+     * @throws {SDKError} If not connected or SDK is destroyed
+     *
+     * @example
+     * ```typescript
+     * // Ping a room to get live user count
+     * await sdk.sendRoomPing("my-room");
+     *
+     * // Listen for the response
+     * sdk.on("room:pong", (data) => {
+     *   console.log(`Room ${data.roomId} has ${data.liveCount} live users`);
+     * });
+     * ```
+     */
+    async sendRoomPing(roomId) {
+        if (this.isDestroyed) {
+            throw new events_1.SDKError("SDK has been destroyed", error_codes_1.ErrorCode.SDK_DESTROYED, null, false);
+        }
+        if (!this.wsClient.isConnected) {
+            throw new events_1.SDKError("Not connected to Teneo Protocol", error_codes_1.ErrorCode.NOT_CONNECTED);
+        }
+        const message = {
+            type: "room_ping",
+            room_id: roomId
+        };
+        await this.wsClient.sendMessage(message);
+    }
     /**
      * Configures webhook URL and headers for receiving real-time event notifications.
      * Webhooks allow you to receive events at your server endpoint via HTTP POST requests.
@@ -1390,8 +1653,8 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
         this._admin.destroy();
         // Destroy other components
         this.webhookHandler.destroy();
-        this.removeAllListeners();
         this.emit("destroy");
+        this.removeAllListeners();
     }
     /**
      * Set up event forwarding from managers
@@ -1454,7 +1717,34 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
         // Handle agent list updates from WebSocketClient
         this.wsClient.on("agent:list", (agents) => {
             this.agents.updateAgents(agents);
+            this.emit("agent:list", agents);
+        });
+        // Forward task confirmed events from WebSocketClient (emitted by handlers)
+        this.wsClient.on("task:confirmed", (data) => {
+            this.emit("task:confirmed", data);
+        });
+        // Forward agent error events from WebSocketClient (emitted by handlers)
+        this.wsClient.on("agent:error", (data) => {
+            this.emit("agent:error", data);
+        });
+        // Forward wallet transaction events from WebSocketClient (emitted by handlers)
+        this.wsClient.on("wallet:tx_requested", (data) => {
+            this.emit("wallet:tx_requested", data);
+        });
+        // Forward room pong events from WebSocketClient (emitted by pong handler)
+        this.wsClient.on("room:pong", (data) => {
+            this.emit("room:pong", data);
+        });
+        // Forward success events from WebSocketClient (emitted by handlers)
+        this.wsClient.on("success", (message) => {
+            this.emit("success", message);
         });
+        // Forward message deduplication events from WebSocketClient
+        this.wsClient.on("message:duplicate", (message) => this.emit("message:duplicate", message));
+        // Forward signature verification events from WebSocketClient
+        this.wsClient.on("signature:verified", (messageType, address) => this.emit("signature:verified", messageType, address));
+        this.wsClient.on("signature:failed", (messageType, reason, address) => this.emit("signature:failed", messageType, reason, address));
+        this.wsClient.on("signature:missing", (messageType, required) => this.emit("signature:missing", messageType, required));
         // 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));
@@ -1524,11 +1814,11 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
             // Emit on SDK for external listeners
             this.emit("agent_room:agents_listed", roomId, agents);
         });
-        this.wsClient.on("agent_room:available_agents_listed", (agents) => {
+        this.wsClient.on("agent_room:available_agents_listed", (agents, paginationMeta) => {
             // Emit on AgentRoomManager for promise resolution
-            this.agentRoom.emit("agent_room:available_agents_listed", agents);
+            this.agentRoom.emit("agent_room:available_agents_listed", agents, paginationMeta);
             // Emit on SDK for external listeners
-            this.emit("agent_room:available_agents_listed", agents);
+            this.emit("agent_room:available_agents_listed", agents, paginationMeta);
         });
         this.wsClient.on("agent_room:status_update", (data) => {
             // Emit on SDK for external listeners
@@ -1620,13 +1910,14 @@ class TeneoSDK extends eventemitter3_1.EventEmitter {
      *
      * @example
      * ```typescript
-     * const sdk = TeneoSDK.builder()
-     *   .wsUrl('wss://teneo.example.com')
-     *   .privateKey('0x...')
-     *   .withAutoJoinRooms(['general'])
-     *   .logLevel('debug')
-     *   .webhookUrl('https://api.example.com/webhooks')
+     * const config = TeneoSDK.builder()
+     *   .withWebSocketUrl('wss://teneo.example.com')
+     *   .withAuthentication('0x...')
+     *   .withAutoJoinPublicRooms(['public-room-1', 'public-room-2'])
+     *   .withLogging('debug')
+     *   .withWebhook('https://api.example.com/webhooks')
      *   .build();
+     * const sdk = new TeneoSDK(config);
      *
      * await sdk.connect();
      * ```