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

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # CHANGELOG.md
 
+## [0.1.7](https://github.com/team-telnyx/react-native-voice-commons/releases/tag/0.1.7) (2026-02-20)
+
+### Enhancement
+
+• Added `TelnyxVoipClient.isLaunchedFromPushNotification()` static method to check if the app was cold-started from a push notification, allowing consumers to skip auto-login and avoid double-login races
+• `createTelnyxVoipClient()` now returns a singleton — safe to call inside React component bodies without creating a new instance on every render
+• Added `destroyTelnyxVoipClient()` to tear down the singleton when a fresh instance is needed
+• `TelnyxVoiceApp` now automatically wires the `voipClient` on the CallKit coordinator on mount — consumers no longer need to manually call `setVoipClient()` at the correct component level
+
+### Bug Fixing
+
+• Fixed cold-start push notification failures caused by double-login race between user auto-login and SDK internal push login
+• Fixed CallKit coordinator having no `voipClient` reference when user answered a call via CallKit before navigating to the correct screen
+• Fixed `call_id` extraction in `checkForInitialPushNotification` — the double-nested path `pushData.metadata?.metadata?.call_id` never resolved, so the CallKit coordinator was bypassed on iOS
+• Refactored `checkForInitialPushNotification` into `getAndroidPushData` and `getIOSPushData` helpers to reduce nesting and improve readability
+
+### Deprecation
+
+• `setVoipClient()` on `CallKitCoordinator` and `useCallKitCoordinator()` hook is now deprecated — `TelnyxVoiceApp` handles this automatically
+
+## [0.1.7-beta.0](https://github.com/team-telnyx/react-native-voice-commons/releases/tag/0.1.7-beta.0) (2026-02-18)
+
+### Bug Fixing
+
+• Fixed `call_id` extraction in `checkForInitialPushNotification` — the double-nested path `pushData.metadata?.metadata?.call_id` never resolved, so the CallKit coordinator was bypassed and all iOS push calls fell through to direct handling
+• Refactored `checkForInitialPushNotification` into `getAndroidPushData` and `getIOSPushData` helpers to reduce nesting and improve readability
+
 ## [0.1.6](https://github.com/team-telnyx/react-native-voice-commons/releases/tag/0.1.6) (2025-12-09)
 
 ### Enhancement

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/internal/calls/call-state-controller.js

