@telnyx/react-voice-commons-sdk 0.4.3 → 1.1.0

package/ios/CallKitBridge.swift

@@ -6,8 +6,52 @@ import React
     import AVFoundation
     import UIKit
     import PushKit
+    import UserNotifications
     import WebRTC
 
+    /// Small synchronized dictionary used because React Native module methods
+    /// and CXProvider delegate callbacks are not guaranteed to share a queue.
+    public final class LockedDictionary<Key: Hashable, Value> {
+        private var storage: [Key: Value] = [:]
+        private let lock: NSRecursiveLock
+
+        init(lock: NSRecursiveLock) {
+            self.lock = lock
+        }
+
+        public subscript(key: Key) -> Value? {
+            get {
+                lock.lock()
+                defer { lock.unlock() }
+                return storage[key]
+            }
+            set {
+                lock.lock()
+                defer { lock.unlock() }
+                storage[key] = newValue
+            }
+        }
+
+        public var values: [Value] {
+            lock.lock()
+            defer { lock.unlock() }
+            return Array(storage.values)
+        }
+
+        @discardableResult
+        public func removeValue(forKey key: Key) -> Value? {
+            lock.lock()
+            defer { lock.unlock() }
+            return storage.removeValue(forKey: key)
+        }
+
+        public func removeAll() {
+            lock.lock()
+            defer { lock.unlock() }
+            storage.removeAll()
+        }
+    }
+
     @objc(CallKitBridge)
     class CallKitBridge: RCTEventEmitter {
 
@@ -28,6 +72,7 @@ import React
                 "CallKitDidReceiveStartCallAction",
                 "CallKitDidPerformAnswerCallAction",
                 "CallKitDidPerformEndCallAction",
+                "CallKitDidPerformHeldCallAction",
                 "CallKitDidReceivePush",
                 "AudioSessionActivated",
                 "AudioSessionDeactivated",
@@ -49,8 +94,9 @@ import React
         }
 
         // Direct event emission methods called by TelnyxVoiceAppDelegate
-        public func emitCallEvent(_ eventName: String, callUUID: UUID, callData: [String: Any]?) {
-            guard hasListeners else { return }
+        @discardableResult
+        public func emitCallEvent(_ eventName: String, callUUID: UUID, callData: [String: Any]?) -> Bool {
+            guard hasListeners else { return false }
 
             let eventData: [String: Any] = [
                 "callUUID": callUUID.uuidString,
@@ -58,6 +104,22 @@ import React
             ]
 
             sendEvent(withName: eventName, body: eventData)
+            return true
+        }
+
+        @discardableResult
+        public func emitHeldCallEvent(
+            callUUID: UUID, isOnHold: Bool, callData: [String: Any]?
+        ) -> Bool {
+            guard hasListeners else { return false }
+
+            let eventData: [String: Any] = [
+                "callUUID": callUUID.uuidString,
+                "isOnHold": isOnHold,
+                "callData": callData ?? [:],
+            ]
+            sendEvent(withName: "CallKitDidPerformHeldCallAction", body: eventData)
+            return true
         }
 
         // Event emission method for audio session changes
@@ -89,8 +151,17 @@ import React
             let startCallAction = CXStartCallAction(call: uuid, handle: callHandle)
             let transaction = CXTransaction(action: startCallAction)
 
+            manager.activeCalls[uuid] = [
+                "caller": displayName,
+                "handle": handle,
+                "uuid": uuid.uuidString,
+                "direction": "outgoing",
+                "source": "react_native",
+            ]
+
             callController.request(transaction) { error in
                 if let error = error {
+                    manager.activeCalls.removeValue(forKey: uuid)
                     reject("START_CALL_ERROR", error.localizedDescription, error)
                 } else {
                     resolve(["success": true, "callUUID": callUUID])
@@ -119,11 +190,23 @@ import React
             callUpdate.remoteHandle = callHandle
             callUpdate.hasVideo = false
             callUpdate.localizedCallerName = displayName
+            callUpdate.supportsHolding = true
+
+            manager.activeCalls[uuid] = [
+                "caller": displayName,
+                "handle": handle,
+                "uuid": uuid.uuidString,
+                "direction": "incoming",
+                "source": "react_native",
+                "isCallKitRegistered": false,
+            ]
 
             provider.reportNewIncomingCall(with: uuid, update: callUpdate) { error in
                 if let error = error {
+                    manager.activeCalls.removeValue(forKey: uuid)
                     reject("INCOMING_CALL_ERROR", error.localizedDescription, error)
                 } else {
+                    manager.markCallKitRegistered(uuid)
                     resolve(["success": true, "callUUID": callUUID])
                 }
             }
@@ -156,6 +239,127 @@ import React
             }
         }
 
+        @objc func completeHeldCallAction(
+            _ callUUID: String, success: Bool,
+            resolver resolve: @escaping RCTPromiseResolveBlock,
+            rejecter reject: @escaping RCTPromiseRejectBlock
+        ) {
+            guard let uuid = UUID(uuidString: callUUID) else {
+                reject("INVALID_UUID", "Invalid UUID format", nil)
+                return
+            }
+
+            let manager = getCallKitManager()
+            let completeAction = {
+                guard let action = manager.pendingHeldActions.removeValue(forKey: uuid) else {
+                    reject("NO_PENDING_HELD_ACTION", "No pending held action for UUID", nil)
+                    return
+                }
+
+                if success {
+                    if var callData = manager.activeCalls[uuid] {
+                        callData["isOnHold"] = action.isOnHold
+                        manager.activeCalls[uuid] = callData
+                    }
+                    action.fulfill()
+                } else {
+                    action.fail()
+                }
+                resolve(["success": success, "callUUID": callUUID])
+            }
+
+            if Thread.isMainThread {
+                completeAction()
+            } else {
+                DispatchQueue.main.async(execute: completeAction)
+            }
+        }
+
+        @objc func setCallHeld(
+            _ callUUID: String, isOnHold: Bool,
+            resolver resolve: @escaping RCTPromiseResolveBlock,
+            rejecter reject: @escaping RCTPromiseRejectBlock
+        ) {
+            guard let uuid = UUID(uuidString: callUUID) else {
+                reject("INVALID_UUID", "Invalid UUID format", nil)
+                return
+            }
+
+            let manager = getCallKitManager()
+            guard let callController = manager.callKitController else {
+                reject("NO_CALLKIT", "CallKit not available", nil)
+                return
+            }
+
+            guard manager.activeCalls[uuid] != nil else {
+                reject("UNKNOWN_CALL", "Call must be registered with CallKit", nil)
+                return
+            }
+
+            let action = CXSetHeldCallAction(call: uuid, onHold: isOnHold)
+            let transaction = CXTransaction(action: action)
+            callController.request(transaction) { error in
+                if let error = error {
+                    reject("SET_HELD_ERROR", error.localizedDescription, error)
+                } else {
+                    resolve([
+                        "success": true,
+                        "callUUID": callUUID,
+                        "isOnHold": isOnHold,
+                    ])
+                }
+            }
+        }
+
+        @objc func swapCalls(
+            _ activeCallUUID: String, heldCallUUID: String,
+            resolver resolve: @escaping RCTPromiseResolveBlock,
+            rejecter reject: @escaping RCTPromiseRejectBlock
+        ) {
+            guard let activeUUID = UUID(uuidString: activeCallUUID),
+                let heldUUID = UUID(uuidString: heldCallUUID)
+            else {
+                reject("INVALID_UUID", "Invalid UUID format", nil)
+                return
+            }
+
+            guard activeUUID != heldUUID else {
+                reject("INVALID_SWAP", "Active and held call UUIDs must be different", nil)
+                return
+            }
+
+            let manager = getCallKitManager()
+            guard let callController = manager.callKitController else {
+                reject("NO_CALLKIT", "CallKit not available", nil)
+                return
+            }
+
+            guard manager.activeCalls[activeUUID] != nil,
+                manager.activeCalls[heldUUID] != nil
+            else {
+                reject("UNKNOWN_CALL", "Both calls must be registered with CallKit", nil)
+                return
+            }
+
+            let actions: [CXAction] = [
+                CXSetHeldCallAction(call: activeUUID, onHold: true),
+                CXSetHeldCallAction(call: heldUUID, onHold: false),
+            ]
+            let transaction = CXTransaction(actions: actions)
+
+            callController.request(transaction) { error in
+                if let error = error {
+                    reject("SWAP_CALLS_ERROR", error.localizedDescription, error)
+                } else {
+                    resolve([
+                        "success": true,
+                        "activeCallUUID": activeCallUUID,
+                        "heldCallUUID": heldCallUUID,
+                    ])
+                }
+            }
+        }
+
         @objc func answerCall(
             _ callUUID: String, resolver resolve: @escaping RCTPromiseResolveBlock,
             rejecter reject: @escaping RCTPromiseRejectBlock
@@ -171,6 +375,15 @@ import React
                 return
             }
 
+            guard manager.isCallKitRegistered(uuid) else {
+                reject(
+                    "UNKNOWN_CALL",
+                    "Call was not registered with CallKit or its registration was rejected",
+                    nil
+                )
+                return
+            }
+
             // Mark this call as already answered to prevent duplicate emission
             if var callData = manager.activeCalls[uuid] {
                 callData["isAlreadyAnswered"] = true
@@ -189,6 +402,22 @@ import React
             }
         }
 
