@telnyx/react-voice-commons-sdk 1.0.0 → 1.1.1

package/src/callkit/callkit.ts

@@ -11,8 +11,21 @@ interface CallKitBridgeInterface {
     handle: string,
     displayName: string
   ): Promise<{ success: boolean; callUUID: string }>;
+  isCallRegistered(callUUID: string): Promise<{ registered: boolean; callUUID: string }>;
   answerCall(callUUID: string): Promise<{ success: boolean; callUUID: string }>;
   endCall(callUUID: string): Promise<{ success: boolean; callUUID: string }>;
+  completeHeldCallAction(
+    callUUID: string,
+    success: boolean
+  ): Promise<{ success: boolean; callUUID: string }>;
+  setCallHeld(
+    callUUID: string,
+    isOnHold: boolean
+  ): Promise<{ success: boolean; callUUID: string; isOnHold: boolean }>;
+  swapCalls(
+    activeCallUUID: string,
+    heldCallUUID: string
+  ): Promise<{ success: boolean; activeCallUUID: string; heldCallUUID: string }>;
   reportCallConnected(callUUID: string): Promise<{ success: boolean }>;
   reportCallEnded(callUUID: string, reason: number): Promise<{ success: boolean }>;
   updateCall(callUUID: string, displayName: string, handle: string): Promise<{ success: boolean }>;
