@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-ios-calls/references/call-session.md

@@ -1,218 +0,0 @@
-# Call session — no ringing (iOS)
-
-Server-generated sessionId, both parties enter it. Customer-validated against `calls-sdk-ios-5/sample-apps/cometchat-calls-sample-app-ios/CometChatCallsSample/CallView.swift`.
-
-**Read first:** `cometchat-react-calls/references/call-session.md` — cross-platform architecture (sessionId strategies, server-side authorization). Then come back here for the iOS shape.
-
-**Known issue:** iOS V5 native (`CometChatCallsSDK`) is currently blocked upstream by a Cloudsmith 404 on the WebRTC binary. See `docs/known-issues-v4.2.0.md`. This file describes the correct shape for when the binary becomes available; the canonical pattern itself is sound.
-
----
-
-## Hard rules (iOS-specific overrides on top of the cross-platform rules)
-
-1. **Two-step session start: `generateToken` then `startSession`.** `CometChatCalls.generateToken(authToken:sessionID:onSuccess:onError:)` returns a call token; pass it to `CometChatCalls.startSession(callToken:callSetting:view:onSuccess:onError:)`. There is NO `joinSession` convenience method on the iOS Calls SDK v5.
-2. **`CallSettingsBuilder()` is the canonical settings shape** (chained `.setIsAudioOnly(false).setStartVideoMuted(false).setStartAudioMuted(false).setDelegate(coordinator).build()`). There is NO `SessionSettings` or `SessionSettingsBuilder` type.
-3. **`CallsEventsDelegate` protocol on a Coordinator object**, set via `CallSettingsBuilder.setDelegate(_:)` or registered with `CometChatCalls.addCallEventListener(observerId:delegate:)`. There is NO `SessionStatusListener`, NO `ButtonClickListener`, NO `CometChatCallsEventsListener`, and NO `addEventListener(.sessionLeft)`.
-4. **`onCallEnded` and `onCallEndButtonPressed` trigger UI dismiss.** These are the real termination callbacks; ignoring either leaves the call view stranded. `CallsEventsDelegate` ALSO has an optional `onSessionTimeout()` callback (swiftinterface:30) that fires when the idle timeout set via `CallSettingsBuilder.setIdleTimeoutPeriod(_:)` elapses — handle it for dismiss/cleanup too. See `references/idle-timeout.md`.
-5. **For standalone session-only integrations, the Chat SDK is OPTIONAL.** The upstream iOS sample never imports `CometChatSDK` (the chat SDK). Keep `CometChat.init` / `CometChat.login` only for additive (chat + calls) integrations.
-6. **`AVAudioSession` activated with `.playAndRecord` + `.voiceChat`** — `.playback` mode captures NO mic input.
-
----
-
-## SwiftUI + UIViewRepresentable (canonical shape)
-
-```swift
-import SwiftUI
-import CometChatCallsSDK
-
-struct CallView: View {
-    let sessionID: String
-    @Environment(\.dismiss) private var dismiss
-    @State private var errorMessage: String?
-
-    var body: some View {
-        ZStack {
-            Color.black.ignoresSafeArea()
-            CallContainerView(
-                sessionID: sessionID,
-                onEnd: { dismiss() },
-                onError: { msg in errorMessage = msg }
-            )
-        }
-        .alert("Call Error", isPresented: .init(
-            get: { errorMessage != nil },
-            set: { if !$0 { errorMessage = nil; dismiss() } }
-        )) {
-            Button("OK") { errorMessage = nil; dismiss() }
-        } message: {
-            Text(errorMessage ?? "")
-        }
-    }
-}
-
-// MARK: - UIKit container bridging the Calls SDK
-
-struct CallContainerView: UIViewRepresentable {
-    let sessionID: String
-    let onEnd: () -> Void
-    let onError: (String) -> Void
-
-    func makeUIView(context: Context) -> UIView {
-        let container = UIView()
-        container.backgroundColor = .black
-        startSession(container: container, coordinator: context.coordinator)
-        return container
-    }
-
-    func updateUIView(_ uiView: UIView, context: Context) {}
-
-    func makeCoordinator() -> Coordinator {
-        Coordinator(onEnd: onEnd)
-    }
-
-    private func startSession(container: UIView, coordinator: Coordinator) {
-        let settings = CallSettingsBuilder()
-            .setIsAudioOnly(false)
-            .setStartVideoMuted(false)
-            .setStartAudioMuted(false)
-            .setDelegate(coordinator)        // CallsEventsDelegate — set here, on the builder
-            .build()
-
-        // Two-step: generateToken THEN startSession. There is no joinSession convenience.
-        // authToken is nil for session-only apps (Calls SDK derives it server-side from the
-        // session); pass CometChat.getUserAuthToken() in additive (chat + calls) integrations.
-        CometChatCalls.generateToken(authToken: nil, sessionID: sessionID) { token in
-            guard let token = token else {
-                DispatchQueue.main.async { onError("Failed to generate call token") }
-                return
-            }
-            CometChatCalls.startSession(
-                callToken: token,
-                callSetting: settings,
-                view: container
-            ) { _ in
-                // session started — delegate already wired via setDelegate
-            } onError: { error in
-                DispatchQueue.main.async {
-                    onError(error?.errorDescription ?? "Failed to start call")
-                }
-            }
-        } onError: { error in
-            DispatchQueue.main.async {
-                onError(error?.errorDescription ?? "Failed to generate call token")
-            }
-        }
-    }
-
-    class Coordinator: NSObject, CallsEventsDelegate {
-        let onEnd: () -> Void
-
-        init(onEnd: @escaping () -> Void) {
-            self.onEnd = onEnd
-        }
-
-        // --- CallsEventsDelegate (all @objc optional) ---
-        func onCallEnded() {
-            DispatchQueue.main.async { self.onEnd() }
-        }
-
-        func onCallEndButtonPressed() {
-            CometChatCalls.endSession()           // EXISTS on the static facade
-            DispatchQueue.main.async { self.onEnd() }
-        }
-    }
-}
-```
-
-**Why this shape:**
-
-- **`UIViewRepresentable` bridging a `UIView` container**, not a raw SwiftUI view — the SDK draws into a `UIView` it owns and lays out internally. SwiftUI can't host that directly.
-- **`generateToken` then `startSession`** — the iOS Calls SDK v5 has no single-call `joinSession`. Generate the call token, then start the session into the container `UIView`.
-- **`CallSettingsBuilder().build()`** — chained builder ending in `.build()` returning `CallSettings`. There is no `SessionSettings`/`SessionSettingsBuilder` type.
-- **`Coordinator` implements `CallsEventsDelegate`** — wired via `setDelegate(_:)` on the builder. There is no `SessionStatusListener`/`ButtonClickListener`; do not register against `CallSession.shared` (it doesn't exist).
-
----
-
-## Required iOS configuration
-
-`Info.plist`:
-```xml
-<key>NSCameraUsageDescription</key>
-<string>Camera is needed for video calls</string>
-<key>NSMicrophoneUsageDescription</key>
-<string>Microphone is needed for calls</string>
-<key>UIBackgroundModes</key>
-<array>
-    <string>audio</string>
-    <string>voip</string>
-</array>
-```
-
-`AVAudioSession` setup (call once at app launch):
-```swift
-import AVFoundation
-
-let session = AVAudioSession.sharedInstance()
-try? session.setCategory(.playAndRecord, mode: .voiceChat, options: [.allowBluetooth, .defaultToSpeaker])
-try? session.setActive(true)
-```
-
-See `references/avaudiosession-routing.md` for full audio routing including AirPods / CarPlay handoff.
-
----
-
-## Universal Link routing
-
-`SceneDelegate.scene(_:continue:)`:
-```swift
-func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
-    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
-          let url = userActivity.webpageURL,
-          url.pathComponents.count >= 3,
-          url.pathComponents[1] == "meet" else { return }
-    let sessionID = url.pathComponents[2]
-    router.routeToCallView(sessionID: sessionID)
-}
-```
-
-Configure `applinks:yourapp.com` per `references/share-invite.md`.
-
----
-
-## Anti-patterns
-
-1. **Looking for a single-call `joinSession(sessionID:)` convenience.** It does not exist on iOS v5. Always do `generateToken` → `startSession`.
-2. **`SessionSettings` / `SessionSettingsBuilder`.** Neither type exists. Use `CallSettingsBuilder()...build()`.
-3. **`CometChatCalls.addEventListener(.sessionLeft)` or `SessionStatusListener`/`ButtonClickListener`.** None exist. iOS uses the `CallsEventsDelegate` protocol set via `setDelegate(_:)` or `addCallEventListener(observerId:delegate:)`.
-4. **Skipping the `onCallEnded` callback.** The call ends via this (remote hangup, server end) → call view stays mounted forever. (For idle-timeout termination, also handle `onSessionTimeout()` — swiftinterface:30.)
-5. **Starting the session from `viewDidAppear`.** Re-runs on every navigation push. Use `viewDidLoad` + a `started` flag, OR use `UIViewRepresentable` + Coordinator (the pattern above).
-6. **`AVAudioSession.setCategory(.playback)`.** Mic input doesn't capture. Use `.playAndRecord` + `.voiceChat` mode.
-7. **`async/await` on `startSession`/`generateToken`.** They use completion handlers — `try await` does nothing.
-8. **Initializing Chat SDK for a session-only integration.** Wastes time and adds two extra failure modes. Drop `CometChat.init` / `CometChat.login` entirely for standalone session apps.
-
----
-
-## Verification checklist
-
-- [ ] `generateToken(authToken:sessionID:)` → `startSession(callToken:callSetting:view:)` two-step (no `joinSession`)
-- [ ] Settings built via `CallSettingsBuilder()`, not `SessionSettings`/`SessionSettingsBuilder`
-- [ ] `CallsEventsDelegate` protocol implemented on a Coordinator class
-- [ ] Coordinator wired via `CallSettingsBuilder.setDelegate(_:)` (or `addCallEventListener(observerId:delegate:)`)
-- [ ] `onCallEnded` and `onCallEndButtonPressed` both trigger dismiss
-- [ ] `Info.plist` has `NSCameraUsageDescription`, `NSMicrophoneUsageDescription`, `UIBackgroundModes: audio, voip`
-- [ ] `AVAudioSession.setCategory(.playAndRecord, mode: .voiceChat, ...)`
-- [ ] Universal Link routing wired in SceneDelegate
-- [ ] **Standalone session-only:** no `CometChatSDK` (chat SDK) import — Calls SDK alone
-- [ ] **Additive (chat + calls):** dual-SDK contract preserved
-- [ ] Real-device smoke: tap meeting link in Messages → app opens at `/meet/:sessionID` → joins
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/call-session.md` — cross-platform architecture
-- `cometchat-ios-calls/SKILL.md` — iOS seven hard rules
-- `cometchat-ios-calls/references/share-invite.md` — Universal Link config
-- `cometchat-ios-calls/references/avaudiosession-routing.md` — audio session routing
-- Upstream iOS sample — `calls-sdk-ios-5/sample-apps/cometchat-calls-sample-app-ios/CometChatCallsSample/CallView.swift`
-- Canonical docs: https://www.cometchat.com/docs/calls/ios/join-session

package/skills/cometchat-ios-calls/references/callkit-and-pushkit.md

@@ -1,357 +0,0 @@
-# CallKit + PushKit on iOS — the canonical implementation
-
-iOS is the only platform where the OS owns the incoming-call UI. CallKit + PushKit isn't optional for production — without them, calls don't ring on locked devices and Apple rejects production builds. This reference is the full implementation; the SKILL.md sketches it, here is the code.
-
----
-
-## Why two frameworks
-
-| Framework | Role |
-|---|---|
-| **PushKit** | Receives high-priority VoIP push payloads, even when the app is terminated. Separate from APNs. |
-| **CallKit** | Presents the system incoming-call UI (lock-screen, even on locked device), reports call state to the OS, integrates with Phone app's "Recents" list. |
-
-Combined: a VoIP push wakes the app via PushKit; the app immediately reports the call to CallKit; CallKit takes over and shows the system UI.
-
----
-
-## Apple Developer setup (one-time, manual)
-
-The skill cannot automate these:
-
-1. **Create a VoIP Services certificate** in Apple Developer portal → Certificates → "+" → VoIP Services.
-2. **Pin to the bundle ID** of your app.
-3. **Download the .p12** and convert to .pem if your push server needs it (`openssl pkcs12 -in cert.p12 -out cert.pem -nodes`).
-4. **Upload to your push server.** This is a SEPARATE certificate from your standard APNs cert.
-
-The skill prints these steps and waits for the user to confirm before proceeding.
-
----
-
-## Xcode setup
-
-In the target's "Signing & Capabilities":
-
-1. Click "+" → "Push Notifications" → adds the entitlement.
-2. Click "+" → "Background Modes" → check:
-   - ☑ Audio, AirPlay, and Picture in Picture
-   - ☑ Voice over IP
-   - ☑ Remote notifications
-
-Verify the resulting `Info.plist` has:
-
-```xml
-<key>UIBackgroundModes</key>
-<array>
-  <string>audio</string>
-  <string>voip</string>
-  <string>remote-notification</string>
-</array>
-<key>NSMicrophoneUsageDescription</key>
-<string>So you can talk during voice and video calls.</string>
-<key>NSCameraUsageDescription</key>
-<string>So you can be seen during video calls.</string>
-```
-
----
-
-## App entry — register PushKit + CallKit
-
-### SwiftUI (`@main App`)
-
-```swift
-import SwiftUI
-import PushKit
-import CallKit
-import CometChatSDK
-import CometChatCallsSDK
-
-@main
-struct YourApp: App {
-  @StateObject private var callManager = CallManager.shared
-
-  var body: some Scene {
-    WindowGroup {
-      ContentView()
-        .onAppear {
-          CometChat.init(appId: Secrets.cometchatAppID, appSettings: appSettings) { isInitialized, error in
-            guard error == nil else { return }
-            CometChatCalls.init(callsAppSettings: callAppSettings) { _ in
-              callManager.registerForPushKit()                     // wait for SDK ready
-            }
-          }
-        }
-    }
-  }
-}
-```
-
-### UIKit (`AppDelegate`)
-
-```swift
-import UIKit
-import PushKit
-import CallKit
-
-@main
-class AppDelegate: UIResponder, UIApplicationDelegate {
-  func application(_ app: UIApplication, didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
-    CometChat.init(appId: Secrets.cometchatAppID, appSettings: appSettings) { _, error in
-      guard error == nil else { return }
-      CometChatCalls.init(callsAppSettings: callAppSettings) { _ in
-        CallManager.shared.registerForPushKit()
-      }
-    }
-    return true
-  }
-}
-```
-
----
-
-## CallManager — the shared state holder
-
-```swift
-import PushKit
-import CallKit
-import CometChatCallsSDK
-
-class CallManager: NSObject, ObservableObject {
-  static let shared = CallManager()
-
-  private let pushRegistry = PKPushRegistry(queue: .main)
-  private let provider: CXProvider
-  private let callController = CXCallController()
-
-  private override init() {
-    let config = CXProviderConfiguration(localizedName: "YourApp")
-    config.supportsVideo = true
-    config.maximumCallGroups = 1
-    config.maximumCallsPerCallGroup = 1
-    config.supportedHandleTypes = [.generic]
-    config.iconTemplateImageData = UIImage(named: "CallKitIcon")?.pngData()
-    config.ringtoneSound = "ringtone.caf"
-
-    self.provider = CXProvider(configuration: config)
-    super.init()
-    provider.setDelegate(self, queue: .main)
-  }
-
-  func registerForPushKit() {
-    pushRegistry.delegate = self
-    pushRegistry.desiredPushTypes = [.voIP]
-  }
-
-  func reportIncomingCall(uuid: UUID, callerName: String, callerUid: String, hasVideo: Bool) {
-    let update = CXCallUpdate()
-    update.remoteHandle = CXHandle(type: .generic, value: callerUid)
-    update.localizedCallerName = callerName
-    update.hasVideo = hasVideo
-
-    provider.reportNewIncomingCall(with: uuid, update: update) { error in
-      if let error = error {
-        print("Failed to report incoming call: \(error)")
-      }
-    }
-  }
-}
-```
-
----
-
-## PushKit delegate — the 5-second rule
-
-```swift
-extension CallManager: PKPushRegistryDelegate {
-  func pushRegistry(_ registry: PKPushRegistry, didUpdate credentials: PKPushCredentials, for type: PKPushType) {
-    guard type == .voIP else { return }
-    let token = credentials.token.map { String(format: "%02x", $0) }.joined()
-    // Send this token to your server, keyed by the logged-in CometChat UID
-    Task {
-      await sendVoipTokenToServer(token: token, uid: CometChat.getLoggedInUser()?.uid ?? "")
-    }
-  }
-
-  func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) {
-    guard type == .voIP else { completion(); return }
-
-    // CRITICAL: report to CallKit IMMEDIATELY. iOS terminates apps that delay this >~5s.
-    let data = payload.dictionaryPayload["data"] as? [String: Any] ?? [:]
-    let sessionId = data["sessionId"] as? String ?? UUID().uuidString
-    let callerName = data["callerName"] as? String ?? "Unknown"
-    let callerUid = data["callerUid"] as? String ?? ""
-    let hasVideo = (data["callType"] as? String) == "video"
-
-    let uuid = UUID(uuidString: sessionId) ?? UUID()
-    reportIncomingCall(uuid: uuid, callerName: callerName, callerUid: callerUid, hasVideo: hasVideo)
-
-    // Store sessionId for later when CXAnswerCallAction fires
-    self.pendingSessionIds[uuid] = sessionId
-
-    completion()                     // ← tell iOS we're done
-  }
-
-  // iOS may invalidate the token (OS upgrade, app reinstall)
-  func pushRegistry(_ registry: PKPushRegistry, didInvalidatePushTokenFor type: PKPushType) {
-    // Token will re-register; wait for didUpdate
-  }
-}
-```
-
-**The 5-second rule:** Apple's `PKPushRegistry` documentation says you must call `reportNewIncomingCall` "promptly." Practical limit: ~5 seconds. If you exceed it, iOS terminates your app process and won't deliver future VoIP pushes for ~24 hours (apologies, no public retry mechanism).
-
----
-
-## CallKit delegate — answer + end actions
-
-```swift
-extension CallManager: CXProviderDelegate {
-  func providerDidReset(_ provider: CXProvider) {
-    // OS reset everything — clean up local state
-    pendingSessionIds.removeAll()
-  }
-
-  func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
-    // User tapped "Answer" on the lock screen
-    guard let sessionId = pendingSessionIds[action.callUUID] else {
-      action.fail()
-      return
-    }
-
-    Task {
-      do {
-        // Accept via Chat SDK
-        try await CometChat.acceptCall(sessionID: sessionId)
-
-        // Configure AVAudioSession for voice/video call audio
-        try AVAudioSession.sharedInstance().setCategory(.playAndRecord, mode: .voiceChat)
-        try AVAudioSession.sharedInstance().setActive(true)
-
-        // Build session settings via CallSettingsBuilder. The CallsEventsDelegate
-        // is wired with setDelegate(_:); there is no SessionSettings(Builder).
-        let settings = CallSettingsBuilder()
-          .setIsAudioOnly(false)
-          .setStartVideoMuted(false)
-          .setStartAudioMuted(false)
-          .setDelegate(callListener)        // callListener conforms to CallsEventsDelegate
-          .build()
-
-        // Two-step: generateToken THEN startSession. There is no joinSession.
-        // `view` is the UIView the ongoing-call UI will be drawn into.
-        CometChatCalls.generateToken(authToken: CometChat.getUserAuthToken(), sessionID: sessionId) { token in
-          guard let token = token else {
-            print("generateToken returned nil")
-            action.fail()
-            return
-          }
-          CometChatCalls.startSession(
-            callToken: token,
-            callSetting: settings,
-            view: callContainerView   // a UIView with measurable bounds
-          ) { _ in
-            action.fulfill()                // tell CallKit we answered successfully
-          } onError: { error in
-            print("startSession failed: \(error?.errorDescription ?? "unknown")")
-            action.fail()
-          }
-        } onError: { error in
-          print("generateToken failed: \(error?.errorDescription ?? "unknown")")
-          action.fail()
-        }
-
-        // Navigate the app's UI to the ongoing-call screen
-        await MainActor.run {
-          // ...your nav logic — push the view that hosts callContainerView...
-        }
-      } catch {
-        action.fail()
-      }
-    }
-  }
-
-  func provider(_ provider: CXProvider, perform action: CXEndCallAction) {
-    // User tapped "End" or call ended remotely.
-    CometChatCalls.endSession()   // EXISTS on the static facade in v5
-
-    // CRITICAL: deactivate audio session (rule 1.5)
-    do {
-      try AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
-    } catch {
-      // log but don't block
-    }
-
-    pendingSessionIds.removeValue(forKey: action.callUUID)
-    action.fulfill()
-  }
-
-  func provider(_ provider: CXProvider, perform action: CXSetMutedCallAction) {
-    CometChatCalls.audioMuted(action.isMuted)   // NOT muteAudio
-    action.fulfill()
-  }
-}
-```
-
----
-
-## Outgoing calls — also through CallKit
-
-For caller-initiated calls, report via `CXStartCallAction` so the call appears in the iOS Phone app's Recents:
-
-```swift
-extension CallManager {
-  func startOutgoingCall(receiverUid: String, callType: CallType) {
-    let uuid = UUID()
-    let handle = CXHandle(type: .generic, value: receiverUid)
-    let action = CXStartCallAction(call: uuid, handle: handle)
-    action.isVideo = (callType == .video)
-
-    let transaction = CXTransaction(action: action)
-    callController.request(transaction) { error in
-      if let error = error {
-        print("Failed to start outgoing call: \(error)")
-      }
-    }
-  }
-}
-
-extension CallManager {
-  // CXProviderDelegate
-  func provider(_ provider: CXProvider, perform action: CXStartCallAction) {
-    Task {
-      do {
-        let outgoing = Call(receiverId: action.handle.value,
-                           callType: action.isVideo ? .video : .audio,   // CallType has no .voice
-                           receiverType: .user)
-        let initiated = try await CometChat.initiateCall(call: outgoing)
-        pendingSessionIds[action.callUUID] = initiated.sessionID
-        provider.reportOutgoingCall(with: action.callUUID, startedConnectingAt: nil)
-        action.fulfill()
-      } catch {
-        action.fail()
-      }
-    }
-  }
-}
-```
-
-This gives the user a "Calling..." UI in the iOS system. When the receiver accepts, `provider.reportOutgoingCall(connectedAt:)` switches the UI to "Connected."
-
----
-
-## Common failure modes
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| App terminates 5s after PushKit delivery | Async work before `reportNewIncomingCall` | Report first, then do anything else |
-| "VoIP services not available" at registry setup | Background Modes capability missing | Add VoIP capability in Xcode and rebuild |
-| Token never registers | App not signed with VoIP-capable provisioning profile | Re-download provisioning profile |
-| Call rings but answering does nothing | `CXAnswerCallAction` delegate doesn't fail/fulfill | Always call `action.fulfill()` or `action.fail()` |
-| Music doesn't resume after hangup | Missing `setActive(false, .notifyOthersOnDeactivation)` | Add to `CXEndCallAction` handler |
-| Lock-screen rings but unlocking shows wrong screen | App didn't navigate to ongoing-call view in `CXAnswerCallAction` | Navigate inside the action handler |
-| Outgoing call never shows "Calling..." UI | Started via `initiateCall` directly without `CXStartCallAction` | Use `CXTransaction` flow |
-
----
-
-## Testing without a push server
-
-Same workaround as RN — call `CallManager.shared.reportIncomingCall(...)` from a debug button. Bypasses PushKit entirely. Useful for testing the in-app + CallKit-UI flow but doesn't exercise the lock-screen ring (which requires PushKit delivery to an unlocked or terminated app).