ttp-agent-sdk 2.0.0

package/src/core/WebSocketManager.js

@@ -0,0 +1,218 @@
+/**
+ * WebSocketManager - Handles WebSocket connection and message routing
+ */
+import EventEmitter from './EventEmitter.js';
+import connectionManager from './ConnectionManager.js';
+
+export default class WebSocketManager extends EventEmitter {
+  constructor(config) {
+    super();
+    this.config = config;
+    this.ws = null;
+    this.isConnected = false;
+    this.reconnectAttempts = 0;
+    this.maxReconnectAttempts = config.autoReconnect !== false ? 3 : 0; // Disable auto-reconnect if explicitly set to false
+    this.isReconnecting = false;
+    this.isConnecting = false; // Track if we're currently trying to connect
+    this.connectionId = null; // Unique ID for this connection attempt
+  }
+  
+  /**
+   * Connect to WebSocket
+   */
+  async connect() {
+    return new Promise((resolve, reject) => {
+      try {
+        // Prevent multiple connections
+        if (this.ws && (this.ws.readyState === WebSocket.CONNECTING || this.ws.readyState === WebSocket.OPEN)) {
+          resolve();
+          return;
+        }
+        
+        // Prevent connection if already reconnecting
+        if (this.isReconnecting) {
+          resolve();
+          return;
+        }
+        
+        // Prevent connection if already connecting
+        if (this.isConnecting) {
+          resolve();
+          return;
+        }
+        
+        // Check if connection is allowed by global manager
+        if (!connectionManager.isConnectionAllowed(this.config.websocketUrl)) {
+          console.log(`🔌 WebSocketManager: Connection blocked by global manager for ${this.config.websocketUrl}`);
+          resolve();
+          return;
+        }
+        
+        this.isConnecting = true;
+        this.connectionId = Date.now() + '_' + Math.random().toString(36).substr(2, 9);
+        
+        // Register with global connection manager
+        if (!connectionManager.registerConnection(this.config.websocketUrl, this.connectionId)) {
+          console.log(`🔌 WebSocketManager: Connection registration failed for ${this.connectionId}`);
+          this.isConnecting = false;
+          resolve();
+          return;
+        }
+        
+        console.log(`🔌 WebSocketManager: Starting connection attempt ${this.connectionId}`);
+        this.ws = new WebSocket(this.config.websocketUrl);
+        
+        this.ws.onopen = () => {
+          console.log(`🔌 WebSocketManager: Connection successful ${this.connectionId}`);
+          this.isConnected = true;
+          this.reconnectAttempts = 0;
+          this.isReconnecting = false;
+          this.isConnecting = false;
+          this.emit('connected');
+          resolve();
+        };
+        
+        this.ws.onmessage = (event) => {
+          this.handleMessage(event);
+        };
+        
+        this.ws.onclose = (event) => {
+          console.log(`🔌 WebSocketManager: Connection closed ${this.connectionId} (Code: ${event.code})`);
+          this.isConnected = false;
+          this.isConnecting = false;
+          this.emit('disconnected', event);
+          
+          // Attempt reconnection if not intentional and not already reconnecting
+          if (event.code !== 1000 && this.reconnectAttempts < this.maxReconnectAttempts && !this.isReconnecting) {
+            this.isReconnecting = true;
+            this.reconnectAttempts++;
+            console.log(`🔌 WebSocketManager: Attempting reconnection ${this.reconnectAttempts}/${this.maxReconnectAttempts}`);
+            setTimeout(() => {
+              this.isReconnecting = false;
+              this.connect().catch(() => {
+                // Ignore reconnection errors to prevent infinite loops
+              });
+            }, 1000 * this.reconnectAttempts);
+          }
+        };
+        
+        this.ws.onerror = (error) => {
+          console.log(`🔌 WebSocketManager: Connection error ${this.connectionId}`, error);
+          this.isConnecting = false;
+          this.emit('error', error);
+          reject(error);
+        };
+        
+      } catch (error) {
+        console.log(`🔌 WebSocketManager: Connection failed ${this.connectionId}`, error);
+        this.isConnecting = false;
+        reject(error);
+      }
+    });
+  }
+  
+  /**
+   * Disconnect from WebSocket
+   */
+  disconnect() {
+    // Stop any reconnection attempts
+    this.isReconnecting = false;
+    this.reconnectAttempts = this.maxReconnectAttempts; // Prevent reconnection
+    
+    // Unregister from global connection manager
+    if (this.connectionId) {
+      connectionManager.unregisterConnection(this.config.websocketUrl, this.connectionId);
+    }
+    
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.close(1000, 'Intentional disconnect');
+    }
+    this.ws = null;
+    this.isConnected = false;
+    this.isConnecting = false;
+  }
+  
+  /**
+   * Reset reconnection attempts (useful for manual reconnection)
+   */
+  resetReconnectionAttempts() {
+    this.reconnectAttempts = 0;
+    this.isReconnecting = false;
+  }
+  
+  /**
+   * Clear all global connections (useful for testing)
+   */
+  static clearAllConnections() {
+    connectionManager.clearAll();
+  }
+  
+  /**
+   * Send JSON message
+   */
+  sendMessage(message) {
+    if (!this.isConnected || !this.ws) {
+      throw new Error('WebSocket not connected');
+    }
+    
+    this.ws.send(JSON.stringify(message));
+  }
+  
+  /**
+   * Send binary data
+   */
+  sendBinary(data) {
+    if (!this.isConnected || !this.ws) {
+      throw new Error('WebSocket not connected');
+    }
+    
+    this.ws.send(data);
+  }
+  
+  /**
+   * Handle incoming WebSocket messages
+   */
+  handleMessage(event) {
+    // Check if it's binary data first
+    if (event.data instanceof ArrayBuffer) {
+      this.emit('binaryAudio', event.data);
+      return;
+    } else if (event.data instanceof Blob) {
+      event.data.arrayBuffer().then(arrayBuffer => {
+        this.emit('binaryAudio', arrayBuffer);
+      }).catch(err => {
+        this.emit('error', err);
+      });
+      return;
+    }
+    
+    // Handle JSON messages
+    try {
+      const message = JSON.parse(event.data);
+      
+      // Handle barge-in related messages
+      if (message.t === 'barge_in_ack' || message.t === 'stop_sending') {
+        this.emit('bargeIn', message);
+      }
+      
+      // Handle stop playing message
+      if (message.t === 'stop_playing') {
+        this.emit('stopPlaying', message);
+      }
+      
+      this.emit('message', message);
+    } catch (error) {
+      this.emit('error', error);
+    }
+  }
+  
+  /**
+   * Get connection status
+   */
+  getStatus() {
+    return {
+      isConnected: this.isConnected,
+      readyState: this.ws ? this.ws.readyState : WebSocket.CLOSED
+    };
+  }
+}

