@cometchat/skills 4.3.0 → 4.4.0

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

@@ -61,8 +61,8 @@ 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)
+  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,
@@ -122,35 +122,28 @@ Diffable data source means roster updates animate cleanly without cell-recreatio
 
 ---
 
-## Active-speaker observation
+## Participant-roster observation
 
-`CometChatCallsSDK` exposes the active-speaker callback via `CometChatCallsEventsListener`. Wrap it for SwiftUI/Combine:
+> **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
-final class CallStateObserver: ObservableObject {
-  @Published var activeSpeakerUid: String?
-  @Published var participants: [Participant] = []
+import CometChatCallsSDK
 
-  private var debounceTimer: Timer?
+final class CallStateObserver: NSObject, ObservableObject, CallsEventsDelegate {
+  @Published var participants: [RTCUser] = []
 
-  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]) {
+  // swiftinterface:41 onUserListChanged(rtcUsers: [RTCUser])
+  func onUserListChanged(rtcUsers: [RTCUser]) {
     DispatchQueue.main.async {
-      self.participants = users
+      self.participants = rtcUsers
     }
   }
 }
 ```
 
-500ms debounce — same rule as RN/Angular. Without it, the spotlight tile jitters.
+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.
 
@@ -202,63 +195,35 @@ The `Identifiable` conformance on `Participant` (with `id = uid`) is what makes
 
 ---
 
-## 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)
-  }
+## Moderator actions — not in the Calls SDK
 
-  private var canModerate: Bool {
-    return group?.scope == "admin" || group?.scope == "moderator"
-  }
-}
-```
+> **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.
 
