modular-voice-agent-sdk 2.5.1 → 2.6.1

package/dist/client/transports/http-sse.js

@@ -0,0 +1,134 @@
+/**
+ * HTTP + SSE Transport
+ *
+ * Transport that uses HTTP POST for client→server messages and
+ * Server-Sent Events (SSE) for server→client streaming.
+ *
+ * Useful for:
+ * - Environments where WebSocket isn't available or is blocked
+ * - Simpler server setups (standard HTTP endpoints)
+ * - Serverless/edge deployments that don't support long-lived connections
+ * - Debugging (HTTP requests are easier to inspect)
+ *
+ * Protocol:
+ * - POST /session → creates a session, returns { sessionId }
+ * - GET  /events?sessionId=xxx → SSE stream of ServerEnvelope events
+ * - POST /message → sends a ClientEnvelope to the server
+ *
+ * Audio considerations:
+ * - Works best for text-only or hybrid (client-side STT/TTS) modes
+ * - Audio chunks are accumulated and sent as POST requests
+ * - Higher latency than WebSocket for real-time audio streaming
+ */
+export class HttpSseTransport {
+    state = 'closed';
+    sessionId = null;
+    eventSource = null;
+    messageHandler = null;
+    errorHandler = null;
+    closeHandler = null;
+    baseUrl;
+    sessionPath;
+    eventsPath;
+    messagePath;
+    headers;
+    constructor(config) {
+        if (typeof config === 'string') {
+            config = { baseUrl: config };
+        }
+        // Strip trailing slash
+        this.baseUrl = config.baseUrl.replace(/\/$/, '');
+        this.sessionPath = config.sessionPath ?? '/session';
+        this.eventsPath = config.eventsPath ?? '/events';
+        this.messagePath = config.messagePath ?? '/message';
+        this.headers = config.headers ?? {};
+    }
+    get readyState() {
+        return this.state;
+    }
+    async connect() {
+        if (this.state === 'open')
+            return;
+        this.state = 'connecting';
+        try {
+            // Step 1: Create a session via POST
+            const response = await fetch(`${this.baseUrl}${this.sessionPath}`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...this.headers,
+                },
+            });
+            if (!response.ok) {
+                throw new Error(`Session creation failed: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            this.sessionId = data.sessionId;
+            // Step 2: Open SSE stream for server→client messages
+            await this.connectEventSource();
+            this.state = 'open';
+        }
+        catch (error) {
+            this.state = 'closed';
+            throw error;
+        }
+    }
+    connectEventSource() {
+        return new Promise((resolve, reject) => {
+            const url = `${this.baseUrl}${this.eventsPath}?sessionId=${encodeURIComponent(this.sessionId)}`;
+            this.eventSource = new EventSource(url);
+            this.eventSource.onopen = () => {
+                resolve();
+            };
+            this.eventSource.onmessage = (event) => {
+                try {
+                    const envelope = JSON.parse(event.data);
+                    this.messageHandler?.(envelope);
+                }
+                catch {
+                    this.errorHandler?.(new Error('Failed to parse SSE message'));
+                }
+            };
+            this.eventSource.onerror = () => {
+                if (this.state === 'connecting') {
+                    reject(new Error('SSE connection failed'));
+                }
+                else if (this.state === 'open') {
+                    this.state = 'closed';
+                    this.errorHandler?.(new Error('SSE connection lost'));
+                    this.closeHandler?.();
+                }
+            };
+        });
+    }
+    send(envelope) {
+        if (this.state !== 'open')
+            return;
+        fetch(`${this.baseUrl}${this.messagePath}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...this.headers,
+            },
+            body: JSON.stringify(envelope),
+        }).catch((error) => {
+            this.errorHandler?.(error instanceof Error ? error : new Error(String(error)));
+        });
+    }
+    onMessage(handler) {
+        this.messageHandler = handler;
+    }
+    onError(handler) {
+        this.errorHandler = handler;
+    }
+    onClose(handler) {
+        this.closeHandler = handler;
+    }
+    close() {
+        this.eventSource?.close();
+        this.eventSource = null;
+        this.sessionId = null;
+        this.state = 'closed';
+    }
+}
+//# sourceMappingURL=http-sse.js.map

