@teneo-protocol/sdk 1.0.0 → 2.0.0

package/examples/n8n-teneo/index.ts

@@ -0,0 +1,177 @@
+/**
+ * Minimal example: Teneo Consumer SDK + n8n Integration
+ *
+ * Simple REST API for n8n workflows to query Teneo agents.
+ *
+ * Features:
+ * - POST /query - Send messages to Teneo coordinator or specific agents
+ * - GET /agents - List all available agents
+ * - GET /health - Health check endpoint
+ *
+ * The /query endpoint supports:
+ * - Automatic agent selection via coordinator (default)
+ * - Direct agent commands (when agent parameter is provided)
+ * - Event-based response handling for reliable message delivery
+ */
+
+import 'dotenv/config';
+import express from 'express';
+import { SDKConfigBuilder, TeneoSDK } from '../../dist/index.js';
+
+// Load environment variables
+const WS_URL = process.env.WS_URL || '';
+const PRIVATE_KEY = process.env.PRIVATE_KEY || '';
+const WALLET_ADDRESS = process.env.WALLET_ADDRESS || '';
+const DEFAULT_ROOM = process.env.DEFAULT_ROOM || 'general';
+const LOG_LEVEL = (process.env.LOG_LEVEL || 'info') as 'debug' | 'info' | 'warn' | 'error' | 'silent';
+const ENABLE_SIG_VERIFICATION = process.env.ENABLE_SIGNATURE_VERIFICATION === 'true';
+const TRUSTED_ADDRESSES = process.env.TRUSTED_ADDRESSES?.split(',').filter(Boolean) || [];
+const ENABLE_CACHE = process.env.ENABLE_CACHE !== 'false';
+const CACHE_TIMEOUT = parseInt(process.env.CACHE_TIMEOUT || '300000');
+const MAX_CACHE_SIZE = parseInt(process.env.MAX_CACHE_SIZE || '100');
+const ENABLE_RECONNECTION = process.env.ENABLE_RECONNECTION !== 'false';
+const RECONNECT_DELAY = parseInt(process.env.RECONNECT_DELAY || '5000');
+const MAX_RECONNECT_ATTEMPTS = parseInt(process.env.MAX_RECONNECT_ATTEMPTS || '10');
+
+// Validate required environment variables
+if (!WS_URL || !PRIVATE_KEY) {
+  console.error('Missing required environment variables: WS_URL, PRIVATE_KEY');
+  process.exit(1);
+}
+
+const app = express();
+app.use(express.json());
+
+// Initialize Teneo SDK using SDKConfigBuilder pattern
+const config = new SDKConfigBuilder()
+  .withWebSocketUrl(WS_URL)
+  .withAuthentication(PRIVATE_KEY, WALLET_ADDRESS)  // Wallet auto-derived if not provided
+  .withRoom(DEFAULT_ROOM)
+  .withReconnection({
+    enabled: ENABLE_RECONNECTION,
+    delay: RECONNECT_DELAY,
+    maxAttempts: MAX_RECONNECT_ATTEMPTS
+  })
+  .withResponseFormat({ format: 'both', includeMetadata: true })
+  .withLogging(LOG_LEVEL)
+  .withCache(ENABLE_CACHE, CACHE_TIMEOUT, MAX_CACHE_SIZE)
+  .withSignatureVerification({
+    enabled: ENABLE_SIG_VERIFICATION,
+    trustedAddresses: TRUSTED_ADDRESSES,
+    requireFor: ['task_response', 'agent_selected'],
+    strictMode: false
+  })
+  .build();
+
+const teneoSDK = new TeneoSDK(config);
+
+// Connect to Teneo
+console.log('📡 Connecting to Teneo network...');
+await teneoSDK.connect();
+console.log('✅ Connected to Teneo\n');
+
+// Health endpoint
+app.get('/health', (req, res) => {
+  const health = teneoSDK.getHealth();
+  res.json({
+    status: 'ok',
+    teneo: {
+      connected: health.connection.status === 'connected',
+      authenticated: health.connection.authenticated
+    }
+  });
+});
+
+// Query endpoint - send message to Teneo coordinator or specific agent
+app.post('/query', async (req, res) => {
+  try {
+    const { message, agent, timeout = 30000 } = req.body;
+
+    if (!message) {
+      return res.status(400).json({
+        success: false,
+        error: 'Message is required'
+      });
+    }
+
+    console.log(`\n🔍 Query: ${message}${agent ? ` (to agent: ${agent})` : ' (via coordinator)'}`);
+
+    let response: any;
+
+    // Send message either to specific agent or via coordinator
+    // Use the SDK's built-in waitForResponse feature with the improved fallback matching
+    if (agent) {
+      // Direct command to specific agent
+      console.log(`🎯 Sending direct command to agent: ${agent}`);
+      response = await teneoSDK.sendDirectCommand({
+        agent,
+        command: message,
+        room: DEFAULT_ROOM
+      }, true);  // waitForResponse = true
+    } else {
+      // Send via coordinator (coordinator will select best agent)
+      console.log('📡 Sending message via coordinator');
+      response = await teneoSDK.sendMessage(message, {
+        waitForResponse: true,
+        timeout
+      });
+    }
+
+    if (!response || !response.humanized) {
+      console.log('⚠️  No response data received');
+      return res.json({
+        success: false,
+        error: 'No response from agent'
+      });
+    }
+
+    console.log('📨 Response received from agent');
+    console.log(`✅ Response successfully processed\n`);
+
+    res.json({
+      success: true,
+      data: {
+        humanized: response.humanized,
+        raw: response.raw,
+        metadata: response.metadata
+      }
+    });
+  } catch (error) {
+    console.error('❌ Query error:', error);
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error'
+    });
+  }
+});
+
+// List agents endpoint
+app.get('/agents', (_req, res) => {
+  const agents = teneoSDK.getAgents();
+  res.json({
+    success: true,
+    agents: agents.map(a => ({
+      id: a.id,
+      name: a.name,
+      description: a.description,
+      capabilities: a.capabilities
+    }))
+  });
+});
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`🚀 Teneo Service running on http://localhost:${PORT}`);
+  console.log(`   Health: GET  http://localhost:${PORT}/health`);
+  console.log(`   Query:  POST http://localhost:${PORT}/query`);
+  console.log(`           Body: { "message": "your query", "agent": "optional-agent-id", "timeout": 30000 }`);
+  console.log(`   Agents: GET  http://localhost:${PORT}/agents\n`);
+});
+
+// Graceful shutdown
+process.on('SIGINT', () => {
+  console.log('\n👋 Shutting down...');
+  teneoSDK.disconnect();
+  teneoSDK.destroy();
+  process.exit(0);
+});