-`popoverPresentationController` is required on iPad — without it, action sheets crash on iPad.
+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 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)
-        }
+  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)
@@ -312,11 +277,9 @@ NotificationCenter.default.addObserver(
 
 @objc func powerStateChanged() {
   if ProcessInfo.processInfo.isLowPowerModeEnabled && callActive {
-    Task {
-      await CometChatCalls.pauseVideo(true)
-      DispatchQueue.main.async {
-        self.showBanner("Video paused — Low Power Mode")
-      }
+    CometChatCalls.videoPaused(true)   // NOT pauseVideo; synchronous
+    DispatchQueue.main.async {
+      self.showBanner("Video paused — Low Power Mode")
     }
   }
 }

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

@@ -1,37 +1,33 @@
 # Idle timeout on iOS
 
-Same SDK API as web — `idleTimeoutPeriodBeforePrompt` / `idleTimeoutPeriodAfterPrompt` on `CallSettingsBuilder`, `onSessionTimedOut` event. iOS-specific deltas: CallKit interaction (idle timeout doesn't end the OS-level call card automatically; you have to report end to CallKit), foreground/background interplay (iOS can suspend the call session in background), and SwiftUI/UIKit prompt UI.
+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 API
+## 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()
-  .setSessionType(.video)
-  .setIsAudioOnly(false)
-  .setIdleTimeoutPeriodBeforePrompt(60_000)   // ms
-  .setIdleTimeoutPeriodAfterPrompt(120_000)
+  .setIdleTimeoutPeriod(120)        // swiftinterface:289 setIdleTimeoutPeriod(_ value: Int) -> Self
+  .setDelegate(callListener)
   .build()
-```
-
-Listener — implement on the `CometChatCallsEventsListener`:
+// ... generateToken → startSession(callToken:callSetting:view:) ...
 
-```swift
-class CallListener: NSObject, CometChatCallsEventsListener {
-  func onSessionTimedOut() {
+class CallListener: NSObject, CallsEventsDelegate {
+  // swiftinterface:30 — optional CallsEventsDelegate.onSessionTimeout()
+  func onSessionTimeout() {
     DispatchQueue.main.async {
-      // Report end to CallKit (rule 1.5 — hangup cleanup)
-      CallManager.shared.endCall(reason: .answeredElsewhere)
-      // Navigate away
+      // Report end to CallKit (rule 1.5 — hangup cleanup); SDK already ended the session.
+      CallManager.shared.endCall(reason: .remoteEnded)
     }
   }
-  // ...
 }
 ```
 
@@ -41,7 +37,7 @@ The `CallManager.shared.endCall(reason:)` call is critical — see `references/c
 
 ## CallKit interaction — endCall reason
 
-When the SDK fires `onSessionTimedOut`, you must report the call end to CallKit. The reason matters for system UI:
+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
@@ -61,6 +57,8 @@ provider.reportCall(
 
 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
@@ -117,7 +115,7 @@ struct CallView: View {
           .onTapGesture { /* prevent dismiss on backdrop */ }
         IdleTimeoutPrompt(
           onStay: { showIdlePrompt = false; resetIdleTimer() },
-          onEnd: { CometChatCallsSDK.CallSession.shared.leaveSession() },
+          onEnd: { CometChatCalls.endSession() },
         )
       }
     }
@@ -143,7 +141,7 @@ alert.addAction(UIAlertAction(title: "Stay", style: .default) { _ in
   resetIdleTimer()
 })
 alert.addAction(UIAlertAction(title: "End now", style: .destructive) { _ in
-  CometChatCallsSDK.CallSession.shared.leaveSession()
+  CometChatCalls.endSession()
 })
 alert.preferredAction = alert.actions.first  // make Stay the default
 present(alert, animated: true)
@@ -157,17 +155,18 @@ present(alert, animated: true)
 
 Web sister reference rules apply, plus iOS-specific:
 
-1. **`onSessionTimedOut` without reporting end to CallKit.** Lock-screen call card persists — user sees a stuck "ongoing call" until they manually end it.
-2. **Using `.failed` reason for idle timeout end.** iOS shows "call failed" — wrong semantic. Use `.remoteEnded`.
-3. **Custom prompt that doesn't dim background.** Calls UI keeps rendering behind the prompt; user can interact with controls and call ends prematurely.
-4. **`UIAlertController` from background queue.** Crashes — must be on main. Wrap in `DispatchQueue.main.async`.
+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
 
-- [ ] CallSettingsBuilder sets both idle periods
-- [ ] `onSessionTimedOut` listener reports end to CallKit with `.remoteEnded` reason
+- [ ] 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

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

@@ -1,33 +1,29 @@
 # In-call chat on iOS
 
-Same SDK shape as web. iOS-specific: `UISheetPresentationController` for the chat sheet (iOS 15+) + AVAudioSession ducking when keyboard is open.
+> **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.
 
 ---
 
-## SDK API
+## 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 CometChatCallsSDK
 import CometChatSDK
 
-let settings = CallSettingsBuilder()
-  .setSessionType(.video)
-  .setHideChatButton(false)
-  .build()
-
-// Chat button event — implement in your CometChatCallsEventsListener
-func onChatButtonClicked() {
-  DispatchQueue.main.async {
-    self.presentChatSheet()
-  }
-}
+// 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
-CometChatCalls.setChatButtonUnreadCount(5)
-CometChatCalls.setChatButtonUnreadCount(0)
+// 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.
 ```
 
 ---
@@ -93,8 +89,8 @@ class InCallChatViewController: UIViewController {
 
   override func viewWillDisappear(_ animated: Bool) {
     super.viewWillDisappear(animated)
-    // Clear badge on close
-    CometChatCalls.setChatButtonUnreadCount(0)
+    // Clear YOUR unread count on close (no SDK badge API exists).
+    NotificationCenter.default.post(name: .inCallChatClosed, object: nil)
   }
 
   private func embedMessageList() {
@@ -155,8 +151,8 @@ Most apps don't need this; the kit's defaults are sensible. Override only if use
 
 Web sister rules apply, plus iOS-specific:
 
-1. **`UIAlertController` instead of sheet for in-call chat.** Wrong UX — `UIAlertController` is for confirmations, not extended UIs.
-2. **`present(nav, animated: true)` from background queue.** Crash. Always main queue (covered by `DispatchQueue.main.async` in `onChatButtonClicked`).
+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.
 
@@ -164,8 +160,8 @@ Web sister rules apply, plus iOS-specific:
 
 ## Verification checklist
 
-- [ ] `setHideChatButton(false)` in CallSettings
-- [ ] `onChatButtonClicked` presents the chat sheet on main queue
+- [ ] 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

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

@@ -1,9 +1,11 @@
 # CometChat Calls iOS SDK v4 → v5 migration
 
-`CometChatCallsSDK` v5 is a drop-in upgrade for v4 — bump the SwiftPM/CocoaPods version, your existing call code still compiles. Migrate to v5 APIs for granular events + simpler init.
+`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
@@ -22,111 +24,167 @@ pod install --repo-update
 
 ---
 
-## Step 2 — Migrate init to plain struct
+## Step 2 — Init
 
-```diff
-- let callAppSettings = CallAppSettings.Builder()
--   .setAppId("APP_ID")
--   .setRegion("REGION")
--   .build()
-- CometChatCalls.init(with: callAppSettings) { error in
--   // ...
-- }
-
-+ let settings = CallAppSettings(appId: "APP_ID", region: "REGION")
-+ try await CometChatCalls.init(with: settings)
+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
+})
 ```
 
-V5 ships async/await. The completion-handler form still works for backwards compat.
+There is no async/await `init(with:)` form and no `CallAppSettings.Builder()` nested type — use `CallAppSettingsBuilder()`.
 
 ---
 
-## Step 3 — Add Calls SDK login
+## 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
-// After CometChat.login() resolves with a User:
-let authToken = user.authToken
-try await CometChatCalls.login(authToken: authToken)
+// 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
+})
 ```
 
-After this, `generateToken()` and `joinSession()` no longer need an authToken parameter.
+`generateToken` is `CometChatCalls.generateToken(authToken:sessionID:onSuccess:onError:)`.
 
 ---
 
-## Step 4 — Migrate session settings
+## Step 4 — Session settings (`CallSettingsBuilder`, not `SessionSettings`)
 
-```diff
-- let callSettings = CallSettings.Builder()
--   .setSessionType(.video)
--   .startWithAudioMuted(false)
--   .showRecordingButton(true)
--   .build()
-
-+ let sessionSettings = SessionSettings(
-+   sessionType: .video,
-+   startAudioMuted: false,
-+   hideRecordingButton: false,    // INVERTED — was showRecordingButton(true)
-+   layout: .tile
-+ )
+> **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 — Migrate events to delegates / closures
+## Step 5 — Start / end the session
 
-```diff
-- // v4: implementing CometChatCallsEventsListener with all callbacks
-- class MyCallEvents: CometChatCallsEventsListener {
--   func onCallEnded() { /* ... */ }
--   func onUserJoined(user: User) { /* ... */ }
--   func onUserLeft(user: User) { /* ... */ }
--   func onError(error: Error) { /* ... */ }
-- }
-
-+ // v5: granular subscriptions
-+ let unsub1 = CometChatCalls.addEventListener(.sessionLeft) { _ in /* ... */ }
-+ let unsub2 = CometChatCalls.addEventListener(.participantJoined) { participant in /* ... */ }
-+ let unsub3 = CometChatCalls.addEventListener(.participantLeft) { participant in /* ... */ }
-+
-+ // Cleanup
-+ deinit { unsub1(); unsub2(); unsub3() }
+> **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 6 — Method renames
+## Step 7 — In-call control method names
 
 ```diff
-// session lifecycle — receiver changed from CometChatCalls (static) to CallSession.shared (singleton)
-- CometChatCalls.endSession()
-+ CallSession.shared.leaveSession()
+- 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.muteAudio(true)
-+ CallSession.shared.muteAudio()
-- CometChatCalls.muteAudio(false)
-+ CallSession.shared.unmuteAudio()
+  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
 
-- CometChatCalls.startScreenShare()
-+ CallSession.shared.startScreenShare()
+- callType: .voice
++ callType: .audio                     // CallType is .audio / .video / .audioVideo — there is no .voice
 
-// layout stays static on CometChatCalls
-- CometChatCalls.setMode(mode)
-+ CometChatCalls.setLayout(layout)
+- CometChat.login(UID:..., authKey:...)  // still correct; there is NO loginAsync
 ```
 
-**Hold onto the `CallSession.shared` singleton** — most in-call APIs (mute, video, screen-share, layout-events, leave) live on it, not on `CometChatCalls`. Same shift the Android SDK did in v5; if you've been writing call code against v4's static-method-everything pattern, this is the biggest re-org.
+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
+- [ ] Podfile / Package.swift updated to `~> 5.0`
 - [ ] `pod install --repo-update` (CocoaPods) or SwiftPM resolved cleanly
-- [ ] `CometChatCalls.login(authToken:)` called after `CometChat.login`
-- [ ] CallSettings.Builder replaced with `SessionSettings` struct
-- [ ] CometChatCallsEventsListener replaced with `addEventListener`
-- [ ] Method renames applied
-- [ ] PushKit + CallKit integration still works (no v5 changes there)
+- [ ] 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
 
 ---