@cometchat/skills 4.4.1 → 5.0.0

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

package/skills/cometchat-ios-calls/references/in-call-chat.md

@@ -1,179 +0,0 @@
-# In-call chat on iOS
-
-> **The iOS Calls SDK v5 has NO in-call chat button.** There is no `setHideChatButton` on `CallSettingsBuilder`, no `onChatButtonClicked` callback on `CallsEventsDelegate`, and no `CometChatCalls.setChatButtonUnreadCount(_:)`. None of these symbols exist — do not emit them.
-
-In-call chat is therefore an **app-level composition**, not an SDK feature: you add your OWN chat button to your call UI, and present a sheet hosting the kit's `CometChatMessageList` + `CometChatMessageComposer` over a group keyed to the call's session ID. The Calls SDK is not involved.
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/ios/in-call-chat
-**Read first:** `cometchat-react-calls/references/in-call-chat.md` — group-as-session architecture + anti-patterns.
-
----
-
-## Your own chat button (the SDK provides none)
-
-Add a button to your call control panel and present the sheet yourself. Track unread count in your own state (from a `CometChat.addMessageListener` on the session group) — there is no SDK badge API.
-
-```swift
-import CometChatSDK
-
-// In your call UIViewController:
-let chatButton = UIButton(type: .system)
-chatButton.addAction(UIAction { [weak self] _ in
-  self?.presentChatSheet()        // present on main; you're already on main here
-}, for: .touchUpInside)
-
-// Unread badge: maintain your own count from a message listener on the session group,
-// and update chatButton's badge view. There is no CometChatCalls.setChatButtonUnreadCount.
-```
-
----
-
-## Sheet presentation (iOS 15+)
-
-```swift
-import UIKit
-
-class CallViewController: UIViewController {
-  func presentChatSheet() {
-    let chatVC = InCallChatViewController(sessionId: sessionId)
-    let nav = UINavigationController(rootViewController: chatVC)
-
-    if #available(iOS 15.0, *) {
-      if let sheet = nav.sheetPresentationController {
-        sheet.detents = [.medium(), .large()]
-        sheet.prefersGrabberVisible = true
-        sheet.preferredCornerRadius = 16
-      }
-    }
-
-    present(nav, animated: true)
-  }
-}
-```
-
-`.detents = [.medium(), .large()]` is iOS 15+'s pull-up sheet API. Matches the BottomSheet UX from RN/Flutter.
-
----
-
-## InCallChatViewController
-
-```swift
-class InCallChatViewController: UIViewController {
-  let sessionId: String
-  private var group: Group?
-  private var listenerId: String!
-
-  init(sessionId: String) {
-    self.sessionId = sessionId
-    super.init(nibName: nil, bundle: nil)
-    self.title = "Chat"
-  }
-  required init?(coder: NSCoder) { fatalError() }
-
-  override func viewDidLoad() {
-    super.viewDidLoad()
-    listenerId = "in-call-chat-\(sessionId)"
-
-    Task {
-      do {
-        group = try await ensureGroup(sessionId: sessionId)
-        try await joinGroup(sessionId: sessionId)
-        await MainActor.run {
-          self.embedMessageList()
-        }
-      } catch {
-        print("Failed to set up in-call chat:", error)
-      }
-    }
-  }
-
-  override func viewWillDisappear(_ animated: Bool) {
-    super.viewWillDisappear(animated)
-    // Clear YOUR unread count on close (no SDK badge API exists).
-    NotificationCenter.default.post(name: .inCallChatClosed, object: nil)
-  }
-
-  private func embedMessageList() {
-    guard let group = group else { return }
-    // The kit's CometChatMessageList is a UIViewController
-    let messageList = CometChatMessageList()
-    messageList.group = group
-    addChild(messageList)
-    view.addSubview(messageList.view)
-    // ... AutoLayout pinning to fill view
-    messageList.didMove(toParent: self)
-
-    // Composer
-    let composer = CometChatMessageComposer()
-    composer.group = group
-    addChild(composer)
-    view.addSubview(composer.view)
-    // ... AutoLayout pinning to bottom
-    composer.didMove(toParent: self)
-  }
-}
-
-func ensureGroup(sessionId: String) async throws -> Group {
-  do {
-    return try await fetchGroup(sessionId)   // CometChat.getGroup wrapper
-  } catch {
-    let group = Group(guid: sessionId, name: "Call \(sessionId)", groupType: .public, password: "")
-    return try await createGroup(group)
-  }
-}
-```
-
----
-
-## Audio ducking when keyboard opens
-
-iOS auto-ducks call audio when the system keyboard opens (the kit handles this). For custom UI you may want to maintain unducked audio for the whole call — explicit override:
-
-```swift
-NotificationCenter.default.addObserver(
-  forName: UIResponder.keyboardWillShowNotification,
-  object: nil, queue: .main
-) { _ in
-  // Re-assert non-ducking audio category
-  try? AVAudioSession.sharedInstance().setCategory(
-    .playAndRecord,
-    mode: .voiceChat,
-    options: [.allowBluetooth, .defaultToSpeaker]
-  )
-}
-```
-
-Most apps don't need this; the kit's defaults are sensible. Override only if user testing surfaces the audio ducking as confusing.
-
----
-
-## Anti-patterns
-
-Web sister rules apply, plus iOS-specific:
-
-1. **Wiring `setHideChatButton` / `onChatButtonClicked` / `setChatButtonUnreadCount`.** None exist on iOS v5. Present your own button + sheet; track unread in your own state.
-2. **`present(nav, animated: true)` from background queue.** Crash. Always main queue.
-3. **Mutating `group` from background.** `group` updates must be on main; `Task { @MainActor in ... }` or `DispatchQueue.main.async`.
-4. **Forgetting `dismiss(animated: true)` on call end.** Sheet stays up over the post-call screen — looks broken.
-
----
-
-## Verification checklist
-
-- [ ] Your OWN chat button presents the sheet (no `setHideChatButton`/`onChatButtonClicked`/`setChatButtonUnreadCount` — none exist)
-- [ ] Sheet presented on main queue
-- [ ] `UISheetPresentationController` with `[.medium(), .large()]` detents (iOS 15+)
-- [ ] `CometChatMessageList` + `CometChatMessageComposer` embedded as child VCs
-- [ ] Sheet dismissed on call end
-- [ ] Real-device smoke: 2 iPhones in call, send message → badge in other
-- [ ] Sheet drag-down dismisses cleanly
-- [ ] Lock-screen smoke: backgrounded → return → chat sheet still visible if open
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/in-call-chat.md` — sister web reference (group-as-session pattern)
-- `cometchat-ios-calls` SKILL.md — the seven hard rules
-- `references/swiftui-uikit-hosting.md` — embedding SwiftUI sheets
-- Canonical docs: https://www.cometchat.com/docs/calls/ios/in-call-chat

package/skills/cometchat-ios-calls/references/migration-v4-to-v5.md

@@ -1,196 +0,0 @@
-# CometChat Calls iOS SDK v4 → v5 migration
-
-`CometChatCallsSDK` v5 keeps the same session model as v4 — a per-session call token, a `CallSettingsBuilder`, and a static `CometChatCalls` facade. There is **no** `CometChatCalls.login`, **no** `CallSession`/`CallSession.shared`, and **no** `SessionSettings` struct. Auth is per-session via `generateToken`.
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/ios/migration-guide-v5
-
-> Every symbol below is verified against the v5 `CometChatCallsSDK` Swift interface. Do NOT introduce `CallSession`, `joinSession`, `SessionSettings`, `SessionSettingsBuilder`, `CometChatCallsEventsListener`, `muteAudio`/`pauseVideo`, `setLayout`, or `startScreenShare` — none of these exist in v5.
-
----
-
-## Step 1 — Bump the SDK
-
-**SwiftPM:** Update the `CometChatCallsSDK` package version pin to `5.0.0` or higher.
-
-**CocoaPods:**
-```ruby
-# Podfile
-pod 'CometChatCallsSDK', '~> 5.0'
-```
-
-```bash
-pod install --repo-update
-```
-
----
-
-## Step 2 — Init
-
-Init takes a `CallAppSettings` built with `CallAppSettingsBuilder`, passed under the `callsAppSettings:` label (note the `s` — `callsAppSettings`, not `callAppSettings`).
-
-```swift
-let callAppSettings = CallAppSettingsBuilder()
-  .setAppId("APP_ID")
-  .setRegion("REGION")
-  .build()
-
-CometChatCalls.init(callsAppSettings: callAppSettings, onSuccess: { _ in
-  // ready
-}, onError: { error in
-  // surface error
-})
-```
-
-There is no async/await `init(with:)` form and no `CallAppSettings.Builder()` nested type — use `CallAppSettingsBuilder()`.
-
----
-
-## Step 3 — Auth is per-session (no Calls SDK login)
-
-> **There is NO `CometChatCalls.login` and NO `CometChatCalls.getLoggedInUser` in v5.** Do not call them — they do not exist on the Calls SDK.
-
-Authentication is per call session. Get a call token immediately before starting a session:
-
-```swift
-// Chat SDK still owns the user session. Get its auth token from the Chat SDK:
-let authToken = CometChat.getUserAuthToken()   // CometChatSDK — User has NO `authToken` property
-
-CometChatCalls.generateToken(authToken: authToken, sessionID: sessionID, onSuccess: { token in
-  // `token` is the call token you pass to startSession
-}, onError: { error in
-  // surface error
-})
-```
-
-`generateToken` is `CometChatCalls.generateToken(authToken:sessionID:onSuccess:onError:)`.
-
----
-
-## Step 4 — Session settings (`CallSettingsBuilder`, not `SessionSettings`)
-
-> **There is NO `SessionSettings` struct and NO `SessionSettingsBuilder`.** Use `CallSettingsBuilder().build()` which returns `CallSettings`.
-
-```swift
-let callSettings = CallSettingsBuilder()
-  .setIsAudioOnly(false)               // was setSessionType(.video) — there is no setSessionType
-  .setStartAudioMuted(false)
-  .setStartVideoMuted(false)
-  .setShowRecordingButton(true)        // NOT inverted — there is no hideRecordingButton
-  .setMode(.default)                   // setMode(_ value: DisplayModes) — swiftinterface:281 (.default/.single/.spotlight); NSString overload is deprecated
-  .setDelegate(self)                   // self conforms to CallsEventsDelegate
-  .build()
-```
-
-There is no `setLayout`, no `setHideChatButton`, no `enableRecording`. Recording-button visibility is `setShowRecordingButton(_:)`; auto-record on start is `setStartRecordingOnCallStart(_:)`.
-
----
-
-## Step 5 — Start / end the session
-
-> **There is NO `joinSession` and NO `CallSession`.** The lifecycle is `generateToken` → `startSession` → `endSession`, all static on `CometChatCalls`.
-
-```swift
-// `view` is the UIView the SDK renders the call into.
-CometChatCalls.startSession(callToken: token, callSetting: callSettings, view: callView, onSuccess: { _ in
-  // session started
-}, onError: { error in
-  // surface error
-})
-
-// End the call:
-CometChatCalls.endSession()             // EXISTS in v5 — do not say it doesn't
-```
-
----
-
-## Step 6 — Events: `CallsEventsDelegate`, not `CometChatCallsEventsListener`
-
-> **The listener protocol is `CallsEventsDelegate`.** `CometChatCallsEventsListener` does not exist. There is no `addEventListener(.someEnum)` granular-subscription API.
-
-```swift
-// v5: implement the CallsEventsDelegate protocol (callbacks are @objc optional).
-// Prefer the TYPED forms below (swiftinterface:29-54); the NSDictionary/NSArray
-// overloads still exist but are DEPRECATED.
-extension MyCallController: CallsEventsDelegate {
-  func onSessionTimeout()                                          { /* idle timeout — swiftinterface:30 */ }
-  func onCallEnded()                                               { /* ... */ }
-  func onCallEndButtonPressed()                                    { /* ... */ }
-  func onUserJoined(rtcUser: RTCUser)                              { /* swiftinterface:35 */ }
-  func onUserLeft(rtcUser: RTCUser)                                { /* swiftinterface:38 */ }
-  func onUserListChanged(rtcUsers: [RTCUser])                      { /* swiftinterface:41 */ }
-  func onAudioModeChanged(mode: [CallAudioMode])                   { /* swiftinterface:44 */ }
-  func onCallSwitchedToVideo(callSwitchedInfo: CallSwitchRequestInfo) { /* swiftinterface:47 */ }
-  func onUserMuted(rtcMutedUser: RTCMutedUser)                     { /* swiftinterface:50 */ }
-  func onRecordingToggled(recordingInfo: RTCRecordingInfo)         { /* one callback — no Started/Stopped/Failed split — swiftinterface:53 */ }
-}
-
-// Register either via the builder (setDelegate, Step 4) or:
-CometChatCalls.addCallEventListener(observerId: "my-id", delegate: self)
-```
-
-There is no `onScreenShareStarted`/`onScreenShareEnded`, no `onChatButtonClicked`, no `onActiveSpeakerUpdated`, and no layout-change callback in v5.
-
----
-
-## Step 7 — In-call control method names
-
-```diff
-- CometChatCalls.muteAudio(true)       // phantom
-+ CometChatCalls.audioMuted(true)      // mute
-+ CometChatCalls.audioMuted(false)     // unmute
-
-- CometChatCalls.pauseVideo(true)      // phantom
-+ CometChatCalls.videoPaused(true)
-+ CometChatCalls.videoPaused(false)
-
-  CometChatCalls.switchCamera()        // unchanged
-
-- CometChatCalls.setMode(mode)         // setMode is on CallSettingsBuilder, not the runtime facade
-+ // layout is fixed at session start via CallSettingsBuilder.setMode(_:) — there is no runtime setLayout
-
-  CometChatCalls.startRecording()      // recording control
-  CometChatCalls.stopRecording()
-
-  CometChatCalls.enterPIPMode()        // PiP — NOT CallSession.shared.enablePictureInPictureLayout
-  CometChatCalls.exitPIPMode()
-```
-
-Local screen-share initiation is **not** available on the iOS Calls SDK v5 — there is no `startScreenShare`.
-
----
-
-## Chat SDK signaling (ringing mode) — verify these too
-
-```diff
-- Call(receiverUid: uid, receiverType: .user, callType: .video)
-+ Call(receiverId: uid, callType: .video, receiverType: .user)   // CometChatSDK arg order
-
-- callType: .voice
-+ callType: .audio                     // CallType is .audio / .video / .audioVideo — there is no .voice
-
-- CometChat.login(UID:..., authKey:...)  // still correct; there is NO loginAsync
-```
-
-Call delegate is `CometChatCallDelegate` with two-param callbacks, e.g. `onIncomingCallReceived(incomingCall:error:)`; register with `CometChat.addCallListener(_:_:)` (positional labels).
-
----
-
-## Verification checklist
-
-- [ ] Podfile / Package.swift updated to `~> 5.0`
-- [ ] `pod install --repo-update` (CocoaPods) or SwiftPM resolved cleanly
-- [ ] NO `CometChatCalls.login` anywhere — auth is per-session via `generateToken`
-- [ ] `CallSettingsBuilder().build()` used; no `SessionSettings`/`SessionSettingsBuilder`
-- [ ] `CallsEventsDelegate` implemented; no `CometChatCallsEventsListener`, no `addEventListener(.enum)`
-- [ ] Lifecycle is `generateToken` → `startSession` → `endSession`; no `joinSession`, no `CallSession.shared`
-- [ ] Controls use `audioMuted`/`videoPaused`/`enterPIPMode`/`exitPIPMode`
-- [ ] `Call(receiverId:callType:receiverType:)` arg order; `CallType` has no `.voice`
-- [ ] Real-device smoke: incoming call from iPhone → answer → mute → end
-
----
-
-## Pointers
-
-- Canonical migration: https://www.cometchat.com/docs/calls/ios/migration-guide-v5
-- `cometchat-ios-calls/SKILL.md` — seven hard rules (still apply post-v5)
-- `cometchat-ios-calls/references/server-apns-pushkit.md` — PushKit setup (unchanged in v5)