package/dist/client/transports/http-sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-sse.js","sourceRoot":"","sources":["../../../src/client/transports/http-sse.ts"],"names":[],"mappings":"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"}

package/dist/client/transports/index.d.ts

@@ -0,0 +1,4 @@
+export { WebSocketTransport } from './websocket';
+export { HttpSseTransport } from './http-sse';
+export type { HttpSseTransportConfig } from './http-sse';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/transports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/transports/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC"}

package/dist/client/transports/index.js

@@ -0,0 +1,3 @@
+export { WebSocketTransport } from './websocket';
+export { HttpSseTransport } from './http-sse';
+//# sourceMappingURL=index.js.map

package/dist/client/transports/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/transports/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/client/transports/websocket.d.ts

@@ -0,0 +1,29 @@
+/**
+ * WebSocket Transport
+ *
+ * Standard WebSocket-based transport for voice pipeline communication.
+ * This is the default transport used by VoiceClient when a serverUrl is provided.
+ *
+ * Features:
+ * - Full-duplex communication
+ * - Real-time audio streaming
+ * - Low latency
+ */
+import type { ClientEnvelope, ServerEnvelope } from '../protocol';
+import type { Transport, TransportState } from '../transport';
+export declare class WebSocketTransport implements Transport {
+    private url;
+    private ws;
+    private messageHandler;
+    private errorHandler;
+    private closeHandler;
+    constructor(url: string);
+    get readyState(): TransportState;
+    connect(): Promise<void>;
+    send(envelope: ClientEnvelope): void;
+    onMessage(handler: (envelope: ServerEnvelope) => void): void;
+    onError(handler: (error: Error) => void): void;
+    onClose(handler: () => void): void;
+    close(): void;
+}
+//# sourceMappingURL=websocket.d.ts.map

package/dist/client/transports/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../../src/client/transports/websocket.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9D,qBAAa,kBAAmB,YAAW,SAAS;IAMtC,OAAO,CAAC,GAAG;IALvB,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,cAAc,CAAqD;IAC3E,OAAO,CAAC,YAAY,CAAyC;IAC7D,OAAO,CAAC,YAAY,CAA6B;gBAE7B,GAAG,EAAE,MAAM;IAE/B,IAAI,UAAU,IAAI,cAAc,CAO/B;IAEK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAkC9B,IAAI,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAMpC,SAAS,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,GAAG,IAAI;IAI5D,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI;IAI9C,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;IAIlC,KAAK,IAAI,IAAI;CAId"}

package/dist/client/transports/websocket.js

@@ -0,0 +1,79 @@
+/**
+ * WebSocket Transport
+ *
+ * Standard WebSocket-based transport for voice pipeline communication.
+ * This is the default transport used by VoiceClient when a serverUrl is provided.
+ *
+ * Features:
+ * - Full-duplex communication
+ * - Real-time audio streaming
+ * - Low latency
+ */
+export class WebSocketTransport {
+    url;
+    ws = null;
+    messageHandler = null;
+    errorHandler = null;
+    closeHandler = null;
+    constructor(url) {
+        this.url = url;
+    }
+    get readyState() {
+        if (!this.ws)
+            return 'closed';
+        switch (this.ws.readyState) {
+            case WebSocket.CONNECTING: return 'connecting';
+            case WebSocket.OPEN: return 'open';
+            default: return 'closed';
+        }
+    }
+    async connect() {
+        if (this.ws?.readyState === WebSocket.OPEN)
+            return;
+        return new Promise((resolve, reject) => {
+            this.ws = new WebSocket(this.url);
+            this.ws.onopen = () => {
+                resolve();
+            };
+            this.ws.onclose = () => {
+                this.closeHandler?.();
+            };
+            this.ws.onerror = () => {
+                const error = new Error('WebSocket error');
+                this.errorHandler?.(error);
+                // Reject only if we haven't connected yet
+                if (this.ws?.readyState !== WebSocket.OPEN) {
+                    reject(error);
+                }
+            };
+            this.ws.onmessage = (event) => {
+                try {
+                    const envelope = JSON.parse(event.data);
+                    this.messageHandler?.(envelope);
+                }
+                catch {
+                    this.errorHandler?.(new Error('Failed to parse server message'));
+                }
+            };
+        });
+    }
+    send(envelope) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(envelope));
+        }
+    }
+    onMessage(handler) {
+        this.messageHandler = handler;
+    }
+    onError(handler) {
+        this.errorHandler = handler;
+    }
+    onClose(handler) {
+        this.closeHandler = handler;
+    }
+    close() {
+        this.ws?.close();
+        this.ws = null;
+    }
+}
+//# sourceMappingURL=websocket.js.map

