@teneo-protocol/sdk 1.0.0 → 2.0.0

package/examples/usage/05-webhook-example.ts

@@ -0,0 +1,319 @@
+/**
+ * Example 5: Webhook Integration (Production Pattern)
+ *
+ * This example demonstrates production-ready webhook integration
+ * following the pattern from examples/production-dashboard:
+ *
+ * - Setting up a local webhook receiver with multiple endpoints
+ * - Configuring SDK with allowInsecureWebhooks for local development
+ * - Using sdk.configureWebhook() for runtime webhook setup
+ * - Receiving and processing different webhook event types
+ * - Webhook retry logic and error handling
+ * - Circuit breaker behavior on failures
+ * - Tracking webhook statistics and metrics
+ *
+ * The webhook server provides:
+ * - POST /webhook - Receives webhook events from SDK
+ * - GET /health - Health check with metrics
+ * - GET /webhooks - List all received webhooks
+ *
+ * Run: npx tsx examples/usage/05-webhook-example.ts
+ */
+
+import "dotenv/config";
+import { TeneoSDK, SDKConfigBuilder } from "../../dist/index.js";
+import express from "express";
+import type { Request, Response } from "express";
+
+// Load configuration from environment
+const WS_URL =
+  process.env.WS_URL || "wss://your-teneo-server.com/ws";
+const PRIVATE_KEY = process.env.PRIVATE_KEY || "";
+const DEFAULT_ROOM = process.env.DEFAULT_ROOM || "general";
+const WEBHOOK_PORT = parseInt(process.env.WEBHOOK_PORT || "3001");
+const WEBHOOK_SINK_PORT = parseInt(process.env.WEBHOOK_SINK_PORT || "3000");
+
+// Track received webhooks for stats
+let webhookCounter = 0;
+const receivedWebhooks: any[] = [];
+
+async function main() {
+  console.log("🚀 Example 5: Webhook Integration\n");
+
+  if (!PRIVATE_KEY) {
+    console.error("❌ ERROR: PRIVATE_KEY environment variable is required\n");
+    process.exit(1);
+  }
+
+  // Step 1: Set up local webhook receiver
+  console.log("⚙️  Step 1: Setting up local webhook receiver...");
+
+  const app = express();
+  app.use(express.json());
+
+  // Webhook endpoint - receives events from SDK
+  app.post("/webhook", (req: Request, res: Response) => {
+    const payload = req.body;
+    webhookCounter++;
+
+    // Store webhook for later display
+    receivedWebhooks.push({
+      ...payload,
+      receivedAt: new Date().toISOString()
+    });
+
+    console.log(`\n🎯 Webhook #${webhookCounter} received!`);
+    console.log("=".repeat(80));
+    console.log(`Event: ${payload.event}`);
+    console.log(`Timestamp: ${payload.timestamp}`);
+
+    // Show specific data based on event type
+    if (payload.event === "task_response") {
+      console.log(`Agent: ${payload.data?.agentName || "Unknown"}`);
+      console.log(`Task ID: ${payload.data?.taskId}`);
+      console.log(`Success: ${payload.data?.success !== false}`);
+      if (payload.data?.humanized) {
+        const preview = payload.data.humanized.substring(0, 100);
+        console.log(`Response: ${preview}${payload.data.humanized.length > 100 ? "..." : ""}`);
+      }
+    } else if (payload.event === "agent_selected") {
+      console.log(`Agent: ${payload.data?.agent_name || "Unknown"}`);
+      console.log(`Reasoning: ${payload.data?.reasoning || "N/A"}`);
+    } else {
+      console.log(`Data: ${JSON.stringify(payload.data, null, 2).substring(0, 200)}`);
+    }
+
+    if (payload.metadata) {
+      console.log(
+        `Metadata: Room=${payload.metadata.roomId}, Agent=${payload.metadata.agentId || "N/A"}`
+      );
+    }
+    console.log("=".repeat(80) + "\n");
+
+    // Respond with success
+    res.status(200).json({
+      success: true,
+      received_at: new Date().toISOString(),
+      webhook_count: webhookCounter
+    });
+  });
+
+  // Health check endpoint
+  app.get("/health", (_req: Request, res: Response) => {
+    res.json({
+      status: "ok",
+      webhooksReceived: webhookCounter,
+      uptime: process.uptime()
+    });
+  });
+
+  // Webhook list endpoint - view all received webhooks
+  app.get("/webhooks", (_req: Request, res: Response) => {
+    res.json({
+      total: webhookCounter,
+      webhooks: receivedWebhooks
+    });
+  });
+
+  const server = app.listen(WEBHOOK_SINK_PORT, () => {
+    console.log(`✅ Webhook server running on http://localhost:${WEBHOOK_SINK_PORT}`);
+    console.log(`   POST http://localhost:${WEBHOOK_PORT}/webhook - Receive webhooks`);
+    console.log(`   GET  http://localhost:${WEBHOOK_PORT}/health - Health check`);
+    console.log(`   GET  http://localhost:${WEBHOOK_PORT}/webhooks - List all webhooks`);
+    console.log("");
+  });
+
+  // Step 2: Build SDK with webhook configuration
+  console.log("⚙️  Step 2: Building SDK and configuring webhook...");
+
+  const webhookUrl = `http://localhost:${WEBHOOK_PORT}/webhook`;
+
+  const config = new SDKConfigBuilder()
+    .withWebSocketUrl(WS_URL)
+    .withAuthentication(PRIVATE_KEY)
+    // .withAutoJoinRooms([DEFAULT_ROOM])
+    .withResponseFormat({ format: "both", includeMetadata: true })
+    .withLogging("info")
+    .build();
+
+  // IMPORTANT: Allow insecure webhooks for local development
+  // In production, remove this and use HTTPS webhooks only
+  config.allowInsecureWebhooks = true;
+
+  const sdk = new TeneoSDK(config);
+
+  // Configure webhook after SDK creation (production-dashboard pattern)
+  // This allows runtime webhook configuration with custom headers
+  sdk.configureWebhook(webhookUrl, {
+    "X-API-Key": "webhook-example-secret",
+    "Content-Type": "application/json"
+  });
+
+  console.log(`✅ SDK configured with webhook: ${webhookUrl}`);
+  console.log("   Custom headers: X-API-Key, Content-Type\n");
+
+  // Step 3: Monitor webhook events
+  console.log("⚙️  Step 3: Setting up webhook event listeners...");
+
+  sdk.on("webhook:sent", (payload, url) => {
+    console.log(`📤 Webhook sent to ${url}`);
+    console.log(`   Event: ${payload.event}`);
+  });
+
+  sdk.on("webhook:success", (response, url) => {
+    console.log(`✅ Webhook delivered successfully to ${url}`);
+  });
+
+  sdk.on("webhook:error", (error, url) => {
+    console.error(`❌ Webhook delivery failed to ${url}:`);
+    console.error(`   Error: ${error.message}`);
+  });
+
+  sdk.on("webhook:retry", (attempt, url) => {
+    console.log(`🔄 Retrying webhook delivery (attempt ${attempt}) to ${url}`);
+  });
+
+  console.log("✅ Webhook event listeners configured\n");
+
+  try {
+    // Step 4: Connect to Teneo
+    console.log("⚙️  Step 4: Connecting to Teneo network...");
+    await sdk.connect();
+    console.log("✅ Connected!\n");
+
+    console.log("💡 Tip: While this runs, you can visit:");
+    console.log(`   http://localhost:${WEBHOOK_PORT}/health - Check server health`);
+    console.log(`   http://localhost:${WEBHOOK_PORT}/webhooks - View all webhooks\n`);
+
+    // Wait for agents
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    // Step 5: Trigger events that will send webhooks
+    console.log("⚙️  Step 5: Triggering events to test webhook delivery...");
+    console.log("   The following actions will trigger webhooks:\n");
+
+    // Get agents (triggers agent:list event)
+    console.log("   1. Getting agent list...");
+    const agents = sdk.getAgents();
+    console.log(`      Found ${agents.length} agents`);
+    await new Promise((resolve) => setTimeout(resolve, 500));
+
+    // Send a message (triggers message:sent)
+    if (agents.length > 0) {
+      const agent = agents.find((a) => a.status === "online") || agents[0];
+
+      console.log(`\n   2. Sending message to ${agent.name || agent.id}...`);
+      await sdk.sendDirectCommand(
+        {
+          agent: agent.id,
+          command: "hello webhook test",
+          room: DEFAULT_ROOM
+        },
+        false
+      ); // Don't wait for response
+      console.log("      Message sent");
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+
+    // Step 6: Check webhook status
+    console.log("\n⚙️  Step 6: Checking webhook status...");
+    const webhookStatus = sdk.getWebhookStatus();
+
+    console.log("\n📊 Webhook Status:");
+    console.log("=".repeat(80));
+    console.log(`Configured: ${webhookStatus.configured}`);
+    console.log(`URL: ${webhookStatus.config?.url}`);
+    console.log(`Pending deliveries: ${webhookStatus.queue.pending}`);
+    console.log(`Failed deliveries: ${webhookStatus.queue.failed}`);
+    console.log(`Circuit breaker state: ${webhookStatus.queue.circuitState}`);
+    console.log("=".repeat(80));
+
+    // Step 7: Demonstrate retry on failure
+    console.log("\n⚙️  Step 7: Testing webhook retry behavior...");
+    console.log("   Temporarily stopping webhook server to simulate failure...\n");
+
+    // Close server to simulate failure
+    server.close();
+    console.log("   ⚠️  Webhook server stopped");
+
+    // Try to send a message (webhook will fail and retry)
+    console.log("   Triggering event (webhook should fail and retry)...");
+    const testAgents = sdk.getAgents();
+    if (testAgents.length > 0) {
+      await sdk.sendDirectCommand(
+        {
+          agent: testAgents[0].id,
+          command: "test retry",
+          room: DEFAULT_ROOM
+        },
+        false
+      );
+    }
+
+    // Wait to see retry attempts
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+
+    // Check status again
+    const statusAfterFailure = sdk.getWebhookStatus();
+    console.log("\n📊 Status after failure:");
+    console.log(`   Pending: ${statusAfterFailure.queue.pending}`);
+    console.log(`   Failed: ${statusAfterFailure.queue.failed}`);
+    console.log(`   Circuit state: ${statusAfterFailure.queue.circuitState}`);
+
+    // Clear failed webhooks
+    if (statusAfterFailure.queue.failed > 0) {
+      console.log("\n⚙️  Clearing failed webhooks...");
+      sdk.clearWebhookQueue();
+      console.log("   ✅ Queue cleared");
+    }
+
+    console.log("\n💡 Key Points:");
+    console.log("   • Webhooks are sent asynchronously (non-blocking)");
+    console.log("   • Automatic retry with exponential backoff");
+    console.log("   • Circuit breaker prevents cascading failures");
+    console.log("   • Failed webhooks can be retried or cleared");
+    console.log("   • All events are logged and can be monitored");
+
+    // Display webhook summary
+    console.log("\n📊 Webhook Summary:");
+    console.log("=".repeat(80));
+    console.log(`Total webhooks received: ${webhookCounter}`);
+
+    if (receivedWebhooks.length > 0) {
+      console.log("\nWebhook events breakdown:");
+      const eventTypes = receivedWebhooks.reduce(
+        (acc, wh) => {
+          acc[wh.event] = (acc[wh.event] || 0) + 1;
+          return acc;
+        },
+        {} as Record<string, number>
+      );
+
+      Object.entries(eventTypes).forEach(([event, count]) => {
+        console.log(`   ${event}: ${count}`);
+      });
+
+      console.log("\nRecent webhooks (last 5):");
+      receivedWebhooks
+        .slice(-5)
+        .reverse()
+        .forEach((wh, idx) => {
+          console.log(
+            `   ${idx + 1}. ${wh.event} at ${new Date(wh.receivedAt).toLocaleTimeString()}`
+          );
+        });
+    }
+    console.log("=".repeat(80));
+  } catch (error) {
+    console.error("\n❌ Error:", error);
+    process.exit(1);
+  } finally {
+    sdk.disconnect();
+    sdk.destroy();
+    server.close();
+    console.log("\n✅ Disconnected and cleaned up");
+    console.log("🎉 Example completed!");
+  }
+}
+
+main().catch(console.error);

package/examples/usage/06-simple-api-server.ts

@@ -0,0 +1,396 @@
+/**
+ * Example 6: Simple API Server
+ *
+ * This example demonstrates:
+ * - Building a REST API server using Express that wraps the SDK
+ * - Exposing SDK functionality via HTTP endpoints
+ * - Managing SDK lifecycle in a server context
+ * - Error handling and health checks
+ * - Production-ready server patterns
+ *
+ * Run: npx tsx examples/usage/06-simple-api-server.ts
+ * Then use curl or Postman to test:
+ *   curl http://localhost:3000/health
+ *   curl http://localhost:3000/agents
+ *   curl -X POST http://localhost:3000/message -H "Content-Type: application/json" -d '{"message":"hello","agent":"agent-id"}'
+ */
+
+import "dotenv/config";
+import express from "express";
+import type { Request, Response } from "express";
+import { TeneoSDK, SDKConfigBuilder } from "../../dist/index.js";
+
+// Load configuration from environment
+const WS_URL =
+  process.env.WS_URL || "wss://your-teneo-server.com/ws";
+const PRIVATE_KEY = process.env.PRIVATE_KEY || "";
+const DEFAULT_ROOM = process.env.DEFAULT_ROOM || "general";
+const PORT = parseInt(process.env.PORT || "3000");
+
+// Validate configuration
+if (!PRIVATE_KEY) {
+  console.error("❌ ERROR: PRIVATE_KEY environment variable is required\n");
+  process.exit(1);
+}
+
+// Initialize Express app
+const app = express();
+app.use(express.json());
+
+// Build SDK
+console.log("🚀 Initializing Teneo API Server\n");
+console.log("📋 Configuration:");
+console.log(`   WebSocket: ${WS_URL}`);
+console.log(`   Room: ${DEFAULT_ROOM}`);
+console.log(`   Port: ${PORT}\n`);
+
+const config = new SDKConfigBuilder()
+  .withWebSocketUrl(WS_URL)
+  .withAuthentication(PRIVATE_KEY)
+  // .withAutoJoinRooms([DEFAULT_ROOM])
+  .withResponseFormat({ format: "both", includeMetadata: true })
+  .withReconnection({ enabled: true, delay: 5000, maxAttempts: 10 })
+  .withLogging("info")
+  .build();
+
+const sdk = new TeneoSDK(config);
+
+// Track SDK state
+let isReady = false;
+
+// SDK event listeners
+sdk.on("auth:success", (state) => {
+  console.log(`✅ Authenticated as ${state.walletAddress}`);
+  isReady = true;
+});
+
+sdk.on("connection:close", () => {
+  console.log("⚠️  Connection closed");
+  isReady = false;
+});
+
+sdk.on("connection:reconnecting", (attempt) => {
+  console.log(`🔄 Reconnecting... (attempt ${attempt})`);
+});
+
+sdk.on("error", (error) => {
+  console.error("❌ SDK Error:", error.message);
+});
+
+// Connect to Teneo
+console.log("🔌 Connecting to Teneo network...");
+await sdk.connect();
+console.log("✅ Connected!\n");
+
+// Wait for agents to load
+await new Promise((resolve) => setTimeout(resolve, 1000));
+
+// ============================================================================
+// API ENDPOINTS
+// ============================================================================
+
+/**
+ * GET /health
+ * Health check endpoint - returns SDK and server status
+ */
+app.get("/health", (_req: Request, res: Response) => {
+  const health = sdk.getHealth();
+
+  res.json({
+    status: health.status,
+    server: {
+      ready: isReady,
+      uptime: process.uptime()
+    },
+    teneo: {
+      connected: health.connection.status === "connected",
+      authenticated: health.connection.authenticated,
+      reconnectAttempts: health.connection.reconnectAttempts,
+      agents: health.agents.count,
+      rooms: health.rooms.count,
+      subscribedRooms: health.rooms.subscribedRooms
+    }
+  });
+});
+
+/**
+ * GET /agents
+ * List all available agents
+ */
+app.get("/agents", (_req: Request, res: Response) => {
+  try {
+    const agents = sdk.getAgents();
+
+    res.json({
+      success: true,
+      count: agents.length,
+      agents: agents.map((agent) => ({
+        id: agent.id,
+        name: agent.name,
+        description: agent.description,
+        status: agent.status,
+        capabilities: agent.capabilities,
+        commands: agent.commands
+      }))
+    });
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+});
+
+/**
+ * GET /agents/:id
+ * Get specific agent by ID
+ */
+app.get("/agents/:id", (req: Request, res: Response) => {
+  try {
+    const { id } = req.params;
+    const agent = sdk.getAgent(id);
+
+    if (!agent) {
+      return res.status(404).json({
+        success: false,
+        error: `Agent ${id} not found`
+      });
+    }
+
+    res.json({
+      success: true,
+      agent: {
+        id: agent.id,
+        name: agent.name,
+        description: agent.description,
+        status: agent.status,
+        capabilities: agent.capabilities,
+        commands: agent.commands
+      }
+    });
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+});
+
+/**
+ * GET /agents/capability/:capability
+ * Find agents by capability
+ */
+app.get("/agents/capability/:capability", (req: Request, res: Response) => {
+  try {
+    const { capability } = req.params;
+    const agents = sdk.findAgentsByCapability(capability);
+
+    res.json({
+      success: true,
+      capability,
+      count: agents.length,
+      agents: agents.map((agent) => ({
+        id: agent.id,
+        name: agent.name,
+        status: agent.status
+      }))
+    });
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+});
+
+/**
+ * POST /message
+ * Send a message to an agent
+ * Body: { message: string, agent?: string, waitForResponse?: boolean, timeout?: number }
+ */
+app.post("/message", async (req: Request, res: Response) => {
+  try {
+    const { message, agent, waitForResponse = false, timeout = 30000 } = req.body;
+
+    if (!message) {
+      return res.status(400).json({
+        success: false,
+        error: "Message is required"
+      });
+    }
+
+    if (!isReady) {
+      return res.status(503).json({
+        success: false,
+        error: "SDK is not ready yet"
+      });
+    }
+
+    const startTime = Date.now();
+
+    if (agent) {
+      // Send to specific agent
+      const response = await sdk.sendDirectCommand(
+        {
+          agent,
+          command: message,
+          room: DEFAULT_ROOM
+        },
+        waitForResponse
+      );
+
+      if (waitForResponse && response) {
+        res.json({
+          success: true,
+          agent,
+          response: {
+            humanized: response.humanized,
+            raw: response.raw,
+            metadata: response.metadata
+          },
+          duration: Date.now() - startTime
+        });
+      } else {
+        res.json({
+          success: true,
+          agent,
+          message: "Message sent (no response requested)",
+          duration: Date.now() - startTime
+        });
+      }
+    } else {
+      // Send via coordinator (will auto-select agent)
+      const response = await sdk.sendMessage(message, {
+        room: DEFAULT_ROOM,
+        waitForResponse,
+        timeout
+      });
+
+      if (waitForResponse && response) {
+        res.json({
+          success: true,
+          response: {
+            humanized: response.humanized,
+            raw: response.raw,
+            metadata: response.metadata
+          },
+          duration: Date.now() - startTime
+        });
+      } else {
+        res.json({
+          success: true,
+          message: "Message sent to coordinator (no response requested)",
+          duration: Date.now() - startTime
+        });
+      }
+    }
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+});
+
+/**
+ * GET /rooms
+ * List subscribed rooms
+ */
+app.get("/rooms", (_req: Request, res: Response) => {
+  try {
+    const rooms = sdk.getSubscribedRooms();
+
+    res.json({
+      success: true,
+      rooms
+    });
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+});
+
+/**
+ * POST /rooms/:roomId/subscribe
+ * Subscribe to a room
+ */
+app.post("/rooms/:roomId/subscribe", async (req: Request, res: Response) => {
+  try {
+    const { roomId } = req.params;
+    await sdk.subscribeToRoom(roomId);
+
+    res.json({
+      success: true,
+      message: `Subscribed to room ${roomId}`,
+      subscribedRooms: sdk.getSubscribedRooms()
+    });
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+});
+
+/**
+ * POST /rooms/:roomId/unsubscribe
+ * Unsubscribe from a room
+ */
+app.post("/rooms/:roomId/unsubscribe", async (req: Request, res: Response) => {
+  try {
+    const { roomId } = req.params;
+    await sdk.unsubscribeFromRoom(roomId);
+
+    res.json({
+      success: true,
+      message: `Unsubscribed from room ${roomId}`,
+      subscribedRooms: sdk.getSubscribedRooms()
+    });
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+});
+
+// ============================================================================
+// START SERVER
+// ============================================================================
+
+const server = app.listen(PORT, () => {
+  console.log("🚀 Teneo API Server running!\n");
+  console.log("📡 Endpoints:");
+  console.log(`   GET    http://localhost:${PORT}/health`);
+  console.log(`   GET    http://localhost:${PORT}/agents`);
+  console.log(`   GET    http://localhost:${PORT}/agents/:id`);
+  console.log(`   GET    http://localhost:${PORT}/agents/capability/:capability`);
+  console.log(`   POST   http://localhost:${PORT}/message`);
+  console.log(`   GET    http://localhost:${PORT}/rooms`);
+  console.log(`   POST   http://localhost:${PORT}/rooms/:roomId/subscribe`);
+  console.log(`   POST   http://localhost:${PORT}/rooms/:roomId/unsubscribe`);
+  console.log("\n📝 Example requests:");
+  console.log(`   curl http://localhost:${PORT}/health`);
+  console.log(`   curl http://localhost:${PORT}/agents`);
+  console.log(
+    `   curl -X POST http://localhost:${PORT}/message -H "Content-Type: application/json" -d '{"message":"hello","waitForResponse":true}'`
+  );
+  console.log("\n✅ Server ready to accept requests!\n");
+});
+
+// Graceful shutdown
+process.on("SIGINT", () => {
+  console.log("\n\n👋 Shutting down gracefully...");
+
+  server.close(() => {
+    console.log("✅ HTTP server closed");
+  });
+
+  sdk.disconnect();
+  sdk.destroy();
+  console.log("✅ SDK disconnected");
+
+  process.exit(0);
+});