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

package/lib/telnyx-voice-app.js

@@ -194,6 +194,98 @@ const TelnyxVoiceAppComponent = ({
       log('Auto-reconnection error - redirecting to login screen');
     }
   }, [voipClient, log]);
+  // Retrieve pending push data from the Android native bridge
+  const getAndroidPushData = async () => {
+    try {
+      const { NativeModules } = require('react-native');
+      const VoicePnBridge = NativeModules.VoicePnBridge;
+      if (!VoicePnBridge) {
+        log('VoicePnBridge not available on Android');
+        return { pushData: null, earlyReturn: false };
+      }
+      log('Checking for pending push actions via VoicePnBridge');
+      // Check for pending call actions (notification button taps like hangup/answer)
+      const pendingCallAction = await VoicePnBridge.getPendingCallAction();
+      log('Raw pending call action response:', pendingCallAction);
+      if (pendingCallAction?.action === 'hangup' && pendingCallAction.callId) {
+        log('Processing hangup action from notification for call:', pendingCallAction.callId);
+        const activeCall = voipClient.currentActiveCall;
+        if (activeCall && activeCall.callId === pendingCallAction.callId) {
+          log('Hanging up active call from notification action');
+          try {
+            await activeCall.hangup();
+            log('Call hung up successfully from notification action');
+          } catch (error) {
+            log('Error hanging up call from notification action:', error);
+          }
+        } else {
+          log('No matching active call found for hangup action');
+        }
+        await VoicePnBridge.clearPendingCallAction();
+        return { pushData: null, earlyReturn: true };
+      }
+      // Check for regular push notification data
+      const pendingAction = await VoicePnBridge.getPendingPushAction();
+      log('Raw pending action response:', pendingAction);
+      if (pendingAction?.action != null && pendingAction?.metadata != null) {
+        log('Found pending push action:', pendingAction);
+        let metadata = pendingAction.metadata;
+        try {
+          metadata = JSON.parse(metadata);
+          log('Parsed metadata as JSON:', metadata);
+        } catch (e) {
+          log('JSON parse failed, trying Android key-value format');
+        }
+        await VoicePnBridge.clearPendingPushAction();
+        log('Cleared pending push action after retrieval');
+        return {
+          pushData: { action: pendingAction.action, metadata, from_notification: true },
+          earlyReturn: false,
+        };
+      }
+      log('No pending push actions found');
+      return { pushData: null, earlyReturn: false };
+    } catch (bridgeError) {
+      log('Error accessing VoicePnBridge on Android:', bridgeError);
+      return { pushData: null, earlyReturn: false };
+    }
+  };
+  // Retrieve pending push data from the iOS native bridge
+  const getIOSPushData = async () => {
+    try {
+      const { NativeModules } = require('react-native');
+      const VoicePnBridge = NativeModules.VoicePnBridge;
+      if (!VoicePnBridge) {
+        log('VoicePnBridge not available on iOS');
+        return null;
+      }
+      log('Checking for pending VoIP push data via iOS VoicePnBridge');
+      const pendingVoipPushJson = await VoicePnBridge.getPendingVoipPush();
+      log('Raw pending VoIP push response:', pendingVoipPushJson);
+      if (!pendingVoipPushJson) {
+        log('No pending VoIP push data found');
+        return null;
+      }
+      try {
+        const pendingVoipPush = JSON.parse(pendingVoipPushJson);
+        const voipPayload = pendingVoipPush?.payload;
+        if (!voipPayload?.metadata) {
+          log('Invalid VoIP push data structure');
+          return null;
+        }
+        log('Found pending VoIP push data:', voipPayload);
+        await VoicePnBridge.clearPendingVoipPush();
+        log('Cleared pending VoIP push data after retrieval');
+        return { action: 'incoming_call', metadata: voipPayload.metadata, from_notification: true };
+      } catch (parseError) {
+        log('Error parsing VoIP push JSON:', parseError);
+        return null;
+      }
+    } catch (bridgeError) {
+      log('Error accessing VoicePnBridge on iOS:', bridgeError);
+      return null;
+    }
+  };
   // Check for initial push notification action when app launches
   const checkForInitialPushNotification = (0, react_1.useCallback)(
     async (fromAppResume = false) => {
@@ -202,178 +294,62 @@ const TelnyxVoiceAppComponent = ({
         log('Already processing push, returning early');
         return;
       }
-      // Only set the flag if this is not from app resume to allow resume processing
       if (!fromAppResume) {
         setProcessingPushOnLaunch(true);
       }
       onPushNotificationProcessingStarted?.();
       try {
+        // Retrieve pending push data from the native layer
         let pushData = null;
-        // Try to get push data from the native layer using platform-specific methods
         if (react_native_1.Platform.OS === 'android') {
-          try {
-            // Import the native bridge module dynamically
-            const { NativeModules } = require('react-native');
-            const VoicePnBridge = NativeModules.VoicePnBridge;
-            if (VoicePnBridge) {
-              log('Checking for pending push actions via VoicePnBridge');
-              // First check for pending call actions (notification button taps like hangup/answer)
-              const pendingCallAction = await VoicePnBridge.getPendingCallAction();
-              log('Raw pending call action response:', pendingCallAction);
-              if (pendingCallAction && pendingCallAction.action != null) {
-                log('Found pending call action:', pendingCallAction);
-                // Handle call actions directly
-                if (pendingCallAction.action === 'hangup' && pendingCallAction.callId) {
-                  log(
-                    'Processing hangup action from notification for call:',
-                    pendingCallAction.callId
-                  );
-                  // Find and hangup the call
-                  const activeCall = voipClient.currentActiveCall;
-                  if (activeCall && activeCall.callId === pendingCallAction.callId) {
-                    log('Hanging up active call from notification action');
-                    try {
-                      await activeCall.hangup();
-                      log('Call hung up successfully from notification action');
-                    } catch (error) {
-                      log('Error hanging up call from notification action:', error);
-                    }
-                  } else {
-                    log('No matching active call found for hangup action');
-                  }
-                  // Clear the pending action
-                  await VoicePnBridge.clearPendingCallAction();
-                  return; // Don't process as push data
-                }
-              }
-              // Then check for regular push notification data
-              const pendingAction = await VoicePnBridge.getPendingPushAction();
-              log('Raw pending action response:', pendingAction);
-              if (pendingAction && pendingAction.action != null && pendingAction.metadata != null) {
-                log('Found pending push action:', pendingAction);
-                // Parse the metadata if it's a string
-                let metadata = pendingAction.metadata;
-                try {
-                  // First try parsing as JSON
-                  metadata = JSON.parse(metadata);
-                  log('Parsed metadata as JSON:', metadata);
-                } catch (e) {
-                  log('JSON parse failed, trying Android key-value format');
-                }
-                // Create push data structure that matches what the VoIP client expects
-                pushData = {
-                  action: pendingAction.action,
-                  metadata: metadata,
-                  from_notification: true,
-                };
-                // Clear the pending action so it doesn't get processed again
-                await VoicePnBridge.clearPendingPushAction();
-                log('Cleared pending push action after retrieval');
-              } else {
-                log('No pending push actions found');
-              }
-            } else {
-              log('VoicePnBridge not available on Android');
-            }
-          } catch (bridgeError) {
-            log('Error accessing VoicePnBridge on Android:', bridgeError);
-          }
+          const result = await getAndroidPushData();
+          if (result.earlyReturn) return;
+          pushData = result.pushData;
         } else if (react_native_1.Platform.OS === 'ios') {
-          try {
-            // Import the native bridge module dynamically (same as Android)
-            const { NativeModules } = require('react-native');
-            const VoicePnBridge = NativeModules.VoicePnBridge;
-            if (VoicePnBridge) {
-              log('Checking for pending VoIP push data via iOS VoicePnBridge');
-              // Check for VoIP push notification data stored by the native push handler
-              const pendingVoipPushJson = await VoicePnBridge.getPendingVoipPush();
-              log('Raw pending VoIP push response:', pendingVoipPushJson);
-              if (pendingVoipPushJson) {
-                try {
-                  const pendingVoipPush = JSON.parse(pendingVoipPushJson);
-                  const voipPayload = pendingVoipPush?.payload;
-                  if (voipPayload && voipPayload.metadata) {
-                    log('Found pending VoIP push data:', voipPayload);
-                    // Create push data structure that matches what the VoIP client expects
-                    pushData = {
-                      action: 'incoming_call',
-                      metadata: voipPayload.metadata,
-                      from_notification: true,
-                    };
-                    // Clear the pending VoIP push data so it doesn't get processed again
-                    await VoicePnBridge.clearPendingVoipPush();
-                    log('Cleared pending VoIP push data after retrieval');
-                  } else {
-                    log('Invalid VoIP push data structure');
-                  }
-                } catch (parseError) {
-                  log('Error parsing VoIP push JSON:', parseError);
-                }
-              } else {
-                log('No pending VoIP push data found');
-              }
-            } else {
-              log('VoicePnBridge not available on iOS');
-            }
-          } catch (bridgeError) {
-            log('Error accessing VoicePnBridge on iOS:', bridgeError);
-          }
+          pushData = await getIOSPushData();
         } else {
           log('Push data check skipped - unsupported platform');
         }
-        // Process the push notification if found
-        if (pushData) {
-          log('Processing initial push notification...');
-          // Check if we're already connected and handling a push - prevent duplicate processing
-          const isConnected =
-            voipClient.currentConnectionState ===
-            connection_state_1.TelnyxConnectionState.CONNECTED;
-          if (isConnected) {
-            log('SKIPPING - Already connected, preventing duplicate processing');
-            // Clear the stored data since we're already handling it
-            // TODO: Implement clearPushMetaData
-            return;
-          }
-          // Set flags to prevent auto-reconnection during push call
-          setIsHandlingForegroundCall(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()}`);
-          // Dispose any existing background client to prevent conflicts
-          disposeBackgroundClient();
-          // Handle the push notification using platform-specific approach
-          if (react_native_1.Platform.OS === 'ios') {
-            // On iOS, coordinate with CallKit by notifying the coordinator about the push
+        if (!pushData) {
+          log('No initial push data found');
+          return;
+        }
+        log('Processing initial push notification...');
+        // Prevent duplicate processing if already connected
+        if (
+          voipClient.currentConnectionState === connection_state_1.TelnyxConnectionState.CONNECTED
+        ) {
+          log('SKIPPING - Already connected, preventing duplicate processing');
+          return;
+        }
+        // Set flags to prevent auto-reconnection during push call
+        setIsHandlingForegroundCall(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();
+        // 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');
-            // Extract call_id from nested metadata structure to use as CallKit UUID
-            const callId = pushData.metadata?.metadata?.call_id;
-            if (callId) {
-              log('Notifying CallKit coordinator about push notification:', callId);
-              await callKitCoordinator.handleCallKitPushReceived(callId, {
-                callData: { source: 'push_notification' },
-                pushData: pushData,
-              });
-            } else {
-              log('No call_id found in push data, falling back to direct handling');
-              await voipClient.handlePushNotification(pushData);
-            }
+            log('Notifying CallKit coordinator about push notification:', callId);
+            await callKitCoordinator.handleCallKitPushReceived(callId, {
+              callData: { source: 'push_notification' },
+              pushData: pushData,
+            });
           } else {
-            // On other platforms, handle push notification directly
+            log('No call_id found in push data, falling back to direct handling');
             await voipClient.handlePushNotification(pushData);
           }
-          log('Initial push notification processed');
-          log('Cleared stored push data to prevent duplicate processing');
-          // Note: isHandlingForegroundCall will be reset when calls.length becomes 0
-          // This prevents premature disconnection during CallKit answer flow
         } else {
-          log('No initial push data found');
+          await voipClient.handlePushNotification(pushData);
         }
+        log('Initial push notification processed');
       } catch (e) {
         log('Error processing initial push notification:', e);
-        // Reset flags on error
         setIsHandlingForegroundCall(false);
       } finally {
-        // Always reset the processing flag - it should not remain stuck
         setProcessingPushOnLaunch(false);
         onPushNotificationProcessingCompleted?.();
       }
@@ -402,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.
    *
@@ -69,6 +79,27 @@ export declare class TelnyxVoipClient {
    * Current active call (synchronous access).
    */
   get currentActiveCall(): Call | null;
+  /**
+   * Check if there are any active calls (not in ENDED or FAILED state).
+   * Matches TelnyxRTC `hasActiveCalls` property for multi-call support.
+   */
+  get hasActiveCalls(): boolean;
+  /**
+   * Access any active call tracked by the client.
+   * A call will be accessible until it has ended (transitioned to the ENDED state).
+   * This matches the TelnyxRTC `getCall(callId)` method for multi-call support.
+   *
+   * @param callId The unique identifier of a call.
+   * @returns The Call object that matches the requested callId, or null if not found.
+   * @example
+   * ```typescript
+   * const call = voipClient.getCall('some-call-uuid');
+   * if (call) {
+   *   console.log('Call state:', call.currentState);
+   * }
+   * ```
+   */
+  getCall(callId: string): Call | null;
   /**
    * Current session ID (UUID) for this connection.
    */
@@ -192,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,11 +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.
  *
@@ -19,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.
    *
@@ -97,6 +120,35 @@ class TelnyxVoipClient {
   get currentActiveCall() {
     return this._callStateController.currentActiveCall;
   }
+  /**
+   * Check if there are any active calls (not in ENDED or FAILED state).
+   * Matches TelnyxRTC `hasActiveCalls` property for multi-call support.
+   */
+  get hasActiveCalls() {
+    return this.currentCalls.some(
+      (call) =>
+        call.currentState !== call_state_1.TelnyxCallState.ENDED &&
+        call.currentState !== call_state_1.TelnyxCallState.FAILED
+    );
+  }
+  /**
+   * Access any active call tracked by the client.
+   * A call will be accessible until it has ended (transitioned to the ENDED state).
+   * This matches the TelnyxRTC `getCall(callId)` method for multi-call support.
+   *
+   * @param callId The unique identifier of a call.
+   * @returns The Call object that matches the requested callId, or null if not found.
+   * @example
+   * ```typescript
+   * const call = voipClient.getCall('some-call-uuid');
+   * if (call) {
+   *   console.log('Call state:', call.currentState);
+   * }
+   * ```
+   */
+  getCall(callId) {
+    return this._callStateController.getCall(callId);
+  }
   /**
    * Current session ID (UUID) for this connection.
    */
@@ -440,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.6",
+  "version": "0.1.7-beta.1",
   "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",
@@ -17,7 +17,8 @@
   "files": [
     "lib",
     "src",
-    "android",
+    "android/src",
+    "android/build.gradle",
     "ios",
     "TelnyxVoiceCommons.podspec",
     "README.md",
@@ -25,6 +26,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "postbuild": "prettier --write --ignore-path /dev/null \"lib/**/*.{js,ts}\"",
     "dev": "tsc --watch",
     "test": "jest",
     "test:watch": "jest --watch",

package/src/callkit/callkit-coordinator.ts

@@ -326,6 +326,14 @@ class CallKitCoordinator {
       return;
     }
 
+    if (this.endedCalls.has(callKitUUID)) {
+      console.log('CallKitCoordinator: Call already ended, skipping duplicate end action');
+      return;
+    }
+
+    // Mark as ended immediately to prevent any duplicate processing
+    this.endedCalls.add(callKitUUID);
+
     const call = this.callMap.get(callKitUUID);
 
     if (!call) {
@@ -648,9 +656,7 @@ class CallKitCoordinator {
    * Clean up call mappings and listeners
    */
   private cleanupCall(callKitUUID: string) {
-    // Remove from all tracking sets
     this.processingCalls.delete(callKitUUID);
-    this.endedCalls.delete(callKitUUID);
     this.connectedCalls.delete(callKitUUID);
 
     // Get the call before removing it
@@ -734,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';