@telnyx/react-voice-commons-sdk 0.1.0

package/src/hooks/use-callkit-coordinator.ts

@@ -0,0 +1,60 @@
+import { useCallback } from 'react';
+import { Call } from '@telnyx/react-native-voice-sdk';
+import callKitCoordinator from '../callkit/callkit-coordinator';
+import { TelnyxVoipClient } from '../telnyx-voip-client';
+
+export function useCallKitCoordinator() {
+  const reportIncomingCall = useCallback(
+    async (call: Call, callerName: string, callerNumber: string): Promise<string | null> => {
+      return callKitCoordinator.reportIncomingCall(call, callerName, callerNumber);
+    },
+    []
+  );
+
+  const startOutgoingCall = useCallback(
+    async (call: Call, destinationNumber: string, displayName?: string): Promise<string | null> => {
+      return callKitCoordinator.startOutgoingCall(call, destinationNumber, displayName);
+    },
+    []
+  );
+
+  const answerCallFromUI = useCallback(async (call: Call): Promise<boolean> => {
+    return callKitCoordinator.answerCallFromUI(call);
+  }, []);
+
+  const endCallFromUI = useCallback(async (call: Call): Promise<boolean> => {
+    return callKitCoordinator.endCallFromUI(call);
+  }, []);
+
+  const getCallKitUUID = useCallback((call: Call): string | null => {
+    return callKitCoordinator.getCallKitUUID(call);
+  }, []);
+
+  const getWebRTCCall = useCallback((callKitUUID: string): Call | null => {
+    return callKitCoordinator.getWebRTCCall(callKitUUID);
+  }, []);
+
+  const linkExistingCallKitCall = useCallback((call: Call, callKitUUID: string): void => {
+    callKitCoordinator.linkExistingCallKitCall(call, callKitUUID);
+  }, []);
+
+  const isAvailable = useCallback((): boolean => {
+    return callKitCoordinator.isAvailable();
+  }, []);
+
+  const setVoipClient = useCallback((voipClient: TelnyxVoipClient): void => {
+    callKitCoordinator.setVoipClient(voipClient);
+  }, []);
+
+  return {
+    reportIncomingCall,
+    startOutgoingCall,
+    answerCallFromUI,
+    endCallFromUI,
+    getCallKitUUID,
+    getWebRTCCall,
+    linkExistingCallKitCall,
+    isAvailable,
+    setVoipClient,
+  };
+}

package/src/hooks/useAppReadyNotifier.ts

@@ -0,0 +1,25 @@
+import { useEffect } from 'react';
+import { Platform } from 'react-native';
+
+/**
+ * Hook to notify the native side when React Native is ready
+ * Call this hook when your main screen/login screen is visible and ready
+ * This is automatically called by TelnyxVoiceApp, but can be used manually if needed
+ *
+ * Note: With the native VoicePnManager integration, this notification is now
+ * handled automatically by the native Android services, so this hook is simplified.
+ */
+export const useAppReadyNotifier = () => {
+  useEffect(() => {
+    // Only notify on Android since this is Android-specific functionality
+    if (Platform.OS === 'android') {
+      console.log(
+        'useAppReadyNotifier: React Native is ready (native services handle FCM automatically)'
+      );
+
+      // Note: The VoicePnManager in the native Android code automatically handles
+      // push notification state when the Firebase messaging service receives notifications.
+      // No JavaScript module communication is needed anymore.
+    }
+  }, []);
+};

package/src/hooks/useAppStateHandler.ts

