@teneo-protocol/sdk 1.0.0 → 2.0.0

package/examples/room-management-example.ts

@@ -0,0 +1,285 @@
+/**
+ * Room Management Example
+ *
+ * Demonstrates how to create, manage, and organize multiple rooms in the Teneo SDK v2.0.
+ *
+ * This example shows:
+ * - Creating rooms with different configurations
+ * - Checking room limits and quotas
+ * - Querying owned vs shared rooms
+ * - Updating room properties
+ * - Deleting rooms
+ * - Handling room events
+ *
+ * Prerequisites:
+ * - Set TENEO_WS_URL environment variable
+ * - Set PRIVATE_KEY environment variable (64 hex characters, no 0x prefix)
+ *
+ * Run:
+ *   npx ts-node examples/room-management-example.ts
+ */
+
+import { TeneoSDK } from "../src";
+import * as dotenv from "dotenv";
+
+dotenv.config();
+
+const wsUrl = process.env.TENEO_WS_URL!;
+const privateKey = process.env.PRIVATE_KEY!;
+
+async function main() {
+  console.log("🚀 Teneo SDK v2.0 - Room Management Example\n");
+
+  // Initialize SDK
+  const sdk = new TeneoSDK({
+    wsUrl,
+    privateKey,
+    logLevel: "info",
+    reconnect: true
+  });
+
+  // Set up event listeners for room operations
+  setupEventListeners(sdk);
+
+  try {
+    // Connect and authenticate
+    console.log("📡 Connecting to Teneo network...");
+    await sdk.connect();
+    console.log("✅ Connected and authenticated\n");
+
+    // Wait a moment for initial room data to load
+    await new Promise(resolve => setTimeout(resolve, 1000));
+
+    // Step 1: Check current room status
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    console.log("📊 Current Room Status");
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    await displayRoomStatus(sdk);
+
+    // Step 2: Create new rooms
+    console.log("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    console.log("🏗️  Creating New Rooms");
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    const newRooms = await createSampleRooms(sdk);
+
+    // Wait for room creation events to process
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    // Step 3: Display updated room status
+    console.log("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    console.log("📊 Updated Room Status");
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    await displayRoomStatus(sdk);
+
+    // Step 4: Update a room
+    if (newRooms.length > 0) {
+      console.log("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+      console.log("📝 Updating Room");
+      console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+      await updateRoomExample(sdk, newRooms[0].id);
+    }
+
+    // Step 5: Query specific room
+    if (newRooms.length > 0) {
+      console.log("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+      console.log("🔍 Querying Specific Room");
+      console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+      const room = sdk.getRoomById(newRooms[0].id);
+      if (room) {
+        console.log(`Room ID: ${room.id}`);
+        console.log(`Name: ${room.name}`);
+        console.log(`Description: ${room.description || "N/A"}`);
+        console.log(`Type: ${room.is_public ? "Public" : "Private"}`);
+        console.log(`Created by: ${room.created_by}`);
+        console.log(`Created at: ${room.created_at}`);
+        console.log(`You are: ${room.is_owner ? "Owner" : "Member"}`);
+      }
+    }
+
+    // Step 6: Delete rooms
+    console.log("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    console.log("🗑️  Cleaning Up (Deleting Rooms)");
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    await deleteRooms(sdk, newRooms);
+
+    // Wait for deletion events to process
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    // Step 7: Final room status
+    console.log("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    console.log("📊 Final Room Status");
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    await displayRoomStatus(sdk);
+
+    console.log("\n✅ Room management example completed!");
+
+  } catch (error: any) {
+    console.error("\n❌ Error:", error.message);
+    console.error(error.stack);
+  } finally {
+    // Disconnect
+    console.log("\n👋 Disconnecting...");
+    sdk.disconnect();
+    console.log("✅ Disconnected");
+  }
+}
+
+function setupEventListeners(sdk: TeneoSDK) {
+  // Room created
+  sdk.on("room:created", (room) => {
+    console.log(`  ✅ Room created: "${room.name}" (${room.id})`);
+  });
+
+  // Room updated
+  sdk.on("room:updated", (room) => {
+    console.log(`  ✅ Room updated: "${room.name}" (${room.id})`);
+  });
+
+  // Room deleted
+  sdk.on("room:deleted", (roomId) => {
+    console.log(`  ✅ Room deleted: ${roomId}`);
+  });
+
+  // Room errors
+  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}`);
+  });
+}
+
+async function displayRoomStatus(sdk: TeneoSDK) {
+  const ownedRooms = sdk.getOwnedRooms();
+  const sharedRooms = sdk.getSharedRooms();
+  const roomLimit = sdk.getRoomLimit();
+  const roomCount = sdk.getOwnedRoomCount();
+
+  console.log(`Room Capacity: ${roomCount}/${roomLimit} rooms used`);
+  console.log(`Can create more rooms: ${sdk.canCreateRoom() ? "✅ Yes" : "❌ No (limit reached)"}`);
+
+  console.log(`\n📁 Owned Rooms (${ownedRooms.length}):`);
+  if (ownedRooms.length === 0) {
+    console.log("  (none)");
+  } else {
+    ownedRooms.forEach((room, i) => {
+      console.log(`  ${i + 1}. "${room.name}" - ${room.is_public ? "Public" : "Private"}`);
+      console.log(`     ID: ${room.id}`);
+      if (room.description) {
+        console.log(`     Description: ${room.description}`);
+      }
+    });
+  }
+
+  console.log(`\n🤝 Shared Rooms (${sharedRooms.length}):`);
+  if (sharedRooms.length === 0) {
+    console.log("  (none)");
+  } else {
+    sharedRooms.forEach((room, i) => {
+      console.log(`  ${i + 1}. "${room.name}" - ${room.is_public ? "Public" : "Private"}`);
+      console.log(`     ID: ${room.id}`);
+      console.log(`     Created by: ${room.created_by}`);
+    });
+  }
+}
+
+async function createSampleRooms(sdk: TeneoSDK) {
+  const newRooms = [];
+
+  // Check if we can create rooms
+  if (!sdk.canCreateRoom()) {
+    console.log("⚠️  Cannot create rooms - limit reached");
+    console.log(`   Current: ${sdk.getOwnedRoomCount()}/${sdk.getRoomLimit()}`);
+    return newRooms;
+  }
+
+  try {
+    // Create room 1: Private crypto research room
+    console.log("Creating 'Crypto Research' room...");
+    const cryptoRoom = await sdk.createRoom({
+      name: "Crypto Research",
+      description: "Room for cryptocurrency analysis and tracking",
+      isPublic: false
+    });
+    newRooms.push(cryptoRoom);
+
+    // Create room 2: Public gaming room (if we have capacity)
+    if (sdk.canCreateRoom()) {
+      console.log("Creating 'Gaming Hub' room...");
+      const gamingRoom = await sdk.createRoom({
+        name: "Gaming Hub",
+        description: "Public room for gaming-related AI agents",
+        isPublic: true
+      });
+      newRooms.push(gamingRoom);
+    }
+
+    // Create room 3: Research room (if we have capacity)
+    if (sdk.canCreateRoom()) {
+      console.log("Creating 'AI Research' room...");
+      const researchRoom = await sdk.createRoom({
+        name: "AI Research",
+        description: "Room for AI research and experimentation"
+      });
+      newRooms.push(researchRoom);
+    }
+
+  } catch (error: any) {
+    console.error(`Failed to create room: ${error.message}`);
+  }
+
+  return newRooms;
+}
+
+async function updateRoomExample(sdk: TeneoSDK, roomId: string) {
+  try {
+    const originalRoom = sdk.getRoomById(roomId);
+    if (!originalRoom) {
+      console.log("  ⚠️  Room not found");
+      return;
+    }
+
+    console.log(`Original room name: "${originalRoom.name}"`);
+    console.log(`Original description: "${originalRoom.description || "N/A"}"`);
+
+    console.log("\nUpdating room...");
+    const updatedRoom = await sdk.updateRoom(roomId, {
+      name: `${originalRoom.name} (Updated)`,
+      description: "This room was updated via the SDK v2.0 API"
+    });
+
+    console.log(`\nNew room name: "${updatedRoom.name}"`);
+    console.log(`New description: "${updatedRoom.description}"`);
+
+  } catch (error: any) {
+    console.error(`Failed to update room: ${error.message}`);
+  }
+}
+
+async function deleteRooms(sdk: TeneoSDK, rooms: any[]) {
+  if (rooms.length === 0) {
+    console.log("No rooms to delete");
+    return;
+  }
+
+  console.log(`Deleting ${rooms.length} room(s)...\n`);
+
+  for (const room of rooms) {
+    try {
+      console.log(`Deleting "${room.name}" (${room.id})...`);
+      await sdk.deleteRoom(room.id);
+      // Wait a bit between deletions
+      await new Promise(resolve => setTimeout(resolve, 300));
+    } catch (error: any) {
+      console.error(`Failed to delete room ${room.id}: ${error.message}`);
+    }
+  }
+}
+
+// Run the example
+main().catch(console.error);

package/examples/usage/.env.example

@@ -0,0 +1,17 @@
+# Teneo SDK Examples - Environment Configuration
+# Copy this file to .env and fill in your actual values
+
+# Required: WebSocket URL for Teneo network
+WS_URL=wss://your-teneo-server.com/ws
+
+# Required: Your Ethereum private key (keep this secret!)
+PRIVATE_KEY=your-private-key-here
+
+# Optional: Your wallet address (auto-derived from private key if not provided)
+WALLET_ADDRESS=0x...
+
+# Optional: Default room to join on connection
+DEFAULT_ROOM=general
+
+# Optional: Additional room ID (for multi-room examples)
+ROOM_ID=your-room-id-here

package/examples/usage/01-connect.ts

@@ -0,0 +1,116 @@
+/**
+ * Example 1: Basic SDK Connection
+ *
+ * This example demonstrates:
+ * - Building SDK configuration
+ * - Connecting to Teneo WebSocket
+ * - Basic authentication
+ * - Graceful disconnection
+ *
+ * Run: npx tsx examples/usage/01-connect.ts
+ */
+
+import "dotenv/config";
+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";
+
+async function main() {
+  console.log("🚀 Example 1: Basic SDK Connection\n");
+
+  // Validate required configuration
+  if (!PRIVATE_KEY) {
+    console.error("❌ ERROR: PRIVATE_KEY environment variable is required");
+    console.error("Set it with: export PRIVATE_KEY=your_private_key\n");
+    process.exit(1);
+  }
+
+  console.log("📋 Configuration:");
+  console.log(`   WebSocket URL: ${WS_URL}`);
+  console.log(`   Default Room: ${DEFAULT_ROOM}`);
+  console.log(`   Private Key: ${PRIVATE_KEY.substring(0, 10)}...`);
+  console.log("");
+
+  // Step 1: Build SDK configuration using the fluent builder API
+  console.log("⚙️  Step 1: Building SDK configuration...");
+  const config = new SDKConfigBuilder()
+    .withWebSocketUrl(WS_URL)
+    .withAuthentication(PRIVATE_KEY)
+    // .withAutoJoinRooms([DEFAULT_ROOM])
+    .withLogging("info")
+    .withReconnection({ enabled: true, delay: 5000, maxAttempts: 3 })
+    .build();
+  console.log("✅ Configuration built\n");
+
+  // Step 2: Create SDK instance
+  console.log("⚙️  Step 2: Creating SDK instance...");
+  const sdk = new TeneoSDK(config);
+  console.log("✅ SDK instance created\n");
+
+  // Step 3: Set up event listeners for connection lifecycle
+  console.log("⚙️  Step 3: Setting up event listeners...");
+
+  sdk.on("connection:open", () => {
+    console.log("🔌 WebSocket connection opened");
+  });
+
+  sdk.on("auth:challenge", (challenge) => {
+    console.log("🔐 Authentication challenge received");
+  });
+
+  sdk.on("auth:success", (state) => {
+    console.log("✅ Authentication successful!");
+    console.log(`   Wallet: ${state.walletAddress}`);
+    console.log(`   Whitelisted: ${state.isWhitelisted}`);
+    console.log(`   Rooms: ${state.rooms?.length || 0}`);
+  });
+
+  sdk.on("connection:close", (code, reason) => {
+    console.log(`🔌 Connection closed: ${code} - ${reason}`);
+  });
+
+  sdk.on("error", (error) => {
+    console.error("❌ SDK Error:", error.message);
+  });
+
+  console.log("✅ Event listeners configured\n");
+
+  try {
+    // Step 4: Connect to Teneo network
+    console.log("⚙️  Step 4: Connecting to Teneo network...");
+    await sdk.connect();
+    console.log("✅ Connected and authenticated!\n");
+
+    // Step 5: Check connection state
+    console.log("⚙️  Step 5: Checking connection state...");
+    const connectionState = sdk.getConnectionState();
+    const authState = sdk.getAuthState();
+
+    console.log("📊 Connection Status:");
+    console.log(`   Connected: ${connectionState.connected}`);
+    console.log(`   Authenticated: ${connectionState.authenticated}`);
+    console.log(`   Wallet: ${authState.walletAddress}`);
+    console.log("");
+
+    // Keep connection alive for a few seconds
+    console.log("⏳ Keeping connection alive for 3 seconds...");
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+  } catch (error) {
+    console.error("❌ Connection failed:", error);
+    process.exit(1);
+  } finally {
+    // Step 6: Graceful disconnection
+    console.log("\n⚙️  Step 6: Disconnecting...");
+    sdk.disconnect();
+    sdk.destroy();
+    console.log("✅ Disconnected and cleaned up\n");
+    console.log("🎉 Example completed successfully!");
+  }
+}
+
+// Run the example
+main().catch(console.error);

package/examples/usage/02-list-agents.ts

@@ -0,0 +1,153 @@
+/**
+ * Example 2: List Available Agents
+ *
+ * This example demonstrates:
+ * - Connecting to Teneo
+ * - Retrieving list of available agents
+ * - Inspecting agent properties (name, description, capabilities, status)
+ * - Using the agent registry
+ *
+ * Run: npx tsx examples/usage/02-list-agents.ts
+ */
+
+import "dotenv/config";
+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";
+
+async function main() {
+  console.log("🚀 Example 2: List Available Agents\n");
+
+  if (!PRIVATE_KEY) {
+    console.error("❌ ERROR: PRIVATE_KEY environment variable is required\n");
+    process.exit(1);
+  }
+
+  // Build and create SDK
+  const config = new SDKConfigBuilder()
+    .withWebSocketUrl(WS_URL)
+    .withAuthentication(PRIVATE_KEY)
+    // .withAutoJoinRooms([DEFAULT_ROOM])
+    .withLogging("info")
+    .build();
+
+  const sdk = new TeneoSDK(config);
+
+  // Listen for agent list updates
+  sdk.on("agent:list", (agents) => {
+    console.log(`📋 Agent list updated: ${agents.length} agents available`);
+  });
+
+  try {
+    // Connect to Teneo
+    console.log("🔌 Connecting to Teneo network...");
+    await sdk.connect();
+    console.log("✅ Connected!\n");
+
+    // Wait a moment for agent list to populate
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    // Step 1: Get all agents
+    console.log("⚙️  Step 1: Retrieving all agents...");
+    const agents = sdk.getAgents();
+    console.log(`✅ Found ${agents.length} agents\n`);
+
+    if (agents.length === 0) {
+      console.log("⚠️  No agents available in the network");
+      console.log("   This might be because:");
+      console.log("   - No agents are registered in the room");
+      console.log("   - Agents are offline");
+      console.log("   - You need to wait a bit longer for the list to populate");
+      return;
+    }
+
+    // Step 2: Display agent details
+    console.log("📊 Agent Details:");
+    console.log("=".repeat(80));
+
+    agents.forEach((agent, index) => {
+      console.log(`\n${index + 1}. ${agent.name || "Unnamed Agent"}`);
+      console.log(`   ID: ${agent.id}`);
+      console.log(`   Status: ${agent.status}`);
+
+      if (agent.description) {
+        console.log(`   Description: ${agent.description}`);
+      }
+
+      if (agent.room) {
+        console.log(`   Room: ${agent.room}`);
+      }
+
+      if (agent.agentType) {
+        console.log(`   Type: ${agent.agentType}`);
+      }
+
+      // Display capabilities
+      if (agent.capabilities && agent.capabilities.length > 0) {
+        console.log(`   Capabilities (${agent.capabilities.length}):`);
+        agent.capabilities.forEach((cap) => {
+          console.log(`      • ${cap.name}: ${cap.description}`);
+        });
+      }
+
+      // Display commands
+      if (agent.commands && agent.commands.length > 0) {
+        console.log(`   Commands (${agent.commands.length}):`);
+        agent.commands.slice(0, 3).forEach((cmd) => {
+          console.log(`      • ${cmd.trigger} ${cmd.argument || ""}`);
+          console.log(`        ${cmd.description}`);
+        });
+        if (agent.commands.length > 3) {
+          console.log(`      ... and ${agent.commands.length - 3} more`);
+        }
+      }
+    });
+
+    console.log("\n" + "=".repeat(80));
+
+    // Step 3: Get agent by ID
+    if (agents.length > 0) {
+      console.log("\n⚙️  Step 3: Retrieving specific agent by ID...");
+      const firstAgent = agents[0];
+      const agent = sdk.getAgent(firstAgent.id);
+
+      if (agent) {
+        console.log(`✅ Retrieved agent: ${agent.name}`);
+        console.log(`   ID: ${agent.id}`);
+        console.log(`   Status: ${agent.status}`);
+      }
+    }
+
+    // Step 4: Summary statistics
+    console.log("\n📈 Summary Statistics:");
+    console.log(`   Total Agents: ${agents.length}`);
+
+    const onlineAgents = agents.filter((a) => a.status === "online");
+    console.log(`   Online: ${onlineAgents.length}`);
+
+    const offlineAgents = agents.filter((a) => a.status === "offline");
+    console.log(`   Offline: ${offlineAgents.length}`);
+
+    const agentsWithCapabilities = agents.filter(
+      (a) => a.capabilities && a.capabilities.length > 0
+    );
+    console.log(`   With Capabilities: ${agentsWithCapabilities.length}`);
+
+    const agentsWithCommands = agents.filter((a) => a.commands && a.commands.length > 0);
+    console.log(`   With Commands: ${agentsWithCommands.length}`);
+  } catch (error) {
+    console.error("❌ Error:", error);
+    process.exit(1);
+  } finally {
+    sdk.disconnect();
+    sdk.destroy();
+    console.log("\n✅ Disconnected");
+    console.log("🎉 Example completed!");
+  }
+}
+
+main().catch(console.error);