+        @objc func isCallRegistered(
+            _ callUUID: String, resolver resolve: @escaping RCTPromiseResolveBlock,
+            rejecter reject: @escaping RCTPromiseRejectBlock
+        ) {
+            guard let uuid = UUID(uuidString: callUUID) else {
+                reject("INVALID_UUID", "Invalid UUID format", nil)
+                return
+            }
+
+            let registered = getCallKitManager().isCallKitRegistered(uuid)
+            resolve([
+                "registered": registered,
+                "callUUID": callUUID,
+            ])
+        }
+
         @objc func reportCallConnected(
             _ callUUID: String, resolver resolve: @escaping RCTPromiseResolveBlock,
             rejecter reject: @escaping RCTPromiseRejectBlock
@@ -207,10 +436,9 @@ import React
             provider.reportOutgoingCall(with: uuid, connectedAt: Date())
 
             // Fulfill deferred CXAnswerCallAction now that peer connection is ready
-            if let pendingAction = manager.pendingAnswerAction {
+            if let pendingAction = manager.pendingAnswerActions.removeValue(forKey: uuid) {
                 NSLog("TelnyxVoice: reportCallConnected - fulfilling deferred CXAnswerCallAction")
                 pendingAction.fulfill()
-                manager.pendingAnswerAction = nil
             } else {
                 // Fallback: ensure audio is enabled for non-push or already-fulfilled cases
                 let rtcAudioSession = RTCAudioSession.sharedInstance()
@@ -253,6 +481,9 @@ import React
 
             let endReason = CXCallEndedReason(rawValue: reason.intValue) ?? .remoteEnded
             provider.reportCall(with: uuid, endedAt: Date(), reason: endReason)
+            manager.activeCalls.removeValue(forKey: uuid)
+            manager.pendingAnswerActions.removeValue(forKey: uuid)?.fail()
+            manager.pendingHeldActions.removeValue(forKey: uuid)?.fail()
             resolve(["success": true])
         }
 
@@ -285,12 +516,217 @@ import React
             let callUpdate = CXCallUpdate()
             callUpdate.remoteHandle = callHandle
             callUpdate.localizedCallerName = displayName
+            callUpdate.supportsHolding = true
 
             provider.reportCall(with: uuid, updated: callUpdate)
             resolve(["success": true])
         }
     }
 