@@ -0,0 +1,134 @@
+import { useEffect, useRef } from 'react';
+import { AppState, AppStateStatus } from 'react-native';
+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 { TelnyxCallState, CallStateHelpers } from '../models/call-state';
+
+interface UseAppStateHandlerOptions {
+  voipClient: TelnyxVoipClient;
+  disconnectOnBackground?: boolean;
+  navigateToLoginOnDisconnect?: boolean;
+  debug?: boolean;
+}
+
+/**
+ * Hook to handle app state changes for VoIP behavior
+ * When app goes to background without an active call, disconnect socket and redirect to login
+ */
+export const useAppStateHandler = ({
+  voipClient,
+  disconnectOnBackground = true,
+  navigateToLoginOnDisconnect = true,
+  debug = false,
+}: UseAppStateHandlerOptions) => {
+  const appState = useRef(AppState.currentState);
+  const log = debug ? console.log : () => {};
+
+  useEffect(() => {
+    const handleAppStateChange = async (nextAppState: AppStateStatus) => {
+      log('AppStateHandler: App state changed from', appState.current, 'to', nextAppState);
+
+      // When app goes to background
+      if (appState.current.match(/active/) && nextAppState === 'background') {
+        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');
+          appState.current = nextAppState;
+          return;
+        }
+
+        // Check if there's an active call (including ringing calls)
+        const activeCalls = voipClient.currentCalls;
+        const hasActiveCall =
+          activeCalls.length > 0 &&
+          activeCalls.some(
+            (call) =>
+              CallStateHelpers.isActive(call.currentState) ||
+              call.currentState === TelnyxCallState.RINGING
+          );
+
+        log('AppStateHandler: Active call check:', {
+          callCount: activeCalls.length,
+          hasActiveCall,
+          callStates: activeCalls.map((call) => ({
+            callId: call.callId,
+            currentState: call.currentState,
+            destination: call.destination,
+            isIncoming: call.isIncoming,
+          })),
+        });
+
+        if (!hasActiveCall && disconnectOnBackground) {
+          // Check if there's a push notification call in progress
+          const isPushNotificationInProgress = await AsyncStorage.getItem(
+            '@push_notification_payload'
+          );
+
+          if (isPushNotificationInProgress) {
+            log('AppStateHandler: Push notification call in progress, keeping socket connected');
+            // Wait a bit longer before allowing disconnection to give time for WebRTC call to establish
+            setTimeout(async () => {
+              const stillInProgress = await AsyncStorage.getItem('@push_notification_payload');
+              if (!stillInProgress) {
+                log('AppStateHandler: Push notification call completed, now disconnecting socket');
+                await voipClient.logout();
+                if (navigateToLoginOnDisconnect) {
+                  router.replace('/');
+                }
+              }
+            }, 5000); // Wait 5 seconds
+            appState.current = nextAppState;
+            return;
+          }
+
+          log('AppStateHandler: No active call detected, disconnecting socket...');
+
+          try {
+            // Disconnect the socket with background reason
+            await voipClient.logout();
+
+            log('AppStateHandler: Socket disconnected successfully');
+
+            // Navigate to login screen
+            if (navigateToLoginOnDisconnect) {
+              // Use a small delay to ensure the disconnect completes
+              setTimeout(() => {
+                log('AppStateHandler: Navigating to login screen');
+                router.replace('/');
+              }, 100);
+            }
+          } catch (error) {
+            console.error('AppStateHandler: Error during background disconnect:', error);
+          }
+        } else {
+          log(
+            'AppStateHandler: Active call detected or disconnect disabled, keeping socket connected'
+          );
+        }
+      }
+
+      // When app comes to foreground
+      if (appState.current.match(/background/) && nextAppState === 'active') {
+        log('AppStateHandler: App came to foreground');
+        // User will need to manually login again when returning from background
+        // Auto-login only happens for push notification calls
+      }
+
+      appState.current = nextAppState;
+    };
+
+    const subscription = AppState.addEventListener('change', handleAppStateChange);
+
+    return () => {
+      subscription?.remove();
+    };
+  }, [voipClient, disconnectOnBackground, navigateToLoginOnDisconnect, log]);
+
+  return {
+    currentAppState: appState.current,
+  };
+};

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * @telnyx/react-voice-commons-sdk
+ *
+ * A high-level, state-agnostic, drop-in module for the Telnyx React Native SDK.
+ *
+ * This library provides a simplified interface for integrating Telnyx WebRTC
+ * capabilities into React Native applications. It handles session management,
+ * call state transitions, push notification processing, and native call UI
+ * integration.
+ */
+
+// Main client
+export {
+  TelnyxVoipClient,
+  createTelnyxVoipClient,
+  createBackgroundTelnyxVoipClient,
+} from './telnyx-voip-client';
+export type { TelnyxVoipClientOptions } from './telnyx-voip-client';
+
+// TelnyxVoiceApp component
+export { TelnyxVoiceApp } from './telnyx-voice-app';
+export type { TelnyxVoiceAppOptions, TelnyxVoiceAppProps } from './telnyx-voice-app';
+
+// Hooks
+export { useAppStateHandler } from './hooks/useAppStateHandler';
+export { useTelnyxVoice } from './context/TelnyxVoiceContext';
+
+// Models
+export { Call } from './models/call';
+export {
+  TelnyxConnectionState,
+  isTelnyxConnectionState,
+  canMakeCalls,
+  isConnected,
+  isTransitioning,
+} from './models/connection-state';
+export { TelnyxCallState, isTelnyxCallState, CallStateHelpers } from './models/call-state';
+export {
+  isCredentialConfig,
+  isTokenConfig,
+  validateConfig,
+  validateCredentialConfig,
+  validateTokenConfig,
+  createCredentialConfig,
+  createTokenConfig,
+} from './models/config';
+export type { Config, CredentialConfig, TokenConfig } from './models/config';
+
+// Re-export useful types from the underlying SDK
+export type { Call as TelnyxCall } from '@telnyx/react-native-voice-sdk';
+
+// Export CallKit functionality
+export * from './callkit';
+
+// Export hooks
+export { useAppReadyNotifier } from './hooks/useAppReadyNotifier';

