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

package/ios/README.md

@@ -1,211 +1,211 @@
-# Telnyx Voice Commons - iOS Integration
-
-This document explains how to integrate the iOS CallKit and VoIP push notification functionality into your React Native app.
-
-## 📋 **Prerequisites**
-
-1. iOS deployment target 13.0 or higher
-2. Valid Apple Developer account with VoIP push notification entitlements
-3. Telnyx account with Voice SDK access
-
-## 🚀 **Installation**
-
-1. Install the react-voice-commons package
-2. Add VoIP background mode to your Info.plist
-3. Set up your AppDelegate
-
-## ⚙️ **Setup**
-
-### 1. Info.plist Configuration
-
-Add the following to your iOS app's `Info.plist`:
-
-```xml
-<key>UIBackgroundModes</key>
-<array>
-    <string>voip</string>
-</array>
-
-<key>NSMicrophoneUsageDescription</key>
-<string>This app needs microphone access to make voice calls</string>
-```
-
-### 2. AppDelegate Integration
-
-#### Option A: Easy Integration (Recommended)
-
-Import and use the `TelnyxVoiceAppDelegate` protocol:
-
-```swift
-import TelnyxVoiceCommons
-
-class AppDelegate: ExpoAppDelegate, TelnyxVoiceAppDelegate {
-    // Required properties for TelnyxVoiceAppDelegate
-    var voipRegistry: PKPushRegistry?
-    var callKitProvider: CXProvider?
-    var callKitController: CXCallController?
-    var activeCalls: [UUID: [String: Any]] = [:]
-
-    override func application(
-        _ application: UIApplication,
-        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
-    ) -> Bool {
-        // Your existing setup code...
-
-        // Add Telnyx Voice setup
-        setupTelnyxVoice()
-
-        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
-    }
-
-    // Optionally customize CallKit configuration
-    override func customCallKitConfiguration() -> CXProviderConfiguration {
-        let configuration = CXProviderConfiguration(localizedName: "My App Voice")
-        configuration.supportsVideo = false
-        configuration.maximumCallGroups = 1
-        configuration.maximumCallsPerCallGroup = 1
-        configuration.supportedHandleTypes = [.phoneNumber, .generic]
-        configuration.includesCallsInRecents = true
-        return configuration
-    }
-}
-
-// Automatically get PKPushRegistryDelegate methods
-extension AppDelegate: PKPushRegistryDelegate {}
-
-// Automatically get CXProviderDelegate methods
-extension AppDelegate: CXProviderDelegate {}
-```
-
-#### Option B: Manual Integration
-
-If you prefer to implement the delegates manually:
-
-```swift
-import PushKit
-import CallKit
-import AVFoundation
-
-class AppDelegate: ExpoAppDelegate {
-    var voipRegistry: PKPushRegistry?
-    var callKitProvider: CXProvider?
-    var callKitController: CXCallController?
-    var activeCalls: [UUID: [String: Any]] = [:]
-
-    override func application(
-        _ application: UIApplication,
-        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
-    ) -> Bool {
-        // Your existing setup...
-
-        setupVoIPPushNotifications()
-        setupCallKit()
-
-        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
-    }
-
-    private func setupVoIPPushNotifications() {
-        voipRegistry = PKPushRegistry(queue: DispatchQueue.main)
-        voipRegistry?.delegate = self
-        voipRegistry?.desiredPushTypes = [PKPushType.voIP]
-    }
-
-    private func setupCallKit() {
-        let configuration = CXProviderConfiguration(localizedName: "Voice Call")
-        configuration.supportsVideo = false
-        configuration.maximumCallGroups = 1
-        configuration.maximumCallsPerCallGroup = 1
-        configuration.supportedHandleTypes = [.phoneNumber, .generic]
-        configuration.includesCallsInRecents = true
-
-        callKitProvider = CXProvider(configuration: configuration)
-        callKitProvider?.setDelegate(self, queue: nil)
-        callKitController = CXCallController()
-    }
-}
-
-extension AppDelegate: PKPushRegistryDelegate {
-    // Implement push notification methods...
-    // (See TelnyxVoiceAppDelegate.swift for full implementation)
-}
-
-extension AppDelegate: CXProviderDelegate {
-    // Implement CallKit delegate methods...
-    // (See TelnyxVoiceAppDelegate.swift for full implementation)
-}
-```
-
-## 🔧 **iOS Project Configuration**
-
-### 1. Enable VoIP Background Mode
-
-In Xcode:
-
-1. Select your project target
-2. Go to "Signing & Capabilities"
-3. Add "Background Modes" capability
-4. Check "Voice over IP"
-
-### 2. Add Push Notification Entitlement
-
-1. Add "Push Notifications" capability
-2. Ensure VoIP push notifications are enabled in your Apple Developer account
-
-## 📱 **Usage in React Native**
-
-After setting up the iOS native code, use the library in your React Native code:
-
-```typescript
-import { createTelnyxVoipClient } from '@telnyx/react-voice-commons-sdk';
-
-const voipClient = createTelnyxVoipClient({
-  enableNativeUI: true, // Enable CallKit integration
-  enableBackgroundHandling: true,
-  debug: true,
-});
-
-// Login and make calls as usual
-await voipClient.login({
-  sipUser: 'your-sip-user',
-  sipPassword: 'your-password',
-  debug: true,
-});
-```
-
-## 🎯 **Features**
-
-With this setup, your app will automatically get:
-
-- ✅ Native iOS CallKit interface for incoming/outgoing calls
-- ✅ VoIP push notifications for incoming calls
-- ✅ Background call handling
-- ✅ Call history integration
-- ✅ Native call controls (answer, end, hold)
-- ✅ Audio session management
-- ✅ Automatic CallKit synchronization
-
-## 🐛 **Troubleshooting**
-
-### Common Issues:
-
-1. **CallKit not showing**: Ensure VoIP background mode is enabled in Info.plist
-2. **Push notifications not working**: Check that VoIP push entitlements are properly configured
-3. **Audio issues**: Verify microphone permissions and audio session setup
-4. **Build errors**: Make sure iOS deployment target is 13.0+
-
-### Debug Logs:
-
-Enable debug logging to see detailed CallKit integration logs:
-
-```swift
-// In your AppDelegate setup
-setupTelnyxVoice()
-```
-
-Look for logs prefixed with `TelnyxVoice:` in the Xcode console.
-
-## 📚 **Additional Resources**
-
-- [Apple CallKit Documentation](https://developer.apple.com/documentation/callkit)
-- [VoIP Push Notifications Guide](https://developer.apple.com/documentation/pushkit)
-- [Telnyx Voice API Documentation](https://developers.telnyx.com/docs/v2/voice)
+# Telnyx Voice Commons - iOS Integration
+
+This document explains how to integrate the iOS CallKit and VoIP push notification functionality into your React Native app.
+
+## 📋 **Prerequisites**
+
+1. iOS deployment target 13.0 or higher
+2. Valid Apple Developer account with VoIP push notification entitlements
+3. Telnyx account with Voice SDK access
+
+## 🚀 **Installation**
+
+1. Install the react-voice-commons package
+2. Add VoIP background mode to your Info.plist
+3. Set up your AppDelegate
+
+## ⚙️ **Setup**
+
+### 1. Info.plist Configuration
+
+Add the following to your iOS app's `Info.plist`:
+
+```xml
+<key>UIBackgroundModes</key>
+<array>
+    <string>voip</string>
+</array>
+
+<key>NSMicrophoneUsageDescription</key>
+<string>This app needs microphone access to make voice calls</string>
+```
+
+### 2. AppDelegate Integration
+
+#### Option A: Easy Integration (Recommended)
+
+Import and use the `TelnyxVoiceAppDelegate` protocol:
+
+```swift
+import TelnyxVoiceCommons
+
+class AppDelegate: ExpoAppDelegate, TelnyxVoiceAppDelegate {
+    // Required properties for TelnyxVoiceAppDelegate
+    var voipRegistry: PKPushRegistry?
+    var callKitProvider: CXProvider?
+    var callKitController: CXCallController?
+    var activeCalls: [UUID: [String: Any]] = [:]
+
+    override func application(
+        _ application: UIApplication,
+        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
+    ) -> Bool {
+        // Your existing setup code...
+
+        // Add Telnyx Voice setup
+        setupTelnyxVoice()
+
+        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
+    }
+
+    // Optionally customize CallKit configuration
+    override func customCallKitConfiguration() -> CXProviderConfiguration {
+        let configuration = CXProviderConfiguration(localizedName: "My App Voice")
+        configuration.supportsVideo = false
+        configuration.maximumCallGroups = 1
+        configuration.maximumCallsPerCallGroup = 1
+        configuration.supportedHandleTypes = [.phoneNumber, .generic]
+        configuration.includesCallsInRecents = true
+        return configuration
+    }
+}
+
+// Automatically get PKPushRegistryDelegate methods
+extension AppDelegate: PKPushRegistryDelegate {}
+
+// Automatically get CXProviderDelegate methods
+extension AppDelegate: CXProviderDelegate {}
+```
+
+#### Option B: Manual Integration
+
+If you prefer to implement the delegates manually:
+
+```swift
+import PushKit
+import CallKit
+import AVFoundation
+
+class AppDelegate: ExpoAppDelegate {
+    var voipRegistry: PKPushRegistry?
+    var callKitProvider: CXProvider?
+    var callKitController: CXCallController?
+    var activeCalls: [UUID: [String: Any]] = [:]
+
+    override func application(
+        _ application: UIApplication,
+        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
+    ) -> Bool {
+        // Your existing setup...
+
+        setupVoIPPushNotifications()
+        setupCallKit()
+
+        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
+    }
+
+    private func setupVoIPPushNotifications() {
+        voipRegistry = PKPushRegistry(queue: DispatchQueue.main)
+        voipRegistry?.delegate = self
+        voipRegistry?.desiredPushTypes = [PKPushType.voIP]
+    }
+
+    private func setupCallKit() {
+        let configuration = CXProviderConfiguration(localizedName: "Voice Call")
+        configuration.supportsVideo = false
+        configuration.maximumCallGroups = 1
+        configuration.maximumCallsPerCallGroup = 1
+        configuration.supportedHandleTypes = [.phoneNumber, .generic]
+        configuration.includesCallsInRecents = true
+
+        callKitProvider = CXProvider(configuration: configuration)
+        callKitProvider?.setDelegate(self, queue: nil)
+        callKitController = CXCallController()
+    }
+}
+
+extension AppDelegate: PKPushRegistryDelegate {
+    // Implement push notification methods...
+    // (See TelnyxVoiceAppDelegate.swift for full implementation)
+}
+
+extension AppDelegate: CXProviderDelegate {
+    // Implement CallKit delegate methods...
+    // (See TelnyxVoiceAppDelegate.swift for full implementation)
+}
+```
+
+## 🔧 **iOS Project Configuration**
+
+### 1. Enable VoIP Background Mode
+
+In Xcode:
+
+1. Select your project target
+2. Go to "Signing & Capabilities"
+3. Add "Background Modes" capability
+4. Check "Voice over IP"
+
+### 2. Add Push Notification Entitlement
+
+1. Add "Push Notifications" capability
+2. Ensure VoIP push notifications are enabled in your Apple Developer account
+
+## 📱 **Usage in React Native**
+
+After setting up the iOS native code, use the library in your React Native code:
+
+```typescript
+import { createTelnyxVoipClient } from '@telnyx/react-voice-commons-sdk';
+
+const voipClient = createTelnyxVoipClient({
+  enableNativeUI: true, // Enable CallKit integration
+  enableBackgroundHandling: true,
+  debug: true,
+});
+
+// Login and make calls as usual
+await voipClient.login({
+  sipUser: 'your-sip-user',
+  sipPassword: 'your-password',
+  debug: true,
+});
+```
+
+## 🎯 **Features**
+
+With this setup, your app will automatically get:
+
+- ✅ Native iOS CallKit interface for incoming/outgoing calls
+- ✅ VoIP push notifications for incoming calls
+- ✅ Background call handling
+- ✅ Call history integration
+- ✅ Native call controls (answer, end, hold)
+- ✅ Audio session management
+- ✅ Automatic CallKit synchronization
+
+## 🐛 **Troubleshooting**
+
+### Common Issues:
+
+1. **CallKit not showing**: Ensure VoIP background mode is enabled in Info.plist
+2. **Push notifications not working**: Check that VoIP push entitlements are properly configured
+3. **Audio issues**: Verify microphone permissions and audio session setup
+4. **Build errors**: Make sure iOS deployment target is 13.0+
+
+### Debug Logs:
+
+Enable debug logging to see detailed CallKit integration logs:
+
+```swift
+// In your AppDelegate setup
+setupTelnyxVoice()
+```
+
+Look for logs prefixed with `TelnyxVoice:` in the Xcode console.
+
+## 📚 **Additional Resources**
+
+- [Apple CallKit Documentation](https://developer.apple.com/documentation/callkit)
+- [VoIP Push Notifications Guide](https://developer.apple.com/documentation/pushkit)
+- [Telnyx Voice API Documentation](https://developers.telnyx.com/docs/v2/voice)

package/lib/callkit/callkit-coordinator.d.ts

@@ -8,119 +8,123 @@ import { TelnyxVoipClient } from '../telnyx-voip-client';
  * guidelines for proper CallKit integration.
  */
 declare class CallKitCoordinator {
-    private static instance;
-    private callMap;
-    private processingCalls;
-    private endedCalls;
-    private connectedCalls;
-    private isCallFromPush;
-    private voipClient;
-    static getInstance(): CallKitCoordinator;
-    private constructor();
-    private setupCallKitListeners;
-    /**
-     * Report an incoming call to CallKit (from push notification or socket)
-     * For push notifications, the call is already reported - we just need to map it
-     */
-    reportIncomingCall(call: Call, callerName: string, callerNumber: string): Promise<string | null>;
-    /**
-     * Start an outgoing call through CallKit
-     */
-    startOutgoingCall(call: Call, destinationNumber: string, displayName?: string): Promise<string | null>;
-    /**
-     * Answer a call from the app UI (CallKit-first approach)
-     */
-    answerCallFromUI(call: Call): Promise<boolean>;
-    /**
-     * End a call from the app UI (CallKit-first approach)
-     */
-    endCallFromUI(call: Call): Promise<boolean>;
-    /**
-     * Handle CallKit answer action (triggered by CallKit)
-     */
-    handleCallKitAnswer(callKitUUID: string, event?: any): Promise<void>;
-    /**
-     * Handle CallKit end action (triggered by CallKit)
-     */
-    private handleCallKitEnd;
-    /**
-     * Handle CallKit start action (triggered by CallKit for outgoing calls)
-     */
-    private handleCallKitStart;
-    /**
-     * Handle CallKit push received event - when a VoIP push notification has been processed
-     * This allows us to coordinate between the push notification and any subsequent WebRTC calls
-     */
-    handleCallKitPushReceived(callKitUUID: string, event?: any): Promise<void>;
-    /**
-     * Handle push notification answer - when user answers from CallKit but we don't have a WebRTC call yet
-     * This is the iOS equivalent of the Android FCM handler
-     */
-    private handlePushNotificationAnswer;
-    /**
-     * Handle push notification reject - when user rejects from CallKit but we don't have a WebRTC call yet
-     * This is the iOS equivalent of the Android FCM handler reject
-     */
-    private handlePushNotificationReject;
-    /**
-     * Set up listeners for WebRTC call state changes
-     */
-    private setupWebRTCCallListeners;
-    /**
-     * Clean up call mappings and listeners
-     */
-    private cleanupCall;
-    /**
-     * Get CallKit UUID for a WebRTC call
-     */
-    getCallKitUUID(call: Call): string | null;
-    /**
-     * Get WebRTC call for a CallKit UUID
-     */
-    getWebRTCCall(callKitUUID: string): Call | null;
-    /**
-     * Link an existing CallKit call (from push notification) with a WebRTC call
-     * This should be called when a WebRTC call arrives that corresponds to an existing CallKit call
-     */
-    linkExistingCallKitCall(call: Call, callKitUUID: string): void;
-    /**
-     * Set the VoIP client reference for triggering reconnection
-     */
-    setVoipClient(voipClient: TelnyxVoipClient): void;
-    /**
-     * Helper method to handle auto-answer logic for push notification calls
-     */
-    private handleAutoAnswer;
-    /**
-     * Helper method to clean up push notification state
-     */
-    private cleanupPushNotificationState;
-    /**
-     * Get reference to the SDK client (for queuing actions when call doesn't exist yet)
-     */
-    private getSDKClient;
-    /**
-     * Check if app is in background and disconnect client if no active calls
-     */
-    private checkBackgroundDisconnection;
-    /**
-     * Reset only flags (keeping active call mappings intact)
-     */
-    resetFlags(): void;
-    /**
-     * Check if there are any calls currently being processed by CallKit
-     * This helps prevent premature flag resets during CallKit operations
-     */
-    hasProcessingCalls(): boolean;
-    /**
-     * Check if there's currently a call from push notification being processed
-     * This helps prevent disconnection during push call handling
-     */
-    getIsCallFromPush(): boolean;
-    /**
-     * Check if CallKit is available and coordinator is active
-     */
-    isAvailable(): boolean;
+  private static instance;
+  private callMap;
+  private processingCalls;
+  private endedCalls;
+  private connectedCalls;
+  private isCallFromPush;
+  private voipClient;
+  static getInstance(): CallKitCoordinator;
+  private constructor();
+  private setupCallKitListeners;
+  /**
+   * Report an incoming call to CallKit (from push notification or socket)
+   * For push notifications, the call is already reported - we just need to map it
+   */
+  reportIncomingCall(call: Call, callerName: string, callerNumber: string): Promise<string | null>;
+  /**
+   * Start an outgoing call through CallKit
+   */
+  startOutgoingCall(
+    call: Call,
+    destinationNumber: string,
+    displayName?: string
+  ): Promise<string | null>;
+  /**
+   * Answer a call from the app UI (CallKit-first approach)
+   */
+  answerCallFromUI(call: Call): Promise<boolean>;
+  /**
+   * End a call from the app UI (CallKit-first approach)
+   */
+  endCallFromUI(call: Call): Promise<boolean>;
+  /**
+   * Handle CallKit answer action (triggered by CallKit)
+   */
+  handleCallKitAnswer(callKitUUID: string, event?: any): Promise<void>;
+  /**
+   * Handle CallKit end action (triggered by CallKit)
+   */
+  private handleCallKitEnd;
+  /**
+   * Handle CallKit start action (triggered by CallKit for outgoing calls)
+   */
+  private handleCallKitStart;
+  /**
+   * Handle CallKit push received event - when a VoIP push notification has been processed
+   * This allows us to coordinate between the push notification and any subsequent WebRTC calls
+   */
+  handleCallKitPushReceived(callKitUUID: string, event?: any): Promise<void>;
+  /**
+   * Handle push notification answer - when user answers from CallKit but we don't have a WebRTC call yet
+   * This is the iOS equivalent of the Android FCM handler
+   */
+  private handlePushNotificationAnswer;
+  /**
+   * Handle push notification reject - when user rejects from CallKit but we don't have a WebRTC call yet
+   * This is the iOS equivalent of the Android FCM handler reject
+   */
+  private handlePushNotificationReject;
+  /**
+   * Set up listeners for WebRTC call state changes
+   */
+  private setupWebRTCCallListeners;
+  /**
+   * Clean up call mappings and listeners
+   */
+  private cleanupCall;
+  /**
+   * Get CallKit UUID for a WebRTC call
+   */
+  getCallKitUUID(call: Call): string | null;
+  /**
+   * Get WebRTC call for a CallKit UUID
+   */
+  getWebRTCCall(callKitUUID: string): Call | null;
+  /**
+   * Link an existing CallKit call (from push notification) with a WebRTC call
+   * This should be called when a WebRTC call arrives that corresponds to an existing CallKit call
+   */
+  linkExistingCallKitCall(call: Call, callKitUUID: string): void;
+  /**
+   * Set the VoIP client reference for triggering reconnection
+   */
+  setVoipClient(voipClient: TelnyxVoipClient): void;
+  /**
+   * Helper method to handle auto-answer logic for push notification calls
+   */
+  private handleAutoAnswer;
+  /**
+   * Helper method to clean up push notification state
+   */
+  private cleanupPushNotificationState;
+  /**
+   * Get reference to the SDK client (for queuing actions when call doesn't exist yet)
+   */
+  private getSDKClient;
+  /**
+   * Check if app is in background and disconnect client if no active calls
+   */
+  private checkBackgroundDisconnection;
+  /**
+   * Reset only flags (keeping active call mappings intact)
+   */
+  resetFlags(): void;
+  /**
+   * Check if there are any calls currently being processed by CallKit
+   * This helps prevent premature flag resets during CallKit operations
+   */
+  hasProcessingCalls(): boolean;
+  /**
+   * Check if there's currently a call from push notification being processed
+   * This helps prevent disconnection during push call handling
+   */
+  getIsCallFromPush(): boolean;
+  /**
+   * Check if CallKit is available and coordinator is active
+   */
+  isAvailable(): boolean;
 }
 export declare const callKitCoordinator: CallKitCoordinator;
 export default callKitCoordinator;