package/dist/client/transports/websocket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.js","sourceRoot":"","sources":["../../../src/client/transports/websocket.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,MAAM,OAAO,kBAAkB;IAMT;IALZ,EAAE,GAAqB,IAAI,CAAC;IAC5B,cAAc,GAAgD,IAAI,CAAC;IACnE,YAAY,GAAoC,IAAI,CAAC;IACrD,YAAY,GAAwB,IAAI,CAAC;IAEjD,YAAoB,GAAW;QAAX,QAAG,GAAH,GAAG,CAAQ;IAAG,CAAC;IAEnC,IAAI,UAAU;QACZ,IAAI,CAAC,IAAI,CAAC,EAAE;YAAE,OAAO,QAAQ,CAAC;QAC9B,QAAQ,IAAI,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC;YAC3B,KAAK,SAAS,CAAC,UAAU,CAAC,CAAC,OAAO,YAAY,CAAC;YAC/C,KAAK,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,MAAM,CAAC;YACnC,OAAO,CAAC,CAAC,OAAO,QAAQ,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,EAAE,EAAE,UAAU,KAAK,SAAS,CAAC,IAAI;YAAE,OAAO;QAEnD,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC3C,IAAI,CAAC,EAAE,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAElC,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,GAAG,EAAE;gBACpB,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;YAEF,IAAI,CAAC,EAAE,CAAC,OAAO,GAAG,GAAG,EAAE;gBACrB,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;YACxB,CAAC,CAAC;YAEF,IAAI,CAAC,EAAE,CAAC,OAAO,GAAG,GAAG,EAAE;gBACrB,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;gBAC3C,IAAI,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC;gBAC3B,0CAA0C;gBAC1C,IAAI,IAAI,CAAC,EAAE,EAAE,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;oBAC3C,MAAM,CAAC,KAAK,CAAC,CAAC;gBAChB,CAAC;YACH,CAAC,CAAC;YAEF,IAAI,CAAC,EAAE,CAAC,SAAS,GAAG,CAAC,KAAK,EAAE,EAAE;gBAC5B,IAAI,CAAC;oBACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAmB,CAAC;oBAC1D,IAAI,CAAC,cAAc,EAAE,CAAC,QAAQ,CAAC,CAAC;gBAClC,CAAC;gBAAC,MAAM,CAAC;oBACP,IAAI,CAAC,YAAY,EAAE,CAAC,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC,CAAC;gBACnE,CAAC;YACH,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC,QAAwB;QAC3B,IAAI,IAAI,CAAC,EAAE,EAAE,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;YAC3C,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,SAAS,CAAC,OAA2C;QACnD,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC;IAChC,CAAC;IAED,OAAO,CAAC,OAA+B;QACrC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC;IAC9B,CAAC;IAED,OAAO,CAAC,OAAmB;QACzB,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC;IAC9B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;IACjB,CAAC;CACF"}

package/dist/client/voice-client.d.ts

@@ -4,17 +4,23 @@
  * Unified browser SDK for voice assistants.
  * Handles three modes:
  * 1. Fully local - all components run in browser, no server needed
