@telnyx/react-voice-commons-sdk 0.4.2 → 1.0.0

package/src/internal/calls/call-state-controller.ts

@@ -17,6 +17,7 @@ export class CallStateController {
   private readonly _calls = new BehaviorSubject<Call[]>([]);
   private readonly _callMap = new Map<string, Call>();
   private _disposed = false;
+  private _listenerClient?: TelnyxRTC;
 
   // Callbacks for waiting for invite logic (used for push notifications)
   private _isWaitingForInvite?: () => boolean;
@@ -155,6 +156,9 @@ export class CallStateController {
         callerIdName: callerName,
         callerIdNumber: callerNumber,
         customHeaders,
+        peerConnectionOptions: {
+          useTrickleIce: this._sessionManager.useTrickleIce,
+        },
       };
       const telnyxCall = await this._sessionManager.telnyxClient.newCall(callOptions);
 
@@ -225,6 +229,7 @@ export class CallStateController {
     }
 
     this._disposed = true;
+    this._removeClientListeners();
 
     // Dispose of all calls
     this.currentCalls.forEach((call) => call.dispose());
@@ -241,40 +246,28 @@ export class CallStateController {
   private _setupClientListeners(): void {
     console.log('CallStateController: Setting up client listeners...');
 
-    if (!this._sessionManager.telnyxClient) {
+    const telnyxClient = this._sessionManager.telnyxClient;
+
+    if (!telnyxClient) {
       console.log('CallStateController: No telnyxClient available yet, skipping listener setup');
       return;
     }
 
+    this._removeClientListeners();
+    this._listenerClient = telnyxClient;
+
     console.log('CallStateController: TelnyxClient found, setting up incoming call listener');
-    console.log(
-      'CallStateController: Client instance:',
-      this._sessionManager.telnyxClient.constructor.name
-    );
+    console.log('CallStateController: Client instance:', telnyxClient.constructor.name);
 
     // Listen for incoming calls
-    this._sessionManager.telnyxClient.on(
-      'telnyx.call.incoming',
-      (telnyxCall: TelnyxCall, msg: any) => {
-        console.log('CallStateController: Incoming call received:', telnyxCall.callId);
-        this._handleIncomingCall(telnyxCall, msg, false);
-      }
-    );
+    telnyxClient.on('telnyx.call.incoming', this._handleTelnyxIncomingCall);
 
     // Listen for reattached calls (after network reconnection)
-    this._sessionManager.telnyxClient.on(
-      'telnyx.call.reattached',
-      (telnyxCall: TelnyxCall, msg: any) => {
-        console.log('CallStateController: Reattached call received:', telnyxCall.callId);
-        this._handleIncomingCall(telnyxCall, msg, true);
-      }
-    );
+    telnyxClient.on('telnyx.call.reattached', this._handleTelnyxReattachedCall);
 
     // Verify listeners are set up
-    const incomingListeners =
-      this._sessionManager.telnyxClient.listenerCount('telnyx.call.incoming');
-    const reattachedListeners =
-      this._sessionManager.telnyxClient.listenerCount('telnyx.call.reattached');
+    const incomingListeners = telnyxClient.listenerCount('telnyx.call.incoming');
+    const reattachedListeners = telnyxClient.listenerCount('telnyx.call.reattached');
     console.log(
       'CallStateController: Listeners registered - incoming:',
       incomingListeners,
@@ -283,34 +276,57 @@ export class CallStateController {
     );
 
     // Listen for call state changes from the TelnyxRTC client (multi-call support)
-    this._sessionManager.telnyxClient.on(
-      'telnyx.call.stateChanged',
-      (telnyxCall: TelnyxCall, state: string) => {
-        console.log(
-          'CallStateController: Call state changed from TelnyxRTC:',
-          telnyxCall.callId,
-          state
-        );
-        // Find our wrapper call and update if needed
-        const call = this.findCallByTelnyxCall(telnyxCall);
-        if (call) {
-          console.log(
-            'CallStateController: Found wrapper call, state sync handled by Call subscription'
-          );
-        }
-      }
-    );
+    telnyxClient.on('telnyx.call.stateChanged', this._handleTelnyxCallStateChanged);
 
     // Listen for call removal events from TelnyxRTC (multi-call support)
-    this._sessionManager.telnyxClient.on('telnyx.call.removed', (callId: string) => {
-      console.log('CallStateController: Call removed from TelnyxRTC:', callId);
-      // The call cleanup is already handled by our call state subscription
-      // This event is informational for logging/debugging
-    });
+    telnyxClient.on('telnyx.call.removed', this._handleTelnyxCallRemoved);
 
     console.log('CallStateController: Client listeners set up successfully');
   }
 
+  private _removeClientListeners(): void {
+    if (!this._listenerClient) {
+      return;
+    }
+
+    this._listenerClient.off('telnyx.call.incoming', this._handleTelnyxIncomingCall);
+    this._listenerClient.off('telnyx.call.reattached', this._handleTelnyxReattachedCall);
+    this._listenerClient.off('telnyx.call.stateChanged', this._handleTelnyxCallStateChanged);
+    this._listenerClient.off('telnyx.call.removed', this._handleTelnyxCallRemoved);
+    this._listenerClient = undefined;
+  }
+
+  private _handleTelnyxIncomingCall = (telnyxCall: TelnyxCall, msg: any): void => {
+    console.log('CallStateController: Incoming call received:', telnyxCall.callId);
+    this._handleIncomingCall(telnyxCall, msg, false);
+  };
+
+  private _handleTelnyxReattachedCall = (telnyxCall: TelnyxCall, msg: any): void => {
+    console.log('CallStateController: Reattached call received:', telnyxCall.callId);
+    this._handleIncomingCall(telnyxCall, msg, true);
+  };
+
+  private _handleTelnyxCallStateChanged = (telnyxCall: TelnyxCall, state: string): void => {
+    console.log(
+      'CallStateController: Call state changed from TelnyxRTC:',
+      telnyxCall.callId,
+      state
+    );
+    // Find our wrapper call and update if needed
+    const call = this.findCallByTelnyxCall(telnyxCall);
+    if (call) {
+      console.log(
+        'CallStateController: Found wrapper call, state sync handled by Call subscription'
+      );
+    }
+  };
+
+  private _handleTelnyxCallRemoved = (callId: string): void => {
+    console.log('CallStateController: Call removed from TelnyxRTC:', callId);
+    // The call cleanup is already handled by our call state subscription.
+    // This event is informational for logging/debugging.
+  };
+
   /**
    * Handle incoming call or reattached call
    */

package/src/internal/session/session-manager.ts

@@ -11,6 +11,9 @@ import {
   isTokenConfig,
 } from '../../models/config';
 
+const USE_TRICKLE_ICE_STORAGE_KEY = '@use_trickle_ice';
+const MISSED_CALL_NOTIFICATIONS_STORAGE_KEY = '@enable_missed_call_notifications';
+
 /**
  * Manages the connection lifecycle to the Telnyx platform.
  *
@@ -75,6 +78,10 @@ export class SessionManager {
     return this._telnyxClient;
   }
 
+  get useTrickleIce(): boolean {
+    return Boolean(this._currentConfig?.useTrickleIce);
+  }
+
   /**
    * Connect using credential authentication
    */
@@ -178,39 +185,22 @@ export class SessionManager {
     // Store the push notification payload for when the client is created
     (this as any)._pendingPushPayload = payload;
 
-    // If we have a TelnyxRTC instance but its socket isn't fresh — either not
-    // connected at all, or connected but with no traffic for longer than the
-    // threshold — dispose it so we go through the full _connect() path below
-    // instead of calling processVoIPNotification on a stale client.
-    //
-    // This handles two cases iOS gives us with the same code path:
-    //   1. Terminated-then-cold-launched: a client exists (constructed at
-    //      app boot) but its connection was never opened (idleMs=Infinity).
-    //   2. Suspended-then-thawed: a client exists with `connected=true`,
-    //      but the kernel killed the TLS session during freeze without
-    //      notifying the JS WebSocket wrapper, so no error event fired.
-    //
-    // 30s threshold matches the server's keep-alive ping cadence (~20s),
-    // so a live session always remains fresh.
-    const STALE_THRESHOLD_MS = 30000;
+    // Each push always rebuilds the TelnyxRTC client. The voice_sdk_id is
+    // baked into the WebSocket URL at socket-open time and can't be mutated
+    // mid-flight; reusing a connection from a previous push means the
+    // gateway routes THIS push's INVITE to a different (correctly-stamped)
+    // client and we sit on the wrong socket forever.
     if (this._telnyxClient) {
-      const client = this._telnyxClient as any;
-      const isFresh =
-        typeof client.isFresh === 'function'
-          ? client.isFresh(STALE_THRESHOLD_MS)
-          : !!client.connected;
-      if (!isFresh) {
-        try {
-          await this._telnyxClient.disconnect();
-        } catch (err) {
-          console.warn('SessionManager: disconnect of stale client threw:', err);
-        }
-        this._telnyxClient = undefined;
-        if (this.currentState !== TelnyxConnectionState.DISCONNECTED) {
-          this._connectionState.next(TelnyxConnectionState.DISCONNECTED);
-        }
+      try {
+        await this._telnyxClient.disconnect();
+      } catch (err) {
+        console.warn('SessionManager: disconnect of prior client threw:', err);
       }
     }
+    this._telnyxClient = undefined;
+    if (this.currentState !== TelnyxConnectionState.DISCONNECTED) {
+      this._connectionState.next(TelnyxConnectionState.DISCONNECTED);
+    }
 
     // If we don't have a config yet but we're processing a push notification,
     // attempt to load stored config first (for terminated app startup)
@@ -227,6 +217,12 @@ export class SessionManager {
         const storedPassword = await AsyncStorage.getItem('@telnyx_password');
         const storedCredentialToken = await AsyncStorage.getItem('@credential_token');
         const storedPushToken = await AsyncStorage.getItem('@push_token');
+        const storedUseTrickleIce = await AsyncStorage.getItem(USE_TRICKLE_ICE_STORAGE_KEY);
+        const storedMissedCallNotifications = await AsyncStorage.getItem(
+          MISSED_CALL_NOTIFICATIONS_STORAGE_KEY
+        );
+        const useTrickleIce = storedUseTrickleIce === 'true';
+        const enableMissedCallNotifications = storedMissedCallNotifications === 'true';
 
         // Check if we have credential-based authentication data
         if (storedUsername && storedPassword) {
@@ -234,6 +230,8 @@ export class SessionManager {
           const { createCredentialConfig } = require('../../models/config');
           this._currentConfig = createCredentialConfig(storedUsername, storedPassword, {
             pushNotificationDeviceToken: storedPushToken,
+            useTrickleIce,
+            enableMissedCallNotifications,
           });
         }
         // Check if we have token-based authentication data
@@ -242,6 +240,8 @@ export class SessionManager {
           const { createTokenConfig } = require('../../models/config');
           this._currentConfig = createTokenConfig(storedCredentialToken, {
             pushNotificationDeviceToken: storedPushToken,
+            useTrickleIce,
+            enableMissedCallNotifications,
           });
         }
 
@@ -370,6 +370,8 @@ export class SessionManager {
           logLevel: this._currentConfig.debug ? 'debug' : 'warn',
           debug: this._currentConfig.debug ?? false,
           pushNotificationDeviceToken: this._currentConfig.pushNotificationDeviceToken,
+          enableMissedCallNotifications: this._currentConfig.enableMissedCallNotifications ?? false,
+          useTrickleIce: this._currentConfig.useTrickleIce,
           enableCallReports: this._currentConfig.enableCallReports,
           callReportInterval: this._currentConfig.callReportInterval,
           callReportLogLevel: this._currentConfig.callReportLogLevel,
@@ -388,6 +390,8 @@ export class SessionManager {
           logLevel: this._currentConfig.debug ? 'debug' : 'warn',
           debug: this._currentConfig.debug ?? false,
           pushNotificationDeviceToken: this._currentConfig.pushNotificationDeviceToken,
+          enableMissedCallNotifications: this._currentConfig.enableMissedCallNotifications ?? false,
+          useTrickleIce: this._currentConfig.useTrickleIce,
           enableCallReports: this._currentConfig.enableCallReports,
           callReportInterval: this._currentConfig.callReportInterval,
           callReportLogLevel: this._currentConfig.callReportLogLevel,

package/src/internal/voice-pn-bridge.ts

@@ -38,6 +38,10 @@ export interface VoicePnBridgeInterface {
   clearPendingVoipPush(): Promise<boolean>;
   getPendingVoipAction(): Promise<string | null>;
   clearPendingVoipAction(): Promise<boolean>;
+  setMissedCallNotificationsEnabled(enabled: boolean): Promise<boolean>;
+  getMissedCallNotificationsEnabled(): Promise<boolean>;
+  setSpeakerEnabled(enabled: boolean): Promise<boolean>;
+  isSpeakerEnabled(): Promise<boolean>;
 }
 
 const NativeBridge: VoicePnBridgeInterface = NativeModules.VoicePnBridge;
@@ -244,6 +248,66 @@ export class VoicePnBridge {
     }
   }
 
+  /**
+   * Enable or disable local missed call notifications on iOS.
+   * Missed-call VoIP pushes are still handled through CallKit either way.
+   */
+  static async setMissedCallNotificationsEnabled(enabled: boolean): Promise<boolean> {
+    try {
+      return await NativeBridge.setMissedCallNotificationsEnabled(enabled);
+    } catch (error) {
+      console.error('VoicePnBridge: Error setting missed call notifications:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Returns true by default, matching the sample-app behavior for missed calls.
+   */
+  static async getMissedCallNotificationsEnabled(): Promise<boolean> {
+    try {
+      return await NativeBridge.getMissedCallNotificationsEnabled();
+    } catch (error) {
+      console.error('VoicePnBridge: Error getting missed call notifications setting:', error);
+      return true;
+    }
+  }
+
+  /**
+   * Route call audio through the loudspeaker when enabled, or back to the
+   * platform default voice route when disabled.
+   */
+  static async setSpeakerEnabled(enabled: boolean): Promise<boolean> {
+    try {
+      return await NativeBridge.setSpeakerEnabled(enabled);
+    } catch (error) {
+      console.error('VoicePnBridge: Error setting speaker route:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Returns whether the current audio route is using the loudspeaker.
+   */
+  static async isSpeakerEnabled(): Promise<boolean> {
+    try {
+      return await NativeBridge.isSpeakerEnabled();
+    } catch (error) {
+      console.error('VoicePnBridge: Error getting speaker route:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Toggle between loudspeaker and the platform default voice route.
+   */
+  static async toggleSpeaker(): Promise<boolean> {
+    // This is intentionally read-then-write because route changes can also come from
+    // the OS, Bluetooth, wired accessories, or the active call session.
+    const enabled = await VoicePnBridge.isSpeakerEnabled();
+    return VoicePnBridge.setSpeakerEnabled(!enabled);
+  }
+
   /**
    * Android → React Native: Listen for immediate call action events from notification buttons
    * Use this for active calls where immediate response is needed (e.g., ending ongoing calls)

package/src/models/config.ts

@@ -7,6 +7,10 @@ export interface CredentialConfig {
   sipPassword: string;
   debug?: boolean;
   pushNotificationDeviceToken?: string;
+  /** Enable native missed call push notifications. Default: false */
+  enableMissedCallNotifications?: boolean;
+  /** Enable Trickle ICE. Default: false */
+  useTrickleIce?: boolean;
   /** Enable automatic call quality reporting. Default: true */
   enableCallReports?: boolean;
   /** Stats collection interval in seconds. Default: 5 */
@@ -25,6 +29,10 @@ export interface TokenConfig {
   token: string;
   debug?: boolean;
   pushNotificationDeviceToken?: string;
+  /** Enable native missed call push notifications. Default: false */
+  enableMissedCallNotifications?: boolean;
+  /** Enable Trickle ICE. Default: false */
+  useTrickleIce?: boolean;
   /** Enable automatic call quality reporting. Default: true */
   enableCallReports?: boolean;
   /** Stats collection interval in seconds. Default: 5 */

package/src/telnyx-voip-client.ts

@@ -7,6 +7,9 @@ import { SessionManager } from './internal/session/session-manager';
 import { CallStateController } from './internal/calls/call-state-controller';
 import { VoicePnBridge } from './internal/voice-pn-bridge';
 
+const USE_TRICKLE_ICE_STORAGE_KEY = '@use_trickle_ice';
+const MISSED_CALL_NOTIFICATIONS_STORAGE_KEY = '@enable_missed_call_notifications';
+
 /**
  * Configuration options for TelnyxVoipClient
  */
@@ -16,6 +19,9 @@ export interface TelnyxVoipClientOptions {
 
   /** Enable debug logging */
   debug?: boolean;
+
+  /** Enable Trickle ICE for calls created by this client */
+  useTrickleIce?: boolean;
 }
 
 /**
@@ -67,6 +73,7 @@ export class TelnyxVoipClient {
     this._options = {
       enableAppStateManagement: true,
       debug: false,
+      useTrickleIce: false,
       ...options,
     };
 
@@ -218,10 +225,15 @@ export class TelnyxVoipClient {
       console.log('TelnyxVoipClient: Logging in with credentials for user:', config.sipUser);
     }
 
+    const loginConfig = {
+      ...config,
+      useTrickleIce: config.useTrickleIce ?? this._options.useTrickleIce,
+    };
+
     // Store credentials for future reconnection
-    await this._storeCredentials(config);
+    await this._storeCredentials(loginConfig);
 
-    await this._sessionManager.connectWithCredential(config);
+    await this._sessionManager.connectWithCredential(loginConfig);
   }
 
   /**
@@ -245,10 +257,15 @@ export class TelnyxVoipClient {
       console.log('TelnyxVoipClient: Logging in with token');
     }
 
+    const loginConfig = {
+      ...config,
+      useTrickleIce: config.useTrickleIce ?? this._options.useTrickleIce,
+    };
+
     // Store token for future reconnection
-    await this._storeToken(config);
+    await this._storeToken(loginConfig);
 
-    await this._sessionManager.connectWithToken(config);
+    await this._sessionManager.connectWithToken(loginConfig);
   }
 
   /**
@@ -292,6 +309,13 @@ export class TelnyxVoipClient {
       const storedPassword = await AsyncStorage.getItem('@telnyx_password');
       const storedCredentialToken = await AsyncStorage.getItem('@credential_token');
       const storedPushToken = await AsyncStorage.getItem('@push_token');
+      const storedUseTrickleIce = await AsyncStorage.getItem(USE_TRICKLE_ICE_STORAGE_KEY);
+      const storedMissedCallNotifications = await AsyncStorage.getItem(
+        MISSED_CALL_NOTIFICATIONS_STORAGE_KEY
+      );
+      const useTrickleIce =
+        storedUseTrickleIce === null ? this._options.useTrickleIce : storedUseTrickleIce === 'true';
+      const enableMissedCallNotifications = storedMissedCallNotifications === 'true';
 
       // Check if we have credential-based authentication data
       if (storedUsername && storedPassword) {
@@ -299,6 +323,8 @@ export class TelnyxVoipClient {
         const { createCredentialConfig } = require('./models/config');
         const config = createCredentialConfig(storedUsername, storedPassword, {
           pushNotificationDeviceToken: storedPushToken,
+          useTrickleIce,
+          enableMissedCallNotifications,
         });
 
         if (this._options.debug) {
@@ -318,6 +344,8 @@ export class TelnyxVoipClient {
         const { createTokenConfig } = require('./models/config');
         const config = createTokenConfig(storedCredentialToken, {
           pushNotificationDeviceToken: storedPushToken,
+          useTrickleIce,
+          enableMissedCallNotifications,
         });
 
         if (this._options.debug) {
@@ -401,22 +429,14 @@ export class TelnyxVoipClient {
     }
 
     try {
-      // First, pass the push notification to the session manager for processing
-      // This will set the isCallFromPush flag on the TelnyxRTC client
+      // SessionManager owns the entire push lifecycle: it disposes any prior
+      // client, loads stored credentials if needed, and rebuilds the
+      // TelnyxRTC bound to THIS push's voice_sdk_id. We deliberately do not
+      // fall back to a generic loginFromStoredConfig() here — that would
+      // create a parallel client with no voice_sdk_id awareness, which the
+      // gateway then has to `punt` once the SessionManager-driven session
+      // also registers, dropping the active call.
       await this._sessionManager.handlePushNotification(payload);
-
-      // Connect if not already connected
-      const currentState = this.currentConnectionState;
-      if (currentState !== TelnyxConnectionState.CONNECTED) {
-        // Try to login from stored config - now the push flags should be set
-        const loginSuccess = await this.loginFromStoredConfig();
-        if (!loginSuccess) {
-          console.warn(
-            'TelnyxVoipClient: Could not login from stored config for push notification'
-          );
-          return;
-        }
-      }
     } catch (error) {
       console.error('TelnyxVoipClient: Error handling push notification:', error);
       throw error;
@@ -536,6 +556,14 @@ export class TelnyxVoipClient {
 
       await AsyncStorage.setItem('@telnyx_username', config.sipUser);
       await AsyncStorage.setItem('@telnyx_password', config.sipPassword);
+      await AsyncStorage.setItem(
+        USE_TRICKLE_ICE_STORAGE_KEY,
+        String(config.useTrickleIce ?? false)
+      );
+      await AsyncStorage.setItem(
+        MISSED_CALL_NOTIFICATIONS_STORAGE_KEY,
+        String(config.enableMissedCallNotifications ?? false)
+      );
 
       if (config.pushNotificationDeviceToken) {
         await AsyncStorage.setItem('@push_token', config.pushNotificationDeviceToken);
@@ -563,6 +591,14 @@ export class TelnyxVoipClient {
       const AsyncStorage = require('@react-native-async-storage/async-storage').default;
 
       await AsyncStorage.setItem('@credential_token', config.token);
+      await AsyncStorage.setItem(
+        USE_TRICKLE_ICE_STORAGE_KEY,
+        String(config.useTrickleIce ?? false)
+      );
+      await AsyncStorage.setItem(
+        MISSED_CALL_NOTIFICATIONS_STORAGE_KEY,
+        String(config.enableMissedCallNotifications ?? false)
+      );
 
       if (config.pushNotificationDeviceToken) {
         await AsyncStorage.setItem('@push_token', config.pushNotificationDeviceToken);

package/src/types/telnyx-sdk.d.ts

@@ -14,6 +14,14 @@ declare module '@telnyx/react-native-voice-sdk' {
     destinationNumber?: string;
     audio?: boolean;
     video?: boolean;
+    peerConnectionOptions?: {
+      prefetchIceCandidates?: boolean;
+      useTrickleIce?: boolean;
+      iceServers?: any[];
+      iceTransportPolicy?: string;
+      bundlePolicy?: string;
+      rtcpMuxPolicy?: string;
+    };
   }
 
   export interface ClientOptions {
@@ -26,6 +34,8 @@ declare module '@telnyx/react-native-voice-sdk' {
     debug?: boolean;
     logLevel?: string;
     pushNotificationDeviceToken?: string;
+    enableMissedCallNotifications?: boolean;
+    useTrickleIce?: boolean;
     enableCallReports?: boolean;
     callReportInterval?: number;
     callReportLogLevel?: string;