@cometchat/skills 4.4.2 → 5.0.0

package/skills/cometchat-ios-calls/references/avaudiosession-routing.md

@@ -1,188 +0,0 @@
-# AVAudioSession routing for iOS calls
-
-The most-overlooked piece of iOS calls. Without correct `AVAudioSession` configuration, calls sound like the user is talking through an earpiece even with the speaker on, or background music doesn't resume after hangup.
-
----
-
-## The four states that matter
-
-| State | When |
-|---|---|
-| Inactive | App not in a call |
-| Active + .playAndRecord, .voiceChat | Active call (voice or video) |
-| Active + .playAndRecord, .videoChat | Active video call (slightly different routing — closer to face) |
-| Inactive + .notifyOthersOnDeactivation | Just hung up — tells music apps to resume |
-
----
-
-## On call start
-
-```swift
-import AVFoundation
-
-func configureForCall(isVideo: Bool) throws {
-  let session = AVAudioSession.sharedInstance()
-
-  try session.setCategory(
-    .playAndRecord,
-    mode: isVideo ? .videoChat : .voiceChat,
-    options: [.allowBluetooth, .allowBluetoothA2DP, .defaultToSpeaker]
-  )
-
-  try session.setActive(true)
-}
-```
-
-`mode: .voiceChat` enables echo cancellation and noise suppression optimized for voice calls. `mode: .videoChat` does the same but defaults to a slightly louder speaker volume (designed for handsfree use).
-
-`.allowBluetooth` allows AirPods, hearing aids. `.allowBluetoothA2DP` allows Bluetooth speakers. `.defaultToSpeaker` makes voice calls speakerphone by default — without it, calls route to the earpiece, which feels wrong for a video call.
-
----
-
-## On hangup — the canonical bug fix
-
-```swift
-func endCall() {
-  CometChatCalls.endSession()   // EXISTS on the static facade in v5
-
-  do {
-    try AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
-  } catch {
-    // Best-effort — don't block hangup on this
-    print("Failed to deactivate audio session: \(error)")
-  }
-}
-```
-
-`.notifyOthersOnDeactivation` is the magic. Without it:
-
-- Music app was paused by the call → stays paused
-- Other apps' audio was ducked → stays ducked
-- The user thinks the music app is broken
-
-With it, the system tells other audio sessions "the call's done, resume what you were doing."
-
----
-
-## Switching speaker on/off mid-call
-
-```swift
-func toggleSpeaker(on: Bool) throws {
-  let session = AVAudioSession.sharedInstance()
-  try session.overrideOutputAudioPort(on ? .speaker : .none)
-}
-```
-
-`.none` doesn't mean "no audio" — it means "use the system's default routing for this category" (which for `.playAndRecord` + `.voiceChat` is the receiver/earpiece).
-
----
-
-## Detecting Bluetooth + AirPods + hearing aids
-
-```swift
-func currentAudioRoute() -> String {
-  let route = AVAudioSession.sharedInstance().currentRoute
-  let outputs = route.outputs.map { $0.portType.rawValue }
-  // Common values: "Speaker", "Receiver", "BluetoothA2DPOutput", "BluetoothHFP", "BuiltInReceiver"
-  return outputs.first ?? "unknown"
-}
-
-func observeRouteChanges() {
-  NotificationCenter.default.addObserver(
-    forName: AVAudioSession.routeChangeNotification,
-    object: nil,
-    queue: .main
-  ) { notification in
-    // User plugged in headphones / unplugged AirPods
-    print("Route changed: \(self.currentAudioRoute())")
-  }
-}
-```
-
-For UI: show a "Speaker / AirPods / Bluetooth" indicator in the call control panel based on `currentAudioRoute()`.
-
----
-
-## CallKit + AVAudioSession — they fight if you don't coordinate
-
-CallKit's `provider(_:didActivate:)` callback fires when CallKit takes over the audio session (typically when the user answers from the lock screen). If you call `setActive(true)` yourself in the answer handler, CallKit might do it again and you get warnings.
-
-**Pattern:**
-
-```swift
-extension CallManager: CXProviderDelegate {
-  func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
-    // CallKit just activated the session — do post-activation work
-    // (e.g. start the WebRTC session)
-    if let pendingSessionId = self.pendingActivation {
-      startCometChatCallsSession(sessionID: pendingSessionId)
-      self.pendingActivation = nil
-    }
-  }
-
-  func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
-    // CallKit deactivated — your cleanup runs in CXEndCallAction
-  }
-
-  func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
-    // Configure category but DO NOT set active
-    try? AVAudioSession.sharedInstance().setCategory(
-      .playAndRecord, mode: .voiceChat,
-      options: [.allowBluetooth, .defaultToSpeaker]
-    )
-
-    // Store sessionId; defer startSession to didActivate
-    self.pendingActivation = pendingSessionIds[action.callUUID]
-    action.fulfill()
-  }
-}
-```
-
-CallKit calls `setActive(true)` for you when it's done with its lock-screen UI. You call `startSession` (after `generateToken`) from `didActivate`.
-
-For non-CallKit-driven calls (outgoing from inside the app), you do `setActive(true)` yourself.
-
----
-
-## Common failure modes
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| Music doesn't resume after call | Missing `.notifyOthersOnDeactivation` | Add to `setActive(false, ...)` call |
-| Voice call sounds quiet, like through phone receiver | Missing `.defaultToSpeaker` option | Add to `setCategory` options |
-| Bluetooth headphones not used during call | Missing `.allowBluetooth` option | Add to `setCategory` options |
-| CXAnswerCallAction races with `setActive(true)` | Manual `setActive(true)` in answer handler | Defer `startSession` to `didActivate` |
-| Echo / feedback during voice call | Wrong `mode` (e.g. `.default` instead of `.voiceChat`) | Use `.voiceChat` or `.videoChat` |
-| Call audio works in foreground but cuts in background | UIBackgroundModes missing `audio` | Add `audio` to `Info.plist` UIBackgroundModes |
-
----
-
-## Audio session interruptions
-
-Phone calls (the actual phone, not your VoIP) can interrupt your call:
-
-```swift
-NotificationCenter.default.addObserver(
-  forName: AVAudioSession.interruptionNotification,
-  object: AVAudioSession.sharedInstance(),
-  queue: .main
-) { notification in
-  guard let userInfo = notification.userInfo,
-        let typeValue = userInfo[AVAudioSessionInterruptionTypeKey] as? UInt,
-        let type = AVAudioSession.InterruptionType(rawValue: typeValue) else { return }
-
-  switch type {
-  case .began:
-    // Phone call started — pause our call's audio (CallKit may auto-handle this for you)
-    CometChatCalls.audioMuted(true)   // NOT muteAudio
-  case .ended:
-    // Phone call ended — resume
-    CometChatCalls.audioMuted(false)
-    try? AVAudioSession.sharedInstance().setActive(true)
-  @unknown default:
-    break
-  }
-}
-```
-
-If you've integrated CallKit fully, iOS handles most of this — your VoIP call shows up as a "second call" in the system UI and the user can choose which to keep.

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