package/src/core/WebSocketManagerV2.js

@@ -0,0 +1,211 @@
+/**
+ * WebSocketManagerV2 - Uses singleton pattern to prevent multiple connections
+ */
+import EventEmitter from './EventEmitter.js';
+import webSocketSingleton from './WebSocketSingleton.js';
+
+export default class WebSocketManagerV2 extends EventEmitter {
+  constructor(config) {
+    super();
+    this.config = config;
+    this.ws = null;
+    this.isConnected = false;
+    this.connectionId = null;
+  }
+  
+  /**
+   * Connect to WebSocket using singleton
+   */
+  async connect() {
+    return new Promise((resolve, reject) => {
+      try {
+        this.connectionId = Date.now() + '_' + Math.random().toString(36).substr(2, 9);
+        console.log(`🔌 WebSocketManagerV2: Requesting connection ${this.connectionId} for ${this.config.websocketUrl}`);
+        
+        // Get connection from singleton
+        webSocketSingleton.getConnection(this.config.websocketUrl, this.config)
+          .then((connection) => {
+            this.ws = connection;
+            console.log(`🔌 WebSocketManagerV2: Got connection ${this.connectionId}`);
+            
+            // Set up event listeners
+            this.setupEventListeners();
+            
+            // If already connected, resolve immediately
+            if (connection.readyState === WebSocket.OPEN) {
+              this.isConnected = true;
+              this.emit('connected');
+              resolve();
+            }
+          })
+          .catch((error) => {
+            console.error(`🔌 WebSocketManagerV2: Connection failed ${this.connectionId}`, error);
+            reject(error);
+          });
+        
+      } catch (error) {
+        console.error(`🔌 WebSocketManagerV2: Connection error ${this.connectionId}`, error);
+        reject(error);
+      }
+    });
+  }
+  
+  /**
+   * Set up event listeners
+   */
+  setupEventListeners() {
+    if (!this.ws) return;
+    
+    // Use singleton's event forwarding
+    const handleOpen = (event, url) => {
+      if (url === this.config.websocketUrl) {
+        console.log(`🔌 WebSocketManagerV2: Connection opened ${this.connectionId}`);
+        this.isConnected = true;
+        this.emit('connected');
+      }
+    };
+    
+    const handleClose = (event, url) => {
+      if (url === this.config.websocketUrl) {
+        console.log(`🔌 WebSocketManagerV2: Connection closed ${this.connectionId} (Code: ${event.code})`);
+        this.isConnected = false;
+        this.emit('disconnected', event);
+      }
+    };
+    
+    const handleError = (event, url) => {
+      if (url === this.config.websocketUrl) {
+        console.log(`🔌 WebSocketManagerV2: Connection error ${this.connectionId}`, event);
+        this.emit('error', event);
+      }
+    };
+    
+    const handleMessage = (event, url) => {
+      if (url === this.config.websocketUrl) {
+        this.handleMessage(event);
+      }
+    };
+    
+    // Add event listeners
+    webSocketSingleton.on('open', handleOpen);
+    webSocketSingleton.on('close', handleClose);
+    webSocketSingleton.on('error', handleError);
+    webSocketSingleton.on('message', handleMessage);
+    
+    // Store handlers for cleanup
+    this.eventHandlers = {
+      open: handleOpen,
+      close: handleClose,
+      error: handleError,
+      message: handleMessage
+    };
+  }
+  
+  /**
+   * Disconnect from WebSocket
+   */
+  disconnect() {
+    console.log(`🔌 WebSocketManagerV2: Disconnecting ${this.connectionId}`);
+    
+    // Remove event listeners
+    if (this.eventHandlers) {
+      webSocketSingleton.off('open', this.eventHandlers.open);
+      webSocketSingleton.off('close', this.eventHandlers.close);
+      webSocketSingleton.off('error', this.eventHandlers.error);
+      webSocketSingleton.off('message', this.eventHandlers.message);
+    }
+    
+    // Release connection from singleton
+    if (this.config.websocketUrl) {
+      console.log(`🔌 WebSocketManagerV2: Releasing connection ${this.connectionId} from singleton`);
+      webSocketSingleton.releaseConnection(this.config.websocketUrl);
+    }
+    
+    this.ws = null;
+    this.isConnected = false;
+  }
+  
+  /**
+   * Send JSON message
+   */
+  sendMessage(message) {
+    if (!this.isConnected || !this.ws) {
+      throw new Error('WebSocket not connected');
+    }
+    
+    this.ws.send(JSON.stringify(message));
+  }
+  
+  /**
+   * Send binary data
+   */
+  sendBinary(data) {
+    if (!this.isConnected || !this.ws) {
+      throw new Error('WebSocket not connected');
+    }
+    
+    this.ws.send(data);
+  }
+  
+  /**
+   * Handle incoming messages
+   */
+  handleMessage(event) {
+    // Check if it's binary data
+    if (event.data instanceof ArrayBuffer) {
+      this.emit('binaryAudio', event.data);
+      return;
+    } else if (event.data instanceof Blob) {
+      event.data.arrayBuffer().then(arrayBuffer => {
+        this.emit('binaryAudio', arrayBuffer);
+      }).catch(err => {
+        console.error('🔌 WebSocketManagerV2: Error converting Blob to ArrayBuffer:', err);
+      });
+      return;
+    }
+    
+    // Handle JSON messages
+    try {
+      const message = JSON.parse(event.data);
+      
+      // Handle barge-in related messages
+      if (message.t === 'barge_in_ack' || message.t === 'stop_sending') {
+        this.emit('bargeIn', message);
+      }
+      
+      // Handle stop playing message
+      if (message.t === 'stop_playing') {
+        this.emit('stopPlaying', message);
+      }
+      
+      this.emit('message', message);
+    } catch (error) {
+      this.emit('error', error);
+    }
+  }
+  
+  /**
+   * Get connection status
+   */
+  getStatus() {
+    return {
+      isConnected: this.isConnected,
+      readyState: this.ws ? this.ws.readyState : null,
+      connectionId: this.connectionId
+    };
+  }
+  
+  /**
+   * Get singleton status (for debugging)
+   */
+  static getSingletonStatus() {
+    return webSocketSingleton.getAllConnections();
+  }
+  
+  /**
+   * Clear all singleton connections (for testing)
+   */
+  static clearAllConnections() {
+    webSocketSingleton.clearAll();
+  }
+}

