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

package/lib/models/call.js

@@ -314,6 +314,18 @@ class Call {
       throw new Error(`Cannot hold call in state: ${this.currentState}`);
     }
     try {
+      if (react_native_1.Platform.OS === 'ios') {
+        const { callKitCoordinator } = await Promise.resolve().then(() =>
+          __importStar(require('../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);
@@ -328,6 +340,18 @@ class Call {
       throw new Error(`Cannot resume call in state: ${this.currentState}`);
     }
     try {
+      if (react_native_1.Platform.OS === 'ios') {
+        const { callKitCoordinator } = await Promise.resolve().then(() =>
+          __importStar(require('../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);
@@ -422,6 +446,17 @@ class Call {
     this._telnyxCall.on('telnyx.call.state', (call, state) => {
       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 === call_state_1.TelnyxCallState.HELD) {
+        this._isHeld.next(true);
+      } else if (
+        telnyxState === call_state_1.TelnyxCallState.ACTIVE ||
+        call_state_1.CallStateHelpers.isTerminated(telnyxState)
+      ) {
+        this._isHeld.next(false);
+      }
       // Start duration timer when call becomes active
       if (telnyxState === call_state_1.TelnyxCallState.ACTIVE && !this._startTime) {
         this._startDurationTimer();

package/lib/models/config.d.ts

@@ -7,6 +7,14 @@ export interface CredentialConfig {
   sipPassword: string;
   debug?: boolean;
   pushNotificationDeviceToken?: string;
+  /** Receive PushKit calls while the WebSocket session is active. Default: false */
+  pushWhenActive?: boolean;
+  /** Enable native missed call push notifications. Default: false */
+  enableMissedCallNotifications?: boolean;
+  /** Android only: name of a bundled `res/raw` ringtone (without its file extension). Falls back to the device ringtone. */
+  incomingCallRingtone?: string;
+  /** Enable Trickle ICE. Default: false */
+  useTrickleIce?: boolean;
   /** Enable automatic call quality reporting. Default: true */
   enableCallReports?: boolean;
   /** Stats collection interval in seconds. Default: 5 */
@@ -24,6 +32,14 @@ export interface TokenConfig {
   token: string;
   debug?: boolean;
   pushNotificationDeviceToken?: string;
+  /** Receive PushKit calls while the WebSocket session is active. Default: false */
+  pushWhenActive?: boolean;
+  /** Enable native missed call push notifications. Default: false */
+  enableMissedCallNotifications?: boolean;
+  /** Android only: name of a bundled `res/raw` ringtone (without its file extension). Falls back to the device ringtone. */
+  incomingCallRingtone?: string;
+  /** Enable Trickle ICE. Default: false */
+  useTrickleIce?: boolean;
   /** Enable automatic call quality reporting. Default: true */
   enableCallReports?: boolean;
   /** Stats collection interval in seconds. Default: 5 */
@@ -65,6 +81,7 @@ export declare function validateConfig(config: Config): string[];
  * @param options - Optional configuration settings
  * @param options.debug - Enable debug logging (sets SDK logLevel to 'debug')
  * @param options.pushNotificationDeviceToken - Device token for push notifications
+ * @param options.pushWhenActive - Keep active PushKit devices eligible for incoming calls
  * @returns Complete credential configuration object
  */
 export declare function createCredentialConfig(
@@ -79,6 +96,7 @@ export declare function createCredentialConfig(
  * @param options - Optional configuration settings
  * @param options.debug - Enable debug logging (sets SDK logLevel to 'debug')
  * @param options.pushNotificationDeviceToken - Device token for push notifications
+ * @param options.pushWhenActive - Keep active PushKit devices eligible for incoming calls
  * @returns Complete token configuration object
  */
 export declare function createTokenConfig(

package/lib/models/config.js

@@ -62,6 +62,7 @@ function validateConfig(config) {
  * @param options - Optional configuration settings
  * @param options.debug - Enable debug logging (sets SDK logLevel to 'debug')
  * @param options.pushNotificationDeviceToken - Device token for push notifications
+ * @param options.pushWhenActive - Keep active PushKit devices eligible for incoming calls
  * @returns Complete credential configuration object
  */
 function createCredentialConfig(sipUser, sipPassword, options) {
@@ -79,6 +80,7 @@ function createCredentialConfig(sipUser, sipPassword, options) {
  * @param options - Optional configuration settings
  * @param options.debug - Enable debug logging (sets SDK logLevel to 'debug')
  * @param options.pushNotificationDeviceToken - Device token for push notifications
+ * @param options.pushWhenActive - Keep active PushKit devices eligible for incoming calls
  * @returns Complete token configuration object
  */
 function createTokenConfig(sipToken, options) {

package/lib/telnyx-voice-app.js

@@ -6,7 +6,30 @@ const react_1 = require('react');
 const react_native_1 = require('react-native');
 const telnyx_voip_client_1 = require('./telnyx-voip-client');
 const connection_state_1 = require('./models/connection-state');
+const call_state_1 = require('./models/call-state');
 const TelnyxVoiceContext_1 = require('./context/TelnyxVoiceContext');
+let sharedBackgroundClient = null;
+let sharedBackgroundDisposePromise = null;
+const disposeSharedBackgroundClient = async (log, expectedClient) => {
+  if (sharedBackgroundDisposePromise) {
+    await sharedBackgroundDisposePromise;
+  }
+  const backgroundClient = expectedClient ?? sharedBackgroundClient;
+  if (!backgroundClient || (expectedClient && sharedBackgroundClient !== expectedClient)) {
+    return;
+  }
+  sharedBackgroundClient = null;
+  log('Disposing background client instance');
+  sharedBackgroundDisposePromise = backgroundClient
+    .dispose()
+    .catch((e) => {
+      log('Error disposing background client instance:', e);
+    })
+    .finally(() => {
+      sharedBackgroundDisposePromise = null;
+    });
+  await sharedBackgroundDisposePromise;
+};
 /**
  * A comprehensive wrapper component that handles all Telnyx SDK lifecycle management.
  *
@@ -39,11 +62,17 @@ const TelnyxVoiceAppComponent = ({
   const [currentConnectionState, setCurrentConnectionState] = (0, react_1.useState)(
     voipClient.currentConnectionState
   );
+  // Refs that mirror mutable state for use inside long-lived effects and
+  // callbacks. Reading these flags through refs (instead of the state
+  // variables) keeps the setup effect's dependency array stable so
+  // connection/call subscriptions are not torn down and recreated every
+  // time the flags change — fixing the subscription gap described in
+  // VSDK-344.
+  const isHandlingForegroundCallRef = (0, react_1.useRef)(false);
+  const processingPushOnLaunchRef = (0, react_1.useRef)(false);
   // Refs for tracking state
   const appStateRef = (0, react_1.useRef)(react_native_1.AppState.currentState);
   const backgroundDetectorIgnore = (0, react_1.useRef)(false);
-  // Static background client instance for singleton pattern
-  const backgroundClientRef = (0, react_1.useRef)(null);
   const log = (0, react_1.useCallback)(
     (message, ...args) => {
       if (debug) {
@@ -59,7 +88,7 @@ const TelnyxVoiceAppComponent = ({
       appStateRef.current = nextAppState;
       log(`App state changed from ${previousAppState} to ${nextAppState}`);
       log(`Background detector ignore flag: ${backgroundDetectorIgnore.current}`);
-      log(`Handling foreground call: ${isHandlingForegroundCall}`);
+      log(`Handling foreground call: ${isHandlingForegroundCallRef.current}`);
       // Call optional user callback first
       onAppStateChanged?.(nextAppState);
       // Only handle background disconnection when actually transitioning from active to background
@@ -87,12 +116,12 @@ const TelnyxVoiceAppComponent = ({
         await handleAppResumed();
       }
     },
-    [enableAutoReconnect, onAppStateChanged, isHandlingForegroundCall, log]
+    [enableAutoReconnect, onAppStateChanged, log]
   );
   // Handle app going to background - disconnect like the old implementation
   const handleAppBackgrounded = (0, react_1.useCallback)(async () => {
     // Check if we should ignore background detection (e.g., during active calls)
-    if (backgroundDetectorIgnore.current || isHandlingForegroundCall) {
+    if (backgroundDetectorIgnore.current || isHandlingForegroundCallRef.current) {
       log(
         'Background detector ignore flag set or handling foreground call - skipping disconnection'
       );
@@ -140,7 +169,7 @@ const TelnyxVoiceAppComponent = ({
     } catch (e) {
       log('Error disconnecting on background:', e);
     }
-  }, [voipClient, isHandlingForegroundCall, log]);
+  }, [voipClient, log]);
   // Handle app resuming from background
   const handleAppResumed = (0, react_1.useCallback)(async () => {
     log('App resumed - checking reconnection needs');
@@ -148,7 +177,7 @@ const TelnyxVoiceAppComponent = ({
     // This handles the case where the user accepted a call while the app was backgrounded
     await checkForInitialPushNotification(true); // Pass true for fromAppResume
     // If we're ignoring (e.g., from push call) or handling foreground call, don't auto-reconnect
-    if (backgroundDetectorIgnore.current || isHandlingForegroundCall) {
+    if (backgroundDetectorIgnore.current || isHandlingForegroundCallRef.current) {
       log(
         'Background detector ignore flag set or handling foreground call - skipping reconnection'
       );
@@ -176,7 +205,7 @@ const TelnyxVoiceAppComponent = ({
     if (currentState !== connection_state_1.TelnyxConnectionState.CONNECTED) {
       await attemptAutoReconnection();
     }
-  }, [voipClient, isHandlingForegroundCall, log]);
+  }, [voipClient, log]);
   // Attempt to reconnect using stored credentials
   const attemptAutoReconnection = (0, react_1.useCallback)(async () => {
     try {
@@ -296,12 +325,13 @@ const TelnyxVoiceAppComponent = ({
   const checkForInitialPushNotification = (0, react_1.useCallback)(
     async (fromAppResume = false) => {
       log(`checkForInitialPushNotification called${fromAppResume ? ' (from app resume)' : ''}`);
-      if (processingPushOnLaunch && !fromAppResume) {
+      if (processingPushOnLaunchRef.current && !fromAppResume) {
         log('Already processing push, returning early');
         return;
       }
       if (!fromAppResume) {
         setProcessingPushOnLaunch(true);
+        processingPushOnLaunchRef.current = true;
       }
       onPushNotificationProcessingStarted?.();
       try {
@@ -324,11 +354,20 @@ const TelnyxVoiceAppComponent = ({
         // Prevent duplicate processing if already connected or connecting.
         // Since push data is no longer cleared on read, this guard prevents
         // re-processing when checkForInitialPushNotification fires again on app resume.
-        if (
+        const isConnectedOrConnecting =
           voipClient.currentConnectionState ===
             connection_state_1.TelnyxConnectionState.CONNECTED ||
-          voipClient.currentConnectionState === connection_state_1.TelnyxConnectionState.CONNECTING
-        ) {
+          voipClient.currentConnectionState === connection_state_1.TelnyxConnectionState.CONNECTING;
+        const isActiveIOSCallWaitingPush =
+          react_native_1.Platform.OS === 'ios' &&
+          voipClient.currentConnectionState ===
+            connection_state_1.TelnyxConnectionState.CONNECTED &&
+          voipClient.currentCalls.some(
+            (call) =>
+              call.currentState === call_state_1.TelnyxCallState.ACTIVE ||
+              call.currentState === call_state_1.TelnyxCallState.HELD
+          );
+        if (isConnectedOrConnecting && !isActiveIOSCallWaitingPush) {
           log(
             `SKIPPING - Already ${voipClient.currentConnectionState}, preventing duplicate processing`
           );
@@ -336,20 +375,31 @@ const TelnyxVoiceAppComponent = ({
         }
         // Set flags to prevent auto-reconnection during push call
         setIsHandlingForegroundCall(true);
+        isHandlingForegroundCallRef.current = true;
         backgroundDetectorIgnore.current = true;
         log(`Background detector ignore set to: true at ${new Date().toISOString()}`);
         log(`Foreground call handling flag set to: true at ${new Date().toISOString()}`);
-        disposeBackgroundClient();
+        await disposeBackgroundClient();
         // On iOS, coordinate with CallKit using the call_id from push metadata
         if (react_native_1.Platform.OS === 'ios') {
           const callId = pushData.metadata?.call_id;
           if (callId) {
             const { callKitCoordinator } = require('./callkit/callkit-coordinator');
             log('Notifying CallKit coordinator about push notification:', callId);
-            await callKitCoordinator.handleCallKitPushReceived(callId, {
+            const processed = await callKitCoordinator.handleCallKitPushReceived(callId, {
               callData: { source: 'push_notification' },
               pushData: pushData,
             });
+            if (!processed) {
+              // The push was filtered, rejected, or otherwise ignored by
+              // CallKit. Reset the foreground-push lifecycle flags so the
+              // app does not stay in a state that skips background
+              // disconnect/reconnect handling.
+              log('CallKit push was not processed - resetting foreground flags');
+              setIsHandlingForegroundCall(false);
+              isHandlingForegroundCallRef.current = false;
+              backgroundDetectorIgnore.current = false;
+            }
           } else {
             log('No call_id found in push data, falling back to direct handling');
             await voipClient.handlePushNotification(pushData);
@@ -361,26 +411,18 @@ const TelnyxVoiceAppComponent = ({
       } catch (e) {
         log('Error processing initial push notification:', e);
         setIsHandlingForegroundCall(false);
+        isHandlingForegroundCallRef.current = false;
       } finally {
         setProcessingPushOnLaunch(false);
+        processingPushOnLaunchRef.current = false;
         onPushNotificationProcessingCompleted?.();
       }
     },
-    [
-      processingPushOnLaunch,
-      voipClient,
-      onPushNotificationProcessingStarted,
-      onPushNotificationProcessingCompleted,
-      log,
-    ]
+    [voipClient, onPushNotificationProcessingStarted, onPushNotificationProcessingCompleted, log]
   );
   // Dispose background client instance when no longer needed
-  const disposeBackgroundClient = (0, react_1.useCallback)(() => {
-    if (backgroundClientRef.current) {
-      log('Disposing background client instance');
-      backgroundClientRef.current.dispose();
-      backgroundClientRef.current = null;
-    }
+  const disposeBackgroundClient = (0, react_1.useCallback)(async () => {
+    await disposeSharedBackgroundClient(log);
   }, [log]);
   // Create background client for push notification handling
   const createBackgroundClient = (0, react_1.useCallback)(() => {
@@ -429,17 +471,18 @@ const TelnyxVoiceAppComponent = ({
         }
       }
       log(
-        `Flag reset check: WebRTC calls=${calls.length}, CallKit processing=${hasCallKitProcessing}, isHandlingForegroundCall=${isHandlingForegroundCall}, backgroundDetectorIgnore=${backgroundDetectorIgnore.current}`
+        `Flag reset check: WebRTC calls=${calls.length}, CallKit processing=${hasCallKitProcessing}, isHandlingForegroundCall=${isHandlingForegroundCallRef.current}, backgroundDetectorIgnore=${backgroundDetectorIgnore.current}`
       );
       if (
         !hasActiveWebRTCCalls &&
         !hasCallKitProcessing &&
-        (isHandlingForegroundCall || backgroundDetectorIgnore.current)
+        (isHandlingForegroundCallRef.current || backgroundDetectorIgnore.current)
       ) {
         log(
           `No active calls and no CallKit processing - resetting ignore flags at ${new Date().toISOString()}`
         );
         setIsHandlingForegroundCall(false);
+        isHandlingForegroundCallRef.current = false;
         backgroundDetectorIgnore.current = false;
       } else if (!hasActiveWebRTCCalls && hasCallKitProcessing) {
         log(
@@ -450,9 +493,10 @@ const TelnyxVoiceAppComponent = ({
       }
       // Also reset processingPushOnLaunch if no calls are active
       // This ensures the flag doesn't get stuck after call ends
-      if (calls.length === 0 && processingPushOnLaunch) {
+      if (calls.length === 0 && processingPushOnLaunchRef.current) {
         log('No active calls - resetting processing push flag');
         setProcessingPushOnLaunch(false);
+        processingPushOnLaunchRef.current = false;
       }
     });
     // Listen for immediate call action events from notification buttons (Android only)
@@ -501,7 +545,7 @@ const TelnyxVoiceAppComponent = ({
     // Handle initial push notification if app was launched from terminated state
     // Only check if we're not already processing to prevent infinite loops
     const timeoutId = setTimeout(() => {
-      if (!processingPushOnLaunch) {
+      if (!processingPushOnLaunchRef.current) {
         checkForInitialPushNotification();
       }
     }, 100);
@@ -523,16 +567,9 @@ const TelnyxVoiceAppComponent = ({
       }
       clearTimeout(timeoutId);
       // Clean up background client instance
-      disposeBackgroundClient();
+      void disposeBackgroundClient();
     };
-  }, [
-    voipClient,
-    handleAppStateChange,
-    disposeBackgroundClient,
-    skipWebBackgroundDetection,
-    isHandlingForegroundCall,
-    log,
-  ]);
+  }, [voipClient, handleAppStateChange, disposeBackgroundClient, skipWebBackgroundDetection, log]);
   // Simply return the children wrapped in context provider - all lifecycle management is handled internally
   return (0, jsx_runtime_1.jsx)(TelnyxVoiceContext_1.TelnyxVoiceProvider, {
     voipClient: voipClient,
@@ -608,18 +645,23 @@ const initializeAndCreate = async (options) => {
  */
 const handleBackgroundPush = async (message) => {
   console.log('[TelnyxVoiceApp] Background push received:', message);
+  let backgroundClient = null;
   try {
     // TODO: Initialize push notification service in isolate if needed
+    await disposeSharedBackgroundClient(console.log);
     // Use singleton pattern for background client to prevent multiple instances
-    let backgroundClient = (0, telnyx_voip_client_1.createBackgroundTelnyxVoipClient)({
+    backgroundClient = (0, telnyx_voip_client_1.createBackgroundTelnyxVoipClient)({
       debug: false,
     });
+    sharedBackgroundClient = backgroundClient;
     await backgroundClient.handlePushNotification(message);
     console.log('[TelnyxVoiceApp] Background push processed successfully');
-    // Clean up the background client
-    backgroundClient.dispose();
   } catch (e) {
     console.log('[TelnyxVoiceApp] Error processing background push:', e);
+  } finally {
+    if (backgroundClient) {
+      await disposeSharedBackgroundClient(console.log, backgroundClient);
+    }
   }
 };
 // Create the component with static methods

package/lib/telnyx-voip-client.d.ts

@@ -2,6 +2,7 @@ import { Observable } from 'rxjs';
 import { TelnyxConnectionState } from './models/connection-state';
 import { Call } from './models/call';
 import { CredentialConfig, TokenConfig } from './models/config';
+import { type CustomHeaders } from './internal/calls/call-state-controller';
 /**
  * Configuration options for TelnyxVoipClient
  */
@@ -10,6 +11,8 @@ export interface TelnyxVoipClientOptions {
   enableAppStateManagement?: boolean;
   /** Enable debug logging */
   debug?: boolean;
+  /** Enable Trickle ICE for calls created by this client */
+  useTrickleIce?: boolean;
 }
 /**
  * The main public interface for the react-voice-commons module.
@@ -26,7 +29,9 @@ export declare class TelnyxVoipClient {
   private readonly _sessionManager;
   private readonly _callStateController;
   private readonly _options;
+  private readonly _pendingCallKitAnswers;
   private _disposed;
+  private _disposePromise?;
   /**
    * Check if the app was launched from a push notification.
    *
@@ -100,6 +105,22 @@ export declare class TelnyxVoipClient {
    * ```
    */
   getCall(callId: string): Call | null;
+  /**
+   * Explicitly set the active call for multi-call scenarios.
+   * @param callId The ID of the call to mark as active
+   */
+  setActiveCall(callId: string): void;
+  /**
+   * Clear the explicitly selected active call and return to default selection.
+   */
+  clearActiveCall(): void;
+  /**
+   * Swap the current active call with a held call.
+   * On iOS this is coordinated through CallKit so native and SDK state stay aligned.
+   *
+   * @param targetCallId ID of the held call to make active
+   */
+  swapCalls(targetCallId: string): Promise<void>;
   /**
    * Current session ID (UUID) for this connection.
    */
@@ -159,7 +180,7 @@ export declare class TelnyxVoipClient {
     destination: string,
     callerName?: string,
     callerNumber?: string,
-    customHeaders?: Record<string, string>
+    customHeaders?: CustomHeaders
   ): Promise<Call>;
   /**
    * Handle push notification payload.
@@ -195,12 +216,21 @@ export declare class TelnyxVoipClient {
    * This should be called when the user answers from CallKit before the socket connection is established
    * @param customHeaders Optional custom headers to include with the answer
    */
-  queueAnswerFromCallKit(customHeaders?: Record<string, string>): void;
+  queueAnswerFromCallKit(
+    callKitUUIDOrHeaders?: string | Record<string, string>,
+    customHeaders?: Record<string, string>
+  ): void;
   /**
    * Queue an end action for when the call invite arrives (for CallKit integration)
    * This should be called when the user ends from CallKit before the socket connection is established
    */
-  queueEndFromCallKit(): void;
+  queueEndFromCallKit(callKitUUID?: string): void;
+  /**
+   * Associate the next push-delivered INVITE with its app-facing CallKit UUID.
+   * The underlying signaling call ID remains unchanged.
+   * @internal
+   */
+  setPushNotificationCallKitUUID(callKitUUID: string | null): void;
   /**
    * Dispose of the client and clean up all resources.
    *
@@ -208,7 +238,20 @@ export declare class TelnyxVoipClient {
    * This is particularly important for background clients that should be
    * disposed after handling push notifications.
    */
-  dispose(): void;
+  dispose(): Promise<void>;
+  /**
+   * Forward answers captured during cold start as soon as SessionManager has
+   * created the TelnyxRTC instance. SessionManager invokes its ready callback
+   * before connect(), so the UUID-keyed action is present when the INVITE
+   * arrives.
+   */
+  private _flushPendingCallKitAnswers;
+  /**
+   * Prefer an explicitly supplied token, otherwise hydrate it from PushKit's
+   * native storage. PushKit registration starts in AppDelegate before React
+   * mounts, so this removes the race between the JS token event and login.
+   */
+  private _withNativeVoipPushToken;
   /**
    * Store credential configuration for automatic reconnection
    */
@@ -236,7 +279,7 @@ export declare function createTelnyxVoipClient(options?: TelnyxVoipClientOptions
  * Disposes the current singleton so that a subsequent call to
  * `createTelnyxVoipClient()` will create a fresh instance.
  */
-export declare function destroyTelnyxVoipClient(): void;
+export declare function destroyTelnyxVoipClient(): Promise<void>;
 /**
  * Create a new TelnyxVoipClient instance for background push notification handling.
  *