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

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/lib/callkit/callkit-coordinator.d.ts

@@ -89,7 +89,10 @@ declare class CallKitCoordinator {
    */
   linkExistingCallKitCall(call: Call, callKitUUID: string): void;
   /**
-   * Set the VoIP client reference for triggering reconnection
+   * Set the VoIP client reference for triggering reconnection.
+   *
+   * @deprecated No longer needed — TelnyxVoiceApp now auto-wires the voipClient
+   * on mount. Kept for backwards compatibility.
    */
   setVoipClient(voipClient: TelnyxVoipClient): void;
   /**

package/lib/callkit/callkit-coordinator.js

@@ -673,7 +673,10 @@ class CallKitCoordinator {
     this.setupWebRTCCallListeners(call, callKitUUID);
   }
   /**
-   * Set the VoIP client reference for triggering reconnection
+   * Set the VoIP client reference for triggering reconnection.
+   *
+   * @deprecated No longer needed — TelnyxVoiceApp now auto-wires the voipClient
+   * on mount. Kept for backwards compatibility.
    */
   setVoipClient(voipClient) {
     this.voipClient = voipClient;

package/lib/hooks/use-callkit-coordinator.js

@@ -36,6 +36,11 @@ function useCallKitCoordinator() {
   const isAvailable = (0, react_1.useCallback)(() => {
     return callkit_coordinator_1.default.isAvailable();
   }, []);
+  /**
+   * @deprecated No longer needed — TelnyxVoiceApp now auto-wires the voipClient
+   * on the CallKit coordinator when it receives the voipClient prop.
+   * This method is kept for backwards compatibility and will be removed in a future release.
+   */
   const setVoipClient = (0, react_1.useCallback)((voipClient) => {
     callkit_coordinator_1.default.setVoipClient(voipClient);
   }, []);

package/lib/index.d.ts

@@ -11,6 +11,7 @@
 export {
   TelnyxVoipClient,
   createTelnyxVoipClient,
+  destroyTelnyxVoipClient,
   createBackgroundTelnyxVoipClient,
 } from './telnyx-voip-client';
 export type { TelnyxVoipClientOptions } from './telnyx-voip-client';

package/lib/index.js

@@ -58,6 +58,7 @@ exports.useAppReadyNotifier =
   exports.useAppStateHandler =
   exports.TelnyxVoiceApp =
   exports.createBackgroundTelnyxVoipClient =
+  exports.destroyTelnyxVoipClient =
   exports.createTelnyxVoipClient =
   exports.TelnyxVoipClient =
     void 0;
@@ -75,6 +76,12 @@ Object.defineProperty(exports, 'createTelnyxVoipClient', {
     return telnyx_voip_client_1.createTelnyxVoipClient;
   },
 });
+Object.defineProperty(exports, 'destroyTelnyxVoipClient', {
+  enumerable: true,
+  get: function () {
+    return telnyx_voip_client_1.destroyTelnyxVoipClient;
+  },
+});
 Object.defineProperty(exports, 'createBackgroundTelnyxVoipClient', {
   enumerable: true,
   get: function () {

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

@@ -378,6 +378,19 @@ const TelnyxVoiceAppComponent = ({
     });
     return backgroundClient;
   }, [debug, log]);
+  // Auto-wire the voipClient on the CallKit coordinator so consumers don't
+  // have to call setVoipClient() manually at the right level.
+  (0, react_1.useEffect)(() => {
+    if (react_native_1.Platform.OS === 'ios') {
+      try {
+        const { callKitCoordinator } = require('./callkit/callkit-coordinator');
+        callKitCoordinator.setVoipClient(voipClient);
+        log('Auto-wired voipClient on CallKit coordinator');
+      } catch (e) {
+        log('Error auto-wiring voipClient on CallKit coordinator:', e);
+      }
+    }
+  }, [voipClient, log]);
   // Setup effect
   (0, react_1.useEffect)(() => {
     // Listen to connection state changes

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

@@ -27,6 +27,16 @@ export declare class TelnyxVoipClient {
   private readonly _callStateController;
   private readonly _options;
   private _disposed;
+  /**
+   * Check if the app was launched from a push notification.
+   *
+   * Use this to avoid double-login on cold start. When true, the SDK will
+   * handle login internally via the push notification flow, so you should
+   * skip your normal auto-login.
+   *
+   * @returns true if there is pending push notification data indicating a push-launched app
+   */
+  static isLaunchedFromPushNotification(): Promise<boolean>;
   /**
    * Creates a new TelnyxVoipClient instance.
    *
@@ -213,11 +223,25 @@ export declare class TelnyxVoipClient {
   private _throwIfDisposed;
 }
 /**
- * Create a new TelnyxVoipClient instance for normal app usage
+ * Create or retrieve the shared TelnyxVoipClient instance.
+ *
+ * This uses a singleton pattern — calling it multiple times (e.g., inside a
+ * React component body) always returns the same instance.  If you need to
+ * reset the instance, call `destroyTelnyxVoipClient()` first.
  */
 export declare function createTelnyxVoipClient(options?: TelnyxVoipClientOptions): TelnyxVoipClient;
 /**
- * Create a new TelnyxVoipClient instance for background push notification handling
+ * Destroy the shared TelnyxVoipClient instance.
+ *
+ * Disposes the current singleton so that a subsequent call to
+ * `createTelnyxVoipClient()` will create a fresh instance.
+ */
+export declare function destroyTelnyxVoipClient(): void;
+/**
+ * Create a new TelnyxVoipClient instance for background push notification handling.
+ *
+ * Unlike `createTelnyxVoipClient`, this always creates a new instance because
+ * background isolates need their own independent client.
  */
 export declare function createBackgroundTelnyxVoipClient(
   options?: TelnyxVoipClientOptions

package/lib/telnyx-voip-client.js

@@ -2,12 +2,14 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 exports.TelnyxVoipClient = void 0;
 exports.createTelnyxVoipClient = createTelnyxVoipClient;
+exports.destroyTelnyxVoipClient = destroyTelnyxVoipClient;
 exports.createBackgroundTelnyxVoipClient = createBackgroundTelnyxVoipClient;
 const connection_state_1 = require('./models/connection-state');
 const call_state_1 = require('./models/call-state');
 const config_1 = require('./models/config');
 const session_manager_1 = require('./internal/session/session-manager');
 const call_state_controller_1 = require('./internal/calls/call-state-controller');
+const voice_pn_bridge_1 = require('./internal/voice-pn-bridge');
 /**
  * The main public interface for the react-voice-commons module.
  *
@@ -20,6 +22,26 @@ const call_state_controller_1 = require('./internal/calls/call-state-controller'
  * into their chosen state management solution naturally.
  */
 class TelnyxVoipClient {
+  /**
+   * Check if the app was launched from a push notification.
+   *
+   * Use this to avoid double-login on cold start. When true, the SDK will
+   * handle login internally via the push notification flow, so you should
+   * skip your normal auto-login.
+   *
+   * @returns true if there is pending push notification data indicating a push-launched app
+   */
+  static async isLaunchedFromPushNotification() {
+    try {
+      const pendingAction = await voice_pn_bridge_1.VoicePnBridge.getPendingPushAction();
+      if (pendingAction?.action) return true;
+      const pendingVoipPush = await voice_pn_bridge_1.VoicePnBridge.getPendingVoipPush();
+      if (pendingVoipPush) return true;
+      return false;
+    } catch {
+      return false;
+    }
+  }
   /**
    * Creates a new TelnyxVoipClient instance.
    *
@@ -470,14 +492,38 @@ class TelnyxVoipClient {
 }
 exports.TelnyxVoipClient = TelnyxVoipClient;
 // ========== Factory Functions ==========
+let _sharedInstance = null;
 /**
- * Create a new TelnyxVoipClient instance for normal app usage
+ * Create or retrieve the shared TelnyxVoipClient instance.
+ *
+ * This uses a singleton pattern — calling it multiple times (e.g., inside a
+ * React component body) always returns the same instance.  If you need to
+ * reset the instance, call `destroyTelnyxVoipClient()` first.
  */
 function createTelnyxVoipClient(options) {
-  return new TelnyxVoipClient(options);
+  if (_sharedInstance) {
+    return _sharedInstance;
+  }
+  _sharedInstance = new TelnyxVoipClient(options);
+  return _sharedInstance;
 }
 /**
- * Create a new TelnyxVoipClient instance for background push notification handling
+ * Destroy the shared TelnyxVoipClient instance.
+ *
+ * Disposes the current singleton so that a subsequent call to
+ * `createTelnyxVoipClient()` will create a fresh instance.
+ */
+function destroyTelnyxVoipClient() {
+  if (_sharedInstance) {
+    _sharedInstance.dispose();
+    _sharedInstance = null;
+  }
+}
+/**
+ * Create a new TelnyxVoipClient instance for background push notification handling.
+ *
+ * Unlike `createTelnyxVoipClient`, this always creates a new instance because
+ * background isolates need their own independent client.
  */
 function createBackgroundTelnyxVoipClient(options) {
   return new TelnyxVoipClient(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telnyx/react-voice-commons-sdk",
-  "version": "0.1.7-beta.0",
+  "version": "0.1.7",
   "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

@@ -740,7 +740,10 @@ class CallKitCoordinator {
   }
 
   /**
-   * Set the VoIP client reference for triggering reconnection
+   * Set the VoIP client reference for triggering reconnection.
+   *
+   * @deprecated No longer needed — TelnyxVoiceApp now auto-wires the voipClient
+   * on mount. Kept for backwards compatibility.
    */
   setVoipClient(voipClient: TelnyxVoipClient): void {
     this.voipClient = voipClient;

package/src/hooks/use-callkit-coordinator.ts

@@ -42,6 +42,11 @@ export function useCallKitCoordinator() {
     return callKitCoordinator.isAvailable();
   }, []);
 
+  /**
+   * @deprecated No longer needed — TelnyxVoiceApp now auto-wires the voipClient
+   * on the CallKit coordinator when it receives the voipClient prop.
+   * This method is kept for backwards compatibility and will be removed in a future release.
+   */
   const setVoipClient = useCallback((voipClient: TelnyxVoipClient): void => {
     callKitCoordinator.setVoipClient(voipClient);
   }, []);

package/src/index.ts

@@ -13,6 +13,7 @@
 export {
   TelnyxVoipClient,
   createTelnyxVoipClient,
+  destroyTelnyxVoipClient,
   createBackgroundTelnyxVoipClient,
 } from './telnyx-voip-client';
 export type { TelnyxVoipClientOptions } from './telnyx-voip-client';

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

@@ -494,6 +494,20 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
     return backgroundClient;
   }, [debug, log]);
 
+  // Auto-wire the voipClient on the CallKit coordinator so consumers don't
+  // have to call setVoipClient() manually at the right level.
+  useEffect(() => {
+    if (Platform.OS === 'ios') {
+      try {
+        const { callKitCoordinator } = require('./callkit/callkit-coordinator');
+        callKitCoordinator.setVoipClient(voipClient);
+        log('Auto-wired voipClient on CallKit coordinator');
+      } catch (e) {
+        log('Error auto-wiring voipClient on CallKit coordinator:', e);
+      }
+    }
+  }, [voipClient, log]);
+
   // Setup effect
   useEffect(() => {
     // Listen to connection state changes

package/src/telnyx-voip-client.ts

@@ -5,6 +5,7 @@ import { TelnyxCallState } from './models/call-state';
 import { Config, CredentialConfig, TokenConfig, validateConfig } from './models/config';
 import { SessionManager } from './internal/session/session-manager';
 import { CallStateController } from './internal/calls/call-state-controller';
+import { VoicePnBridge } from './internal/voice-pn-bridge';
 
 /**
  * Configuration options for TelnyxVoipClient
@@ -34,6 +35,29 @@ export class TelnyxVoipClient {
   private readonly _options: Required<TelnyxVoipClientOptions>;
   private _disposed = false;
 
+  /**
+   * Check if the app was launched from a push notification.
+   *
+   * Use this to avoid double-login on cold start. When true, the SDK will
+   * handle login internally via the push notification flow, so you should
+   * skip your normal auto-login.
+   *
+   * @returns true if there is pending push notification data indicating a push-launched app
+   */
+  static async isLaunchedFromPushNotification(): Promise<boolean> {
+    try {
+      const pendingAction = await VoicePnBridge.getPendingPushAction();
+      if (pendingAction?.action) return true;
+
+      const pendingVoipPush = await VoicePnBridge.getPendingVoipPush();
+      if (pendingVoipPush) return true;
+
+      return false;
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * Creates a new TelnyxVoipClient instance.
    *
@@ -565,15 +589,41 @@ export class TelnyxVoipClient {
 
 // ========== Factory Functions ==========
 
+let _sharedInstance: TelnyxVoipClient | null = null;
+
 /**
- * Create a new TelnyxVoipClient instance for normal app usage
+ * Create or retrieve the shared TelnyxVoipClient instance.
+ *
+ * This uses a singleton pattern — calling it multiple times (e.g., inside a
+ * React component body) always returns the same instance.  If you need to
+ * reset the instance, call `destroyTelnyxVoipClient()` first.
  */
 export function createTelnyxVoipClient(options?: TelnyxVoipClientOptions): TelnyxVoipClient {
-  return new TelnyxVoipClient(options);
+  if (_sharedInstance) {
+    return _sharedInstance;
+  }
+  _sharedInstance = new TelnyxVoipClient(options);
+  return _sharedInstance;
 }
 
 /**
- * Create a new TelnyxVoipClient instance for background push notification handling
+ * Destroy the shared TelnyxVoipClient instance.
+ *
+ * Disposes the current singleton so that a subsequent call to
+ * `createTelnyxVoipClient()` will create a fresh instance.
+ */
+export function destroyTelnyxVoipClient(): void {
+  if (_sharedInstance) {
+    _sharedInstance.dispose();
+    _sharedInstance = null;
+  }
+}
+
+/**
+ * Create a new TelnyxVoipClient instance for background push notification handling.
+ *
+ * Unlike `createTelnyxVoipClient`, this always creates a new instance because
+ * background isolates need their own independent client.
  */
 export function createBackgroundTelnyxVoipClient(
   options?: TelnyxVoipClientOptions

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;