@cometchat/skills 4.4.2 → 5.0.1

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

@@ -1,359 +0,0 @@
-# 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 : .audio   // CallType has no .voice
-  let call = Call(receiverId: group.guid, callType: callType, receiverType: .group)
-
-  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+.
-
----
-
-## Participant-roster observation
-
-> **The iOS Calls SDK v5 has NO active-speaker callback.** `CallsEventsDelegate` exposes no `onActiveSpeakerUpdated` (and no `onUserListUpdated`). If you want an active-speaker spotlight on iOS, the SDK won't drive it — use the SDK's built-in spotlight mode instead (set via `CallSettingsBuilder.setMode(.spotlight)` — the typed `DisplayModes` enum, swiftinterface:175/281), which the SDK lays out internally.
-
-For a custom roster, observe the participant callbacks that DO exist — use the TYPED forms `onUserJoined(rtcUser:)`, `onUserLeft(rtcUser:)`, `onUserListChanged(rtcUsers:)` (swiftinterface:35,38,41). They deliver `RTCUser` objects (swiftinterface:139 — `uid`, `avatar`, `name`, `jwt`, `resource`), so read typed properties instead of parsing dictionaries. The `NSDictionary`/`NSArray` forms are DEPRECATED.
-
-```swift
-import CometChatCallsSDK
-
-final class CallStateObserver: NSObject, ObservableObject, CallsEventsDelegate {
-  @Published var participants: [RTCUser] = []
-
-  // swiftinterface:41 onUserListChanged(rtcUsers: [RTCUser])
-  func onUserListChanged(rtcUsers: [RTCUser]) {
-    DispatchQueue.main.async {
-      self.participants = rtcUsers
-    }
-  }
-}
-```
-
-Wire it via `CallSettingsBuilder.setDelegate(self)` or `CometChatCalls.addCallEventListener(observerId:delegate:)`.
-
-`@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 — not in the Calls SDK
-
-> **There are NO in-call moderator APIs on the iOS Calls SDK v5.** `CometChatCalls` has no `muteUser(uid:)` and no `removeUser(uid:)` (verified against the `CometChatCallsSDK` swiftinterface). Do not scaffold these — they won't compile.
-
-If you need remote mute / kick semantics, route them through the **Chat SDK group APIs** (e.g. `CometChat.kickGroupMember` / `banGroupMember`) or the **REST API** for group membership, and treat "muted" as app-level state you broadcast over a custom/transient message and apply locally. The Calls SDK is not involved in moderation.
-
----
-
-## Capacity error handling
-
-`CallsEventsDelegate` has NO `onError` callback. Capacity / membership errors surface from the `onError` closures of `generateToken` and `startSession` as a `CometChatCallException` — handle them there:
-
-```swift
-final class GroupCallViewController: UIViewController {
-  func handleStartError(_ error: CometChatCallException?) {
-    DispatchQueue.main.async { [weak self] in
-      switch error?.errorCode {
-      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?.errorDescription ?? "Unknown error")
-      }
-    }
-  }
-  // Pass handleStartError to the onError of generateToken / startSession.
-
-  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 {
-    CometChatCalls.videoPaused(true)   // NOT pauseVideo; synchronous
-    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

package/skills/cometchat-ios-calls/references/idle-timeout.md

@@ -1,184 +0,0 @@
-# Idle timeout on iOS
-
-The iOS Calls SDK v5 has a real idle-timeout API. Set it on the builder with `setIdleTimeoutPeriod(_ value: Int) -> Self` (swiftinterface:289), and react to the timeout via the optional `CallsEventsDelegate.onSessionTimeout()` callback (swiftinterface:30). The SDK runs the timer; you do NOT hand-roll a client-side `Timer`. (If you want an "are you still there?" prompt BEFORE the SDK ends the session, you can still drive a softer client-side warning off participant events — but the timeout itself is the SDK's job.)
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/ios/idle-timeout
-**Read first:** `cometchat-react-calls/references/idle-timeout.md` — settings + archetype timeouts + Pattern A custom timer.
-
----
-
-## SDK idle timeout — `setIdleTimeoutPeriod` + `onSessionTimeout`
-
-Set the timeout (in seconds) on the builder, then react to the SDK's `onSessionTimeout()` callback. When it fires, report the end to CallKit and the SDK has already torn the session down:
-
-```swift
-import CometChatCallsSDK
-
-let settings = CallSettingsBuilder()
-  .setIdleTimeoutPeriod(120)        // swiftinterface:289 setIdleTimeoutPeriod(_ value: Int) -> Self
-  .setDelegate(callListener)
-  .build()
-// ... generateToken → startSession(callToken:callSetting:view:) ...
-
-class CallListener: NSObject, CallsEventsDelegate {
-  // swiftinterface:30 — optional CallsEventsDelegate.onSessionTimeout()
-  func onSessionTimeout() {
-    DispatchQueue.main.async {
-      // Report end to CallKit (rule 1.5 — hangup cleanup); SDK already ended the session.
-      CallManager.shared.endCall(reason: .remoteEnded)
-    }
-  }
-}
-```
-
-The `CallManager.shared.endCall(reason:)` call is critical — see `references/callkit-and-pushkit.md`. CallKit's call card persists on the lock screen unless you report the end.
-
----
-
-## CallKit interaction — endCall reason
-
-When your client-side timer fires, you must report the call end to CallKit. The reason matters for system UI:
-
-```swift
-let endReason: CXCallEndedReason = .remoteEnded
-// Other options:
-//   .failed           — error / network issue
-//   .remoteEnded      — counterparty hung up
-//   .unanswered       — incoming call not answered
-//   .answeredElsewhere — answered on another device
-//   .declinedElsewhere — declined on another device
-
-provider.reportCall(
-  with: callUUID,
-  endedAt: Date(),
-  reason: endReason,
-)
-```
-
-Use `.remoteEnded` for idle timeout — it's the closest semantic match (the "remote" effectively ended the call by leaving). Don't use `.failed` (implies error; iOS shows a "call failed" UI).
-
-Drive the reporting from your own timer's completion handler — there is no SDK callback to hang this off.
-
----
-
-## Foreground/background gotcha
-
-iOS suspends background JavaScript / WebRTC threads aggressively. If the user backgrounds the app, the call session may pause. The idle timer continues running in the SDK's tracking, but participant-leave events may queue until foreground.
-
-Practical implication: idle timeout fires immediately on app return, even if the user only backgrounded for a few seconds. Same as RN.
-
-If using CallKit (rule 1.7 in SKILL.md), the background-mode `voip` capability keeps the call alive — but participant tracking may still lag. Test the foreground transition.
-
----
-
-## Custom prompt — SwiftUI
-
-```swift
-struct IdleTimeoutPrompt: View {
-  let onStay: () -> Void
-  let onEnd: () -> Void
-
-  var body: some View {
-    VStack(spacing: 16) {
-      Text("Still there?")
-        .font(.headline)
-      Text("You're alone in this call. It'll end in 60 seconds.")
-        .multilineTextAlignment(.center)
-        .foregroundColor(.secondary)
-      HStack(spacing: 12) {
-        Button("End now", role: .destructive, action: onEnd)
-          .buttonStyle(.bordered)
-        Button("Stay", action: onStay)
-          .buttonStyle(.borderedProminent)
-      }
-    }
-    .padding(24)
-    .background(.regularMaterial, in: RoundedRectangle(cornerRadius: 16))
-    .accessibilityElement(children: .contain)
-    .accessibilityAddTraits(.isModal)
-  }
-}
-```
-
-Used as an overlay:
-
-```swift
-struct CallView: View {
-  @State private var showIdlePrompt = false
-
-  var body: some View {
-    ZStack {
-      // Call surface
-      if showIdlePrompt {
-        Color.black.opacity(0.5)
-          .ignoresSafeArea()
-          .onTapGesture { /* prevent dismiss on backdrop */ }
-        IdleTimeoutPrompt(
-          onStay: { showIdlePrompt = false; resetIdleTimer() },
-          onEnd: { CometChatCalls.endSession() },
-        )
-      }
-    }
-  }
-}
-```
-
-`accessibilityAddTraits(.isModal)` is the SwiftUI equivalent of web's `aria-modal="true"`. VoiceOver focus stays trapped within the prompt.
-
----
-
-## UIKit pattern — UIAlertController
-
-For UIKit projects, the simplest path is `UIAlertController`:
-
-```swift
-let alert = UIAlertController(
-  title: "Still there?",
-  message: "You're alone in this call. It'll end in 60 seconds.",
-  preferredStyle: .alert,
-)
-alert.addAction(UIAlertAction(title: "Stay", style: .default) { _ in
-  resetIdleTimer()
-})
-alert.addAction(UIAlertAction(title: "End now", style: .destructive) { _ in
-  CometChatCalls.endSession()
-})
-alert.preferredAction = alert.actions.first  // make Stay the default
-present(alert, animated: true)
-```
-
-`alert.preferredAction` makes "Stay" the default highlighted action — VoiceOver activates it on triple-click home button as the default response.
-
----
-
-## Anti-patterns
-
-Web sister reference rules apply, plus iOS-specific:
-
-1. **Hand-rolling a `Timer` for the timeout itself.** The SDK has `setIdleTimeoutPeriod(_:)` (swiftinterface:289) + `onSessionTimeout()` (swiftinterface:30) — use them. Only a soft "still there?" warning prompt should be client-side.
-2. **`onSessionTimeout` firing without reporting end to CallKit.** Lock-screen call card persists — user sees a stuck "ongoing call" until they manually end it.
-3. **Using `.failed` reason for idle timeout end.** iOS shows "call failed" — wrong semantic. Use `.remoteEnded`.
-4. **Custom prompt that doesn't dim background.** Calls UI keeps rendering behind the prompt; user can interact with controls and call ends prematurely.
-5. **`UIAlertController` from background queue.** Crashes — must be on main. Wrap in `DispatchQueue.main.async`.
-
----
-
-## Verification checklist
-
-- [ ] Timeout set via `CallSettingsBuilder.setIdleTimeoutPeriod(_:)` (seconds) — no hand-rolled `Timer` for the timeout
-- [ ] `onSessionTimeout()` delegate callback reports end to CallKit with `.remoteEnded` reason
-- [ ] Custom prompt uses `accessibilityAddTraits(.isModal)` (SwiftUI) or `UIAlertController.preferredStyle = .alert`
-- [ ] Backdrop dimmed; prevents accidental dismiss
-- [ ] All UIKit alert presentations on main thread
-- [ ] Real-device smoke: 2 iPhones in call, hangup from one → other shows prompt after configured delay
-- [ ] Lock-screen smoke: when call times out, lock-screen card disappears (CallKit reported)
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/idle-timeout.md` — sister reference (settings, archetype timeouts)
-- `cometchat-ios-calls` SKILL.md
-- `references/callkit-and-pushkit.md` — CallKit reporting end
-- `references/swiftui-uikit-hosting.md` — embedding SwiftUI prompts in UIKit nav
-- Canonical docs: https://www.cometchat.com/docs/calls/ios/idle-timeout