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

package/src/models/config.ts

@@ -7,8 +7,12 @@ 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 */
@@ -29,8 +33,12 @@ 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 */
@@ -113,6 +121,7 @@ export 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 function createCredentialConfig(
@@ -135,6 +144,7 @@ export 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 function createTokenConfig(

package/src/telnyx-voice-app.tsx

@@ -3,8 +3,40 @@ import { AppState, AppStateStatus, Platform } from 'react-native';
 import { TelnyxVoipClient, createBackgroundTelnyxVoipClient } from './telnyx-voip-client';
 import { TelnyxConnectionState } from './models/connection-state';
 import { Call } from './models/call';
+import { TelnyxCallState } from './models/call-state';
 import { TelnyxVoiceProvider } from './context/TelnyxVoiceContext';
 
+let sharedBackgroundClient: TelnyxVoipClient | null = null;
+let sharedBackgroundDisposePromise: Promise<void> | null = null;
+
+const disposeSharedBackgroundClient = async (
+  log: (message: string, ...args: any[]) => void,
+  expectedClient?: TelnyxVoipClient
+): Promise<void> => {
+  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;
+};
+
 /**
  * Configuration options for TelnyxVoiceApp
  */
@@ -91,13 +123,19 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
     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 = useRef(false);
+  const processingPushOnLaunchRef = useRef(false);
+
   // Refs for tracking state
   const appStateRef = useRef<AppStateStatus>(AppState.currentState);
   const backgroundDetectorIgnore = useRef(false);
 
-  // Static background client instance for singleton pattern
-  const backgroundClientRef = useRef<TelnyxVoipClient | null>(null);
-
   const log = useCallback(
     (message: string, ...args: any[]) => {
       if (debug) {
@@ -115,7 +153,7 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
 
       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);
@@ -147,13 +185,13 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
         await handleAppResumed();
       }
     },
-    [enableAutoReconnect, onAppStateChanged, isHandlingForegroundCall, log]
+    [enableAutoReconnect, onAppStateChanged, log]
   );
 
   // Handle app going to background - disconnect like the old implementation
   const handleAppBackgrounded = 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'
       );
@@ -206,7 +244,7 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
     } catch (e) {
       log('Error disconnecting on background:', e);
     }
-  }, [voipClient, isHandlingForegroundCall, log]);
+  }, [voipClient, log]);
 
   // Handle app resuming from background
   const handleAppResumed = useCallback(async () => {
@@ -217,7 +255,7 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
     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'
       );
@@ -248,7 +286,7 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
     if (currentState !== TelnyxConnectionState.CONNECTED) {
       await attemptAutoReconnection();
     }
-  }, [voipClient, isHandlingForegroundCall, log]);
+  }, [voipClient, log]);
 
   // Attempt to reconnect using stored credentials
   const attemptAutoReconnection = useCallback(async () => {
@@ -399,13 +437,14 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
     async (fromAppResume: boolean = 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?.();
 
@@ -433,10 +472,19 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
         // 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 === TelnyxConnectionState.CONNECTED ||
-          voipClient.currentConnectionState === TelnyxConnectionState.CONNECTING
-        ) {
+          voipClient.currentConnectionState === TelnyxConnectionState.CONNECTING;
+        const isActiveIOSCallWaitingPush =
+          Platform.OS === 'ios' &&
+          voipClient.currentConnectionState === TelnyxConnectionState.CONNECTED &&
+          voipClient.currentCalls.some(
+            (call) =>
+              call.currentState === TelnyxCallState.ACTIVE ||
+              call.currentState === TelnyxCallState.HELD
+          );
+
+        if (isConnectedOrConnecting && !isActiveIOSCallWaitingPush) {
           log(
             `SKIPPING - Already ${voipClient.currentConnectionState}, preventing duplicate processing`
           );
@@ -445,11 +493,12 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
 
         // 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 (Platform.OS === 'ios') {
@@ -457,10 +506,20 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
           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);
@@ -473,27 +532,19 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
       } 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 = useCallback(() => {
-    if (backgroundClientRef.current) {
-      log('Disposing background client instance');
-      backgroundClientRef.current.dispose();
-      backgroundClientRef.current = null;
-    }
+  const disposeBackgroundClient = useCallback(async (): Promise<void> => {
+    await disposeSharedBackgroundClient(log);
   }, [log]);
 
   // Create background client for push notification handling
@@ -551,18 +602,19 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
       }
 
       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(
@@ -574,9 +626,10 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
 
       // 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;
       }
     });
 
@@ -628,7 +681,7 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
     // 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);
@@ -651,16 +704,9 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
       }
       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 <TelnyxVoiceProvider voipClient={voipClient}>{children}</TelnyxVoiceProvider>;
@@ -769,23 +815,28 @@ const initializeAndCreate = async (options: {
  */
 const handleBackgroundPush = async (message: any): Promise<void> => {
   console.log('[TelnyxVoiceApp] Background push received:', message);
+  let backgroundClient: TelnyxVoipClient | null = 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 = createBackgroundTelnyxVoipClient({
+    backgroundClient = 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);
+    }
   }
 };