package/examples/n8n-teneo/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "n8n-teneo-example",
+  "version": "1.0.0",
+  "description": "Minimal example: Teneo Consumer SDK + n8n Integration",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch index.ts",
+    "build": "tsc",
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@teneo-protocol/sdk": "file:../../",
+    "express": "^4.18.2",
+    "dotenv": "^16.3.1"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3"
+  }
+}

package/examples/n8n-teneo/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "."
+  },
+  "include": ["index.ts"]
+}

package/examples/n8n-teneo/workflows/x-timeline.json

@@ -0,0 +1,66 @@
+{
+  "name": "X Timeline Query via Teneo",
+  "nodes": [
+    {
+      "parameters": {},
+      "name": "When clicking 'Test workflow'",
+      "type": "n8n-nodes-base.manualTrigger",
+      "typeVersion": 1,
+      "position": [250, 300],
+      "id": "manual-trigger"
+    },
+    {
+      "parameters": {
+        "method": "POST",
+        "url": "http://teneo-service:3000/query",
+        "jsonParameters": true,
+        "options": {},
+        "bodyParametersJson": "={\n  \"message\": \"timeline @elonmusk 10\"\n}"
+      },
+      "name": "Query Teneo X-Agent",
+      "type": "n8n-nodes-base.httpRequest",
+      "typeVersion": 4.1,
+      "position": [450, 300],
+      "id": "http-request"
+    },
+    {
+      "parameters": {
+        "values": {
+          "string": [
+            {
+              "name": "response",
+              "value": "={{ $json.data.humanized }}"
+            },
+            {
+              "name": "agent",
+              "value": "={{ $json.data.metadata.agentName }}"
+            }
+          ]
+        },
+        "options": {}
+      },
+      "name": "Extract Response",
+      "type": "n8n-nodes-base.set",
+      "typeVersion": 3,
+      "position": [650, 300],
+      "id": "set-node"
+    }
+  ],
+  "connections": {
+    "When clicking 'Test workflow'": {
+      "main": [[{"node": "Query Teneo X-Agent", "type": "main", "index": 0}]]
+    },
+    "Query Teneo X-Agent": {
+      "main": [[{"node": "Extract Response", "type": "main", "index": 0}]]
+    }
+  },
+  "pinData": {},
+  "settings": {
+    "executionOrder": "v1"
+  },
+  "staticData": null,
+  "tags": [],
+  "triggerCount": 0,
+  "updatedAt": "2025-10-15T00:00:00.000Z",
+  "versionId": "1"
+}

