@teneo-protocol/sdk 1.0.0 → 2.0.0

package/examples/usage/README.md

@@ -0,0 +1,383 @@
+# Teneo SDK Usage Examples
+
+This directory contains progressive, hands-on examples demonstrating how to use the Teneo Consumer SDK. Each example builds on concepts from the previous ones, taking you from basic connection to building production-ready applications.
+
+## 📚 Examples Overview
+
+| # | Example | Description | Key Concepts |
+|---|---------|-------------|--------------|
+| 1 | [Connect](#1-basic-connection) | Basic WebSocket connection | Config builder, authentication, lifecycle |
+| 2 | [List Agents](#2-list-agents) | Retrieve available agents | Agent registry, properties, statistics |
+| 3 | [Pick Agent](#3-pick-specific-agent) | Direct agent communication | sendDirectCommand, response handling |
+| 4 | [Find by Capability](#4-find-by-capability) | Indexed agent search | O(1) lookups, capability matching |
+| 5 | [Webhooks](#5-webhook-integration) | HTTP event notifications | Webhook setup, retry logic, circuit breaker |
+| 6 | [API Server](#6-simple-api-server) | REST API wrapper | Express integration, endpoint design |
+| 7 | [Event Listener](#7-event-listener) | Event-driven patterns | 30+ events, real-time monitoring |
+
+## 🚀 Prerequisites
+
+Before running these examples, make sure you have:
+
+1. **Node.js 18+** installed
+2. **Built the SDK**: Run `npm run build` in the project root
+3. **Environment variables** set up (see below)
+
+## ⚙️ Environment Setup
+
+Create a `.env` file in the project root or export these variables:
+
+```bash
+# Required
+PRIVATE_KEY=your_ethereum_private_key_here
+WS_URL=wss://your-teneo-server.com/ws
+
+# Optional
+DEFAULT_ROOM=general
+WALLET_ADDRESS=0x...  # Auto-derived if not provided
+LOG_LEVEL=info
+```
+
+## 📖 Usage Examples
+
+### 1. Basic Connection
+
+**File**: `01-connect.ts`
+
+The simplest example - connect to Teneo and authenticate.
+
+```bash
+npx tsx examples/usage/01-connect.ts
+```
+
+**What you'll learn**:
+- Using `SDKConfigBuilder` for configuration
+- Connecting to the WebSocket server
+- Ethereum wallet authentication
+- Event listeners for connection lifecycle
+- Graceful disconnection and cleanup
+
+**Output**:
+```
+🚀 Example 1: Basic SDK Connection
+⚙️  Step 1: Building SDK configuration...
+✅ Configuration built
+...
+✅ Connected and authenticated!
+```
+
+---
+
+### 2. List Agents
+
+**File**: `02-list-agents.ts`
+
+Retrieve and inspect all available agents in the network.
+
+```bash
+npx tsx examples/usage/02-list-agents.ts
+```
+
+**What you'll learn**:
+- Getting the agent list
+- Inspecting agent properties (name, description, status)
+- Viewing agent capabilities and commands
+- Getting statistics (online/offline counts)
+
+**Output**:
+```
+📊 Agent Details:
+1. X Platform Agent
+   ID: x-agent-001
+   Status: online
+   Capabilities: social-media, twitter
+   ...
+```
+
+---
+
+### 3. Pick Specific Agent
+
+**File**: `03-pick-agent.ts`
+
+Find and communicate with a specific agent.
+
+```bash
+# Pick by name
+npx tsx examples/usage/03-pick-agent.ts "X Platform Agent"
+
+# Or let it auto-select
+npx tsx examples/usage/03-pick-agent.ts
+```
+
+**What you'll learn**:
+- Finding agents by ID or name
+- Sending direct commands to agents
+- Waiting for responses with timeout
+- Handling both humanized and raw responses
+- Response metadata (task ID, duration, etc.)
+
+**Output**:
+```
+✅ Selected: X Platform Agent
+⚙️  Sending command to agent...
+   Command: timeline @elonmusk 3
+   Waiting for response...
+✅ Response received!
+📝 Humanized Response: [response content]
+```
+
+---
+
+### 4. Find by Capability
+
+**File**: `04-find-by-capability.ts`
+
+Use the SDK's indexed search for efficient agent discovery.
+
+```bash
+npx tsx examples/usage/04-find-by-capability.ts
+```
+
+**What you'll learn**:
+- **PERF-3**: O(1) capability lookups
+- O(1) status lookups (online/offline)
+- O(k) name-based token search
+- Performance comparison
+- Practical agent selection strategies
+
+**Output**:
+```
+🔍 Searching for capability: "weather-forecast"
+✅ Found 2 agent(s) (0.123ms):
+   • Weather Agent
+   • Climate Data Agent
+
+📊 Performance Summary:
+   • Capability search: O(1) - constant time
+   • Status search: O(1) - constant time
+```
+
+---
+
+### 5. Webhook Integration
+
+**File**: `05-webhook-example.ts`
+
+Set up HTTP webhooks to receive SDK events.
+
+```bash
+npx tsx examples/usage/05-webhook-example.ts
+```
+
+**What you'll learn**:
+- Creating a local webhook receiver
+- Configuring SDK webhook delivery
+- Receiving webhook events
+- Automatic retry with exponential backoff
+- Circuit breaker pattern
+- Queue management
+
+**Output**:
+```
+✅ Webhook server running on http://localhost:3001
+🎯 Webhook received!
+   Event: agent:response
+   Timestamp: 2025-10-28T...
+```
+
+---
+
+### 6. Simple API Server
+
+**File**: `06-simple-api-server.ts`
+
+Build a REST API that wraps the Teneo SDK.
+
+```bash
+npx tsx examples/usage/06-simple-api-server.ts
+```
+
+Then test with curl:
+
+```bash
+# Health check
+curl http://localhost:3000/health
+
+# List agents
+curl http://localhost:3000/agents
+
+# Send message
+curl -X POST http://localhost:3000/message \
+  -H "Content-Type: application/json" \
+  -d '{"message":"hello","waitForResponse":true}'
+
+# Find by capability
+curl http://localhost:3000/agents/capability/weather-forecast
+```
+
+**What you'll learn**:
+- Building Express REST API
+- Wrapping SDK in HTTP endpoints
+- Error handling patterns
+- Health monitoring
+- Production-ready server design
+
+**Endpoints**:
+- `GET /health` - Server and SDK health
+- `GET /agents` - List all agents
+- `GET /agents/:id` - Get specific agent
+- `GET /agents/capability/:capability` - Find by capability
+- `POST /message` - Send message to agent
+- `GET /rooms` - List rooms
+- `POST /rooms/:roomId/subscribe` - Subscribe to room
+
+---
+
+### 7. Event Listener
+
+**File**: `07-event-listener.ts`
+
+Listen to all SDK events for real-time monitoring.
+
+```bash
+npx tsx examples/usage/07-event-listener.ts
+```
+
+**What you'll learn**:
+- All 30+ SDK event types
+- Event categorization (connection, auth, agent, message, etc.)
+- Real-time event monitoring
+- Event-driven architecture
+- Statistics and analytics
+
+**Output**:
+```
+🔌 [CONNECTION] WebSocket connection opened
+🔐 [AUTH] ✅ Authentication successful!
+🤖 [AGENT] Agent list updated: 5 agents
+📤 [MESSAGE] Message sent: Type: message
+...
+📊 EVENT STATISTICS
+Connection events:    12
+Authentication events: 4
+Agent events:         8
+```
+
+---
+
+## 🎯 Learning Path
+
+We recommend following this learning path:
+
+1. **Start with 01-connect.ts** to understand basic setup
+2. **Try 02-list-agents.ts** to explore the agent registry
+3. **Run 03-pick-agent.ts** to learn agent communication
+4. **Explore 04-find-by-capability.ts** for efficient search
+5. **Set up 05-webhook-example.ts** for event notifications
+6. **Build 06-simple-api-server.ts** for production patterns
+7. **Monitor with 07-event-listener.ts** for observability
+
+## 🔧 Common Patterns
+
+### Pattern 1: Basic Message Flow
+
+```typescript
+const sdk = new TeneoSDK(config);
+await sdk.connect();
+
+// Send and wait for response
+const response = await sdk.sendMessage('hello', {
+  room: 'general',
+  waitForResponse: true,
+  timeout: 30000
+});
+
+console.log(response.humanized);
+```
+
+### Pattern 2: Direct Agent Command
+
+```typescript
+// Find agent by capability
+const agents = sdk.findAgentsByCapability('weather');
+const weatherAgent = agents[0];
+
+// Send direct command
+const response = await sdk.sendDirectCommand({
+  agent: weatherAgent.id,
+  command: 'forecast for NYC',
+  room: 'general'
+}, true);
+```
+
+### Pattern 3: Event-Driven
+
+```typescript
+sdk.on('agent:response', (response) => {
+  console.log('Response:', response.humanized);
+  // Process response asynchronously
+});
+
+// Fire and forget
+await sdk.sendMessage('hello', { room: 'general' });
+```
+
+## 🐛 Troubleshooting
+
+### "PRIVATE_KEY is required"
+
+Set the environment variable:
+```bash
+export PRIVATE_KEY=your_private_key_here
+```
+
+### "No agents available"
+
+Wait a bit longer after connecting:
+```typescript
+await sdk.connect();
+await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2s
+```
+
+### "Webhook delivery failed"
+
+Ensure your webhook URL is accessible:
+- Use `http://localhost:PORT` for local testing
+- Use HTTPS for production webhooks
+- Check firewall settings
+
+### "Connection timeout"
+
+Check your WebSocket URL and network:
+```typescript
+const config = new SDKConfigBuilder()
+  .withWebSocketUrl('wss://correct-url.com/ws')
+  .withReconnection({ enabled: true, maxAttempts: 10 })
+  .build();
+```
+
+## 📚 Next Steps
+
+After completing these examples, check out:
+
+- **[Integration Examples](../INTEGRATION_EXAMPLES.md)** - Claude, OpenAI, n8n integrations
+- **[Production Dashboard](../production-dashboard/)** - Full-featured monitoring UI
+- **[API Documentation](../../docs/)** - Complete API reference
+- **[Main README](../../README.md)** - Full SDK documentation
+
+## 💡 Tips
+
+1. **Always build the SDK first**: Run `npm run build` before running examples
+2. **Use environment variables**: Don't hardcode credentials
+3. **Enable debug logging**: Set `LOG_LEVEL=debug` for troubleshooting
+4. **Check health status**: Use `sdk.getHealth()` to monitor SDK state
+5. **Handle errors**: Always use try-catch blocks in production code
+
+## 🤝 Contributing
+
+Found an issue or want to add an example? Please open an issue or PR!
+
+## 📄 License
+
+MIT - See [LICENSE](../../LICENSE) for details
+

package/examples/usage/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@teneo/usage-examples",
+  "version": "1.0.0",
+  "description": "Step-by-step usage examples for Teneo Protocol SDK",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "01:connect": "tsx 01-connect.ts",
+    "02:list-agents": "tsx 02-list-agents.ts",
+    "03:pick-agent": "tsx 03-pick-agent.ts",
+    "04:find-by-capability": "tsx 04-find-by-capability.ts",
+    "05:webhook": "tsx 05-webhook-example.ts",
+    "06:api-server": "tsx 06-simple-api-server.ts",
+    "07:event-listener": "tsx 07-event-listener.ts",
+    "all": "npm run 01:connect && npm run 02:list-agents && npm run 03:pick-agent && npm run 04:find-by-capability"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.0",
+    "express": "^4.18.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.5",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "teneo",
+    "sdk",
+    "examples",
+    "usage",
+    "tutorial",
+    "websocket",
+    "ai",
+    "agents"
+  ],
+  "author": "Teneo Protocol",
+  "license": "MIT"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teneo-protocol/sdk",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "TypeScript SDK for external platforms to interact with Teneo agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,9 +15,16 @@
   ],
   "author": "Teneo Protocol",
   "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TeneoProtocolAI/teneo-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TeneoProtocolAI/teneo-sdk/issues"
+  },
+  "homepage": "https://github.com/TeneoProtocolAI/teneo-sdk#readme",
   "dependencies": {
     "eventemitter3": "^5.0.1",
-    "hono": "^4.9.12",
     "node-fetch": "^3.3.2",
     "pino": "^8.17.2",
     "uuid": "^9.0.1",
@@ -60,6 +67,9 @@
     "lint:fix": "eslint . --ext .ts --fix",
     "format": "prettier --write \"src/**/*.ts\"",
     "example:battle": "ts-node examples/x-influencer-battle-server.ts",
-    "example:dashboard": "cd examples/production-dashboard && bun run server.ts"
+    "example:dashboard": "cd examples/production-dashboard && bun run server.ts",
+    "example:claude": "tsx examples/claude-agent-x-follower/index.ts",
+    "example:openai": "cd examples/openai-teneo && tsx index.ts",
+    "example:n8n": "cd examples/n8n-teneo && tsx index.ts"
   }
 }

package/src/core/websocket-client.ts

@@ -56,6 +56,9 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
   private deduplicationCache?: DeduplicationCache;
   private reconnectPolicy: RetryPolicy;
   private roomManager?: any; // Reference to RoomManager for handler context
+  private roomManagementManager?: any; // Reference to RoomManagementManager for handler context (v2.0.0)
+  private agentRoomManager?: any; // Reference to AgentRoomManager for handler context (v2.0.0)
+  private intentionalDisconnect: boolean = false; // Track intentional disconnect to prevent reconnection
 
   private connectionState: ConnectionState = {
     connected: false,
@@ -94,15 +97,13 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
     if (config.privateKey) {
       try {
         // Check if privateKey is already a SecurePrivateKey instance (SEC-3)
-        if (typeof config.privateKey === 'object' && 'use' in config.privateKey) {
+        if (typeof config.privateKey === "object" && "use" in config.privateKey) {
           // Use the provided SecurePrivateKey directly
           this.secureKey = config.privateKey;
           this.ownsSecureKey = false; // User provided it, we don't own it
 
           // Create account using the secure key
-          this.account = this.secureKey.use((key) =>
-            privateKeyToAccount(key as `0x${string}`)
-          );
+          this.account = this.secureKey.use((key) => privateKeyToAccount(key as `0x${string}`));
         } else {
           // privateKey is a plain string - encrypt it immediately
           const privateKeyString = config.privateKey as string;
@@ -117,9 +118,7 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
           this.ownsSecureKey = true; // We created it, we own it
 
           // Create account using the secure key
-          this.account = this.secureKey.use((key) =>
-            privateKeyToAccount(key as `0x${string}`)
-          );
+          this.account = this.secureKey.use((key) => privateKeyToAccount(key as `0x${string}`));
         }
 
         if (
@@ -214,6 +213,22 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
     this.roomManager = roomManager;
   }
 
+  /**
+   * Sets the room management manager for room CRUD operations (v2.0.0)
+   * @internal
+   */
+  public setRoomManagementManager(roomManagementManager: any): void {
+    this.roomManagementManager = roomManagementManager;
+  }
+
+  /**
+   * Sets the agent room manager for agent-room operations (v2.0.0)
+   * @internal
+   */
+  public setAgentRoomManager(agentRoomManager: any): void {
+    this.agentRoomManager = agentRoomManager;
+  }
+
   /**
    * Establishes a WebSocket connection to the Teneo server.
    * Handles connection timeout, authentication challenge-response flow,
@@ -241,6 +256,10 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
       // Clear any existing connection
       this.disconnect();
 
+      // Reset intentional disconnect flag after clearing connection
+      // This allows automatic reconnection for this new connection
+      this.intentionalDisconnect = false;
+
       // Build connection URL with webhook parameter
       let url = this.config.wsUrl;
       if (this.config.webhookUrl) {
@@ -295,7 +314,11 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
           if (parseResult.success) {
             this.handleMessage(parseResult.data as BaseMessage);
           } else {
-            this.logger.error("Invalid message format", parseResult.error);
+            // Use warn instead of error - allows SDK to be more resilient
+            this.logger.warn("Received message with unknown or invalid format", {
+              type: rawMessage?.type,
+              error: parseResult.error?.message
+            });
             this.emit(
               "message:error",
               new ValidationError("Invalid message format", parseResult.error),
@@ -362,6 +385,9 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
   public disconnect(): void {
     this.logger.info("Disconnecting from WebSocket server");
 
+    // Mark as intentional disconnect to prevent reconnection
+    this.intentionalDisconnect = true;
+
     // Clear all timers
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
@@ -490,7 +516,7 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
           this.logger.error("Failed to send message", error);
           reject(error);
         } else {
-          this.logger.debug("Message sent", { type: validatedMessage.type });
+          this.logger.debug("Message sent", validatedMessage);
           this.emit("message:sent", validatedMessage);
           resolve();
         }
@@ -649,6 +675,8 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
       updateConnectionState: (update: any) => this.updateConnectionState(update),
       updateAuthState: (update: any) => this.updateAuthState(update),
       roomManager: this.roomManager,
+      roomManagementManager: this.roomManagementManager,
+      agentRoomManager: this.agentRoomManager,
       account: this.account,
       sendMessage: (message: BaseMessage) => this.sendMessage(message)
     };
@@ -795,6 +823,12 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
    * Handle reconnection logic with configurable retry strategy (REL-3)
    */
   private handleReconnection(): void {
+    // Don't reconnect if disconnect was intentional
+    if (this.intentionalDisconnect) {
+      this.logger.debug("Skipping reconnection - disconnect was intentional");
+      return;
+    }
+
     if (!this.config.reconnect || this.connectionState.reconnecting) {
       return;
     }

package/src/formatters/response-formatter.test.ts

@@ -428,12 +428,18 @@ describe("ResponseFormatter", () => {
         data: { message: "Test", code: 1 }
       };
 
-      const rawResult = ResponseFormatter.validateAndFormat(message, { format: "raw", includeMetadata: false });
+      const rawResult = ResponseFormatter.validateAndFormat(message, {
+        format: "raw",
+        includeMetadata: false
+      });
       expect(rawResult.raw).toBeDefined();
       expect(rawResult.humanized).toBeUndefined();
       expect(rawResult.metadata).toBeUndefined();
 
-      const bothWithMeta = ResponseFormatter.validateAndFormat(message, { format: "both", includeMetadata: true });
+      const bothWithMeta = ResponseFormatter.validateAndFormat(message, {
+        format: "both",
+        includeMetadata: true
+      });
       expect(bothWithMeta.raw).toBeDefined();
       expect(bothWithMeta.humanized).toBeDefined();
       expect(bothWithMeta.metadata).toBeDefined();

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

@@ -0,0 +1,83 @@
+/**
+ * Handler for agent_room_operation_response messages (v2.0.0)
+ * Processes responses from agent-room operations (add, remove)
+ */
+
+import {
+  AgentRoomOperationResponse,
+  AgentRoomOperationResponseSchema
+} from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+import { SDKError } from "../../types/events";
+import { ErrorCode } from "../../types/error-codes";
+
+export class AgentRoomOperationResponseHandler extends BaseMessageHandler<AgentRoomOperationResponse> {
+  readonly type = "agent_room_operation_response" as const;
+  readonly schema = AgentRoomOperationResponseSchema;
+
+  protected handleValidated(
+    message: AgentRoomOperationResponse,
+    context: HandlerContext
+  ): void {
+    const { success, message: errorMessage, room_id, agent_id } = message.data;
+
+    context.logger.debug("Handling agent_room_operation_response", {
+      success,
+      roomId: room_id,
+      agentId: agent_id
+    });
+
+    if (!success) {
+      // Operation failed - emit error events
+      const error = new SDKError(
+        errorMessage || "Agent room operation failed",
+        ErrorCode.OPERATION_FAILED
+      );
+
+      context.logger.error("Agent room operation failed", {
+        roomId: room_id,
+        agentId: agent_id,
+        error: errorMessage
+      });
+
+      // Emit both add and remove error events - listeners will filter by room/agent ID
+      this.emit(context, "agent_room:add_error", error, room_id);
+      this.emit(context, "agent_room:remove_error", error, room_id);
+
+      // Send webhook
+      this.sendWebhook(context, "agent_room_operation_error", {
+        success: false,
+        message: errorMessage,
+        room_id,
+        agent_id
+      });
+
+      return;
+    }
+
+    // Operation succeeded
+    if (room_id && agent_id) {
+      context.logger.info("Agent room operation succeeded", {
+        roomId: room_id,
+        agentId: agent_id
+      });
+
+      // Emit success events
+      // The promise handlers in AgentRoomManager will filter by room_id and agent_id
+      this.emit(context, "agent_room:agent_added", room_id, agent_id);
+      this.emit(context, "agent_room:agent_removed", room_id, agent_id);
+
+      // Send webhook
+      this.sendWebhook(context, "agent_room_operation", {
+        success: true,
+        room_id,
+        agent_id,
+        message: "Agent room operation completed successfully"
+      });
+    } else {
+      // Unexpected: success but missing required fields
+      context.logger.warn("Agent room operation succeeded but missing room_id or agent_id");
+    }
+  }
+}