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

package/src/telnyx-voice-app.tsx

@@ -1,737 +1,788 @@
-import React, { useEffect, useRef, useState, useCallback } from 'react';
-import { AppState, AppStateStatus, Platform } from 'react-native';
-import { TelnyxVoipClient, createBackgroundTelnyxVoipClient } from './telnyx-voip-client';
-import { TelnyxConnectionState } from './models/connection-state';
-import { Call } from './models/call';
-import { TelnyxVoiceProvider } from './context/TelnyxVoiceContext';
-
-/**
- * Configuration options for TelnyxVoiceApp
- */
-export interface TelnyxVoiceAppOptions {
-  /** The TelnyxVoipClient instance to manage */
-  voipClient: TelnyxVoipClient;
-
-  /** Optional callback when push notification processing starts */
-  onPushNotificationProcessingStarted?: () => void;
-
-  /** Optional callback when push notification processing completes */
-  onPushNotificationProcessingCompleted?: () => void;
-
-  /** Optional callback for additional background/foreground handling */
-  onAppStateChanged?: (state: AppStateStatus) => void;
-
-  /** Whether to enable automatic login/reconnection (default: true) */
-  enableAutoReconnect?: boolean;
-
-  /** Whether to skip web platform for background detection (default: true) */
-  skipWebBackgroundDetection?: boolean;
-
-  /** Enable debug logging */
-  debug?: boolean;
-}
-
-/**
- * Props for the TelnyxVoiceApp component
- */
-export interface TelnyxVoiceAppProps extends TelnyxVoiceAppOptions {
-  /** The child components to render */
-  children: React.ReactNode;
-}
-
-/**
- * Interface for the TelnyxVoiceApp component with static methods
- */
-export interface TelnyxVoiceAppComponent extends React.FC<TelnyxVoiceAppProps> {
-  initializeAndCreate: (options: {
-    voipClient: TelnyxVoipClient;
-    children: React.ReactNode;
-    backgroundMessageHandler?: (message: any) => Promise<void>;
-    onPushNotificationProcessingStarted?: () => void;
-    onPushNotificationProcessingCompleted?: () => void;
-    onAppStateChanged?: (state: AppStateStatus) => void;
-    enableAutoReconnect?: boolean;
-    skipWebBackgroundDetection?: boolean;
-    debug?: boolean;
-  }) => Promise<React.ComponentType>;
-
-  handleBackgroundPush: (message: any) => Promise<void>;
-}
-
-/**
- * A comprehensive wrapper component that handles all Telnyx SDK lifecycle management.
- *
- * This component automatically handles:
- * - Push notification initialization from terminated state
- * - Background/foreground lifecycle detection and auto-reconnection
- * - Login state management with automatic reconnection
- * - CallKit integration preparation
- *
- * Simply wrap your main app component with this to get full Telnyx functionality:
- * ```tsx
- * <TelnyxVoiceApp voipClient={myVoipClient}>
- *   <MyApp />
- * </TelnyxVoiceApp>
- * ```
- */
-const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
-  voipClient,
-  children,
-  onPushNotificationProcessingStarted,
-  onPushNotificationProcessingCompleted,
-  onAppStateChanged,
-  enableAutoReconnect = true,
-  skipWebBackgroundDetection = true,
-  debug = false,
-}) => {
-  // State management
-  const [processingPushOnLaunch, setProcessingPushOnLaunch] = useState(false);
-  const [isHandlingForegroundCall, setIsHandlingForegroundCall] = useState(false);
-  const [currentConnectionState, setCurrentConnectionState] = useState<TelnyxConnectionState>(
-    voipClient.currentConnectionState
-  );
-
-  // Refs for tracking state
-  const appStateRef = useRef<AppStateStatus>(AppState.currentState);
-  const backgroundDetectorIgnore = useRef(false);
-
-  // Static background client instance for singleton pattern
-  const backgroundClientRef = useRef<TelnyxVoipClient | null>(null);
-
-  const log = useCallback(
-    (message: string, ...args: any[]) => {
-      if (debug) {
-        console.log(`[TelnyxVoiceApp] ${message}`, ...args);
-      }
-    },
-    [debug]
-  );
-
-  // Handle app state changes
-  const handleAppStateChange = useCallback(
-    async (nextAppState: AppStateStatus) => {
-      const previousAppState = appStateRef.current;
-      appStateRef.current = nextAppState;
-
-      log(`App state changed from ${previousAppState} to ${nextAppState}`);
-      log(`Background detector ignore flag: ${backgroundDetectorIgnore.current}`);
-      log(`Handling foreground call: ${isHandlingForegroundCall}`);
-
-      // Call optional user callback first
-      onAppStateChanged?.(nextAppState);
-
-      // Only handle background disconnection when actually transitioning from active to background
-      // Don't disconnect on background-to-background transitions (e.g., during CallKit operations)
-      if (
-        (nextAppState === 'background' || nextAppState === 'inactive') &&
-        previousAppState === 'active'
-      ) {
-        log(
-          `App transitioned from ${previousAppState} to ${nextAppState} - handling backgrounding`
-        );
-        await handleAppBackgrounded();
-      } else if (nextAppState === 'background' || nextAppState === 'inactive') {
-        log(
-          `App state is ${nextAppState} but was already ${previousAppState} - skipping background handling`
-        );
-      }
-
-      // Always check for push notifications when app becomes active (regardless of auto-reconnect setting)
-      if (nextAppState === 'active' && previousAppState !== 'active') {
-        log('App became active - checking for push notifications');
-        await checkForInitialPushNotification(true); // Pass true for fromAppResume
-      }
-
-      // Only handle auto-reconnection if auto-reconnect is enabled
-      if (enableAutoReconnect && nextAppState === 'active' && previousAppState !== 'active') {
-        await handleAppResumed();
-      }
-    },
-    [enableAutoReconnect, onAppStateChanged, isHandlingForegroundCall, log]
-  );
-
-  // Handle app going to background - disconnect like the old implementation
-  const handleAppBackgrounded = useCallback(async () => {
-    // Check if we should ignore background detection (e.g., during active calls)
-    if (backgroundDetectorIgnore.current || isHandlingForegroundCall) {
-      log(
-        'Background detector ignore flag set or handling foreground call - skipping disconnection'
-      );
-      return;
-    }
-
-    // Check if there are any active calls that should prevent disconnection
-    const activeCalls = voipClient.currentCalls;
-    const hasOngoingCall =
-      activeCalls.length > 0 &&
-      activeCalls.some(
-        (call) =>
-          call.currentState === 'ACTIVE' ||
-          call.currentState === 'HELD' ||
-          call.currentState === 'RINGING' ||
-          call.currentState === 'CONNECTING'
-      );
-
-    // Also check if there's an incoming call from push notification being processed
-    let isCallFromPush = false;
-    if (Platform.OS === 'ios') {
-      try {
-        const { callKitCoordinator } = require('./callkit/callkit-coordinator');
-        isCallFromPush = callKitCoordinator.getIsCallFromPush();
-      } catch (e) {
-        log('Error checking isCallFromPush:', e);
-      }
-    }
-
-    if (hasOngoingCall || isCallFromPush) {
-      log('Active calls or push call detected - skipping background disconnection', {
-        callCount: activeCalls.length,
-        hasOngoingCall,
-        isCallFromPush,
-        callStates: activeCalls.map((call) => ({
-          callId: call.callId,
-          currentState: call.currentState,
-          destination: call.destination,
-        })),
-      });
-      return;
-    }
-
-    log('App backgrounded - disconnecting (matching old BackgroundDetector behavior)');
-
-    try {
-      // Always disconnect when backgrounded (matches old implementation)
-      await voipClient.logout();
-      log('Successfully disconnected on background');
-    } catch (e) {
-      log('Error disconnecting on background:', e);
-    }
-  }, [voipClient, isHandlingForegroundCall, log]);
-
-  // Handle app resuming from background
-  const handleAppResumed = useCallback(async () => {
-    log('App resumed - checking reconnection needs');
-
-    // IMPORTANT: Check for push notifications first when resuming from background
-    // This handles the case where the user accepted a call while the app was backgrounded
-    await checkForInitialPushNotification(true); // Pass true for fromAppResume
-
-    // If we're ignoring (e.g., from push call) or handling foreground call, don't auto-reconnect
-    if (backgroundDetectorIgnore.current || isHandlingForegroundCall) {
-      log(
-        'Background detector ignore flag set or handling foreground call - skipping reconnection'
-      );
-      return;
-    }
-
-    // iOS-specific: If push notification handling just initiated a connection,
-    // skip auto-reconnection to prevent double login
-    if (Platform.OS === 'ios') {
-      // Check if connection state changed after push processing
-      const connectionStateAfterPush = voipClient.currentConnectionState;
-      if (
-        connectionStateAfterPush === TelnyxConnectionState.CONNECTING ||
-        connectionStateAfterPush === TelnyxConnectionState.CONNECTED
-      ) {
-        log(
-          `iOS: Push handling initiated connection (${connectionStateAfterPush}), skipping auto-reconnection`
-        );
-        return;
-      }
-    }
-
-    // Check current connection state and reconnect if needed
-    const currentState = voipClient.currentConnectionState;
-    log(`Current connection state: ${currentState}`);
-
-    // If we're not connected and have stored credentials, attempt reconnection
-    if (currentState !== TelnyxConnectionState.CONNECTED) {
-      await attemptAutoReconnection();
-    }
-  }, [voipClient, isHandlingForegroundCall, log]);
-
-  // Attempt to reconnect using stored credentials
-  const attemptAutoReconnection = useCallback(async () => {
-    try {
-      log('Attempting auto-reconnection...');
-
-      // Try to get stored config and reconnect
-      const success = await voipClient.loginFromStoredConfig();
-      log(`Auto-reconnection ${success ? 'successful' : 'failed'}`);
-
-      // If auto-reconnection fails, redirect to login screen
-      if (!success) {
-        log('Auto-reconnection failed - redirecting to login screen');
-      }
-    } catch (e) {
-      log('Auto-reconnection error:', e);
-      // On error, also redirect to login
-      log('Auto-reconnection error - redirecting to login screen');
-    }
-  }, [voipClient, log]);
-
-  // Check for initial push notification action when app launches
-  const checkForInitialPushNotification = useCallback(
-    async (fromAppResume: boolean = false) => {
-      log(`checkForInitialPushNotification called${fromAppResume ? ' (from app resume)' : ''}`);
-
-      if (processingPushOnLaunch && !fromAppResume) {
-        log('Already processing push, returning early');
-        return;
-      }
-
-      // Only set the flag if this is not from app resume to allow resume processing
-      if (!fromAppResume) {
-        setProcessingPushOnLaunch(true);
-      }
-      onPushNotificationProcessingStarted?.();
-
-      try {
-        let pushData: Record<string, any> | null = null;
-
-        // Try to get push data from the native layer using our VoicePnBridge
-        try {
-          // Import the native bridge module dynamically
-          const { NativeModules } = require('react-native');
-          const VoicePnBridge = NativeModules.VoicePnBridge;
-
-          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);
-
-            if (pendingAction && pendingAction.action != null && pendingAction.metadata != null) {
-              log('Found pending push action:', pendingAction);
-
-              // Parse the metadata if it's a string
-              let metadata = pendingAction.metadata;
-              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
-              pushData = {
-                action: pendingAction.action,
-                metadata: metadata,
-                from_notification: true,
-              };
-
-              // Clear the pending action so it doesn't get processed again
-              await VoicePnBridge.clearPendingPushAction();
-              log('Cleared pending push action after retrieval');
-            } else {
-              log('No pending push actions found');
-            }
-          } else {
-            log('VoicePnBridge not available - this is expected on iOS');
-          }
-        } catch (bridgeError) {
-          log('Error accessing VoicePnBridge:', bridgeError);
-        }
-
-        // Process the push notification if found
-        if (pushData) {
-          log('Processing initial push notification...');
-
-          // Check if we're already connected and handling a push - prevent duplicate processing
-          const isConnected = voipClient.currentConnectionState === TelnyxConnectionState.CONNECTED;
-          if (isConnected) {
-            log('SKIPPING - Already connected, preventing duplicate processing');
-            // Clear the stored data since we're already handling it
-            // TODO: Implement clearPushMetaData
-            return;
-          }
-
-          // Set flags to prevent auto-reconnection during push call
-          setIsHandlingForegroundCall(true);
-          backgroundDetectorIgnore.current = true;
-          log(`Background detector ignore set to: true at ${new Date().toISOString()}`);
-          log(`Foreground call handling flag set to: true at ${new Date().toISOString()}`);
-
-          // Dispose any existing background client to prevent conflicts
-          disposeBackgroundClient();
-
-          // Handle the push notification using platform-specific approach
-          if (Platform.OS === 'ios') {
-            // On iOS, coordinate with CallKit by notifying the coordinator about the push
-            const { callKitCoordinator } = require('./callkit/callkit-coordinator');
-
-            // Extract call_id from nested metadata structure to use as CallKit UUID
-            const callId = pushData.metadata?.metadata?.call_id;
-            if (callId) {
-              log('Notifying CallKit coordinator about push notification:', callId);
-              await callKitCoordinator.handleCallKitPushReceived(callId, {
-                callData: { source: 'push_notification' },
-                pushData: pushData,
-              });
-            } else {
-              log('No call_id found in push data, falling back to direct handling');
-              await voipClient.handlePushNotification(pushData);
-            }
-          } else {
-            // On other platforms, handle push notification directly
-            await voipClient.handlePushNotification(pushData);
-          }
-
-          log('Initial push notification processed');
-          log('Cleared stored push data to prevent duplicate processing');
-
-          // Note: isHandlingForegroundCall will be reset when calls.length becomes 0
-          // This prevents premature disconnection during CallKit answer flow
-        } else {
-          log('No initial push data found');
-        }
-      } catch (e) {
-        log('Error processing initial push notification:', e);
-        // Reset flags on error
-        setIsHandlingForegroundCall(false);
-      } finally {
-        // Always reset the processing flag - it should not remain stuck
-        setProcessingPushOnLaunch(false);
-        onPushNotificationProcessingCompleted?.();
-      }
-    },
-    [
-      processingPushOnLaunch,
-      voipClient,
-      onPushNotificationProcessingStarted,
-      onPushNotificationProcessingCompleted,
-      log,
-    ]
-  );
-
-  // Dispose background client instance when no longer needed
-  const disposeBackgroundClient = useCallback(() => {
-    if (backgroundClientRef.current) {
-      log('Disposing background client instance');
-      backgroundClientRef.current.dispose();
-      backgroundClientRef.current = null;
-    }
-  }, [log]);
-
-  // Create background client for push notification handling
-  const createBackgroundClient = useCallback((): TelnyxVoipClient => {
-    log('Creating background client instance');
-
-    const backgroundClient = createBackgroundTelnyxVoipClient({
-      debug,
-    });
-
-    return backgroundClient;
-  }, [debug, log]);
-
-  // Setup effect
-  useEffect(() => {
-    // Listen to connection state changes
-    const connectionStateSubscription = voipClient.connectionState$.subscribe((state) => {
-      setCurrentConnectionState(state);
-
-      // Just log connection changes, let the app handle navigation
-      log(`Connection state changed to: ${state}`);
-    });
-
-    // Listen to call changes to reset flags when no active calls
-    const callsSubscription = voipClient.calls$.subscribe((calls) => {
-      // Check if we should reset flags - only reset if:
-      // 1. No active WebRTC calls AND
-      // 2. No CallKit operations in progress (to prevent disconnection during CallKit answer flow)
-      const hasActiveWebRTCCalls = calls.length > 0;
-      let hasCallKitProcessing = false;
-
-      // Check CallKit processing calls only on iOS
-      if (Platform.OS === 'ios') {
-        try {
-          const { callKitCoordinator } = require('./callkit/callkit-coordinator');
-          hasCallKitProcessing = callKitCoordinator.hasProcessingCalls();
-          log(`CallKit processing check: hasProcessingCalls=${hasCallKitProcessing}`);
-        } catch (e) {
-          log('Error checking CallKit processing calls:', e);
-        }
-      }
-
-      log(
-        `Flag reset check: WebRTC calls=${calls.length}, CallKit processing=${hasCallKitProcessing}, isHandlingForegroundCall=${isHandlingForegroundCall}, backgroundDetectorIgnore=${backgroundDetectorIgnore.current}`
-      );
-
-      if (
-        !hasActiveWebRTCCalls &&
-        !hasCallKitProcessing &&
-        (isHandlingForegroundCall || backgroundDetectorIgnore.current)
-      ) {
-        log(
-          `No active calls and no CallKit processing - resetting ignore flags at ${new Date().toISOString()}`
-        );
-        setIsHandlingForegroundCall(false);
-        backgroundDetectorIgnore.current = false;
-      } else if (!hasActiveWebRTCCalls && hasCallKitProcessing) {
-        log(
-          `No WebRTC calls but CallKit operations in progress - keeping ignore flags active at ${new Date().toISOString()}`
-        );
-      } else if (hasActiveWebRTCCalls) {
-        log(`WebRTC calls active - keeping ignore flags active at ${new Date().toISOString()}`);
-      }
-
-      // Also reset processingPushOnLaunch if no calls are active
-      // This ensures the flag doesn't get stuck after call ends
-      if (calls.length === 0 && processingPushOnLaunch) {
-        log('No active calls - resetting processing push flag');
-        setProcessingPushOnLaunch(false);
-      }
-    });
-
-    // 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;
-    if (
-      (!skipWebBackgroundDetection || Platform.OS !== 'web') &&
-      voipClient.options.enableAppStateManagement
-    ) {
-      appStateSubscription = AppState.addEventListener('change', handleAppStateChange);
-    }
-
-    // Handle initial push notification if app was launched from terminated state
-    // Only check if we're not already processing to prevent infinite loops
-    const timeoutId = setTimeout(() => {
-      if (!processingPushOnLaunch) {
-        checkForInitialPushNotification();
-      }
-    }, 100);
-
-    // Cleanup function
-    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();
-      }
-      clearTimeout(timeoutId);
-      // Clean up background client instance
-      disposeBackgroundClient();
-    };
-  }, [
-    voipClient,
-    handleAppStateChange,
-    disposeBackgroundClient,
-    skipWebBackgroundDetection,
-    isHandlingForegroundCall,
-    log,
-  ]);
-
-  // Simply return the children wrapped in context provider - all lifecycle management is handled internally
-  return <TelnyxVoiceProvider voipClient={voipClient}>{children}</TelnyxVoiceProvider>;
-};
-
-/**
- * Static factory method that handles all common SDK initialization boilerplate.
- *
- * This is the recommended way to initialize the Telnyx Voice SDK in your app.
- * It ensures that push notifications, background handlers, and other dependencies are
- * set up correctly before the app runs.
- *
- * This method:
- * - Initializes push notification handling
- * - Registers the background push notification handler
- * - Returns a fully configured TelnyxVoiceApp component to be used in your app
- *
- * ## Usage:
- * ```tsx
- * const App = TelnyxVoiceApp.initializeAndCreate({
- *   voipClient: myVoipClient,
- *   backgroundHandler: backgroundHandler,
- *   children: <MyApp />,
- * });
- * ```
- */
-const initializeAndCreate = async (options: {
-  /** The TelnyxVoipClient instance that will be managed by this component */
-  voipClient: TelnyxVoipClient;
-
-  /** The main component of your application */
-  children: React.ReactNode;
-
-  /** The function that will handle background push notifications */
-  backgroundMessageHandler?: (message: any) => Promise<void>;
-
-  /** Optional callback when push notification processing starts */
-  onPushNotificationProcessingStarted?: () => void;
-
-  /** Optional callback when push notification processing completes */
-  onPushNotificationProcessingCompleted?: () => void;
-
-  /** Optional callback for app state changes */
-  onAppStateChanged?: (state: AppStateStatus) => void;
-
-  /** Whether to enable automatic reconnection (default: true) */
-  enableAutoReconnect?: boolean;
-
-  /** Whether to skip web background detection (default: true) */
-  skipWebBackgroundDetection?: boolean;
-
-  /** Enable debug logging */
-  debug?: boolean;
-}): Promise<React.ComponentType> => {
-  const {
-    voipClient,
-    children,
-    backgroundMessageHandler,
-    onPushNotificationProcessingStarted,
-    onPushNotificationProcessingCompleted,
-    onAppStateChanged,
-    enableAutoReconnect = true,
-    skipWebBackgroundDetection = true,
-    debug = false,
-  } = options;
-
-  // Initialize push notification handling for Android
-  if (Platform.OS === 'android') {
-    // TODO: Initialize Firebase or other push notification service
-    if (debug) {
-      console.log('[TelnyxVoiceApp] Android push notification initialization needed');
-    }
-  }
-
-  // Register background message handler if provided
-  if (backgroundMessageHandler) {
-    // TODO: Register the background message handler with the push notification service
-    if (debug) {
-      console.log('[TelnyxVoiceApp] Background message handler registration needed');
-    }
-  }
-
-  if (debug) {
-    console.log('[TelnyxVoiceApp] SDK initialization complete');
-  }
-
-  // Return a component that renders TelnyxVoiceApp with the provided options
-  return () => (
-    <TelnyxVoiceApp
-      voipClient={voipClient}
-      onPushNotificationProcessingStarted={onPushNotificationProcessingStarted}
-      onPushNotificationProcessingCompleted={onPushNotificationProcessingCompleted}
-      onAppStateChanged={onAppStateChanged}
-      enableAutoReconnect={enableAutoReconnect}
-      skipWebBackgroundDetection={skipWebBackgroundDetection}
-      debug={debug}
-    >
-      {children}
-    </TelnyxVoiceApp>
-  );
-};
-
-/**
- * Handles background push notifications in the background isolate.
- * This should be called from your background message handler.
- */
-const handleBackgroundPush = async (message: any): Promise<void> => {
-  console.log('[TelnyxVoiceApp] Background push received:', message);
-
-  try {
-    // TODO: Initialize push notification service in isolate if needed
-
-    // Use singleton pattern for background client to prevent multiple instances
-    let backgroundClient = createBackgroundTelnyxVoipClient({
-      debug: true,
-    });
-
-    await backgroundClient.handlePushNotification(message);
-
-    console.log('[TelnyxVoiceApp] Background push processed successfully');
-
-    // Clean up the background client
-    backgroundClient.dispose();
-  } catch (e) {
-    console.log('[TelnyxVoiceApp] Error processing background push:', e);
-  }
-};
-
-// Create the component with static methods
-export const TelnyxVoiceApp: TelnyxVoiceAppComponent = Object.assign(TelnyxVoiceAppComponent, {
-  initializeAndCreate,
-  handleBackgroundPush,
-});
-
-export default TelnyxVoiceApp;
+import React, { useEffect, useRef, useState, useCallback } from 'react';
+import { AppState, AppStateStatus, Platform } from 'react-native';
+import { TelnyxVoipClient, createBackgroundTelnyxVoipClient } from './telnyx-voip-client';
+import { TelnyxConnectionState } from './models/connection-state';
+import { Call } from './models/call';
+import { TelnyxVoiceProvider } from './context/TelnyxVoiceContext';
+
+/**
+ * Configuration options for TelnyxVoiceApp
+ */
+export interface TelnyxVoiceAppOptions {
+  /** The TelnyxVoipClient instance to manage */
+  voipClient: TelnyxVoipClient;
+
+  /** Optional callback when push notification processing starts */
+  onPushNotificationProcessingStarted?: () => void;
+
+  /** Optional callback when push notification processing completes */
+  onPushNotificationProcessingCompleted?: () => void;
+
+  /** Optional callback for additional background/foreground handling */
+  onAppStateChanged?: (state: AppStateStatus) => void;
+
+  /** Whether to enable automatic login/reconnection (default: true) */
+  enableAutoReconnect?: boolean;
+
+  /** Whether to skip web platform for background detection (default: true) */
+  skipWebBackgroundDetection?: boolean;
+
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+/**
+ * Props for the TelnyxVoiceApp component
+ */
+export interface TelnyxVoiceAppProps extends TelnyxVoiceAppOptions {
+  /** The child components to render */
+  children: React.ReactNode;
+}
+
+/**
+ * Interface for the TelnyxVoiceApp component with static methods
+ */
+export interface TelnyxVoiceAppComponent extends React.FC<TelnyxVoiceAppProps> {
+  initializeAndCreate: (options: {
+    voipClient: TelnyxVoipClient;
+    children: React.ReactNode;
+    backgroundMessageHandler?: (message: any) => Promise<void>;
+    onPushNotificationProcessingStarted?: () => void;
+    onPushNotificationProcessingCompleted?: () => void;
+    onAppStateChanged?: (state: AppStateStatus) => void;
+    enableAutoReconnect?: boolean;
+    skipWebBackgroundDetection?: boolean;
+    debug?: boolean;
+  }) => Promise<React.ComponentType>;
+
+  handleBackgroundPush: (message: any) => Promise<void>;
+}
+
+/**
+ * A comprehensive wrapper component that handles all Telnyx SDK lifecycle management.
+ *
+ * This component automatically handles:
+ * - Push notification initialization from terminated state
+ * - Background/foreground lifecycle detection and auto-reconnection
+ * - Login state management with automatic reconnection
+ * - CallKit integration preparation
+ *
+ * Simply wrap your main app component with this to get full Telnyx functionality:
+ * ```tsx
+ * <TelnyxVoiceApp voipClient={myVoipClient}>
+ *   <MyApp />
+ * </TelnyxVoiceApp>
+ * ```
+ */
+const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
+  voipClient,
+  children,
+  onPushNotificationProcessingStarted,
+  onPushNotificationProcessingCompleted,
+  onAppStateChanged,
+  enableAutoReconnect = true,
+  skipWebBackgroundDetection = true,
+  debug = false,
+}) => {
+  // State management
+  const [processingPushOnLaunch, setProcessingPushOnLaunch] = useState(false);
+  const [isHandlingForegroundCall, setIsHandlingForegroundCall] = useState(false);
+  const [currentConnectionState, setCurrentConnectionState] = useState<TelnyxConnectionState>(
+    voipClient.currentConnectionState
+  );
+
+  // Refs for tracking state
+  const appStateRef = useRef<AppStateStatus>(AppState.currentState);
+  const backgroundDetectorIgnore = useRef(false);
+
+  // Static background client instance for singleton pattern
+  const backgroundClientRef = useRef<TelnyxVoipClient | null>(null);
+
+  const log = useCallback(
+    (message: string, ...args: any[]) => {
+      if (debug) {
+        console.log(`[TelnyxVoiceApp] ${message}`, ...args);
+      }
+    },
+    [debug]
+  );
+
+  // Handle app state changes
+  const handleAppStateChange = useCallback(
+    async (nextAppState: AppStateStatus) => {
+      const previousAppState = appStateRef.current;
+      appStateRef.current = nextAppState;
+
+      log(`App state changed from ${previousAppState} to ${nextAppState}`);
+      log(`Background detector ignore flag: ${backgroundDetectorIgnore.current}`);
+      log(`Handling foreground call: ${isHandlingForegroundCall}`);
+
+      // Call optional user callback first
+      onAppStateChanged?.(nextAppState);
+
+      // Only handle background disconnection when actually transitioning from active to background
+      // Don't disconnect on background-to-background transitions (e.g., during CallKit operations)
+      if (
+        (nextAppState === 'background' || nextAppState === 'inactive') &&
+        previousAppState === 'active'
+      ) {
+        log(
+          `App transitioned from ${previousAppState} to ${nextAppState} - handling backgrounding`
+        );
+        await handleAppBackgrounded();
+      } else if (nextAppState === 'background' || nextAppState === 'inactive') {
+        log(
+          `App state is ${nextAppState} but was already ${previousAppState} - skipping background handling`
+        );
+      }
+
+      // Always check for push notifications when app becomes active (regardless of auto-reconnect setting)
+      if (nextAppState === 'active' && previousAppState !== 'active') {
+        log('App became active - checking for push notifications');
+        await checkForInitialPushNotification(true); // Pass true for fromAppResume
+      }
+
+      // Only handle auto-reconnection if auto-reconnect is enabled
+      if (enableAutoReconnect && nextAppState === 'active' && previousAppState !== 'active') {
+        await handleAppResumed();
+      }
+    },
+    [enableAutoReconnect, onAppStateChanged, isHandlingForegroundCall, log]
+  );
+
+  // Handle app going to background - disconnect like the old implementation
+  const handleAppBackgrounded = useCallback(async () => {
+    // Check if we should ignore background detection (e.g., during active calls)
+    if (backgroundDetectorIgnore.current || isHandlingForegroundCall) {
+      log(
+        'Background detector ignore flag set or handling foreground call - skipping disconnection'
+      );
+      return;
+    }
+
+    // Check if there are any active calls that should prevent disconnection
+    const activeCalls = voipClient.currentCalls;
+    const hasOngoingCall =
+      activeCalls.length > 0 &&
+      activeCalls.some(
+        (call) =>
+          call.currentState === 'ACTIVE' ||
+          call.currentState === 'HELD' ||
+          call.currentState === 'RINGING' ||
+          call.currentState === 'CONNECTING'
+      );
+
+    // Also check if there's an incoming call from push notification being processed
+    let isCallFromPush = false;
+    if (Platform.OS === 'ios') {
+      try {
+        const { callKitCoordinator } = require('./callkit/callkit-coordinator');
+        isCallFromPush = callKitCoordinator.getIsCallFromPush();
+      } catch (e) {
+        log('Error checking isCallFromPush:', e);
+      }
+    }
+
+    if (hasOngoingCall || isCallFromPush) {
+      log('Active calls or push call detected - skipping background disconnection', {
+        callCount: activeCalls.length,
+        hasOngoingCall,
+        isCallFromPush,
+        callStates: activeCalls.map((call) => ({
+          callId: call.callId,
+          currentState: call.currentState,
+          destination: call.destination,
+        })),
+      });
+      return;
+    }
+
+    log('App backgrounded - disconnecting (matching old BackgroundDetector behavior)');
+
+    try {
+      // Always disconnect when backgrounded (matches old implementation)
+      await voipClient.logout();
+      log('Successfully disconnected on background');
+    } catch (e) {
+      log('Error disconnecting on background:', e);
+    }
+  }, [voipClient, isHandlingForegroundCall, log]);
+
+  // Handle app resuming from background
+  const handleAppResumed = useCallback(async () => {
+    log('App resumed - checking reconnection needs');
+
+    // IMPORTANT: Check for push notifications first when resuming from background
+    // This handles the case where the user accepted a call while the app was backgrounded
+    await checkForInitialPushNotification(true); // Pass true for fromAppResume
+
+    // If we're ignoring (e.g., from push call) or handling foreground call, don't auto-reconnect
+    if (backgroundDetectorIgnore.current || isHandlingForegroundCall) {
+      log(
+        'Background detector ignore flag set or handling foreground call - skipping reconnection'
+      );
+      return;
+    }
+
+    // iOS-specific: If push notification handling just initiated a connection,
+    // skip auto-reconnection to prevent double login
+    if (Platform.OS === 'ios') {
+      // Check if connection state changed after push processing
+      const connectionStateAfterPush = voipClient.currentConnectionState;
+      if (
+        connectionStateAfterPush === TelnyxConnectionState.CONNECTING ||
+        connectionStateAfterPush === TelnyxConnectionState.CONNECTED
+      ) {
+        log(
+          `iOS: Push handling initiated connection (${connectionStateAfterPush}), skipping auto-reconnection`
+        );
+        return;
+      }
+    }
+
+    // Check current connection state and reconnect if needed
+    const currentState = voipClient.currentConnectionState;
+    log(`Current connection state: ${currentState}`);
+
+    // If we're not connected and have stored credentials, attempt reconnection
+    if (currentState !== TelnyxConnectionState.CONNECTED) {
+      await attemptAutoReconnection();
+    }
+  }, [voipClient, isHandlingForegroundCall, log]);
+
+  // Attempt to reconnect using stored credentials
+  const attemptAutoReconnection = useCallback(async () => {
+    try {
+      log('Attempting auto-reconnection...');
+
+      // Try to get stored config and reconnect
+      const success = await voipClient.loginFromStoredConfig();
+      log(`Auto-reconnection ${success ? 'successful' : 'failed'}`);
+
+      // If auto-reconnection fails, redirect to login screen
+      if (!success) {
+        log('Auto-reconnection failed - redirecting to login screen');
+      }
+    } catch (e) {
+      log('Auto-reconnection error:', e);
+      // On error, also redirect to login
+      log('Auto-reconnection error - redirecting to login screen');
+    }
+  }, [voipClient, log]);
+
+  // Check for initial push notification action when app launches
+  const checkForInitialPushNotification = useCallback(
+    async (fromAppResume: boolean = false) => {
+      log(`checkForInitialPushNotification called${fromAppResume ? ' (from app resume)' : ''}`);
+
+      if (processingPushOnLaunch && !fromAppResume) {
+        log('Already processing push, returning early');
+        return;
+      }
+
+      // Only set the flag if this is not from app resume to allow resume processing
+      if (!fromAppResume) {
+        setProcessingPushOnLaunch(true);
+      }
+      onPushNotificationProcessingStarted?.();
+
+      try {
+        let pushData: Record<string, any> | null = null;
+
+        // Try to get push data from the native layer using platform-specific methods
+        if (Platform.OS === 'android') {
+          try {
+            // Import the native bridge module dynamically
+            const { NativeModules } = require('react-native');
+            const VoicePnBridge = NativeModules.VoicePnBridge;
+
+            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);
+
+              if (pendingAction && pendingAction.action != null && pendingAction.metadata != null) {
+                log('Found pending push action:', pendingAction);
+
+                // Parse the metadata if it's a string
+                let metadata = pendingAction.metadata;
+                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
+                pushData = {
+                  action: pendingAction.action,
+                  metadata: metadata,
+                  from_notification: true,
+                };
+
+                // Clear the pending action so it doesn't get processed again
+                await VoicePnBridge.clearPendingPushAction();
+                log('Cleared pending push action after retrieval');
+              } else {
+                log('No pending push actions found');
+              }
+            } else {
+              log('VoicePnBridge not available on Android');
+            }
+          } catch (bridgeError) {
+            log('Error accessing VoicePnBridge on Android:', bridgeError);
+          }
+        } else if (Platform.OS === 'ios') {
+          try {
+            // Import the native bridge module dynamically (same as Android)
+            const { NativeModules } = require('react-native');
+            const VoicePnBridge = NativeModules.VoicePnBridge;
+            
+            if (VoicePnBridge) {
+              log('Checking for pending VoIP push data via iOS VoicePnBridge');
+
+              // Check for VoIP push notification data stored by the native push handler
+              const pendingVoipPushJson = await VoicePnBridge.getPendingVoipPush();
+              log('Raw pending VoIP push response:', pendingVoipPushJson);
+
+              if (pendingVoipPushJson) {
+                try {
+                  const pendingVoipPush = JSON.parse(pendingVoipPushJson);
+                  const voipPayload = pendingVoipPush?.payload;
+                  
+                  if (voipPayload && voipPayload.metadata) {
+                    log('Found pending VoIP push data:', voipPayload);
+
+                    // Create push data structure that matches what the VoIP client expects
+                    pushData = {
+                      action: 'incoming_call',
+                      metadata: voipPayload.metadata,
+                      from_notification: true,
+                    };
+
+                    // Clear the pending VoIP push data so it doesn't get processed again
+                    await VoicePnBridge.clearPendingVoipPush();
+                    log('Cleared pending VoIP push data after retrieval');
+                  } else {
+                    log('Invalid VoIP push data structure');
+                  }
+                } catch (parseError) {
+                  log('Error parsing VoIP push JSON:', parseError);
+                }
+              } else {
+                log('No pending VoIP push data found');
+              }
+            } else {
+              log('VoicePnBridge not available on iOS');
+            }
+          } catch (bridgeError) {
+            log('Error accessing VoicePnBridge on iOS:', bridgeError);
+          }
+        } else {
+          log('Push data check skipped - unsupported platform');
+        }
+
+        // Process the push notification if found
+        if (pushData) {
+          log('Processing initial push notification...');
+
+          // Check if we're already connected and handling a push - prevent duplicate processing
+          const isConnected = voipClient.currentConnectionState === TelnyxConnectionState.CONNECTED;
+          if (isConnected) {
+            log('SKIPPING - Already connected, preventing duplicate processing');
+            // Clear the stored data since we're already handling it
+            // TODO: Implement clearPushMetaData
+            return;
+          }
+
+          // Set flags to prevent auto-reconnection during push call
+          setIsHandlingForegroundCall(true);
+          backgroundDetectorIgnore.current = true;
+          log(`Background detector ignore set to: true at ${new Date().toISOString()}`);
+          log(`Foreground call handling flag set to: true at ${new Date().toISOString()}`);
+
+          // Dispose any existing background client to prevent conflicts
+          disposeBackgroundClient();
+
+          // Handle the push notification using platform-specific approach
+          if (Platform.OS === 'ios') {
+            // On iOS, coordinate with CallKit by notifying the coordinator about the push
+            const { callKitCoordinator } = require('./callkit/callkit-coordinator');
+
+            // Extract call_id from nested metadata structure to use as CallKit UUID
+            const callId = pushData.metadata?.metadata?.call_id;
+            if (callId) {
+              log('Notifying CallKit coordinator about push notification:', callId);
+              await callKitCoordinator.handleCallKitPushReceived(callId, {
+                callData: { source: 'push_notification' },
+                pushData: pushData,
+              });
+            } else {
+              log('No call_id found in push data, falling back to direct handling');
+              await voipClient.handlePushNotification(pushData);
+            }
+          } else {
+            // On other platforms, handle push notification directly
+            await voipClient.handlePushNotification(pushData);
+          }
+
+          log('Initial push notification processed');
+          log('Cleared stored push data to prevent duplicate processing');
+
+          // Note: isHandlingForegroundCall will be reset when calls.length becomes 0
+          // This prevents premature disconnection during CallKit answer flow
+        } 
+        else {
+          log('No initial push data found');
+        }
+      } catch (e) {
+        log('Error processing initial push notification:', e);
+        // Reset flags on error
+        setIsHandlingForegroundCall(false);
+      } finally {
+        // Always reset the processing flag - it should not remain stuck
+        setProcessingPushOnLaunch(false);
+        onPushNotificationProcessingCompleted?.();
+      }
+    },
+    [
+      processingPushOnLaunch,
+      voipClient,
+      onPushNotificationProcessingStarted,
+      onPushNotificationProcessingCompleted,
+      log,
+    ]
+  );
+
+  // Dispose background client instance when no longer needed
+  const disposeBackgroundClient = useCallback(() => {
+    if (backgroundClientRef.current) {
+      log('Disposing background client instance');
+      backgroundClientRef.current.dispose();
+      backgroundClientRef.current = null;
+    }
+  }, [log]);
+
+  // Create background client for push notification handling
+  const createBackgroundClient = useCallback((): TelnyxVoipClient => {
+    log('Creating background client instance');
+
+    const backgroundClient = createBackgroundTelnyxVoipClient({
+      debug,
+    });
+
+    return backgroundClient;
+  }, [debug, log]);
+
+  // Setup effect
+  useEffect(() => {
+    // Listen to connection state changes
+    const connectionStateSubscription = voipClient.connectionState$.subscribe((state) => {
+      setCurrentConnectionState(state);
+
+      // Just log connection changes, let the app handle navigation
+      log(`Connection state changed to: ${state}`);
+    });
+
+    // Listen to call changes to reset flags when no active calls
+    const callsSubscription = voipClient.calls$.subscribe((calls) => {
+      // Check if we should reset flags - only reset if:
+      // 1. No active WebRTC calls AND
+      // 2. No CallKit operations in progress (to prevent disconnection during CallKit answer flow)
+      const hasActiveWebRTCCalls = calls.length > 0;
+      let hasCallKitProcessing = false;
+
+      // Check CallKit processing calls only on iOS
+      if (Platform.OS === 'ios') {
+        try {
+          const { callKitCoordinator } = require('./callkit/callkit-coordinator');
+          hasCallKitProcessing = callKitCoordinator.hasProcessingCalls();
+          log(`CallKit processing check: hasProcessingCalls=${hasCallKitProcessing}`);
+        } catch (e) {
+          log('Error checking CallKit processing calls:', e);
+        }
+      }
+
+      log(
+        `Flag reset check: WebRTC calls=${calls.length}, CallKit processing=${hasCallKitProcessing}, isHandlingForegroundCall=${isHandlingForegroundCall}, backgroundDetectorIgnore=${backgroundDetectorIgnore.current}`
+      );
+
+      if (
+        !hasActiveWebRTCCalls &&
+        !hasCallKitProcessing &&
+        (isHandlingForegroundCall || backgroundDetectorIgnore.current)
+      ) {
+        log(
+          `No active calls and no CallKit processing - resetting ignore flags at ${new Date().toISOString()}`
+        );
+        setIsHandlingForegroundCall(false);
+        backgroundDetectorIgnore.current = false;
+      } else if (!hasActiveWebRTCCalls && hasCallKitProcessing) {
+        log(
+          `No WebRTC calls but CallKit operations in progress - keeping ignore flags active at ${new Date().toISOString()}`
+        );
+      } else if (hasActiveWebRTCCalls) {
+        log(`WebRTC calls active - keeping ignore flags active at ${new Date().toISOString()}`);
+      }
+
+      // Also reset processingPushOnLaunch if no calls are active
+      // This ensures the flag doesn't get stuck after call ends
+      if (calls.length === 0 && processingPushOnLaunch) {
+        log('No active calls - resetting processing push flag');
+        setProcessingPushOnLaunch(false);
+      }
+    });
+
+    // 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;
+    if (
+      (!skipWebBackgroundDetection || Platform.OS !== 'web') &&
+      voipClient.options.enableAppStateManagement
+    ) {
+      appStateSubscription = AppState.addEventListener('change', handleAppStateChange);
+    }
+
+    // Handle initial push notification if app was launched from terminated state
+    // Only check if we're not already processing to prevent infinite loops
+    const timeoutId = setTimeout(() => {
+      if (!processingPushOnLaunch) {
+        checkForInitialPushNotification();
+      }
+    }, 100);
+
+    // Cleanup function
+    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();
+      }
+      clearTimeout(timeoutId);
+      // Clean up background client instance
+      disposeBackgroundClient();
+    };
+  }, [
+    voipClient,
+    handleAppStateChange,
+    disposeBackgroundClient,
+    skipWebBackgroundDetection,
+    isHandlingForegroundCall,
+    log,
+  ]);
+
+  // Simply return the children wrapped in context provider - all lifecycle management is handled internally
+  return <TelnyxVoiceProvider voipClient={voipClient}>{children}</TelnyxVoiceProvider>;
+};
+
+/**
+ * Static factory method that handles all common SDK initialization boilerplate.
+ *
+ * This is the recommended way to initialize the Telnyx Voice SDK in your app.
+ * It ensures that push notifications, background handlers, and other dependencies are
+ * set up correctly before the app runs.
+ *
+ * This method:
+ * - Initializes push notification handling
+ * - Registers the background push notification handler
+ * - Returns a fully configured TelnyxVoiceApp component to be used in your app
+ *
+ * ## Usage:
+ * ```tsx
+ * const App = TelnyxVoiceApp.initializeAndCreate({
+ *   voipClient: myVoipClient,
+ *   backgroundHandler: backgroundHandler,
+ *   children: <MyApp />,
+ * });
+ * ```
+ */
+const initializeAndCreate = async (options: {
+  /** The TelnyxVoipClient instance that will be managed by this component */
+  voipClient: TelnyxVoipClient;
+
+  /** The main component of your application */
+  children: React.ReactNode;
+
+  /** The function that will handle background push notifications */
+  backgroundMessageHandler?: (message: any) => Promise<void>;
+
+  /** Optional callback when push notification processing starts */
+  onPushNotificationProcessingStarted?: () => void;
+
+  /** Optional callback when push notification processing completes */
+  onPushNotificationProcessingCompleted?: () => void;
+
+  /** Optional callback for app state changes */
+  onAppStateChanged?: (state: AppStateStatus) => void;
+
+  /** Whether to enable automatic reconnection (default: true) */
+  enableAutoReconnect?: boolean;
+
+  /** Whether to skip web background detection (default: true) */
+  skipWebBackgroundDetection?: boolean;
+
+  /** Enable debug logging */
+  debug?: boolean;
+}): Promise<React.ComponentType> => {
+  const {
+    voipClient,
+    children,
+    backgroundMessageHandler,
+    onPushNotificationProcessingStarted,
+    onPushNotificationProcessingCompleted,
+    onAppStateChanged,
+    enableAutoReconnect = true,
+    skipWebBackgroundDetection = true,
+    debug = false,
+  } = options;
+
+  // Initialize push notification handling for Android
+  if (Platform.OS === 'android') {
+    // TODO: Initialize Firebase or other push notification service
+    if (debug) {
+      console.log('[TelnyxVoiceApp] Android push notification initialization needed');
+    }
+  }
+
+  // Register background message handler if provided
+  if (backgroundMessageHandler) {
+    // TODO: Register the background message handler with the push notification service
+    if (debug) {
+      console.log('[TelnyxVoiceApp] Background message handler registration needed');
+    }
+  }
+
+  if (debug) {
+    console.log('[TelnyxVoiceApp] SDK initialization complete');
+  }
+
+  // Return a component that renders TelnyxVoiceApp with the provided options
+  return () => (
+    <TelnyxVoiceApp
+      voipClient={voipClient}
+      onPushNotificationProcessingStarted={onPushNotificationProcessingStarted}
+      onPushNotificationProcessingCompleted={onPushNotificationProcessingCompleted}
+      onAppStateChanged={onAppStateChanged}
+      enableAutoReconnect={enableAutoReconnect}
+      skipWebBackgroundDetection={skipWebBackgroundDetection}
+      debug={debug}
+    >
+      {children}
+    </TelnyxVoiceApp>
+  );
+};
+
+/**
+ * Handles background push notifications in the background isolate.
+ * This should be called from your background message handler.
+ */
+const handleBackgroundPush = async (message: any): Promise<void> => {
+  console.log('[TelnyxVoiceApp] Background push received:', message);
+
+  try {
+    // TODO: Initialize push notification service in isolate if needed
+
+    // Use singleton pattern for background client to prevent multiple instances
+    let backgroundClient = createBackgroundTelnyxVoipClient({
+      debug: true,
+    });
+
+    await backgroundClient.handlePushNotification(message);
+
+    console.log('[TelnyxVoiceApp] Background push processed successfully');
+
+    // Clean up the background client
+    backgroundClient.dispose();
+  } catch (e) {
+    console.log('[TelnyxVoiceApp] Error processing background push:', e);
+  }
+};
+
+// Create the component with static methods
+export const TelnyxVoiceApp: TelnyxVoiceAppComponent = Object.assign(TelnyxVoiceAppComponent, {
+  initializeAndCreate,
+  handleBackgroundPush,
+});
+
+export default TelnyxVoiceApp;