package/src/core/WebSocketSingleton.js

@@ -0,0 +1,171 @@
+/**
+ * WebSocketSingleton - Ensures only one WebSocket connection per URL exists
+ */
+import EventEmitter from './EventEmitter.js';
+
+class WebSocketSingleton extends EventEmitter {
+  constructor() {
+    super();
+    this.connections = new Map(); // Map of URL -> WebSocket instance
+    this.connectionCounts = new Map(); // Map of URL -> number of subscribers
+    this.creatingConnections = new Set(); // Set of URLs currently being created
+  }
+  
+  /**
+   * Get or create a WebSocket connection
+   */
+  async getConnection(url, config = {}) {
+    // If connection already exists, just return it
+    if (this.connections.has(url)) {
+      const existingConnection = this.connections.get(url);
+      this.connectionCounts.set(url, (this.connectionCounts.get(url) || 0) + 1);
+      console.log(`🔌 WebSocketSingleton: Reusing existing connection for ${url} (${this.connectionCounts.get(url)} subscribers)`);
+      return existingConnection;
+    }
+    
+    // Check if we're already in the process of creating a connection
+    if (this.creatingConnections && this.creatingConnections.has(url)) {
+      console.log(`🔌 WebSocketSingleton: Connection already being created for ${url}, waiting...`);
+      // Wait for the existing creation to complete
+      return new Promise((resolve) => {
+        const checkConnection = () => {
+          if (this.connections.has(url)) {
+            const existingConnection = this.connections.get(url);
+            this.connectionCounts.set(url, (this.connectionCounts.get(url) || 0) + 1);
+            console.log(`🔌 WebSocketSingleton: Got existing connection after wait for ${url} (${this.connectionCounts.get(url)} subscribers)`);
+            resolve(existingConnection);
+          } else {
+            setTimeout(checkConnection, 50);
+          }
+        };
+        checkConnection();
+      });
+    }
+    
+    // Create new connection
+    console.log(`🔌 WebSocketSingleton: Creating new connection for ${url}`);
+    this.creatingConnections.add(url);
+    const connection = new WebSocket(url);
+    this.connections.set(url, connection);
+    this.connectionCounts.set(url, 1);
+    
+    // Set up event forwarding
+    connection.addEventListener('open', (event) => {
+      console.log(`🔌 WebSocketSingleton: Connection opened for ${url}`);
+      this.creatingConnections.delete(url);
+      this.emit('open', event, url);
+    });
+    
+    connection.addEventListener('close', (event) => {
+      console.log(`🔌 WebSocketSingleton: Connection closed for ${url} (Code: ${event.code})`);
+      this.creatingConnections.delete(url);
+      this.connections.delete(url);
+      this.connectionCounts.delete(url);
+      this.emit('close', event, url);
+    });
+    
+    connection.addEventListener('error', (event) => {
+      console.log(`🔌 WebSocketSingleton: Connection error for ${url}`, event);
+      this.creatingConnections.delete(url);
+      this.emit('error', event, url);
+    });
+    
+    connection.addEventListener('message', (event) => {
+      this.emit('message', event, url);
+    });
+    
+    return connection;
+  }
+  
+  /**
+   * Release a connection (decrement subscriber count)
+   */
+  releaseConnection(url) {
+    if (!this.connections.has(url)) {
+      console.log(`🔌 WebSocketSingleton: Attempted to release non-existent connection for ${url}`);
+      return;
+    }
+    
+    const currentCount = this.connectionCounts.get(url) || 0;
+    const newCount = Math.max(0, currentCount - 1);
+    this.connectionCounts.set(url, newCount);
+    
+    console.log(`🔌 WebSocketSingleton: Released connection for ${url} (${newCount} subscribers remaining)`);
+    
+    // If no more subscribers, close the connection
+    if (newCount === 0) {
+      const connection = this.connections.get(url);
+      if (connection && connection.readyState === WebSocket.OPEN) {
+        console.log(`🔌 WebSocketSingleton: Closing connection for ${url} (no more subscribers)`);
+        connection.close(1000, 'No more subscribers');
+      }
+      this.connections.delete(url);
+      this.connectionCounts.delete(url);
+    }
+  }
+  
+  /**
+   * Force close a connection
+   */
+  forceClose(url) {
+    if (this.connections.has(url)) {
+      const connection = this.connections.get(url);
+      if (connection && connection.readyState === WebSocket.OPEN) {
+        console.log(`🔌 WebSocketSingleton: Force closing connection for ${url}`);
+        connection.close(1000, 'Force close');
+      }
+      this.connections.delete(url);
+      this.connectionCounts.delete(url);
+    }
+  }
+  
+  /**
+   * Get connection status
+   */
+  getConnectionStatus(url) {
+    if (!this.connections.has(url)) {
+      return { exists: false, readyState: null, subscribers: 0 };
+    }
+    
+    const connection = this.connections.get(url);
+    return {
+      exists: true,
+      readyState: connection.readyState,
+      subscribers: this.connectionCounts.get(url) || 0
+    };
+  }
+  
+  /**
+   * Get all active connections
+   */
+  getAllConnections() {
+    const result = {};
+    for (const [url, connection] of this.connections.entries()) {
+      result[url] = {
+        readyState: connection.readyState,
+        subscribers: this.connectionCounts.get(url) || 0
+      };
+    }
+    return result;
+  }
+  
+  /**
+   * Clear all connections (for testing)
+   */
+  clearAll() {
+    console.log(`🔌 WebSocketSingleton: Clearing all connections`);
+    for (const [url, connection] of this.connections.entries()) {
+      if (connection && connection.readyState === WebSocket.OPEN) {
+        connection.close(1000, 'Clear all');
+      }
+    }
+    this.connections.clear();
+    this.connectionCounts.clear();
+    this.creatingConnections.clear();
+  }
+}
+
+// Global singleton instance
+const webSocketSingleton = new WebSocketSingleton();
+
+export default webSocketSingleton;

