@teneo-protocol/sdk 1.0.0 → 1.0.1

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://dev-rooms-websocket-ai-core-o9fmb.ondigitalocean.app/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": "1.0.1",
   "description": "TypeScript SDK for external platforms to interact with Teneo agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,7 +17,6 @@
   "license": "AGPL-3.0",
   "dependencies": {
     "eventemitter3": "^5.0.1",
-    "hono": "^4.9.12",
     "node-fetch": "^3.3.2",
     "pino": "^8.17.2",
     "uuid": "^9.0.1",
@@ -60,6 +59,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,7 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
   private deduplicationCache?: DeduplicationCache;
   private reconnectPolicy: RetryPolicy;
   private roomManager?: any; // Reference to RoomManager for handler context
+  private intentionalDisconnect: boolean = false; // Track intentional disconnect to prevent reconnection
 
   private connectionState: ConnectionState = {
     connected: false,
@@ -94,15 +95,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 +116,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 (
@@ -241,6 +238,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) {
@@ -362,6 +363,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);
@@ -795,6 +799,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/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/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"
+      );
     });
   });
 

package/src/managers/message-router.ts

@@ -156,7 +156,10 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
    * });
    * ```
    */
-  public async sendDirectCommand(command: AgentCommand): Promise<FormattedResponse | void> {
+  public async sendDirectCommand(
+    command: AgentCommand,
+    waitForResponse: boolean = false
+  ): Promise<FormattedResponse | void> {
     if (!this.wsClient.isConnected) {
       throw new SDKError("Not connected to Teneo network", ErrorCode.NOT_CONNECTED);
     }
@@ -185,11 +188,21 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
       from: walletAddress
     });
 
-    await this.wsClient.sendMessage(message);
-    await this.webhookHandler.sendMessageWebhook(message);
-  }
-
+    const options: SendMessageOptions = {
+      room,
+      from: walletAddress,
+      waitForResponse,
+      timeout: this.messageTimeout,
+      format: this.responseFormat
+    };
 
+    if (waitForResponse) {
+      return await this.sendMessageAndWaitForResponse(message, options);
+    } else {
+      await this.wsClient.sendMessage(message);
+      await this.webhookHandler.sendMessageWebhook(message);
+    }
+  }
 
   /**
    * Send message and wait for agent response
@@ -220,16 +233,45 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
 
     // Wait for agent response with automatic timeout and cleanup
     // The filter ensures we only match responses for THIS specific request
+    const requestTimestamp = Date.now();
+    let responseMatched = false;
+
     const response = await waitForEvent<AgentResponse>(this.wsClient, "agent:response", {
       timeout,
       filter: (r) => {
+        // Prevent double-matching
+        if (responseMatched) return false;
+
         // Try to match by client_request_id if server echoes it back
         const responseRequestId =
           r.raw?.data && "client_request_id" in r.raw.data
             ? (r.raw.data as any).client_request_id
             : undefined;
 
-        return responseRequestId === requestId;
+        if (responseRequestId === requestId) {
+          responseMatched = true;
+          return true;
+        }
+
+        // Fallback: If server doesn't support client_request_id,
+        // match the first response from the expected room within 60 seconds
+        // This handles servers that don't echo back client_request_id
+        const timeSinceRequest = Date.now() - requestTimestamp;
+        const responseRoom = r.raw?.room;
+        const isFromExpectedRoom = responseRoom === message.room;
+        const isWithinTimeWindow = timeSinceRequest < 60000; // 60 second window
+
+        if (isFromExpectedRoom && isWithinTimeWindow && !responseRequestId) {
+          this.logger.debug("Matching response without client_request_id (server fallback)", {
+            responseRoom,
+            expectedRoom: message.room,
+            timeSinceRequest
+          });
+          responseMatched = true;
+          return true;
+        }
+
+        return false;
       },
       timeoutMessage: `Message timeout - no response received after ${timeout}ms (requestId: ${requestId})`
     });