@@ -31,13 +44,14 @@ export enum CallEndReason {
 // CallKit event types
 export interface CallKitEvent {
   callUUID: string;
+  isOnHold?: boolean;
   [key: string]: any;
 }
 
 class CallKitManager {
   private bridge: CallKitBridgeInterface | null = null;
   private eventEmitter: NativeEventEmitter | null = null;
-  private listeners: Map<string, (event: CallKitEvent) => void> = new Map();
+  private listeners: Map<string, Set<(event: CallKitEvent) => void>> = new Map();
 
   /**
    * Normalize UUID to lowercase for consistent handling in React Native
@@ -100,6 +114,12 @@ class CallKitManager {
       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);
@@ -108,9 +128,11 @@ class CallKitManager {
   }
 
   private notifyListeners(eventType: string, event: CallKitEvent) {
-    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);
+      }
     }
   }
 
@@ -189,6 +211,23 @@ class CallKitManager {
     }
   }
 
+  public async isCallRegistered(callUUID: string): Promise<boolean> {
+    if (!this.bridge || 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;
+    }
+  }
+
   public async endCall(callUUID: string): Promise<boolean> {
     if (!this.bridge || Platform.OS !== 'ios') {
       console.warn('CallKit: Not available on this platform');
@@ -208,6 +247,52 @@ class CallKitManager {
     }
   }
 
+  public async completeHeldCallAction(callUUID: string, success: boolean): Promise<boolean> {
+    if (!this.bridge || 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;
+    }
+  }
+
+  public async setCallHeld(callUUID: string, isOnHold: boolean): Promise<boolean> {
+    if (!this.bridge || 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;
+    }
+  }
+
+  public async swapCalls(activeCallUUID: string, heldCallUUID: string): Promise<boolean> {
+    if (!this.bridge || 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;
+    }
+  }
+
   public async reportCallConnected(callUUID: string): Promise<boolean> {
     if (!this.bridge || Platform.OS !== 'ios') {
       return false;
@@ -283,23 +368,36 @@ class CallKitManager {
   // Event listener management
 
   public onStartCall(listener: (event: CallKitEvent) => void): () => void {
-    this.listeners.set('startCall', listener);
-    return () => this.listeners.delete('startCall');
+    return this.addListener('startCall', listener);
   }
 
   public onAnswerCall(listener: (event: CallKitEvent) => void): () => void {
-    this.listeners.set('answerCall', listener);
-    return () => this.listeners.delete('answerCall');
+    return this.addListener('answerCall', listener);
   }
 
   public onEndCall(listener: (event: CallKitEvent) => void): () => void {
-    this.listeners.set('endCall', listener);
-    return () => this.listeners.delete('endCall');
+    return this.addListener('endCall', listener);
+  }
+
+  public onHeldCall(listener: (event: CallKitEvent) => void): () => void {
+    return this.addListener('heldCall', listener);
   }
 
   public onReceivePush(listener: (event: CallKitEvent) => void): () => void {
-    this.listeners.set('receivePush', listener);
-    return () => this.listeners.delete('receivePush');
+    return this.addListener('receivePush', listener);
+  }
+
+  private addListener(eventType: string, listener: (event: CallKitEvent) => void): () => void {
+    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

package/src/hooks/useAppStateHandler.ts

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

package/src/internal/CallKitHandler.tsx

@@ -1,10 +1,8 @@
 import React, { useEffect, useRef } from 'react';
 import { Platform, DeviceEventEmitter } from 'react-native';
 import AsyncStorage from '@react-native-async-storage/async-storage';
-import { useTelnyxVoice } from '../context/TelnyxVoiceContext';
-import { callKitCoordinator } from '../callkit';
 
-// Global flag to ensure only one CallKitHandler is active
+// Global flag to ensure only one CallKitHandler is active.
 let isCallKitHandlerActive = false;
 
 interface CallData {
@@ -28,6 +26,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 const CallKitHandler: React.FC<CallKitHandlerProps> = ({
@@ -35,11 +36,65 @@ export const CallKitHandler: React.FC<CallKitHandlerProps> = ({
   onNavigateToDialer,
   onNavigateBack,
 }) => {
-  const { voipClient } = useTelnyxVoice();
-
   // Store active calls by CallKit UUID for coordination
   const activeCallsRef = useRef<Map<string, any>>(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 = useRef(onLoginRequired);
+  const onNavigateToDialerRef = useRef(onNavigateToDialer);
+  const onNavigateBackRef = useRef(onNavigateBack);
+
+  onLoginRequiredRef.current = onLoginRequired;
+  onNavigateToDialerRef.current = onNavigateToDialer;
+  onNavigateBackRef.current = onNavigateBack;
+
+  const handleIncomingCall = async (eventData: CallData) => {
+    console.log('CallKitHandler: Handling incoming call', {
+      callUUID: eventData.callUUID,
+    });
+
+    // Store the push notification payload
+    await AsyncStorage.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: CallData) => {
+    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: CallData) => {
+    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 AsyncStorage.removeItem('@push_notification_payload');
+
+    if (onNavigateBackRef.current) {
+      onNavigateBackRef.current();
+    }
+  };
+
   useEffect(() => {
     if (Platform.OS !== 'ios') return;
 
@@ -51,9 +106,6 @@ export const CallKitHandler: React.FC<CallKitHandlerProps> = ({
     isCallKitHandlerActive = true;
     console.log('CallKitHandler: Setting up DeviceEventEmitter listeners (singleton instance)...');
 
-    DeviceEventEmitter.removeAllListeners('incomingVoIPCall');
-    DeviceEventEmitter.removeAllListeners('callKitAction');
-
     const incomingCallListener = DeviceEventEmitter.addListener(
       'incomingVoIPCall',
       async (eventData: CallData) => {
@@ -89,53 +141,6 @@ export const CallKitHandler: React.FC<CallKitHandlerProps> = ({
     };
   }, []);
 
-  const handleIncomingCall = async (eventData: CallData) => {
-    console.log('CallKitHandler: Handling incoming call', {
-      callUUID: eventData.callUUID,
-      hasClient: !!voipClient,
-    });
-
-    // Store the push notification payload
-    await AsyncStorage.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: CallData) => {
-    console.log('CallKitHandler: User answered call via CallKit', {
-      callUUID: eventData.callUUID,
-      isTrackedCall: activeCallsRef.current.has(eventData.callUUID),
-    });
-
-    if (onNavigateToDialer) {
-      onNavigateToDialer();
-    }
-  };
-
-  const handleEndCall = async (eventData: CallData) => {
-    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 AsyncStorage.removeItem('@push_notification_payload');
-
-    if (onNavigateBack) {
-      onNavigateBack();
-    }
-  };
-
   // This component doesn't render anything, it just handles events
   return null;
 };

package/src/internal/calls/call-state-controller.ts

@@ -5,7 +5,9 @@ import { Call } from '../../models/call';
 import { TelnyxCallState } from '../../models/call-state';
 import { SessionManager } from '../session/session-manager';
 import { callKitCoordinator } from '../../callkit/callkit-coordinator';
-import { VoicePnBridge } from '../voice-pn-bridge';
+
+export type CustomHeader = { name: string; value: string };
+export type CustomHeaders = Record<string, string> | CustomHeader[];
 
 /**
  * Central state machine for call management.
@@ -23,6 +25,12 @@ export class CallStateController {
   private _isWaitingForInvite?: () => boolean;
   private _onInviteAutoAccepted?: () => void;
 
+  // Explicitly-tracked active call ID for multi-call scenarios.
+  // When set, activeCall$/currentActiveCall prefer this call over the
+  // first-match heuristic. Cleared automatically when the call reaches
+  // a terminal state, or manually via clearActiveCall().
+  private _activeCallId: string | null = null;
+
   constructor(private readonly _sessionManager: SessionManager) {
     console.log('CallStateController: Constructor called - instance created');
     // Don't set up client listeners here - client doesn't exist yet
@@ -42,18 +50,18 @@ export class CallStateController {
   get activeCall$(): Observable<Call | null> {
     return this.calls$.pipe(
       map((calls) => {
-        // Find the first call that is not terminated (includes RINGING, CONNECTING, ACTIVE, HELD)
-        return (
-          calls.find(
-            (call) =>
-              call.currentState === TelnyxCallState.RINGING ||
-              call.currentState === TelnyxCallState.CONNECTING ||
-              call.currentState === TelnyxCallState.ACTIVE ||
-              call.currentState === TelnyxCallState.HELD
-          ) || null
-        );
+        const call = this._selectActiveCall(calls);
+        return {
+          call,
+          callId: call?.callId ?? null,
+          state: call?.currentState ?? null,
+        };
       }),
-      distinctUntilChanged()
+      distinctUntilChanged(
+        (previous, current) =>
+          previous.callId === current.callId && previous.state === current.state
+      ),
+      map(({ call }) => call)
     );
   }
 
@@ -68,16 +76,7 @@ export class CallStateController {
    * Current active call (synchronous access)
    */
   get currentActiveCall(): Call | null {
-    const calls = this.currentCalls;
-    return (
-      calls.find(
-        (call) =>
-          call.currentState === TelnyxCallState.RINGING ||
-          call.currentState === TelnyxCallState.CONNECTING ||
-          call.currentState === TelnyxCallState.ACTIVE ||
-          call.currentState === TelnyxCallState.HELD
-      ) || null
-    );
+    return this._selectActiveCall(this.currentCalls);
   }
 
   /**
@@ -106,6 +105,34 @@ export class CallStateController {
     }
   }
 
+  /**
+   * 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 {
+    const call = this._callMap.get(callId);
+    if (call) {
+      this._activeCallId = callId;
+      this._calls.next([...this.currentCalls]);
+    } else {
+      console.warn('CallStateController: Cannot set active call - call not found:', callId);
+    }
+  }
+
+  /**
+   * Clear the explicitly-tracked active call ID, reverting to the
+   * first-match heuristic for active call selection.
+   */
+  clearActiveCall(): void {
+    if (this._activeCallId !== null) {
+      this._activeCallId = null;
+      this._calls.next([...this.currentCalls]);
+    }
+  }
+
   /**
    * Find a call by its underlying Telnyx call ID
    * @param telnyxCall The Telnyx call object to find
@@ -119,6 +146,33 @@ export class CallStateController {
     return null;
   }
 
+  /**
+   * Select the active call, preferring the explicitly-tracked call ID
+   * over the first-match heuristic.
+   */
+  private _selectActiveCall(calls: Call[]): Call | null {
+    if (this._activeCallId) {
+      const tracked = calls.find((c) => c.callId === this._activeCallId);
+      if (tracked && this._isNonTerminal(tracked)) {
+        return tracked;
+      }
+    }
+    // Fall back to first non-terminal call (backward compatible)
+    return calls.find((c) => this._isNonTerminal(c)) || null;
+  }
+
+  /**
+   * Check if a call is in a non-terminal (active or connecting) state.
+   */
+  private _isNonTerminal(call: Call): boolean {
+    return (
+      call.currentState === TelnyxCallState.RINGING ||
+      call.currentState === TelnyxCallState.CONNECTING ||
+      call.currentState === TelnyxCallState.ACTIVE ||
+      call.currentState === TelnyxCallState.HELD
+    );
+  }
+
   /**
    * Initialize client listeners when the Telnyx client becomes available
    * This should be called by the session manager after client creation
@@ -139,7 +193,7 @@ export class CallStateController {
     destination: string,
     callerName?: string,
     callerNumber?: string,
-    customHeaders?: Record<string, string>
+    customHeaders?: CustomHeaders
   ): Promise<Call> {
     if (this._disposed) {
       throw new Error('CallStateController has been disposed');
@@ -155,7 +209,7 @@ export class CallStateController {
         destinationNumber: destination,
         callerIdName: callerName,
         callerIdNumber: callerNumber,
-        customHeaders,
+        customHeaders: this._normalizeCustomHeaders(customHeaders),
         peerConnectionOptions: {
           useTrickleIce: this._sessionManager.useTrickleIce,
         },
@@ -183,6 +237,21 @@ export class CallStateController {
     }
   }
 
+  /**
+   * Normalize public custom headers into the format expected by the underlying SDK.
+   */
+  private _normalizeCustomHeaders(customHeaders?: CustomHeaders): CustomHeader[] | undefined {
+    if (!customHeaders) {
+      return undefined;
+    }
+
+    if (Array.isArray(customHeaders)) {
+      return customHeaders;
+    }
+
+    return Object.entries(customHeaders).map(([name, value]) => ({ name, value }));
+  }
+
   /**
    * Set callbacks for waiting for invite logic (used for push notifications)
    */
@@ -217,6 +286,7 @@ export class CallStateController {
       }
     }
     this._callMap.clear();
+    this._activeCallId = null;
     this._calls.next([]);
   }
 