package/src/index.js

@@ -0,0 +1,64 @@
+/**
+ * TTP Agent SDK - Main Entry Point
+ * 
+ * A comprehensive SDK for voice interaction with AI agents.
+ * Provides real-time audio recording, WebSocket communication, and audio playback.
+ * 
+ * Features:
+ * - 🎤 Real-time Audio Recording with AudioWorklet
+ * - 🔄 WebSocket Communication with authentication
+ * - 🔊 Audio Playback with queue management
+ * - ⚛️ React Components
+ * - 🌐 Vanilla JavaScript Components
+ * - 🎯 Event-driven architecture
+ * - 🔒 Multiple authentication methods
+ */
+
+// Core SDK
+import VoiceSDK from './core/VoiceSDK.js';
+import WebSocketManager from './core/WebSocketManager.js';
+import WebSocketManagerV2 from './core/WebSocketManagerV2.js';
+import AudioRecorder from './core/AudioRecorder.js';
+import AudioPlayer from './core/AudioPlayer.js';
+import EventEmitter from './core/EventEmitter.js';
+
+// React components
+import VoiceButton from './react/VoiceButton.jsx';
+
+// Vanilla JavaScript components
+import VanillaVoiceButton from './vanilla/VoiceButton.js';
+
+// Legacy AgentSDK (for backward compatibility)
+import { AgentSDK, AgentWidget } from './legacy/AgentSDK.js';
+
+// Version
+export const VERSION = '2.0.0';
+
+// Named exports
+export {
+  VoiceSDK,
+  WebSocketManager,
+  WebSocketManagerV2,
+  AudioRecorder,
+  AudioPlayer,
+  EventEmitter,
+  VoiceButton,
+  VanillaVoiceButton,
+  AgentSDK,
+  AgentWidget
+};
+
+// Default export for convenience
+export default {
+  VoiceSDK,
+  WebSocketManager,
+  WebSocketManagerV2,
+  AudioRecorder,
+  AudioPlayer,
+  EventEmitter,
+  VoiceButton,
+  VanillaVoiceButton,
+  AgentSDK,
+  AgentWidget,
+  VERSION
+};