@telnyx/react-voice-commons-sdk 0.4.3 → 1.1.0

package/lib/callkit/callkit.d.ts

@@ -7,6 +7,7 @@ export declare enum CallEndReason {
 }
 export interface CallKitEvent {
   callUUID: string;
+  isOnHold?: boolean;
   [key: string]: any;
 }
 declare class CallKitManager {
@@ -33,7 +34,11 @@ declare class CallKitManager {
   startOutgoingCall(callUUID: string, handle: string, displayName: string): Promise<boolean>;
   reportIncomingCall(callUUID: string, handle: string, displayName: string): Promise<boolean>;
   answerCall(callUUID: string): Promise<boolean>;
+  isCallRegistered(callUUID: string): Promise<boolean>;
   endCall(callUUID: string): Promise<boolean>;
+  completeHeldCallAction(callUUID: string, success: boolean): Promise<boolean>;
+  setCallHeld(callUUID: string, isOnHold: boolean): Promise<boolean>;
+  swapCalls(activeCallUUID: string, heldCallUUID: string): Promise<boolean>;
   reportCallConnected(callUUID: string): Promise<boolean>;
   reportCallEnded(callUUID: string, reason?: CallEndReason): Promise<boolean>;
   updateCall(callUUID: string, displayName: string, handle: string): Promise<boolean>;
@@ -41,7 +46,9 @@ declare class CallKitManager {
   onStartCall(listener: (event: CallKitEvent) => void): () => void;
   onAnswerCall(listener: (event: CallKitEvent) => void): () => void;
   onEndCall(listener: (event: CallKitEvent) => void): () => void;
+  onHeldCall(listener: (event: CallKitEvent) => void): () => void;
   onReceivePush(listener: (event: CallKitEvent) => void): () => void;
+  private addListener;
   generateCallUUID(): string;
   isAvailable(): boolean;
 }

package/lib/callkit/callkit.js

@@ -68,6 +68,11 @@ class CallKitManager {
       console.log('CallKit: Received end call action', normalizedEvent);
       this.notifyListeners('endCall', normalizedEvent);
     });
+    this.eventEmitter.addListener('CallKitDidPerformHeldCallAction', (event) => {
+      const normalizedEvent = this.normalizeEvent(event);
+      console.log('CallKit: Received held call action', normalizedEvent);
+      this.notifyListeners('heldCall', normalizedEvent);
+    });
     this.eventEmitter.addListener('CallKitDidReceivePush', (event) => {
       const normalizedEvent = this.normalizeEvent(event);
       console.log('CallKit: Received push notification event', normalizedEvent);
@@ -75,9 +80,11 @@ class CallKitManager {
     });
   }
   notifyListeners(eventType, event) {
-    const listener = this.listeners.get(eventType);
-    if (listener) {
-      listener(event);
+    const listeners = this.listeners.get(eventType);
+    if (listeners) {
+      for (const listener of listeners) {
+        listener(event);
+      }
     }
   }
   // Public API methods
@@ -140,6 +147,21 @@ class CallKitManager {
       return false;
     }
   }
+  async isCallRegistered(callUUID) {
+    if (!this.bridge || react_native_1.Platform.OS !== 'ios') {
+      return false;
+    }
+    try {
+      const result = await this.bridge.isCallRegistered(this.denormalizeUUID(callUUID));
+      return result.registered;
+    } catch (error) {
+      console.error('CallKit: Failed to check incoming call registration', {
+        callUUID,
+        error,
+      });
+      return false;
+    }
+  }
   async endCall(callUUID) {
     if (!this.bridge || react_native_1.Platform.OS !== 'ios') {
       console.warn('CallKit: Not available on this platform');
@@ -157,6 +179,46 @@ class CallKitManager {
       return false;
     }
   }
+  async completeHeldCallAction(callUUID, success) {
+    if (!this.bridge || react_native_1.Platform.OS !== 'ios') {
+      return false;
+    }
+    try {
+      const uppercaseUUID = this.denormalizeUUID(callUUID);
+      const result = await this.bridge.completeHeldCallAction(uppercaseUUID, success);
+      return result.success;
+    } catch (error) {
+      console.error('CallKit: Failed to complete held call action', error);
+      return false;
+    }
+  }
+  async setCallHeld(callUUID, isOnHold) {
+    if (!this.bridge || react_native_1.Platform.OS !== 'ios') {
+      return false;
+    }
+    try {
+      const result = await this.bridge.setCallHeld(this.denormalizeUUID(callUUID), isOnHold);
+      return result.success;
+    } catch (error) {
+      console.error('CallKit: Failed to change held state', { callUUID, isOnHold, error });
+      return false;
+    }
+  }
+  async swapCalls(activeCallUUID, heldCallUUID) {
+    if (!this.bridge || react_native_1.Platform.OS !== 'ios') {
+      return false;
+    }
+    try {
+      const result = await this.bridge.swapCalls(
+        this.denormalizeUUID(activeCallUUID),
+        this.denormalizeUUID(heldCallUUID)
+      );
+      return result.success;
+    } catch (error) {
+      console.error('CallKit: Failed to swap calls', error);
+      return false;
+    }
+  }
   async reportCallConnected(callUUID) {
     if (!this.bridge || react_native_1.Platform.OS !== 'ios') {
       return false;
@@ -220,20 +282,30 @@ class CallKitManager {
   }
   // Event listener management
   onStartCall(listener) {
-    this.listeners.set('startCall', listener);
-    return () => this.listeners.delete('startCall');
+    return this.addListener('startCall', listener);
   }
   onAnswerCall(listener) {
-    this.listeners.set('answerCall', listener);
-    return () => this.listeners.delete('answerCall');
+    return this.addListener('answerCall', listener);
   }
   onEndCall(listener) {
-    this.listeners.set('endCall', listener);
-    return () => this.listeners.delete('endCall');
+    return this.addListener('endCall', listener);
+  }
+  onHeldCall(listener) {
+    return this.addListener('heldCall', listener);
   }
   onReceivePush(listener) {
-    this.listeners.set('receivePush', listener);
-    return () => this.listeners.delete('receivePush');
+    return this.addListener('receivePush', listener);
+  }
+  addListener(eventType, listener) {
+    const listeners = this.listeners.get(eventType) ?? new Set();
+    listeners.add(listener);
+    this.listeners.set(eventType, listeners);
+    return () => {
+      listeners.delete(listener);
+      if (listeners.size === 0) {
+        this.listeners.delete(eventType);
+      }
+    };
   }
   // Utility methods
   generateCallUUID() {

package/lib/hooks/useAppStateHandler.js

@@ -30,8 +30,12 @@ const useAppStateHandler = ({
       if (appState.current.match(/active/) && nextAppState === 'background') {
         log('AppStateHandler: App went to background, checking for active calls...');
         const connectionState = voipClient.currentConnectionState;
-        if (connectionState !== connection_state_1.TelnyxConnectionState.CONNECTED) {
-          log('AppStateHandler: Not connected, skipping background handling');
+        const shouldHandleBackgroundConnection =
+          connectionState === connection_state_1.TelnyxConnectionState.CONNECTED ||
+          connectionState === connection_state_1.TelnyxConnectionState.CONNECTING ||
+          connectionState === connection_state_1.TelnyxConnectionState.RECONNECTING;
+        if (!shouldHandleBackgroundConnection) {
+          log('AppStateHandler: Not connected or connecting, skipping background handling');
           appState.current = nextAppState;
           return;
         }

package/lib/index.d.ts

@@ -41,4 +41,5 @@ export {
 export type { Config, CredentialConfig, TokenConfig } from './models/config';
 export type { Call as TelnyxCall } from '@telnyx/react-native-voice-sdk';
 export * from './callkit';
+export { VoicePnBridge } from './internal/voice-pn-bridge';
 export { useAppReadyNotifier } from './hooks/useAppReadyNotifier';

package/lib/index.js

@@ -38,6 +38,7 @@ var __exportStar =
   };
 Object.defineProperty(exports, '__esModule', { value: true });
 exports.useAppReadyNotifier =
+  exports.VoicePnBridge =
   exports.createTokenConfig =
   exports.createCredentialConfig =
   exports.validateTokenConfig =
@@ -215,6 +216,14 @@ Object.defineProperty(exports, 'createTokenConfig', {
 });
 // Export CallKit functionality
 __exportStar(require('./callkit'), exports);
+// Native push notification helpers
+var voice_pn_bridge_1 = require('./internal/voice-pn-bridge');
+Object.defineProperty(exports, 'VoicePnBridge', {
+  enumerable: true,
+  get: function () {
+    return voice_pn_bridge_1.VoicePnBridge;
+  },
+});
 // Export hooks
 var useAppReadyNotifier_1 = require('./hooks/useAppReadyNotifier');
 Object.defineProperty(exports, 'useAppReadyNotifier', {

package/lib/internal/CallKitHandler.d.ts

@@ -11,6 +11,9 @@ interface CallKitHandlerProps {
  * Internal CallKit handler for iOS push notifications
  * This component is automatically included in TelnyxVoiceApp
  *
+ * The active instance removes only its own DeviceEventEmitter subscriptions on
+ * unmount via each listener's `.remove()` method.
+ *
  * @internal - Users should not use this component directly
  */
 export declare const CallKitHandler: React.FC<CallKitHandlerProps>;

package/lib/internal/CallKitHandler.js

@@ -9,19 +9,68 @@ exports.CallKitHandler = void 0;
 const react_1 = require('react');
 const react_native_1 = require('react-native');
 const async_storage_1 = __importDefault(require('@react-native-async-storage/async-storage'));
-const TelnyxVoiceContext_1 = require('../context/TelnyxVoiceContext');
-// Global flag to ensure only one CallKitHandler is active
+// Global flag to ensure only one CallKitHandler is active.
 let isCallKitHandlerActive = false;
 /**
  * Internal CallKit handler for iOS push notifications
  * This component is automatically included in TelnyxVoiceApp
  *
+ * The active instance removes only its own DeviceEventEmitter subscriptions on
+ * unmount via each listener's `.remove()` method.
+ *
  * @internal - Users should not use this component directly
  */
 const CallKitHandler = ({ onLoginRequired, onNavigateToDialer, onNavigateBack }) => {
-  const { voipClient } = (0, TelnyxVoiceContext_1.useTelnyxVoice)();
   // Store active calls by CallKit UUID for coordination
   const activeCallsRef = (0, react_1.useRef)(new Map());
+  // DeviceEventEmitter listeners are registered once below, so read callbacks
+  // from refs that are updated during every render rather than stale closures.
+  const onLoginRequiredRef = (0, react_1.useRef)(onLoginRequired);
+  const onNavigateToDialerRef = (0, react_1.useRef)(onNavigateToDialer);
+  const onNavigateBackRef = (0, react_1.useRef)(onNavigateBack);
+  onLoginRequiredRef.current = onLoginRequired;
+  onNavigateToDialerRef.current = onNavigateToDialer;
+  onNavigateBackRef.current = onNavigateBack;
+  const handleIncomingCall = async (eventData) => {
+    console.log('CallKitHandler: Handling incoming call', {
+      callUUID: eventData.callUUID,
+    });
+    // Store the push notification payload
+    await async_storage_1.default.setItem(
+      '@push_notification_payload',
+      JSON.stringify(eventData.payload)
+    );
+    // Mark this call as being processed
+    activeCallsRef.current.set(eventData.callUUID, {
+      processing: true,
+      timestamp: Date.now(),
+    });
+    // Trigger login required callback if provided
+    if (onLoginRequiredRef.current) {
+      onLoginRequiredRef.current(eventData.payload);
+    }
+  };
+  const handleAnswerCall = async (eventData) => {
+    console.log('CallKitHandler: User answered call via CallKit', {
+      callUUID: eventData.callUUID,
+      isTrackedCall: activeCallsRef.current.has(eventData.callUUID),
+    });
+    if (onNavigateToDialerRef.current) {
+      onNavigateToDialerRef.current();
+    }
+  };
+  const handleEndCall = async (eventData) => {
+    console.log('CallKitHandler: User ended call via CallKit', {
+      callUUID: eventData.callUUID,
+      isTrackedCall: activeCallsRef.current.has(eventData.callUUID),
+    });
+    // Clean up our local tracking info
+    activeCallsRef.current.delete(eventData.callUUID);
+    await async_storage_1.default.removeItem('@push_notification_payload');
+    if (onNavigateBackRef.current) {
+      onNavigateBackRef.current();
+    }
+  };
   (0, react_1.useEffect)(() => {
     if (react_native_1.Platform.OS !== 'ios') return;
     if (isCallKitHandlerActive) {
@@ -30,8 +79,6 @@ const CallKitHandler = ({ onLoginRequired, onNavigateToDialer, onNavigateBack })
     }
     isCallKitHandlerActive = true;
     console.log('CallKitHandler: Setting up DeviceEventEmitter listeners (singleton instance)...');
-    react_native_1.DeviceEventEmitter.removeAllListeners('incomingVoIPCall');
-    react_native_1.DeviceEventEmitter.removeAllListeners('callKitAction');
     const incomingCallListener = react_native_1.DeviceEventEmitter.addListener(
       'incomingVoIPCall',
       async (eventData) => {
@@ -63,47 +110,6 @@ const CallKitHandler = ({ onLoginRequired, onNavigateToDialer, onNavigateBack })
       isCallKitHandlerActive = false;
     };
   }, []);
-  const handleIncomingCall = async (eventData) => {
-    console.log('CallKitHandler: Handling incoming call', {
-      callUUID: eventData.callUUID,
-      hasClient: !!voipClient,
-    });
-    // Store the push notification payload
-    await async_storage_1.default.setItem(
-      '@push_notification_payload',
-      JSON.stringify(eventData.payload)
-    );
-    // Mark this call as being processed
-    activeCallsRef.current.set(eventData.callUUID, {
-      processing: true,
-      timestamp: Date.now(),
-    });
-    // Trigger login required callback if provided
-    if (onLoginRequired) {
-      onLoginRequired(eventData.payload);
-    }
-  };
-  const handleAnswerCall = async (eventData) => {
-    console.log('CallKitHandler: User answered call via CallKit', {
-      callUUID: eventData.callUUID,
-      isTrackedCall: activeCallsRef.current.has(eventData.callUUID),
-    });
-    if (onNavigateToDialer) {
-      onNavigateToDialer();
-    }
-  };
-  const handleEndCall = async (eventData) => {
-    console.log('CallKitHandler: User ended call via CallKit', {
-      callUUID: eventData.callUUID,
-      isTrackedCall: activeCallsRef.current.has(eventData.callUUID),
-    });
-    // Clean up our local tracking info
-    activeCallsRef.current.delete(eventData.callUUID);
-    await async_storage_1.default.removeItem('@push_notification_payload');
-    if (onNavigateBack) {
-      onNavigateBack();
-    }
-  };
   // This component doesn't render anything, it just handles events
   return null;
 };

package/lib/internal/calls/call-state-controller.d.ts

@@ -1,6 +1,11 @@
 import { Observable } from 'rxjs';
 import { Call } from '../../models/call';
 import { SessionManager } from '../session/session-manager';
+export type CustomHeader = {
+  name: string;
+  value: string;
+};
+export type CustomHeaders = Record<string, string> | CustomHeader[];
 /**
  * Central state machine for call management.
  *
@@ -12,8 +17,10 @@ export declare class CallStateController {
   private readonly _calls;
   private readonly _callMap;
   private _disposed;
+  private _listenerClient?;
   private _isWaitingForInvite?;
   private _onInviteAutoAccepted?;
+  private _activeCallId;
   constructor(_sessionManager: SessionManager);
   /**
    * Observable stream of all current calls
@@ -45,11 +52,33 @@ export declare class CallStateController {
    * @param callId The ID of the call to set to connecting state
    */
   setCallConnecting(callId: string): void;
+  /**
+   * Explicitly set the active call for multi-call scenarios.
+   * When set, activeCall$ and currentActiveCall prefer this call over
+   * the first-match heuristic. The ID is cleared automatically when the
+   * call reaches a terminal state.
+   * @param callId The ID of the call to mark as active
+   */
+  setActiveCall(callId: string): void;
+  /**
+   * Clear the explicitly-tracked active call ID, reverting to the
+   * first-match heuristic for active call selection.
+   */
+  clearActiveCall(): void;
   /**
    * Find a call by its underlying Telnyx call ID
    * @param telnyxCall The Telnyx call object to find
    */
   findCallByTelnyxCall(telnyxCall: any): Call | null;
+  /**
+   * Select the active call, preferring the explicitly-tracked call ID
+   * over the first-match heuristic.
+   */
+  private _selectActiveCall;
+  /**
+   * Check if a call is in a non-terminal (active or connecting) state.
+   */
+  private _isNonTerminal;
   /**
    * Initialize client listeners when the Telnyx client becomes available
    * This should be called by the session manager after client creation
@@ -62,8 +91,12 @@ export declare class CallStateController {
     destination: string,
     callerName?: string,
     callerNumber?: string,
-    customHeaders?: Record<string, string>
+    customHeaders?: CustomHeaders
   ): Promise<Call>;
+  /**
+   * Normalize public custom headers into the format expected by the underlying SDK.
+   */
+  private _normalizeCustomHeaders;
   /**
    * Set callbacks for waiting for invite logic (used for push notifications)
    */
@@ -86,6 +119,11 @@ export declare class CallStateController {
    * Set up event listeners for the Telnyx client
    */
   private _setupClientListeners;
+  private _removeClientListeners;
+  private _handleTelnyxIncomingCall;
+  private _handleTelnyxReattachedCall;
+  private _handleTelnyxCallStateChanged;
+  private _handleTelnyxCallRemoved;
   /**
    * Handle incoming call or reattached call
    */