@convai/web-sdk 1.7.0 → 1.8.0-beta.0

package/dist/core/ConvaiClient.d.ts

@@ -1,5 +1,5 @@
 import { Room } from "livekit-client";
-import { ConvaiConfig, ConvaiClientState, ChatMessage, IConvaiClient, AudioControls, VideoControls, ScreenShareControls, DynamicInfo, ContextUpdateOptions, UploadFileOptions, WebSocketSessionFactory, RespondModeUpdateOptions, UpdateSceneMetadataOptions, VisionStatusOptions, VisionTriggerOptions } from "./types";
+import { ConvaiConfig, ConvaiClientState, ChatMessage, IConvaiClient, AudioControls, VideoControls, ScreenShareControls, DynamicInfo, ContextUpdateOptions, UploadFileOptions, WebSocketSessionFactory, RespondModeUpdateOptions, UpdateSceneMetadataOptions, VisionStatusOptions, VisionTriggerOptions, ConnectionData } from "./types";
 import { EventEmitter } from "./EventEmitter";
 import { BlendshapeQueue } from "./BlendshapeQueue";
 import { MemoryManager } from "./MemoryManager";
@@ -126,6 +126,45 @@ export declare class ConvaiClient extends EventEmitter implements IConvaiClient
      * Connect to a Convai character
      */
     connect(config?: ConvaiConfig): Promise<void>;