@@ -234,6 +304,7 @@ export class CallStateController {
     // Dispose of all calls
     this.currentCalls.forEach((call) => call.dispose());
     this._callMap.clear();
+    this._activeCallId = null;
 
     // CallKit cleanup is now handled by CallKitCoordinator automatically
 
@@ -415,6 +486,11 @@ export class CallStateController {
   private _addCall(call: Call): void {
     this._callMap.set(call.callId, call);
 
+    // Auto-track as active if no active call is currently set
+    if (this._activeCallId === null) {
+      this._activeCallId = call.callId;
+    }
+
     const currentCalls = this.currentCalls;
     currentCalls.push(call);
     this._calls.next([...currentCalls]);
@@ -429,9 +505,10 @@ export class CallStateController {
 
       if (existingCallKitUUID) {
         console.log(
-          'CallStateController: Call already has CallKit integration, skipping duplicate report:',
+          'CallStateController: Linking push-created CallKit call to its signaling call:',
           existingCallKitUUID
         );
+        callKitCoordinator.linkExistingCallKitCall(telnyxCall, existingCallKitUUID);
       } else if (call.isIncoming) {
         // Handle incoming call with CallKit (only if not already integrated)
         console.log('CallStateController: Reporting incoming call to CallKitCoordinator');
@@ -448,13 +525,19 @@ export class CallStateController {
       // CallKitCoordinator automatically updates CallKit via setupWebRTCCallListeners
       console.log('CallStateController: Call state changed to:', state);
 
+      // Re-emit the call list so calls$/activeCall$ subscribers see state changes.
+      // distinctUntilChanged uses reference equality; without a new array
+      // reference, non-terminal transitions leave activeCall$ stale.
+      this._calls.next([...this.currentCalls]);
+
       // Clean up when call ends - delay to next tick so external subscribers
       // receive the ENDED/FAILED state before the call is disposed
       if (state === TelnyxCallState.ENDED || state === TelnyxCallState.FAILED) {
-        // Clear pending push data so the next app launch isn't mistaken for a push launch
-        VoicePnBridge.clearPendingVoipPush().catch((e) =>
-          console.warn('CallStateController: Failed to clear pending voip push:', e)
-        );
+        // Clear active call ID if the ending call was the tracked active call
+        if (this._activeCallId === call.callId) {
+          this._activeCallId = null;
+        }
+
         setTimeout(() => this._removeCall(call.callId), 0);
       }
     });