+    // MARK: - Missed Call
+    enum TelnyxVoiceUserDefaultsKey {
+        static let missedCallNotificationsEnabled = "telnyx_enable_missed_call_notifications"
+    }
+
+    private enum TelnyxMissedCallPush {
+        static let processedMissedCallIdsKey = "telnyx_processed_missed_call_ids"
+        private static let missedCallMarkerKeys: Set<String> = [
+            "is_missed_call",
+            "message",
+            "missed",
+            "missed_call",
+            "notification_type",
+            "push_type",
+            "type",
+        ]
+        private static let affirmativeMissedCallValues: Set<String> = [
+            "1",
+            "missed",
+            "missed call",
+            "true",
+            "yes",
+        ]
+
+        static func isMissedCallPayload(_ payload: [AnyHashable: Any]) -> Bool {
+            return containsMissedCallMarker(payload)
+        }
+
+        static func stableIdentifier(from payload: [AnyHashable: Any]) -> String {
+            if let callId = callId(from: payload), !callId.isEmpty {
+                return callId
+            }
+
+            return "payload-\(hashHex(canonicalString(from: payload)))"
+        }
+
+        static func uuid(from identifier: String) -> UUID {
+            if let uuid = UUID(uuidString: identifier) {
+                return uuid
+            }
+
+            let firstHash = hashHex(identifier)
+            let secondHash = hashHex("telnyx-\(identifier)")
+            let uuidString =
+                "\(firstHash.prefix(8))-\(firstHash.dropFirst(8).prefix(4))-\(firstHash.dropFirst(12).prefix(4))-\(secondHash.prefix(4))-\(secondHash.dropFirst(4).prefix(12))"
+
+            return UUID(uuidString: uuidString) ?? UUID()
+        }
+
+        static func callId(from payload: [AnyHashable: Any]) -> String? {
+            return stringValue(for: ["call_id", "callId"], in: payload)
+        }
+
+        static func callerName(from payload: [AnyHashable: Any]) -> String {
+            return stringValue(for: ["caller_name", "caller", "from"], in: payload)
+                ?? callerNumber(from: payload)
+        }
+
+        static func callerNumber(from payload: [AnyHashable: Any]) -> String {
+            return stringValue(for: ["caller_number", "caller", "from"], in: payload)
+                ?? "Unknown Caller"
+        }
+
+        static func missedCallNotificationsEnabled() -> Bool {
+            // bool(forKey:) returns false for both "unset" and "false"; default to enabled
+            // unless the app explicitly stores a preference.
+            guard
+                UserDefaults.standard.object(
+                    forKey: TelnyxVoiceUserDefaultsKey.missedCallNotificationsEnabled) != nil
+            else {
+                return true
+            }
+            return UserDefaults.standard.bool(
+                forKey: TelnyxVoiceUserDefaultsKey.missedCallNotificationsEnabled)
+        }
+
+        private static func stringValue(for keys: [String], in payload: [AnyHashable: Any]) -> String? {
+            if let metadata = payload["metadata"] as? [AnyHashable: Any],
+                let value = firstStringValue(for: keys, in: metadata)
+            {
+                return value
+            }
+
+            if let metadata = payload["metadata"] as? [String: Any],
+                let value = firstStringValue(for: keys, in: metadata)
+            {
+                return value
+            }
+
+            return firstStringValue(for: keys, in: payload)
+        }
+
+        private static func firstStringValue(for keys: [String], in dictionary: [AnyHashable: Any])
+            -> String?
+        {
+            for key in keys {
+                if let value = dictionary[key] as? String, !value.isEmpty {
+                    return value
+                }
+            }
+            return nil
+        }
+
+        private static func firstStringValue(for keys: [String], in dictionary: [String: Any])
+            -> String?
+        {
+            for key in keys {
+                if let value = dictionary[key] as? String, !value.isEmpty {
+                    return value
+                }
+            }
+            return nil
+        }
+
+        private static func containsMissedCallMarker(_ value: Any, key: String? = nil) -> Bool {
+            if let key = key, missedCallMarkerKeys.contains(normalizedPayloadKey(key)) {
+                if let boolValue = value as? Bool {
+                    return boolValue
+                }
+
+                if let stringValue = value as? String {
+                    return affirmativeMissedCallValues.contains(normalizedMissedCallValue(stringValue))
+                }
+            }
+
+            if let stringValue = value as? String {
+                let normalized = normalizedMissedCallValue(stringValue)
+                if normalized == "missed call" || normalized == "missed" {
+                    return true
+                }
+            }
+
+            if let dictionary = value as? [AnyHashable: Any] {
+                return dictionary.contains { rawKey, nestedValue in
+                    containsMissedCallMarker(nestedValue, key: String(describing: rawKey))
+                }
+            }
+
+            if let dictionary = value as? [String: Any] {
+                return dictionary.contains { key, nestedValue in
+                    containsMissedCallMarker(nestedValue, key: key)
+                }
+            }
+
+            if let array = value as? [Any] {
+                return array.contains { containsMissedCallMarker($0) }
+            }
+
+            return false
+        }
+
+        private static func normalizedPayloadKey(_ key: String) -> String {
+            return key
+                .lowercased()
+                .replacingOccurrences(of: "-", with: "_")
+                .replacingOccurrences(of: " ", with: "_")
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+        }
+
+        private static func normalizedMissedCallValue(_ value: String) -> String {
+            return value
+                .lowercased()
+                .replacingOccurrences(of: "_", with: " ")
+                .replacingOccurrences(of: "-", with: " ")
+                .replacingOccurrences(of: "!", with: "")
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+        }
+
+        private static func canonicalString(from value: Any) -> String {
+            if let dictionary = value as? [AnyHashable: Any] {
+                return dictionary
+                    .map { (String(describing: $0.key), $0.value) }
+                    .sorted { $0.0 < $1.0 }
+                    .map { "\($0):\(canonicalString(from: $1))" }
+                    .joined(separator: "|")
+            }
+
+            if let dictionary = value as? [String: Any] {
+                return dictionary
+                    .sorted { $0.key < $1.key }
+                    .map { "\($0):\(canonicalString(from: $1))" }
+                    .joined(separator: "|")
+            }
+
+            if let array = value as? [Any] {
+                return array.map { canonicalString(from: $0) }.joined(separator: ",")
+            }
+
+            return String(describing: value)
+        }
+
+        private static func hashHex(_ value: String) -> String {
+            let prime: UInt64 = 1_099_511_628_211
+            var hash: UInt64 = 14_695_981_039_346_656_037
+
+            for byte in value.utf8 {
+                hash ^= UInt64(byte)
+                hash = hash &* prime
+            }
+
+            return String(format: "%016llx", hash)
+        }
+    }
+
     // MARK: - TelnyxCallKitManager
     /// TelnyxCallKitManager - Automatically handles CallKit integration for Telnyx Voice
     /// This class sets up CallKit and VoIP push notifications automatically when the app starts
