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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telnyx/react-voice-commons-sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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",
@@ -19,7 +19,8 @@
     "src",
     "ios",
     "TelnyxVoiceCommons.podspec",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc",
@@ -28,6 +29,10 @@
     "test:watch": "jest --watch",
     "lint": "eslint src --ext .ts,.tsx",
     "clean": "rm -rf lib",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch",
+    "docs:markdown": "typedoc --options typedoc.markdown.json",
+    "docs:all": "npm run docs && npm run docs:markdown",
     "android": "expo run:android",
     "ios": "expo run:ios"
   },
@@ -55,7 +60,7 @@
   "peerDependencies": {
     "@react-native-async-storage/async-storage": "^2.1.0",
     "expo-router": "^5.1.0",
-    "react": "^19.0.0",
+    "react": "19.0.0",
     "react-native": "^0.79.0",
     "react-native-webrtc": "^124.0.5"
   },
@@ -78,7 +83,7 @@
   },
   "dependencies": {
     "@react-native-community/eslint-config": "^3.2.0",
-    "@telnyx/react-native-voice-sdk": "^0.1.0",
+    "@telnyx/react-native-voice-sdk": "^0.1.2",
     "eventemitter3": "^5.0.1",
     "expo": "~53.0.22",
     "react-native-voip-push-notification": "^3.3.3",
@@ -93,6 +98,8 @@
     "eslint": "^8.0.0",
     "jest": "^29.5.0",
     "ts-jest": "^29.1.0",
+    "typedoc": "^0.28.14",
+    "typedoc-plugin-markdown": "^4.9.0",
     "typescript": "^5.0.0"
   },
   "engines": {

package/src/callkit/callkit-coordinator.ts

@@ -3,9 +3,9 @@ import CallKit, { CallEndReason } from './callkit';
 import { Call } from '@telnyx/react-native-voice-sdk';
 import { VoicePnBridge } from '../internal/voice-pn-bridge';
 import { router } from 'expo-router';
-import AsyncStorage from '@react-native-async-storage/async-storage';
 import { TelnyxVoipClient } from '../telnyx-voip-client';
 import { TelnyxConnectionState } from '../models/connection-state';
+import { act } from 'react';
 
 /**
  * CallKit Coordinator - Manages the proper CallKit-first flow for iOS
@@ -31,6 +31,9 @@ class CallKitCoordinator {
 
   private isCallFromPush = false;
 
+  // Flag to auto-answer the next incoming call (set when answering push notifications via CallKit)
+  private shouldAutoAnswerNextCall = false;
+
   // Reference to the VoIP client for triggering reconnection when needed
   private voipClient: TelnyxVoipClient | null = null;
 
@@ -266,10 +269,8 @@ class CallKitCoordinator {
       currentState: call.state,
     });
 
-    if (call.state === 'active' || call.state === 'connecting') {
-      console.log(
-        'CallKitCoordinator: Call already active/connecting, skipping duplicate answer action'
-      );
+    if (call.state === 'active') {
+      console.log('CallKitCoordinator: Call already active, skipping duplicate answer action');
       return;
     }
 
@@ -385,7 +386,7 @@ class CallKitCoordinator {
   }
 
   /**
-   * Handle CallKit push received event - when a VoIP push notification has been processed
+   * Handle CallKit push received event
    * This allows us to coordinate between the push notification and any subsequent WebRTC calls
    */
   async handleCallKitPushReceived(callKitUUID: string, event?: any): Promise<void> {
@@ -438,15 +439,16 @@ class CallKitCoordinator {
       };
 
       // Check if auto-answer is set and add from_notification flag
-      const autoAnswerFlag = await AsyncStorage.getItem('@auto_answer_next_call');
-      const shouldAddFromNotification = autoAnswerFlag === 'true';
+      const shouldAddFromNotification = this.shouldAutoAnswerNextCall;
 
       let pushData;
       if (shouldAddFromNotification) {
         pushData = {
           metadata: enhancedMetadata,
           from_notification: true,
+          action: 'answer',
         };
+        voipClient.queueAnswerFromCallKit();
       } else {
         pushData = {
           metadata: enhancedMetadata,
@@ -476,13 +478,9 @@ class CallKitCoordinator {
         console.log('CallKitCoordinator: Processing iOS push notification answer');
 
         // Set auto-answer flag so when the WebRTC call comes in, it will be answered automatically
-        await AsyncStorage.setItem('@auto_answer_next_call', 'true');
+        this.shouldAutoAnswerNextCall = true;
         console.log('CallKitCoordinator: ✅ Set auto-answer flag for next incoming call');
 
-        // Store the CallKit UUID so we can link it when the WebRTC call arrives
-        await AsyncStorage.setItem('@pending_callkit_uuid', callKitUUID);
-        console.log('CallKitCoordinator: ✅ Stored pending CallKit UUID for linking');
-
         // Get VoIP client and trigger reconnection
         const voipClient = this.getSDKClient();
         if (!voipClient) {
@@ -534,9 +532,9 @@ class CallKitCoordinator {
           });
         }
 
-        // Set the pending push action using VoicePnBridge
+        // Set the pending push action to be handled when app comes to foreground
         await VoicePnBridge.setPendingPushAction(pushAction, pushMetadata);
-        console.log('CallKitCoordinator: ✅ Set pending push action for reconnection');
+        console.log('CallKitCoordinator: ✅ Set pending push action');
 
         return;
       }
@@ -742,29 +740,12 @@ class CallKitCoordinator {
     this.voipClient = voipClient;
   }
 
-  /**
-   * Helper method to handle auto-answer logic for push notification calls
-   */
-  private async handleAutoAnswer(call: Call): Promise<void> {
-    const shouldAutoAnswer = await AsyncStorage.getItem('@auto_answer_next_call');
-    if (shouldAutoAnswer === 'true') {
-      console.log('CallKitCoordinator: Auto-answering call from push notification');
-      await AsyncStorage.removeItem('@auto_answer_next_call');
-
-      // Auto-answer the call after a brief delay to ensure CallKit is ready
-      setTimeout(() => {
-        call.answer();
-      }, 100);
-    }
-  }
-
   /**
    * Helper method to clean up push notification state
    */
   private async cleanupPushNotificationState(): Promise<void> {
-    console.log('CallKitCoordinator: ✅ Cleared pending CallKit UUID and auto-answer flag');
-    await AsyncStorage.removeItem('@pending_callkit_uuid');
-    await AsyncStorage.removeItem('@auto_answer_next_call');
+    console.log('CallKitCoordinator: ✅ Cleared auto-answer flag');
+    this.shouldAutoAnswerNextCall = false;
   }
 
   /**
@@ -814,6 +795,9 @@ class CallKitCoordinator {
     // Reset push notification flag
     this.isCallFromPush = false;
 
+    // Reset auto-answer flag
+    this.shouldAutoAnswerNextCall = false;
+
     console.log('CallKitCoordinator: ✅ Coordinator flags reset');
   }
 

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

@@ -22,6 +22,7 @@ export class CallStateController {
   private _onInviteAutoAccepted?: () => void;
 
   constructor(private readonly _sessionManager: SessionManager) {
+    console.log('🔧 CallStateController: Constructor called - instance created');
     // Don't set up client listeners here - client doesn't exist yet
     // Will be called when client is available
   }
@@ -110,6 +111,10 @@ export class CallStateController {
    */
   initializeClientListeners(): void {
     console.log('🔧 CallStateController: initializeClientListeners called');
+    console.log(
+      '🔧 CallStateController: Current client exists:',
+      !!this._sessionManager.telnyxClient
+    );
     this._setupClientListeners();
 
     // CallKit integration now handled by CallKitCoordinator
@@ -123,7 +128,7 @@ export class CallStateController {
     destination: string,
     callerName?: string,
     callerNumber?: string,
-    debug: boolean = false
+    customHeaders?: Record<string, string>
   ): Promise<Call> {
     if (this._disposed) {
       throw new Error('CallStateController has been disposed');
@@ -139,6 +144,7 @@ export class CallStateController {
         destinationNumber: destination,
         callerIdName: callerName,
         callerIdNumber: callerNumber,
+        customHeaders,
       };
       const telnyxCall = await this._sessionManager.telnyxClient.newCall(callOptions);
 
@@ -147,7 +153,10 @@ export class CallStateController {
         telnyxCall,
         telnyxCall.callId || this._generateCallId(),
         destination,
-        false // outgoing call
+        false, // outgoing call
+        false, // not reattached
+        callerName || destination, // use destination as fallback for caller name
+        callerNumber // original caller number
       );
 
       // Add to our call tracking
@@ -202,16 +211,41 @@ export class CallStateController {
     }
 
     console.log('🔧 CallStateController: TelnyxClient found, setting up incoming call listener');
+    console.log(
+      '🔧 CallStateController: Client instance:',
+      this._sessionManager.telnyxClient.constructor.name
+    );
 
     // Listen for incoming calls
     this._sessionManager.telnyxClient.on(
       'telnyx.call.incoming',
       (telnyxCall: TelnyxCall, msg: any) => {
         console.log('📞 CallStateController: Incoming call received:', telnyxCall.callId);
-        this._handleIncomingCall(telnyxCall, msg);
+        this._handleIncomingCall(telnyxCall, msg, false);
+      }
+    );
+
+    // Listen for reattached calls (after network reconnection)
+    this._sessionManager.telnyxClient.on(
+      'telnyx.call.reattached',
+      (telnyxCall: TelnyxCall, msg: any) => {
+        console.log('📞 CallStateController: Reattached call received:', telnyxCall.callId);
+        this._handleIncomingCall(telnyxCall, msg, true);
       }
     );
 
+    // Verify listeners are set up
+    const incomingListeners =
+      this._sessionManager.telnyxClient.listenerCount('telnyx.call.incoming');
+    const reattachedListeners =
+      this._sessionManager.telnyxClient.listenerCount('telnyx.call.reattached');
+    console.log(
+      '🔧 CallStateController: Listeners registered - incoming:',
+      incomingListeners,
+      'reattached:',
+      reattachedListeners
+    );
+
     // Listen for other call events if needed
     // this._sessionManager.telnyxClient.on('telnyx.call.stateChange', this._handleCallStateChange.bind(this));
 
@@ -219,28 +253,50 @@ export class CallStateController {
   }
 
   /**
-   * Handle incoming call
+   * Handle incoming call or reattached call
    */
-  private _handleIncomingCall(telnyxCall: TelnyxCall, inviteMsg?: any): void {
+  private _handleIncomingCall(
+    telnyxCall: TelnyxCall,
+    inviteMsg?: any,
+    isReattached: boolean = false
+  ): void {
     const callId = telnyxCall.callId || this._generateCallId();
 
-    console.log('📞 CallStateController: Handling incoming call:', callId);
+    console.log(
+      '📞 CallStateController: Handling incoming call:',
+      callId,
+      'isReattached:',
+      isReattached
+    );
     console.log('📞 CallStateController: TelnyxCall object:', telnyxCall);
     console.log('📞 CallStateController: Invite message:', inviteMsg);
 
-    // Check if we already have this call
-    if (this._callMap.has(callId)) {
+    // For reattached calls, remove existing call and create new one
+    if (isReattached && this._callMap.has(callId)) {
+      console.log('📞 CallStateController: Removing existing call for reattachment');
+      const existingCall = this._callMap.get(callId);
+      if (existingCall) {
+        console.log(
+          '📞 CallStateController: Existing call state before removal:',
+          existingCall.currentState
+        );
+        this._removeCall(callId);
+      }
+    }
+
+    // Check if we already have this call (for non-reattached calls)
+    if (this._callMap.has(callId) && !isReattached) {
       console.log('Call already exists:', callId);
       return;
     }
 
     // Get caller information from the invite message (preferred) or fallback to TelnyxCall
-    let callerNumber = 'Unknown';
-    let callerName = 'Unknown';
+    let callerNumber = '';
+    let callerName = '';
 
     if (inviteMsg && inviteMsg.params) {
-      callerNumber = inviteMsg.params.caller_id_number || 'Unknown';
-      callerName = inviteMsg.params.caller_id_name || callerNumber;
+      callerNumber = inviteMsg.params.caller_id_number || '';
+      callerName = inviteMsg.params.caller_id_name || '';
       console.log(
         '📞 CallStateController: Extracted caller info from invite - Number:',
         callerNumber,
@@ -249,8 +305,8 @@ export class CallStateController {
       );
     } else {
       // Fallback to TelnyxCall properties
-      callerNumber = telnyxCall.remoteCallerIdNumber || 'Unknown';
-      callerName = telnyxCall.remoteCallerIdName || callerNumber;
+      callerNumber = telnyxCall.remoteCallerIdNumber || '';
+      callerName = telnyxCall.remoteCallerIdName || '';
       console.log(
         '📞 CallStateController: Extracted caller info from TelnyxCall - Number:',
         callerNumber,
@@ -259,60 +315,25 @@ export class CallStateController {
       );
     }
 
+    // Use smart fallbacks - prefer caller number over "Unknown"
+    const finalCallerNumber = callerNumber || 'Unknown Number';
+    const finalCallerName = callerName || callerNumber || 'Unknown Caller';
+
     // Create our wrapper Call object
     const call = new Call(
       telnyxCall,
       callId,
-      callerNumber, // Use caller number as destination for incoming calls
-      true // incoming call
+      finalCallerNumber, // Use caller number as destination for incoming calls
+      true, // incoming call
+      isReattached, // pass the reattached flag
+      finalCallerName, // use caller name or fallback to number
+      finalCallerNumber // use caller number
     );
 
-    // Check if we're waiting for an invite (push notification scenario)
-    if (this._isWaitingForInvite && this._isWaitingForInvite()) {
-      console.log('Auto-accepting call from push notification');
-      call.answer().catch((error) => {
-        console.error('Failed to auto-accept call:', error);
-      });
-
-      if (this._onInviteAutoAccepted) {
-        this._onInviteAutoAccepted();
-      }
-    }
-
     // Add to our call tracking - CallKit integration happens in _addCall
     this._addCall(call);
   }
 
-  /**
-   * Handle call state changes from the Telnyx client
-   */
-  private _handleCallStateChange(event: any): void {
-    const callId = event.callId || event.id;
-    const call = this._callMap.get(callId);
-
-    if (call) {
-      // The Call object will handle its own state updates through its listeners
-      console.log(`Call ${callId} state changed to ${event.state}`);
-    } else {
-      console.warn(`Received state change for unknown call: ${callId}`);
-    }
-  }
-
-  /**
-   * Handle call updates from notifications
-   */
-  private _handleCallUpdate(callData: any): void {
-    const callId = callData.id;
-    const call = this._callMap.get(callId);
-
-    if (call) {
-      // Update call state based on the notification
-      console.log(`Call ${callId} updated:`, callData);
-    } else {
-      console.warn(`Received update for unknown call: ${callId}`);
-    }
-  }
-
   /**
    * Add a call to our tracking
    */
@@ -365,6 +386,8 @@ export class CallStateController {
   private _removeCall(callId: string): void {
     const call = this._callMap.get(callId);
     if (call) {
+      console.log('CallStateController: Removing call:', callId);
+
       // CallKit cleanup is handled automatically by CallKitCoordinator
 
       call.dispose();

package/src/internal/session/session-manager.ts

@@ -276,7 +276,7 @@ export class SessionManager {
   }
 
   /**
-   * Internal method to establish connection
+   * Internal method to establish connection with or without push notification handling
    */
   private async _connect(): Promise<void> {
     if (!this._currentConfig) {
@@ -363,8 +363,13 @@ export class SessionManager {
       console.log(
         '🔧 SessionManager: Setting up CallStateController listeners before connection...'
       );
+      console.log('🔧 SessionManager: _onClientReady callback exists:', !!this._onClientReady);
       if (this._onClientReady) {
+        console.log('🔧 SessionManager: Calling _onClientReady callback now...');
         this._onClientReady();
+        console.log('🔧 SessionManager: _onClientReady callback completed');
+      } else {
+        console.log('🔧 SessionManager: No _onClientReady callback found');
       }
 
       // Connect to the platform AFTER processing push notification
@@ -393,6 +398,21 @@ export class SessionManager {
     this._telnyxClient.on('telnyx.client.ready', () => {
       console.log('Telnyx client ready');
       this._connectionState.next(TelnyxConnectionState.CONNECTED);
+
+      // Ensure CallStateController listeners are set up when client becomes ready
+      // This handles both initial connection and automatic reconnection
+      console.log(
+        '🔧 SessionManager: Client ready event - reinitializing CallStateController listeners'
+      );
+      if (this._onClientReady) {
+        console.log(
+          '🔧 SessionManager: Calling _onClientReady callback from client ready event...'
+        );
+        this._onClientReady();
+        console.log('🔧 SessionManager: _onClientReady callback completed from client ready event');
+      } else {
+        console.log('🔧 SessionManager: No _onClientReady callback found in client ready event');
+      }
     });
 
     this._telnyxClient.on('telnyx.client.error', (error: Error) => {
@@ -404,28 +424,6 @@ export class SessionManager {
     // We'll rely on the client-level events for now
   }
 
-  /**
-   * Attempt to reconnect after connection loss
-   */
-  private async _attemptReconnection(): Promise<void> {
-    if (this._disposed || !this._currentConfig) {
-      return;
-    }
-
-    // Simple reconnection logic - in production, this should include
-    // exponential backoff and maximum retry attempts
-    setTimeout(async () => {
-      if (this.currentState === TelnyxConnectionState.RECONNECTING) {
-        try {
-          await this._connect();
-        } catch (error) {
-          console.error('Reconnection failed:', error);
-          // Could implement retry logic here
-        }
-      }
-    }, 3000);
-  }
-
   /**
    * Extract the actual payload metadata from wrapped push notification payload
    */
@@ -434,10 +432,19 @@ export class SessionManager {
     let actualPayload = payload;
 
     if (payload.metadata && typeof payload.metadata === 'object') {
-      // If there's a metadata wrapper, use that
+      // If there's a metadata wrapper, use that but preserve wrapper-level flags
       actualPayload = payload.metadata;
+
+      // Preserve important flags from the wrapper level
+      if (payload.from_notification !== undefined) {
+        actualPayload.from_notification = payload.from_notification;
+      }
+      if (payload.action !== undefined) {
+        actualPayload.action = payload.action;
+      }
+
       console.log(
-        'SessionManager: RELEASE DEBUG - Using metadata portion of payload:',
+        'SessionManager: RELEASE DEBUG - Using metadata portion of payload with preserved flags:',
         JSON.stringify(actualPayload)
       );
     } else if (payload.action === 'incoming_call' && payload.metadata) {
@@ -446,8 +453,17 @@ export class SessionManager {
         const parsedMetadata =
           typeof payload.metadata === 'string' ? JSON.parse(payload.metadata) : payload.metadata;
         actualPayload = parsedMetadata;
+
+        // Preserve important flags from the wrapper level
+        if (payload.from_notification !== undefined) {
+          actualPayload.from_notification = payload.from_notification;
+        }
+        if (payload.action !== undefined) {
+          actualPayload.action = payload.action;
+        }
+
         console.log(
-          'SessionManager: RELEASE DEBUG - Using parsed metadata:',
+          'SessionManager: RELEASE DEBUG - Using parsed metadata with preserved flags:',
           JSON.stringify(actualPayload)
         );
       } catch (error) {