@telnyx/webrtc 2.27.0-beta.5 → 2.27.0-beta.6

package/lib/src/Modules/Verto/BaseSession.d.ts

@@ -1,6 +1,7 @@
 import type { Logger } from 'loglevel';
 import BaseMessage from './messages/BaseMessage';
 import Connection from './services/Connection';
+import type { PeerFailureEvidence } from './util/interfaces/SignalingHealth';
 import { SwEvent } from './util/constants';
 import type { ITelnyxErrorEvent } from './util/errors';
 import { BroadcastParams, ILoginParams, IVertoOptions } from './util/interfaces';
@@ -36,6 +37,7 @@ export default abstract class BaseSession {
     private static readonly TOKEN_EXPIRY_WARNING_SECONDS;
     private static readonly CALL_REPORT_UPLOAD_DRAIN_TIMEOUT_MS;
     private _pendingCallReportUploads;
+    private _signalingHealthMonitor;
     private _executeQueue;
     private _pong;
     private registerAgent;
@@ -94,6 +96,14 @@ export default abstract class BaseSession {
     private _resetKeepAlive;
     _triggerKeepAliveTimeoutCheck(): void;
     setPingReceived(): void;
+    private _onSocketActivity;
+    hasActiveCall(): boolean;
+    startSignalingHealthMonitor(): void;
+    stopSignalingHealthMonitor(): void;
+    triggerIceRestart(callId: string): void;
+    onSignalingRequestTimeout(requestId: string, timeoutMs: number, method?: string): void;
+    reportPeerFailure(callId: string, evidence: PeerFailureEvidence): void;
+    reportNoRtp(callId: string, direction: 'inbound' | 'outbound'): void;
     static on(eventName: string, callback: any): void;
     static off(eventName: string): void;
     static uuid(): string;

package/lib/src/Modules/Verto/services/Connection.d.ts

@@ -3,14 +3,20 @@ export declare const setWebSocket: (websocket: typeof WebSocket) => void;
 export default class Connection {
     session: BaseSession;
     previousGatewayState: string;
+    lastInboundAt: number;
+    socketGeneration: number;
     private _wsClient;
     private _host;
     private _timers;
     private _useCanaryRtcServer;
     private _hasCanaryBeenUsed;
     private _safetyTimeoutId;
+    private _pendingRequestIds;
+    private _pendingRequestTimers;
+    private _pendingRequestRejecters;
     upDur: number | null;
     downDur: number | null;
+    static DEFAULT_REQUEST_TIMEOUT_MS: number;
     constructor(session: BaseSession);
     get connected(): boolean;
     get connecting(): boolean;
@@ -21,13 +27,14 @@ export default class Connection {
     get host(): string;
     connect(): void;
     sendRawText(request: string): void;
-    send(bladeObj: any): Promise<any>;
+    send(bladeObj: any, timeoutMs?: number): Promise<any>;
     close(): void;
     private _registerSocketEvents;
     private _deregisterSocketEvents;
     private _handleCloseTimeout;
     private _clearSafetyTimeout;
     private _safetyCleanupSocket;
+    private _cleanupPendingRequests;
     private _unsetTimer;
     private _handleStringResponse;
 }

package/lib/src/Modules/Verto/services/SignalingHealthMonitor.d.ts

@@ -0,0 +1,28 @@
+import type { ISignalingHealthSession, PeerFailureEvidence } from '../util/interfaces/SignalingHealth';
+export default class SignalingHealthMonitor {
+    private readonly _session;
+    private _lastInboundAt;
+    private _lastProbeSentAt;
+    private _probeInFlight;
+    private _intervalId;
+    private _recoveryGeneration;
+    private _pendingMediaRecovery;
+    private static readonly CRITICAL_METHODS;
+    static isCriticalMethod(method: string): boolean;
+    constructor(_session: ISignalingHealthSession);
+    start(): void;
+    stop(): void;
+    get isRunning(): boolean;
+    get isProbeInFlight(): boolean;
+    onSocketActivity(): void;
+    private _probeIfNeeded;
+    onRequestTimeout(requestId: string, timeoutMs: number, method?: string): void;
+    onPeerFailure(callId: string, evidence: PeerFailureEvidence): void;
+    onNoRtp(callId: string, direction: 'inbound' | 'outbound'): void;
+    private _check;
+    private _sendProbe;
+    private _recoverMediaOrSignaling;
+    private _getSignalingHealthState;
+    private _triggerSignalingRecovery;
+    private _triggerIceRestart;
+}

package/lib/src/Modules/Verto/util/constants/errorCodes.d.ts

@@ -37,10 +37,15 @@ export declare const TELNYX_WARNING_CODES: {
     readonly PEER_CONNECTION_FAILED: 33004;
     readonly ONLY_HOST_ICE_CANDIDATES: 33005;
     readonly ANSWER_WHILE_PEER_ACTIVE: 33006;
+    readonly ICE_CANDIDATE_PAIR_CHANGED: 33008;
     readonly DUPLICATE_INBOUND_ANSWER: 33007;
     readonly TOKEN_EXPIRING_SOON: 34001;
     readonly SESSION_NOT_REATTACHED: 35001;
+    readonly SIGNALING_HEALTH_PROBE_TIMEOUT: 36001;
+    readonly SIGNALING_REQUEST_TIMEOUT: 36002;
+    readonly SIGNALING_RECOVERY_REQUIRED: 36003;
+    readonly MEDIA_RECOVERY_REQUIRED: 36004;
 };
 export declare const SDP_CREATE_OFFER_FAILED: 40001, SDP_CREATE_ANSWER_FAILED: 40002, SDP_SET_LOCAL_DESCRIPTION_FAILED: 40003, SDP_SET_REMOTE_DESCRIPTION_FAILED: 40004, SDP_SEND_FAILED: 40005, MEDIA_MICROPHONE_PERMISSION_DENIED: 42001, MEDIA_DEVICE_NOT_FOUND: 42002, MEDIA_GET_USER_MEDIA_FAILED: 42003, HOLD_FAILED: 44001, INVALID_CALL_PARAMETERS: 44002, BYE_SEND_FAILED: 44003, SUBSCRIBE_FAILED: 44004, PEER_CLOSED_DURING_INIT: 44005, WEBSOCKET_CONNECTION_FAILED: 45001, WEBSOCKET_ERROR: 45002, RECONNECTION_EXHAUSTED: 45003, GATEWAY_FAILED: 45004, LOGIN_FAILED: 46001, INVALID_CREDENTIALS: 46002, AUTHENTICATION_REQUIRED: 46003, ICE_RESTART_FAILED: 47001, NETWORK_OFFLINE: 48001, UNEXPECTED_ERROR: 49001;
-export declare const HIGH_RTT: 31001, HIGH_JITTER: 31002, HIGH_PACKET_LOSS: 31003, LOW_MOS: 31004, LOW_LOCAL_AUDIO: 31005, LOW_BYTES_RECEIVED: 32001, LOW_BYTES_SENT: 32002, ICE_CONNECTIVITY_LOST: 33001, ICE_GATHERING_TIMEOUT: 33002, ICE_GATHERING_EMPTY: 33003, PEER_CONNECTION_FAILED: 33004, ONLY_HOST_ICE_CANDIDATES: 33005, ANSWER_WHILE_PEER_ACTIVE: 33006, DUPLICATE_INBOUND_ANSWER: 33007, TOKEN_EXPIRING_SOON: 34001, SESSION_NOT_REATTACHED: 35001;
+export declare const HIGH_RTT: 31001, HIGH_JITTER: 31002, HIGH_PACKET_LOSS: 31003, LOW_MOS: 31004, LOW_LOCAL_AUDIO: 31005, LOW_BYTES_RECEIVED: 32001, LOW_BYTES_SENT: 32002, ICE_CONNECTIVITY_LOST: 33001, ICE_GATHERING_TIMEOUT: 33002, ICE_GATHERING_EMPTY: 33003, PEER_CONNECTION_FAILED: 33004, ONLY_HOST_ICE_CANDIDATES: 33005, ANSWER_WHILE_PEER_ACTIVE: 33006, ICE_CANDIDATE_PAIR_CHANGED: 33008, DUPLICATE_INBOUND_ANSWER: 33007, TOKEN_EXPIRING_SOON: 34001, SESSION_NOT_REATTACHED: 35001, SIGNALING_HEALTH_PROBE_TIMEOUT: 36001, SIGNALING_REQUEST_TIMEOUT: 36002, SIGNALING_RECOVERY_REQUIRED: 36003, MEDIA_RECOVERY_REQUIRED: 36004;
 export declare const HAS_NON_HOST_ICE_CANDIDATE_REGEX: RegExp;

package/lib/src/Modules/Verto/util/constants/index.d.ts

@@ -45,6 +45,7 @@ export declare enum SwEvent {
     SocketError = "telnyx.socket.error",
     SocketMessage = "telnyx.socket.message",
     SpeedTest = "telnyx.internal.speedtest",
+    SocketActivity = "telnyx.internal.socketActivity",
     Ready = "telnyx.ready",
     Error = "telnyx.error",
     Warning = "telnyx.warning",

package/lib/src/Modules/Verto/util/constants/warnings.d.ts

@@ -103,6 +103,13 @@ export declare const SDK_WARNINGS: {
         readonly causes: readonly ["Application called answer() twice on the same call object", "Multiple click handlers or event listeners triggering answer()"];
         readonly solutions: readonly ["Ensure answer() is called only once per call", "Disable the answer button after the first click", "Check that answer() is not invoked from multiple event handlers"];
     };
+    readonly 33008: {
+        readonly name: "ICE_CANDIDATE_PAIR_CHANGED";
+        readonly message: "ICE candidate pair changed mid-call";
+        readonly description: "The selected ICE candidate pair changed during an active call. This indicates a network path shift — for example, a Wi-Fi to cellular handoff, a NAT rebinding, or a relay fallback. The call may continue normally, but the path change can briefly affect audio quality.";
+        readonly causes: readonly ["Network interface change (e.g. Wi-Fi to cellular)", "NAT rebinding or IP address change", "Previous candidate pair failed and ICE selected an alternative", "Network topology change"];
+        readonly solutions: readonly ["Monitor for audio quality degradation after the path change", "Check network stability if changes are frequent", "Verify TURN server configuration for relay fallback"];
+    };
     readonly 33007: {
         readonly name: "DUPLICATE_INBOUND_ANSWER";
         readonly message: "Call answer ignored because another inbound call is already being answered";
@@ -117,6 +124,34 @@ export declare const SDK_WARNINGS: {
         readonly causes: readonly ["Token was issued with a limited lifetime"];
         readonly solutions: readonly ["Generate a new authentication token", "Reconnect with fresh credentials before the token expires"];
     };
+    readonly 36001: {
+        readonly name: "SIGNALING_HEALTH_PROBE_TIMEOUT";
+        readonly message: "Signaling health probe timed out";
+        readonly description: "A signaling liveness probe (Ping) was sent during an active call but no response was received within the timeout window. This indicates the WebSocket may be half-dead — the browser reports it as OPEN but data is not flowing. The SDK will force-close the socket to trigger reconnection.";
+        readonly causes: readonly ["Network interface removed mid-call while another interface remains", "TCP connection bound to a removed IP/route became half-dead", "Firewall or NAT state expired silently", "WebSocket proxy or load balancer dropped the connection without a close frame"];
+        readonly solutions: readonly ["The SDK will automatically force-close the socket and reconnect", "Check for network interface changes during the call", "Verify firewall/NAT timeout settings"];
+    };
+    readonly 36002: {
+        readonly name: "SIGNALING_REQUEST_TIMEOUT";
+        readonly message: "Signaling request timed out";
+        readonly description: "A signaling-critical JSON-RPC request (e.g. ICE restart Modify) did not receive a response within the timeout window while the socket reports OPEN. This may indicate the WebSocket is half-dead or the server is unresponsive. The SDK will mark signaling as unhealthy and force reconnection.";
+        readonly causes: readonly ["Half-dead WebSocket (browser reports OPEN but data does not flow)", "Server unresponsive or overloaded", "Network path interruption without TCP RST"];
+        readonly solutions: readonly ["The SDK will automatically force-close the socket and reconnect", "Check server health and response times", "Check for network path issues"];
+    };
+    readonly 36003: {
+        readonly name: "SIGNALING_RECOVERY_REQUIRED";
+        readonly message: "Signaling recovery required";
+        readonly description: "The signaling (WebSocket) path has been detected as unhealthy and the SDK will force-close the socket and reconnect. If media was still flowing, the reconnect is delayed briefly to allow the application to notify the user about a short interruption. Active calls will be recovered via reattach after reconnection.";
+        readonly causes: readonly ["WebSocket probe timed out with no response", "Critical signaling request timed out", "Peer/media failure detected while signaling is also unhealthy"];
+        readonly solutions: readonly ["The SDK will automatically reconnect and recover the call", "Check for network interface changes or interruptions", "Verify firewall/NAT timeout settings"];
+    };
+    readonly 36004: {
+        readonly name: "MEDIA_RECOVERY_REQUIRED";
+        readonly message: "Media recovery required";
+        readonly description: "The peer connection or media flow has been detected as unhealthy while signaling is healthy. The SDK will attempt ICE restart to recover the media path. No socket reconnection is needed.";
+        readonly causes: readonly ["ICE connection state changed to failed", "RTCPeerConnection state changed to failed", "No RTP packets/bytes received while media should be active"];
+        readonly solutions: readonly ["The SDK will automatically attempt ICE restart", "Check network connectivity and ICE candidate availability", "Verify TURN server configuration"];
+    };
     readonly 35001: {
         readonly name: "SESSION_NOT_REATTACHED";
         readonly message: "Active call lost after reconnect";

package/lib/src/Modules/Verto/util/errors.d.ts

@@ -46,3 +46,15 @@ export declare class TelnyxError extends Error implements ITelnyxError {
 export declare function isMediaRecoveryErrorEvent(event: ITelnyxErrorEvent): event is ITelnyxMediaRecoveryErrorEvent;
 export declare function classifyMediaErrorCode(error: unknown): typeof MEDIA_MICROPHONE_PERMISSION_DENIED | typeof MEDIA_DEVICE_NOT_FOUND | typeof MEDIA_GET_USER_MEDIA_FAILED;
 export declare function createTelnyxError(code: SdkErrorCode, originalError?: unknown, message?: string): TelnyxError;
+export declare class RequestTimeoutError extends Error {
+    readonly requestId: string;
+    readonly timeoutMs: number;
+    readonly method: string;
+    constructor(requestId: string, timeoutMs: number, method?: string);
+}
+export declare class StaleRequestError extends Error {
+    readonly requestId: string;
+    readonly staleGeneration: number;
+    readonly currentGeneration: number;
+    constructor(requestId: string, staleGeneration: number, currentGeneration: number);
+}

package/lib/src/Modules/Verto/util/interfaces/SignalingHealth.d.ts

@@ -0,0 +1,10 @@
+import type Connection from '../../services/Connection';
+export declare type PeerFailureEvidence = 'ice_failed' | 'connection_failed';
+export interface ISignalingHealthSession {
+    uuid: string;
+    sessionid: string;
+    connection: Connection | null;
+    hasActiveCall(): boolean;
+    socketDisconnect(): void;
+    triggerIceRestart(callId: string): void;
+}

package/lib/src/Modules/Verto/webrtc/BaseCall.d.ts

@@ -57,6 +57,7 @@ export default abstract class BaseCall implements IWebRTCCall {
     get remoteStream(): MediaStream;
     get memberChannel(): string;
     get isAudioMuted(): boolean;
+    private _hasActiveUnmutedLocalAudioTrack;
     shouldForceRelayCandidateForRecovery(): boolean;
     invite(): Promise<void>;
     answer(params?: AnswerParams): Promise<void>;

package/lib/src/Modules/Verto/webrtc/CallReportCollector.d.ts

@@ -145,7 +145,7 @@ export declare class CallReportCollector {
     private intervalRTTs;
     private intervalBitrates;
     private previousStats;
-    private previousCandidatePairId;
+    private previousCandidatePairSnapshot;
     private static readonly INITIAL_COLLECTION_INTERVAL_MS;
     private static readonly INITIAL_COLLECTION_DURATION_MS;
     private readonly MAX_BUFFER_SIZE;
@@ -167,6 +167,7 @@ export declare class CallReportCollector {
     private static readonly WARNING_THROTTLE_MS;
     private _prevPacketsReceived;
     private _prevPacketsLost;
+    private _previousStatsEntryForWarnings;
     private _lastLocalAudioTrackSnapshotJson;
     private _hasConfirmedLocalAudio;
     private _confirmedLocalAudioSilenceMs;

package/lib/src/Modules/Verto/webrtc/Peer.d.ts

@@ -29,6 +29,7 @@ export default class Peer {
     private _offlineHandler;
     constructor(type: PeerType, options: IVertoCallOptions, session: BrowserSession, trickleIceSdpFn: (sdp: RTCSessionDescriptionInit) => void, registerPeerEvents: (instance: RTCPeerConnection) => void);
     finishIceRestart(): void;
+    restartIce(): boolean;
     get isOffer(): boolean;
     get isAnswer(): boolean;
     get isDebugEnabled(): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telnyx/webrtc",
-  "version": "2.27.0-beta.5",
+  "version": "2.27.0-beta.6",
   "description": "Telnyx WebRTC Client",
   "keywords": [
     "telnyx",