@cemscale-voip/voip-sdk 1.26.0 → 1.27.0

package/dist/webrtc.js

@@ -0,0 +1,758 @@
+// ============================================================
+// @cemscale/voip-sdk — WebRTC SIP Client (SIP.js 0.21 wrapper)
+// ============================================================
+import { UserAgent, Registerer, RegistererState, Invitation, Inviter, SessionState } from 'sip.js';
+// -------------------------------------------------------------------
+// SDP modifier: restrict audio to G.711 (PCMU/PCMA) + telephone-event
+// -------------------------------------------------------------------
+/**
+ * Returns an SDP modifier that strips all audio codecs except PCMU (G.711µ),
+ * PCMA (G.711A), and telephone-event (RFC 4733 DTMF).
+ *
+ * WHY: Twilio's PSTN gateway natively uses G.711. When the webphone offers
+ * OPUS, FreeSWITCH must activate a write resampler to transcode OPUS↔PCMU
+ * on every bridge. This transcoding introduces latency and timing instability
+ * that causes the call to terminate immediately after the 200 OK (observed as
+ * "call drops after one ring"). By restricting the webphone to G.711 only,
+ * FreeSWITCH performs zero-copy media passthrough — no resampler, no codec
+ * conversion, no timing skew.
+ *
+ * BROWSER SUPPORT: G.711 (PCMU/PCMA) is mandatory in the WebRTC spec (RFC 7874).
+ * All browsers (Chrome, Firefox, Safari, Edge) support it.
+ */
+function makeG711SdpModifier() {
+    return async (desc) => {
+        if (!desc.sdp)
+            return desc;
+        const lines = desc.sdp.split(/\r\n|\r|\n/);
+        // Static G.711 payload types (per RFC 3551, always 0 and 8)
+        const kept = new Set(['0', '8']);
+        let inAudio = false;
+        // Pass 1 — collect dynamic telephone-event payload numbers in the audio section
+        for (const line of lines) {
+            if (line.startsWith('m=audio')) {
+                inAudio = true;
+                continue;
+            }
+            if (line.startsWith('m=') && !line.startsWith('m=audio')) {
+                inAudio = false;
+                continue;
+            }
+            if (!inAudio)
+                continue;
+            const m = line.match(/^a=rtpmap:(\d+)\s+telephone-event\//i);
+            if (m)
+                kept.add(m[1]);
+        }
+        // Pass 2 — rebuild SDP keeping only G.711 + telephone-event lines
+        inAudio = false;
+        const out = [];
+        for (const line of lines) {
+            if (line.startsWith('m=audio')) {
+                inAudio = true;
+                // Rewrite "m=audio <port> <proto> <pt1> <pt2> ..." keeping only our payloads
+                const parts = line.split(' ');
+                const prefix = parts.slice(0, 3).join(' ');
+                const filtered = parts.slice(3).filter((pt) => kept.has(pt));
+                // Safety: if nothing matched, keep original (should never happen)
+                out.push(filtered.length ? `${prefix} ${filtered.join(' ')}` : line);
+                continue;
+            }
+            if (line.startsWith('m=') && !line.startsWith('m=audio')) {
+                inAudio = false;
+            }
+            if (inAudio) {
+                // Drop rtpmap / fmtp / rtcp-fb lines for non-kept payload types
+                const rtpmap = line.match(/^a=rtpmap:(\d+)\s/);
+                const fmtp = line.match(/^a=fmtp:(\d+)\s/);
+                const rtcpfb = line.match(/^a=rtcp-fb:(\d+)\s/);
+                if (rtpmap && !kept.has(rtpmap[1]))
+                    continue;
+                if (fmtp && !kept.has(fmtp[1]))
+                    continue;
+                if (rtcpfb && !kept.has(rtcpfb[1]))
+                    continue;
+            }
+            out.push(line);
+        }
+        return { ...desc, sdp: out.join('\r\n') };
+    };
+}
+/**
+ * WebRTCPhone wraps SIP.js 0.21 to provide a high-level phone interface.
+ *
+ * Hold uses the native SIP.js `sessionDescriptionHandlerOptionsReInvite.hold`
+ * API, which internally calls `SessionDescriptionHandler.updateDirection()` to
+ * set transceiver directions correctly before generating the SDP offer.
+ *
+ * Transfer uses SIP REFER (blind) or REFER with Replaces (attended).
+ *
+ * Usage:
+ *   const phone = new WebRTCPhone({
+ *     sipDomain: 'demo.sip.cemscale.com',
+ *     wsUri: 'wss://sip.cemscale.com/ws',
+ *     extension: '1001',
+ *     password: 'secret',
+ *   });
+ *   await phone.start();
+ *   phone.on('incomingCall', (call) => { ... });
+ *   phone.call('1002');
+ */
+export class WebRTCPhone {
+    config;
+    ua = null;
+    registerer = null;
+    currentSession = null;
+    currentCallInfo = null;
+    heldState = false;
+    mutedState = false;
+    holdPending = false;
+    listeners = new Map();
+    audioElement;
+    registered = false;
+    constructor(config) {
+        this.config = config;
+        this.audioElement = config.audioElement || document.createElement('audio');
+        this.audioElement.autoplay = true;
+    }
+    // -------------------------------------------------------------------
+    // Event emitter
+    // -------------------------------------------------------------------
+    on(event, callback) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(callback);
+        return () => {
+            this.listeners.get(event)?.delete(callback);
+        };
+    }
+    emit(event, ...args) {
+        const handlers = this.listeners.get(event);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(...args);
+                }
+                catch (err) {
+                    console.error(`[WebRTCPhone] Event handler error for "${event}":`, err);
+                }
+            }
+        }
+    }
+    // -------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------
+    /** Start the SIP User Agent and register */
+    async start() {
+        const uri = UserAgent.makeURI(`sip:${this.config.extension}@${this.config.sipDomain}`);
+        if (!uri) {
+            throw new Error(`Invalid SIP URI: sip:${this.config.extension}@${this.config.sipDomain}`);
+        }
+        const iceServers = this.config.turnServers || [
+            { urls: 'stun:stun.l.google.com:19302' },
+        ];
+        // Chrome 97+ requires the offerer to use a=setup:actpass (not active/passive).
+        // SIP.js or browser edge-cases can change it to 'active'. This modifier
+        // ensures the offer always has 'actpass' so setRemoteDescription(answer) succeeds.
+        const forceActpass = async (desc) => {
+            if (!desc.sdp)
+                return desc;
+            return {
+                ...desc,
+                sdp: desc.sdp.replace(/a=setup:active\r?\n/g, 'a=setup:actpass\r\n'),
+            };
+        };
+        const sdpModifiers = [forceActpass];
+        this.ua = new UserAgent({
+            uri,
+            transportOptions: {
+                server: this.config.wsUri,
+                connectionTimeout: 10,
+                keepAliveInterval: 25,
+                reconnectionAttempts: 3,
+                reconnectionDelay: 4,
+            },
+            authorizationUsername: this.config.extension,
+            authorizationPassword: this.config.password,
+            displayName: this.config.displayName || this.config.extension,
+            sessionDescriptionHandlerFactoryOptions: {
+                peerConnectionConfiguration: {
+                    iceServers,
+                },
+                // Codec filter applied to every SDP offer and answer (outbound calls,
+                // inbound answers, re-INVITEs for hold/unhold). Defaults to G.711-only.
+                modifiers: sdpModifiers,
+            },
+            delegate: {
+                onInvite: (invitation) => {
+                    this.handleIncomingCall(invitation);
+                },
+            },
+            logLevel: 'warn',
+        });
+        await this.ua.start();
+        // Monitor transport connect/disconnect for auto-re-registration
+        if (this.ua.transport) {
+            const transport = this.ua.transport;
+            const origOnDisconnect = transport.onDisconnect;
+            transport.onDisconnect = (error) => {
+                this.registered = false;
+                this.emit('unregistered');
+                console.warn('[WebRTCPhone] Transport disconnected', error?.message || '');
+                if (origOnDisconnect)
+                    origOnDisconnect.call(transport, error);
+            };
+            const origOnConnect = transport.onConnect;
+            transport.onConnect = () => {
+                console.log('[WebRTCPhone] Transport reconnected, re-registering...');
+                if (origOnConnect)
+                    origOnConnect.call(transport);
+                // Re-register after transport reconnects
+                if (this.registerer) {
+                    this.registerer.register().catch((err) => {
+                        console.error('[WebRTCPhone] Re-registration failed:', err);
+                        this.emit('registrationFailed', err instanceof Error ? err : new Error(String(err)));
+                    });
+                }
+            };
+        }
+        this.registerer = new Registerer(this.ua, { expires: 300 });
+        this.registerer.stateChange.addListener((state) => {
+            switch (state) {
+                case RegistererState.Registered:
+                    this.registered = true;
+                    this.emit('registered');
+                    break;
+                case RegistererState.Unregistered:
+                case RegistererState.Terminated:
+                    this.registered = false;
+                    this.emit('unregistered');
+                    break;
+            }
+        });
+        try {
+            await this.registerer.register();
+        }
+        catch (err) {
+            this.registered = false;
+            this.emit('registrationFailed', err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+    }
+    /** Stop the SIP User Agent */
+    async stop() {
+        if (this.currentSession) {
+            try {
+                await this.hangup();
+            }
+            catch { /* ignore */ }
+        }
+        if (this.registerer) {
+            try {
+                await this.registerer.unregister();
+            }
+            catch { /* ignore */ }
+            this.registerer = null;
+        }
+        if (this.ua) {
+            try {
+                await this.ua.stop();
+            }
+            catch { /* ignore */ }
+            this.ua = null;
+        }
+        this.registered = false;
+        this.currentSession = null;
+        this.currentCallInfo = null;
+        this.heldState = false;
+        this.mutedState = false;
+    }
+    isRegistered() {
+        return this.registered;
+    }
+    /** Get the SIP domain for this phone instance */
+    getSipDomain() {
+        return this.config.sipDomain;
+    }
+    /** Get the underlying SIP.js Session (for advanced use) */
+    getSession() {
+        return this.currentSession;
+    }
+    /** Get current call info (snapshot) */
+    getCurrentCall() {
+        return this.currentCallInfo ? { ...this.currentCallInfo } : null;
+    }
+    // -------------------------------------------------------------------
+    // Outbound calls
+    // -------------------------------------------------------------------
+    async call(target) {
+        if (!this.ua)
+            throw new Error('UserAgent not started. Call start() first.');
+        if (this.currentSession)
+            throw new Error('A call is already in progress.');
+        // Request microphone access before sending the INVITE.
+        // This surfaces permission errors immediately with a clear message,
+        // rather than letting SIP.js fail silently during media negotiation.
+        try {
+            const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+            stream.getTracks().forEach((t) => t.stop()); // Release — SIP.js re-acquires it
+        }
+        catch (err) {
+            const msg = err.name === 'NotAllowedError' || err.name === 'PermissionDeniedError'
+                ? 'Microphone access denied. Allow microphone in browser settings and try again.'
+                : `Microphone unavailable: ${err.message}`;
+            this.emit('error', new Error(msg));
+            throw new Error(msg);
+        }
+        const targetUri = UserAgent.makeURI(`sip:${target}@${this.config.sipDomain}`);
+        if (!targetUri)
+            throw new Error(`Invalid target: ${target}`);
+        const inviter = new Inviter(this.ua, targetUri, {
+            sessionDescriptionHandlerOptions: {
+                constraints: { audio: true, video: false },
+            },
+        });
+        this.currentSession = inviter;
+        this.heldState = false;
+        this.mutedState = false;
+        this.currentCallInfo = {
+            id: inviter.id,
+            direction: 'outbound',
+            remoteIdentity: target,
+            remoteDisplayName: target,
+            state: 'connecting',
+            startTime: new Date(),
+            answerTime: null,
+            held: false,
+            muted: false,
+            dtmfSent: '',
+        };
+        this.setupSessionHandlers(inviter);
+        await inviter.invite();
+        this.emitCallState();
+        return { ...this.currentCallInfo };
+    }
+    // -------------------------------------------------------------------
+    // Inbound calls
+    // -------------------------------------------------------------------
+    handleIncomingCall(invitation) {
+        if (this.currentSession) {
+            // Reject with 486 Busy Here and notify consumer of missed call
+            invitation.reject({ statusCode: 486 });
+            const remoteUri = invitation.remoteIdentity.uri;
+            this.emit('callStateChanged', {
+                id: invitation.id,
+                direction: 'inbound',
+                remoteIdentity: remoteUri.user || 'unknown',
+                remoteDisplayName: invitation.remoteIdentity.displayName || remoteUri.user || 'unknown',
+                state: 'terminated',
+                startTime: new Date(),
+                answerTime: null,
+                held: false,
+                muted: false,
+                dtmfSent: '',
+            });
+            return;
+        }
+        this.currentSession = invitation;
+        this.heldState = false;
+        this.mutedState = false;
+        const remoteUri = invitation.remoteIdentity.uri;
+        this.currentCallInfo = {
+            id: invitation.id,
+            direction: 'inbound',
+            remoteIdentity: remoteUri.user || 'unknown',
+            remoteDisplayName: invitation.remoteIdentity.displayName || remoteUri.user || 'unknown',
+            state: 'ringing',
+            startTime: new Date(),
+            answerTime: null,
+            held: false,
+            muted: false,
+            dtmfSent: '',
+        };
+        this.setupSessionHandlers(invitation);
+        this.emit('incomingCall', { ...this.currentCallInfo });
+        if (this.config.autoAnswer) {
+            this.answer().catch((err) => {
+                this.emit('error', new Error(`Auto-answer failed: ${err.message}`));
+            });
+        }
+    }
+    async answer() {
+        if (!this.currentSession || !(this.currentSession instanceof Invitation)) {
+            throw new Error('No incoming call to answer');
+        }
+        // Request microphone access before accepting — same rationale as call()
+        try {
+            const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+            stream.getTracks().forEach((t) => t.stop());
+        }
+        catch (err) {
+            const msg = err.name === 'NotAllowedError' || err.name === 'PermissionDeniedError'
+                ? 'Microphone access denied. Allow microphone in browser settings to answer calls.'
+                : `Microphone unavailable: ${err.message}`;
+            this.emit('error', new Error(msg));
+            throw new Error(msg);
+        }
+        await this.currentSession.accept({
+            sessionDescriptionHandlerOptions: {
+                constraints: { audio: true, video: false },
+            },
+        });
+    }
+    async reject() {
+        if (!this.currentSession || !(this.currentSession instanceof Invitation)) {
+            throw new Error('No incoming call to reject');
+        }
+        await this.currentSession.reject();
+        this.clearSession();
+    }
+    // -------------------------------------------------------------------
+    // Session controls
+    // -------------------------------------------------------------------
+    async hangup() {
+        if (!this.currentSession)
+            throw new Error('No active call');
+        const session = this.currentSession;
+        try {
+            switch (session.state) {
+                case SessionState.Initial:
+                case SessionState.Establishing:
+                    if (session instanceof Inviter)
+                        await session.cancel();
+                    else if (session instanceof Invitation)
+                        await session.reject();
+                    break;
+                case SessionState.Established:
+                    await session.bye();
+                    break;
+                case SessionState.Terminated:
+                    break;
+                default:
+                    try {
+                        await session.bye();
+                    }
+                    catch { /* ignore */ }
+                    break;
+            }
+        }
+        catch (err) {
+            console.error('[WebRTCPhone] Hangup error:', err);
+        }
+        this.clearSession();
+    }
+    /**
+     * Hold/unhold the current call.
+     *
+     * Uses the SIP.js 0.21 native hold API:
+     * `session.sessionDescriptionHandlerOptionsReInvite.hold = true/false`
+     *
+     * SIP.js internally calls `SessionDescriptionHandler.updateDirection()` which
+     * correctly sets transceiver directions (sendonly for hold, sendrecv for resume)
+     * before generating the SDP offer. This is the same pattern used by SIP.js's
+     * own SessionManager.setHold().
+     *
+     * The re-INVITE is sent to FreeSWITCH which activates/deactivates music-on-hold.
+     */
+    async toggleHold() {
+        if (!this.currentSession || this.currentSession.state !== SessionState.Established) {
+            throw new Error('No established call to hold');
+        }
+        if (!this.currentCallInfo)
+            throw new Error('No call info');
+        if (this.holdPending)
+            throw new Error('Hold operation already in progress');
+        this.holdPending = true;
+        const newHeld = !this.heldState;
+        const session = this.currentSession;
+        // Preemptively update UI state for immediate feedback
+        this.heldState = newHeld;
+        this.currentCallInfo.held = newHeld;
+        this.currentCallInfo.state = newHeld ? 'held' : 'established';
+        this.emitCallState();
+        // Send re-INVITE with hold flag passed directly to the SessionDescriptionHandler.
+        // SIP.js SDH reads `sessionDescriptionHandlerOptions.hold` and sets the correct
+        // SDP direction: hold=true → sendonly, hold=false → sendrecv.
+        // This tells FreeSWITCH to activate/deactivate Music-On-Hold.
+        // Cast to `any` — `hold` is defined in the Web SDH implementation but not in
+        // the base `SessionDescriptionHandlerOptions` TypeScript interface.
+        try {
+            await session.invite({
+                sessionDescriptionHandlerOptions: { hold: newHeld },
+                requestDelegate: {
+                    onAccept: () => {
+                        console.log(`[WebRTCPhone] Hold ${newHeld ? 'ON' : 'OFF'}: accepted`);
+                        this.holdPending = false;
+                        this.emit('holdSucceeded', newHeld);
+                    },
+                    onReject: () => {
+                        console.warn(`[WebRTCPhone] Hold re-INVITE rejected`);
+                        this.holdPending = false;
+                        this.revertHold(!newHeld);
+                        this.emit('holdFailed', new Error('Hold re-INVITE rejected by server'));
+                    },
+                },
+            });
+        }
+        catch (err) {
+            console.error('[WebRTCPhone] Hold re-INVITE failed:', err);
+            this.holdPending = false;
+            this.revertHold(!newHeld);
+            this.emit('holdFailed', new Error(`Hold failed: ${err.message}`));
+            throw err;
+        }
+        return newHeld;
+    }
+    /** Revert local hold state after re-INVITE failure (no SDP change sent) */
+    revertHold(revertTo) {
+        if (!this.currentCallInfo)
+            return;
+        this.heldState = revertTo;
+        this.currentCallInfo.held = revertTo;
+        this.currentCallInfo.state = revertTo ? 'held' : 'established';
+        this.emitCallState();
+    }
+    /** Mute/unmute local audio */
+    toggleMute() {
+        if (!this.currentSession || this.currentSession.state !== SessionState.Established) {
+            throw new Error('No established call to mute');
+        }
+        if (!this.currentCallInfo)
+            throw new Error('No call info');
+        this.mutedState = !this.mutedState;
+        this.enableSenderTracks(!this.mutedState && !this.heldState);
+        this.currentCallInfo.muted = this.mutedState;
+        this.emitCallState();
+        return this.mutedState;
+    }
+    /** Send a DTMF tone */
+    sendDtmf(tone) {
+        if (!this.currentSession || this.currentSession.state !== SessionState.Established) {
+            throw new Error('No established call for DTMF');
+        }
+        const pc = this.getPeerConnection();
+        if (pc) {
+            for (const sender of pc.getSenders()) {
+                if (sender.track?.kind === 'audio' && sender.dtmf) {
+                    sender.dtmf.insertDTMF(tone, 100, 70);
+                    if (this.currentCallInfo) {
+                        this.currentCallInfo.dtmfSent += tone;
+                        this.emitCallState();
+                    }
+                    return;
+                }
+            }
+        }
+        // Fallback: SIP INFO
+        this.currentSession.info({
+            requestOptions: {
+                body: {
+                    contentDisposition: 'render',
+                    contentType: 'application/dtmf-relay',
+                    content: `Signal=${tone}\r\nDuration=100`,
+                },
+            },
+        });
+        if (this.currentCallInfo) {
+            this.currentCallInfo.dtmfSent += tone;
+            this.emitCallState();
+        }
+    }
+    /**
+     * Blind transfer: send SIP REFER to transfer the call to target.
+     * FreeSWITCH handles the actual transfer in its `transfer` dialplan context.
+     */
+    async blindTransfer(target) {
+        if (!this.currentSession || this.currentSession.state !== SessionState.Established) {
+            throw new Error('No established call to transfer');
+        }
+        const targetUri = UserAgent.makeURI(`sip:${target}@${this.config.sipDomain}`);
+        if (!targetUri)
+            throw new Error(`Invalid transfer target: ${target}`);
+        console.log(`[WebRTCPhone] Blind transfer to ${target}@${this.config.sipDomain}`);
+        await this.currentSession.refer(targetUri, {
+            requestDelegate: {
+                onAccept: () => {
+                    console.log('[WebRTCPhone] REFER accepted');
+                    this.emit('transferProgress', { state: 'accepted', message: 'Transfer accepted' });
+                },
+                onReject: () => {
+                    console.warn('[WebRTCPhone] REFER rejected');
+                    this.emit('transferProgress', { state: 'rejected', message: 'Transfer rejected' });
+                },
+            },
+        });
+        this.emit('transferProgress', { state: 'trying', message: `Transferring to ${target}...` });
+    }
+    /**
+     * Attended transfer: REFER with Replaces.
+     * Requires a second Session (the consultation call) that is already established.
+     */
+    async attendedTransfer(targetSession) {
+        if (!this.currentSession || this.currentSession.state !== SessionState.Established) {
+            throw new Error('No established call to transfer');
+        }
+        console.log('[WebRTCPhone] Attended transfer (REFER with Replaces)');
+        await this.currentSession.refer(targetSession, {
+            requestDelegate: {
+                onAccept: () => {
+                    console.log('[WebRTCPhone] Attended REFER accepted');
+                    this.emit('transferProgress', { state: 'accepted', message: 'Transfer completed' });
+                },
+                onReject: () => {
+                    console.warn('[WebRTCPhone] Attended REFER rejected');
+                    this.emit('transferProgress', { state: 'rejected', message: 'Transfer rejected' });
+                },
+            },
+        });
+        this.emit('transferProgress', { state: 'trying', message: 'Completing attended transfer...' });
+    }
+    // -------------------------------------------------------------------
+    // Internal helpers
+    // -------------------------------------------------------------------
+    setupSessionHandlers(session) {
+        // ------------------------------------------------------------------
+        // Explicit BYE delegate — robust backup for remote hangup detection.
+        // SIP.js stateChange should also fire Terminated, but this ensures
+        // the call ends even if stateChange is delayed or missed.
+        // ------------------------------------------------------------------
+        session.delegate = {
+            ...(session.delegate || {}),
+            onBye: (bye) => {
+                console.log('[WebRTCPhone] BYE received from remote party');
+                // SIP.js already sent 200 OK automatically.
+                // Force immediate cleanup if stateChange hasn't fired yet.
+                if (this.currentCallInfo && this.currentCallInfo.state !== 'terminated') {
+                    this.currentCallInfo.state = 'terminated';
+                    this.emitCallState();
+                    this.emit('callEnded', { ...this.currentCallInfo });
+                    this.clearSession();
+                }
+            },
+        };
+        session.stateChange.addListener((state) => {
+            console.log(`[WebRTCPhone] Session stateChange: ${state}`);
+            if (!this.currentCallInfo)
+                return;
+            switch (state) {
+                case SessionState.Establishing:
+                    // Outbound: far-end is ringing (1xx received). Inbound: we accepted, negotiating.
+                    this.currentCallInfo.state =
+                        this.currentCallInfo.direction === 'outbound' ? 'ringing' : 'connecting';
+                    break;
+                case SessionState.Established:
+                    this.currentCallInfo.state = 'established';
+                    this.currentCallInfo.answerTime = new Date();
+                    this.attachRemoteAudio(session);
+                    break;
+                case SessionState.Terminating:
+                    this.currentCallInfo.state = 'terminating';
+                    break;
+                case SessionState.Terminated:
+                    if (this.currentCallInfo.state === 'terminated')
+                        return; // Already handled by onBye
+                    this.currentCallInfo.state = 'terminated';
+                    this.emitCallState();
+                    this.emit('callEnded', { ...this.currentCallInfo });
+                    this.clearSession();
+                    return;
+            }
+            this.emitCallState();
+        });
+    }
+    attachRemoteAudio(session) {
+        const pc = this.getPeerConnection(session);
+        if (!pc)
+            return;
+        const remoteStream = new MediaStream();
+        // Assign srcObject FIRST so the ontrack handler below can safely add tracks to it.
+        // Previously this was set AFTER ontrack, causing a race condition where ontrack
+        // could fire before srcObject was set, silently dropping the remote audio track.
+        this.audioElement.srcObject = remoteStream;
+        // Add tracks that already exist at the moment Established fires
+        for (const receiver of pc.getReceivers()) {
+            if (receiver.track)
+                remoteStream.addTrack(receiver.track);
+        }
+        // Add tracks that arrive later (hold/unhold re-INVITE renegotiation)
+        pc.ontrack = (event) => {
+            if (event.track && !remoteStream.getTrackById(event.track.id)) {
+                remoteStream.addTrack(event.track);
+            }
+        };
+        // Monitor ICE connection state for media path failures
+        pc.oniceconnectionstatechange = () => {
+            if (pc.iceConnectionState === 'failed') {
+                this.emit('error', new Error('ICE connection failed — media path lost'));
+            }
+            else if (pc.iceConnectionState === 'disconnected') {
+                console.warn('[WebRTCPhone] ICE disconnected — may recover');
+            }
+        };
+        this.audioElement.play().catch((err) => {
+            console.warn('[WebRTCPhone] Autoplay blocked — user interaction required:', err?.message);
+            this.emit('error', new Error('Audio playback blocked by browser. Click the page to enable audio.'));
+        });
+    }
+    getPeerConnection(session) {
+        const s = session || this.currentSession;
+        if (!s)
+            return null;
+        const sdh = s.sessionDescriptionHandler;
+        if (!sdh)
+            return null;
+        return sdh.peerConnection || null;
+    }
+    enableSenderTracks(enabled) {
+        const pc = this.getPeerConnection();
+        if (!pc)
+            return;
+        for (const sender of pc.getSenders()) {
+            if (sender.track?.kind === 'audio') {
+                sender.track.enabled = enabled;
+            }
+        }
+    }
+    enableReceiverTracks(enabled) {
+        const pc = this.getPeerConnection();
+        if (!pc)
+            return;
+        for (const receiver of pc.getReceivers()) {
+            if (receiver.track?.kind === 'audio') {
+                receiver.track.enabled = enabled;
+            }
+        }
+    }
+    emitCallState() {
+        if (this.currentCallInfo) {
+            this.emit('callStateChanged', { ...this.currentCallInfo });
+        }
+    }
+    clearSession() {
+        this.currentSession = null;
+        this.currentCallInfo = null;
+        this.heldState = false;
+        this.mutedState = false;
+        this.holdPending = false;
+    }
+    /**
+     * Check if the browser has microphone permission.
+     * Call this before start() to provide a better UX when mic is denied.
+     */
+    static async checkMicrophoneAccess() {
+        try {
+            const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+            stream.getTracks().forEach((t) => t.stop());
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async destroy() {
+        await this.stop();
+        this.listeners.clear();
+    }
+}
+//# sourceMappingURL=webrtc.js.map