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

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

@@ -12,6 +12,7 @@ import {
 } 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';
 
 /**
@@ -28,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;
 
@@ -86,24 +91,20 @@ export class SessionManager {
    * 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();
   }
 
   /**
@@ -121,6 +122,7 @@ export class SessionManager {
       return;
     }
 
+    this._connectionGeneration += 1;
     this._currentConfig = undefined;
     this._connectionState.next(TelnyxConnectionState.DISCONNECTED);
 
@@ -133,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:');
     }
   }
 
@@ -147,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 {
@@ -159,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;
     }
 
@@ -173,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;
     }
 
@@ -185,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;
     }
-    this._telnyxClient = undefined;
+
+    // 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:'
+      );
+    }
+
+    if (this._isTeardownActive()) {
+      return;
+    }
+
     if (this.currentState !== TelnyxConnectionState.DISCONNECTED) {
       this._connectionState.next(TelnyxConnectionState.DISCONNECTED);
     }
@@ -218,12 +239,18 @@ export class SessionManager {
         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) {
           console.log('SessionManager: RELEASE DEBUG - Found stored credentials, creating config');
@@ -231,6 +258,7 @@ export class SessionManager {
           this._currentConfig = createCredentialConfig(storedUsername, storedPassword, {
             pushNotificationDeviceToken: storedPushToken,
             useTrickleIce,
+            pushWhenActive,
             enableMissedCallNotifications,
           });
         }
@@ -241,6 +269,7 @@ export class SessionManager {
           this._currentConfig = createTokenConfig(storedCredentialToken, {
             pushNotificationDeviceToken: storedPushToken,
             useTrickleIce,
+            pushWhenActive,
             enableMissedCallNotifications,
           });
         }
@@ -257,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(
@@ -306,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
@@ -331,84 +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,
-          enableMissedCallNotifications: this._currentConfig.enableMissedCallNotifications ?? false,
-          useTrickleIce: this._currentConfig.useTrickleIce,
-          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,
-          enableMissedCallNotifications: this._currentConfig.enableMissedCallNotifications ?? false,
-          useTrickleIce: this._currentConfig.useTrickleIce,
-          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
@@ -441,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
@@ -457,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;
     }
@@ -475,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);
 
@@ -500,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);
     });
@@ -565,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>;
@@ -183,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
    */

package/src/models/call.ts

@@ -285,6 +285,17 @@ export class Call {
     }
 
     try {
+      if (Platform.OS === 'ios') {
+        const { callKitCoordinator } = await import('../callkit/callkit-coordinator');
+        if (callKitCoordinator.isAvailable()) {
+          const success = await callKitCoordinator.setHeldFromUI(this._telnyxCall, true);
+          if (!success) {
+            throw new Error('CallKit failed to hold call');
+          }
+          return;
+        }
+      }
+
       await this._telnyxCall.hold();
     } catch (error) {
       console.error('Failed to hold call:', error);
@@ -301,6 +312,17 @@ export class Call {
     }
 
     try {
+      if (Platform.OS === 'ios') {
+        const { callKitCoordinator } = await import('../callkit/callkit-coordinator');
+        if (callKitCoordinator.isAvailable()) {
+          const success = await callKitCoordinator.setHeldFromUI(this._telnyxCall, false);
+          if (!success) {
+            throw new Error('CallKit failed to resume call');
+          }
+          return;
+        }
+      }
+
       await this._telnyxCall.unhold();
     } catch (error) {
       console.error('Failed to resume call:', error);
@@ -406,6 +428,18 @@ export class Call {
       const telnyxState = this._mapToTelnyxCallState(state);
       this._callState.next(telnyxState);
 
+      // Keep the dedicated held observable derived from call state. Updating
+      // this only after the low-level SDK emits its successful transition
+      // preserves the previous value when hold/unhold signaling fails.
+      if (telnyxState === TelnyxCallState.HELD) {
+        this._isHeld.next(true);
+      } else if (
+        telnyxState === TelnyxCallState.ACTIVE ||
+        CallStateHelpers.isTerminated(telnyxState)
+      ) {
+        this._isHeld.next(false);
+      }
+
       // Start duration timer when call becomes active
       if (telnyxState === TelnyxCallState.ACTIVE && !this._startTime) {
         this._startDurationTimer();