@@ -326,8 +326,8 @@ class CallStateController {
         console.log('CallStateController: Reporting incoming call to CallKitCoordinator');
         callkit_coordinator_1.callKitCoordinator.reportIncomingCall(
           telnyxCall,
-          call.destination,
-          call.destination
+          call.callerName,
+          call.callerNumber
         );
       } else {
         // Handle outgoing call with CallKit

package/lib/internal/session/session-manager.d.ts

@@ -49,7 +49,9 @@ export declare class SessionManager {
    */
   disconnect(): Promise<void>;
   /**
-   * Disable push notifications for the current session
+   * Disable push notifications for the current session.
+   * Delegates to the TelnyxRTC client's disablePushNotification() method
+   * which sends a 'telnyx_rtc.disable_push_notification' message via the socket.
    */
   disablePushNotifications(): void;
   /**

package/lib/internal/session/session-manager.js

@@ -140,16 +140,19 @@ class SessionManager {
     this._connectionState.next(connection_state_1.TelnyxConnectionState.DISCONNECTED);
   }
   /**
-   * Disable push notifications for the current session
+   * Disable push notifications for the current session.
+   * Delegates to the TelnyxRTC client's disablePushNotification() method
+   * which sends a 'telnyx_rtc.disable_push_notification' message via the socket.
    */
   disablePushNotifications() {
     if (
       this._telnyxClient &&
       this.currentState === connection_state_1.TelnyxConnectionState.CONNECTED
     ) {
-      // Implementation depends on the actual Telnyx SDK API
-      // This is a placeholder for the actual implementation
-      console.log('Disabling push notifications for session:', this._sessionId);
+      console.log('SessionManager: Disabling push notifications for session:', this._sessionId);
+      this._telnyxClient.disablePushNotification();
+    } else {
+      console.warn('SessionManager: Cannot disable push - client not connected');
     }
   }
   /**

package/lib/models/call.d.ts

@@ -46,6 +46,16 @@ export declare class Call {
    * Whether this is an outgoing call
    */
   get isOutgoing(): boolean;
+  /**
+   * The original caller name (from_display_name) received in the INVITE message.
+   * Falls back to destination if not available.
+   */
+  get callerName(): string;
+  /**
+   * The original caller number received in the INVITE message.
+   * Falls back to destination if not available.
+   */
+  get callerNumber(): string;
   /**
    * Current call state (synchronous access)
    */

package/lib/models/call.js

@@ -115,6 +115,20 @@ class Call {
   get isOutgoing() {
     return !this._isIncoming;
   }
+  /**
+   * The original caller name (from_display_name) received in the INVITE message.
+   * Falls back to destination if not available.
+   */
+  get callerName() {
+    return this._originalCallerName || this._destination;
+  }
+  /**
+   * The original caller number received in the INVITE message.
+   * Falls back to destination if not available.
+   */
+  get callerNumber() {
+    return this._originalCallerNumber || this._destination;
+  }
   /**
    * Current call state (synchronous access)
    */

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-beta.1",
+  "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/internal/calls/call-state-controller.ts

@@ -392,7 +392,7 @@ export class CallStateController {
       } else if (call.isIncoming) {
         // Handle incoming call with CallKit (only if not already integrated)
         console.log('CallStateController: Reporting incoming call to CallKitCoordinator');
-        callKitCoordinator.reportIncomingCall(telnyxCall, call.destination, call.destination);
+        callKitCoordinator.reportIncomingCall(telnyxCall, call.callerName, call.callerNumber);
       } else {
         // Handle outgoing call with CallKit
         console.log('CallStateController: Starting outgoing call with CallKitCoordinator');

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

@@ -111,13 +111,16 @@ export class SessionManager {
   }
 
   /**
-   * Disable push notifications for the current session
+   * Disable push notifications for the current session.
+   * Delegates to the TelnyxRTC client's disablePushNotification() method
+   * which sends a 'telnyx_rtc.disable_push_notification' message via the socket.
    */
   disablePushNotifications(): void {
     if (this._telnyxClient && this.currentState === TelnyxConnectionState.CONNECTED) {
-      // Implementation depends on the actual Telnyx SDK API
-      // This is a placeholder for the actual implementation
-      console.log('Disabling push notifications for session:', this._sessionId);
+      console.log('SessionManager: Disabling push notifications for session:', this._sessionId);
+      this._telnyxClient.disablePushNotification();
+    } else {
+      console.warn('SessionManager: Cannot disable push - client not connected');
     }
   }
 

package/src/models/call.ts

@@ -66,6 +66,22 @@ export class Call {
     return !this._isIncoming;
   }
 
+  /**
+   * The original caller name (from_display_name) received in the INVITE message.
+   * Falls back to destination if not available.
+   */
+  get callerName(): string {
+    return this._originalCallerName || this._destination;
+  }
+
+  /**
+   * The original caller number received in the INVITE message.
+   * Falls back to destination if not available.
+   */
+  get callerNumber(): string {
+    return this._originalCallerNumber || this._destination;
+  }
+
   /**
    * Current call state (synchronous access)
    */

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;
         }
 

package/src/types/telnyx-sdk.d.ts

@@ -83,6 +83,7 @@ declare module '@telnyx/react-native-voice-sdk' {
     connect(): Promise<void>;
     disconnect(): void;
     newCall(options: CallOptions): Promise<Call>;
+    disablePushNotification(): void;
 
     on(event: string, listener: (...args: any[]) => void): this;
     off(event: string, listener: (...args: any[]) => void): this;