@@ -302,8 +738,33 @@ import React
         public var voipRegistry: PKPushRegistry?
         public var callKitProvider: CXProvider?
         public var callKitController: CXCallController?
-        public var activeCalls: [UUID: [String: Any]] = [:]
-        public var pendingAnswerAction: CXAnswerCallAction?
+        private let stateLock = NSRecursiveLock()
+        public lazy var activeCalls = LockedDictionary<UUID, [String: Any]>(lock: stateLock)
+        public lazy var pendingAnswerActions = LockedDictionary<UUID, CXAnswerCallAction>(
+            lock: stateLock)
+        public lazy var pendingHeldActions = LockedDictionary<UUID, CXSetHeldCallAction>(
+            lock: stateLock)
+
+        fileprivate func markCallKitRegistered(_ callUUID: UUID) {
+            guard var callData = activeCalls[callUUID] else {
+                return
+            }
+
+            callData["isCallKitRegistered"] = true
+            activeCalls[callUUID] = callData
+        }
+
+        fileprivate func isCallKitRegistered(_ callUUID: UUID) -> Bool {
+            guard let callData = activeCalls[callUUID] else {
+                return false
+            }
+
+            if callData["direction"] as? String == "incoming" {
+                return callData["isCallKitRegistered"] as? Bool == true
+            }
+
+            return true
+        }
 
         private override init() {
             super.init()
@@ -324,18 +785,27 @@ import React
             }
         }
 
-        public func setupSynchronously() {
+        @discardableResult
+        public func setupSynchronously() -> CXProvider {
             // Only initialize once
-            guard callKitProvider == nil else {
+            if let callKitProvider = callKitProvider {
                 NSLog("TelnyxVoice: CallKit already setup, skipping")
-                return
+                return callKitProvider
             }
 
             // CRITICAL: Setup CallKit synchronously for terminated app VoIP push handling
             // This MUST happen in the same run loop as the VoIP push
             NSLog("TelnyxVoice: Synchronous CallKit setup for terminated app scenario...")
             setupCallKit()
+            if let callKitProvider = callKitProvider {
+                NSLog("TelnyxVoice: ✅ CallKit provider ready for terminated app handling")
+                return callKitProvider
+            }
+
+            NSLog("TelnyxVoice: CallKit setup did not create a provider; creating fallback provider")
+            let callKitProvider = installCallKitProvider()
             NSLog("TelnyxVoice: ✅ CallKit provider ready for terminated app handling")
+            return callKitProvider
         }
 
         private func setupAutomatically() {
@@ -366,6 +836,10 @@ import React
                 return
             }
 
+            _ = installCallKitProvider()
+        }
+
+        private func installCallKitProvider() -> CXProvider {
             // Use the localizedName from the app's bundle display name or fallback
             let appName =
                 Bundle.main.object(forInfoDictionaryKey: "CFBundleDisplayName") as? String
@@ -374,19 +848,66 @@ import React
 
             let configuration = CXProviderConfiguration(localizedName: appName)
             configuration.supportsVideo = false
-            configuration.maximumCallGroups = 1
+            configuration.maximumCallGroups = 2
             configuration.maximumCallsPerCallGroup = 1
             configuration.supportedHandleTypes = [.phoneNumber, .generic]
             configuration.includesCallsInRecents = true
 
-            callKitProvider = CXProvider(configuration: configuration)
-            callKitProvider?.setDelegate(self, queue: nil)
+            let provider = CXProvider(configuration: configuration)
+            provider.setDelegate(self, queue: nil)
+            callKitProvider = provider
             callKitController = CXCallController()
 
             NSLog("TelnyxVoice: CallKit provider and controller created")
+            return provider
         }
 
-     
+        fileprivate func reportAndEndWatchdogCall(
+            callUUID: UUID,
+            callerName: String,
+            callerNumber: String,
+            payload: [AnyHashable: Any],
+            source: String,
+            endedReason: CXCallEndedReason,
+            completion: (() -> Void)? = nil
+        ) {
+            let callKitProvider = setupSynchronously()
+
+            activeCalls[callUUID] = [
+                "caller": callerName,
+                "handle": callerNumber,
+                "payload": payload,
+                "uuid": callUUID.uuidString,
+                "direction": "incoming",
+                "source": source,
+                "watchdogPlaceholder": true,
+            ]
+
+            let handle = CXHandle(type: .phoneNumber, value: callerNumber)
+            let callUpdate = CXCallUpdate()
+            callUpdate.remoteHandle = handle
+            callUpdate.hasVideo = false
+            callUpdate.localizedCallerName = callerName
+            callUpdate.supportsHolding = true
+
+            callKitProvider.reportNewIncomingCall(with: callUUID, update: callUpdate) { error in
+                if let error = error {
+                    NSLog(
+                        "TelnyxVoice: Watchdog CallKit report failed for \(source): \(error.localizedDescription)"
+                    )
+                } else {
+                    NSLog("TelnyxVoice: Watchdog CallKit call reported for \(source)")
+                }
+
+                callKitProvider.reportCall(with: callUUID, endedAt: Date(), reason: endedReason)
+                self.activeCalls.removeValue(forKey: callUUID)
+
+                self.pendingAnswerActions.removeValue(forKey: callUUID)?.fail()
+                self.pendingHeldActions.removeValue(forKey: callUUID)?.fail()
+
+                completion?()
+            }
+        }
 
         private func observeAppDelegate() {
             // Automatically hook into app lifecycle if needed
@@ -404,6 +925,243 @@ import React
                 setupCallKit()
             }
         }
