@teneo-protocol/sdk 1.0.1 → 2.2.0

package/README.md

@@ -2,10 +2,10 @@
 
 **Connect your app to the Teneo AI Agent Network**
 
-[![npm version](https://img.shields.io/badge/version-1.0.0-blue)](https://www.npmjs.com/package/@teneo-protocol/sdk)
+[![npm version](https://img.shields.io/badge/version-2.2.0-blue)](https://www.npmjs.com/package/@teneo-protocol/sdk)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green)](https://nodejs.org/)
-[![Tests](https://img.shields.io/badge/tests-488%20passing-success)](/)
+[![Tests](https://img.shields.io/badge/tests-671%20passing-success)](/)
 
 The Teneo Protocol SDK lets you connect your application to a **decentralized network of specialized AI agents**. Instead of calling a single AI model, your app taps into an entire ecosystem where:
 
@@ -30,7 +30,7 @@ import { TeneoSDK } from "@teneo-protocol/sdk";
 
 // 1. Initialize with your Ethereum private key
 const sdk = new TeneoSDK({
-  wsUrl: "wss://developer.chatroom.teneo-protocol.ai/ws",
+  wsUrl: "wss://backend.developer.chatroom.teneo-protocol.ai/ws",
   privateKey: "your_private_key_here" // No 0x prefix
 });
 
@@ -47,12 +47,57 @@ await sdk.sendMessage("Give me the last 5 tweets from @elonmusk");
 ```
 
 **That's it!** The coordinator automatically:
+
 1. Routes your message to the right agent
 2. Gets the response
 3. Delivers it via the event you're listening to
 
 ---
 
+## ✨ What's New in v2.2
+
+Version 2.2 introduces the **Quote-Approve Payment Flow** with x402 protocol support:
+
+### 💰 Payment Flow (Quote-Approve)
+
+- **Automatic payment handling** - SDK handles the full quote → confirm → pay cycle
+- **x402 Protocol** - Industry-standard payment headers (Coinbase x402)
+- **USDC on PEAQ** - Payments settle on PEAQ network (Chain ID 3338)
+- **Price limits** - Set maximum price per request for safety
+
+[Jump to Payment Flow API](#-payment-flow-api)
+
+---
+
+## ✨ What's New in v2.0
+
+Version 2.0 introduces powerful **room management** and **agent customization** capabilities:
+
+### 🏠 Multi-Room Management
+
+- **Create multiple rooms** for different contexts (crypto, gaming, research, etc.)
+- **Update and delete** your owned rooms
+- **Track room limits** based on your subscription tier
+- **Invite members** to your rooms (coming soon)
+
+### 🤖 Agent Room Management
+
+- **Customize which agents** are available in each room
+- **Add/remove agents** from your owned rooms
+- **List room agents** with caching for performance
+- **Real-time agent status updates** for room availability
+
+### 📊 Enhanced APIs
+
+- 8 new room management methods
+- 8 new agent-room management methods
+- 14 new events for room and agent operations
+- Intelligent caching with 5-minute TTL
+
+[Jump to Room Management API](#-room-management-api) | [Jump to Agent Room Management API](#-agent-room-management-api)
+
+---
+
 ## How It Works
 
 ### 1. Agent Network Architecture
@@ -88,6 +133,7 @@ Unlike traditional APIs with API keys, Teneo uses **Ethereum wallet signatures**
 ```
 
 This enables:
+
 - 🔐 **No API keys to manage** - Your wallet IS your identity
 
 ---
@@ -104,23 +150,35 @@ pnpm run build
 
 # Set credentials
 export PRIVATE_KEY=your_private_key
-export TENEO_WS_URL=wss://developer.chatroom.teneo-protocol.ai/ws
+export TENEO_WS_URL=wss://backend.developer.chatroom.teneo-protocol.ai/ws
 ```
 
-### Basic Usage Example
+### Production Dashboard Example
+
+The **Production Dashboard** is a comprehensive example showcasing **ALL SDK features** in a real-world web application:
 
 ```bash
-npx ts-node examples/basic-usage.ts
+pnpm example:dashboard
+# or
+cd examples/production-dashboard && bun run server.ts
 ```
 
-Demonstrates:
-- ✅ Connection and authentication
-- ✅ Agent discovery
-- ✅ Room management
-- ✅ Sending messages
-- ✅ Event listeners
-- ✅ Secure private key handling
+Then open: **[http://localhost:3000](http://localhost:3000)**
+
+**What it demonstrates:**
 
+- ✅ **Full WebSocket Integration** - Connection, authentication, auto-reconnection
+- ✅ **Room Management (v2.0)** - Create, update, delete rooms with ownership tracking
+- ✅ **Agent-Room Management (v2.0)** - Add/remove agents, list room agents with caching
+- ✅ **Message Sending** - Coordinator-based and direct agent commands
+- ✅ **Real-time Updates** - Server-Sent Events (SSE) for live dashboard
+- ✅ **Agent Discovery** - List agents with capabilities and status
+- ✅ **Secure Private Key Handling** - AES-256-GCM encryption in memory
+- ✅ **Webhook Integration** - Real-time event streaming with circuit breaker
+- ✅ **Health Monitoring** - `/health` and `/metrics` endpoints
+- ✅ **Complete Event System** - All SDK events with real-time UI updates
+
+Built with **Hono** (fast web framework) and **Bun** (fast JavaScript runtime). See `examples/production-dashboard/README.md` for details.
 
 ---
 
@@ -139,14 +197,11 @@ const sdk = new TeneoSDK({
 await sdk.connect();
 
 // Wait for response (blocks until agent responds or timeout)
-const response = await sdk.sendMessage(
-  "Give me the last 5 tweets from @elonmusk?",
-  {
-    waitForResponse: true,
-    timeout: 30000, // 30 seconds
-    format: "both"  // Get both raw data and humanized text
-  }
-);
+const response = await sdk.sendMessage("Give me the last 5 tweets from @elonmusk?", {
+  waitForResponse: true,
+  timeout: 30000, // 30 seconds
+  format: "both" // Get both raw data and humanized text
+});
 
 console.log("Agent:", response.agentName);
 console.log("Answer:", response.humanized);
@@ -184,7 +239,6 @@ console.log("Active rooms:", rooms);
 // Output: Active rooms: ['Crawler Room', 'KOL tracker']
 ```
 
-
 ### Example 3: Webhook Integration
 
 Receive agent responses via HTTP POST to your server:
@@ -221,7 +275,7 @@ const sdk = new TeneoSDK({
   privateKey: process.env.PRIVATE_KEY!,
   webhookUrl: "https://your-webhook.com/",
   webhookHeaders: {
-    "Authorization": "Bearer your-secret-token"
+    Authorization: "Bearer your-secret-token"
   }
 });
 
@@ -243,6 +297,465 @@ console.log("Circuit state:", status.circuitState); // OPEN/CLOSED/HALF_OPEN
 
 ---
 
+## WebSocket Endpoints
+
+The Teneo SDK supports two deployment environments via different WebSocket endpoints:
+
+### Development Platform (Testing)
+
+- **URL**: `wss://backend.developer.chatroom.teneo-protocol.ai/ws`
+- **Whitelist**: Not required - open for testing
+- **Use case**: Development, testing, and experimentation
+
+**Configuration:**
+```bash
+# .env file
+TENEO_WS_URL=wss://backend.developer.chatroom.teneo-protocol.ai/ws
+```
+
+### Production Platform (B2B)
+
+- **URL**: `wss://backend.chatroom.teneo-protocol.ai/ws`
+- **Whitelist**: **Required** - you must be whitelisted to use this endpoint
+- **Use case**: Production applications and B2B integrations
+- **Get access**: Request whitelist access at [https://teneo-protocol.ai/chat-room](https://teneo-protocol.ai/chat-room)
+
+**Configuration:**
+```bash
+# .env file
+TENEO_WS_URL=wss://backend.chatroom.teneo-protocol.ai/ws
+```
+
+
+> **Note**: The SDK uses the **development endpoint by default**. For production use, you need to be whitelisted and explicitly configure the production URL. Use the development endpoint for testing without restrictions.
+
+---
+## 🏠 Room Management API
+
+Create and manage multiple rooms for different contexts and use cases.
+
+### Creating Rooms
+
+```typescript
+// Create a new room
+const room = await sdk.createRoom({
+  name: "Crypto Research",
+  description: "Room for crypto analysis"
+});
+console.log(`Created room: ${room.id}`);
+
+// Check if you can create more rooms
+if (sdk.canCreateRoom()) {
+  await sdk.createRoom({ name: "Gaming Room" });
+} else {
+  console.log(`Room limit reached: ${sdk.getOwnedRoomCount()}/${sdk.getRoomLimit()}`);
+}
+```
+
+### Querying Rooms
+
+```typescript
+// Get all owned rooms (rooms you created)
+const ownedRooms = sdk.getOwnedRooms();
+console.log(`You own ${ownedRooms.length} rooms:`);
+ownedRooms.forEach((room) => {
+  console.log(`  - ${room.name} (${room.is_public ? "Public" : "Private"})`);
+});
+
+// Get shared rooms (rooms you were invited to)
+const sharedRooms = sdk.getSharedRooms();
+console.log(`You have access to ${sharedRooms.length} shared rooms`);
+
+// Get all rooms (owned + shared)
+const allRooms = sdk.getAllRooms();
+console.log(`Total rooms accessible: ${allRooms.length}`);
+
+// Get specific room by ID
+const room = sdk.getRoomById("room-123");
+if (room) {
+  console.log(`Room: ${room.name}`);
+  console.log(`Created by: ${room.created_by}`);
+  console.log(`You are ${room.is_owner ? "owner" : "member"}`);
+}
+
+// Check room limits
+console.log(`Room capacity: ${sdk.getOwnedRoomCount()}/${sdk.getRoomLimit()}`);
+```
+
+### Updating Rooms
+
+```typescript
+// Update room details (owner only)
+const updated = await sdk.updateRoom("room-123", {
+  name: "Updated Room Name",
+  description: "New description"
+});
+
+console.log(`Room updated: ${updated.name}`);
+```
+
+### Deleting Rooms
+
+```typescript
+// Delete a room you own
+await sdk.deleteRoom("room-123");
+console.log("Room deleted");
+
+// Listen for deletion events
+sdk.on("room:deleted", (roomId) => {
+  console.log(`Room ${roomId} was deleted`);
+});
+```
+
+### Room Events
+
+```typescript
+// Room lifecycle events
+sdk.on("room:created", (room) => {
+  console.log(`✅ Created: ${room.name}`);
+});
+
+sdk.on("room:updated", (room) => {
+  console.log(`📝 Updated: ${room.name}`);
+});
+
+sdk.on("room:deleted", (roomId) => {
+  console.log(`🗑️ Deleted: ${roomId}`);
+});
+
+// Error handling
+sdk.on("room:create_error", (error) => {
+  console.error(`Failed to create room: ${error.message}`);
+});
+
+sdk.on("room:update_error", (error, roomId) => {
+  console.error(`Failed to update room ${roomId}: ${error.message}`);
+});
+
+sdk.on("room:delete_error", (error, roomId) => {
+  console.error(`Failed to delete room ${roomId}: ${error.message}`);
+});
+```
+
+---
+
+## 🤖 Agent Room Management API
+
+Customize which agents are available in each of your rooms.
+
+### Adding Agents to Rooms
+
+```typescript
+// Add an agent to your room (owner only)
+await sdk.addAgentToRoom("room-123", "agent-456");
+console.log("Agent added to room");
+
+// Listen for confirmation
+sdk.on("agent_room:agent_added", (roomId, agentId) => {
+  console.log(`✅ Agent ${agentId} added to room ${roomId}`);
+});
+```
+
+### Removing Agents from Rooms
+
+```typescript
+// Remove an agent from your room (owner only)
+await sdk.removeAgentFromRoom("room-123", "agent-456");
+console.log("Agent removed from room");
+
+// Listen for confirmation
+sdk.on("agent_room:agent_removed", (roomId, agentId) => {
+  console.log(`🗑️ Agent ${agentId} removed from room ${roomId}`);
+});
+```
+
+### Listing Room Agents
+
+```typescript
+// List all agents in a room (with 5-minute cache)
+const roomAgents = await sdk.listRoomAgents("room-123");
+console.log(`${roomAgents.length} agents in this room:`);
+roomAgents.forEach((agent) => {
+  console.log(`  - ${agent.agent_name} (${agent.status})`);
+  if (agent.capabilities) {
+    console.log(`    Capabilities: ${agent.capabilities.map((c) => c.name).join(", ")}`);
+  }
+});
+
+// Force refresh (bypass cache)
+const freshAgents = await sdk.listRoomAgents("room-123", false);
+```
+
+### Listing Available Agents
+
+```typescript
+// List agents NOT yet in the room (available to add)
+const available = await sdk.listAvailableAgents("room-123");
+console.log(`${available.length} agents available to add:`);
+available.forEach((agent) => {
+  console.log(`  - ${agent.agent_name}`);
+  if (agent.description) {
+    console.log(`    ${agent.description}`);
+  }
+});
+```
+
+### Query Methods (Synchronous - from cache)
+
+```typescript
+// Check if specific agent is in room (instant, no network call)
+const isInRoom = sdk.isAgentInRoom("room-123", "agent-456");
+if (isInRoom === true) {
+  console.log("Agent is in the room");
+} else if (isInRoom === false) {
+  console.log("Agent is NOT in the room");
+} else {
+  console.log("Cache not available - call listRoomAgents() first");
+}
+
+// Get room agent count (instant)
+const count = sdk.getRoomAgentCount("room-123");
+if (count !== undefined) {
+  console.log(`Room has ${count} agents`);
+}
+
+// Get cached room agents (instant)
+const cached = sdk.getRoomAgents("room-123");
+if (cached) {
+  console.log("Agents:", cached.map((a) => a.agent_name).join(", "));
+} else {
+  console.log("No cached data - call listRoomAgents() first");
+}
+
+// Get cached available agents (instant)
+const cachedAvailable = sdk.getAvailableAgents("room-123");
+```
+
+### Cache Management
+
+```typescript
+// Caching behavior:
+// - listRoomAgents() and listAvailableAgents() cache results for 5 minutes
+// - Cache automatically invalidated when you add/remove agents
+// - Cache automatically invalidated on agent status updates
+
+// Manual cache invalidation (if needed)
+sdk.invalidateAgentRoomCache("room-123");
+console.log("Cache cleared for room-123");
+```
+
+### Agent Room Events
+
+```typescript
+// Agent add/remove events
+sdk.on("agent_room:agent_added", (roomId, agentId) => {
+  console.log(`✅ Agent ${agentId} added to ${roomId}`);
+});
+
+sdk.on("agent_room:agent_removed", (roomId, agentId) => {
+  console.log(`🗑️ Agent ${agentId} removed from ${roomId}`);
+});
+
+// List events
+sdk.on("agent_room:agents_listed", (roomId, agents) => {
+  console.log(`📋 ${agents.length} agents in room ${roomId}`);
+});
+
+sdk.on("agent_room:available_agents_listed", (agents) => {
+  console.log(`📋 ${agents.length} agents available to add`);
+});
+
+// Status updates (real-time)
+sdk.on("agent_room:status_update", (data) => {
+  console.log(`🔄 Agent ${data.agentId} status updated in room ${data.roomId}`);
+  console.log(`   New status: ${data.status}`);
+});
+
+// Error handling
+sdk.on("agent_room:add_error", (error, roomId) => {
+  console.error(`Failed to add agent to ${roomId}: ${error.message}`);
+});
+
+sdk.on("agent_room:remove_error", (error, roomId) => {
+  console.error(`Failed to remove agent from ${roomId}: ${error.message}`);
+});
+
+sdk.on("agent_room:list_error", (error, roomId) => {
+  console.error(`Failed to list agents in ${roomId}: ${error.message}`);
+});
+
+sdk.on("agent_room:list_available_error", (error, roomId) => {
+  console.error(`Failed to list available agents for ${roomId}: ${error.message}`);
+});
+```
+
+### Complete Example: Room Setup
+
+```typescript
+// Complete workflow: Create room and customize agents
+async function setupCustomRoom() {
+  // 1. Create a new room
+  const room = await sdk.createRoom({
+    name: "My Custom Room",
+    description: "Specialized agent room"
+  });
+  console.log(`✅ Created room: ${room.id}`);
+
+  // 2. See what agents are available
+  const available = await sdk.listAvailableAgents(room.id);
+  console.log(`${available.length} agents available`);
+
+  // 3. Add specific agents you want
+  const cryptoAgent = available.find((a) => a.agent_name?.includes("Crypto"));
+  if (cryptoAgent) {
+    await sdk.addAgentToRoom(room.id, cryptoAgent.agent_id);
+    console.log(`✅ Added ${cryptoAgent.agent_name}`);
+  }
+
+  const analyticsAgent = available.find((a) => a.agent_name?.includes("Analytics"));
+  if (analyticsAgent) {
+    await sdk.addAgentToRoom(room.id, analyticsAgent.agent_id);
+    console.log(`✅ Added ${analyticsAgent.agent_name}`);
+  }
+
+  // 4. Verify room configuration
+  const roomAgents = await sdk.listRoomAgents(room.id);
+  console.log(`\n🎯 Room configured with ${roomAgents.length} agents:`);
+  roomAgents.forEach((agent) => {
+    console.log(`   - ${agent.agent_name}`);
+  });
+
+  // 5. Now send messages to this room
+  await sdk.sendMessage("Analyze BTC price trends", { room: room.id });
+}
+
+setupCustomRoom();
+```
+
+---
+
+## 💰 Payment Flow API
+
+The SDK supports automatic micropayments to AI agents using the x402 protocol.
+
+### Basic Usage (Auto-Approve)
+
+```typescript
+import { TeneoSDK } from "@teneo-protocol/sdk";
+
+// Enable payments with auto-approve
+const sdk = new TeneoSDK(
+  TeneoSDK.builder()
+    .withWebSocketUrl("wss://backend.developer.chatroom.teneo-protocol.ai/ws")
+    .withAuthentication(process.env.PRIVATE_KEY!)
+    .withPayments({
+      autoApprove: true,           // Automatically approve quotes
+      maxPricePerRequest: 1000000  // Max 1 USDC per request (in micro-units)
+    })
+    .build()
+);
+
+await sdk.connect();
+
+// Send message - payment handled automatically
+const response = await sdk.sendMessage("@x-agent-enterprise-v2 user @elonmusk", {
+  room: roomId,
+  waitForResponse: true
+});
+
+console.log(response.humanized);
+// Output: User profile for @elonmusk...
+```
+
+### Direct Agent Commands
+
+```typescript
+// Target a specific agent directly
+await sdk.sendMessage("@x-agent-enterprise-v2 timeline @elonmusk 5", {
+  room: roomId,
+  waitForResponse: true
+});
+
+// Let the coordinator choose the best agent
+await sdk.sendMessage("Get me the latest tweets from @elonmusk", {
+  room: roomId,
+  waitForResponse: true
+});
+```
+
+### Payment Events
+
+```typescript
+// Quote received from agent
+sdk.on("quote:received", (quote) => {
+  console.log(`Quote: ${quote.data.pricing.pricePerUnit} USDC`);
+  console.log(`Agent: ${quote.data.agent_name}`);
+  console.log(`Expires: ${quote.data.expires_at}`);
+});
+
+// Payment attached to request
+sdk.on("payment:attached", (data) => {
+  console.log(`Paid ${data.amount / 1_000_000} USDC to ${data.agentId}`);
+});
+
+// Payment errors
+sdk.on("payment:error", (error) => {
+  console.error(`Payment failed: ${error.message}`);
+});
+```
+
+### Manual Quote Approval
+
+```typescript
+const sdk = new TeneoSDK(
+  TeneoSDK.builder()
+    .withWebSocketUrl("wss://...")
+    .withAuthentication(privateKey)
+    .withPayments({
+      autoApprove: false  // Require manual approval
+    })
+    .build()
+);
+
+// Listen for quotes
+sdk.on("quote:received", async (quote) => {
+  const price = quote.data.pricing.pricePerUnit;
+
+  // Check price before approving
+  if (price <= 0.01) {
+    // Approve and send payment
+    await sdk.confirmQuote(quote.data.task_id);
+  } else {
+    console.log(`Quote too expensive: $${price}`);
+  }
+});
+
+// Request triggers quote
+await sdk.sendMessage("@x-agent user @elonmusk", { room: roomId });
+```
+
+### Payment Flow Diagram
+
+```
+Your App                    Teneo Backend                 Agent
+   │                             │                          │
+   │──── request_task ──────────>│                          │
+   │                             │────── select agent ─────>│
+   │<───── task_quote ───────────│<────── pricing ──────────│
+   │                             │                          │
+   │  [Auto-approve or manual]   │                          │
+   │                             │                          │
+   │──── confirm_task ──────────>│                          │
+   │     + x402 payment header   │────── execute task ─────>│
+   │                             │                          │
+   │<───── task_response ────────│<────── response ─────────│
+   │                             │                          │
+   │                             │──── settle payment ─────>│
+   └                             └                          └
+```
+
+---
+
 ## 🎨 Event System
 
 The SDK is fully event-driven. Subscribe to what matters:
@@ -254,7 +767,9 @@ sdk.on("connection:open", () => console.log("🔌 WebSocket connected"));
 sdk.on("connection:close", (code, reason) => console.log(`❌ Disconnected: ${reason}`));
 sdk.on("connection:reconnecting", (attempt) => console.log(`🔄 Reconnecting (attempt ${attempt})`));
 
-sdk.on("auth:challenge", (challenge) => console.log("🔐 Challenge received, signing with wallet..."));
+sdk.on("auth:challenge", (challenge) =>
+  console.log("🔐 Challenge received, signing with wallet...")
+);
 sdk.on("auth:success", (state) => {
   console.log(`✅ Authenticated as ${state.walletAddress}`);
   console.log(`Whitelisted: ${state.isWhitelisted}`);
@@ -277,7 +792,7 @@ sdk.on("agent:response", (response) => {
 
 sdk.on("agent:list", (agents) => {
   console.log(`📋 Agent list updated: ${agents.length} agents available`);
-  agents.forEach(agent => {
+  agents.forEach((agent) => {
     console.log(`  - ${agent.name}: ${agent.capabilities?.join(", ")}`);
   });
 });
@@ -304,7 +819,7 @@ sdk.on("room:unsubscribed", (data) => {
 
 ```typescript
 const sdk = new TeneoSDK({
-  wsUrl: "wss://developer.chatroom.teneo-protocol.ai/ws",
+  wsUrl: "wss://backend.developer.chatroom.teneo-protocol.ai/ws",
   privateKey: "your_key", // No 0x prefix
   defaultRoom: "general",
   reconnect: true,
@@ -322,7 +837,7 @@ const secureKey = new SecurePrivateKey(process.env.PRIVATE_KEY!);
 
 const config = new SDKConfigBuilder()
   // Required
-  .withWebSocketUrl("wss://developer.chatroom.teneo-protocol.ai/ws")
+  .withWebSocketUrl("wss://backend.developer.chatroom.teneo-protocol.ai/ws")
   .withAuthentication(secureKey) // Encrypted key
 
   // Rooms
@@ -331,15 +846,15 @@ const config = new SDKConfigBuilder()
   // Reconnection strategy
   .withReconnectionStrategy({
     type: "exponential",
-    baseDelay: 3000,          // Start at 3 seconds
-    maxDelay: 120000,         // Cap at 2 minutes
+    baseDelay: 3000, // Start at 3 seconds
+    maxDelay: 120000, // Cap at 2 minutes
     maxAttempts: 20,
-    jitter: true              // Prevent thundering herd
+    jitter: true // Prevent thundering herd
   })
 
   // Webhook with retry
   .withWebhook("https://your-server.com/webhook", {
-    "Authorization": "Bearer token"
+    Authorization: "Bearer token"
   })
   .withWebhookRetryStrategy({
     type: "exponential",
@@ -350,7 +865,7 @@ const config = new SDKConfigBuilder()
 
   // Response formatting
   .withResponseFormat({
-    format: "both",           // 'raw' | 'humanized' | 'both'
+    format: "both", // 'raw' | 'humanized' | 'both'
     includeMetadata: true
   })
 
@@ -362,7 +877,7 @@ const config = new SDKConfigBuilder()
   })
 
   // Performance
-  .withRateLimit(10, 20)    // 10 msg/sec, burst 20
+  .withRateLimit(10, 20) // 10 msg/sec, burst 20
   .withMessageDeduplication(true, 60000, 10000)
   .withLogging("debug")
 
@@ -376,7 +891,7 @@ const sdk = new TeneoSDK(config);
 Create `.env`:
 
 ```bash
-TENEO_WS_URL=wss://developer.chatroom.teneo-protocol.ai/ws
+TENEO_WS_URL=wss://backend.developer.chatroom.teneo-protocol.ai/ws
 PRIVATE_KEY=your_private_key_without_0x
 WALLET_ADDRESS=0xYourWalletAddress
 DEFAULT_ROOM=general
@@ -448,11 +963,11 @@ console.log("Circuit state:", status.circuitState);
 
 Configurable exponential backoff, linear, or constant delays:
 
-| Strategy | Formula | Example (base=2s, mult=2) |
-|----------|---------|---------------------------|
-| **Exponential** | `base * mult^attempt` | 2s, 4s, 8s, 16s, 32s |
-| **Linear** | `base * attempt` | 2s, 4s, 6s, 8s, 10s |
-| **Constant** | `base` | 2s, 2s, 2s, 2s, 2s |
+| Strategy        | Formula               | Example (base=2s, mult=2) |
+| --------------- | --------------------- | ------------------------- |
+| **Exponential** | `base * mult^attempt` | 2s, 4s, 8s, 16s, 32s      |
+| **Linear**      | `base * attempt`      | 2s, 4s, 6s, 8s, 10s       |
+| **Constant**    | `base`                | 2s, 2s, 2s, 2s, 2s        |
 
 ```typescript
 const config = new SDKConfigBuilder()
@@ -461,7 +976,7 @@ const config = new SDKConfigBuilder()
     baseDelay: 3000,
     maxDelay: 120000,
     maxAttempts: 20,
-    jitter: true              // Add 0-1000ms randomness
+    jitter: true // Add 0-1000ms randomness
   })
   .build();
 ```
@@ -473,9 +988,9 @@ Prevents duplicate message processing with TTL-based cache:
 ```typescript
 const config = new SDKConfigBuilder()
   .withMessageDeduplication(
-    true,      // Enable
-    300000,    // 5 minute TTL
-    10000      // Cache up to 10k message IDs
+    true, // Enable
+    300000, // 5 minute TTL
+    10000 // Cache up to 10k message IDs
   )
   .build();
 
@@ -569,6 +1084,7 @@ if (dedup) {
 ### Issue: "ERR_REQUIRE_ESM" Error
 
 **Problem:**
+
 ```
 Error [ERR_REQUIRE_ESM]: require() of ES Module node-fetch not supported
 ```
@@ -585,6 +1101,7 @@ npx ts-node your-app.ts
 ```
 
 **Alternative:** Install node-fetch v2:
+
 ```bash
 npm install node-fetch@2.7.0
 npm run build
@@ -596,19 +1113,22 @@ npm run build
 
 **Solutions:**
 
-1. **Check private key format (64 hex characters, no 0x):**
+1. **Check private key format (64 hex characters, + 0x prefix):**
+
    ```typescript
-   // ✅ Good
-   privateKey: "dafe885a73d87dc34b7933068423b40a646adf5cef45954265e9a1b9be6bad9d"
+   // ✅ Good - 64 hex characters after 0x prefix
+   privateKey: "0x1234567890123456789012345678901234567890123456789012345678901234";
    ```
 
 2. **Verify key length:**
+
    ```bash
    echo -n "your_key" | wc -c
-   # Should output: 64
+   # Should output: 64 + 0x prefix
    ```
 
 3. **Enable debug logging:**
+
    ```typescript
    const sdk = new TeneoSDK({
      wsUrl: "...",
@@ -620,6 +1140,7 @@ npm run build
 ### Issue: Rate Limiting
 
 **Problem:**
+
 ```
 RateLimitError: Rate limit exceeded
 ```
@@ -630,7 +1151,7 @@ RateLimitError: Rate limit exceeded
    ```typescript
    for (const message of messages) {
      await sdk.sendMessage(message);
-     await new Promise(r => setTimeout(r, 200)); // 200ms delay
+     await new Promise((r) => setTimeout(r, 200)); // 200ms delay
    }
    ```
 
@@ -639,16 +1160,18 @@ RateLimitError: Rate limit exceeded
 **Solutions:**
 
 1. **Verify HTTPS (except localhost):**
+
    ```typescript
    // ✅ Good
-   webhookUrl: "https://your-server.com/webhook"
-   webhookUrl: "http://localhost:3000/webhook"
+   webhookUrl: "https://your-server.com/webhook";
+   webhookUrl: "http://localhost:3000/webhook";
 
    // ❌ Bad
-   webhookUrl: "http://your-server.com/webhook"
+   webhookUrl: "http://your-server.com/webhook";
    ```
 
 2. **Test manually:**
+
    ```bash
    curl -X POST https://your-server.com/webhook \
      -H "Content-Type: application/json" \
@@ -676,8 +1199,9 @@ npm run test:integration # Integration tests
 ```
 
 **Test Results:**
-- ✅ 488 unit tests passing
-- ✅ 98.6% pass rate
+
+- ✅ 671 unit tests passing
+- ✅ 100% pass rate (Phase 0-2 complete)
 - ✅ Comprehensive coverage
 
 ---
@@ -701,7 +1225,6 @@ We welcome contributions!
 
 AGPL-3.0 License
 
-
 <div align="center">
 
 **Built with ❤️ by the [Teneo Team](https://teneo.pro)**