package/src/internal/CallKitHandler.tsx

@@ -0,0 +1,149 @@
+import React, { useEffect, useRef } from 'react';
+import { Platform, DeviceEventEmitter } from 'react-native';
+import { useRouter } from 'expo-router';
+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
+let isCallKitHandlerActive = false;
+
+interface CallData {
+  type: string;
+  callUUID: string;
+  payload?: any;
+  callData?: any;
+  action: string;
+}
+
+interface CallKitHandlerProps {
+  /** Callback when user needs to login from push notification */
+  onLoginRequired?: (pushPayload: any) => void;
+  /** Callback when call is answered and user should navigate to dialer */
+  onNavigateToDialer?: () => void;
+  /** Callback when call ends and user should navigate back */
+  onNavigateBack?: () => void;
+}
+
+/**
+ * Internal CallKit handler for iOS push notifications
+ * This component is automatically included in TelnyxVoiceApp
+ *
+ * @internal - Users should not use this component directly
+ */
+export const CallKitHandler: React.FC<CallKitHandlerProps> = ({
+  onLoginRequired,
+  onNavigateToDialer,
+  onNavigateBack,
+}) => {
+  const router = useRouter();
+  const { voipClient } = useTelnyxVoice();
+
+  // Store active calls by CallKit UUID for coordination
+  const activeCallsRef = useRef<Map<string, any>>(new Map());
+
+  useEffect(() => {
+    if (Platform.OS !== 'ios') return;
+
+    if (isCallKitHandlerActive) {
+      console.log('CallKitHandler: Another instance is already active, skipping setup');
+      return;
+    }
+
+    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) => {
+        console.log('🔥 CallKitHandler: Incoming VoIP call received:', eventData);
+        if (eventData.action === 'connect_webrtc') {
+          await handleIncomingCall(eventData);
+        }
+      }
+    );
+
+    const callKitActionListener = DeviceEventEmitter.addListener(
+      'callKitAction',
+      async (eventData: CallData) => {
+        console.log('🔥 CallKitHandler: CallKit action received:', eventData);
+        switch (eventData.action) {
+          case 'answer':
+            await handleAnswerCall(eventData);
+            break;
+          case 'end':
+            await handleEndCall(eventData);
+            break;
+        }
+      }
+    );
+
+    console.log('CallKitHandler: DeviceEventEmitter listeners set up successfully');
+
+    return () => {
+      console.log('CallKitHandler: Cleaning up DeviceEventEmitter listeners');
+      incomingCallListener.remove();
+      callKitActionListener.remove();
+      isCallKitHandlerActive = false;
+    };
+  }, []);
+
+  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),
+    });
+
+    // Navigate to dialer after answering
+    if (onNavigateToDialer) {
+      onNavigateToDialer();
+    } else {
+      router.replace('/dialer');
+    }
+  };
+
+  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');
+
+    // Navigate back after call ends
+    if (onNavigateBack) {
+      onNavigateBack();
+    } else {
+      router.replace('/dialer');
+    }
+  };
+
+  // This component doesn't render anything, it just handles events
+  return null;
+};