@telnyx/react-voice-commons-sdk 0.1.0

package/ios/README.md

@@ -0,0 +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)

package/ios/VoicePnBridge.m

@@ -0,0 +1,31 @@
+#import <React/RCTBridgeModule.h>
+
+@interface RCT_EXTERN_MODULE(VoicePnBridge, NSObject)
+
+RCT_EXTERN_METHOD(getPendingPushAction:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(setPendingPushAction:(NSString *)action
+                  metadata:(NSString *)metadata
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(clearPendingPushAction:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getVoipToken:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getPendingVoipPush:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(clearPendingVoipPush:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getPendingVoipAction:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(clearPendingVoipAction:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+@end

package/ios/VoicePnBridge.swift

@@ -0,0 +1,87 @@
+import Foundation
+import React
+
+@objc(VoicePnBridge)
+class VoicePnBridge: NSObject {
+    
+    @objc
+    static func requiresMainQueueSetup() -> Bool {
+        return false
+    }
+    
+    // MARK: - UserDefaults-based methods for VoIP push handling
+    
+    @objc
+    func getPendingPushAction(_ resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+        let action = UserDefaults.standard.string(forKey: "pending_push_action")
+        let metadata = UserDefaults.standard.string(forKey: "pending_push_metadata")
+        
+        NSLog("[VoicePnBridge] getPendingPushAction - action: \(action ?? "nil"), metadata: \(metadata ?? "nil")")
+        
+        let result: [String: Any?] = [
+            "action": action,
+            "metadata": metadata
+        ]
+        
+        resolve(result)
+    }
+    
+    @objc
+    func setPendingPushAction(_ action: String, metadata: String, resolver resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+        UserDefaults.standard.set(action, forKey: "pending_push_action")
+        UserDefaults.standard.set(metadata, forKey: "pending_push_metadata")
+        UserDefaults.standard.synchronize()
+        
+        NSLog("[VoicePnBridge] setPendingPushAction - action: \(action), metadata: \(metadata)")
+        resolve(true)
+    }
+    
+    @objc
+    func clearPendingPushAction(_ resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+        UserDefaults.standard.removeObject(forKey: "pending_push_action")
+        UserDefaults.standard.removeObject(forKey: "pending_push_metadata")
+        UserDefaults.standard.synchronize()
+        
+        NSLog("[VoicePnBridge] clearPendingPushAction - cleared pending push data")
+        resolve(true)
+    }
+    
+    // MARK: - Additional UserDefaults methods from UserDefaultsModule
+    
+    @objc
+    func getVoipToken(_ resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+        let token = UserDefaults.standard.string(forKey: "voip_push_token")
+        NSLog("[VoicePnBridge] getVoipToken called. token=\(token ?? "(nil)")")
+        resolve(token)
+    }
+    
+    @objc
+    func getPendingVoipPush(_ resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+        let pending = UserDefaults.standard.string(forKey: "pending_voip_push")
+        NSLog("[VoicePnBridge] getPendingVoipPush called. pending=\(pending ?? "(nil)")")
+        resolve(pending)
+    }
+    
+    @objc
+    func clearPendingVoipPush(_ resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+        UserDefaults.standard.removeObject(forKey: "pending_voip_push")
+        UserDefaults.standard.synchronize()
+        NSLog("[VoicePnBridge] clearPendingVoipPush called. Cleared key pending_voip_push")
+        resolve(true)
+    }
+    
+    @objc
+    func getPendingVoipAction(_ resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+        let pending = UserDefaults.standard.string(forKey: "pending_voip_action")
+        NSLog("[VoicePnBridge] getPendingVoipAction called. pending=\(pending ?? "(nil)")")
+        resolve(pending)
+    }
+    
+    @objc
+    func clearPendingVoipAction(_ resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+        UserDefaults.standard.removeObject(forKey: "pending_voip_action")
+        UserDefaults.standard.synchronize()
+        NSLog("[VoicePnBridge] clearPendingVoipAction called. Cleared key pending_voip_action")
+        resolve(true)
+    }
+}

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

@@ -0,0 +1,126 @@
+import { Call } from '@telnyx/react-native-voice-sdk';
+import { TelnyxVoipClient } from '../telnyx-voip-client';
+/**
+ * CallKit Coordinator - Manages the proper CallKit-first flow for iOS
+ *
+ * This coordinator ensures that all call actions go through CallKit first,
+ * which then triggers the appropriate WebRTC actions. This follows Apple's
+ * 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;
+}
+export declare const callKitCoordinator: CallKitCoordinator;
+export default callKitCoordinator;