package/examples/openai-teneo/.env.example

@@ -0,0 +1,130 @@
+# OpenAI + Teneo Service - Environment Configuration
+# Copy this file to .env and fill in your values
+
+# ============================================================================
+# REQUIRED: OpenAI Configuration
+# ============================================================================
+
+# OpenAI API Key (get from https://platform.openai.com/api-keys)
+OPENAI_API_KEY=sk-...
+
+# OpenAI Model (optional, default: gpt-4-turbo-preview)
+# Options: gpt-4-turbo-preview, gpt-4, gpt-3.5-turbo, etc.
+OPENAI_MODEL=gpt-4-turbo-preview
+
+# ============================================================================
+# REQUIRED: Teneo Network Connection
+# ============================================================================
+
+# WebSocket URL for Teneo AI Network
+# Production: wss://your-production-server.com/ws
+# Development: wss://your-teneo-server.com/ws
+WS_URL=wss://your-teneo-server.com/ws
+
+# Ethereum Private Key (with 0x prefix)
+# IMPORTANT: Never commit your actual private key to version control!
+PRIVATE_KEY=0x1234567890123456789012345678901234567890123456789012345678901234
+
+# Ethereum Wallet Address (with 0x prefix)
+# If not provided, will be automatically derived from the private key
+WALLET_ADDRESS=
+
+# ============================================================================
+# OPTIONAL: Room Configuration
+# ============================================================================
+
+# Default room to join on connection
+# general: General purpose room for testing
+# x-agent-enterprise-v2: X-Agent room for Twitter/X features
+DEFAULT_ROOM=general
+
+# ============================================================================
+# OPTIONAL: Security Features
+# ============================================================================
+
+# Enable message signature verification (true | false)
+# Verifies Ethereum signatures on incoming messages from agents
+# Recommended: true for production
+ENABLE_SIGNATURE_VERIFICATION=false
+
+# Comma-separated list of trusted agent Ethereum addresses
+# Only messages signed by these addresses will be accepted (if verification enabled)
+# Leave empty to allow all signed messages
+# Example: 0xAgent1...,0xAgent2...,0xAgent3...
+TRUSTED_ADDRESSES=
+
+# ============================================================================
+# OPTIONAL: SDK Performance Tuning
+# ============================================================================
+
+# Enable agent caching (true | false)
+ENABLE_CACHE=true
+
+# Cache timeout in milliseconds (default: 300000 = 5 minutes)
+CACHE_TIMEOUT=300000
+
+# Maximum cache size (default: 100)
+MAX_CACHE_SIZE=100
+
+# ============================================================================
+# OPTIONAL: Connection Settings
+# ============================================================================
+
+# Enable automatic reconnection (true | false)
+ENABLE_RECONNECTION=true
+
+# Reconnection delay in milliseconds (100-60000)
+RECONNECT_DELAY=5000
+
+# Maximum reconnection attempts (0-100, 0 = infinite)
+MAX_RECONNECT_ATTEMPTS=10
+
+# ============================================================================
+# OPTIONAL: Logging
+# ============================================================================
+
+# Log level (debug | info | warn | error | silent)
+# debug: Very verbose, shows all SDK operations
+# info: Normal operations and important events
+# warn: Warnings and potential issues
+# error: Errors only
+# silent: No logging
+LOG_LEVEL=info
+
+# ============================================================================
+# OPTIONAL: API Server Configuration
+# ============================================================================
+
+# Port for the OpenAI+Teneo Service API (default: 3000)
+PORT=3000
+
+# ============================================================================
+# NOTES
+# ============================================================================
+
+# 1. Environment Precedence:
+#    - Environment variables override .env file values
+#    - .env file overrides default SDK values
+#
+# 2. Security Best Practices:
+#    - Never commit .env file to git (already in .gitignore)
+#    - Use different private keys for dev/prod
+#    - Enable signature verification in production
+#    - Wallet address is auto-derived if not provided
+#    - Keep OpenAI API key secure
+#
+# 3. Development Tips:
+#    - Set LOG_LEVEL=debug for troubleshooting
+#    - Disable signature verification for local testing
+#    - Use 'general' room for basic testing
+#    - Test OpenAI separately via /openai endpoint
+#
+# 4. Production Checklist:
+#    ✓ Use production WebSocket URL
+#    ✓ Use secure private key (from secrets manager)
+#    ✓ Use secure OpenAI API key
+#    ✓ Enable signature verification
+#    ✓ Set trusted agent addresses
+#    ✓ Set LOG_LEVEL=info or warn
+#    ✓ Enable all security features
+#    ✓ Use environment variables (not .env file)