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

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

@@ -0,0 +1,50 @@
+export interface AudioChunkPayload {
+    sessionId: string;
+    audioChunk: number[] | number[][];
+    flag: 'end' | null;
+}
+export interface WebSocketConfig {
+    autoConnect?: boolean;
+    reconnectAttempts?: number;
+    reconnectDelay?: number;
+    maxReconnectDelay?: number;
+    namespace?: string;
+}
+export interface WebSocketConnectionStats {
+    isConnected: boolean;
+    reconnectAttempts: number;
+    lastConnectedAt?: Date;
+    lastDisconnectedAt?: Date;
+}
+export interface AudioStreamingOptions {
+    bufferSize?: number;
+    autoTranscribe?: boolean;
+}
+export interface WebSocketEvents {
+    connected: (data: {
+        message: string;
+        userId: string;
+        timestamp: string;
+    }) => void;
+    disconnected: (reason: string) => void;
+    'audio-chunk-received': (data: {
+        sessionId: string;
+        chunkCount: number;
+        timestamp: string;
+    }) => void;
+    'transcription-queued': (data: {
+        sessionId: string;
+        message: string;
+        timestamp: string;
+    }) => void;
+    'audio-error': (error: {
+        error: string;
+    }) => void;
+    'transcription-error': (error: {
+        sessionId: string;
+        error: string;
+    }) => void;
+    'connection-error': (error: Error) => void;
+    'reconnecting': (attemptNumber: number) => void;
+    'reconnect-failed': () => void;
+}

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

@@ -0,0 +1,2 @@
+// WebSocket related types
+export {};

package/examples/websocket-audio-streaming.ts