+    /**
+     * Complete a connection from an already-fetched /connect response body.
+     *
+     * `connect()` fetches /connect and then calls this internally. Call it
+     * directly when the response was obtained elsewhere — a server-side session
+     * manager, or the embed's connect-proxy flow, where the API key must never
+     * reach the browser.
+     *
+     * @example
+     * // Server (customer's backend): holds the API key, calls Convai's
+     * // /connect, and relays the response body verbatim.
+     * // Browser: never sees the API key, only the relayed response.
+     * const data = await fetch('/api/convai-connect', {
+     *   method: 'POST',
+     *   headers: { 'Content-Type': 'application/json' },
+     *   body: JSON.stringify({ characterId: 'your-character-id' }),
+     * }).then(r => r.json())
+     * await client.connectWithConnectionData(data)
+     */
+    connectWithConnectionData(data: ConnectionData, config?: ConvaiConfig): Promise<void>;
+    /**
+     * Add default URL, apply RTVI-logging config, and validate that either an
+     * API key or auth token plus a character ID are present.
+     * Shared by connect() and connectWithConnectionData() so both derive
+     * `configWithDefaults` identically.
+     *
+     * `connect()` performs its own /connect fetch and always needs a credential
+     * to do so, so it uses the default `requireCredential: true`.
+     * `connectWithConnectionData()` consumes a response obtained elsewhere (e.g.
+     * a proxy that holds the credential server-side) and passes
+     * `requireCredential: false` — a character ID is still required either way.
+     */
+    private applyConfigDefaults;
+    /**
+     * Consume a /connect response and bring up the transport.
+     * `connect()` calls this after its own fetch; external callers use it
+     * when the response came from a proxy.
+     */
+    private consumeConnectionData;
     private cleanupWebSocketSessionAfterConnectFailure;
     /**
      * RTVI client-ready handshake. Server-side gates bot-ready emission on

package/dist/core/ConvaiClient.d.ts.map

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

package/dist/core/ConvaiClient.js

@@ -413,18 +413,7 @@ export class ConvaiClient extends EventEmitter {
             finalConfig.characterSessionId !== "-1") {
             this._characterSessionId = finalConfig.characterSessionId;
         }
-        // Add default URL if not provided
-        const configWithDefaults = {
-            url: "https://realtime-api.convai.com",
-            ...finalConfig,
-        };
-        this._logRtviMessages = configWithDefaults.logRtviMessages !== false;
-        this._messageHandler.setRtviMessageLogging(this._logRtviMessages);
-        const hasApiKey = Boolean(configWithDefaults.apiKey);
-        const hasAuthToken = Boolean(configWithDefaults.authToken);
-        if ((!hasApiKey && !hasAuthToken) || !configWithDefaults.characterId) {
-            throw new Error("Either apiKey or authToken is required, and characterId is required");
-        }
+        const configWithDefaults = this.applyConfigDefaults(finalConfig);
         this.updateState({ isConnecting: true });
         try {
             // Store connection config
@@ -565,177 +554,297 @@ export class ConvaiClient extends EventEmitter {
                 throw new Error(errorMessage);
             }
             const connectionData = await response.json();
-            // Capture session identifiers from /connect response
-            if (connectionData.character_session_id) {
-                this._characterSessionId = connectionData.character_session_id;
-                this._storedConfig = {
-                    ...this._storedConfig,
-                    characterSessionId: connectionData.character_session_id,
-                };
+            return await this.consumeConnectionData(connectionData, configWithDefaults);
+        }
+        catch (error) {
+            await this.cleanupWebSocketSessionAfterConnectFailure();
+            this.updateState({
+                isConnected: false,
+                isConnecting: false,
+            });
+            this.emit("error", error);
+            throw error;
+        }
+    }
+    /**
+     * Complete a connection from an already-fetched /connect response body.
+     *
+     * `connect()` fetches /connect and then calls this internally. Call it
+     * directly when the response was obtained elsewhere — a server-side session
+     * manager, or the embed's connect-proxy flow, where the API key must never
+     * reach the browser.
+     *
+     * @example
+     * // Server (customer's backend): holds the API key, calls Convai's
+     * // /connect, and relays the response body verbatim.
+     * // Browser: never sees the API key, only the relayed response.
+     * const data = await fetch('/api/convai-connect', {
+     *   method: 'POST',
+     *   headers: { 'Content-Type': 'application/json' },
+     *   body: JSON.stringify({ characterId: 'your-character-id' }),
+     * }).then(r => r.json())
+     * await client.connectWithConnectionData(data)
+     */
+    async connectWithConnectionData(data, config) {
+        const finalConfig = config || this._storedConfig;
+        if (!finalConfig) {
+            throw new Error("No configuration provided. Pass config to connectWithConnectionData() or store it in the client");
+        }
+        this._storedConfig = { ...finalConfig };
+        // Use characterSessionId from config when reconnecting (so we resume the same session)
+        if (finalConfig.characterSessionId &&
+            finalConfig.characterSessionId !== "-1") {
+            this._characterSessionId = finalConfig.characterSessionId;
+        }
+        const configWithDefaults = this.applyConfigDefaults(finalConfig, {
+            requireCredential: false,
+        });
+        // Symmetric with connect(): the catch below emits isConnecting: false, so
+        // without this a UI bound to stateChange never sees a connecting state on
+        // the proxy path -- and on failure receives a transition out of a state it
+        // was never told about. consumeConnectionData() clears the flag on success.
+        this.updateState({ isConnecting: true });
+        try {
+            return await this.consumeConnectionData(data, configWithDefaults);
+        }
+        catch (error) {
+            await this.cleanupWebSocketSessionAfterConnectFailure();
+            this.updateState({
+                isConnected: false,
+                isConnecting: false,
+            });
+            this.emit("error", error);
+            throw error;
+        }
+    }
+    /**
+     * Add default URL, apply RTVI-logging config, and validate that either an
+     * API key or auth token plus a character ID are present.
+     * Shared by connect() and connectWithConnectionData() so both derive
+     * `configWithDefaults` identically.
+     *
+     * `connect()` performs its own /connect fetch and always needs a credential
+     * to do so, so it uses the default `requireCredential: true`.
+     * `connectWithConnectionData()` consumes a response obtained elsewhere (e.g.
+     * a proxy that holds the credential server-side) and passes
+     * `requireCredential: false` — a character ID is still required either way.
+     */
+    applyConfigDefaults(finalConfig, opts = {}) {
+        const { requireCredential = true } = opts;
+        // Add default URL if not provided
+        const configWithDefaults = {
+            url: "https://realtime-api.convai.com",
+            ...finalConfig,
+        };
+        this._logRtviMessages = configWithDefaults.logRtviMessages !== false;
+        this._messageHandler.setRtviMessageLogging(this._logRtviMessages);
+        const hasApiKey = Boolean(configWithDefaults.apiKey);
+        const hasAuthToken = Boolean(configWithDefaults.authToken);
+        const missingCredential = requireCredential && !hasApiKey && !hasAuthToken;
+        if (missingCredential || !configWithDefaults.characterId) {
+            throw new Error("Either apiKey or authToken is required, and characterId is required");
+        }
+        return configWithDefaults;
+    }
+    /**
+     * Consume a /connect response and bring up the transport.
+     * `connect()` calls this after its own fetch; external callers use it
+     * when the response came from a proxy.
+     */
+    async consumeConnectionData(connectionData, configWithDefaults) {
+        // Store connection config (mirrors connect()'s pre-fetch setup so this
+        // method is self-sufficient when called directly, without connect()
+        // having run first).
+        //
+        // Known race, judged acceptable: when called from connect(), that method
+        // sets these same fields once, before the /connect fetch, then awaits
+        // the network round trip. If disconnect() -> clearAllManagers() lands in
+        // that await window, the pre-split code left these fields null (nothing
+        // re-set them post-fetch), whereas re-deriving them here re-arms them
+        // once the response arrives. Checked `_isDisconnecting` as a guard: it
+        // doesn't cover this window — it's flipped back to false (in a
+        // `finally`) before clearAllManagers() runs on the websocket path, and
+        // disconnect()'s LiveKit-room path never sets it at all — so it can't
+        // reliably detect "a disconnect landed mid-connect" here. Even
+        // pre-split, connect() never checked for a concurrent disconnect after
+        // the fetch resolved; it always went on to establish a new room/session
+        // regardless. Re-arming these fields keeps them consistent with the
+        // connection actually being brought up in that case, rather than
+        // silently stale. Building a proper cancellation token for
+        // connect()-vs-disconnect() races is out of scope for this additive
+        // split.
+        this._apiKey = configWithDefaults.apiKey ?? null;
+        this._authToken = configWithDefaults.authToken ?? null;
+        this._characterId = configWithDefaults.characterId;
+        const connType = configWithDefaults.enableVideo ? "video" : "audio";
+        this._connectionType = connType;
+        const transportType = configWithDefaults.transport ?? "livekit";
+        this._activeTransport = transportType;
+        const effectiveVisionInputConfig = resolveVisionInputConfig(configWithDefaults);
+        // Capture session identifiers from /connect response
+        if (connectionData.character_session_id) {
+            this._characterSessionId = connectionData.character_session_id;
+            this._storedConfig = {
+                ...this._storedConfig,
+                characterSessionId: connectionData.character_session_id,
+            };
+        }
+        if (connectionData.end_user_id) {
+            this._endUserId = connectionData.end_user_id;
+        }
+        if (connectionData.end_user_metadata) {
+            this._endUserMetadata = connectionData.end_user_metadata;
+        }
+        if (transportType === "websocket") {
+            // ── WebSocket (Pipecat) transport path ────────────────────────────
+            // Server returns the WebSocket URL in room_url (same field as LiveKit).
+            const wsUrl = connectionData.room_url;
+            if (!wsUrl) {
+                throw new Error("No WebSocket URL returned from /connect endpoint (expected room_url)");
             }
-            if (connectionData.end_user_id) {
-                this._endUserId = connectionData.end_user_id;
+            if (!_wsFactory) {
+                throw new Error("[ConvaiClient] WebSocket transport is not registered. " +
+                    "Add `import '@convai/web-sdk/vanilla/websocket'` before calling connect().");
             }
-            if (connectionData.end_user_metadata) {
-                this._endUserMetadata = connectionData.end_user_metadata;
+            // Always enable mic at construction so WavMediaManager initializes the
+            // audio stream during connect(). If startWithAudioOn is false, we mute
+            // after the connection is established (enableMic(false) works once the
+            // stream exists, but not before it is initialized).
+            this._wsSession = _wsFactory((payload) => this._messageHandler.handleDataReceivedPublic(payload), true);
+            const webSocketVisionEnabled = configWithDefaults.enableVideo === true &&
+                effectiveVisionInputConfig?.enabled !== false;
+            if (webSocketVisionEnabled) {
+                this._videoManager.setWebSocketVisionMessageSender((type, data) => {
+                    if (this._activeTransport !== "websocket" ||
+                        !this._wsSession?.isConnected) {
+                        return;
+                    }
+                    this._wsSession.sendMessage(type, data);
+                });
             }
-            if (transportType === "websocket") {
-                // ── WebSocket (Pipecat) transport path ────────────────────────────
-                // Server returns the WebSocket URL in room_url (same field as LiveKit).
-                const wsUrl = connectionData.room_url;
-                if (!wsUrl) {
-                    throw new Error("No WebSocket URL returned from /connect endpoint (expected room_url)");
-                }
-                if (!_wsFactory) {
-                    throw new Error("[ConvaiClient] WebSocket transport is not registered. " +
-                        "Add `import '@convai/web-sdk/vanilla/websocket'` before calling connect().");
-                }
-                // Always enable mic at construction so WavMediaManager initializes the
-                // audio stream during connect(). If startWithAudioOn is false, we mute
-                // after the connection is established (enableMic(false) works once the
-                // stream exists, but not before it is initialized).
-                this._wsSession = _wsFactory((payload) => this._messageHandler.handleDataReceivedPublic(payload), true);
-                const webSocketVisionEnabled = configWithDefaults.enableVideo === true &&
-                    effectiveVisionInputConfig?.enabled !== false;
-                if (webSocketVisionEnabled) {
-                    this._videoManager.setWebSocketVisionMessageSender((type, data) => {
-                        if (this._activeTransport !== "websocket" ||
-                            !this._wsSession?.isConnected) {
-                            return;
-                        }
-                        this._wsSession.sendMessage(type, data);
-                    });
-                }
-                else {
-                    this._videoManager.setWebSocketVisionDisabled();
+            else {
+                this._videoManager.setWebSocketVisionDisabled();
+            }
+            const wsSession = this._wsSession;
+            wsSession.on("botAudioTrack", (track) => {
+                this.emit("botAudioTrack", track);
+            });
+            wsSession.on("disconnected", () => {
+                if (this._wsSession !== wsSession || this._isDisconnecting) {
+                    return;
                 }
-                const wsSession = this._wsSession;
-                wsSession.on("botAudioTrack", (track) => {
-                    this.emit("botAudioTrack", track);
-                });
-                wsSession.on("disconnected", () => {
-                    if (this._wsSession !== wsSession || this._isDisconnecting) {
+                this._connectionStateHandler.handleDisconnected();
+                this.clearAllManagers();
+            });
+            this._audioManager.setWebSocketSession(this._wsSession);
+            // Wait for WebSocket transport to connect (fires before bot-ready)
+            await new Promise((resolve, reject) => {
+                let settled = false;
+                const cleanupConnectListeners = () => {
+                    wsSession.off("connected", onConnected);
+                    wsSession.off("error", onError);
+                    wsSession.off("disconnected", onDisconnected);
+                };
+                const settle = (callback) => {
+                    if (settled) {
                         return;
                     }
-                    this._connectionStateHandler.handleDisconnected();
-                    this.clearAllManagers();
-                });
-                this._audioManager.setWebSocketSession(this._wsSession);
-                // Wait for WebSocket transport to connect (fires before bot-ready)
-                await new Promise((resolve, reject) => {
-                    let settled = false;
-                    const cleanupConnectListeners = () => {
-                        wsSession.off("connected", onConnected);
-                        wsSession.off("error", onError);
-                        wsSession.off("disconnected", onDisconnected);
-                    };
-                    const settle = (callback) => {
-                        if (settled) {
-                            return;
-                        }
-                        settled = true;
-                        cleanupConnectListeners();
-                        callback();
-                    };
-                    const onConnected = () => {
-                        settle(resolve);
-                    };
-                    const onError = (err) => {
-                        settle(() => {
-                            reject(err instanceof Error ? err : new Error(String(err)));
-                        });
-                    };
-                    const onDisconnected = () => {
-                        settle(() => {
-                            reject(new Error("WebSocket disconnected before connect completed"));
-                        });
-                    };
-                    wsSession.on("connected", onConnected);
-                    wsSession.on("error", onError);
-                    wsSession.on("disconnected", onDisconnected);
-                    // connectWithUrl calls initDevices() then connect({ wsUrl }) — matches sandbox flow
-                    wsSession.connectWithUrl(wsUrl).catch((err) => {
-                        settle(() => {
-                            reject(err instanceof Error ? err : new Error(String(err)));
-                        });
+                    settled = true;
+                    cleanupConnectListeners();
+                    callback();
+                };
+                const onConnected = () => {
+                    settle(resolve);
+                };
+                const onError = (err) => {
+                    settle(() => {
+                        reject(err instanceof Error ? err : new Error(String(err)));
+                    });
+                };
+                const onDisconnected = () => {
+                    settle(() => {
+                        reject(new Error("WebSocket disconnected before connect completed"));
+                    });
+                };
+                wsSession.on("connected", onConnected);
+                wsSession.on("error", onError);
+                wsSession.on("disconnected", onDisconnected);
+                // connectWithUrl calls initDevices() then connect({ wsUrl }) — matches sandbox flow
+                wsSession.connectWithUrl(wsUrl).catch((err) => {
+                    settle(() => {
+                        reject(err instanceof Error ? err : new Error(String(err)));
                     });
                 });
-                // For WebSocket, mic is already streaming after connect.
-                // Only mute if the caller explicitly sets startWithAudioOn: false.
-                // Defaulting to on matches the sandbox behavior and ensures the bot
-                // sees audio when it initializes (avoids server "tap mic to talk" prompt).
-                if (configWithDefaults.startWithAudioOn === false) {
-                    this._wsSession.enableMic(false);
-                    this._audioManager.syncWsAudioState(false);
-                }
-                else {
-                    this._audioManager.syncWsAudioState(true);
-                }
-                if (webSocketVisionEnabled &&
-                    configWithDefaults.enableVideo &&
-                    configWithDefaults.startWithVideoOn) {
-                    await this._videoManager.enableVideo();
-                }
+            });
+            // For WebSocket, mic is already streaming after connect.
+            // Only mute if the caller explicitly sets startWithAudioOn: false.
+            // Defaulting to on matches the sandbox behavior and ensures the bot
+            // sees audio when it initializes (avoids server "tap mic to talk" prompt).
+            if (configWithDefaults.startWithAudioOn === false) {
+                this._wsSession.enableMic(false);
+                this._audioManager.syncWsAudioState(false);
             }
             else {
-                this._videoManager.setWebSocketVisionMessageSender(null);
-                // ── LiveKit transport path (default) ─────────────────────────────
-                await this._room.connect(connectionData.room_url, connectionData.token, {
-                    rtcConfig: {
-                        iceTransportPolicy: "relay",
-                    },
-                });
-                if (configWithDefaults.startWithAudioOn) {
-                    await this._room.localParticipant.setMicrophoneEnabled(true, {
-                        echoCancellation: this._audioSettings.echoCancellation,
-                        noiseSuppression: this._audioSettings.noiseSuppression,
-                        autoGainControl: this._audioSettings.autoGainControl,
-                        sampleRate: this._audioSettings.sampleRate,
-                        channelCount: this._audioSettings.channelCount,
-                    });
-                }
-                if (configWithDefaults.enableVideo &&
-                    configWithDefaults.startWithVideoOn) {
-                    await this._room.localParticipant.setCameraEnabled(true);
-                }
-                this._audioManager.syncStateFromRoom({ emit: true });
-                this._participantSid = this._room.localParticipant.sid;
+                this._audioManager.syncWsAudioState(true);
             }
-            // Apply custom mapper to blendshape queue if provided
-            if (configWithDefaults.blendshapeConfig?.customMapper) {
-                this.blendshapeQueue.setMapper(configWithDefaults.blendshapeConfig.customMapper);
+            if (webSocketVisionEnabled &&
+                configWithDefaults.enableVideo &&
+                configWithDefaults.startWithVideoOn) {
+                await this._videoManager.enableVideo();
             }
-            this.updateState({
-                isConnected: true,
-                isConnecting: false,
-                endUserId: this._endUserId,
-                endUserMetadata: this._endUserMetadata,
+        }
+        else {
+            this._videoManager.setWebSocketVisionMessageSender(null);
+            // ── LiveKit transport path (default) ─────────────────────────────
+            await this._room.connect(connectionData.room_url, connectionData.token, {
+                rtcConfig: {
+                    // Defaults to "relay" (TURN-only) for reliable NAT traversal
+                    // against Convai's hosted LiveKit. Set iceTransportPolicy: "all"
+                    // when pointing at a LiveKit without TURN (e.g. local dev).
+                    iceTransportPolicy: configWithDefaults.iceTransportPolicy ?? "relay",
+                },
             });
-            // Initialize memory manager if we have authentication and endUserId
-            if (this._endUserId) {
-                if (this._apiKey) {
-                    // Use API key authentication
-                    this._memoryManager = new MemoryManager(this._apiKey, this._characterId, this._endUserId, undefined, // Use default base URL
-                    false);
-                }
-                else if (this._authToken) {
-                    // Use auth token authentication
-                    this._memoryManager = new MemoryManager(this._authToken, this._characterId, this._endUserId, undefined, // Use default base URL
-                    true);
-                }
+            if (configWithDefaults.startWithAudioOn) {
+                await this._room.localParticipant.setMicrophoneEnabled(true, {
+                    echoCancellation: this._audioSettings.echoCancellation,
+                    noiseSuppression: this._audioSettings.noiseSuppression,
+                    autoGainControl: this._audioSettings.autoGainControl,
+                    sampleRate: this._audioSettings.sampleRate,
+                    channelCount: this._audioSettings.channelCount,
+                });
+            }
+            if (configWithDefaults.enableVideo &&
+                configWithDefaults.startWithVideoOn) {
+                await this._room.localParticipant.setCameraEnabled(true);
             }
-            this.emit("connect");
-            this._startClientReadyHandshake();
+            this._audioManager.syncStateFromRoom({ emit: true });
+            this._participantSid = this._room.localParticipant.sid;
         }
-        catch (error) {
-            await this.cleanupWebSocketSessionAfterConnectFailure();
-            this.updateState({
-                isConnected: false,
-                isConnecting: false,
-            });
-            this.emit("error", error);
-            throw error;
+        // Apply custom mapper to blendshape queue if provided
+        if (configWithDefaults.blendshapeConfig?.customMapper) {
+            this.blendshapeQueue.setMapper(configWithDefaults.blendshapeConfig.customMapper);
+        }
+        this.updateState({
+            isConnected: true,
+            isConnecting: false,
+            endUserId: this._endUserId,
+            endUserMetadata: this._endUserMetadata,
+        });
+        // Initialize memory manager if we have authentication and endUserId
+        if (this._endUserId) {
+            if (this._apiKey) {
+                // Use API key authentication
+                this._memoryManager = new MemoryManager(this._apiKey, this._characterId, this._endUserId, undefined, // Use default base URL
+                false);
+            }
+            else if (this._authToken) {
+                // Use auth token authentication
+                this._memoryManager = new MemoryManager(this._authToken, this._characterId, this._endUserId, undefined, // Use default base URL
+                true);
+            }
         }
+        this.emit("connect");
+        this._startClientReadyHandshake();
     }
     async cleanupWebSocketSessionAfterConnectFailure() {
         if (this._activeTransport !== "websocket" || !this._wsSession) {