@cometchat/skills 4.1.0 → 4.2.0

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

@@ -0,0 +1,189 @@
+# 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() does NOT exist on iOS — use leaveSession on CallSession.shared
+  CometChatCallsSDK.CallSession.shared.leaveSession()
+
+  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 joinSession 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 `joinSession` 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 `joinSession` 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.muteAudio(true)
+  case .ended:
+    // Phone call ended — resume
+    CometChatCalls.muteAudio(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

@@ -0,0 +1,136 @@
+# Call layouts on iOS
+
+Same three layouts (TILE/SIDEBAR/SPOTLIGHT). iOS-specific: `UISegmentedControl` is the native pattern for the switcher; layout selection persists across the app via `UserDefaults`.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/ios/call-layouts
+**Read first:** `cometchat-react-calls/references/call-layouts.md` — layout matrix.
+
+---
+
+## SDK API
+
+```swift
+import CometChatCallsSDK
+
+let settings = CallSettingsBuilder()
+  .setSessionType(.video)
+  .setLayout(.tile)        // .tile | .sidebar | .spotlight
+  .setHideChangeLayoutButton(false)
+  .build()
+
+// Mid-call switch
+CometChatCalls.setLayout(.spotlight)
+
+// Listen
+class CallEvents: CometChatCallsEventsListener {
+  func onCallLayoutChanged(layout: CallLayout) {
+    DispatchQueue.main.async {
+      // Update UI
+    }
+  }
+}
+```
+
+---
+
+## SwiftUI switcher
+
+```swift
+import SwiftUI
+
+enum CallLayoutPicker: String, CaseIterable, Identifiable {
+  case tile = "Tile"
+  case sidebar = "Sidebar"
+  case spotlight = "Spotlight"
+  var id: String { rawValue }
+
+  var sdkLayout: CallLayout {
+    switch self {
+    case .tile: return .tile
+    case .sidebar: return .sidebar
+    case .spotlight: return .spotlight
+    }
+  }
+}
+
+struct LayoutSwitcher: View {
+  @State private var selection: CallLayoutPicker = .tile
+
+  var body: some View {
+    Picker("Layout", selection: $selection) {
+      ForEach(CallLayoutPicker.allCases) { opt in
+        Text(opt.rawValue).tag(opt)
+      }
+    }
+    .pickerStyle(.segmented)
+    .accessibilityLabel("Call layout")
+    .onChange(of: selection) { _, new in
+      CometChatCalls.setLayout(new.sdkLayout)
+    }
+  }
+}
+```
+
+`Picker(.segmented)` renders as `UISegmentedControl`, which is the iOS-native expected pattern for radio-group selection.
+
+---
+
+## Persisting the user's preference
+
+```swift
+extension UserDefaults {
+  var preferredCallLayout: CallLayout {
+    get {
+      switch string(forKey: "preferredCallLayout") {
+      case "sidebar": return .sidebar
+      case "spotlight": return .spotlight
+      default: return .tile
+      }
+    }
+    set {
+      let str: String = {
+        switch newValue {
+        case .tile: return "tile"
+        case .sidebar: return "sidebar"
+        case .spotlight: return "spotlight"
+        @unknown default: return "tile"
+        }
+      }()
+      set(str, forKey: "preferredCallLayout")
+    }
+  }
+}
+
+// In your CallViewController:
+let settings = CallSettingsBuilder()
+  .setLayout(UserDefaults.standard.preferredCallLayout)
+  .build()
+```
+
+---
+
+## Anti-patterns
+
+Web sister rules apply, plus iOS-specific:
+
+1. **`Picker(.menu)` instead of `.segmented`.** Wrong UX — menu hides the options, segmented shows them. For 3 options, segmented is the iOS norm.
+2. **`onChange` on background queue.** Crash. SwiftUI's `onChange` is on main but if you bridge through Combine make sure to `.receive(on: DispatchQueue.main)`.
+3. **Forgetting to `.accessibilityLabel`.** VoiceOver announces "Picker" with no context.
+
+---
+
+## Verification checklist
+
+- [ ] Initial layout via `setLayout` on builder
+- [ ] SwiftUI `Picker(.segmented)` for switcher
+- [ ] Layout listener implemented in `CometChatCallsEventsListener`
+- [ ] User preference persisted via `UserDefaults` if desired
+- [ ] Real-device smoke: switcher cycles all 3, persists across calls
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/call-layouts.md` — sister
+- `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

@@ -0,0 +1,221 @@
+# Call session — joinSession with no ringing (iOS)
+
+Server-generated sessionId, both parties enter it. Customer-validated against `~/Downloads/calls-sdk/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. **Use the `joinSession(sessionID:callSetting:container:onSuccess:onError:)` convenience method.** It handles token generation internally — you do NOT need to call `generateToken` separately. Matches the upstream sample exactly.
+2. **`SessionSettingsBuilder()` is the canonical settings shape** (chained `.setTitle().startVideoPaused(false).startAudioMuted(false).build()`). NOT `SessionSettings(sessionType:layout:)` — that initializer is the chat-side type.
+3. **`SessionStatusListener` protocol on a Coordinator object**, registered against `CometChatCallsSDK.CallSession.shared.addSessionStatusListener(...)`. NOT raw `CometChatCalls.addEventListener(.sessionLeft)` — that does not exist on iOS.
+4. **`onSessionLeft`, `onConnectionClosed`, `onSessionTimedOut` all trigger UI dismiss.** All three are real termination paths; ignoring any of them leaves the call view stranded.
+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 = SessionSettingsBuilder()
+            .setTitle("CometChat Meeting")
+            .startVideoPaused(false)
+            .startAudioMuted(false)
+            .build()
+
+        // The convenience joinSession(sessionID:) generates the token internally.
+        // No separate generateToken call needed.
+        CometChatCalls.joinSession(
+            sessionID: sessionID,
+            callSetting: settings,
+            container: container
+        ) { success in
+            let session = CometChatCallsSDK.CallSession.shared
+            session.addSessionStatusListener(coordinator)
+            session.addButtonClickListener(coordinator)
+        } onError: { error in
+            DispatchQueue.main.async {
+                onError(error?.errorDescription ?? "Failed to join call")
+            }
+        }
+    }
+
+    class Coordinator: NSObject, SessionStatusListener, ButtonClickListener {
+        let onEnd: () -> Void
+
+        init(onEnd: @escaping () -> Void) {
+            self.onEnd = onEnd
+        }
+
+        // --- SessionStatusListener ---
+        func onSessionJoined() {}
+
+        func onSessionLeft() {
+            DispatchQueue.main.async { self.onEnd() }
+        }
+
+        func onConnectionClosed() {
+            DispatchQueue.main.async { self.onEnd() }
+        }
+
+        func onSessionTimedOut() {
+            DispatchQueue.main.async { self.onEnd() }
+        }
+
+        func onConnectionLost() {}
+        func onConnectionRestored() {}
+
+        // --- ButtonClickListener ---
+        func onLeaveSessionButtonClicked() {
+            CometChatCallsSDK.CallSession.shared.leaveSession()
+        }
+    }
+}
+```
+
+**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.
+- **`joinSession(sessionID:callSetting:container:)` convenience** — generates the call token internally. No need for `CometChatCalls.generateToken(forSession:)` then `joinSession(callToken:)` two-step. The sample uses this and so should every customer.
+- **`SessionSettingsBuilder().build()`** — chained builder ending in `.build()`. The non-builder `SessionSettings(sessionType:layout:)` is the chat-side type and rejects at runtime.
+- **`Coordinator` implements `SessionStatusListener` AND `ButtonClickListener`** — register both against `CallSession.shared` AFTER `onSuccess` fires. Don't register against `CometChatCalls` — that's not where the events live.
+
+---
+
+## 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. **Calling `CometChatCalls.generateToken(forSession:)` then `joinSession(callToken:)`.** Two-step doesn't match the sample — the sample uses the single-call `joinSession(sessionID:)` convenience. Prior versions of this skill cited the two-step; it works but is not the canonical iOS shape.
+2. **`SessionSettings(sessionType:layout:)` initializer.** Wrong type — that's the chat-side entity. Use `SessionSettingsBuilder()...build()`.
+3. **`CometChatCalls.addEventListener(.sessionLeft)`** — iOS uses the protocol-based `SessionStatusListener`, not a string-keyed listener API.
+4. **Skipping `onConnectionClosed` and `onSessionTimedOut` callbacks.** User's call ends via either of these (network drop, server timeout) → call view stays mounted forever.
+5. **Calling `joinSession` from `viewDidAppear`.** Re-runs on every navigation push. Use `viewDidLoad` + a `joined` flag, OR use `UIViewRepresentable` + Coordinator (the sample's pattern).
+6. **`AVAudioSession.setCategory(.playback)`.** Mic input doesn't capture. Use `.playAndRecord` + `.voiceChat` mode.
+7. **`async/await` on `joinSession`.** It returns void with 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
+
+- [ ] `joinSession(sessionID:callSetting:container:)` used (single-call), NOT `generateToken` + `joinSession(callToken:)` two-step
+- [ ] Settings built via `SessionSettingsBuilder()`, not `SessionSettings(sessionType:layout:)`
+- [ ] `SessionStatusListener` protocol implemented on a Coordinator class
+- [ ] Coordinator registered via `CallSession.shared.addSessionStatusListener(...)` AFTER `onSuccess`
+- [ ] `onSessionLeft`, `onConnectionClosed`, `onSessionTimedOut` ALL 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 — `~/Downloads/calls-sdk/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