@telnyx/react-voice-commons-sdk 0.1.7 → 0.1.8-beta.0

package/README.md

@@ -32,15 +32,30 @@ The `@telnyx/react-voice-commons-sdk` library provides:
 Integrate the library using the `TelnyxVoiceApp` component for automatic lifecycle management:
 
 ```tsx
-import { TelnyxVoiceApp, createTelnyxVoipClient } from '@telnyx/react-voice-commons-sdk';
+import {
+  TelnyxVoiceApp,
+  TelnyxVoipClient,
+  createTelnyxVoipClient,
+} from '@telnyx/react-voice-commons-sdk';
 
-// Create the VoIP client instance
+// Create the VoIP client instance (singleton — safe to call inside a component body)
 const voipClient = createTelnyxVoipClient({
   enableAppStateManagement: true, // Optional: Enable automatic app state management (default: true)
   debug: true, // Optional: Enable debug logging
 });
 
 export default function App() {
+  // Skip auto-login if the app was launched from a push notification —
+  // the SDK handles login internally via the push notification flow.
+  React.useEffect(() => {
+    TelnyxVoipClient.isLaunchedFromPushNotification().then((isFromPush) => {
+      if (!isFromPush) {
+        // Safe to auto-login
+        voipClient.loginFromStoredConfig();
+      }
+    });
+  }, []);
+
   return (
     <TelnyxVoiceApp voipClient={voipClient} enableAutoReconnect={false} debug={true}>
       <YourAppContent />
@@ -54,10 +69,16 @@ export default function App() {
 ### 1. VoIP Client Configuration
 
 ```tsx
+// createTelnyxVoipClient is a singleton — repeated calls return the same instance.
+// This makes it safe to call inside a React component body without re-creating on every render.
 const voipClient = createTelnyxVoipClient({
   enableAppStateManagement: true, // Optional: Enable automatic app state management (default: true)
   debug: true, // Optional: Enable debug logging
 });
+
+// If you need to tear down and recreate the client (e.g., on logout):
+import { destroyTelnyxVoipClient } from '@telnyx/react-voice-commons-sdk';
+destroyTelnyxVoipClient(); // Disposes the singleton; next createTelnyxVoipClient() call creates a fresh instance
 ```
 
 **Configuration Options Explained:**
@@ -73,6 +94,7 @@ The `TelnyxVoiceApp` component handles:
 - Push notification processing from terminated state
 - Login state management with automatic reconnection
 - Background client management for push notifications
+- **Automatic CallKit coordinator wiring** — the `voipClient` is set on the CallKit coordinator on mount, so you don't need to call `setVoipClient()` manually
 
 ### 3. Reactive State Management
 
@@ -416,9 +438,18 @@ npx expo run:ios
 
 ### Common Integration Issues
 
-### Double Login
+### Double Login on Cold-Start
+
+When the app is launched from a push notification, the SDK handles login internally. If your app also auto-logs in on mount, both will race and the push flow breaks. Use `isLaunchedFromPushNotification()` to guard your auto-login:
+
+```tsx
+const isFromPush = await TelnyxVoipClient.isLaunchedFromPushNotification();
+if (!isFromPush) {
+  voipClient.loginFromStoredConfig();
+}
+```
 
-Ensure you're not calling login methods manually when using `TelnyxVoiceApp` with auto-reconnection enabled.
+Also ensure you're not calling login methods manually when using `TelnyxVoiceApp` with auto-reconnection enabled.
 
 ### Background Disconnection
 
@@ -457,7 +488,6 @@ useEffect(() => {
   const subscription = voipClient.connectionState$.subscribe(handleStateChange);
   return () => subscription.unsubscribe();
 }, []);
-}, []);
 ```
 
 ## Documentation

package/lib/callkit/callkit-coordinator.js

@@ -303,10 +303,21 @@ class CallKitCoordinator {
       } else {
         console.log('CallKitCoordinator: Outgoing call, skipping answer and CONNECTING state');
       }
+      // Clear push data now that answer action is fulfilled
+      try {
+        await voice_pn_bridge_1.VoicePnBridge.clearPendingVoipPush();
+        console.log('CallKitCoordinator: Cleared pending VoIP push after answer fulfilled');
+      } catch (clearErr) {
+        console.error('CallKitCoordinator: Error clearing push data after answer:', clearErr);
+      }
     } catch (error) {
       console.error('CallKitCoordinator: Error processing CallKit answer', error);
       await callkit_1.default.reportCallEnded(callKitUUID, callkit_1.CallEndReason.Failed);
       this.cleanupCall(callKitUUID);
+      // Clear push data even on error to prevent stale state
+      try {
+        await voice_pn_bridge_1.VoicePnBridge.clearPendingVoipPush();
+      } catch (_) {}
     } finally {
       this.processingCalls.delete(callKitUUID);
     }