@@ -1,76 +0,0 @@
-# Call layouts on iOS
-
-The iOS Calls SDK v5 exposes layout via the `DisplayModes` enum (swiftinterface:175 — `.default` / `.single` / `.spotlight`), passed ONCE at session start via `CallSettingsBuilder.setMode(_:)`. The current setter is `setMode(_ value: DisplayModes) -> Self` (swiftinterface:281); the `setMode(_ value: NSString)` string overload (swiftinterface:280) is DEPRECATED — prefer the typed enum. There is no `CallLayout` type, no runtime `setLayout`, no `setHideChangeLayoutButton`, and no `onCallLayoutChanged` callback. To change layout you must end and restart the session with a different `setMode`.
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/ios/call-layouts
-
----
-
-## SDK API
-
-```swift
-import CometChatCallsSDK
-
-let settings = CallSettingsBuilder()
-  .setIsAudioOnly(false)
-  .setMode(.default)         // swiftinterface:281 setMode(_ value: DisplayModes) -> Self
-  .build()
-```
-
-`setMode` takes a `DisplayModes` value:
-
-| Value | Meaning |
-|---|---|
-| `.default` | Standard grid of participant tiles |
-| `.single` | One participant fills the surface |
-| `.spotlight` | Active speaker enlarged, others as a strip |
-
-> **There is no runtime layout switch.** `CometChatCalls` has no `setLayout`/`setMode` instance/static method that re-lays-out a live session. `setMode(_:)` exists only on `CallSettingsBuilder` and only takes effect at `startSession`. If you need to offer a switcher, tear down and restart the session with new settings (expensive — most apps just pick one mode).
-
----
-
-## Picking a layout at session start
-
-```swift
-// Read a persisted preference and map it to a DisplayModes value before startSession:
-let stored = UserDefaults.standard.string(forKey: "preferredDisplayMode") ?? "default"
-let mode: DisplayModes = {
-  switch stored {
-  case "single":    return .single
-  case "spotlight": return .spotlight
-  default:          return .default
-  }
-}()
-let settings = CallSettingsBuilder()
-  .setMode(mode)
-  .build()
-// ... generateToken → startSession(callToken:callSetting:view:) ...
-```
-
-A SwiftUI `Picker(.segmented)` over the three modes is a fine way to capture the preference BEFORE the call starts (on a pre-join screen). It cannot drive a live re-layout.
-
----
-
-## Anti-patterns
-
-1. **`CallLayout` / `.tile` / `.sidebar`.** Don't exist on iOS v5. `setMode` takes a `DisplayModes` value (`.default`/`.single`/`.spotlight`, swiftinterface:175). The deprecated `setMode(_ value: NSString)` string overload still exists but prefer the typed enum.
-2. **`CometChatCalls.setLayout(...)` mid-call.** No such method. Layout is fixed at `startSession`.
-3. **Implementing `onCallLayoutChanged` on the delegate.** Not a callback on `CallsEventsDelegate`. There is no layout-change event.
-4. **`setHideChangeLayoutButton(_:)`.** Not a `CallSettingsBuilder` method.
-
----
-
-## Verification checklist
-
-- [ ] Layout set via `CallSettingsBuilder.setMode(_:)` with a `DisplayModes` value (`.default`/`.single`/`.spotlight`)
-- [ ] No `CallLayout`, `.tile`, `.sidebar`, `setLayout`, `onCallLayoutChanged`, or `setHideChangeLayoutButton` anywhere
-- [ ] Any preference UI captured BEFORE `startSession` (no live switch attempted)
-- [ ] User preference persisted via `UserDefaults` if desired
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/call-layouts.md` — sister (web exposes more layout control)
-- `cometchat-ios-calls` SKILL.md
-- Canonical docs: https://www.cometchat.com/docs/calls/ios/call-layouts

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