@vanira/sdk-react-native 0.0.2

package/src/core/WebRTCClient.ts

@@ -0,0 +1,1012 @@
+import { WebRTCClientConfig, ControlEvent, PresetEventPayload } from '../types';
+import { resolveRuntimeConfig } from '../runtime/resolveRuntimeConfig';
+import { canDispatchBrowserEvent } from '../runtime/platform';
+import { normalizeToolCallFields, unwrapToolCallData } from './toolCallNormalize';
+import {
+    getIceTrickleUrl,
+    ICE_TRICKLE_POLL_MS,
+    isWorkerSdpUrl,
+    mapIceServersFromCreate,
+    type CreateCallResponse,
+} from './webrtcSignaling';
+import type { RuntimeCapabilities } from '../runtime/types';
+import type { AudioAdapter, MediaAdapter, AudioPlayerHandle } from '../adapters/interfaces';
+import type { PeerConnectionAdapter, DataChannelAdapter, DataChannelController } from '../adapters/PeerConnectionAdapter';
+import type { StorageAdapter } from '../adapters/storage/StorageAdapter';
+import {
+    isRNUploadFileDescriptor,
+    normalizeUploadMimeForUpload,
+    type UploadMediaInput,
+    uploadFileMimeType,
+} from '../adapters/react-native/rnUploadFile';
+import { readResponseJson } from './httpResponse';
+import {
+    activateCallAudioPlayback,
+    prepareCallAudioForCapture,
+    stopCallAudioSession,
+} from '../adapters/react-native/callAudioRouting';
+import {dispatchBoardAbort} from '../presets/chalkboard/boardAbort';
+import {resetBoardSession} from '../presets/chalkboard/boardQueue';
+import {loadContinueSession, saveCallSession} from './CallSessionStore';
+
+const STORAGE_KEY_PROSPECT = 'vanira_prospect_id';
+const STORAGE_KEY_CALL = 'vanira_latest_call_id';
+
+function storageValueOrUndefined(value: string | null): string | undefined {
+    return value || undefined;
+}
+
+export class WebRTCClient {
+    public serverUrl: string;
+    public agentId: string;
+    public callId: string | undefined;
+    public prospectId: string | undefined;
+    public apiKey: string | undefined;
+    private backendUrl: string;
+    public token: string | undefined;
+    private onConnected: () => void;
+    private onDisconnected: () => void;
+    private onError: (error: any) => void;
+    private onTranscription: (text: string, isFinal: boolean) => void;
+    private onLocalStream: (stream: MediaStream) => void;
+    // @ts-ignore
+    private onRemoteTrack: (track: MediaStreamTrack, stream: MediaStream) => void;
+    private onClientToolCall: (toolCall: any) => void;
+    private onPreset: ((payload: PresetEventPayload) => void) | undefined;
+    private onSessionStarted: ((payload: { prospectId: string; callId: string; serverUrl: string }) => void) | undefined;
+    private sessionStartedEmitted: boolean = false;
+
+    private readonly runtimeName: string;
+    private readonly callType: 'web';
+    private readonly callIdPrefix: string;
+    private readonly capabilities: RuntimeCapabilities;
+    private readonly audioAdapter: AudioAdapter;
+    private readonly mediaAdapter: MediaAdapter;
+    private readonly peerAdapter: PeerConnectionAdapter;
+    private readonly dataChannelAdapter: DataChannelAdapter;
+    private readonly storage: StorageAdapter;
+    private iceServers: RTCIceServer[] = [];
+    private readonly sessionBehavior: 'continue' | 'new' | undefined;
+
+    private pc: RTCPeerConnection | null = null;
+    private dataChannel: RTCDataChannel | null = null;
+    private dcController: DataChannelController | null = null;
+    private audioPlayer: AudioPlayerHandle | null = null;
+    private localStream: MediaStream | null = null;
+    public connected: boolean = false;
+    /** True after onConnected fires — requires transport + DataChannel open. */
+    private connectedNotified = false;
+    private pendingOutbound: string[] = [];
+    private iceTricklePollTimer: ReturnType<typeof setInterval> | null = null;
+    private seenRemoteIceCandidates = new Set<string>();
+    private playedStreamFallbackTimer: ReturnType<typeof setTimeout> | null = null;
+    /** RN has no audio onended — delay after final transcription before playedStream. */
+    private static readonly PLAYED_STREAM_AFTER_TRANSCRIPTION_MS = 1800;
+    private controlEventTap: ((msg: ControlEvent) => void) | null = null;
+    /** Set by disconnect() so in-flight createCall/connect can bail out cleanly. */
+    private teardownRequested = false;
+
+    constructor(config: WebRTCClientConfig) {
+        if (!config.agentId) throw new Error('[VaniraSDK] agentId is required');
+        if (!config.serverUrl && !config.apiKey) {
+            throw new Error('[VaniraSDK] Provide either serverUrl or apiKey (to use createCall())');
+        }
+
+        const resolved = resolveRuntimeConfig(config);
+
+        this.runtimeName = resolved.runtimeName;
+        this.callType = resolved.callType;
+        this.callIdPrefix = resolved.callIdPrefix;
+        this.capabilities = resolved.capabilities;
+        this.audioAdapter = resolved.audio;
+        this.mediaAdapter = resolved.media;
+        this.peerAdapter = resolved.peer;
+        this.dataChannelAdapter = resolved.dataChannel;
+        this.storage = resolved.storage;
+        if (config.iceServers?.length) {
+            console.warn(
+                '[VaniraSDK] config.iceServers is deprecated — ICE comes from POST /calls/create only',
+            );
+            this.iceServers = config.iceServers;
+        }
+        if (config.serverUrl && config.apiKey) {
+            console.warn(
+                '[VaniraSDK] config.serverUrl is ignored when apiKey is set — use createCall() worker_url',
+            );
+        }
+        this.sessionBehavior = config.sessionBehavior;
+        this.token = config.token;
+
+        this.agentId = config.agentId;
+        this.serverUrl = config.serverUrl ? config.serverUrl.replace(/\/$/, '') : '';
+        this.apiKey = config.apiKey;
+        this.backendUrl = (config.backendUrl || 'https://api.vanira.io').replace(/\/$/, '');
+
+        // 1. Resolve prospectId + prior call_id for continue (mirrors web SDK)
+        this.prospectId = config.prospectId;
+        const isContinue = config.sessionBehavior === 'continue';
+
+        if (isContinue && !config.callId) {
+            const stored = loadContinueSession(this.storage, this.agentId);
+            if (stored) {
+                this.callId = stored.callId;
+                if (!this.prospectId && stored.prospectId) {
+                    this.prospectId = stored.prospectId;
+                }
+            }
+        }
+
+        if (!this.prospectId) {
+            try {
+                const scoped = loadContinueSession(this.storage, this.agentId);
+                this.prospectId =
+                    scoped?.prospectId ||
+                    storageValueOrUndefined(
+                        this.storage.getItem(STORAGE_KEY_PROSPECT),
+                    );
+            } catch {
+                /* ignore storage errors */
+            }
+        }
+
+        // 2. Resolve callId depending on sessionBehavior
+        if (config.callId) {
+            this.callId = config.callId;
+        } else if (!isContinue) {
+            this.callId = undefined;
+        } else if (!this.callId) {
+            try {
+                this.callId = storageValueOrUndefined(
+                    this.storage.getItem(STORAGE_KEY_CALL),
+                );
+            } catch {
+                /* ignore */
+            }
+        }
+
+        // Callbacks
+        this.onConnected = config.onConnected || (() => { });
+        this.onDisconnected = config.onDisconnected || (() => { });
+        this.onError = config.onError || ((e) => console.error('[WebRTC]', e));
+        this.onTranscription = config.onTranscription || (() => { });
+        this.onLocalStream = config.onLocalStream || (() => { });
+        // @ts-ignore
+        this.onRemoteTrack = config.onRemoteTrack || (() => { });
+        this.onClientToolCall = config.onClientToolCall || (() => { });
+        this.onPreset = config.onPreset;
+        this.onSessionStarted = config.onSessionStarted;
+    }
+
+    /**
+     * Create a call session via the Vanira API, then connect.
+     * Requires apiKey in the constructor config.
+     * Equivalent to manually calling POST /calls/create + client.connect().
+     */
+    private bailIfTeardown(context: string): boolean {
+        if (!this.teardownRequested) {
+            return false;
+        }
+        console.log(`[WebRTC] ${context} — aborted (teardown requested)`);
+        return true;
+    }
+
+    async createCall(): Promise<void> {
+        console.log('[INSTR] WebRTCClient.createCall() entry');
+        if (this.bailIfTeardown('createCall() entry')) {
+            return;
+        }
+        if (!this.apiKey) throw new Error("[VaniraAI] apiKey is required to use createCall()");
+
+        if (this.sessionBehavior === 'new') {
+            resetBoardSession();
+        }
+
+        const headers: Record<string, string> = {
+            'Content-Type': 'application/json',
+            'X-API-Key': this.apiKey,
+        };
+
+        const body: Record<string, unknown> = {
+            agent_id: this.agentId,
+            type: this.callType,
+            runtime: this.runtimeName,
+            prospect_id: this.prospectId,
+            call_id: this.callId,
+        };
+        if (this.sessionBehavior === 'continue') {
+            body.mode = 'continue';
+        }
+
+        const createUrl = `${this.backendUrl}/calls/create`;
+        console.log('[INSTR] WebRTCClient.createCall() before fetch', createUrl);
+        const response = await fetch(createUrl, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        });
+        console.log('[INSTR] WebRTCClient.createCall() after fetch');
+        console.log('[INSTR] WebRTCClient.createCall() response status', response.status);
+        if (this.bailIfTeardown('createCall() after fetch')) {
+            return;
+        }
+
+        const data = await readResponseJson<CreateCallResponse>(response, 'POST /calls/create');
+        if (this.bailIfTeardown('createCall() after parse')) {
+            return;
+        }
+        if (!response.ok) {
+            console.log('[INSTR] WebRTCClient.createCall() response body', JSON.stringify(data));
+            const detail = data.detail as { message?: string } | undefined;
+            throw new Error(
+                `[VaniraAI] createCall failed (${response.status}): ${
+                    detail?.message || (data.message as string) || response.statusText
+                }`,
+            );
+        }
+        console.log('[INSTR] WebRTCClient.createCall() response body', JSON.stringify(data));
+        if (!data.call_id || !data.worker_url) {
+            throw new Error('[VaniraAI] createCall response missing call_id or worker_url');
+        }
+
+        this.iceServers = mapIceServersFromCreate(data.ice_servers);
+        this.callId = data.call_id;
+        this.prospectId = data.prospect_id || this.prospectId;
+        this.serverUrl = data.worker_url as string;
+
+        try {
+            saveCallSession(
+                this.storage,
+                this.agentId,
+                this.callId || '',
+                this.prospectId,
+            );
+        } catch (e) {
+            console.warn('[WebRTC] Failed to save session variables to storage:', e);
+        }
+
+        if (this.onSessionStarted && this.prospectId && this.callId) {
+            try {
+                this.onSessionStarted({ prospectId: this.prospectId, callId: this.callId, serverUrl: this.serverUrl });
+                this.sessionStartedEmitted = true;
+            } catch (e) {
+                console.error('[WebRTC] Error in onSessionStarted callback:', e);
+            }
+        }
+
+        if (this.bailIfTeardown('createCall() before connect')) {
+            return;
+        }
+        await this.connect();
+    }
+
+    /**
+     * Connect to the agent. If apiKey is set and serverUrl is not yet resolved,
+     * automatically calls the pre-flight API to get call_id + worker_url first.
+     */
+    async connect(): Promise<void> {
+        console.log('[INSTR] WebRTCClient.connect() entry');
+        if (this.bailIfTeardown('connect() entry')) {
+            return;
+        }
+        if (this.apiKey && !this.serverUrl) {
+            await this.createCall();
+            return;
+        }
+        if (this.bailIfTeardown('connect() after createCall')) {
+            return;
+        }
+
+        if (!this.serverUrl) throw new Error('[VaniraAI] serverUrl is missing. Provide apiKey or serverUrl.');
+
+        if (!this.iceServers.length) {
+            throw new Error(
+                '[VaniraAI] ice_servers missing — call POST /calls/create before connect()',
+            );
+        }
+
+        if (!this.callId) {
+            this.callId = this.generateCallId();
+        }
+
+        if (this.onSessionStarted && this.prospectId && this.callId && !this.sessionStartedEmitted) {
+            try {
+                this.onSessionStarted({ prospectId: this.prospectId, callId: this.callId, serverUrl: this.serverUrl });
+                this.sessionStartedEmitted = true;
+            } catch (e) {
+                console.error('[WebRTC] Error in onSessionStarted callback:', e);
+            }
+        }
+
+        console.log('🔵 [WebRTC] Starting connection...');
+
+        try {
+            console.log('[INSTR] WebRTCClient.connect() before RTCPeerConnection creation');
+            this.pc = this.peerAdapter.create({
+                iceServers: this.iceServers,
+                iceTransportPolicy: 'all',
+            });
+            console.log('[INSTR] WebRTCClient.connect() after RTCPeerConnection creation');
+            console.log('🧊 [WebRTC] Using ICE servers from /calls/create:', this.iceServers.length);
+
+            const iceTrickleUrl = getIceTrickleUrl(this.serverUrl, this.agentId, this.callId);
+            console.log('[WebRTC] worker_url (POST offer):', this.serverUrl);
+            console.log('[WebRTC] ice_trickle_url (GET/POST ICE):', iceTrickleUrl);
+            this.bindIceTrickle(this.pc, iceTrickleUrl);
+
+            // Android: VoIP mode + earpiece before AudioRecord (avoids emulator beep/loopback).
+            if (!this.capabilities.supportsAudioEndedEvent) {
+                prepareCallAudioForCapture();
+            }
+
+            let stream: MediaStream;
+            try {
+                console.log('[INSTR] WebRTCClient.connect() before getUserMedia');
+                stream = await this.mediaAdapter.getUserAudio({
+                    echoCancellation: true,
+                    noiseSuppression: true,
+                    autoGainControl: true,
+                    sampleRate: { ideal: 16000 },
+                    channelCount: 1,
+                });
+                console.log('[INSTR] WebRTCClient.connect() after getUserMedia');
+                if (this.bailIfTeardown('connect() after getUserMedia')) {
+                    this.mediaAdapter.stopStream(stream);
+                    return;
+                }
+            } catch (err: any) {
+                if (this.teardownRequested) {
+                    return;
+                }
+                console.error('🎤 [WebRTC] Microphone access failed:', err);
+                if (
+                    err.name === 'NotAllowedError' ||
+                    err.name === 'PermissionDeniedError' ||
+                    err.message?.includes('Permission denied')
+                ) {
+                    const ua = typeof navigator !== 'undefined' ? navigator.userAgent : '';
+                    const isIOS = /iPad|iPhone|iPod/.test(ua) ||
+                        (typeof navigator !== 'undefined' &&
+                            navigator.platform === 'MacIntel' &&
+                            navigator.maxTouchPoints > 1);
+                    let customMsg = "Microphone access denied. Please allow microphone access in your browser settings.";
+
+                    if (isIOS) {
+                        if (ua.includes('CriOS')) {
+                            customMsg = "Microphone access blocked. Please enable it in iOS Settings > Chrome > Microphone, then reload the page.";
+                        } else if (ua.includes('FxiOS')) {
+                            customMsg = "Microphone access blocked. Please enable it in iOS Settings > Firefox > Microphone, then reload the page.";
+                        } else {
+                            customMsg = "Microphone access blocked. Please enable it in iOS Settings > Safari > Microphone (or tap 'aA' > Website Settings > Allow Microphone).";
+                        }
+                    }
+                    const newErr = new Error(customMsg);
+                    (newErr as any).name = err.name;
+                    throw newErr;
+                }
+                throw err;
+            }
+            console.log('🎤 [WebRTC] Microphone access granted');
+            this.localStream = stream;
+
+            if (!this.pc) {
+                console.log('[WebRTC] Connection aborted: peer connection closed during setup');
+                this.mediaAdapter.stopStream(stream);
+                return;
+            }
+
+            this.onLocalStream(stream);
+
+            stream.getTracks().forEach(track => {
+                this.pc?.addTrack(track, stream);
+            });
+
+            if (!this.pc) {
+                throw new Error('RTCPeerConnection was closed unexpectedly');
+            }
+
+            this.dataChannel = this.pc.createDataChannel('control');
+            this.dcController = this.dataChannelAdapter.bind(this.dataChannel, {
+                onOpen: () => {
+                    console.log('📡 [WebRTC] DataChannel opened');
+                    this.flushPendingOutbound();
+                    this.tryNotifyConnected();
+                },
+                onMessage: ({ text }) => {
+                    try {
+                        this.handleControlEvent(JSON.parse(text));
+                    } catch {
+                        console.warn('[WebRTC] Failed to parse message:', text);
+                    }
+                },
+                onError: (e) => console.error('❌ [WebRTC] DataChannel error:', e),
+            });
+
+            this.pc.ontrack = (event) => {
+                const track = event.track;
+                let stream = event.streams?.[0];
+                if (!stream && track) {
+                    // react-native-webrtc may omit event.streams on some Android builds.
+                    stream = new MediaStream([track]);
+                }
+                console.log(`📥 [WebRTC] Received ${track.kind} track`);
+
+                if (track.kind === 'audio') {
+                    console.log('🔊 [WebRTC] Received audio track from server');
+                    track.enabled = true;
+                    this.audioPlayer?.cleanup();
+                    if (stream) {
+                        this.audioPlayer = this.audioAdapter.createRemotePlayer(stream);
+                    }
+
+                    if (this.capabilities.supportsAudioEndedEvent) {
+                        this.audioPlayer.onEnded(() => {
+                            this.sendEvent('playedStream');
+                            console.log('✅ [WebRTC] TTS playback complete');
+                        });
+                    }
+
+                    this.onRemoteTrack(track, stream);
+                } else if (track.kind === 'video') {
+                    console.log('📹 [WebRTC] Video track received');
+                    this.onRemoteTrack(track, stream);
+                }
+            };
+
+            const checkConnectionState = () => {
+                console.log('🔄 [WebRTC] State:', this.pc?.connectionState, '| ICE:', this.pc?.iceConnectionState);
+                const isConnected =
+                    this.pc?.connectionState === 'connected' ||
+                    this.pc?.iceConnectionState === 'connected' ||
+                    this.pc?.iceConnectionState === 'completed';
+
+                const isFailed =
+                    this.pc?.connectionState === 'failed' ||
+                    this.pc?.iceConnectionState === 'failed' ||
+                    this.pc?.connectionState === 'closed' ||
+                    this.pc?.iceConnectionState === 'closed' ||
+                    this.pc?.connectionState === 'disconnected' ||
+                    this.pc?.iceConnectionState === 'disconnected';
+
+                if (isConnected && !this.connected) {
+                    this.connected = true;
+                    this.tryNotifyConnected();
+                } else if (isFailed && this.connected) {
+                    this.connected = false;
+                    this.onDisconnected();
+                }
+            };
+
+            this.pc.onconnectionstatechange = checkConnectionState;
+            this.pc.oniceconnectionstatechange = checkConnectionState;
+
+            const offer = await this.pc.createOffer();
+            await this.pc.setLocalDescription(offer);
+            console.log('📝 [WebRTC] Created offer — sending immediately (trickle ICE)');
+
+            const fetchUrl = this.serverUrl;
+            console.log('[WebRTC] Offer POST URL:', fetchUrl);
+            if (this.bailIfTeardown('connect() before offer POST')) {
+                return;
+            }
+
+            const response = await fetch(fetchUrl, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    offer: this.pc.localDescription,
+                    agentId: this.agentId,
+                    callId: this.callId,
+                }),
+            });
+
+            const payload = await readResponseJson<{
+                answer?: RTCSessionDescriptionInit;
+                error?: string;
+            }>(response, 'WebRTC offer exchange');
+            if (this.bailIfTeardown('connect() after offer POST')) {
+                return;
+            }
+
+            if (!response.ok) {
+                throw new Error(payload.error || `WebRTC offer exchange failed (HTTP ${response.status})`);
+            }
+
+            if (!payload.answer) {
+                throw new Error(
+                    `WebRTC offer exchange: response missing answer (HTTP ${response.status})`,
+                );
+            }
+
+            console.log('📥 [WebRTC] Received answer from server');
+            await this.pc.setRemoteDescription(payload.answer);
+            this.startIceTricklePoll(this.pc, iceTrickleUrl);
+            console.log('✅ [WebRTC] SDP exchange complete — trickle ICE polling active');
+
+        } catch (error: any) {
+            if (this.teardownRequested) {
+                console.log('[WebRTC] Connect aborted during teardown');
+                return;
+            }
+            console.error('❌ [WebRTC] Connection failed:', error);
+            this.disconnect();
+            this.onError(error.message || error);
+            throw error;
+        }
+    }
+
+    /** POST local ICE candidates to worker as they are gathered (trickle ICE). */
+    private bindIceTrickle(pc: RTCPeerConnection, iceTrickleUrl: string): void {
+        pc.onicecandidate = (event) => {
+            if (!event.candidate) {
+                return;
+            }
+            fetch(iceTrickleUrl, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ candidate: event.candidate.toJSON() }),
+            }).catch((err) => {
+                console.warn('[WebRTC] ICE trickle POST failed:', err);
+            });
+        };
+    }
+
+    /** Poll remote ICE candidates from worker after answer is set. */
+    private startIceTricklePoll(pc: RTCPeerConnection, iceTrickleUrl: string): void {
+        if (isWorkerSdpUrl(iceTrickleUrl)) {
+            throw new Error(
+                '[WebRTC] ICE poll URL must be /webrtc/ice — got SDP worker_url (GET would 405)',
+            );
+        }
+
+        this.stopIceTricklePoll();
+        this.seenRemoteIceCandidates.clear();
+
+        this.iceTricklePollTimer = setInterval(async () => {
+            if (
+                pc.connectionState === 'connected' ||
+                pc.connectionState === 'closed' ||
+                pc.connectionState === 'failed'
+            ) {
+                this.stopIceTricklePoll();
+                return;
+            }
+
+            try {
+                const response = await fetch(iceTrickleUrl, { method: 'GET' });
+                if (!response.ok) {
+                    return;
+                }
+                const payload = await readResponseJson<{ candidates?: RTCIceCandidateInit[] }>(
+                    response,
+                    'ICE trickle GET',
+                );
+                for (const candidate of payload.candidates ?? []) {
+                    const key = JSON.stringify(candidate);
+                    if (this.seenRemoteIceCandidates.has(key)) {
+                        continue;
+                    }
+                    this.seenRemoteIceCandidates.add(key);
+                    try {
+                        await pc.addIceCandidate(candidate);
+                    } catch {
+                        /* ignore duplicate or late candidates */
+                    }
+                }
+            } catch (err) {
+                console.warn('[WebRTC] ICE trickle poll failed:', err);
+            }
+        }, ICE_TRICKLE_POLL_MS);
+    }
+
+    private stopIceTricklePoll(): void {
+        if (this.iceTricklePollTimer) {
+            clearInterval(this.iceTricklePollTimer);
+            this.iceTricklePollTimer = null;
+        }
+    }
+
+    private isPeerTransportReady(): boolean {
+        return (
+            this.pc?.connectionState === 'connected' ||
+            this.pc?.iceConnectionState === 'connected' ||
+            this.pc?.iceConnectionState === 'completed'
+        );
+    }
+
+    /** Fire onConnected once peer transport and DataChannel are both ready. */
+    private tryNotifyConnected(): void {
+        if (this.connectedNotified || !this.connected) {
+            return;
+        }
+        if (!this.isPeerTransportReady() || !this.dcController?.isOpen()) {
+            return;
+        }
+        this.connectedNotified = true;
+        this.stopIceTricklePoll();
+        if (!this.capabilities.supportsAudioEndedEvent) {
+            activateCallAudioPlayback();
+        }
+        this.onConnected();
+    }
+
+    private flushPendingOutbound(): void {
+        if (!this.dcController?.isOpen()) {
+            return;
+        }
+        while (this.pendingOutbound.length > 0) {
+            const text = this.pendingOutbound.shift()!;
+            this.dcController.send(text);
+            try {
+                const payload = JSON.parse(text) as { event?: string };
+                console.log(`📤 [WebRTC] Flushed queued event: ${payload.event ?? 'unknown'}`);
+            } catch {
+                console.log('📤 [WebRTC] Flushed queued DataChannel message');
+            }
+        }
+    }
+
+    private sendDataChannelPayload(payload: Record<string, unknown>): void {
+        const text = JSON.stringify(payload);
+        const eventName = typeof payload.event === 'string' ? payload.event : 'message';
+
+        if (this.dcController?.isOpen()) {
+            console.log(`📤 [WebRTC] Sending event: ${eventName}`, payload);
+            this.dcController.send(text);
+            return;
+        }
+
+        if (this.pc && this.pc.connectionState !== 'closed') {
+            this.pendingOutbound.push(text);
+            console.log(`📤 [WebRTC] Queued event: ${eventName} (DataChannel opening)`);
+            return;
+        }
+
+        console.warn(`⚠️ [WebRTC] Cannot send event ${eventName} - DataChannel not open`);
+    }
+
+    sendEvent(event: string, data = {}): void {
+        this.sendDataChannelPayload({ event, ...data });
+    }
+
+    /**
+     * Observe every inbound DataChannel control event (harness / debugging).
+     * Fires before internal routing. Returns false when not connected.
+     */
+    tapControlEvents(handler: (msg: ControlEvent) => void): boolean {
+        this.controlEventTap = handler;
+        return true;
+    }
+
+    /** Harness-only: replay an inbound DataChannel frame through normal routing. */
+    injectControlEvent(msg: ControlEvent): void {
+        this.handleControlEvent(msg);
+    }
+
+    /**
+     * RN has no audio onended. Web sends playedStream only when playback finishes.
+     * Do NOT send on `mark` — that fires at TTS start and causes the worker to skip audio.
+     */
+    private schedulePlayedStreamAfterTranscription(): void {
+        if (this.capabilities.supportsAudioEndedEvent) {
+            return;
+        }
+        if (this.playedStreamFallbackTimer) {
+            clearTimeout(this.playedStreamFallbackTimer);
+        }
+        this.playedStreamFallbackTimer = setTimeout(() => {
+            this.playedStreamFallbackTimer = null;
+            this.sendEvent('playedStream');
+            console.log(
+                '📤 [WebRTC] playedStream sent after final transcription (RN)',
+            );
+        }, WebRTCClient.PLAYED_STREAM_AFTER_TRANSCRIPTION_MS);
+    }
+
+    private clearPlayedStreamFallback(): void {
+        if (this.playedStreamFallbackTimer) {
+            clearTimeout(this.playedStreamFallbackTimer);
+            this.playedStreamFallbackTimer = null;
+        }
+    }
+
+    /** Notify board queue to cancel in-flight write/erase animations. */
+    private dispatchBoardAbort(reason: string, toolCallId?: string): void {
+        dispatchBoardAbort(reason, toolCallId);
+    }
+
+    private handleControlEvent(msg: ControlEvent): void {
+        this.controlEventTap?.(msg);
+
+        switch (msg.event) {
+            case 'clearAudio':
+                console.log('🛑 [WebRTC] Interrupt: clearAudio received (leaving stream unpaused)');
+                this.clearPlayedStreamFallback();
+                this.dispatchBoardAbort('Server interrupted');
+                break;
+
+            case 'transcription':
+                console.log('📝 [WebRTC] Transcription:', msg.text);
+                // @ts-ignore
+                this.onTranscription(msg.text, msg.isFinal);
+                // @ts-ignore
+                if (!this.capabilities.supportsAudioEndedEvent && msg.isFinal) {
+                    this.schedulePlayedStreamAfterTranscription();
+                }
+                break;
+
+            case 'mark':
+                // @ts-ignore
+                console.log('🏷️ [WebRTC] Mark:', msg.name);
+                break;
+
+            case 'client_tool_cancel': {
+                const cancelData = ((msg as ControlEvent & {data?: Record<string, unknown>}).data || msg) as Record<string, unknown>;
+                const cancelledId =
+                    (cancelData.tool_call_id as string | undefined)
+                    || ((msg as ControlEvent & {tool_call_id?: string}).tool_call_id);
+                console.log('🛑 [WebRTC] client_tool_cancel received:', cancelledId || '(all)');
+                this.dispatchBoardAbort('Tool cancelled by server', cancelledId);
+                break;
+            }
+
+            case 'client_tool_call': {
+                const toolCallData = unwrapToolCallData(msg.tool_call || msg.data || msg);
+                const normalized = normalizeToolCallFields(toolCallData);
+                const toolCallId = normalized.tool_call_id || (msg as any).tool_call_id || '';
+
+                if (toolCallId) {
+                    this.sendToolAck(toolCallId);
+                } else {
+                    console.warn('⚠️ [VaniraAI] client_tool_call received without tool_call_id — ack skipped');
+                }
+
+                const toolArgs = normalized.arguments;
+                const clientFields = normalized.client_fields;
+                const presetId = clientFields?.preset_id || toolArgs?.preset_id;
+
+                const wireToolCall = {
+                    tool_call_id: normalized.tool_call_id,
+                    name: normalized.name,
+                    arguments: normalized.arguments,
+                    execution_mode: normalized.execution_mode,
+                    client_fields: normalized.client_fields,
+                };
+
+                if (presetId) {
+                    console.log(`🎨 [VaniraAI] Preset detected: ${presetId}`);
+                    console.log(`🎨 [VaniraAI] Tool args:`, toolArgs);
+                    console.log(`🎨 [VaniraAI] Client fields:`, clientFields);
+
+                    const presetPayload: PresetEventPayload = {
+                        toolCall: wireToolCall,
+                        client: this,
+                    };
+
+                    this.onPreset?.(presetPayload);
+
+                    console.log(`🎨 [VaniraAI] Preset "${presetId}" — dispatching vanira:preset event`);
+                    if (canDispatchBrowserEvent()) {
+                        globalThis.dispatchEvent(new CustomEvent('vanira:preset', {
+                            detail: presetPayload,
+                        }));
+                    }
+
+                    this.onClientToolCall(wireToolCall);
+                    break;
+                }
+
+                console.log('🛠️ [VaniraAI] Client Tool Call:', msg);
+                this.onClientToolCall(wireToolCall);
+                break;
+            }
+
+            default:
+                console.log('ℹ️ [WebRTC] Unknown event:', msg.event);
+        }
+    }
+
+    disconnect(): void {
+        if (this.teardownRequested) {
+            return;
+        }
+        this.teardownRequested = true;
+        console.log('🔴 [WebRTC] Disconnecting...');
+
+        resetBoardSession();
+        this.clearPlayedStreamFallback();
+        this.stopIceTricklePoll();
+        this.controlEventTap = null;
+        this.pendingOutbound = [];
+        this.connectedNotified = false;
+
+        if (!this.capabilities.supportsAudioEndedEvent) {
+            stopCallAudioSession();
+        }
+
+        if (this.audioPlayer) {
+            this.audioPlayer.cleanup();
+            this.audioPlayer = null;
+        }
+
+        if (this.dcController) {
+            this.dcController.close();
+            this.dcController = null;
+        }
+        this.dataChannel = null;
+
+        if (this.pc) {
+            this.pc.getSenders().forEach(sender => {
+                if (sender.track) {
+                    sender.track.stop();
+                }
+            });
+            this.pc.close();
+            this.pc = null;
+        }
+
+        if (this.localStream) {
+            this.mediaAdapter.stopStream(this.localStream);
+            this.localStream = null;
+        }
+
+        this.connected = false;
+        this.onDisconnected();
+    }
+
+    /** Mute or unmute the local microphone without ending the call. */
+    setMicrophoneMuted(muted: boolean): boolean {
+        if (!this.localStream) {
+            return false;
+        }
+        const tracks =
+            typeof this.localStream.getAudioTracks === 'function'
+                ? this.localStream.getAudioTracks()
+                : [];
+        for (const track of tracks) {
+            track.enabled = !muted;
+        }
+        return tracks.length > 0;
+    }
+
+    isMicrophoneMuted(): boolean {
+        if (!this.localStream) {
+            return false;
+        }
+        const tracks =
+            typeof this.localStream.getAudioTracks === 'function'
+                ? this.localStream.getAudioTracks()
+                : [];
+        if (tracks.length === 0) {
+            return false;
+        }
+        return !tracks[0].enabled;
+    }
+
+    generateCallId(): string {
+        return this.callIdPrefix + Date.now() + '_' + Math.random().toString(36).substr(2, 8);
+    }
+
+    sendToolResult(callId: string, result: any): void {
+        this.sendEvent('client_tool_result', {
+            call_id: callId,
+            result: result
+        });
+    }
+
+    sendToolAck(toolCallId: string): void {
+        this.sendDataChannelPayload({
+            event: 'client_tool_ack',
+            data: { tool_call_id: toolCallId },
+        });
+    }
+
+    sendContextUpdate(context: Record<string, any>): void {
+        this.sendEvent('client_context_update', { data: { context } });
+    }
+
+    sendActionTrigger(actionName: string, data: Record<string, any> = {}): void {
+        this.sendEvent('client_action_trigger', {
+            data: {
+                action_name: actionName,
+                data
+            }
+        });
+    }
+
+    triggerActionInterrupt(): void {
+        this.sendEvent('action_interrupt');
+        console.log('🛑 [VaniraAI] Triggered client-side action interrupt');
+    }
+
+    async uploadMedia(
+        file: UploadMediaInput,
+        reason: string = 'general',
+        message: string = ''
+    ): Promise<{ media_id: string; url: string; content_type?: string }> {
+        if (!this.serverUrl) {
+            throw new Error('Upload failed: serverUrl is not set. Connect the WebRTCClient first.');
+        }
+        if (!this.callId) {
+            throw new Error('Upload failed: callId is missing.');
+        }
+
+        let uploadBase = '';
+        try {
+            uploadBase = new URL(this.serverUrl).origin;
+        } catch (e) {
+            uploadBase = this.serverUrl.replace(/\/webrtc.*$/, '').replace(/\/$/, '');
+        }
+        const uploadUrl = `${uploadBase}/media/upload`;
+
+        const formData = new FormData();
+        const uploadPayload = isRNUploadFileDescriptor(file)
+            ? {
+                  ...file,
+                  type: normalizeUploadMimeForUpload(file),
+              }
+            : file;
+        formData.append('file', uploadPayload as Blob);
+        formData.append('call_id', this.callId);
+        formData.append('reason', reason);
+
+        const fileLabel = isRNUploadFileDescriptor(file)
+            ? `${file.name} (${file.type}, uri=${file.uri.slice(0, 48)}…)`
+            : `blob type=${uploadFileMimeType(file)}`;
+        console.log(
+            `[VaniraAI] Uploading media to ${uploadUrl} (Call: ${this.callId}, Reason: ${reason}, File: ${fileLabel})...`
+        );
+        const response = await fetch(uploadUrl, {
+            method: 'POST',
+            body: formData,
+        });
+
+        if (!response.ok) {
+            let errorMessage = `HTTP ${response.status}`;
+            try {
+                const errData = await response.json();
+                errorMessage = errData.error || errorMessage;
+            } catch (_) { }
+            throw new Error(`Upload failed: ${errorMessage}`);
+        }
+
+        const data = await response.json();
+        const mediaId = data.media_id;
+        const mediaUrl = data.url;
+        const contentType = data.content_type || uploadFileMimeType(file);
+
+        if (!mediaId || !mediaUrl) {
+            throw new Error('Upload failed: server response missing media_id or url');
+        }
+
+        console.log(`[VaniraAI] Media uploaded successfully. ID: ${mediaId}, URL: ${mediaUrl}`);
+
+        const notification = {
+            event: 'client_media_update',
+            data: {
+                media_id: mediaId,
+                media_url: mediaUrl,
+                content_type: contentType,
+                reason,
+                message,
+            },
+        };
+        this.sendDataChannelPayload(notification);
+        if (this.dcController?.isOpen()) {
+            console.log('[VaniraAI] Sent client_media_update notification via DataChannel:', notification);
+        }
+
+        return { media_id: mediaId, url: mediaUrl, content_type: contentType };
+    }
+
+    /**
+     * @deprecated ICE servers come from POST /calls/create only.
+     */
+    public static async fetchIceServers(
+        _apiKey: string,
+        _backendUrl: string = 'https://api.vanira.io',
+    ): Promise<RTCIceServer[]> {
+        throw new Error(
+            '[VaniraSDK] fetchIceServers is removed — use ice_servers from POST /calls/create',
+        );
+    }
+}