@@ -352,6 +363,11 @@ class CallKitCoordinator {
     } finally {
       this.processingCalls.delete(callKitUUID);
       this.cleanupCall(callKitUUID);
+      // Clear push data now that end action is fulfilled
+      try {
+        await voice_pn_bridge_1.VoicePnBridge.clearPendingVoipPush();
+        console.log('CallKitCoordinator: Cleared pending VoIP push after end fulfilled');
+      } catch (_) {}
       // Check if app is in background and no more calls - disconnect client
       await this.checkBackgroundDisconnection();
     }
@@ -506,6 +522,11 @@ class CallKitCoordinator {
         // Set the pending push action to be handled when app comes to foreground
         await voice_pn_bridge_1.VoicePnBridge.setPendingPushAction(pushAction, pushMetadata);
         console.log('CallKitCoordinator: ✅ Set pending push action');
+        // Clear push data now that push notification answer is handled
+        try {
+          await voice_pn_bridge_1.VoicePnBridge.clearPendingVoipPush();
+          console.log('CallKitCoordinator: Cleared pending VoIP push after push answer handled');
+        } catch (_) {}
         return;
       }
       // For other platforms (shouldn't happen on iOS)
@@ -533,6 +554,11 @@ class CallKitCoordinator {
         this.voipClient.queueEndFromCallKit();
         // Clean up push notification state
         await this.cleanupPushNotificationState();
+        // Clear push data now that rejection is handled
+        try {
+          await voice_pn_bridge_1.VoicePnBridge.clearPendingVoipPush();
+          console.log('CallKitCoordinator: Cleared pending VoIP push after rejection handled');
+        } catch (_) {}
         console.log('CallKitCoordinator: 🎯 Push notification rejection handling complete');
         return;
       }
