whio-api-sdk 1.0.197-beta-staging → 1.0.198-beta-staging

package/WEBSOCKET_AUDIO_STREAMING.md

@@ -0,0 +1,258 @@
+# WebSocket Audio Streaming
+
+The SDK now supports real-time audio streaming via WebSocket connections, providing an efficient alternative to HTTP-based audio upload for live transcription scenarios.
+
+## Features
+
+- 🔄 **Auto-reconnection** with exponential backoff
+- 📡 **Real-time audio streaming** with float array support
+- 🎯 **Event-driven architecture** for connection and audio events
+- 🛡️ **Automatic authentication** using existing SDK tokens
+- 📊 **Connection statistics** and monitoring
+- 🔧 **Configurable buffering** and reconnection behavior
+
+## Quick Start
+
+```typescript
+import { ApiSDK } from 'whio-api-sdk';
+
+// Initialize SDK with WebSocket support
+const sdk = new ApiSDK({
+  baseUrl: 'https://your-api.com/api',
+  storage: localStorage,
+  websocket: {
+    autoConnect: true,        // Connect immediately on SDK initialization
+    reconnectAttempts: -1,    // Infinite reconnection attempts
+    reconnectDelay: 1000,     // Initial delay between reconnects (ms)
+    maxReconnectDelay: 30000, // Maximum delay between reconnects (ms)
+    namespace: 'connections'   // WebSocket namespace
+  }
+});
+
+// Authenticate first
+await sdk.login('user@example.com', 'password');
+
+// Create a session for audio streaming
+const session = await sdk.createSession({
+  sessionName: 'Live Audio Session',
+  transcript: ''
+});
+```
+
+## Event Handling
+
+Set up event listeners to respond to WebSocket events:
+
+```typescript
+// Connection events
+sdk.onWebSocketEvent('connected', (data) => {
+  console.log('WebSocket connected:', data);
+  // data: { message: string, userId: string, timestamp: string }
+});
+
+sdk.onWebSocketEvent('disconnected', (reason) => {
+  console.log('WebSocket disconnected:', reason);
+});
+
+sdk.onWebSocketEvent('reconnecting', (attemptNumber) => {
+  console.log(`Reconnecting... attempt ${attemptNumber}`);
+});
+
+// Audio streaming events
+sdk.onWebSocketEvent('audio-chunk-received', (data) => {
+  console.log('Audio chunk processed:', data);
+  // data: { sessionId: string, chunkCount: number, timestamp: string }
+});
+
+sdk.onWebSocketEvent('transcription-queued', (data) => {
+  console.log('Transcription started:', data);
+  // data: { sessionId: string, message: string, timestamp: string }
+});
+
+// Error handling
+sdk.onWebSocketEvent('audio-error', (error) => {
+  console.error('Audio streaming error:', error);
+});
+
+sdk.onWebSocketEvent('connection-error', (error) => {
+  console.error('Connection error:', error);
+});
+```
+
+## Audio Streaming
+
+### Single Chunk Streaming
+
+```typescript
+// Stream individual audio chunks
+const audioChunk = [0.1, 0.2, -0.3, 0.4]; // Float array
+sdk.streamAudioChunk(session.id, audioChunk, false);
+
+// Stream final chunk to trigger transcription
+sdk.streamAudioChunk(session.id, finalChunk, true);
+```
+
+### Batch Streaming
+
+```typescript
+// Stream multiple chunks with automatic pacing
+const audioChunks = [
+  [0.1, 0.2, 0.3],
+  [0.4, 0.5, 0.6],
+  [0.7, 0.8, 0.9]
+];
+
+await sdk.streamAudioChunks(session.id, audioChunks, {
+  bufferSize: 100 // Delay between chunks in ms
+});
+```
+
+### Microphone Integration
+
+```typescript
+// Real-time microphone streaming (browser)
+const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+const audioContext = new AudioContext();
+const source = audioContext.createMediaStreamSource(stream);
+const processor = audioContext.createScriptProcessor(4096, 1, 1);
+
+processor.onaudioprocess = (event) => {
+  const inputBuffer = event.inputBuffer;
+  const inputData = inputBuffer.getChannelData(0);
+  
+  // Convert to regular array and stream
+  const audioChunk = Array.from(inputData);
+  sdk.streamAudioChunk(session.id, audioChunk, false);
+};
+
+source.connect(processor);
+processor.connect(audioContext.destination);
+
+// Stop recording and trigger transcription
+setTimeout(() => {
+  sdk.streamAudioChunk(session.id, [], true);
+  // Cleanup...
+}, 10000);
+```
+
+## Connection Management
+
+### Manual Connection Control
+
+```typescript
+// Disable auto-connect and manage manually
+const sdk = new ApiSDK({
+  websocket: { autoConnect: false }
+});
+
+// Connect when ready
+sdk.connectWebSocket();
+
+// Check connection status
+if (sdk.isWebSocketConnected()) {
+  console.log('Ready to stream audio');
+}
+
+// Disconnect when done
+sdk.disconnectWebSocket();
+```
+
+### Connection Statistics
+
+```typescript
+const stats = sdk.getWebSocketStats();
+console.log({
+  isConnected: stats.isConnected,
+  reconnectAttempts: stats.reconnectAttempts,
+  lastConnectedAt: stats.lastConnectedAt,
+  lastDisconnectedAt: stats.lastDisconnectedAt
+});
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `autoConnect` | boolean | `true` | Automatically connect on SDK initialization |
+| `reconnectAttempts` | number | `-1` | Number of reconnection attempts (-1 = infinite) |
+| `reconnectDelay` | number | `1000` | Initial delay between reconnects (ms) |
+| `maxReconnectDelay` | number | `30000` | Maximum delay between reconnects (ms) |
+| `namespace` | string | `'connections'` | WebSocket namespace |
+
+## Audio Buffer Management
+
+The server automatically buffers audio chunks and flushes them when:
+- Buffer reaches 10 chunks
+- Client sends a chunk with `flag: 'end'`
+
+```typescript
+// The server handles buffering automatically
+sdk.streamAudioChunk(sessionId, chunk1, false); // Buffered
+sdk.streamAudioChunk(sessionId, chunk2, false); // Buffered
+// ... (8 more chunks buffered)
+sdk.streamAudioChunk(sessionId, chunk10, false); // Auto-flush triggered
+sdk.streamAudioChunk(sessionId, chunk11, true);  // End flag triggers transcription
+```
+
+## Error Handling
+
+```typescript
+// Handle various error scenarios
+sdk.onWebSocketEvent('connection-error', (error) => {
+  if (error.message.includes('No access token')) {
+    // Re-authenticate
+    await sdk.login(email, password);
+  }
+});
+
+sdk.onWebSocketEvent('audio-error', (error) => {
+  if (error.error === 'sessionId and audioChunk are required') {
+    // Fix payload format
+  }
+});
+
+sdk.onWebSocketEvent('reconnect-failed', () => {
+  // Handle permanent connection failure
+  console.error('Unable to reconnect to WebSocket');
+});
+```
+
+## Best Practices
+
+1. **Authentication First**: Always authenticate before connecting WebSocket
+2. **Event Listeners**: Set up event listeners before connecting
+3. **Error Handling**: Always handle connection and audio errors
+4. **Cleanup**: Disconnect WebSocket when done to free resources
+5. **Chunk Size**: Keep audio chunks reasonably sized (1024-4096 samples)
+6. **End Flag**: Always send final chunk with `flag: 'end'` to trigger transcription
+
+## Browser vs Node.js
+
+The WebSocket functionality works in both browser and Node.js environments:
+
+- **Browser**: Perfect for real-time microphone streaming
+- **Node.js**: Great for processing audio files or streams
+
+## Migration from HTTP
+
+Replace HTTP-based audio upload:
+
+```typescript
+// Old HTTP approach
+await sdk.addBase64Chunk(sessionId, base64Chunks);
+await sdk.queueSessionBase64AudioForTranscription(sessionId);
+
+// New WebSocket approach
+for (const chunk of audioChunks) {
+  const isLast = chunk === audioChunks[audioChunks.length - 1];
+  sdk.streamAudioChunk(sessionId, chunk, isLast);
+}
+// Transcription automatically triggered on end flag
+```
+
+## Troubleshooting
+
+- **Connection Issues**: Check network connectivity and authentication
+- **Audio Not Processing**: Ensure chunks are valid float arrays
+- **Transcription Not Starting**: Verify end flag is sent
+- **Reconnection Problems**: Check server availability and token validity

package/dist/src/sdk/modules/websocket.module.d.ts

@@ -0,0 +1,73 @@
+import { BaseClient } from './base-client';
+import { WebSocketConnectionStats, WebSocketEvents, AudioStreamingOptions } from '../types';
+/**
+ * WebSocket connection manager with auto-reconnect and audio streaming capabilities
+ */
+export declare class WebSocketModule extends BaseClient {
+    private socket;
+    private config;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectDelay;
+    private maxReconnectDelay;
+    private reconnectTimeout;
+    private connectionStats;
+    private eventHandlers;
+    constructor(baseConfig: any);
+    /**
+     * Connect to WebSocket server
+     */
+    connect(): void;
+    /**
+     * Disconnect from WebSocket server
+     */
+    disconnect(): void;
+    /**
+     * Check if WebSocket is connected
+     */
+    isConnected(): boolean;
+    /**
+     * Get connection statistics
+     */
+    getConnectionStats(): WebSocketConnectionStats;
+    /**
+     * Stream audio chunk to server
+     */
+    streamAudioChunk(sessionId: string, audioChunk: number[] | number[][], isEnd?: boolean): void;
+    /**
+     * Stream multiple audio chunks with automatic end detection
+     */
+    streamAudioChunks(sessionId: string, audioChunks: number[], options?: AudioStreamingOptions): Promise<void>;
+    /**
+     * Add event listener
+     */
+    on<K extends keyof WebSocketEvents>(event: K, handler: WebSocketEvents[K]): void;
+    /**
+     * Remove event listener
+     */
+    off<K extends keyof WebSocketEvents>(event: K, handler: WebSocketEvents[K]): void;
+    /**
+     * Emit event to registered handlers
+     */
+    private emit;
+    /**
+     * Setup WebSocket event handlers
+     */
+    private setupEventHandlers;
+    /**
+     * Determine if should attempt reconnection
+     */
+    private shouldReconnect;
+    /**
+     * Schedule reconnection attempt
+     */
+    private scheduleReconnect;
+    /**
+     * Get WebSocket URL
+     */
+    private getWebSocketUrl;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}

package/dist/src/sdk/modules/websocket.module.js

@@ -0,0 +1,253 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { io } from 'socket.io-client';
+import { BaseClient } from './base-client';
+/**
+ * WebSocket connection manager with auto-reconnect and audio streaming capabilities
+ */
+export class WebSocketModule extends BaseClient {
+    constructor(baseConfig) {
+        super(baseConfig);
+        this.socket = null;
+        this.reconnectAttempts = 0;
+        this.reconnectTimeout = null;
+        this.eventHandlers = new Map();
+        const wsConfig = baseConfig.websocket || {};
+        this.config = Object.assign({ autoConnect: true, reconnectAttempts: -1, reconnectDelay: 1000, maxReconnectDelay: 30000, namespace: 'connections' }, wsConfig);
+        this.maxReconnectAttempts = this.config.reconnectAttempts;
+        this.reconnectDelay = this.config.reconnectDelay;
+        this.maxReconnectDelay = this.config.maxReconnectDelay;
+        this.connectionStats = {
+            isConnected: false,
+            reconnectAttempts: 0
+        };
+        if (this.config.autoConnect) {
+            this.connect();
+        }
+    }
+    /**
+     * Connect to WebSocket server
+     */
+    connect() {
+        var _a;
+        if ((_a = this.socket) === null || _a === void 0 ? void 0 : _a.connected) {
+            return;
+        }
+        const wsUrl = this.getWebSocketUrl();
+        const token = this.getAccessToken();
+        if (!token) {
+            this.emit('connection-error', new Error('No access token available for WebSocket connection'));
+            return;
+        }
+        this.socket = io(wsUrl, {
+            auth: {
+                token: token
+            },
+            forceNew: true,
+            timeout: 10000
+        });
+        this.setupEventHandlers();
+    }
+    /**
+     * Disconnect from WebSocket server
+     */
+    disconnect() {
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
+        if (this.socket) {
+            this.socket.disconnect();
+            this.socket = null;
+        }
+        this.connectionStats.isConnected = false;
+        this.connectionStats.lastDisconnectedAt = new Date();
+    }
+    /**
+     * Check if WebSocket is connected
+     */
+    isConnected() {
+        var _a;
+        return ((_a = this.socket) === null || _a === void 0 ? void 0 : _a.connected) || false;
+    }
+    /**
+     * Get connection statistics
+     */
+    getConnectionStats() {
+        return Object.assign({}, this.connectionStats);
+    }
+    /**
+     * Stream audio chunk to server
+     */
+    streamAudioChunk(sessionId, audioChunk, isEnd = false) {
+        var _a;
+        if (!((_a = this.socket) === null || _a === void 0 ? void 0 : _a.connected)) {
+            throw new Error('WebSocket not connected. Cannot stream audio chunk.');
+        }
+        const payload = {
+            sessionId,
+            audioChunk,
+            flag: isEnd ? 'end' : null
+        };
+        this.socket.emit('audio-chunk', payload);
+    }
+    /**
+     * Stream multiple audio chunks with automatic end detection
+     */
+    streamAudioChunks(sessionId, audioChunks, options = {}) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!((_a = this.socket) === null || _a === void 0 ? void 0 : _a.connected)) {
+                throw new Error('WebSocket not connected. Cannot stream audio chunks.');
+            }
+            const chunks = audioChunks;
+            const delay = options.bufferSize || 100; // ms between chunks
+            for (let i = 0; i < chunks.length; i++) {
+                const isLastChunk = i === chunks.length - 1;
+                this.streamAudioChunk(sessionId, chunks, isLastChunk);
+                // Small delay between chunks to prevent overwhelming the server
+                if (!isLastChunk) {
+                    yield new Promise(resolve => setTimeout(resolve, delay));
+                }
+            }
+        });
+    }
+    /**
+     * Add event listener
+     */
+    on(event, handler) {
+        if (!this.eventHandlers.has(event)) {
+            this.eventHandlers.set(event, []);
+        }
+        this.eventHandlers.get(event).push(handler);
+    }
+    /**
+     * Remove event listener
+     */
+    off(event, handler) {
+        const handlers = this.eventHandlers.get(event);
+        if (handlers) {
+            const index = handlers.indexOf(handler);
+            if (index > -1) {
+                handlers.splice(index, 1);
+            }
+        }
+    }
+    /**
+     * Emit event to registered handlers
+     */
+    emit(event, ...args) {
+        const handlers = this.eventHandlers.get(event);
+        if (handlers) {
+            handlers.forEach(handler => {
+                try {
+                    handler(...args);
+                }
+                catch (error) {
+                    console.error(`Error in WebSocket event handler for ${event}:`, error);
+                }
+            });
+        }
+    }
+    /**
+     * Setup WebSocket event handlers
+     */
+    setupEventHandlers() {
+        if (!this.socket)
+            return;
+        // Connection events
+        this.socket.on('connect', () => {
+            this.connectionStats.isConnected = true;
+            this.connectionStats.lastConnectedAt = new Date();
+            this.reconnectAttempts = 0;
+            if (this.reconnectTimeout) {
+                clearTimeout(this.reconnectTimeout);
+                this.reconnectTimeout = null;
+            }
+        });
+        this.socket.on('disconnect', (reason) => {
+            this.connectionStats.isConnected = false;
+            this.connectionStats.lastDisconnectedAt = new Date();
+            this.emit('disconnected', reason);
+            // Auto-reconnect logic
+            if (this.shouldReconnect(reason)) {
+                this.scheduleReconnect();
+            }
+        });
+        this.socket.on('connect_error', (error) => {
+            this.emit('connection-error', error);
+            if (this.shouldReconnect()) {
+                this.scheduleReconnect();
+            }
+        });
+        // Application-specific events
+        this.socket.on('connected', (data) => {
+            this.emit('connected', data);
+        });
+        this.socket.on('audio-chunk-received', (data) => {
+            this.emit('audio-chunk-received', data);
+        });
+        this.socket.on('transcription-queued', (data) => {
+            this.emit('transcription-queued', data);
+        });
+        this.socket.on('audio-error', (error) => {
+            this.emit('audio-error', error);
+        });
+        this.socket.on('transcription-error', (error) => {
+            this.emit('transcription-error', error);
+        });
+    }
+    /**
+     * Determine if should attempt reconnection
+     */
+    shouldReconnect(reason) {
+        // Don't reconnect if manually disconnected
+        if (reason === 'io client disconnect') {
+            return false;
+        }
+        // Check if we've exceeded max attempts
+        if (this.maxReconnectAttempts > 0 && this.reconnectAttempts >= this.maxReconnectAttempts) {
+            this.emit('reconnect-failed');
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Schedule reconnection attempt
+     */
+    scheduleReconnect() {
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+        }
+        this.reconnectAttempts++;
+        this.connectionStats.reconnectAttempts = this.reconnectAttempts;
+        // Calculate exponential backoff delay
+        const delay = Math.min(this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1), this.maxReconnectDelay);
+        this.emit('reconnecting', this.reconnectAttempts);
+        this.reconnectTimeout = setTimeout(() => {
+            this.connect();
+        }, delay);
+    }
+    /**
+     * Get WebSocket URL
+     */
+    getWebSocketUrl() {
+        const wsProtocol = this.baseUrl.startsWith('https') ? 'wss' : 'ws';
+        const baseWsUrl = this.baseUrl.replace(/^https?/, wsProtocol);
+        return `${baseWsUrl}/${this.config.namespace}`;
+    }
+    /**
+     * Clean up resources
+     */
+    destroy() {
+        this.disconnect();
+        this.eventHandlers.clear();
+    }
+}

package/dist/src/sdk/sdk.d.ts

@@ -12,6 +12,7 @@ import { WorkflowModule } from './modules/workflow.module';
 import { LogModule } from './modules/log.module';
 import { DebugModule } from './modules/debug.module';
 import { ExternalIntegrationModule } from './modules/external-integration.module';
+import { WebSocketModule } from './modules/websocket.module';
 /**
  * Main SDK class that provides access to all domain-specific modules
  */
@@ -28,6 +29,7 @@ export declare class ApiSDK extends BaseClient {
     readonly logs: LogModule;
     readonly debug: DebugModule;
     readonly externalIntegrations: ExternalIntegrationModule;
+    readonly websocket: WebSocketModule;
     constructor(config?: SDKConfig);
     login(...args: Parameters<AuthModule['login']>): Promise<import("./types").LoginResponse>;
     logout(...args: Parameters<AuthModule['logout']>): Promise<void>;
@@ -181,4 +183,12 @@ export declare class ApiSDK extends BaseClient {
     getExternalIntegration(...args: Parameters<ExternalIntegrationModule['getExternalIntegration']>): Promise<import("./types").ExternalIntegration>;
     updateExternalIntegration(...args: Parameters<ExternalIntegrationModule['updateExternalIntegration']>): Promise<import("./types").ExternalIntegration>;
     deleteExternalIntegration(...args: Parameters<ExternalIntegrationModule['deleteExternalIntegration']>): Promise<void>;
+    connectWebSocket(): void;
+    disconnectWebSocket(): void;
+    isWebSocketConnected(): boolean;
+    streamAudioChunk(...args: Parameters<WebSocketModule['streamAudioChunk']>): void;
+    streamAudioChunks(...args: Parameters<WebSocketModule['streamAudioChunks']>): Promise<void>;
+    onWebSocketEvent(...args: Parameters<WebSocketModule['on']>): void;
+    offWebSocketEvent(...args: Parameters<WebSocketModule['off']>): void;
+    getWebSocketStats(): import("./types").WebSocketConnectionStats;
 }

package/dist/src/sdk/sdk.js

@@ -20,6 +20,7 @@ import { WorkflowModule } from './modules/workflow.module';
 import { LogModule } from './modules/log.module';
 import { DebugModule } from './modules/debug.module';
 import { ExternalIntegrationModule } from './modules/external-integration.module';
+import { WebSocketModule } from './modules/websocket.module';
 /**
  * Main SDK class that provides access to all domain-specific modules
  */
@@ -39,6 +40,7 @@ export class ApiSDK extends BaseClient {
         this.logs = new LogModule(config);
         this.debug = new DebugModule(config);
         this.externalIntegrations = new ExternalIntegrationModule(config);
+        this.websocket = new WebSocketModule(config);
     }
     // ======================
     // BACKWARD COMPATIBILITY LAYER
@@ -761,4 +763,29 @@ export class ApiSDK extends BaseClient {
             return this.externalIntegrations.deleteExternalIntegration(...args);
         });
     }
+    // WebSocket methods
+    connectWebSocket() {
+        return this.websocket.connect();
+    }
+    disconnectWebSocket() {
+        return this.websocket.disconnect();
+    }
+    isWebSocketConnected() {
+        return this.websocket.isConnected();
+    }
+    streamAudioChunk(...args) {
+        return this.websocket.streamAudioChunk(...args);
+    }
+    streamAudioChunks(...args) {
+        return this.websocket.streamAudioChunks(...args);
+    }
+    onWebSocketEvent(...args) {
+        return this.websocket.on(...args);
+    }
+    offWebSocketEvent(...args) {
+        return this.websocket.off(...args);
+    }
+    getWebSocketStats() {
+        return this.websocket.getConnectionStats();
+    }
 }

package/dist/src/sdk/types/common.types.d.ts

@@ -1,3 +1,4 @@
+import { WebSocketConfig } from './websocket.types';
 export interface SDKConfig {
     baseUrl?: string;
     storage?: {
@@ -5,6 +6,7 @@ export interface SDKConfig {
         setItem: (key: string, value: string) => void | Promise<void>;
         removeItem: (key: string) => void | Promise<void>;
     };
+    websocket?: WebSocketConfig;
 }
 export interface Role {
     id: string;

package/dist/src/sdk/types/common.types.js

@@ -1,4 +1,3 @@
-// Common types used across the SDK
 // Enum for global role types to match API
 export var RoleType;
 (function (RoleType) {

package/dist/src/sdk/types/index.d.ts

@@ -10,3 +10,4 @@ export * from './audio.types';
 export * from './workflow.types';
 export * from './log.types';
 export * from './external-integration.types';
+export * from './websocket.types';

package/dist/src/sdk/types/index.js

@@ -11,3 +11,4 @@ export * from './audio.types';
 export * from './workflow.types';
 export * from './log.types';
 export * from './external-integration.types';
+export * from './websocket.types';