@telnyx/react-voice-commons-sdk 0.4.3 → 1.1.0

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

@@ -11,6 +11,10 @@ import {
   isTokenConfig,
 } from '../../models/config';
 
+const USE_TRICKLE_ICE_STORAGE_KEY = '@use_trickle_ice';
+const PUSH_WHEN_ACTIVE_STORAGE_KEY = '@push_when_active';
+const MISSED_CALL_NOTIFICATIONS_STORAGE_KEY = '@enable_missed_call_notifications';
+
 /**
  * Manages the connection lifecycle to the Telnyx platform.
  *
@@ -25,6 +29,10 @@ export class SessionManager {
   private _currentConfig?: Config;
   private _sessionId: string;
   private _disposed = false;
+  private _disposing = false;
+  private _connectionGeneration = 0;
+  private _disposePromise?: Promise<void>;
+  private _connectPromise?: Promise<void>;
   private _onClientReady?: () => void;
   private _onDisconnect?: () => void;
 
@@ -75,28 +83,28 @@ export class SessionManager {
     return this._telnyxClient;
   }
 
+  get useTrickleIce(): boolean {
+    return Boolean(this._currentConfig?.useTrickleIce);
+  }
+
   /**
    * Connect using credential authentication
    */
   async connectWithCredential(config: CredentialConfig): Promise<void> {
-    if (this._disposed) {
-      throw new Error('SessionManager has been disposed');
-    }
-
+    this._assertCanStartConnection();
     this._currentConfig = config;
     await this._connect();
+    this._assertCanStartConnection();
   }
 
   /**
    * Connect using token authentication
    */
   async connectWithToken(config: TokenConfig): Promise<void> {
-    if (this._disposed) {
-      throw new Error('SessionManager has been disposed');
-    }
-
+    this._assertCanStartConnection();
     this._currentConfig = config;
     await this._connect();
+    this._assertCanStartConnection();
   }
 
   /**
@@ -114,6 +122,7 @@ export class SessionManager {
       return;
     }
 
+    this._connectionGeneration += 1;
     this._currentConfig = undefined;
     this._connectionState.next(TelnyxConnectionState.DISCONNECTED);
 
@@ -126,11 +135,7 @@ export class SessionManager {
     }
 
     if (this._telnyxClient) {
-      try {
-        await this._telnyxClient.disconnect();
-      } catch (error) {
-        console.error('Error during disconnect:', error);
-      }
+      await this._disconnectAndForgetClient(this._telnyxClient, 'Error during disconnect:');
     }
   }
 
@@ -140,7 +145,11 @@ export class SessionManager {
    * which sends a 'telnyx_rtc.disable_push_notification' message via the socket.
    */
   disablePushNotifications(): void {
-    if (this._telnyxClient && this.currentState === TelnyxConnectionState.CONNECTED) {
+    if (
+      !this._isTeardownActive() &&
+      this._telnyxClient &&
+      this.currentState === TelnyxConnectionState.CONNECTED
+    ) {
       console.log('SessionManager: Disabling push notifications for session:', this._sessionId);
       this._telnyxClient.disablePushNotification();
     } else {
@@ -152,7 +161,7 @@ export class SessionManager {
    * Handle push notification with stored config
    */
   handlePushNotificationWithConfig(pushMetaData: any, config: Config): void {
-    if (this._disposed) {
+    if (this._isTeardownActive()) {
       return;
     }
 
@@ -166,7 +175,7 @@ export class SessionManager {
    * Handle push notification (async version)
    */
   async handlePushNotification(payload: Record<string, any>): Promise<void> {
-    if (this._disposed) {
+    if (this._isTeardownActive()) {
       return;
     }
 
@@ -178,19 +187,38 @@ export class SessionManager {
     // Store the push notification payload for when the client is created
     (this as any)._pendingPushPayload = payload;
 
-    // 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) {
-      try {
-        await this._telnyxClient.disconnect();
-      } catch (err) {
-        console.warn('SessionManager: disconnect of prior client threw:', err);
+    // A second-call push must stay on the client that owns the active/held
+    // call. Tearing it down destroys the first signaling session and clears
+    // the call collection before CallKit can complete Hold & Accept.
+    if (this._telnyxClient && this._hasActiveOrHeldCall(this._telnyxClient)) {
+      const actualPayload = this._extractPushPayload(payload);
+      const processVoIPNotification = (this._telnyxClient as any).processVoIPNotification;
+
+      if (typeof processVoIPNotification !== 'function') {
+        throw new Error('TelnyxRTC client cannot process an active-call VoIP notification');
       }
+
+      console.log(
+        'SessionManager: Preserving active client while processing second-call push notification'
+      );
+      processVoIPNotification.call(this._telnyxClient, actualPayload);
+      (this as any)._pendingPushPayload = null;
+      return;
+    }
+
+    // The cold/no-active-call path still rebuilds the client so the socket is
+    // stamped with the push voice_sdk_id before connecting.
+    if (this._telnyxClient) {
+      await this._disconnectAndForgetClient(
+        this._telnyxClient,
+        'SessionManager: disconnect of prior client threw:'
+      );
     }
-    this._telnyxClient = undefined;
+
+    if (this._isTeardownActive()) {
+      return;
+    }
+
     if (this.currentState !== TelnyxConnectionState.DISCONNECTED) {
       this._connectionState.next(TelnyxConnectionState.DISCONNECTED);
     }
@@ -210,6 +238,18 @@ 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 storedPushWhenActive = await AsyncStorage.getItem(PUSH_WHEN_ACTIVE_STORAGE_KEY);
+        const storedMissedCallNotifications = await AsyncStorage.getItem(
+          MISSED_CALL_NOTIFICATIONS_STORAGE_KEY
+        );
+        const useTrickleIce = storedUseTrickleIce === 'true';
+        const pushWhenActive = storedPushWhenActive === 'true';
+        const enableMissedCallNotifications = storedMissedCallNotifications === 'true';
+
+        if (this._isTeardownActive()) {
+          return;
+        }
 
         // Check if we have credential-based authentication data
         if (storedUsername && storedPassword) {
@@ -217,6 +257,9 @@ export class SessionManager {
           const { createCredentialConfig } = require('../../models/config');
           this._currentConfig = createCredentialConfig(storedUsername, storedPassword, {
             pushNotificationDeviceToken: storedPushToken,
+            useTrickleIce,
+            pushWhenActive,
+            enableMissedCallNotifications,
           });
         }
         // Check if we have token-based authentication data
@@ -225,6 +268,9 @@ export class SessionManager {
           const { createTokenConfig } = require('../../models/config');
           this._currentConfig = createTokenConfig(storedCredentialToken, {
             pushNotificationDeviceToken: storedPushToken,
+            useTrickleIce,
+            pushWhenActive,
+            enableMissedCallNotifications,
           });
         }
 
@@ -240,6 +286,10 @@ export class SessionManager {
       }
     }
 
+    if (this._isTeardownActive()) {
+      return;
+    }
+
     // If we already have a client, process the push notification immediately
     if (this._telnyxClient) {
       console.log(
@@ -289,10 +339,16 @@ export class SessionManager {
         );
         try {
           await this._connect();
+          if (this._isTeardownActive()) {
+            return;
+          }
           console.log(
             'SessionManager: RELEASE DEBUG - Successfully connected after push notification trigger'
           );
         } catch (error) {
+          if (this._isTeardownActive()) {
+            return;
+          }
           console.error(
             'SessionManager: Failed to connect after push notification trigger:',
             error
@@ -314,80 +370,160 @@ export class SessionManager {
     console.log('SessionManager: RELEASE DEBUG - Push notification handling complete');
   }
 
+  private _hasActiveOrHeldCall(client: TelnyxSDK.TelnyxRTC): boolean {
+    const calls =
+      typeof (client as any).getActiveCalls === 'function'
+        ? (client as any).getActiveCalls()
+        : Array.from(((client as any).calls as Map<string, any> | undefined)?.values?.() || []);
+
+    return calls.some((call: any) => call?.state === 'active' || call?.state === 'held');
+  }
+
   /**
    * Dispose of the session manager and clean up resources
    */
-  dispose(): void {
+  async dispose(): Promise<void> {
     if (this._disposed) {
       return;
     }
 
-    this._disposed = true;
-    this.disconnect();
-    this._connectionState.complete();
+    if (!this._disposePromise) {
+      this._disposePromise = this._dispose();
+    }
+
+    await this._disposePromise;
   }
 
   /**
    * Internal method to establish connection with or without push notification handling
    */
   private async _connect(): Promise<void> {
-    if (!this._currentConfig) {
+    const previousConnect = this._connectPromise;
+    if (previousConnect) {
+      try {
+        await previousConnect;
+      } catch (error) {
+        if (this._isTeardownActive()) {
+          throw error;
+        }
+      }
+    }
+
+    this._assertCanStartConnection();
+
+    const config = this._currentConfig;
+    if (!config) {
       throw new Error('No configuration provided');
     }
 
+    const connectionGeneration = (this._connectionGeneration += 1);
+    const connectPromise = this._runConnect(config, connectionGeneration);
+    this._connectPromise = connectPromise;
+
+    try {
+      await connectPromise;
+    } finally {
+      if (this._connectPromise === connectPromise) {
+        this._connectPromise = undefined;
+      }
+    }
+  }
+
+  private async _dispose(): Promise<void> {
+    this._disposing = true;
+    this._connectionGeneration += 1;
+
+    const inFlightConnect = this._connectPromise;
+
+    await this.disconnect();
+
+    if (inFlightConnect) {
+      try {
+        await inFlightConnect;
+      } catch {
+        // A connect canceled by disposal is expected; the cleanup path runs in _runConnect.
+      }
+    }
+
+    const client = this._telnyxClient;
+    if (client) {
+      await this._disconnectAndForgetClient(client, 'Error during dispose disconnect:');
+    }
+
+    this._currentConfig = undefined;
+    (this as any)._pendingPushPayload = null;
+    this._disposed = true;
+    this._disposing = false;
+    this._connectionState.complete();
+  }
+
+  private async _runConnect(config: Config, connectionGeneration: number): Promise<void> {
+    this._throwIfConnectCanceled(connectionGeneration);
     this._connectionState.next(TelnyxConnectionState.CONNECTING);
 
+    let client: TelnyxSDK.TelnyxRTC | undefined;
+    let canceledConnectCleanupCompleted = false;
+
     try {
       // Clean up existing client
       if (this._telnyxClient) {
-        await this._telnyxClient.disconnect();
+        await this._disconnectClient(this._telnyxClient, 'Error during disconnect:');
       }
 
+      this._throwIfConnectCanceled(connectionGeneration);
+
       // Create new client instance with authentication options
       let clientOptions: TelnyxSDK.ClientOptions;
 
-      if (isCredentialConfig(this._currentConfig)) {
+      if (isCredentialConfig(config)) {
         clientOptions = {
-          login: this._currentConfig.sipUser,
-          password: this._currentConfig.sipPassword,
-          logLevel: this._currentConfig.debug ? 'debug' : 'warn',
-          debug: this._currentConfig.debug ?? false,
-          pushNotificationDeviceToken: this._currentConfig.pushNotificationDeviceToken,
-          enableCallReports: this._currentConfig.enableCallReports,
-          callReportInterval: this._currentConfig.callReportInterval,
-          callReportLogLevel: this._currentConfig.callReportLogLevel,
-          callReportMaxLogEntries: this._currentConfig.callReportMaxLogEntries,
+          login: config.sipUser,
+          password: config.sipPassword,
+          logLevel: config.debug ? 'debug' : 'warn',
+          debug: config.debug ?? false,
+          pushNotificationDeviceToken: config.pushNotificationDeviceToken,
+          pushWhenActive: config.pushWhenActive,
+          enableMissedCallNotifications: config.enableMissedCallNotifications ?? false,
+          useTrickleIce: config.useTrickleIce,
+          enableCallReports: config.enableCallReports,
+          callReportInterval: config.callReportInterval,
+          callReportLogLevel: config.callReportLogLevel,
+          callReportMaxLogEntries: config.callReportMaxLogEntries,
           sdkVersion: pkg.version,
         };
         console.log(
           '🔧 SessionManager: Creating TelnyxRTC with credential config, logLevel:',
           clientOptions.logLevel,
           'pushToken:',
-          !!this._currentConfig.pushNotificationDeviceToken
+          !!config.pushNotificationDeviceToken
         );
-      } else if (isTokenConfig(this._currentConfig)) {
+      } else if (isTokenConfig(config)) {
         clientOptions = {
-          login_token: this._currentConfig.token,
-          logLevel: this._currentConfig.debug ? 'debug' : 'warn',
-          debug: this._currentConfig.debug ?? false,
-          pushNotificationDeviceToken: this._currentConfig.pushNotificationDeviceToken,
-          enableCallReports: this._currentConfig.enableCallReports,
-          callReportInterval: this._currentConfig.callReportInterval,
-          callReportLogLevel: this._currentConfig.callReportLogLevel,
-          callReportMaxLogEntries: this._currentConfig.callReportMaxLogEntries,
+          login_token: config.token,
+          logLevel: config.debug ? 'debug' : 'warn',
+          debug: config.debug ?? false,
+          pushNotificationDeviceToken: config.pushNotificationDeviceToken,
+          pushWhenActive: config.pushWhenActive,
+          enableMissedCallNotifications: config.enableMissedCallNotifications ?? false,
+          useTrickleIce: config.useTrickleIce,
+          enableCallReports: config.enableCallReports,
+          callReportInterval: config.callReportInterval,
+          callReportLogLevel: config.callReportLogLevel,
+          callReportMaxLogEntries: config.callReportMaxLogEntries,
           sdkVersion: pkg.version,
         };
         console.log(
           '🔧 SessionManager: Creating TelnyxRTC with token config, logLevel:',
           clientOptions.logLevel,
           'pushToken:',
-          !!this._currentConfig.pushNotificationDeviceToken
+          !!config.pushNotificationDeviceToken
         );
       } else {
         throw new Error('Invalid configuration type');
       }
 
-      this._telnyxClient = new TelnyxSDK.TelnyxRTC(clientOptions);
+      client = new TelnyxSDK.TelnyxRTC(clientOptions);
+      this._telnyxClient = client;
 
       // CRITICAL: Process any pending push notification payload BEFORE connecting
       // This ensures voice_sdk_id and other payload variables are set before connect() is called
@@ -420,7 +556,7 @@ export class SessionManager {
         (this as any)._pendingPushPayload = null;
       }
 
-      this._setupClientListeners();
+      this._setupClientListeners(client);
 
       // Set up CallStateController listeners immediately after client creation
       // This ensures they're ready before any incoming call events are emitted
@@ -436,16 +572,38 @@ export class SessionManager {
         console.log('🔧 SessionManager: No _onClientReady callback found');
       }
 
+      this._throwIfConnectCanceled(connectionGeneration);
+
       // Connect to the platform AFTER processing push notification
       console.log(
         'SessionManager: RELEASE DEBUG - About to call connect() after processing push notification'
       );
-      await this._telnyxClient.connect();
+      await client.connect();
+
+      if (this._isConnectCanceled(connectionGeneration)) {
+        await this._disconnectAndForgetClient(client, 'Error during dispose disconnect:');
+        canceledConnectCleanupCompleted = true;
+        throw this._createConnectCanceledError();
+      }
 
       // Notify that client is ready for event listeners
       console.log('🔧 SessionManager: Client connected successfully');
     } catch (error) {
+      if (this._isConnectCanceled(connectionGeneration)) {
+        if (client && !canceledConnectCleanupCompleted) {
+          await this._disconnectAndForgetClient(client, 'Error during dispose disconnect:');
+        }
+        throw this._createConnectCanceledError();
+      }
+
       console.error('Connection failed:', error);
+      if (client) {
+        try {
+          await this._disconnectAndForgetClient(client, 'Error during failed connect cleanup:');
+        } catch (cleanupError) {
+          console.error('Error during failed connect cleanup:', cleanupError);
+        }
+      }
       this._connectionState.next(TelnyxConnectionState.ERROR);
       throw error;
     }
@@ -454,12 +612,16 @@ export class SessionManager {
   /**
    * Set up event listeners for the Telnyx client
    */
-  private _setupClientListeners(): void {
-    if (!this._telnyxClient) {
+  private _setupClientListeners(client: TelnyxSDK.TelnyxRTC): void {
+    if (!client) {
       return;
     }
 
-    this._telnyxClient.on('telnyx.client.ready', () => {
+    client.on('telnyx.client.ready', () => {
+      if (this._isTeardownActive() || this._telnyxClient !== client) {
+        return;
+      }
+
       console.log('Telnyx client ready');
       this._connectionState.next(TelnyxConnectionState.CONNECTED);
 
@@ -479,7 +641,11 @@ export class SessionManager {
       }
     });
 
-    this._telnyxClient.on('telnyx.client.error', (error: Error) => {
+    client.on('telnyx.client.error', (error: Error) => {
+      if (this._isTeardownActive() || this._telnyxClient !== client) {
+        return;
+      }
+
       console.error('Telnyx client error:', error);
       this._connectionState.next(TelnyxConnectionState.ERROR);
     });
@@ -544,4 +710,54 @@ export class SessionManager {
   private _generateSessionId(): string {
     return `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
   }
+
+  private _assertCanStartConnection(): void {
+    if (this._isTeardownActive()) {
+      throw new Error('SessionManager has been disposed');
+    }
+  }
+
+  private _isTeardownActive(): boolean {
+    return this._disposed || this._disposing;
+  }
+
+  private _isConnectCanceled(connectionGeneration: number): boolean {
+    return this._isTeardownActive() || this._connectionGeneration !== connectionGeneration;
+  }
+
+  private _throwIfConnectCanceled(connectionGeneration: number): void {
+    if (this._isConnectCanceled(connectionGeneration)) {
+      throw this._createConnectCanceledError();
+    }
+  }
+
+  private _createConnectCanceledError(): Error {
+    return new Error(
+      this._isTeardownActive()
+        ? 'SessionManager has been disposed'
+        : 'SessionManager connection has been canceled'
+    );
+  }
+
+  private async _disconnectClient(
+    client: TelnyxSDK.TelnyxRTC,
+    errorMessage: string
+  ): Promise<void> {
+    try {
+      await client.disconnect();
+    } catch (error) {
+      console.error(errorMessage, error);
+      throw error;
+    }
+  }
+
+  private async _disconnectAndForgetClient(
+    client: TelnyxSDK.TelnyxRTC,
+    errorMessage: string
+  ): Promise<void> {
+    await this._disconnectClient(client, errorMessage);
+    if (this._telnyxClient === client) {
+      this._telnyxClient = undefined;
+    }
+  }
 }

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

@@ -31,6 +31,11 @@ export interface VoicePnBridgeInterface {
   ): Promise<boolean>;
   hideOngoingCallNotification(): Promise<boolean>;
   hideIncomingCallNotification(): Promise<boolean>;
+  setIncomingCallRingtone(resourceName: string | null): Promise<boolean>;
+
+  // CallKit answer persistence (iOS only)
+  getPendingCallKitAnswer(): Promise<string | null>;
+  clearPendingCallKitAnswer(): Promise<boolean>;
 
   // Additional UserDefaults methods
   getVoipToken(): Promise<string | null>;
@@ -38,6 +43,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;
@@ -179,6 +188,48 @@ export class VoicePnBridge {
     }
   }
 
+  /**
+   * Configure Android's incoming-call ringtone using an app resource in `res/raw`.
+   * Pass no value to use the device's default phone ringtone.
+   */
+  static async setIncomingCallRingtone(resourceName?: string): Promise<boolean> {
+    if (Platform.OS !== 'android') return true;
+    try {
+      return await NativeBridge.setIncomingCallRingtone(resourceName?.trim() || null);
+    } catch (error) {
+      console.error('VoicePnBridge: Error setting incoming call ringtone:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Get pending CallKit answer UUID from native storage (iOS only).
+   * When the user answers a CallKit call before JS listeners are ready,
+   * the native side persists the answer UUID in UserDefaults so JS can detect it.
+   */
+  static async getPendingCallKitAnswer(): Promise<string | null> {
+    if (Platform.OS !== 'ios') return null;
+    try {
+      return await NativeBridge.getPendingCallKitAnswer();
+    } catch (error) {
+      console.error('VoicePnBridge: Error getting pending CallKit answer:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Clear pending CallKit answer from native storage (iOS only)
+   */
+  static async clearPendingCallKitAnswer(): Promise<boolean> {
+    if (Platform.OS !== 'ios') return true;
+    try {
+      return await NativeBridge.clearPendingCallKitAnswer();
+    } catch (error) {
+      console.error('VoicePnBridge: Error clearing pending CallKit answer:', error);
+      return false;
+    }
+  }
+
   /**
    * Get VoIP token from native storage
    */
@@ -244,6 +295,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)