+
+        @discardableResult
+        public func handleMissedCallPushIfNeeded(
+            _ payload: [AnyHashable: Any],
+            completion: (() -> Void)? = nil
+        ) -> Bool {
+            guard TelnyxMissedCallPush.isMissedCallPayload(payload) else {
+                return false
+            }
+
+            NSLog("TelnyxVoice: Missed call VoIP push received: \(payload)")
+            let callKitProvider = setupSynchronously()
+
+            let callId = TelnyxMissedCallPush.callId(from: payload)
+            let missedCallId = TelnyxMissedCallPush.stableIdentifier(from: payload)
+            let callUUID = TelnyxMissedCallPush.uuid(from: missedCallId)
+            let callerName = TelnyxMissedCallPush.callerName(from: payload)
+            let callerNumber = TelnyxMissedCallPush.callerNumber(from: payload)
+
+            if hasProcessedMissedCall(id: missedCallId) {
+                NSLog("TelnyxVoice: Suppressing duplicate missed call notification: \(missedCallId)")
+                reportAndEndWatchdogCall(
+                    callUUID: UUID(),
+                    callerName: callerName,
+                    callerNumber: callerNumber,
+                    payload: payload,
+                    source: "missed_call_duplicate_watchdog",
+                    endedReason: .remoteEnded,
+                    completion: completion
+                )
+                return true
+            }
+
+            let finishMissedCall = {
+                callKitProvider.reportCall(with: callUUID, endedAt: Date(), reason: .remoteEnded)
+                self.activeCalls.removeValue(forKey: callUUID)
+
+                self.pendingAnswerActions.removeValue(forKey: callUUID)?.fail()
+                self.pendingHeldActions.removeValue(forKey: callUUID)?.fail()
+
+                NSLog("TelnyxVoice: Ended stale CallKit call for missed call UUID: \(callUUID)")
+                self.clearPendingPushData(for: callId)
+                self.showMissedCallNotification(
+                    callerName: callerName,
+                    callerNumber: callerNumber,
+                    missedCallId: missedCallId
+                )
+                self.markMissedCallProcessed(id: missedCallId)
+                completion?()
+            }
+
+            if let activeCall = activeCalls[callUUID] {
+                guard activeCall["source"] as? String == "missed_call_push" else {
+                    NSLog("TelnyxVoice: Suppressing missed call notification because UUID belongs to an active call: \(callUUID)")
+                    markMissedCallProcessed(id: missedCallId)
+                    reportAndEndWatchdogCall(
+                        callUUID: UUID(),
+                        callerName: callerName,
+                        callerNumber: callerNumber,
+                        payload: payload,
+                        source: "missed_call_collision_watchdog",
+                        endedReason: .remoteEnded,
+                        completion: completion
+                    )
+                    return true
+                }
+
+                reportAndEndWatchdogCall(
+                    callUUID: UUID(),
+                    callerName: callerName,
+                    callerNumber: callerNumber,
+                    payload: payload,
+                    source: "missed_call_active_watchdog",
+                    endedReason: .remoteEnded
+                ) {
+                    finishMissedCall()
+                }
+                return true
+            }
+
+            activeCalls[callUUID] = [
+                "caller": callerName,
+                "handle": callerNumber,
+                "payload": payload,
+                "uuid": callUUID.uuidString,
+                "direction": "incoming",
+                "source": "missed_call_push",
+            ]
+
+            let handle = CXHandle(type: .phoneNumber, value: callerNumber)
+            let callUpdate = CXCallUpdate()
+            callUpdate.remoteHandle = handle
+            callUpdate.hasVideo = false
+            callUpdate.localizedCallerName = callerName
+            callUpdate.supportsHolding = true
+
+            callKitProvider.reportNewIncomingCall(with: callUUID, update: callUpdate) { error in
+                if let error = error {
+                    NSLog("TelnyxVoice: Missed call CallKit report failed: \(error.localizedDescription)")
+                    callKitProvider.reportCall(with: callUUID, endedAt: Date(), reason: .failed)
+                    self.activeCalls.removeValue(forKey: callUUID)
+                    self.clearPendingPushData(for: callId)
+                    completion?()
+                    return
+                }
+
+                finishMissedCall()
+            }
+
+            return true
+        }
+
+        fileprivate func clearPendingPushData(for callId: String?) {
+            if hasPendingPushData(forDifferentCallThan: callId) {
+                NSLog("TelnyxVoice: Skipping pending push cleanup for missed call; pending data belongs to a different call")
+                return
+            }
+
+            UserDefaults.standard.removeObject(forKey: "pending_push_action")
+            UserDefaults.standard.removeObject(forKey: "pending_push_metadata")
+            UserDefaults.standard.removeObject(forKey: "pending_voip_push")
+            UserDefaults.standard.removeObject(forKey: "pending_voip_action")
+            UserDefaults.standard.removeObject(forKey: "@pending_callkit_uuid")
+            UserDefaults.standard.synchronize()
+        }
+
+        private func hasPendingPushData(forDifferentCallThan missedCallId: String?) -> Bool {
+            guard let missedCallId = missedCallId, !missedCallId.isEmpty else {
+                return false
+            }
+
+            let pendingIds = [
+                pendingCallId(fromJsonForKey: "pending_push_metadata"),
+                pendingCallId(fromJsonForKey: "pending_voip_push"),
+                UserDefaults.standard.string(forKey: "@pending_callkit_uuid"),
+            ].compactMap { $0 }
+
+            return pendingIds.contains {
+                !$0.isEmpty && $0.caseInsensitiveCompare(missedCallId) != .orderedSame
+            }
+        }
+
+        private func pendingCallId(fromJsonForKey key: String) -> String? {
+            guard let jsonString = UserDefaults.standard.string(forKey: key),
+                let data = jsonString.data(using: .utf8),
+                let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+            else {
+                return nil
+            }
+
+            if let directCallId = callId(from: json) {
+                return directCallId
+            }
+
+            if let payload = json["payload"] as? [String: Any] {
+                return callId(from: payload)
+            }
+
+            return nil
+        }
+
+        private func callId(from dictionary: [String: Any]) -> String? {
+            for key in ["call_id", "callId", "telnyx_call_id"] {
+                if let value = dictionary[key] as? String, !value.isEmpty {
+                    return value
+                }
+            }
+
+            if let metadata = dictionary["metadata"] as? [String: Any] {
+                return callId(from: metadata)
+            }
+
+            return nil
+        }
+
+        private func hasProcessedMissedCall(id: String) -> Bool {
+            return processedMissedCallIds().contains(id)
+        }
+
+        private func markMissedCallProcessed(id: String) {
+            var ids = processedMissedCallIds().filter { $0 != id }
+            ids.append(id)
+            UserDefaults.standard.set(Array(ids.suffix(50)), forKey: TelnyxMissedCallPush.processedMissedCallIdsKey)
+            UserDefaults.standard.synchronize()
+        }
+
+        private func processedMissedCallIds() -> [String] {
+            return UserDefaults.standard.stringArray(
+                forKey: TelnyxMissedCallPush.processedMissedCallIdsKey) ?? []
+        }
+
+        private func showMissedCallNotification(
+            callerName: String, callerNumber: String, missedCallId: String
+        ) {
+            guard TelnyxMissedCallPush.missedCallNotificationsEnabled() else {
+                NSLog("TelnyxVoice: Missed call local notification disabled")
+                return
+            }
+
+            let content = UNMutableNotificationContent()
+            content.title = "Missed Call"
+            content.body = "You missed a call from \(callerName)"
+            content.sound = .default
+            content.userInfo = [
+                "call_id": missedCallId,
+                "caller_name": callerName,
+                "caller_number": callerNumber,
+            ]
+
+            let identifier = "telnyx.missed-call.\(missedCallId)"
+            let request = UNNotificationRequest(
+                identifier: identifier,
+                content: content,
+                trigger: nil
+            )
+
+            let notificationCenter = UNUserNotificationCenter.current()
+            notificationCenter.getNotificationSettings { settings in
+                guard settings.authorizationStatus == .authorized
+                    || settings.authorizationStatus == .provisional
+                    || settings.authorizationStatus == .ephemeral
+                else {
+                    NSLog(
+                        "TelnyxVoice: Missed call notification not shown; notification authorization status: \(settings.authorizationStatus.rawValue)"
+                    )
+                    return
+                }
+
+                notificationCenter.add(request) { error in
+                    if let error = error {
+                        NSLog("TelnyxVoice: Failed to show missed call notification: \(error)")
+                    } else {
+                        NSLog("TelnyxVoice: Missed call notification scheduled")
+                    }
+                }
+            }
+        }
     }
 
     // MARK: - PKPushRegistryDelegate
