@cometchat/skills 4.0.0 → 4.2.0

package/skills/cometchat-ios-calls/references/device-management.md

@@ -0,0 +1,171 @@
+# Device management on iOS
+
+iOS handles audio routing at the system level via `AVAudioSession.sharedInstance().availableInputs`. The Calls SDK exposes camera switching (`switchCamera`) but defers audio device selection to the OS — the user picks via the system's audio route picker (`AVRoutePickerView`) or Control Center.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/ios/device-management
+**Read first:** `references/avaudiosession-routing.md` — AVAudioSession setup + Bluetooth/AirPods routing rules.
+
+---
+
+## Camera switching (front / back / external)
+
+```swift
+import CometChatCallsSDK
+
+CometChatCalls.switchCamera()
+```
+
+That's the SDK's primary camera control — toggles front/back. For iPad with attached external cameras (Studio Display, Continuity Camera), the user picks via the system Camera control center.
+
+---
+
+## Audio inputs (mic / Bluetooth / AirPods)
+
+System-driven via `AVAudioSession`. The user picks from Control Center → Audio destination, or via your in-app `AVRoutePickerView`:
+
+```swift
+import AVKit
+
+class CallControlsView: UIView {
+  private let routePicker = AVRoutePickerView()
+
+  init() {
+    super.init(frame: .zero)
+    routePicker.translatesAutoresizingMaskIntoConstraints = false
+    routePicker.activeTintColor = .systemBlue
+    addSubview(routePicker)
+    NSLayoutConstraint.activate([
+      routePicker.widthAnchor.constraint(equalToConstant: 44),
+      routePicker.heightAnchor.constraint(equalToConstant: 44),
+    ])
+  }
+  required init?(coder: NSCoder) { fatalError() }
+}
+```
+
+`AVRoutePickerView` is the canonical iOS audio-route picker. Tapping shows the system sheet with all available outputs (Built-in Speaker, AirPods, CarPlay, Bluetooth speakers, etc.). System-styled; matches user expectations.
+
+---
+
+## Speakerphone toggle
+
+Most calls want a quick speaker on/off without going through the route picker:
+
+```swift
+import AVFoundation
+
+func toggleSpeaker(on: Bool) {
+  do {
+    let session = AVAudioSession.sharedInstance()
+    if on {
+      try session.overrideOutputAudioPort(.speaker)
+    } else {
+      try session.overrideOutputAudioPort(.none)   // restore default routing
+    }
+  } catch {
+    print("Failed to switch speaker: \(error)")
+  }
+}
+```
+
+`.none` means "use the system default for current category" (typically receiver/earpiece for `playAndRecord` + `voiceChat`). NOT "no audio."
+
+---
+
+## SwiftUI integration
+
+```swift
+struct CallControls: View {
+  @State private var speakerOn = false
+
+  var body: some View {
+    HStack(spacing: 16) {
+      // Speaker toggle
+      Button(action: {
+        speakerOn.toggle()
+        toggleSpeaker(on: speakerOn)
+      }) {
+        Image(systemName: speakerOn ? "speaker.wave.3.fill" : "speaker.fill")
+      }
+
+      // Camera flip
+      Button(action: { CometChatCalls.switchCamera() }) {
+        Image(systemName: "camera.rotate")
+      }
+
+      // System route picker (Bluetooth / AirPods)
+      AVRoutePickerViewWrapper()
+        .frame(width: 44, height: 44)
+    }
+  }
+}
+
+struct AVRoutePickerViewWrapper: UIViewRepresentable {
+  func makeUIView(context: Context) -> AVRoutePickerView {
+    let view = AVRoutePickerView()
+    view.activeTintColor = .systemBlue
+    return view
+  }
+  func updateUIView(_ view: AVRoutePickerView, context: Context) {}
+}
+```
+
+---
+
+## Listen for route changes
+
+```swift
+NotificationCenter.default.addObserver(
+  forName: AVAudioSession.routeChangeNotification,
+  object: AVAudioSession.sharedInstance(),
+  queue: .main
+) { notification in
+  guard let userInfo = notification.userInfo,
+        let reasonValue = userInfo[AVAudioSessionRouteChangeReasonKey] as? UInt,
+        let reason = AVAudioSession.RouteChangeReason(rawValue: reasonValue) else { return }
+
+  switch reason {
+  case .newDeviceAvailable:
+    // AirPods connected, headphones plugged
+    print("New audio device available")
+  case .oldDeviceUnavailable:
+    // Headphones unplugged
+    print("Audio device unavailable")
+  default:
+    break
+  }
+}
+```
+
+The two reason codes that matter for UI: `.newDeviceAvailable` (show "AirPods connected" toast) and `.oldDeviceUnavailable` (audio routes back to speaker; might want to update UI button state).
+
+---
+
+## Anti-patterns
+
+1. **Building a custom audio route picker** instead of using `AVRoutePickerView`. iOS users expect the system picker; custom feels off-brand.
+2. **Setting `overrideOutputAudioPort(.speaker)` from background.** AVAudioSession changes only work when session is active. Wrap in `setActive(true)` first.
+3. **Forgetting to listen for `routeChangeNotification`.** UI gets out of sync when user changes route via Control Center.
+4. **Calling `setActive(true)` repeatedly during a call.** AVAudioSession is sticky once activated; redundant calls produce warnings in console.
+5. **Not handling `.failed` errors from `overrideOutputAudioPort`.** Some Bluetooth devices reject the override; silently swallow OR show a toast.
+
+---
+
+## Verification checklist
+
+- [ ] `AVRoutePickerView` rendered in call controls
+- [ ] Speaker toggle uses `overrideOutputAudioPort` correctly
+- [ ] `.routeChangeNotification` observer set up
+- [ ] All AVAudioSession calls on main queue
+- [ ] Real-device smoke: AirPods connect mid-call → toast shown, audio routes
+- [ ] Real-device smoke: Speaker toggle works
+- [ ] Real-device smoke: Camera flip works (front/back)
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/device-management.md` — web sister reference (different mechanism but UX shape)
+- `cometchat-ios-calls` SKILL.md — the seven hard rules
+- `references/avaudiosession-routing.md` — AVAudioSession setup details
+- Canonical docs: https://www.cometchat.com/docs/calls/ios/device-management

package/skills/cometchat-ios-calls/references/group-calls.md

@@ -0,0 +1,396 @@
+# Group calls (meetings) on iOS
+
+iOS group calls combine the `CometChatCallsSDK` group APIs with iOS-platform patterns: `UICollectionView` for scalable rosters, KVO/Combine for active-speaker observation, CallKit for OS-level multi-party reporting. For SDK-level semantics (capacity, bandwidth, moderator actions) read `cometchat-native-calls/references/group-calls.md` first — same SDK, identical contracts.
+
+---
+
+## Signaling architecture — meeting-message broadcast, NOT call ringing
+
+**Critical to read first.** Group calls do NOT use the Ringing channel (`CometChat.initiateCall` → `onIncomingCallReceived`). That channel is **1:1 user calls only**. The kit broadcasts a **custom message of type `"meeting"`** to the group; receivers see a "Join meeting" card in their `CometChatMessageList` (kit) or need an explicit `MessageListener.onCustomMessageReceived` (custom UI).
+
+This applies identically on iOS as on web/RN/Android/Flutter — the same Chat SDK semantic is in play. The kit's `CometChatUI` group surface auto-renders meeting cards; custom Swift/SwiftUI call surfaces need the explicit listener.
+
+```swift
+import CometChatSDK
+
+let listener = MessageListener()
+listener.onCustomMessageReceived = { customMessage in
+    guard customMessage.category == .custom else { return }
+    guard customMessage.type == "meeting" else { return }
+
+    let customData = customMessage.customData as? [String: Any] ?? [:]
+    let sessionID = (customData["sessionId"] as? String) ?? customMessage.receiverUid
+    let callTypeRaw = (customData["callType"] as? String) ?? "video"
+    let callType: CallType = callTypeRaw == "audio" ? .audio : .video
+    let fromUid = customMessage.sender.uid
+    let groupGuid = customMessage.receiverUid
+
+    DispatchQueue.main.async {
+        // Present your custom "incoming meeting" UI:
+        // - banner / toast with "Join" CTA
+        // - or full-screen incoming-meeting view controller
+        // Tapping Join → navigate to OngoingCallViewController(sessionID:)
+    }
+}
+CometChat.addMessageListener("APP_ROOT_GROUP_MEETING_LISTENER", listener)
+```
+
+| Channel | 1:1 user calls | Group calls |
+|---|---|---|
+| Signaling API (caller) | `CometChat.initiateCall(call:)` | `CometChat.sendCustomMessage(customMessage:)` with type="meeting" |
+| Receiver event | `CallListener.onIncomingCallReceived` | `MessageListener.onCustomMessageReceived` (category=.custom + type="meeting") |
+| Session ID | server-generated unique per call | group's GUID (persistent) |
+| CallKit ring | yes — report via `CXProvider.reportNewIncomingCall` | no — meeting message lands in chat; manual CallKit interception only |
+| Auto-cancel timeout | yes (45s default) | no — meeting persists in chat history |
+
+### CallKit and group calls
+
+Because group meeting events come through the message channel (not the call channel), CallKit does NOT auto-ring for incoming group meetings the way it does for 1:1 calls. If you want CallKit-style ringing for groups, you must:
+
+1. Configure your push provider to deliver the meeting message as a VoIP push (PushKit), not a regular APNs push.
+2. Intercept the VoIP push in `PKPushRegistryDelegate`, parse the meeting payload, and call `CXProvider.reportNewIncomingCall(...)` with a synthesized `CallKit` UUID and metadata.
+
+The CometChat dashboard's PushKit provider doesn't auto-route meeting messages to VoIP push by default — you'd need a server-side webhook that re-routes meeting messages. Not built-in.
+
+---
+
+## Initiating a group call
+
+```swift
+import CometChatSDK
+
+func initiateGroupCall(guid: String, isVideo: Bool) async throws -> Call {
+  let group = try await fetchGroup(guid)
+  let callType: CallType = isVideo ? .video : .voice
+  let call = Call(receiverUid: group.guid, receiverType: .group, callType: callType)
+
+  return try await withCheckedThrowingContinuation { cont in
+    CometChat.initiateCall(call: call,
+      onSuccess: { initiated in cont.resume(returning: initiated) },
+      onError: { error in cont.resume(throwing: error) })
+  }
+}
+```
+
+Receiver type is `.group` — anyone in the group can `acceptCall` until the call ends.
+
+---
+
+## Roster as `UICollectionView`
+
+Multi-party rosters scale poorly with `UIStackView`. Use `UICollectionView` with a `UICollectionViewDiffableDataSource` for smooth roster updates:
+
+```swift
+import UIKit
+import CometChatCallsSDK
+
+final class ParticipantRosterController: NSObject, UICollectionViewDelegateFlowLayout {
+  enum Section { case main }
+  typealias DataSource = UICollectionViewDiffableDataSource<Section, Participant>
+  typealias Snapshot = NSDiffableDataSourceSnapshot<Section, Participant>
+
+  private let collectionView: UICollectionView
+  private lazy var dataSource = makeDataSource()
+  private var participants: [Participant] = []
+
+  init(collectionView: UICollectionView) {
+    self.collectionView = collectionView
+    super.init()
+    collectionView.delegate = self
+  }
+
+  func update(participants: [Participant]) {
+    self.participants = participants
+    var snapshot = Snapshot()
+    snapshot.appendSections([.main])
+    snapshot.appendItems(participants)
+    dataSource.apply(snapshot, animatingDifferences: true)
+  }
+
+  private func makeDataSource() -> DataSource {
+    let registration = UICollectionView.CellRegistration<ParticipantCell, Participant> { cell, _, p in
+      cell.configure(with: p)
+    }
+    return DataSource(collectionView: collectionView) { cv, indexPath, p in
+      cv.dequeueConfiguredReusableCell(using: registration, for: indexPath, item: p)
+    }
+  }
+}
+```
+
+Diffable data source means roster updates animate cleanly without cell-recreation thrashing. Rule of thumb: 25-participant rosters render at 60fps on iPhone 12+.
+
+---
+
+## Active-speaker observation
+
+`CometChatCallsSDK` exposes the active-speaker callback via `CometChatCallsEventsListener`. Wrap it for SwiftUI/Combine:
+
+```swift
+final class CallStateObserver: ObservableObject {
+  @Published var activeSpeakerUid: String?
+  @Published var participants: [Participant] = []
+
+  private var debounceTimer: Timer?
+
+  func onActiveSpeakerUpdated(_ uid: String) {
+    debounceTimer?.invalidate()
+    debounceTimer = Timer.scheduledTimer(withTimeInterval: 0.5, repeats: false) { [weak self] _ in
+      DispatchQueue.main.async {
+        self?.activeSpeakerUid = uid
+      }
+    }
+  }
+
+  func onUserListUpdated(_ users: [Participant]) {
+    DispatchQueue.main.async {
+      self.participants = users
+    }
+  }
+}
+```
+
+500ms debounce — same rule as RN/Angular. Without it, the spotlight tile jitters.
+
+`@Published` works in both SwiftUI (via `@StateObject`) and UIKit (via Combine subscriptions). Pick one path; don't mix.
+
+---
+
+## SwiftUI spotlight layout
+
+```swift
+struct GroupCallView: View {
+  @StateObject private var state = CallStateObserver()
+
+  var body: some View {
+    VStack(spacing: 8) {
+      if let speaker = activeSpeaker {
+        ParticipantTile(participant: speaker)
+          .frame(maxWidth: .infinity, maxHeight: .infinity)
+      }
+
+      ScrollView(.horizontal, showsIndicators: false) {
+        HStack(spacing: 8) {
+          ForEach(others) { p in
+            ParticipantTile(participant: p)
+              .frame(width: 100, height: 130)
+          }
+        }
+        .padding(.horizontal)
+      }
+      .frame(height: 140)
+    }
+  }
+
+  private var activeSpeaker: Participant? {
+    if let uid = state.activeSpeakerUid {
+      return state.participants.first { $0.uid == uid }
+    }
+    return state.participants.first
+  }
+
+  private var others: [Participant] {
+    let speaker = activeSpeaker
+    return state.participants.filter { $0.uid != speaker?.uid && $0.uid != localUid }
+  }
+
+  private var localUid: String { CometChat.getLoggedInUser()?.uid ?? "" }
+}
+```
+
+The `Identifiable` conformance on `Participant` (with `id = uid`) is what makes `ForEach` reuse cells across roster updates. Without it, every update destroys + recreates every tile — same bug as RN/Angular.
+
+---
+
+## Moderator actions — UIKit Action Sheet
+
+```swift
+extension GroupCallViewController {
+  @objc func participantTapped(_ sender: UITapGestureRecognizer) {
+    guard let cell = sender.view as? ParticipantCell,
+          let participant = cell.participant else { return }
+    guard canModerate else { return }                    // gate
+
+    let alert = UIAlertController(title: participant.name, message: nil, preferredStyle: .actionSheet)
+    alert.addAction(UIAlertAction(title: "Mute", style: .default) { _ in
+      Task { try? await CometChatCalls.muteUser(uid: participant.uid) }
+    })
+    alert.addAction(UIAlertAction(title: "Remove from call", style: .destructive) { _ in
+      Task { try? await CometChatCalls.removeUser(uid: participant.uid) }
+    })
+    alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
+
+    if let popover = alert.popoverPresentationController {
+      popover.sourceView = cell
+      popover.sourceRect = cell.bounds
+    }
+    present(alert, animated: true)
+  }
+
+  private var canModerate: Bool {
+    return group?.scope == "admin" || group?.scope == "moderator"
+  }
+}
+```
+
+`popoverPresentationController` is required on iPad — without it, action sheets crash on iPad.
+
+---
+
+## Capacity error handling
+
+```swift
+final class GroupCallViewController: UIViewController {
+  func setupCallListener() {
+    let listener = CometChatCallsEventsListener()
+    listener.onError = { [weak self] error in
+      DispatchQueue.main.async {
+        switch error.code {
+        case "ERR_CALL_FULL":
+          self?.showAlert(title: "Call is full",
+                          message: "This meeting has reached its participant limit.")
+        case "ERR_NOT_GROUP_MEMBER":
+          self?.showAlert(title: "Not a member",
+                          message: "You're not a member of this group.")
+        default:
+          self?.showAlert(title: "Call error", message: error.message)
+        }
+      }
+    }
+    // ...
+  }
+
+  private func showAlert(title: String, message: String) {
+    let alert = UIAlertController(title: title, message: message, preferredStyle: .alert)
+    alert.addAction(UIAlertAction(title: "OK", style: .default))
+    present(alert, animated: true)
+  }
+}
+```
+
+`DispatchQueue.main.async` wraps the UI update — listener fires on a background queue.
+
+---
+
+## CallKit and group calls
+
+CallKit was designed for 1:1 — its `CXCallUpdate` model has a single `remoteHandle`. Group calls don't fit cleanly. Two practical patterns:
+
+### A — Report group calls as a single "meeting" call
+
+```swift
+let update = CXCallUpdate()
+update.remoteHandle = CXHandle(type: .generic, value: group.guid)
+update.localizedCallerName = "Meeting: \(group.name)"
+update.hasVideo = isVideo
+update.supportsHolding = false
+update.supportsGrouping = false       // CallKit "group" means call merging, not multi-party
+update.supportsUngrouping = false
+provider.reportNewIncomingCall(with: callUUID, update: update) { _ in }
+```
+
+The user sees "Incoming meeting call from <Group Name>" in CallKit's lock-screen UI. No participant detail — that's in your app's UI after they accept.
+
+### B — Skip CallKit for group calls
+
+Some apps treat group calls as a foreground-only experience and skip CallKit reporting entirely. Trade-off: no lock-screen ring → users miss meeting invitations. Only viable if your audience is reliably foregrounded (corporate apps with predictable usage).
+
+The skill defaults to pattern A.
+
+---
+
+## Battery + low-power mode
+
+iOS broadcasts `NSProcessInfoPowerStateDidChangeNotification` when the user enables Low Power Mode. Auto-downgrade video:
+
+```swift
+NotificationCenter.default.addObserver(
+  self,
+  selector: #selector(powerStateChanged),
+  name: NSNotification.Name.NSProcessInfoPowerStateDidChange,
+  object: nil)
+
+@objc func powerStateChanged() {
+  if ProcessInfo.processInfo.isLowPowerModeEnabled && callActive {
+    Task {
+      await CometChatCalls.pauseVideo(true)
+      DispatchQueue.main.async {
+        self.showBanner("Video paused — Low Power Mode")
+      }
+    }
+  }
+}
+```
+
+Same pattern for `UIDevice.current.batteryLevel` (`isBatteryMonitoringEnabled = true` first), but Low Power Mode is the more reliable signal.
+
+---
+
+## Joining an in-progress call
+
+```swift
+func checkActiveGroupCall(guid: String) async -> Call? {
+  guard let active = try? await fetchActiveCall() else { return nil }
+  guard active.receiverType == .group, active.receiverUid == guid else { return nil }
+  return active
+}
+```
+
+Render a "Join meeting" button on the group screen if there's an active call:
+
+```swift
+struct GroupDetailView: View {
+  @State private var activeCall: Call?
+
+  var body: some View {
+    VStack {
+      if let call = activeCall {
+        Button("Join meeting") {
+          Task { await join(call: call) }
+        }
+        .buttonStyle(.borderedProminent)
+      }
+      // ... rest of group detail
+    }
+    .task {
+      activeCall = await checkActiveGroupCall(guid: group.guid)
+    }
+  }
+}
+```
+
+---
+
+## Anti-patterns
+
+1. **Roster updates without `Identifiable` (or `IndexPath` reuse identifier)**. Cells thrash on every update; video tracks die with them.
+2. **No active-speaker debounce.** Spotlight tile jitters at 5+ Hz.
+3. **`UIAlertController` action sheet on iPad without `popoverPresentationController`.** Crash.
+4. **Moderator buttons rendered without scope check.** Backend rejects but UI is misleading.
+5. **No `DispatchQueue.main.async` wrapping** SDK callbacks. UI updates skipped.
+6. **Skipping CallKit for group calls without a lock-screen ring fallback.** Missed meetings.
+7. **CallKit `supportsGrouping = true`.** That's CallKit's call-merging feature; doesn't mean multi-party. Set to false.
+
+---
+
+## Verification checklist
+
+- [ ] `Participant` conforms to `Identifiable` with `id = uid`
+- [ ] `UICollectionViewDiffableDataSource` for UIKit OR `ForEach` with stable IDs for SwiftUI
+- [ ] Active-speaker debounced ≥500ms via Timer or Combine `.debounce`
+- [ ] All SDK callbacks dispatched to `DispatchQueue.main.async`
+- [ ] Moderator buttons gated on `group.scope == "admin" || == "moderator"`
+- [ ] iPad action sheets configure `popoverPresentationController`
+- [ ] `ERR_CALL_FULL` and `ERR_NOT_GROUP_MEMBER` produce user-facing alerts
+- [ ] Low Power Mode observer auto-pauses video
+- [ ] CallKit pattern: meeting reported as `localizedCallerName: "Meeting: <Group Name>"` (or skipped intentionally)
+- [ ] Active-call check on group screen entry; "Join meeting" button rendered when active
+
+---
+
+## Pointers
+
+- `cometchat-native-calls/references/group-calls.md` — sister reference (SDK semantics, capacity, bandwidth scaling)
+- `references/callkit-and-pushkit.md` — CallKit reporting pattern; group-call adaptation above
+- `references/custom-ui.md` — UICollectionView roster integration with WebRTC views
+- `cometchat-ios-calls` SKILL.md — base hard rules