@@ -738,7 +764,11 @@ class CallKitCoordinator {
    * This helps prevent premature flag resets during CallKit operations
    */
   hasProcessingCalls() {
-    return this.processingCalls.size > 0;
+    // Also return true when isCallFromPush is set — this prevents the
+    // calls$ subscription in TelnyxVoiceApp from resetting protection flags
+    // (isHandlingForegroundCall, backgroundDetectorIgnore) before the WebRTC
+    // call arrives during push notification handling.
+    return this.processingCalls.size > 0 || this.isCallFromPush;
   }
   /**
    * Check if there's currently a call from push notification being processed

package/lib/telnyx-voice-app.js

@@ -274,8 +274,14 @@ const TelnyxVoiceAppComponent = ({
           return null;
         }
         log('Found pending VoIP push data:', voipPayload);
-        await VoicePnBridge.clearPendingVoipPush();
-        log('Cleared pending VoIP push data after retrieval');
+        // Do NOT clear push data here. Let it persist until the answer/end action
+        // is fulfilled in the CallKit coordinator. This prevents a race condition in
+        // Expo apps where the RN bridge mounts immediately on push notification —
+        // the push data would be consumed and cleared before the user answers,
+        // leaving the coordinator with nothing to work with.
+        // For non-Expo apps (RN mounts after answer), the coordinator's
+        // handlePushNotificationAnswer/Reject clears the data before
+        // checkForInitialPushNotification ever runs, so no loop occurs.
         return { action: 'incoming_call', metadata: voipPayload.metadata, from_notification: true };
       } catch (parseError) {
         log('Error parsing VoIP push JSON:', parseError);
@@ -315,11 +321,17 @@ const TelnyxVoiceAppComponent = ({
           return;
         }
         log('Processing initial push notification...');
-        // Prevent duplicate processing if already connected
+        // 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 (
-          voipClient.currentConnectionState === connection_state_1.TelnyxConnectionState.CONNECTED
+          voipClient.currentConnectionState ===
+            connection_state_1.TelnyxConnectionState.CONNECTED ||
+          voipClient.currentConnectionState === connection_state_1.TelnyxConnectionState.CONNECTING
         ) {
-          log('SKIPPING - Already connected, preventing duplicate processing');
+          log(
+            `SKIPPING - Already ${voipClient.currentConnectionState}, preventing duplicate processing`
+          );
           return;
         }
         // Set flags to prevent auto-reconnection during push call

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telnyx/react-voice-commons-sdk",
-  "version": "0.1.7",
+  "version": "0.1.8-beta.0",
   "description": "A high-level, state-agnostic, drop-in module for the Telnyx React Native SDK that simplifies WebRTC voice calling integration",
   "main": "lib/index.js",
   "module": "lib/index.js",

package/src/callkit/callkit-coordinator.ts

@@ -306,10 +306,21 @@ class CallKitCoordinator {
       } else {
         console.log('CallKitCoordinator: Outgoing call, skipping answer and CONNECTING state');
       }
+      // Clear push data now that answer action is fulfilled
+      try {
+        await VoicePnBridge.clearPendingVoipPush();
+        console.log('CallKitCoordinator: Cleared pending VoIP push after answer fulfilled');
+      } catch (clearErr) {
+        console.error('CallKitCoordinator: Error clearing push data after answer:', clearErr);
+      }
     } catch (error) {
       console.error('CallKitCoordinator: Error processing CallKit answer', error);
       await CallKit.reportCallEnded(callKitUUID, CallEndReason.Failed);
       this.cleanupCall(callKitUUID);
+      // Clear push data even on error to prevent stale state
+      try {
+        await VoicePnBridge.clearPendingVoipPush();
+      } catch (_) {}
     } finally {
       this.processingCalls.delete(callKitUUID);
     }
@@ -366,6 +377,12 @@ class CallKitCoordinator {
       this.processingCalls.delete(callKitUUID);
       this.cleanupCall(callKitUUID);
 
+      // Clear push data now that end action is fulfilled
+      try {
+        await VoicePnBridge.clearPendingVoipPush();
+        console.log('CallKitCoordinator: Cleared pending VoIP push after end fulfilled');
+      } catch (_) {}
+
       // Check if app is in background and no more calls - disconnect client
       await this.checkBackgroundDisconnection();
     }
@@ -544,6 +561,12 @@ class CallKitCoordinator {
         await VoicePnBridge.setPendingPushAction(pushAction, pushMetadata);
         console.log('CallKitCoordinator: ✅ Set pending push action');
 
+        // Clear push data now that push notification answer is handled
+        try {
+          await VoicePnBridge.clearPendingVoipPush();
+          console.log('CallKitCoordinator: Cleared pending VoIP push after push answer handled');
+        } catch (_) {}
+
         return;
       }
 
@@ -577,6 +600,12 @@ class CallKitCoordinator {
         // Clean up push notification state
         await this.cleanupPushNotificationState();
 
+        // Clear push data now that rejection is handled
+        try {
+          await VoicePnBridge.clearPendingVoipPush();
+          console.log('CallKitCoordinator: Cleared pending VoIP push after rejection handled');
+        } catch (_) {}
+
         console.log('CallKitCoordinator: 🎯 Push notification rejection handling complete');
         return;
       }
@@ -815,7 +844,11 @@ class CallKitCoordinator {
    * This helps prevent premature flag resets during CallKit operations
    */
   hasProcessingCalls(): boolean {
-    return this.processingCalls.size > 0;
+    // Also return true when isCallFromPush is set — this prevents the
+    // calls$ subscription in TelnyxVoiceApp from resetting protection flags
+    // (isHandlingForegroundCall, backgroundDetectorIgnore) before the WebRTC
+    // call arrives during push notification handling.
+    return this.processingCalls.size > 0 || this.isCallFromPush;
   }
 
   /**

package/src/telnyx-voice-app.tsx

@@ -374,8 +374,14 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
 
         log('Found pending VoIP push data:', voipPayload);
 
-        await VoicePnBridge.clearPendingVoipPush();
-        log('Cleared pending VoIP push data after retrieval');
+        // Do NOT clear push data here. Let it persist until the answer/end action
+        // is fulfilled in the CallKit coordinator. This prevents a race condition in
+        // Expo apps where the RN bridge mounts immediately on push notification —
+        // the push data would be consumed and cleared before the user answers,
+        // leaving the coordinator with nothing to work with.
+        // For non-Expo apps (RN mounts after answer), the coordinator's
+        // handlePushNotificationAnswer/Reject clears the data before
+        // checkForInitialPushNotification ever runs, so no loop occurs.
 
         return { action: 'incoming_call', metadata: voipPayload.metadata, from_notification: true };
       } catch (parseError) {
@@ -424,9 +430,14 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
 
         log('Processing initial push notification...');
 
-        // Prevent duplicate processing if already connected
-        if (voipClient.currentConnectionState === TelnyxConnectionState.CONNECTED) {
-          log('SKIPPING - Already connected, preventing duplicate processing');
+        // 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 (
+          voipClient.currentConnectionState === TelnyxConnectionState.CONNECTED ||
+          voipClient.currentConnectionState === TelnyxConnectionState.CONNECTING
+        ) {
+          log(`SKIPPING - Already ${voipClient.currentConnectionState}, preventing duplicate processing`);
           return;
         }