@cometchat/skills 4.3.0 → 4.4.0

package/skills/cometchat-ios-calls/SKILL.md

@@ -1,9 +1,8 @@
 ---
 name: cometchat-ios-calls
-description: CometChat Calls SDK v5 integration for native iOS (Swift; SwiftUI + UIKit hosting). Covers SDK install (SPM + CocoaPods), CometChatCalls init, dual-SDK ringing (Chat SDK initiateCall + Calls SDK joinSession), CallKit + PushKit VoIP push, AVAudioSession routing, mixed-stack hosting (UIViewControllerRepresentable for SwiftUI), Info.plist permissions + Background Modes, and additive-vs-standalone modes.
+description: CometChat Calls SDK v5 integration for native iOS (Swift; SwiftUI + UIKit hosting). Covers SDK install (SPM + CocoaPods), CometChatCalls init, dual-SDK ringing (Chat SDK initiateCall + Calls SDK generateToken/startSession), CallKit + PushKit VoIP push, AVAudioSession routing, mixed-stack hosting (UIViewControllerRepresentable for SwiftUI), Info.plist permissions + Background Modes, and additive-vs-standalone modes.
 license: "MIT"
 compatibility: "Xcode 15+, Swift 5.9+, iOS 13+ deployment target; CometChatCallsSDK 5.x; CometChatSDK 4.x; CometChatUIKitSwift 5.x (additive mode)"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "4.0.0"
@@ -22,66 +21,51 @@ Production-grade voice + video calling for native iOS. Loaded by `cometchat-call
 - `cometchat-ios-core` — Chat SDK init, login, `Secrets.swift` / `.xcconfig` credential conventions, SwiftUI vs UIKit entry-point detection
 
 **Ground truth:**
-- SDK source — `~/Downloads/calls-sdk/calls-sdk-ios-5/sdk/`
-- Sample app — `~/Downloads/calls-sdk/calls-sdk-ios-5/sample-apps/cometchat-calls-sample-app-ios/`
+- SDK source — `calls-sdk-ios-5/sdk/`
+- Sample app — `calls-sdk-ios-5/sample-apps/cometchat-calls-sample-app-ios/`
 - `Package.swift` — `https://github.com/cometchat/calls-sdk-ios.git` (SPM)
 - Public docs — https://www.cometchat.com/docs/calls/ios/overview
 
 ---
 
-## ⚠️ Known upstream issue — iOS v5 binary is broken (May 2026)
+## iOS Calls SDK v5 resolution — verified working (re-checked 2026-06-04)
 