@@ -458,6 +1216,10 @@ import React
         ) {
             NSLog("TelnyxVoice: Received VoIP push notification: \(payload.dictionaryPayload)")
 
+            if handleMissedCallPushIfNeeded(payload.dictionaryPayload, completion: completion) {
+                return
+            }
+
             // Store the VoIP push data for VoicePnBridge (same format as AppDelegate was using)
             do {
                 let jsonData = try JSONSerialization.data(withJSONObject: payload.dictionaryPayload)
@@ -499,6 +1261,7 @@ import React
                 "uuid": callUUID.uuidString,
                 "direction": "incoming",
                 "source": "push",
+                "isCallKitRegistered": false,
             ]
 
             let handle = CXHandle(type: .phoneNumber, value: caller)
@@ -506,6 +1269,7 @@ import React
             callUpdate.remoteHandle = handle
             callUpdate.hasVideo = false
             callUpdate.localizedCallerName = caller
+            callUpdate.supportsHolding = true
 
             callKitProvider?.reportNewIncomingCall(with: callUUID, update: callUpdate) {
                 [weak self] error in
@@ -513,6 +1277,7 @@ import React
                     NSLog("TelnyxVoice: CallKit error: \(error.localizedDescription)")
                     self?.activeCalls.removeValue(forKey: callUUID)
                 } else {
+                    self?.markCallKitRegistered(callUUID)
                     NSLog("TelnyxVoice: CallKit incoming call reported successfully")
                 }
                 completion()
@@ -527,12 +1292,35 @@ import React
             NSLog("📞 TelnyxVoice: CALLKIT PROVIDER RESET - Provider: \(provider)")
             NSLog("TelnyxVoice: CallKit provider reset - ending all active calls")
             activeCalls.removeAll()
+            pendingAnswerActions.values.forEach { $0.fail() }
+            pendingAnswerActions.removeAll()
+            pendingHeldActions.values.forEach { $0.fail() }
+            pendingHeldActions.removeAll()
         }
 
         public func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
             NSLog("📞 TelnyxVoice: CALLKIT ANSWER ACTION - Provider: \(provider), Action: \(action)")
             NSLog("TelnyxVoice: User answered call with UUID: \(action.callUUID)")
 
+            if activeCalls[action.callUUID]?["watchdogPlaceholder"] as? Bool == true {
+                NSLog("TelnyxVoice: Failing answer for watchdog placeholder call: \(action.callUUID)")
+                activeCalls.removeValue(forKey: action.callUUID)
+                action.fail()
+                return
+            }
+
+            guard isCallKitRegistered(action.callUUID) else {
+                NSLog("TelnyxVoice: Failing answer for unknown UUID: \(action.callUUID)")
+                action.fail()
+                return
+            }
+
+            guard pendingAnswerActions[action.callUUID] == nil else {
+                NSLog("TelnyxVoice: Failing duplicate answer for UUID: \(action.callUUID)")
+                action.fail()
+                return
+            }
+
             // Check if this is a programmatic answer (call already answered in WebRTC)
             // vs a user answer from CallKit UI
             if let callData = activeCalls[action.callUUID],
@@ -542,25 +1330,83 @@ import React
                 NSLog("TelnyxVoice: Call already answered in WebRTC, skipping emission")
             } else {
                 // Notify React Native via CallKit bridge (only for user-initiated answers)
-                CallKitBridge.shared?.emitCallEvent(
+                let eventDelivered = CallKitBridge.shared?.emitCallEvent(
                     "CallKitDidPerformAnswerCallAction", callUUID: action.callUUID,
-                    callData: activeCalls[action.callUUID])
+                    callData: activeCalls[action.callUUID]) ?? false
+                if !eventDelivered {
+                    UserDefaults.standard.set(action.callUUID.uuidString, forKey: "pending_callkit_answer")
+                    UserDefaults.standard.synchronize()
+                    NSLog("TelnyxVoice: Stored pending CallKit answer for UUID: \(action.callUUID)")
+                }
             }
 
             // Defer action.fulfill() until reportCallConnected when peer connection is ready
             NSLog("TelnyxVoice: Deferring CXAnswerCallAction.fulfill() until peer connection is ready")
