@telnyx/react-voice-commons-sdk 0.1.2 → 0.1.3

package/src/internal/voice-pn-bridge.ts

@@ -1,4 +1,10 @@
-import { NativeModules } from 'react-native';
+import { NativeModules, DeviceEventEmitter, EmitterSubscription } from 'react-native';
+
+export interface CallActionEvent {
+  action: string;
+  callId?: string;
+  timestamp: number;
+}
 
 export interface VoicePnBridgeInterface {
   getPendingPushAction(): Promise<{
@@ -7,6 +13,25 @@ export interface VoicePnBridgeInterface {
   }>;
   setPendingPushAction(action: string, metadata: string): Promise<boolean>;
   clearPendingPushAction(): Promise<boolean>;
+
+  // Call action methods (reliable @ReactMethod pattern)
+  getPendingCallAction(): Promise<{
+    action: string | null;
+    callId: string | null;
+    timestamp: number | null;
+  }>;
+  clearPendingCallAction(): Promise<boolean>;
+
+  // Call control methods (Android specific)
+  endCall(callId: string | null): Promise<boolean>;
+  showOngoingCallNotification(
+    callerName: string | null,
+    callerNumber: string | null,
+    callId: string | null
+  ): Promise<boolean>;
+  hideOngoingCallNotification(): Promise<boolean>;
+  hideIncomingCallNotification(): Promise<boolean>;
+
   // Additional UserDefaults methods
   getVoipToken(): Promise<string | null>;
   getPendingVoipPush(): Promise<string | null>;
@@ -15,4 +40,227 @@ export interface VoicePnBridgeInterface {
   clearPendingVoipAction(): Promise<boolean>;
 }
 
-export const VoicePnBridge: VoicePnBridgeInterface = NativeModules.VoicePnBridge;
+const NativeBridge: VoicePnBridgeInterface = NativeModules.VoicePnBridge;
+
+/**
+ * Enhanced VoicePnBridge with call control and event handling capabilities
+ */
+export class VoicePnBridge {
+  /**
+   * Get any pending push notification action from native side
+   */
+  static async getPendingPushAction(): Promise<{ action?: string; metadata?: string }> {
+    try {
+      const result = await NativeBridge.getPendingPushAction();
+      return {
+        action: result?.action || undefined,
+        metadata: result?.metadata || undefined,
+      };
+    } catch (error) {
+      console.error('VoicePnBridge: Error getting pending push action:', error);
+      return {};
+    }
+  }
+
+  /**
+   * Set a pending push notification action to native side
+   */
+  static async setPendingPushAction(action: string, metadata: string): Promise<boolean> {
+    try {
+      return await NativeBridge.setPendingPushAction(action, metadata);
+    } catch (error) {
+      console.error('VoicePnBridge: Error setting pending push action:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Get any pending call action from native side (reliable polling pattern)
+   */
+  static async getPendingCallAction(): Promise<{
+    action?: string;
+    callId?: string;
+    timestamp?: number;
+  }> {
+    try {
+      const result = await NativeBridge.getPendingCallAction();
+      return {
+        action: result?.action || undefined,
+        callId: result?.callId || undefined,
+        timestamp: result?.timestamp || undefined,
+      };
+    } catch (error) {
+      console.error('VoicePnBridge: Error getting pending call action:', error);
+      return {};
+    }
+  }
+
+  /**
+   * Clear any pending call action
+   */
+  static async clearPendingCallAction(): Promise<boolean> {
+    try {
+      return await NativeBridge.clearPendingCallAction();
+    } catch (error) {
+      console.error('VoicePnBridge: Error clearing pending call action:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Clear any pending push notification action
+   */
+  static async clearPendingPushAction(): Promise<boolean> {
+    try {
+      return await NativeBridge.clearPendingPushAction();
+    } catch (error) {
+      console.error('VoicePnBridge: Error clearing pending push action:', error);
+      return false;
+    }
+  }
+
+  /**
+   * React Native → Android: End/hang up the current call
+   * This will hide the ongoing call notification and notify the native side
+   */
+  static async endCall(callId?: string): Promise<boolean> {
+    try {
+      return await NativeBridge.endCall(callId || null);
+    } catch (error) {
+      console.error('VoicePnBridge: Error ending call:', error);
+      return false;
+    }
+  }
+
+  /**
+   * React Native → Android: Show ongoing call notification to keep app alive
+   * Should be called when a call becomes active to prevent background termination
+   */
+  static async showOngoingCallNotification(
+    callerName?: string,
+    callerNumber?: string,
+    callId?: string
+  ): Promise<boolean> {
+    try {
+      return await NativeBridge.showOngoingCallNotification(
+        callerName || null,
+        callerNumber || null,
+        callId || null
+      );
+    } catch (error) {
+      console.error('VoicePnBridge: Error showing ongoing call notification:', error);
+      return false;
+    }
+  }
+
+  /**
+   * React Native → Android: Hide ongoing call notification
+   * Should be called when a call ends to clean up notifications
+   */
+  static async hideOngoingCallNotification(): Promise<boolean> {
+    try {
+      return await NativeBridge.hideOngoingCallNotification();
+    } catch (error) {
+      console.error('VoicePnBridge: Error hiding ongoing call notification:', error);
+      return false;
+    }
+  }
+
+  /**
+   * React Native → Android: Hide incoming call notification
+   * Useful for dismissing notifications when call is answered/rejected in app
+   */
+  static async hideIncomingCallNotification(): Promise<boolean> {
+    try {
+      return await NativeBridge.hideIncomingCallNotification();
+    } catch (error) {
+      console.error('VoicePnBridge: Error hiding incoming call notification:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Get VoIP token from native storage
+   */
+  static async getVoipToken(): Promise<string | null> {
+    try {
+      return await NativeBridge.getVoipToken();
+    } catch (error) {
+      console.error('VoicePnBridge: Error getting VoIP token:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Get pending VoIP push from native storage
+   */
+  static async getPendingVoipPush(): Promise<string | null> {
+    try {
+      return await NativeBridge.getPendingVoipPush();
+    } catch (error) {
+      console.error('VoicePnBridge: Error getting pending VoIP push:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Clear pending VoIP push from native storage
+   */
+  static async clearPendingVoipPush(): Promise<boolean> {
+    try {
+      return await NativeBridge.clearPendingVoipPush();
+    } catch (error) {
+      console.error('VoicePnBridge: Error clearing pending VoIP push:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Get pending VoIP action from native storage
+   */
+  static async getPendingVoipAction(): Promise<string | null> {
+    try {
+      return await NativeBridge.getPendingVoipAction();
+    } catch (error) {
+      console.error('VoicePnBridge: Error getting pending VoIP action:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Clear pending VoIP action from native storage
+   */
+  static async clearPendingVoipAction(): Promise<boolean> {
+    try {
+      return await NativeBridge.clearPendingVoipAction();
+    } catch (error) {
+      console.error('VoicePnBridge: Error clearing pending VoIP action:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Android → React Native: Listen for immediate call action events from notification buttons
+   * Use this for active calls where immediate response is needed (e.g., ending ongoing calls)
+   */
+  static addCallActionListener(listener: (event: CallActionEvent) => void): EmitterSubscription {
+    return DeviceEventEmitter.addListener('TelnyxCallAction', listener);
+  }
+
+  /**
+   * Remove call action listener
+   */
+  static removeCallActionListener(subscription: EmitterSubscription): void {
+    subscription.remove();
+  }
+
+  /**
+   * Remove all call action listeners
+   */
+  static removeAllCallActionListeners(): void {
+    DeviceEventEmitter.removeAllListeners('TelnyxCallAction');
+  }
+}
+
+// Export the native bridge for direct access if needed
+export { NativeBridge as VoicePnBridgeNative };

package/src/models/call-state.ts

@@ -22,6 +22,9 @@ export enum TelnyxCallState {
 
   /** Call failed to connect or was rejected */
   FAILED = 'FAILED',
+
+  /** Call was dropped due to network issues */
+  DROPPED = 'DROPPED',
 }
 
 /**
@@ -79,7 +82,11 @@ export const CallStateHelpers = {
    * Is the call in a terminated state?
    */
   isTerminated(state: TelnyxCallState): boolean {
-    return state === TelnyxCallState.ENDED || state === TelnyxCallState.FAILED;
+    return (
+      state === TelnyxCallState.ENDED ||
+      state === TelnyxCallState.FAILED ||
+      state === TelnyxCallState.DROPPED
+    );
   },
 
   /**

package/src/models/call.ts

@@ -24,8 +24,17 @@ export class Call {
     private readonly _telnyxCall: TelnyxCall,
     private readonly _callId: string,
     private readonly _destination: string,
-    private readonly _isIncoming: boolean
+    private readonly _isIncoming: boolean,
+    isReattached: boolean = false,
+    private readonly _originalCallerName?: string,
+    private readonly _originalCallerNumber?: string
   ) {
+    // Set initial state based on whether this is a reattached call
+    if (isReattached) {
+      console.log('Call: Setting initial state to ACTIVE for reattached call');
+      this._callState.next(TelnyxCallState.ACTIVE);
+    }
+
     this._setupCallListeners();
   }
 
@@ -85,6 +94,24 @@ export class Call {
     return this._duration.value;
   }
 
+  /**
+   * Custom headers received from the WebRTC INVITE message.
+   * These headers are passed during call initiation and can contain application-specific information.
+   * Format should be [{"name": "X-Header-Name", "value": "Value"}] where header names must start with "X-".
+   */
+  get inviteCustomHeaders(): { name: string; value: string }[] | null {
+    return this._telnyxCall.inviteCustomHeaders;
+  }
+
+  /**
+   * Custom headers received from the WebRTC ANSWER message.
+   * These headers are passed during call acceptance and can contain application-specific information.
+   * Format should be [{"name": "X-Header-Name", "value": "Value"}] where header names must start with "X-".
+   */
+  get answerCustomHeaders(): { name: string; value: string }[] | null {
+    return this._telnyxCall.answerCustomHeaders;
+  }
+
   /**
    * Get the underlying Telnyx Call object (for internal use)
    * @internal
@@ -163,8 +190,9 @@ export class Call {
 
   /**
    * Answer the incoming call
+   * @param customHeaders Optional custom headers to include with the answer
    */
-  async answer(): Promise<void> {
+  async answer(customHeaders?: { name: string; value: string }[]): Promise<void> {
     if (!CallStateHelpers.canAnswer(this.currentState)) {
       throw new Error(`Cannot answer call in state: ${this.currentState}`);
     }
@@ -184,7 +212,8 @@ export class Call {
       console.log('Call: Setting state to CONNECTING before answering');
       this._callState.next(TelnyxCallState.CONNECTING);
 
-      await this._telnyxCall.answer();
+      // Pass custom headers to the underlying Telnyx call
+      await this._telnyxCall.answer(customHeaders);
     } catch (error) {
       console.error('Failed to answer call:', error);
       throw error;
@@ -193,8 +222,9 @@ export class Call {
 
   /**
    * Hang up the call
+   * @param customHeaders Optional custom headers to include with the hangup request
    */
-  async hangup(): Promise<void> {
+  async hangup(customHeaders?: { name: string; value: string }[]): Promise<void> {
     if (!CallStateHelpers.canHangup(this.currentState)) {
       throw new Error(`Cannot hang up call in state: ${this.currentState}`);
     }
@@ -211,7 +241,19 @@ export class Call {
       }
 
       // Fallback for Android or when CallKit is not available
-      await this._telnyxCall.hangup();
+      await this._telnyxCall.hangup(customHeaders);
+
+      // On Android, also notify the native side to hide ongoing notification
+      if (Platform.OS === 'android') {
+        try {
+          const { VoicePnBridge } = await import('../internal/voice-pn-bridge');
+          await VoicePnBridge.endCall(this._callId);
+          console.log('Call: Notified Android to hide ongoing notification');
+        } catch (error) {
+          console.error('Call: Failed to notify Android about call end:', error);
+          // Don't fail the hangup if notification hiding fails
+        }
+      }
     } catch (error) {
       console.error('Failed to hang up call:', error);
       throw error;
@@ -327,11 +369,79 @@ export class Call {
       // Start duration timer when call becomes active
       if (telnyxState === TelnyxCallState.ACTIVE && !this._startTime) {
         this._startDurationTimer();
+
+        // Show ongoing call notification on Android when call becomes active
+        // This covers both locally answered calls and calls that become active from remote side
+        if (Platform.OS === 'android') {
+          (async () => {
+            try {
+              const { VoicePnBridge } = await import('../internal/voice-pn-bridge');
+
+              // Extract caller information based on call direction
+              let callerNumber: string | undefined;
+              let callerName: string | undefined;
+
+              if (this._isIncoming) {
+                // For incoming calls, use the remote caller ID (who's calling us)
+                callerNumber = this._telnyxCall.remoteCallerIdNumber;
+                callerName = this._telnyxCall.remoteCallerIdName;
+              } else {
+                // For outgoing calls, use our own caller ID (what we're showing to them)
+                // These are the values we set when making the call
+                callerNumber = this._telnyxCall.localCallerIdNumber || this._originalCallerNumber;
+                callerName = this._telnyxCall.localCallerIdName || this._originalCallerName;
+              }
+
+              // Fallback logic for better notification display - avoid "Unknown" when possible
+              let displayName: string;
+              let displayNumber: string;
+
+              if (this._isIncoming) {
+                // For incoming calls: use caller name or fall back to caller number, then destination
+                displayName = callerName || callerNumber || this._destination;
+                displayNumber = callerNumber || this._destination;
+              } else {
+                // For outgoing calls: use our caller ID or descriptive text
+                displayName = callerName || `${this._destination}`;
+                displayNumber = callerNumber || this._destination;
+              }
+
+              await VoicePnBridge.showOngoingCallNotification(
+                displayName,
+                displayNumber,
+                this._callId
+              );
+              console.log('Call: Showed ongoing call notification on Android (call active)', {
+                isIncoming: this._isIncoming,
+                callerName: displayName,
+                callerNumber: displayNumber,
+              });
+            } catch (error) {
+              console.error('Call: Failed to show ongoing call notification on active:', error);
+            }
+          })();
+        }
       }
 
       // Stop duration timer when call ends
       if (CallStateHelpers.isTerminated(telnyxState)) {
         this._stopDurationTimer();
+
+        // Clean up ongoing call notification on Android when call ends
+        if (Platform.OS === 'android') {
+          (async () => {
+            try {
+              const { VoicePnBridge } = await import('../internal/voice-pn-bridge');
+              await VoicePnBridge.endCall(this._callId);
+              console.log('Call: Cleaned up ongoing call notification (call terminated)');
+            } catch (error) {
+              console.error(
+                'Call: Failed to clean up ongoing call notification on termination:',
+                error
+              );
+            }
+          })();
+        }
       }
     });
   }
@@ -346,6 +456,8 @@ export class Call {
       case 'ringing':
       case 'new':
         return TelnyxCallState.RINGING;
+      case 'connecting':
+        return TelnyxCallState.CONNECTING;
       case 'active':
       case 'answered':
         return TelnyxCallState.ACTIVE;
@@ -357,6 +469,8 @@ export class Call {
       case 'failed':
       case 'rejected':
         return TelnyxCallState.FAILED;
+      case 'dropped':
+        return TelnyxCallState.DROPPED;
       default:
         console.warn(`Unknown call state: ${telnyxState}`);
         return TelnyxCallState.RINGING;

package/src/telnyx-voice-app.tsx

@@ -262,27 +262,15 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
       // If auto-reconnection fails, redirect to login screen
       if (!success) {
         log('Auto-reconnection failed - redirecting to login screen');
-        // Import router dynamically to avoid circular dependency issues
-        const { router } = require('expo-router');
-
-        // Small delay to ensure state is settled
-        setTimeout(() => {
-          router.replace('/');
-        }, 100);
       }
     } catch (e) {
       log('Auto-reconnection error:', e);
-
       // On error, also redirect to login
       log('Auto-reconnection error - redirecting to login screen');
-      const { router } = require('expo-router');
-      setTimeout(() => {
-        router.replace('/');
-      }, 100);
     }
   }, [voipClient, log]);
 
-  // Check for initial push notification when app launches
+  // Check for initial push notification action when app launches
   const checkForInitialPushNotification = useCallback(
     async (fromAppResume: boolean = false) => {
       log(`checkForInitialPushNotification called${fromAppResume ? ' (from app resume)' : ''}`);
@@ -309,6 +297,42 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
 
           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);
 
@@ -317,33 +341,12 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
 
               // Parse the metadata if it's a string
               let metadata = pendingAction.metadata;
-              if (typeof metadata === 'string') {
-                try {
-                  // First try parsing as JSON
-                  metadata = JSON.parse(metadata);
-                  log('Parsed metadata as JSON:', metadata);
-                } catch (e) {
-                  // If JSON parsing fails, try parsing Android key-value format
-                  // Format: "{call_id=value, action=value}"
-                  log('JSON parse failed, trying Android key-value format');
-                  try {
-                    const cleanedString = metadata.replace(/[{}]/g, '').trim();
-                    const pairs = cleanedString.split(',').map((pair) => pair.trim());
-                    const parsed: Record<string, any> = {};
-
-                    for (const pair of pairs) {
-                      const [key, value] = pair.split('=').map((s) => s.trim());
-                      if (key && value) {
-                        parsed[key] = value;
-                      }
-                    }
-
-                    metadata = parsed;
-                    log('Parsed metadata as Android key-value format:', metadata);
-                  } catch (parseError) {
-                    log('Failed to parse metadata in any format, using as-is:', parseError);
-                  }
-                }
+              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
@@ -516,6 +519,41 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
       }
     });
 
+    // Listen for immediate call action events from notification buttons (Android only)
+    let callActionSubscription: any = null;
+    if (Platform.OS === 'android') {
+      try {
+        const { VoicePnBridge } = require('./internal/voice-pn-bridge');
+        callActionSubscription = VoicePnBridge.addCallActionListener((event) => {
+          log(`Received immediate call action: ${event.action} for callId: ${event.callId}`);
+
+          // Handle immediate call actions (mainly for ending active calls from notification)
+          if (
+            event.action === 'hangup' ||
+            event.action === 'endCall' ||
+            event.action === 'reject'
+          ) {
+            log(`Processing immediate end call action for callId: ${event.callId}`);
+
+            // Find the call by ID and end it
+            const targetCall = voipClient.currentCalls.find((call) => call.callId === event.callId);
+            if (targetCall) {
+              log(`Found active call ${event.callId}, ending it immediately`);
+              targetCall.hangup().catch((error) => {
+                log(`Error ending call ${event.callId}:`, error);
+              });
+            } else {
+              log(`No active call found with ID ${event.callId}`);
+            }
+          }
+        });
+
+        log('Call action listener registered for immediate notification handling');
+      } catch (e) {
+        log('Error setting up call action listener (VoicePnBridge not available):', e);
+      }
+    }
+
     // Add app state listener if not skipping web background detection or not on web
     // AND if app state management is enabled in the client options
     let appStateSubscription: any = null;
@@ -538,6 +576,15 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
     return () => {
       connectionStateSubscription.unsubscribe();
       callsSubscription.unsubscribe();
+      if (callActionSubscription) {
+        try {
+          const { VoicePnBridge } = require('./internal/voice-pn-bridge');
+          VoicePnBridge.removeCallActionListener(callActionSubscription);
+          log('Call action listener removed');
+        } catch (e) {
+          log('Error removing call action listener:', e);
+        }
+      }
       if (appStateSubscription) {
         appStateSubscription.remove();
       }

package/src/telnyx-voip-client.ts

@@ -286,12 +286,19 @@ export class TelnyxVoipClient {
    * Initiates a new outgoing call.
    *
    * @param destination The destination number or SIP URI to call
-   * @param debug Optional flag to enable call quality metrics for this call
+   * @param callerName Optional caller name to display
+   * @param callerNumber Optional caller ID number
+   * @param customHeaders Optional custom headers to include with the call
    * @returns A Promise that completes with the Call object once the invitation has been sent
    *
    * The call's state can be monitored through the returned Call object's streams.
    */
-  async newCall(destination: string, debug: boolean = false): Promise<Call> {
+  async newCall(
+    destination: string,
+    callerName?: string,
+    callerNumber?: string,
+    customHeaders?: Record<string, string>
+  ): Promise<Call> {
     this._throwIfDisposed();
 
     if (!destination || destination.trim() === '') {
@@ -306,7 +313,12 @@ export class TelnyxVoipClient {
       console.log('TelnyxVoipClient: Creating new call to:', destination);
     }
 
-    return await this._callStateController.newCall(destination, undefined, undefined, debug);
+    return await this._callStateController.newCall(
+      destination,
+      callerName,
+      callerNumber,
+      customHeaders
+    );
   }
 
   // ========== Push Notification Methods ==========