-**SPM and CocoaPods both fail to resolve the iOS Calls SDK v5** because the WebRTC binary it depends on is missing from Cloudsmith:
-
-```
-https://dl.cloudsmith.io/public/cometchat/cometchat/raw/versions/124.0.4/CometChatWebRTC-124.0.4.xcframework.zip
-→ 404 Not Found
-```
-
-This affects every v5 tag (`5.0.0`, `5.0.0-beta.1` … `5.0.0-beta.3`). The `Package.swift` and `.podspec` both reference the same broken URL.
-
-**Until upstream republishes the binary:**
-- Customers on iOS should stay on **v4.2.x** of the Calls SDK (it has its own WebRTC dependency that's still hosted)
-- If you must use v5 for parity with other platforms, contact CometChat support for a working binary or a private SPM fork
-- This skill's v5 setup section assumes the binary is available — that assumption is currently invalid for iOS only
-
-Tracking this so the next audit pass can verify when it's fixed. The vendor sample-apps at `~/Downloads/calls-sdk/calls-sdk-ios-5/sample-apps/` reference the same broken binary — they don't ship a workaround.
+> An earlier draft of this skill warned that "the iOS Calls SDK v5 binary is broken / missing from Cloudsmith — stay on v4.2.x." **That warning was wrong and has been removed.** It was based on a hand-constructed URL (`…/raw/versions/124.0.4/CometChatWebRTC-124.0.4.xcframework.zip`) that 404s — but that is NOT the path the podspec/`Package.swift` actually fetches, so its 404 never proved anything. Verified 2026-06-04:
+> - **Additive (UI Kit) path:** `CometChatCallsSDK` v5 ships **vendored inside `CometChatUIKitSwift`** — a clean `pod install` resolves `CometChatUIKitSwift (5.1.13)` (which bundles the v5 CallsSDK framework) with **no 404**. The audited `CometChatCallsSDK.swiftinterface` (v5 shape: `generateToken`/`startSession`, no `login`) came straight out of that resolved framework.
+> - **Standalone path:** `CometChatCallsSDK` v5.0.0 is consumable via CocoaPods (e.g. the internal VoIP+APNs sample under Linear ENG-35167 builds against it).
+>
+> If you ever DO hit a missing-WebRTC binary on a direct standalone `pod 'CometChatCallsSDK'` install, treat it as an environment/registry hiccup and check the current podspec URL — it is not a known blanket failure, and there is no open vendor ticket for it.
 
 ---
 
 ## 1. The seven hard rules — iOS specialization
 
-### 1.0 Calls SDK login is its own step (v5+)
+> ⚠️ **TOP PRIORITY (ENG-35710): Auth-token passing is the most-broken step on iOS Calls integrations.** Unlike Android / Flutter / JS, the **iOS Calls SDK 5.x has NO separate login step** — there is no `CometChatCalls.login(...)` and no `CometChatCalls.getLoggedInUser()` (those are phantom; verified absent from `CometChatCallsSDK`). Auth is supplied **per session** as the `authToken:` argument to `CometChatCalls.generateToken(authToken:sessionID:)`. Every tester who hit "calls don't work" on iOS traced back to that token: (a) the token was empty/nil → `generateToken` fails with **"auth token cannot be null"**; (b) a server-minted token expired between mint and `generateToken` (default ~30-minute TTL); (c) the client-side `apiKey` was passed instead of the user's auth token. Before scaffolding ANY iOS calls code, confirm the auth path (dev: read `CometChat.getUserAuthToken()`; production: fetch a fresh server-minted token) and feed it to `generateToken`. Mixing them is the canonical "ringing but never joins" iOS failure mode.
+
+### 1.0 The iOS Calls SDK has NO separate login (v5)
 
-The v5 Calls SDK has its own auth state, separate from the Chat SDK. After `CometChat.login` succeeds, you MUST also call `CometChatCalls.login` — without it, the FIRST calls API call throws **"auth token cannot be null"**.
+Unlike the Android / Flutter / JS Calls SDKs, **`CometChatCalls` on iOS has no `login()` and no `getLoggedInUser()`** — those methods do not exist in `CometChatCallsSDK` 5.x. There is nothing to "log in" to. Once the Chat SDK session exists, you authorize each call session by passing an **auth token** to `generateToken(authToken:sessionID:)`, then `startSession(callToken:callSetting:view:)` with the returned call token (full flow in §1.1).
 
 ```swift
 import CometChatSDK
 import CometChatCallsSDK
 
+// Chat SDK login is the ONLY login. (UI Kit users: CometChatUIKit.login already did this.)
 CometChat.login(UID: uid, authKey: AUTH_KEY) { user in
-    // Chat SDK ready — now login Calls SDK
-    CometChatCalls.login(UID: uid, authKey: AUTH_KEY) { callUser in
-        // both ready — incoming-call listener can be registered, calls can fire
-    } onError: { error in
-        // surface to user — common cause: typo in app id / auth key
-    }
+    // Chat SDK ready. No CometChatCalls.login() exists — do NOT call it.
+    // The incoming-call listener can be registered now; per-call auth happens via generateToken.
 } onError: { error in
-    // chat login failed; calls login never fires
+    // chat login failed
 }
-```
-
-For production with server-minted tokens:
 
-```swift
-CometChatCalls.login(authToken: tokenFromBackend) { callUser in
-    // …
-} onError: { error in /* … */ }
+// Dev: the auth token for generateToken comes from the Chat SDK:
+let authToken = CometChat.getUserAuthToken()   // String? — pass to generateToken(authToken:)
+// Production: fetch a fresh server-minted token from your backend instead.
 ```
 
 **Surprises:**
-- The Chat SDK persists login via Keychain across app launches. The **Calls SDK does NOT** persist as reliably — always check `CometChatCalls.getLoggedInUser()` on app start and re-login if nil.
-- Calls SDK errors hit the `onError` closure (not `do/try/catch`). The error type is `CometChatException` from the Calls module — has `errorDescription` and `errorCode`.
+- There is **no Calls-SDK session to persist** — the Chat SDK's Keychain session is the only persisted login. On app start just confirm `CometChat.getLoggedInUser() != nil`.
+- `generateToken` / `startSession` errors hit the `onError` closure (not `do/try/catch`). The error type is `CometChatCallException` — has `errorDescription` and `errorCode`.
 
 ### 1.1 Dual-SDK contract
 
@@ -91,7 +75,7 @@ Chat SDK (`CometChatSDK`) initiates ringing; Calls SDK (`CometChatCallsSDK`) run
 // ✓ RIGHT — initiate ringing (Chat SDK)
 import CometChatSDK
 
-let outgoing = Call(receiverUid: receiverUid, receiverType: .user, callType: .video)
+let outgoing = Call(receiverId: receiverUid, callType: .video, receiverType: .user)
 CometChat.initiateCall(call: outgoing, onSuccess: { initiated in
   // initiated.sessionID is what the Calls SDK will join
 }, onError: { error in
@@ -100,34 +84,113 @@ CometChat.initiateCall(call: outgoing, onSuccess: { initiated in
 ```
 
 ```swift
-// ✓ RIGHT — join WebRTC session (Calls SDK) after acceptance.
-// Matches upstream sample at calls-sdk-ios-5/sample-apps/cometchat-calls-
-// sample-app-ringing-ios/CometChatCallsRinging/CallView.swift.
-//   - SessionSettingsBuilder (NOT CallSettingsBuilder — that's chat-side)
-//   - Single-call joinSession(sessionID:callSetting:container:) — token is
-//     generated internally; no separate generateToken needed
-//   - Register listeners on the resulting CallSession in onSuccess
+// ✓ RIGHT — start the WebRTC session (Calls SDK 5.x) after acceptance.
+// iOS Calls SDK 5.x is a TWO-STEP flow: generateToken → startSession.
+// There is NO joinSession, NO CallSession singleton, and NO SessionSettingsBuilder
+// in the 5.x SDK — those are phantom. The real builder is CallSettingsBuilder.
+//   - CallSettingsBuilder (NOT SessionSettingsBuilder) builds the CallSettings
+//   - generateToken(authToken:sessionID:) FIRST, then startSession(callToken:callSetting:view:)
+//   - Attach the event listener via CallSettingsBuilder.setDelegate(_:) (CallsEventsDelegate)
 import CometChatCallsSDK
 
-let settings = SessionSettingsBuilder()
-  .setTitle("CometChat Call")
-  .startVideoPaused(false)
-  .startAudioMuted(false)
+let settings = CallSettingsBuilder()
+  .setStartVideoMuted(false)
+  .setStartAudioMuted(false)
+  .setDelegate(callListener)        // any CallsEventsDelegate — onCallEnded, onUserJoined, …
   .build()
 
-CometChatCalls.joinSession(
-  sessionID: sessionID,
-  callSetting: settings,
-  container: callContainerView   // UIView with measurable bounds
-) { success in
-  let session = CometChatCallsSDK.CallSession.shared
-  session.addSessionStatusListener(callListener)
-  session.addButtonClickListener(callListener)
+// loggedInAuthToken: the current user's auth token — CometChat.getUserAuthToken()
+//   (User has NO .authToken property; getUserAuthToken() is the real accessor)
+CometChatCalls.generateToken(authToken: loggedInAuthToken, sessionID: sessionID) { callToken in
+  guard let callToken = callToken else { return }
+  CometChatCalls.startSession(
+    callToken: callToken,
+    callSetting: settings,
+    view: callContainerView         // UIView with measurable bounds
+  ) { _ in
+    // session started — the call UI is rendered into callContainerView
+  } onError: { error in
+    print("startSession failed: \(error?.errorDescription ?? "unknown")")
+  }
 } onError: { error in
-  print("joinSession failed: \(error?.errorDescription ?? "unknown")")
+  print("generateToken failed: \(error?.errorDescription ?? "unknown")")
 }
 ```
 
+### 1.1a End-to-end initiate→join sequence (ENG-35710)
+
+After `CometChat.initiateCall` the caller's session is NOT auto-joined — the gap between *initiation* and *joining* is the second canonical iOS failure (after auth-token). Three events must fire in sequence; the caller side handles each in a different callback.
+
+> **Corrected 2026-06-02 against `calls-sdk-ios/sample-apps/cometchat-calls-sample-app-ringing-ios/CometChatCallsRinging/AppState.swift:213`** — the listener protocol is **`CometChatCallDelegate`** (NOT `CometChatCallsListener` as earlier drafts said), and each callback takes TWO parameters (`Call?` + `CometChatException?`), NOT one. Earlier example would not compile.
+
+```swift
+// Step A: register the listener on app start (before any call fires)
+// Listener ID is a String; listener instance is "self" or any class conforming
+// to CometChatCallDelegate.
+CometChat.addCallListener(callListenerID, self)
+
+// Step B: conform to CometChatCallDelegate (NOT CometChatCallsListener)
+extension YourClass: CometChatCallDelegate {
+  // Caller side: the OTHER party accepted — NOW join the session
+  func onOutgoingCallAccepted(acceptedCall: Call?, error: CometChatException?) {
+    if let error = error { /* surface */ return }
+    guard let call = acceptedCall, let sessionID = call.sessionID else { return }
+    startCallSession(sessionID: sessionID)
+  }
+  // Receiver side: incoming call rang — present accept UI; on accept, start the session
+  func onIncomingCallReceived(incomingCall: Call?, error: CometChatException?) {
+    if let error = error { /* surface */ return }
+    guard let call = incomingCall else { return }
+    presentIncomingCallUI(for: call) { accepted in
+      if accepted {
+        CometChat.acceptCall(sessionID: call.sessionID ?? "") { acceptedCall in
+          self.startCallSession(sessionID: acceptedCall?.sessionID ?? "")
+        } onError: { _ in /* surface */ }
+      }
+    }
+  }
+  func onOutgoingCallRejected(rejectedCall: Call?, error: CometChatException?) { /* end UI, cleanup */ }
+  func onIncomingCallCancelled(canceledCall: Call?, error: CometChatException?) { /* dismiss incoming UI — label is canceledCall: (single L) */ }
+}
+
+// Don't forget to remove the listener on teardown
+// CometChat.removeCallListener(callListenerID)
+
+// Step B: kick the call off (caller — your "Call" button taps this)
+let outgoing = Call(receiverId: targetUid, callType: .video, receiverType: .user)
+CometChat.initiateCall(call: outgoing, onSuccess: { initiated in
+  // initiated.sessionID is what the session will use — but DO NOT start the
+  // session here. Wait for onOutgoingCallAccepted on the listener. Starting before
+  // the remote accepts means you're alone in an empty session.
+}, onError: { error in /* surface */ })
+
+// Step C: start the session (caller in onOutgoingCallAccepted, receiver after acceptCall)
+// 5.x flow: generateToken(authToken:sessionID:) → startSession(callToken:callSetting:view:)
+func startCallSession(sessionID: String) {
+  let settings = CallSettingsBuilder()
+    .setStartVideoMuted(false)
+    .setStartAudioMuted(false)
+    .setDelegate(self)             // self conforms to CallsEventsDelegate
+    .build()
+  CometChatCalls.generateToken(authToken: loggedInAuthToken, sessionID: sessionID) { callToken in
+    guard let callToken = callToken else { return }
+    CometChatCalls.startSession(
+      callToken: callToken,
+      callSetting: settings,
+      view: callContainerView      // UIView WITH non-zero bounds (lay out first)
+    ) { _ in
+      // session started
+    } onError: { error in
+      print("startSession failed: \(error?.errorDescription ?? "unknown")")
+    }
+  } onError: { error in
+    print("generateToken failed: \(error?.errorDescription ?? "unknown")")
+  }
+}
+```
+
+The shape: `initiateCall` → wait for `onOutgoingCallAccepted` on your `CometChatCallDelegate` → `generateToken` → `startSession`. Skipping the listener and starting inside `initiateCall`'s `onSuccess` is the "ringing but never joins" trap — you'll see the call connect on the wire but the receiver's accept never reaches your code.
+
 ### 1.2 CallKit + PushKit are mandatory
 
 iOS will not deliver standard push notifications to a backgrounded/terminated app for an incoming call — the app would have to be foregrounded for it to ring. CallKit + PushKit is the only correct path:
@@ -168,13 +231,13 @@ Same rule as the chat dispatcher / `cometchat-ios-production`. Production calls
 Releasing the camera + mic on iOS is straightforward; the gotcha is `AVAudioSession`:
 
 ```swift
-import CometChatCallsSDK   // for the CallSession namespace
+import CometChatCallsSDK
 
 func endCall() {
-  // v5: leaveSession lives on the CallSession singleton, NOT on CometChatCalls.
-  // CometChatCalls.endSession() exists as a deprecated alias but the v5 API is
-  // singleton-based — use the form below to stay forward-compatible.
-  CometChatCallsSDK.CallSession.shared.leaveSession()
+  // v5: end the session via the static CometChatCalls.endSession().
+  // There is NO CallSession singleton and NO leaveSession() in the 5.x SDK —
+  // all in-call control is via static funcs on CometChatCalls.
+  CometChatCalls.endSession()
   callContainer.subviews.forEach { $0.removeFromSuperview() }
 
   // CRITICAL: deactivate the audio session, otherwise the speaker stays
@@ -191,15 +254,17 @@ func endCall() {
 }
 ```
 
-**Module-qualified `CometChatCallsSDK.CallSession.shared`** is the canonical reference (matches the iOS sample app). `CallSession` exists in both `CometChatSDK` and `CometChatCallsSDK` modules — Swift will resolve the unqualified name based on import order, but qualifying with the module prefix makes intent explicit and avoids drift if Swift's resolution changes. Same singleton hosts the in-call control APIs:
+In-call controls are **static funcs on `CometChatCalls`** (there is no `CallSession` type in the 5.x Calls SDK). Audio/video toggles take a `Bool`:
 
 ```swift
-CometChatCallsSDK.CallSession.shared.muteAudio()
-CometChatCallsSDK.CallSession.shared.unmuteAudio()
-CometChatCallsSDK.CallSession.shared.pauseVideo()
-CometChatCallsSDK.CallSession.shared.resumeVideo()
-CometChatCallsSDK.CallSession.shared.startScreenShare()
-CometChatCallsSDK.CallSession.shared.stopScreenShare()
+CometChatCalls.audioMuted(true)    // mute mic;   false = unmute
+CometChatCalls.videoPaused(true)   // pause video; false = resume
+CometChatCalls.switchCamera()
+CometChatCalls.enterPIPMode()      // picture-in-picture; exitPIPMode() to leave
+CometChatCalls.startRecording()    // stopRecording() to end
+// NOTE: the iOS Calls SDK 5.x has NO local screen-share initiation API
+// (no startScreenShare/stopScreenShare) — iOS can only RECEIVE a remote
+// participant's screen share, not start one.
 ```
 
 Skipping the `setActive(false, options: .notifyOthersOnDeactivation)` is the canonical "music doesn't resume after the call" bug.
@@ -223,10 +288,68 @@ In standalone mode, you do NOT render an in-app incoming-call screen. CallKit's
 
 1. Keep `PKPushRegistry` alive — register in `application(_:didFinishLaunchingWithOptions:)` (UIKit) or `App.init()` (SwiftUI's `@main`)
 2. On VoIP payload → call `CXProvider.reportNewIncomingCall`
-3. Implement `CXProviderDelegate` `provider(_:perform:)` for `CXAnswerCallAction` — this is where you finally call `CometChatCalls.joinSession`
+3. Implement `CXProviderDelegate` `provider(_:perform:)` for `CXAnswerCallAction` — this is where you finally call `CometChatCalls.generateToken` then `startSession`
 
 In additive mode, the UI Kit's incoming-call view can be used for in-foreground rings; CallKit handles backgrounded/terminated rings.
 
+### 1.7a Default incoming/outgoing UI fallback (ENG-35710)
+
+Two iOS testers shipped without a foreground incoming/outgoing screen because the skill jumped straight to CallKit and never showed what to render when the app is already in-foreground. Result: a Call rings on the wire, but the user-facing app shows nothing — the call connects, the call drops, no feedback.
+
+**If the developer hasn't asked for a custom incoming-call UI, wire the kit's defaults:**
+
+```swift
+// SwiftUI host
+import SwiftUI
+import UIKit
+import CometChatUIKitSwift
+
+// The kit ships call UI as UIViewControllers (CometChatIncomingCall / CometChatOutgoingCall /
+// CometChatOngoingCall) — there are NO `…SwiftUI`-suffixed wrappers. Bridge with
+// UIViewControllerRepresentable. Present the controller when your delegate fires (§1.1a);
+// configure it via the kit's IncomingCallConfiguration rather than a constructor arg.
+struct CometChatIncomingCallView: UIViewControllerRepresentable {
+  func makeUIViewController(context: Context) -> CometChatIncomingCall {
+    CometChatIncomingCall()
+  }
+  func updateUIViewController(_ vc: CometChatIncomingCall, context: Context) {}
+}
+
+struct AppRootView: View {
+  @State private var hasIncomingCall = false
+  var body: some View {
+    ZStack {
+      ContentView()    // your app's tabs / nav
+      if hasIncomingCall {
+        CometChatIncomingCallView()
+          .ignoresSafeArea()
+      }
+    }
+    // flip `hasIncomingCall` from your CometChatCallDelegate.onIncomingCallReceived (see §1.1a)
+  }
+}
+```
+
+```swift
+// UIKit host
+class RootViewController: UIViewController {
+  override func viewDidLoad() {
+    super.viewDidLoad()
+    // Install the kit's incoming-call VC above all other view controllers
+    let incoming = CometChatIncomingCall()
+    addChild(incoming)
+    view.addSubview(incoming.view)
+    incoming.view.frame = view.bounds
+    incoming.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+    incoming.didMove(toParent: self)
+  }
+}
+```
+
+Mounting at the root (above your nav / tab structure) means foreground rings work app-wide — same idea as the web skill's "mount above the route boundary" rule. CallKit still handles backgrounded/terminated rings; the kit's incoming-call VC handles foreground rings. Together they're the complete foreground-and-background coverage.
+
+If the developer DOES want a custom UI: tell them to (a) implement `CometChatCallDelegate.onIncomingCallReceived` to drive their own SwiftUI/UIKit screen, (b) call `CometChat.acceptCall` / `rejectCall` from that screen, and (c) on accept, follow the `generateToken` → `startSession` recipe in §1.1a. The kit's default UI is the recommended starting point because it already wires accept/reject/timer/profile-pic; replicating it from scratch is a 200-line side quest.
+
 ---
 
 ## 2. Setup
@@ -280,9 +403,11 @@ CometChat.init(appId: Secrets.cometchatAppID, appSettings: appSettings) { isInit
     .setRegion(Secrets.cometchatRegion)
     .build()
 
-  CometChatCalls.init(callAppSettings: callAppSettings) { _ in
+  CometChatCalls.init(callsAppSettings: callAppSettings, onSuccess: { _ in
     // ready — register PushKit (rule 1.2) and CXProvider (rule 1.7) here
-  }
+  }, onError: { error in
+    print("CometChatCalls.init failed: \(error?.errorDescription ?? "")")
+  })
 }
 ```
 
@@ -296,19 +421,19 @@ Credentials via `Secrets.swift` (gitignored) or `.xcconfig` Build Settings — s
 
 | Type | Purpose |
 |---|---|
-| `CometChatCalls` | Top-level facade — init, joinSession, endSession, generateToken |
-| `CallSettingsBuilder` | Per-session config (type, layout, hide buttons, audio mode) |
-| `CallSession` | Active session object — held during a call |
-| `CallType` | `.voice` / `.video` |
-| `LayoutMode` | `.tile` / `.sidebar` / `.spotlight` |
-| `CallLogRequest.CallLogRequestBuilder` | Paginated call history |
-| `CometChatCallsEventsListener` (protocol) | Lifecycle + media + participant + button events |
+| `CometChatCalls` | Top-level facade — `init`, `generateToken`, `startSession`, `endSession`, `audioMuted(_:)`, `videoPaused(_:)`, `switchCamera`, `enterPIPMode`/`exitPIPMode`, `startRecording`/`stopRecording`, `addCallEventListener` |
+| `CallSettingsBuilder` | Per-session config (audio-only, presenter, hide buttons, start muted, `setDelegate`) → `.build()` returns `CallSettings` |
+| `CallSettings` | The built per-session config passed to `startSession(callToken:callSetting:view:)` (there is no `CallSession` object in 5.x — `startSession` returns a session-id `String`) |
+| `CallType` | `.video` / `.audio` / `.audioVideo` (swiftinterface:294-297) — there is NO `.voice` |
+| `DisplayModes` (enum) | `.default` / `.single` / `.spotlight` (swiftinterface:175) — passed to `CallSettingsBuilder.setMode(_:)`. The current setter is `setMode(_ value: DisplayModes)` (swiftinterface:281); the `setMode(_ value: NSString)` string overload (swiftinterface:280) is DEPRECATED. There is no `LayoutMode`/`.tile`/`.sidebar` |
+| `CallLogsRequest` + `CallLogsBuilder` | Paginated call history (note the plural — there is no `CallLogRequest`/`CallLogRequestBuilder`) |
+| `CallsEventsDelegate` (protocol) | Lifecycle + media + participant + button events — set via `CallSettingsBuilder.setDelegate(_:)` or `CometChatCalls.addCallEventListener(observerId:delegate:)`. (NOT `CometChatCallsEventsListener` — that name doesn't exist.) |
 
 ### UI Kit views (additive mode — `CometChatUIKitSwift`)
 
 | View / VC | Purpose |
 |---|---|
-| `CometChatCallButton` | Voice + video button row (standalone or in `CometChatMessageHeader`) |
+| `CometChatCallButtons` | Voice + video button row (standalone or in `CometChatMessageHeader`) |
 | `CometChatIncomingCall` (UIViewController) | Foreground in-app ring UI |
 | `CometChatOutgoingCall` (UIViewController) | Dialing UI |
 | `CometChatOngoingCall` (UIViewController) | Active call UI hosting WebRTC |
@@ -333,11 +458,11 @@ When `product === "voice-video"` and there is no existing UI Kit.
 
 ### 4a. Standalone — Session mode (meeting-room UX, no ringing)
 
-Calls SDK ONLY. NO Chat SDK, NO CallKit, NO PushKit. Matches `~/Downloads/calls-sdk/calls-sdk-ios-5/sample-apps/cometchat-calls-sample-app-ios/`. Scaffold:
+Calls SDK ONLY. NO Chat SDK, NO CallKit, NO PushKit. Matches `calls-sdk-ios-5/sample-apps/cometchat-calls-sample-app-ios/`. Scaffold:
 
-1. **App entry** — `CometChatCalls.init({appId, region, authKey})` ONLY. No `CometChat.init`, no `CometChat.login`, no PushKit, no CallKit.
+1. **App entry** — `CometChatCalls.init(callsAppSettings:)` with a `CallAppSettingsBuilder().setAppId(...).setRegion(...).build()` ONLY. No `CometChat.init`, no `CometChat.login`, no PushKit, no CallKit.
 2. **`JoinSessionView.swift`** — UID picker + "Start meeting" / "Join meeting" + state.
-3. **`CallView.swift` + `CallContainerView: UIViewRepresentable`** — Single-call `CometChatCalls.joinSession(sessionID:callSetting:container:)`. Coordinator implements `SessionStatusListener` + `ButtonClickListener`. See `references/call-session.md`.
+3. **`CallView.swift` + `CallContainerView: UIViewRepresentable`** — `CometChatCalls.generateToken(authToken:sessionID:)` then `CometChatCalls.startSession(callToken:callSetting:view:)`. Coordinator conforms to `CallsEventsDelegate` (set via `CallSettingsBuilder.setDelegate`). See `references/call-session.md`.
 4. **`Info.plist` patch** — Camera + microphone permissions ONLY. No `audio` or `voip` Background Modes needed.
 5. **Universal Link routing** — meeting URL → CallView.
 
@@ -348,29 +473,33 @@ Calls SDK ONLY. NO Chat SDK, NO CallKit, NO PushKit. Matches `~/Downloads/calls-
 Dual-SDK + CallKit + PushKit. Scaffold:
 
 1. **App entry** — Chat SDK + Calls SDK init, PushKit + CallKit registration (rule 1.2, 1.7).
-2. **`CallKitProviderDelegate.swift`** — `CXProviderDelegate` implementation. Routes `CXAnswerCallAction` → `CometChatCalls.joinSession(sessionID:callSetting:container:)`. Routes `CXEndCallAction` → `CallSession.shared.leaveSession()` + `AVAudioSession` cleanup (rule 1.5).
+2. **`CallKitProviderDelegate.swift`** — `CXProviderDelegate` implementation. Routes `CXAnswerCallAction` → `CometChatCalls.generateToken` then `startSession(callToken:callSetting:view:)`. Routes `CXEndCallAction` → `CometChatCalls.endSession()` + `AVAudioSession` cleanup (rule 1.5).
 3. **`PushRegistryDelegate.swift`** — `PKPushRegistryDelegate` listening on `.voIP`. On payload → `CXProvider.reportNewIncomingCall` immediately.
 4. **`ProfileView.swift` (SwiftUI) or `ProfileViewController.swift` (UIKit)** — Hosts call buttons next to user info. Tap → `CometChat.initiateCall`.
 5. **`OngoingCallView.swift`** — Custom view hosting the SDK's call surface via `UIViewRepresentable` bridging. Implements rule 1.5 teardown.
-6. **`CallLogsView.swift`** — `/calls` equivalent — `CallLogRequest.CallLogRequestBuilder`.
+6. **`CallLogsView.swift`** — `/calls` equivalent — `CallLogsRequest.CallLogsBuilder`.
 7. **`Info.plist` patch** — Background Modes (rule 1.3), permissions (rule 1.6).
 8. **VoIP Services certificate setup** — manual step (Apple Developer portal + App Store Connect). The skill documents the steps; cannot automate.
 
 ## 5. Additive integration
 
-When `cometchat-ios` is already integrated. The skill:
+When `cometchat-ios` is already integrated.
+
+> ✅ **Kit-default path FIRST (what the canonical `SampleApp` actually does).** `CometChatCallsSDK` is **vendored inside `CometChatUIKitSwift`** — no separate SPM/Pod add, and **no separate `CometChatCalls.init`**. The sample turns calling on with **`UIKitSettings…enable(inAppIncomingCall: true)`** at init (`SampleApp/SceneDelegate.swift`), then just drops in `CometChatCallButtons(...).set(user:)` (e.g. in the user-details screen) and a `CometChatCallLogs` tab — the kit handles `generateToken`/`startSession` and the incoming-call UI internally. You do NOT hand-write `CometChatCalls.init` + a manual `generateToken → startSession` flow on this path. (The manual two-step is the **standalone / custom-UI** path only — §1.1 / §4.)
+
+The kit-default additive recipe:
+1. Confirm `CometChatUIKitSwift` is present (CallsSDK is bundled — nothing extra to install).
+2. Set **`.enable(inAppIncomingCall: true)`** on the `UIKitSettings` builder at init (the one calling switch).
+3. Add Background Modes (`voip`, `remote-notification`, `audio`) + camera/mic permissions to `Info.plist`.
+4. Drop in `CometChatCallButtons` (e.g. user-details / contact screen) — the kit also auto-renders them in `CometChatMessageHeader` when CallsSDK is present; add `CometChatCallLogs` as a tab/route.
+5. (Optional) CallKit + PushKit for background VoIP (asks user — same opt-in as Android).
 
-1. Adds `CometChatCallsSDK` to SPM or Podfile.
-2. Adds `CometChatCalls.init(...)` to the existing `CometChat.init` success callback.
-3. Adds Background Modes + permissions to `Info.plist`.
-4. Wires `CometChatMessageHeader` call buttons (already rendered by the kit — just enable them).
-5. Adds CallKit + PushKit (asks user — same opt-in as Android).
-6. Adds `CallLogsView` as an additional tab/route.
+Only reach for `CometChatCalls.init` + `generateToken`/`startSession` (§1.1) when building a **custom call surface** without the kit's call components.
 
 ## 6. Anti-patterns
 
 1. **Skipping CallKit + PushKit** in standalone mode. The app cannot ring backgrounded/terminated devices any other way. App Store reviewers test this.
-2. **Calling `CXProvider.reportNewIncomingCall` after async work.** Apple terminates the app process if the report happens more than ~5 seconds after PushKit delivery. Report immediately, then do the actual `joinSession` from inside `CXAnswerCallAction`.
+2. **Calling `CXProvider.reportNewIncomingCall` after async work.** Apple terminates the app process if the report happens more than ~5 seconds after PushKit delivery. Report immediately, then do the actual `generateToken` + `startSession` from inside `CXAnswerCallAction`.
 3. **Forgetting `setActive(false, options: .notifyOthersOnDeactivation)`** on hangup. Music/phone-call audio sounds wrong until the next foreground. The "looks fine in dev, fails review" bug.
 4. **Declaring `voip` in `UIBackgroundModes` without using PushKit.** Apple rejects.
 5. **Mixing CallKit and an in-app incoming-call screen** in standalone mode. Causes double-rings and confused state. CallKit owns standalone rings; in-app UI is additive-mode only.
@@ -402,6 +531,7 @@ When `cometchat-ios` is already integrated. The skill:
 
 ## 8. Pointers
 
+- `references/audio-modes-and-controls.md` — audio-route switching (speaker/earpiece/Bluetooth) + custom control panel (button-disable matrix)
 - `cometchat-ios-core` — Chat SDK init, login, `Secrets.swift` conventions
 - `cometchat-ios-components` — full UI Kit catalog (additive mode)
 - `cometchat-ios-push` — APNs setup; some overlap with PushKit but distinct (PushKit is VoIP-only)

package/skills/cometchat-ios-calls/references/add-calls-to-existing-chat.md

@@ -72,15 +72,17 @@ CometChatUIKit.init(uikitSettings: chatSettings) { result in
 
 ## Step 4 — Login
 
-After your existing login flow:
+Log in with the Chat SDK only. **There is no `CometChatCalls.login` and no `CometChat.loginAsync`** — the Calls SDK has no separate login step; it authenticates per call session via `generateToken`.
 
 ```swift
-let user = try await CometChat.loginAsync(uid: uid, authKey: authKey)
-let authToken = user.authToken
-try await CometChatCalls.login(authToken: authToken)
+CometChat.login(UID: uid, authKey: authKey, onSuccess: { user in
+  // logged in — that's it. Do NOT call CometChatCalls.login (doesn't exist).
+  // When a call starts, call CometChatCalls.generateToken(authToken:sessionID:)
+  // with CometChat.getUserAuthToken() (User has no `authToken` property).
+}, onError: { error in /* surface */ })
 ```
 
-If you use server-minted auth tokens (recommended), pass that token to both SDKs.
+If you use server-minted auth tokens (recommended), use the `CometChat.login(UID:authToken:...)` overload instead of `authKey`.
 
 ---
 
@@ -141,9 +143,9 @@ Init this handler from your `AppDelegate.didFinishLaunchingWithOptions`.
 ## Step 7 — Hangup teardown
 
 ```swift
-func endCall(sessionId: String) async {
-  CometChatCalls.leaveSession()
-  try? await CometChat.endCallAsync(sessionId: sessionId)
+func endCall(sessionId: String) {
+  CometChatCalls.endSession()   // Calls SDK — EXISTS (not leaveSession)
+  CometChat.endCall(sessionID: sessionId, onSuccess: { _ in }, onError: { _ in })
   callProvider.reportCall(with: callUUID, endedAt: nil, reason: .remoteEnded)
 }
 ```
@@ -156,7 +158,7 @@ func endCall(sessionId: String) async {
 - [ ] Background Modes capability + Info.plist UIBackgroundModes (audio + voip + remote-notification)
 - [ ] NSCameraUsageDescription + NSMicrophoneUsageDescription
 - [ ] Calls init runs AFTER chat init succeeds
-- [ ] `CometChatCalls.login` runs after chat login
+- [ ] NO `CometChatCalls.login` (doesn't exist) — Calls auth is per-session via `generateToken`
 - [ ] `CometChatIncomingCall` mounted at root (SwiftUI overlay or UIKit window-root)
 - [ ] PushKit registry initialized + reports to CallKit within 5s
 - [ ] Hangup teardown ends both SDK + CallKit + chat-side call record

package/skills/cometchat-ios-calls/references/audio-modes-and-controls.md

@@ -0,0 +1,45 @@
+# iOS — Audio Modes + Custom Control Panel
+
+Verified against `CometChatCallsSDK` 5.x (`callssdk.swiftinterface`).
+
+## 1. Audio modes (speaker / earpiece / Bluetooth)
+
+The SDK reports the available audio routes via the `CallsEventsDelegate` as typed `CallAudioMode` objects (swiftinterface:133 — `mode: String`, `isSelected: Bool`), and lets you switch programmatically by passing a `CallAudioMode`.
+
+```swift
+import CometChatCallsSDK
+
+// Observe available routes + current selection (typed form).
+// swiftinterface:44 onAudioModeChanged(mode: [CallAudioMode])
+func onAudioModeChanged(mode: [CallAudioMode]) {
+    self.audioRoutes = mode   // each has .mode (e.g. "SPEAKER") and .isSelected
+}
+
+// Switch route with a typed CallAudioMode — the current setter.
+// swiftinterface:234 CometChatCalls.setAudioMode(_ audioMode: CallAudioMode)
+CometChatCalls.setAudioMode(CallAudioMode(mode: "SPEAKER", isSelected: true))
+```
+
+Note the kit's default in-call UI already shows an audio-mode button; you only need the above for a **custom** control surface (or to drive routing yourself).
+
+Verified against `CometChatCallsSDK` swiftinterface: the typed `CallsEventsDelegate.onAudioModeChanged(mode: [CallAudioMode])` (swiftinterface:44) and `CometChatCalls.setAudioMode(_ audioMode: CallAudioMode)` (swiftinterface:234) are the CURRENT API. The string forms — `onAudioModeChanged(audioModeList: NSArray)` (swiftinterface:43) and `setAudioMode(mode: String)` (swiftinterface:235) — are DEPRECATED.
+
+## 2. Custom control panel (hide built-in buttons)
+
+There is no separate "panel" object — you compose a custom control bar by **disabling the kit's default buttons** on the `CallSettingsBuilder`, then rendering your own controls (wired to `audioMuted(_:)`, `videoPaused(_:)`, `switchCamera()`, `endSession()`, etc. from the main skill):
+
+```swift
+let settings = CallSettingsBuilder()
+  .setEndCallButtonDisable(true)
+  .setMuteAudioButtonDisable(true)
+  .setPauseVideoButtonDisable(true)
+  .setSwitchCameraButtonDisable(true)
+  .setAudioModeButtonDisable(true)
+  .setShowRecordingButton(false)
+  .build()
+// then overlay your own SwiftUI/UIKit control bar on the call container
+```
+
+Verified (on `CallSettingsBuilder`): `setEndCallButtonDisable`, `setMuteAudioButtonDisable`, `setPauseVideoButtonDisable`, `setSwitchCameraButtonDisable`, `setAudioModeButtonDisable`, `setShowRecordingButton` — all `(Bool) -> Self`.
+
+> **Not supported on iOS** (no SDK symbol — do not author): Virtual Background, and local screen-share **initiation** (receive-only). See the main skill's resolution note.

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

@@ -43,8 +43,7 @@ func configureForCall(isVideo: Bool) throws {
 
 ```swift
 func endCall() {
-  // CometChatCalls.endSession() does NOT exist on iOS — use leaveSession on CallSession.shared
-  CometChatCallsSDK.CallSession.shared.leaveSession()
+  CometChatCalls.endSession()   // EXISTS on the static facade in v5
 
   do {
     try AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
@@ -132,14 +131,14 @@ extension CallManager: CXProviderDelegate {
       options: [.allowBluetooth, .defaultToSpeaker]
     )
 
-    // Store sessionId; defer joinSession to didActivate
+    // Store sessionId; defer startSession to didActivate
     self.pendingActivation = pendingSessionIds[action.callUUID]
     action.fulfill()
   }
 }
 ```
 
-CallKit calls `setActive(true)` for you when it's done with its lock-screen UI. You call `joinSession` from `didActivate`.
+CallKit calls `setActive(true)` for you when it's done with its lock-screen UI. You call `startSession` (after `generateToken`) from `didActivate`.
 
 For non-CallKit-driven calls (outgoing from inside the app), you do `setActive(true)` yourself.
 
@@ -152,7 +151,7 @@ For non-CallKit-driven calls (outgoing from inside the app), you do `setActive(t
 | Music doesn't resume after call | Missing `.notifyOthersOnDeactivation` | Add to `setActive(false, ...)` call |
 | Voice call sounds quiet, like through phone receiver | Missing `.defaultToSpeaker` option | Add to `setCategory` options |
 | Bluetooth headphones not used during call | Missing `.allowBluetooth` option | Add to `setCategory` options |
-| CXAnswerCallAction races with `setActive(true)` | Manual `setActive(true)` in answer handler | Defer `joinSession` to `didActivate` |
+| CXAnswerCallAction races with `setActive(true)` | Manual `setActive(true)` in answer handler | Defer `startSession` to `didActivate` |
 | Echo / feedback during voice call | Wrong `mode` (e.g. `.default` instead of `.voiceChat`) | Use `.voiceChat` or `.videoChat` |
 | Call audio works in foreground but cuts in background | UIBackgroundModes missing `audio` | Add `audio` to `Info.plist` UIBackgroundModes |
 
@@ -175,10 +174,10 @@ NotificationCenter.default.addObserver(
   switch type {
   case .began:
     // Phone call started — pause our call's audio (CallKit may auto-handle this for you)
-    CometChatCalls.muteAudio(true)
+    CometChatCalls.audioMuted(true)   // NOT muteAudio
   case .ended:
     // Phone call ended — resume
-    CometChatCalls.muteAudio(false)
+    CometChatCalls.audioMuted(false)
     try? AVAudioSession.sharedInstance().setActive(true)
   @unknown default:
     break