-            self.pendingAnswerAction = action
+            self.pendingAnswerActions[action.callUUID] = action
+        }
+
+        public func provider(_ provider: CXProvider, perform action: CXSetHeldCallAction) {
+            NSLog(
+                "TelnyxVoice: User requested held=\(action.isOnHold) for UUID: \(action.callUUID)"
+            )
+
+            guard activeCalls[action.callUUID] != nil else {
+                NSLog("TelnyxVoice: Failing held action for unknown UUID: \(action.callUUID)")
+                action.fail()
+                return
+            }
+
+            guard pendingHeldActions[action.callUUID] == nil else {
+                NSLog("TelnyxVoice: Failing duplicate held action for UUID: \(action.callUUID)")
+                action.fail()
+                return
+            }
+
+            pendingHeldActions[action.callUUID] = action
+            let emitted = CallKitBridge.shared?.emitHeldCallEvent(
+                callUUID: action.callUUID,
+                isOnHold: action.isOnHold,
+                callData: activeCalls[action.callUUID]
+            ) ?? false
+
+            guard emitted else {
+                pendingHeldActions.removeValue(forKey: action.callUUID)
+                action.fail()
+                return
+            }
+
+            DispatchQueue.main.asyncAfter(deadline: .now() + 10) { [weak self, weak action] in
+                guard let self = self, let action = action,
+                    self.pendingHeldActions[action.callUUID] === action
+                else { return }
+
+                NSLog("TelnyxVoice: Held action timed out for UUID: \(action.callUUID)")
+                self.pendingHeldActions.removeValue(forKey: action.callUUID)
+                action.fail()
+            }
         }
 
         public func provider(_ provider: CXProvider, perform action: CXEndCallAction) {
             NSLog("TelnyxVoice: User ended call with UUID: \(action.callUUID)")
 
+            guard let callData = activeCalls[action.callUUID] else {
+                NSLog("TelnyxVoice: Failing end action for unknown UUID: \(action.callUUID)")
+                action.fail()
+                return
+            }
+            if UserDefaults.standard.string(forKey: "pending_callkit_answer") == action.callUUID.uuidString {
+                UserDefaults.standard.removeObject(forKey: "pending_callkit_answer")
+                UserDefaults.standard.synchronize()
+            }
+
             // Notify React Native via CallKit bridge
             CallKitBridge.shared?.emitCallEvent(
                 "CallKitDidPerformEndCallAction", callUUID: action.callUUID,
-                callData: activeCalls[action.callUUID])
+                callData: callData)
 
             activeCalls.removeValue(forKey: action.callUUID)
+            pendingAnswerActions.removeValue(forKey: action.callUUID)?.fail()
+            pendingHeldActions.removeValue(forKey: action.callUUID)?.fail()
             NSLog("📞 TelnyxVoice: Fulfilling CXEndCallAction for call UUID: \(action.callUUID)")
             action.fulfill()
             NSLog("📞 TelnyxVoice: ✅ CXEndCallAction fulfilled successfully")
@@ -574,11 +1420,26 @@ import React
                 "CallKitDidReceiveStartCallAction", callUUID: action.callUUID,
                 callData: activeCalls[action.callUUID])
 
+            let callUpdate = CXCallUpdate()
+            callUpdate.remoteHandle = action.handle
+            callUpdate.hasVideo = false
+            callUpdate.supportsHolding = true
+            provider.reportCall(with: action.callUUID, updated: callUpdate)
+
             NSLog("📞 TelnyxVoice: Fulfilling CXStartCallAction for call UUID: \(action.callUUID)")
             action.fulfill()
             NSLog("📞 TelnyxVoice: ✅ CXStartCallAction fulfilled successfully")
         }
 
+        public func provider(_ provider: CXProvider, timedOutPerforming action: CXAction) {
+            if let answerAction = action as? CXAnswerCallAction {
+                pendingAnswerActions.removeValue(forKey: answerAction.callUUID)
+            } else if let heldAction = action as? CXSetHeldCallAction {
+                pendingHeldActions.removeValue(forKey: heldAction.callUUID)
+            }
+            action.fail()
+        }
+
         public func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
             NSLog("TelnyxVoice: Audio session activated by CallKit")
 
@@ -665,6 +1526,33 @@ import React
             super.init()
         }
 