@@ -0,0 +1,204 @@
+import { ApiSDK } from '../src/sdk/sdk';
+
+// Example demonstrating WebSocket audio streaming
+async function exampleWebSocketAudioStreaming() {
+  // Initialize SDK with WebSocket configuration
+  const sdk = new ApiSDK({
+    baseUrl: 'http://localhost:3000/api',
+    storage: {
+      getItem: (key: string) => localStorage.getItem(key),
+      setItem: (key: string, value: string) => localStorage.setItem(key, value),
+      removeItem: (key: string) => localStorage.removeItem(key)
+    },
+    websocket: {
+      autoConnect: true,
+      reconnectAttempts: -1, // Infinite reconnection attempts
+      reconnectDelay: 1000,
+      maxReconnectDelay: 30000,
+      namespace: 'connections'
+    }
+  });
+
+  // First, authenticate
+  try {
+    await sdk.login('user@example.com', 'password');
+    console.log('Authenticated successfully');
+  } catch (error) {
+    console.error('Authentication failed:', error);
+    return;
+  }
+
+  // Create a session for audio streaming
+  const session = await sdk.createSession({
+    sessionName: 'WebSocket Audio Test',
+    transcript: ''
+  });
+  
+  console.log('Created session:', session.id);
+
+  // Set up WebSocket event listeners
+  sdk.onWebSocketEvent('connected', (data) => {
+    console.log('WebSocket connected:', data);
+  });
+
+  sdk.onWebSocketEvent('disconnected', (reason) => {
+    console.log('WebSocket disconnected:', reason);
+  });
+
+  sdk.onWebSocketEvent('audio-chunk-received', (data) => {
+    console.log('Audio chunk received:', data);
+  });
+
+  sdk.onWebSocketEvent('transcription-queued', (data) => {
+    console.log('Transcription queued:', data);
+  });
+
+  sdk.onWebSocketEvent('audio-error', (error) => {
+    console.error('Audio error:', error);
+  });
+
+  sdk.onWebSocketEvent('connection-error', (error) => {
+    console.error('Connection error:', error);
+  });
+
+  sdk.onWebSocketEvent('reconnecting', (attemptNumber) => {
+    console.log(`Reconnecting... attempt ${attemptNumber}`);
+  });
+
+  // Wait for WebSocket connection
+  while (!sdk.isWebSocketConnected()) {
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+
+  console.log('WebSocket connected, starting audio streaming...');
+
+  // Simulate audio data (in a real app, this would come from microphone)
+  const simulateAudioChunks = (): number[][] => {
+    const chunks: number[][] = [];
+    for (let i = 0; i < 15; i++) {
+      const chunk: number[] = [];
+      for (let j = 0; j < 1024; j++) {
+        // Generate random audio samples between -1 and 1
+        chunk.push((Math.random() - 0.5) * 2);
+      }
+      chunks.push(chunk);
+    }
+    return chunks;
+  };
+
+  const audioChunks = simulateAudioChunks();
+
+  // Stream audio chunks one by one
+  for (let i = 0; i < audioChunks.length; i++) {
+    const isLastChunk = i === audioChunks.length - 1;
+    
+    console.log(`Streaming chunk ${i + 1}/${audioChunks.length}`);
+    sdk.streamAudioChunk(session.id, audioChunks[i], isLastChunk);
+    
+    // Small delay between chunks
+    await new Promise(resolve => setTimeout(resolve, 200));
+  }
+
+  console.log('Finished streaming audio chunks');
+
+  // Alternative: Stream all chunks at once
+  // await sdk.streamAudioChunks(session.id, audioChunks);
+
+  // Keep the connection alive for a bit to see the responses
+  await new Promise(resolve => setTimeout(resolve, 5000));
+
+  // Clean up
+  sdk.disconnectWebSocket();
+  console.log('WebSocket disconnected');
+}
+
+// Example of handling microphone input (browser environment)
+async function exampleMicrophoneStreaming() {
+  const sdk = new ApiSDK({
+    baseUrl: 'http://localhost:3000/api',
+    storage: {
+      getItem: (key: string) => localStorage.getItem(key),
+      setItem: (key: string, value: string) => localStorage.setItem(key, value),
+      removeItem: (key: string) => localStorage.removeItem(key)
+    }
+  });
+
+  // Authenticate and create session
+  await sdk.login('user@example.com', 'password');
+  const session = await sdk.createSession({
+    sessionName: 'Microphone Streaming',
+    transcript: ''
+  });
+
+  // Set up WebSocket events
+  sdk.onWebSocketEvent('connected', (data) => {
+    console.log('Ready for microphone streaming');
+  });
+
+  sdk.onWebSocketEvent('audio-chunk-received', (data) => {
+    console.log(`Buffer count: ${data.chunkCount}`);
+  });
+
+  sdk.onWebSocketEvent('transcription-queued', (data) => {
+    console.log('Transcription started for session:', data.sessionId);
+  });
+
+  // Wait for connection
+  while (!sdk.isWebSocketConnected()) {
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+
+  // Get microphone access
+  try {
+    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 Float32Array to regular array
+      const audioChunk = Array.from(inputData);
+      
+      // Stream the audio chunk
+      sdk.streamAudioChunk(session.id, audioChunk, false);
+    };
+
+    source.connect(processor);
+    processor.connect(audioContext.destination);
+
+    console.log('Microphone streaming started. Recording for 10 seconds...');
+
+    // Stop after 10 seconds and trigger transcription
+    setTimeout(() => {
+      // Send empty chunk with end flag to trigger transcription
+      sdk.streamAudioChunk(session.id, [], true);
+      
+      // Clean up
+      processor.disconnect();
+      source.disconnect();
+      stream.getTracks().forEach(track => track.stop());
+      
+      console.log('Recording stopped, transcription queued');
+    }, 10000);
+
+  } catch (error) {
+    console.error('Error accessing microphone:', error);
+  }
+}
+
+// Run the example
+if (typeof window !== 'undefined') {
+  // Browser environment
+  console.log('Browser environment detected');
+  // Uncomment to run microphone example
+  // exampleMicrophoneStreaming();
+} else {
+  // Node.js environment
+  console.log('Node.js environment detected');
+  exampleWebSocketAudioStreaming();
+}
+
+export { exampleWebSocketAudioStreaming, exampleMicrophoneStreaming };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whio-api-sdk",
-  "version": "1.0.197-beta-staging",
+  "version": "1.0.198-beta-staging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -11,6 +11,7 @@
   },
   "dependencies": {
     "jwt-decode": "^4.0.0",
+    "socket.io-client": "^4.8.1",
     "typescript": "^4.0.0"
   },
   "devDependencies": {

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

@@ -0,0 +1,325 @@
+import { io, Socket } from 'socket.io-client';
+import { BaseClient } from './base-client';
+import { 
+  WebSocketConfig, 
+  WebSocketConnectionStats, 
+  WebSocketEvents,
+  AudioChunkPayload,
+  AudioStreamingOptions 
+} from '../types';
+
+/**
+ * WebSocket connection manager with auto-reconnect and audio streaming capabilities
+ */
+export class WebSocketModule extends BaseClient {
+  private socket: Socket | null = null;
+  private config: WebSocketConfig;
+  private reconnectAttempts = 0;
+  private maxReconnectAttempts: number;
+  private reconnectDelay: number;
+  private maxReconnectDelay: number;
+  private reconnectTimeout: NodeJS.Timeout | null = null;
+  private connectionStats: WebSocketConnectionStats;
+  private eventHandlers: Map<keyof WebSocketEvents, Function[]> = new Map();
+
+  constructor(baseConfig: any) {
+    super(baseConfig);
+    
+    const wsConfig = baseConfig.websocket || {};
+    this.config = {
+      autoConnect: true,
+      reconnectAttempts: -1, // Infinite attempts
+      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
+   */
+  public connect(): void {
+    if (this.socket?.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
+   */
+  public disconnect(): void {
+    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
+   */
+  public isConnected(): boolean {
+    return this.socket?.connected || false;
+  }
+
+  /**
+   * Get connection statistics
+   */
+  public getConnectionStats(): WebSocketConnectionStats {
+    return { ...this.connectionStats };
+  }
+
+  /**
+   * Stream audio chunk to server
+   */
+  public streamAudioChunk(
+    sessionId: string, 
+    audioChunk: number[] | number[][], 
+    isEnd: boolean = false
+  ): void {
+    if (!this.socket?.connected) {
+      throw new Error('WebSocket not connected. Cannot stream audio chunk.');
+    }
+
+    const payload: AudioChunkPayload = {
+      sessionId,
+      audioChunk,
+      flag: isEnd ? 'end' : null
+    };
+
+    this.socket.emit('audio-chunk', payload);
+  }
+
+  /**
+   * Stream multiple audio chunks with automatic end detection
+   */
+  public async streamAudioChunks(
+    sessionId: string,
+    audioChunks: number[], 
+    options: AudioStreamingOptions = {}
+  ): Promise<void> {
+    if (!this.socket?.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) {
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  /**
+   * Add event listener
+   */
+  public on<K extends keyof WebSocketEvents>(
+    event: K,
+    handler: WebSocketEvents[K]
+  ): void {
+    if (!this.eventHandlers.has(event)) {
+      this.eventHandlers.set(event, []);
+    }
+    this.eventHandlers.get(event)!.push(handler);
+  }
+
+  /**
+   * Remove event listener
+   */
+  public off<K extends keyof WebSocketEvents>(
+    event: K,
+    handler: WebSocketEvents[K]
+  ): void {
+    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
+   */
+  private emit<K extends keyof WebSocketEvents>(
+    event: K,
+    ...args: Parameters<WebSocketEvents[K]>
+  ): void {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      handlers.forEach(handler => {
+        try {
+          (handler as Function)(...args);
+        } catch (error) {
+          console.error(`Error in WebSocket event handler for ${event}:`, error);
+        }
+      });
+    }
+  }
+
+  /**
+   * Setup WebSocket event handlers
+   */
+  private setupEventHandlers(): void {
+    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: string) => {
+      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: Error) => {
+      this.emit('connection-error', error);
+      
+      if (this.shouldReconnect()) {
+        this.scheduleReconnect();
+      }
+    });
+
+    // Application-specific events
+    this.socket.on('connected', (data: any) => {
+      this.emit('connected', data);
+    });
+
+    this.socket.on('audio-chunk-received', (data: any) => {
+      this.emit('audio-chunk-received', data);
+    });
+
+    this.socket.on('transcription-queued', (data: any) => {
+      this.emit('transcription-queued', data);
+    });
+
+    this.socket.on('audio-error', (error: any) => {
+      this.emit('audio-error', error);
+    });
+
+    this.socket.on('transcription-error', (error: any) => {
+      this.emit('transcription-error', error);
+    });
+  }
+
+  /**
+   * Determine if should attempt reconnection
+   */
+  private shouldReconnect(reason?: string): boolean {
+    // 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
+   */
+  private scheduleReconnect(): void {
+    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
+   */
+  private getWebSocketUrl(): string {
+    const wsProtocol = this.baseUrl.startsWith('https') ? 'wss' : 'ws';
+    const baseWsUrl = this.baseUrl.replace(/^https?/, wsProtocol);
+    return `${baseWsUrl}/${this.config.namespace}`;
+  }
+
+  /**
+   * Clean up resources
+   */
+  public destroy(): void {
+    this.disconnect();
+    this.eventHandlers.clear();
+  }
+}

package/src/sdk/sdk.ts

@@ -13,6 +13,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
@@ -30,6 +31,7 @@ export class ApiSDK extends BaseClient {
   public readonly logs: LogModule;
   public readonly debug: DebugModule;
   public readonly externalIntegrations: ExternalIntegrationModule;
+  public readonly websocket: WebSocketModule;
 
   constructor(config: SDKConfig = {}) {
     super(config);
@@ -47,6 +49,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);
   }
 
   // ======================
@@ -629,4 +632,37 @@ export class ApiSDK extends BaseClient {
   public async deleteExternalIntegration(...args: Parameters<ExternalIntegrationModule['deleteExternalIntegration']>) {
     return this.externalIntegrations.deleteExternalIntegration(...args);
   }
+
+  // WebSocket methods
+  public connectWebSocket() {
+    return this.websocket.connect();
+  }
+
+  public disconnectWebSocket() {
+    return this.websocket.disconnect();
+  }
+
+  public isWebSocketConnected() {
+    return this.websocket.isConnected();
+  }
+
+  public streamAudioChunk(...args: Parameters<WebSocketModule['streamAudioChunk']>) {
+    return this.websocket.streamAudioChunk(...args);
+  }
+
+  public streamAudioChunks(...args: Parameters<WebSocketModule['streamAudioChunks']>) {
+    return this.websocket.streamAudioChunks(...args);
+  }
+
+  public onWebSocketEvent(...args: Parameters<WebSocketModule['on']>) {
+    return this.websocket.on(...args);
+  }
+
+  public offWebSocketEvent(...args: Parameters<WebSocketModule['off']>) {
+    return this.websocket.off(...args);
+  }
+
+  public getWebSocketStats() {
+    return this.websocket.getConnectionStats();
+  }
 }

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

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

package/src/sdk/types/index.ts

@@ -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';