- * 2. Fully remote - all processing on server via WebSocket
+ * 2. Fully remote - all processing on server via transport
  * 3. Hybrid - mix of local and server components
  *
  * Component logic:
  * - Component provided → runs locally
- * - Component is null + serverUrl → server handles it
- * - All components local → no WebSocket needed
+ * - Component is null + serverUrl/transport → server handles it
+ * - All components local → no server connection needed
+ *
+ * Transport:
+ * - Default: WebSocketTransport (when serverUrl is provided)
+ * - Custom: Pass any Transport implementation via the transport option
+ * - Built-in alternatives: HttpSseTransport (HTTP POST + SSE)
  */
 import type { STTPipeline, LLMPipeline, TTSPipeline } from '../types';
 import { WebSpeechSTT } from './web-speech-stt';
 import { WebSpeechTTS } from './web-speech-tts';
+import type { Transport } from './transport';
 export interface BrowserSupport {
     /** Web Speech API speech recognition (Chrome, Edge, Safari only) */
     webSpeechSTT: boolean;
@@ -64,9 +70,26 @@ export interface ClientComponents {
      */
     systemPrompt?: string;
     /**
-     * WebSocket server URL (required if any component is null)
+     * Server URL (required if any component is null).
+     * When no custom transport is provided, this creates a WebSocketTransport.
+     * For WebSocket: 'ws://localhost:3000'
+     * For HTTP+SSE: use a custom transport instead
      */
     serverUrl?: string;
+    /**
+     * Custom transport for server communication.
+     * Overrides serverUrl when provided.
+     * Use this for non-WebSocket transports (HTTP+SSE, postMessage, etc.)
+     *
+     * @example
+     * ```typescript
+     * import { HttpSseTransport } from 'modular-voice-agent-sdk/client';
+     * {
+     *   transport: new HttpSseTransport('http://localhost:3000'),
+     * }
+     * ```
+     */
+    transport?: Transport;
 }
 import type { ModelStore } from '../voice-pipeline';
 /**
@@ -184,7 +207,7 @@ export declare class VoiceClient {
     private localLLM;
     private localTTS;
     private localPipeline;
-    private ws;
+    private transport;
     private recorder;
     private player;
     private status;
@@ -210,7 +233,7 @@ export declare class VoiceClient {
      */
     connect(): Promise<void>;
     private initializeLocalComponents;
-    private connectWebSocket;
+    private connectTransport;
     /**
      * Disconnect and clean up
      */
@@ -276,10 +299,17 @@ export declare class VoiceClient {
      * Returns null if no request is in progress
      */
     getCurrentRequestId(): string | null;
+    /**
+     * Get the underlying transport.
+     * Useful for inspecting the transport state or for advanced use cases.
+     * Returns null if not using server mode.
+     */
+    getTransport(): Transport | null;
     /**
      * Get the underlying WebSocket connection.
-     * Useful for sending/receiving custom app-specific messages outside the voice protocol.
-     * Returns null if not using server mode or not connected.
+     * Returns null if not using server mode, not connected, or not using WebSocket transport.
+     *
+     * @deprecated Use getTransport() instead for transport-agnostic code.
      *
      * @example
      * ```typescript
@@ -290,12 +320,6 @@ export declare class VoiceClient {
      *   message: { type: 'my_custom_message', data: {...} } as any,
      * };
      * client.getWebSocket()?.send(JSON.stringify(envelope));
-     *
-     * // Listen for custom messages
-     * client.getWebSocket()?.addEventListener('message', (event) => {
-     *   const envelope = JSON.parse(event.data) as ServerEnvelope;
-     *   if (envelope.message.type === 'my_custom_response') { ... }
-     * });
      * ```
      */
     getWebSocket(): WebSocket | null;

package/dist/client/voice-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"voice-client.d.ts","sourceRoot":"","sources":["../../src/client/voice-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"voice-client.d.ts","sourceRoot":"","sources":["../../src/client/voice-client.ts"],"names":[],"mappings":"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"}

package/dist/client/voice-client.js

@@ -4,13 +4,18 @@
  * Unified browser SDK for voice assistants.
  * Handles three modes:
  * 1. Fully local - all components run in browser, no server needed
- * 2. Fully remote - all processing on server via WebSocket
+ * 2. Fully remote - all processing on server via transport
  * 3. Hybrid - mix of local and server components
  *
  * Component logic:
  * - Component provided → runs locally
- * - Component is null + serverUrl → server handles it
- * - All components local → no WebSocket needed
+ * - Component is null + serverUrl/transport → server handles it
+ * - All components local → no server connection needed
+ *
+ * Transport:
+ * - Default: WebSocketTransport (when serverUrl is provided)
+ * - Custom: Pass any Transport implementation via the transport option
+ * - Built-in alternatives: HttpSseTransport (HTTP POST + SSE)
  */
 import { VoicePipeline } from '../voice-pipeline';
 import { AudioRecorder } from './audio-recorder';
@@ -18,6 +23,7 @@ import { AudioPlayer } from './audio-player';
 import { WebSpeechSTT } from './web-speech-stt';
 import { WebSpeechTTS } from './web-speech-tts';
 import { float32ToBase64, base64ToFloat32, generateId, } from './protocol';
+import { WebSocketTransport } from './transports/websocket';
 // ============ Helpers ============
 function isWebSpeechSTT(obj) {
     return obj instanceof WebSpeechSTT;
@@ -99,7 +105,7 @@ export class VoiceClient {
     localTTS = null;
     localPipeline = null;
     // Remote/hybrid components
-    ws = null;
+    transport = null;
     recorder = null;
     player = null;
     // State
@@ -142,9 +148,16 @@ export class VoiceClient {
             this.mode = 'hybrid';
         }
         // Validate config
-        if (this.needsServer && !components.serverUrl) {
-            throw new Error('serverUrl is required when any component (stt, llm, tts) is null. ' +
-                'Either provide all components for fully-local mode, or specify a serverUrl.');
+        if (this.needsServer && !components.serverUrl && !components.transport) {
+            throw new Error('serverUrl or transport is required when any component (stt, llm, tts) is null. ' +
+                'Either provide all components for fully-local mode, or specify a serverUrl or custom transport.');
+        }
+        // Create transport from serverUrl if no custom transport provided
+        if (components.transport) {
+            this.transport = components.transport;
+        }
+        else if (components.serverUrl) {
+            this.transport = new WebSocketTransport(components.serverUrl);
         }
         if (hasLocalLLM && !components.systemPrompt) {
             throw new Error('systemPrompt is required when using a local LLM');
@@ -258,7 +271,7 @@ export class VoiceClient {
         }
         // Connect to server if needed
         if (this.needsServer) {
-            await this.connectWebSocket();
+            await this.connectTransport();
         }
         else {
             this.setStatus('ready');
@@ -296,37 +309,28 @@ export class VoiceClient {
         }
         await Promise.all(promises);
     }
-    async connectWebSocket() {
-        if (!this.config.serverUrl)
+    async connectTransport() {
+        if (!this.transport)
             return;
-        if (this.ws?.readyState === WebSocket.OPEN)
+        if (this.transport.readyState === 'open')
             return;
         this.setStatus('connecting');
-        this.ws = new WebSocket(this.config.serverUrl);
-        this.ws.onopen = () => {
-            // Wait for session_init before sending capabilities
-            // The server will send session_init immediately on connect
-        };
-        this.ws.onclose = () => {
+        // Register handlers before connecting
+        this.transport.onMessage((envelope) => {
+            this.handleServerEnvelope(envelope);
+        });
+        this.transport.onClose(() => {
             this.sessionId = null;
             this.currentRequestId = null;
             this.setStatus('disconnected');
             if (this.config.autoReconnect && this.needsServer) {
                 this.scheduleReconnect();
             }
-        };
-        this.ws.onerror = () => {
-            this.emit('error', new Error('WebSocket error'), createLocalMeta(this.currentRequestId));
-        };
-        this.ws.onmessage = (event) => {
-            try {
-                const envelope = JSON.parse(event.data);
-                this.handleServerEnvelope(envelope);
-            }
-            catch {
-                this.emit('error', new Error('Failed to parse server message'), createLocalMeta(this.currentRequestId));
-            }
-        };
+        });
+        this.transport.onError((error) => {
+            this.emit('error', error, createLocalMeta(this.currentRequestId));
+        });
+        await this.transport.connect();
     }
     /**
      * Disconnect and clean up
@@ -337,8 +341,7 @@ export class VoiceClient {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
-        this.ws?.close();
-        this.ws = null;
+        this.transport?.close();
         // Stop any TTS
         if (isWebSpeechTTS(this.localTTS)) {
             this.localTTS.stop();
@@ -583,7 +586,7 @@ export class VoiceClient {
         if (this.mode === 'local') {
             return this.localPipeline?.isReady() ?? false;
         }
-        return this.ws?.readyState === WebSocket.OPEN;
+        return this.transport?.readyState === 'open';
     }
     /**
      * Check if currently recording
@@ -651,10 +654,19 @@ export class VoiceClient {
     getCurrentRequestId() {
         return this.currentRequestId;
     }
+    /**
+     * Get the underlying transport.
+     * Useful for inspecting the transport state or for advanced use cases.
+     * Returns null if not using server mode.
+     */
+    getTransport() {
+        return this.transport;
+    }
     /**
      * Get the underlying WebSocket connection.
-     * Useful for sending/receiving custom app-specific messages outside the voice protocol.
-     * Returns null if not using server mode or not connected.
+     * Returns null if not using server mode, not connected, or not using WebSocket transport.
+     *
+     * @deprecated Use getTransport() instead for transport-agnostic code.
      *
      * @example
      * ```typescript
@@ -665,16 +677,15 @@ export class VoiceClient {
      *   message: { type: 'my_custom_message', data: {...} } as any,
      * };
      * client.getWebSocket()?.send(JSON.stringify(envelope));
-     *
-     * // Listen for custom messages
-     * client.getWebSocket()?.addEventListener('message', (event) => {
-     *   const envelope = JSON.parse(event.data) as ServerEnvelope;
-     *   if (envelope.message.type === 'my_custom_response') { ... }
-     * });
      * ```
      */
     getWebSocket() {
-        return this.ws;
+        if (this.transport instanceof WebSocketTransport) {
+            // WebSocketTransport doesn't expose the raw WS; return null
+            // Users should migrate to getTransport()
+            return null;
+        }
+        return null;
     }
     /**
      * Subscribe to events
@@ -705,13 +716,13 @@ export class VoiceClient {
     }
     // ============ Private Methods ============
     send(msg) {
-        if (this.ws?.readyState === WebSocket.OPEN && this.sessionId && this.currentRequestId) {
+        if (this.transport?.readyState === 'open' && this.sessionId && this.currentRequestId) {
             const envelope = {
                 sessionId: this.sessionId,
                 requestId: this.currentRequestId,
                 message: msg,
             };
-            this.ws.send(JSON.stringify(envelope));
+            this.transport.send(envelope);
         }
     }
     handleServerEnvelope(envelope) {
@@ -901,9 +912,9 @@ export class VoiceClient {
                 '  2. The browser does not support getUserMedia\n' +
                 '  3. Microphone permissions were denied');
         }
-        // Check WebSocket if using server
-        if (components.serverUrl && !support.webSocket) {
-            throw new Error('WebSocket is not supported in this browser.');
+        // Check WebSocket if using server with default transport (no custom transport)
+        if (components.serverUrl && !components.transport && !support.webSocket) {
+            throw new Error('WebSocket is not supported in this browser. Consider using a custom transport (e.g., HttpSseTransport).');
         }
         // Check AudioContext for audio processing
         if (!support.audioContext) {