+        private func storePendingVoipPush(_ payload: [AnyHashable: Any]) {
+            do {
+                let jsonData = try JSONSerialization.data(withJSONObject: payload)
+                let jsonString = String(data: jsonData, encoding: .utf8) ?? ""
+
+                UserDefaults.standard.set("incoming_call", forKey: "pending_push_action")
+                UserDefaults.standard.set(jsonString, forKey: "pending_push_metadata")
+
+                let voipPushData = [
+                    "payload": payload
+                ]
+                let voipJsonData = try JSONSerialization.data(withJSONObject: voipPushData)
+                let voipJsonString = String(data: voipJsonData, encoding: .utf8) ?? ""
+                UserDefaults.standard.set(voipJsonString, forKey: "pending_voip_push")
+                UserDefaults.standard.synchronize()
+                NSLog(
+                    "[TelnyxVoipPushHandler] Stored VoIP push data after CallKit registration succeeded"
+                )
+            } catch {
+                NSLog("[TelnyxVoipPushHandler] Error converting VoIP payload to JSON: \(error)")
+                UserDefaults.standard.set("incoming_call", forKey: "pending_push_action")
+                UserDefaults.standard.set("{}", forKey: "pending_push_metadata")
+                UserDefaults.standard.set("{\"payload\":{}}", forKey: "pending_voip_push")
+                UserDefaults.standard.synchronize()
+            }
+        }
+
         /**
          * Initialize VoIP push registration
          * Call this from the main app's AppDelegate didFinishLaunchingWithOptions
@@ -698,6 +1586,13 @@ import React
             NSLog("[TelnyxVoipPushHandler] VoIP push received for type: \(type.rawValue)")
             NSLog("[TelnyxVoipPushHandler] VoIP payload: \(payload.dictionaryPayload)")
 
+            if TelnyxCallKitManager.shared.handleMissedCallPushIfNeeded(
+                payload.dictionaryPayload,
+                completion: completion
+            ) {
+                return
+            }
+
             // Configure audio session early for VoIP call
             let audioSession = AVAudioSession.sharedInstance()
             do {
@@ -706,35 +1601,6 @@ import React
             } catch {
                 NSLog("Failed to activate audio session: \(error)")
             }
-            // Store the VoIP push data for VoicePnBridge
-            do {
-                let jsonData = try JSONSerialization.data(withJSONObject: payload.dictionaryPayload)
-                let jsonString = String(data: jsonData, encoding: .utf8) ?? ""
-
-                // Store for TelnyxVoiceApp (push action flow)
-                UserDefaults.standard.set("incoming_call", forKey: "pending_push_action")
-                UserDefaults.standard.set(jsonString, forKey: "pending_push_metadata")
-
-                // ALSO store for VoicePnBridge.getPendingVoipPush() (CallKit coordinator flow)
-                // This creates a structured object with payload property
-                let voipPushData = [
-                    "payload": payload.dictionaryPayload
-                ]
-                let voipJsonData = try JSONSerialization.data(withJSONObject: voipPushData)
-                let voipJsonString = String(data: voipJsonData, encoding: .utf8) ?? ""
-                UserDefaults.standard.set(voipJsonString, forKey: "pending_voip_push")
-
-                UserDefaults.standard.synchronize()
-                NSLog(
-                    "[TelnyxVoipPushHandler] Stored VoIP push data for both TelnyxVoiceApp and VoicePnBridge"
-                )
-            } catch {
-                NSLog("[TelnyxVoipPushHandler] Error converting VoIP payload to JSON: \(error)")
-                UserDefaults.standard.set("incoming_call", forKey: "pending_push_action")
-                UserDefaults.standard.set("{}", forKey: "pending_push_metadata")
-                UserDefaults.standard.set("{\"payload\":{}}", forKey: "pending_voip_push")
-                UserDefaults.standard.synchronize()
-            }
 
             // Extract caller information and call_id from the payload
             var callerName = "Unknown Caller"
@@ -755,12 +1621,20 @@ import React
                 callId = payload.dictionaryPayload["call_id"] as? String
             }
 
-            // Use call_id as CallKit UUID to ensure matching with WebRTC
+            // Use call_id as CallKit UUID to ensure matching with WebRTC.
             guard let callIdString = callId, let callUUID = UUID(uuidString: callIdString) else {
                 NSLog(
-                    "[TelnyxVoipPushHandler] ❌ No valid call_id found in payload, cannot process call"
+                    "[TelnyxVoipPushHandler] ⚠️ Invalid or missing call_id in payload (\(callId ?? "nil")); reporting failed watchdog placeholder"
+                )
+                TelnyxCallKitManager.shared.reportAndEndWatchdogCall(
+                    callUUID: UUID(),
+                    callerName: callerName,
+                    callerNumber: callerNumber,
+                    payload: payload.dictionaryPayload,
+                    source: "malformed_push_watchdog",
+                    endedReason: .failed,
+                    completion: completion
                 )
-                completion()
                 return
             }
 
@@ -776,16 +1650,7 @@ import React
 
             // CRITICAL: Setup CallKit SYNCHRONOUSLY - no async dispatch allowed
             // This must happen in the same run loop as the VoIP push
-            callKitManager.setupSynchronously()
-
-            // Ensure we have a valid CallKit provider after setup
-            guard let callKitProvider = callKitManager.callKitProvider else {
-                NSLog(
-                    "[TelnyxVoipPushHandler] ❌ FATAL: CallKit provider not available after synchronous setup!"
-                )
-                completion()
-                return
-            }
+            let callKitProvider = callKitManager.setupSynchronously()
 
             NSLog("[TelnyxVoipPushHandler] ✅ CallKit provider ready, reporting incoming call")
 
@@ -799,6 +1664,7 @@ import React
                 "uuid": callUUID.uuidString,
                 "direction": "incoming",
                 "source": isAppRunning ? "push_notification" : "terminated_app_push",
+                "isCallKitRegistered": false,
             ]
 
             // Report to CallKit immediately
@@ -807,18 +1673,27 @@ import React
             callUpdate.remoteHandle = handle
             callUpdate.hasVideo = false
             callUpdate.localizedCallerName = callerName
+            callUpdate.supportsHolding = true
 
             callKitProvider.reportNewIncomingCall(with: callUUID, update: callUpdate) { error in
                 if let error = error {
+                    let nsError = error as NSError
+                    let reason =
+                        nsError.domain == CXErrorDomainIncomingCall && nsError.code == 3
+                        ? "filteredByDoNotDisturb" : "registrationRejected"
                     NSLog(
-                        "[TelnyxVoipPushHandler] ❌ CallKit error during terminated app handling: \(error.localizedDescription)"
+                        "[TelnyxVoipPushHandler] CallKit incoming registration rejected: domain=\(nsError.domain), code=\(nsError.code), reason=\(reason)"
                     )
                     callKitManager.activeCalls.removeValue(forKey: callUUID)
+                    callKitManager.clearPendingPushData(for: callUUID.uuidString)
                 } else {
                     NSLog(
                         "[TelnyxVoipPushHandler] ✅ CallKit call reported successfully via unified path"
                     )
 
+                    callKitManager.markCallKitRegistered(callUUID)
+                    self.storePendingVoipPush(payload.dictionaryPayload)
+
                     // CRITICAL: Store the CallKit UUID for the React Native CallKitCoordinator
                     // This allows the coordinator to find the existing CallKit call instead of creating a duplicate
                     UserDefaults.standard.set(callUUID.uuidString, forKey: "@pending_callkit_uuid")