@cometchat/skills 4.3.0 → 4.4.0

package/skills/cometchat-ios-calls/references/call-layouts.md

@@ -1,9 +1,8 @@
 # Call layouts on iOS
 
-Same three layouts (TILE/SIDEBAR/SPOTLIGHT). iOS-specific: `UISegmentedControl` is the native pattern for the switcher; layout selection persists across the app via `UserDefaults`.
+The iOS Calls SDK v5 exposes layout via the `DisplayModes` enum (swiftinterface:175 — `.default` / `.single` / `.spotlight`), passed ONCE at session start via `CallSettingsBuilder.setMode(_:)`. The current setter is `setMode(_ value: DisplayModes) -> Self` (swiftinterface:281); the `setMode(_ value: NSString)` string overload (swiftinterface:280) is DEPRECATED — prefer the typed enum. There is no `CallLayout` type, no runtime `setLayout`, no `setHideChangeLayoutButton`, and no `onCallLayoutChanged` callback. To change layout you must end and restart the session with a different `setMode`.
 
 **Canonical docs:** https://www.cometchat.com/docs/calls/ios/call-layouts
-**Read first:** `cometchat-react-calls/references/call-layouts.md` — layout matrix.
 
 ---
 
@@ -13,124 +12,65 @@ Same three layouts (TILE/SIDEBAR/SPOTLIGHT). iOS-specific: `UISegmentedControl`
 import CometChatCallsSDK
 
 let settings = CallSettingsBuilder()
-  .setSessionType(.video)
-  .setLayout(.tile)        // .tile | .sidebar | .spotlight
-  .setHideChangeLayoutButton(false)
+  .setIsAudioOnly(false)
+  .setMode(.default)         // swiftinterface:281 setMode(_ value: DisplayModes) -> Self
   .build()
-
-// Mid-call switch
-CometChatCalls.setLayout(.spotlight)
-
-// Listen
-class CallEvents: CometChatCallsEventsListener {
-  func onCallLayoutChanged(layout: CallLayout) {
-    DispatchQueue.main.async {
-      // Update UI
-    }
-  }
-}
 ```
 
----
-
-## SwiftUI switcher
+`setMode` takes a `DisplayModes` value:
 
-```swift
-import SwiftUI
-
-enum CallLayoutPicker: String, CaseIterable, Identifiable {
-  case tile = "Tile"
-  case sidebar = "Sidebar"
-  case spotlight = "Spotlight"
-  var id: String { rawValue }
-
-  var sdkLayout: CallLayout {
-    switch self {
-    case .tile: return .tile
-    case .sidebar: return .sidebar
-    case .spotlight: return .spotlight
-    }
-  }
-}
-
-struct LayoutSwitcher: View {
-  @State private var selection: CallLayoutPicker = .tile
-
-  var body: some View {
-    Picker("Layout", selection: $selection) {
-      ForEach(CallLayoutPicker.allCases) { opt in
-        Text(opt.rawValue).tag(opt)
-      }
-    }
-    .pickerStyle(.segmented)
-    .accessibilityLabel("Call layout")
-    .onChange(of: selection) { _, new in
-      CometChatCalls.setLayout(new.sdkLayout)
-    }
-  }
-}
-```
+| Value | Meaning |
+|---|---|
+| `.default` | Standard grid of participant tiles |
+| `.single` | One participant fills the surface |
+| `.spotlight` | Active speaker enlarged, others as a strip |
 
-`Picker(.segmented)` renders as `UISegmentedControl`, which is the iOS-native expected pattern for radio-group selection.
+> **There is no runtime layout switch.** `CometChatCalls` has no `setLayout`/`setMode` instance/static method that re-lays-out a live session. `setMode(_:)` exists only on `CallSettingsBuilder` and only takes effect at `startSession`. If you need to offer a switcher, tear down and restart the session with new settings (expensive — most apps just pick one mode).
 
 ---
 
-## Persisting the user's preference
+## Picking a layout at session start
 
 ```swift
-extension UserDefaults {
-  var preferredCallLayout: CallLayout {
-    get {
-      switch string(forKey: "preferredCallLayout") {
-      case "sidebar": return .sidebar
-      case "spotlight": return .spotlight
-      default: return .tile
-      }
-    }
-    set {
-      let str: String = {
-        switch newValue {
-        case .tile: return "tile"
-        case .sidebar: return "sidebar"
-        case .spotlight: return "spotlight"
-        @unknown default: return "tile"
-        }
-      }()
-      set(str, forKey: "preferredCallLayout")
-    }
+// Read a persisted preference and map it to a DisplayModes value before startSession:
+let stored = UserDefaults.standard.string(forKey: "preferredDisplayMode") ?? "default"
+let mode: DisplayModes = {
+  switch stored {
+  case "single":    return .single
+  case "spotlight": return .spotlight
+  default:          return .default
   }
-}
-
-// In your CallViewController:
+}()
 let settings = CallSettingsBuilder()
-  .setLayout(UserDefaults.standard.preferredCallLayout)
+  .setMode(mode)
   .build()
+// ... generateToken → startSession(callToken:callSetting:view:) ...
 ```
 
+A SwiftUI `Picker(.segmented)` over the three modes is a fine way to capture the preference BEFORE the call starts (on a pre-join screen). It cannot drive a live re-layout.
+
 ---
 
 ## Anti-patterns
 
-Web sister rules apply, plus iOS-specific:
-
-1. **`Picker(.menu)` instead of `.segmented`.** Wrong UX — menu hides the options, segmented shows them. For 3 options, segmented is the iOS norm.
-2. **`onChange` on background queue.** Crash. SwiftUI's `onChange` is on main but if you bridge through Combine make sure to `.receive(on: DispatchQueue.main)`.
-3. **Forgetting to `.accessibilityLabel`.** VoiceOver announces "Picker" with no context.
+1. **`CallLayout` / `.tile` / `.sidebar`.** Don't exist on iOS v5. `setMode` takes a `DisplayModes` value (`.default`/`.single`/`.spotlight`, swiftinterface:175). The deprecated `setMode(_ value: NSString)` string overload still exists but prefer the typed enum.
+2. **`CometChatCalls.setLayout(...)` mid-call.** No such method. Layout is fixed at `startSession`.
+3. **Implementing `onCallLayoutChanged` on the delegate.** Not a callback on `CallsEventsDelegate`. There is no layout-change event.
+4. **`setHideChangeLayoutButton(_:)`.** Not a `CallSettingsBuilder` method.
 
 ---
 
 ## Verification checklist
 
-- [ ] Initial layout via `setLayout` on builder
-- [ ] SwiftUI `Picker(.segmented)` for switcher
-- [ ] Layout listener implemented in `CometChatCallsEventsListener`
+- [ ] Layout set via `CallSettingsBuilder.setMode(_:)` with a `DisplayModes` value (`.default`/`.single`/`.spotlight`)
+- [ ] No `CallLayout`, `.tile`, `.sidebar`, `setLayout`, `onCallLayoutChanged`, or `setHideChangeLayoutButton` anywhere
+- [ ] Any preference UI captured BEFORE `startSession` (no live switch attempted)
 - [ ] User preference persisted via `UserDefaults` if desired
-- [ ] Real-device smoke: switcher cycles all 3, persists across calls
 
 ---
 
 ## Pointers
 
-- `cometchat-react-calls/references/call-layouts.md` — sister
+- `cometchat-react-calls/references/call-layouts.md` — sister (web exposes more layout control)
 - `cometchat-ios-calls` SKILL.md
 - Canonical docs: https://www.cometchat.com/docs/calls/ios/call-layouts

package/skills/cometchat-ios-calls/references/call-session.md

@@ -1,6 +1,6 @@
-# Call session — joinSession with no ringing (iOS)
+# Call session — no ringing (iOS)
 
-Server-generated sessionId, both parties enter it. Customer-validated against `~/Downloads/calls-sdk/calls-sdk-ios-5/sample-apps/cometchat-calls-sample-app-ios/CometChatCallsSample/CallView.swift`.
+Server-generated sessionId, both parties enter it. Customer-validated against `calls-sdk-ios-5/sample-apps/cometchat-calls-sample-app-ios/CometChatCallsSample/CallView.swift`.
 
 **Read first:** `cometchat-react-calls/references/call-session.md` — cross-platform architecture (sessionId strategies, server-side authorization). Then come back here for the iOS shape.
 
@@ -10,10 +10,10 @@ Server-generated sessionId, both parties enter it. Customer-validated against `~
 
 ## Hard rules (iOS-specific overrides on top of the cross-platform rules)
 
-1. **Use the `joinSession(sessionID:callSetting:container:onSuccess:onError:)` convenience method.** It handles token generation internally — you do NOT need to call `generateToken` separately. Matches the upstream sample exactly.
-2. **`SessionSettingsBuilder()` is the canonical settings shape** (chained `.setTitle().startVideoPaused(false).startAudioMuted(false).build()`). NOT `SessionSettings(sessionType:layout:)` — that initializer is the chat-side type.
-3. **`SessionStatusListener` protocol on a Coordinator object**, registered against `CometChatCallsSDK.CallSession.shared.addSessionStatusListener(...)`. NOT raw `CometChatCalls.addEventListener(.sessionLeft)` — that does not exist on iOS.
-4. **`onSessionLeft`, `onConnectionClosed`, `onSessionTimedOut` all trigger UI dismiss.** All three are real termination paths; ignoring any of them leaves the call view stranded.
+1. **Two-step session start: `generateToken` then `startSession`.** `CometChatCalls.generateToken(authToken:sessionID:onSuccess:onError:)` returns a call token; pass it to `CometChatCalls.startSession(callToken:callSetting:view:onSuccess:onError:)`. There is NO `joinSession` convenience method on the iOS Calls SDK v5.
+2. **`CallSettingsBuilder()` is the canonical settings shape** (chained `.setIsAudioOnly(false).setStartVideoMuted(false).setStartAudioMuted(false).setDelegate(coordinator).build()`). There is NO `SessionSettings` or `SessionSettingsBuilder` type.
+3. **`CallsEventsDelegate` protocol on a Coordinator object**, set via `CallSettingsBuilder.setDelegate(_:)` or registered with `CometChatCalls.addCallEventListener(observerId:delegate:)`. There is NO `SessionStatusListener`, NO `ButtonClickListener`, NO `CometChatCallsEventsListener`, and NO `addEventListener(.sessionLeft)`.
+4. **`onCallEnded` and `onCallEndButtonPressed` trigger UI dismiss.** These are the real termination callbacks; ignoring either leaves the call view stranded. `CallsEventsDelegate` ALSO has an optional `onSessionTimeout()` callback (swiftinterface:30) that fires when the idle timeout set via `CallSettingsBuilder.setIdleTimeoutPeriod(_:)` elapses — handle it for dismiss/cleanup too. See `references/idle-timeout.md`.
 5. **For standalone session-only integrations, the Chat SDK is OPTIONAL.** The upstream iOS sample never imports `CometChatSDK` (the chat SDK). Keep `CometChat.init` / `CometChat.login` only for additive (chat + calls) integrations.
 6. **`AVAudioSession` activated with `.playAndRecord` + `.voiceChat`** — `.playback` mode captures NO mic input.
 
@@ -71,58 +71,55 @@ struct CallContainerView: UIViewRepresentable {
     }
 
     private func startSession(container: UIView, coordinator: Coordinator) {
-        let settings = SessionSettingsBuilder()
-            .setTitle("CometChat Meeting")
-            .startVideoPaused(false)
-            .startAudioMuted(false)
+        let settings = CallSettingsBuilder()
+            .setIsAudioOnly(false)
+            .setStartVideoMuted(false)
+            .setStartAudioMuted(false)
+            .setDelegate(coordinator)        // CallsEventsDelegate — set here, on the builder
             .build()
 
-        // The convenience joinSession(sessionID:) generates the token internally.
-        // No separate generateToken call needed.
-        CometChatCalls.joinSession(
-            sessionID: sessionID,
-            callSetting: settings,
-            container: container
-        ) { success in
-            let session = CometChatCallsSDK.CallSession.shared
-            session.addSessionStatusListener(coordinator)
-            session.addButtonClickListener(coordinator)
+        // Two-step: generateToken THEN startSession. There is no joinSession convenience.
+        // authToken is nil for session-only apps (Calls SDK derives it server-side from the
+        // session); pass CometChat.getUserAuthToken() in additive (chat + calls) integrations.
+        CometChatCalls.generateToken(authToken: nil, sessionID: sessionID) { token in
+            guard let token = token else {
+                DispatchQueue.main.async { onError("Failed to generate call token") }
+                return
+            }
+            CometChatCalls.startSession(
+                callToken: token,
+                callSetting: settings,
+                view: container
+            ) { _ in
+                // session started — delegate already wired via setDelegate
+            } onError: { error in
+                DispatchQueue.main.async {
+                    onError(error?.errorDescription ?? "Failed to start call")
+                }
+            }
         } onError: { error in
             DispatchQueue.main.async {
-                onError(error?.errorDescription ?? "Failed to join call")
+                onError(error?.errorDescription ?? "Failed to generate call token")
             }
         }
     }
 
-    class Coordinator: NSObject, SessionStatusListener, ButtonClickListener {
+    class Coordinator: NSObject, CallsEventsDelegate {
         let onEnd: () -> Void
 
         init(onEnd: @escaping () -> Void) {
             self.onEnd = onEnd
         }
 
-        // --- SessionStatusListener ---
-        func onSessionJoined() {}
-
-        func onSessionLeft() {
+        // --- CallsEventsDelegate (all @objc optional) ---
+        func onCallEnded() {
             DispatchQueue.main.async { self.onEnd() }
         }
 
-        func onConnectionClosed() {
+        func onCallEndButtonPressed() {
+            CometChatCalls.endSession()           // EXISTS on the static facade
             DispatchQueue.main.async { self.onEnd() }
         }
-
-        func onSessionTimedOut() {
-            DispatchQueue.main.async { self.onEnd() }
-        }
-
-        func onConnectionLost() {}
-        func onConnectionRestored() {}
-
-        // --- ButtonClickListener ---
-        func onLeaveSessionButtonClicked() {
-            CometChatCallsSDK.CallSession.shared.leaveSession()
-        }
     }
 }
 ```
@@ -130,9 +127,9 @@ struct CallContainerView: UIViewRepresentable {
 **Why this shape:**
 
 - **`UIViewRepresentable` bridging a `UIView` container**, not a raw SwiftUI view — the SDK draws into a `UIView` it owns and lays out internally. SwiftUI can't host that directly.
-- **`joinSession(sessionID:callSetting:container:)` convenience** — generates the call token internally. No need for `CometChatCalls.generateToken(forSession:)` then `joinSession(callToken:)` two-step. The sample uses this and so should every customer.
-- **`SessionSettingsBuilder().build()`** — chained builder ending in `.build()`. The non-builder `SessionSettings(sessionType:layout:)` is the chat-side type and rejects at runtime.
-- **`Coordinator` implements `SessionStatusListener` AND `ButtonClickListener`** — register both against `CallSession.shared` AFTER `onSuccess` fires. Don't register against `CometChatCalls` — that's not where the events live.
+- **`generateToken` then `startSession`** — the iOS Calls SDK v5 has no single-call `joinSession`. Generate the call token, then start the session into the container `UIView`.
+- **`CallSettingsBuilder().build()`** — chained builder ending in `.build()` returning `CallSettings`. There is no `SessionSettings`/`SessionSettingsBuilder` type.
+- **`Coordinator` implements `CallsEventsDelegate`** — wired via `setDelegate(_:)` on the builder. There is no `SessionStatusListener`/`ButtonClickListener`; do not register against `CallSession.shared` (it doesn't exist).
 
 ---
 
@@ -184,24 +181,24 @@ Configure `applinks:yourapp.com` per `references/share-invite.md`.
 
 ## Anti-patterns
 
-1. **Calling `CometChatCalls.generateToken(forSession:)` then `joinSession(callToken:)`.** Two-step doesn't match the sample — the sample uses the single-call `joinSession(sessionID:)` convenience. Prior versions of this skill cited the two-step; it works but is not the canonical iOS shape.
-2. **`SessionSettings(sessionType:layout:)` initializer.** Wrong type — that's the chat-side entity. Use `SessionSettingsBuilder()...build()`.
-3. **`CometChatCalls.addEventListener(.sessionLeft)`** — iOS uses the protocol-based `SessionStatusListener`, not a string-keyed listener API.
-4. **Skipping `onConnectionClosed` and `onSessionTimedOut` callbacks.** User's call ends via either of these (network drop, server timeout) → call view stays mounted forever.
-5. **Calling `joinSession` from `viewDidAppear`.** Re-runs on every navigation push. Use `viewDidLoad` + a `joined` flag, OR use `UIViewRepresentable` + Coordinator (the sample's pattern).
+1. **Looking for a single-call `joinSession(sessionID:)` convenience.** It does not exist on iOS v5. Always do `generateToken` → `startSession`.
+2. **`SessionSettings` / `SessionSettingsBuilder`.** Neither type exists. Use `CallSettingsBuilder()...build()`.
+3. **`CometChatCalls.addEventListener(.sessionLeft)` or `SessionStatusListener`/`ButtonClickListener`.** None exist. iOS uses the `CallsEventsDelegate` protocol set via `setDelegate(_:)` or `addCallEventListener(observerId:delegate:)`.
+4. **Skipping the `onCallEnded` callback.** The call ends via this (remote hangup, server end) → call view stays mounted forever. (For idle-timeout termination, also handle `onSessionTimeout()` — swiftinterface:30.)
+5. **Starting the session from `viewDidAppear`.** Re-runs on every navigation push. Use `viewDidLoad` + a `started` flag, OR use `UIViewRepresentable` + Coordinator (the pattern above).
 6. **`AVAudioSession.setCategory(.playback)`.** Mic input doesn't capture. Use `.playAndRecord` + `.voiceChat` mode.
-7. **`async/await` on `joinSession`.** It returns void with completion handlers — `try await` does nothing.
+7. **`async/await` on `startSession`/`generateToken`.** They use completion handlers — `try await` does nothing.
 8. **Initializing Chat SDK for a session-only integration.** Wastes time and adds two extra failure modes. Drop `CometChat.init` / `CometChat.login` entirely for standalone session apps.
 
 ---
 
 ## Verification checklist
 
-- [ ] `joinSession(sessionID:callSetting:container:)` used (single-call), NOT `generateToken` + `joinSession(callToken:)` two-step
-- [ ] Settings built via `SessionSettingsBuilder()`, not `SessionSettings(sessionType:layout:)`
-- [ ] `SessionStatusListener` protocol implemented on a Coordinator class
-- [ ] Coordinator registered via `CallSession.shared.addSessionStatusListener(...)` AFTER `onSuccess`
-- [ ] `onSessionLeft`, `onConnectionClosed`, `onSessionTimedOut` ALL trigger dismiss
+- [ ] `generateToken(authToken:sessionID:)` → `startSession(callToken:callSetting:view:)` two-step (no `joinSession`)
+- [ ] Settings built via `CallSettingsBuilder()`, not `SessionSettings`/`SessionSettingsBuilder`
+- [ ] `CallsEventsDelegate` protocol implemented on a Coordinator class
+- [ ] Coordinator wired via `CallSettingsBuilder.setDelegate(_:)` (or `addCallEventListener(observerId:delegate:)`)
+- [ ] `onCallEnded` and `onCallEndButtonPressed` both trigger dismiss
 - [ ] `Info.plist` has `NSCameraUsageDescription`, `NSMicrophoneUsageDescription`, `UIBackgroundModes: audio, voip`
 - [ ] `AVAudioSession.setCategory(.playAndRecord, mode: .voiceChat, ...)`
 - [ ] Universal Link routing wired in SceneDelegate
@@ -217,5 +214,5 @@ Configure `applinks:yourapp.com` per `references/share-invite.md`.
 - `cometchat-ios-calls/SKILL.md` — iOS seven hard rules
 - `cometchat-ios-calls/references/share-invite.md` — Universal Link config
 - `cometchat-ios-calls/references/avaudiosession-routing.md` — audio session routing
-- Upstream iOS sample — `~/Downloads/calls-sdk/calls-sdk-ios-5/sample-apps/cometchat-calls-sample-app-ios/CometChatCallsSample/CallView.swift`
+- Upstream iOS sample — `calls-sdk-ios-5/sample-apps/cometchat-calls-sample-app-ios/CometChatCallsSample/CallView.swift`
 - Canonical docs: https://www.cometchat.com/docs/calls/ios/join-session

package/skills/cometchat-ios-calls/references/callkit-and-pushkit.md

@@ -76,7 +76,7 @@ struct YourApp: App {
         .onAppear {
           CometChat.init(appId: Secrets.cometchatAppID, appSettings: appSettings) { isInitialized, error in
             guard error == nil else { return }
-            CometChatCalls.init(callAppSettings: callAppSettings) { _ in
+            CometChatCalls.init(callsAppSettings: callAppSettings) { _ in
               callManager.registerForPushKit()                     // wait for SDK ready
             }
           }
@@ -98,7 +98,7 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
   func application(_ app: UIApplication, didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
     CometChat.init(appId: Secrets.cometchatAppID, appSettings: appSettings) { _, error in
       guard error == nil else { return }
-      CometChatCalls.init(callAppSettings: callAppSettings) { _ in
+      CometChatCalls.init(callsAppSettings: callAppSettings) { _ in
         CallManager.shared.registerForPushKit()
       }
     }
@@ -227,30 +227,35 @@ extension CallManager: CXProviderDelegate {
         try AVAudioSession.sharedInstance().setCategory(.playAndRecord, mode: .voiceChat)
         try AVAudioSession.sharedInstance().setActive(true)
 
-        // Build session settings via SessionSettingsBuilder (matches upstream
-        // ringing sample at calls-sdk-ios-5/sample-apps/cometchat-calls-sample-
-        // app-ringing-ios/CometChatCallsRinging/CallView.swift).
-        let settings = SessionSettingsBuilder()
-          .setTitle("CometChat Call")
-          .startVideoPaused(false)
-          .startAudioMuted(false)
+        // Build session settings via CallSettingsBuilder. The CallsEventsDelegate
+        // is wired with setDelegate(_:); there is no SessionSettings(Builder).
+        let settings = CallSettingsBuilder()
+          .setIsAudioOnly(false)
+          .setStartVideoMuted(false)
+          .setStartAudioMuted(false)
+          .setDelegate(callListener)        // callListener conforms to CallsEventsDelegate
           .build()
 
-        // Single-call joinSession(sessionID:callSetting:container:) — the SDK
-        // generates the token internally. Do NOT call generateToken separately.
-        // Container is the UIView the ongoing-call UI will be drawn into.
-        CometChatCalls.joinSession(
-          sessionID: sessionId,
-          callSetting: settings,
-          container: callContainerView   // a UIView with measurable bounds
-        ) { success in
-          // Register listeners on the resulting CallSession AFTER onSuccess
-          let session = CometChatCallsSDK.CallSession.shared
-          session.addSessionStatusListener(callListener)
-          session.addButtonClickListener(callListener)
-          action.fulfill()                  // tell CallKit we answered successfully
+        // Two-step: generateToken THEN startSession. There is no joinSession.
+        // `view` is the UIView the ongoing-call UI will be drawn into.
+        CometChatCalls.generateToken(authToken: CometChat.getUserAuthToken(), sessionID: sessionId) { token in
+          guard let token = token else {
+            print("generateToken returned nil")
+            action.fail()
+            return
+          }
+          CometChatCalls.startSession(
+            callToken: token,
+            callSetting: settings,
+            view: callContainerView   // a UIView with measurable bounds
+          ) { _ in
+            action.fulfill()                // tell CallKit we answered successfully
+          } onError: { error in
+            print("startSession failed: \(error?.errorDescription ?? "unknown")")
+            action.fail()
+          }
         } onError: { error in
-          print("joinSession failed: \(error?.errorDescription ?? "unknown")")
+          print("generateToken failed: \(error?.errorDescription ?? "unknown")")
           action.fail()
         }
 
@@ -266,9 +271,7 @@ extension CallManager: CXProviderDelegate {
 
   func provider(_ provider: CXProvider, perform action: CXEndCallAction) {
     // User tapped "End" or call ended remotely.
-    // Use CallSession.shared.leaveSession() — `CometChatCalls.endSession()`
-    // doesn't exist on iOS (matches upstream ringing sample).
-    CometChatCallsSDK.CallSession.shared.leaveSession()
+    CometChatCalls.endSession()   // EXISTS on the static facade in v5
 
     // CRITICAL: deactivate audio session (rule 1.5)
     do {
@@ -282,7 +285,7 @@ extension CallManager: CXProviderDelegate {
   }
 
   func provider(_ provider: CXProvider, perform action: CXSetMutedCallAction) {
-    CometChatCalls.muteAudio(action.isMuted)
+    CometChatCalls.audioMuted(action.isMuted)   // NOT muteAudio
     action.fulfill()
   }
 }
@@ -316,8 +319,9 @@ extension CallManager {
   func provider(_ provider: CXProvider, perform action: CXStartCallAction) {
     Task {
       do {
-        let outgoing = Call(receiverUid: action.handle.value, receiverType: .user,
-                           callType: action.isVideo ? .video : .voice)
+        let outgoing = Call(receiverId: action.handle.value,
+                           callType: action.isVideo ? .video : .audio,   // CallType has no .voice
+                           receiverType: .user)
         let initiated = try await CometChat.initiateCall(call: outgoing)
         pendingSessionIds[action.callUUID] = initiated.sessionID
         provider.reportOutgoingCall(with: action.callUUID, startedConnectingAt: nil)

package/skills/cometchat-ios-calls/references/custom-ui.md

@@ -7,7 +7,7 @@ Same shape as the other families' custom-ui references. iOS-specific because of
 ## Two paths
 
 1. **Style the kit's `CometChatOngoingCall`** UIViewController via theming + property overrides. Cheapest. Covers most apps.
-2. **Build your own UIViewController on the SDK** — direct `CometChatCalls.joinSession` with your own UIView containers. Maximum control.
+2. **Build your own UIViewController on the SDK** — direct `CometChatCalls.generateToken` → `startSession` with your own UIView container. Maximum control.
 
 This reference covers path 2.
 
@@ -42,7 +42,8 @@ class CustomOngoingCallViewController: UIViewController {
 
   private let sessionID: String
   private let isAudioOnly: Bool
-  private var listener: CometChatCallsEventsListener?
+  private var muted = false
+  private var cameraOff = false
 
   init(sessionID: String, isAudioOnly: Bool) {
     self.sessionID = sessionID
@@ -66,35 +67,35 @@ class CustomOngoingCallViewController: UIViewController {
   }
 
   private func startCall() {
-    listener = self
-    // Build SessionSettings — match upstream sample shape.
-    // For custom UI, you typically build your own controls and just need the SDK
-    // to feed video tiles into your container. enableDefaultLayout is not part
-    // of SessionSettings — disable individual default-UI elements via the
-    // hide* setters on SessionSettingsBuilder if you want a minimal surface.
-    let settings = SessionSettingsBuilder()
-      .setTitle(isAudioOnly ? "Voice Call" : "Video Call")
-      .startVideoPaused(isAudioOnly)
-      .startAudioMuted(false)
+    // Build CallSettings via CallSettingsBuilder. The CallsEventsDelegate is
+    // wired with setDelegate(_:); there is no SessionSettings/SessionSettingsBuilder.
+    let settings = CallSettingsBuilder()
+      .setIsAudioOnly(isAudioOnly)
+      .setStartVideoMuted(isAudioOnly)
+      .setStartAudioMuted(false)
+      .setDelegate(self)
       .build()
 
-    // Configure audio session BEFORE joining
+    // Configure audio session BEFORE starting
     try? configureAudioSession()
 
-    // Single-call joinSession(sessionID:callSetting:container:) — the SDK
-    // generates the token internally. NO separate generateToken call.
-    CometChatCalls.joinSession(
-      sessionID: sessionID,
-      callSetting: settings,
-      container: containerView
-    ) { [weak self] success in
-      guard let self = self else { return }
-      // Register listeners on the resulting CallSession AFTER onSuccess.
-      let session = CometChatCallsSDK.CallSession.shared
-      session.addSessionStatusListener(self.listener)
-      session.addButtonClickListener(self.listener)
+    // Two-step: generateToken THEN startSession into your container UIView.
+    // There is no single-call joinSession on the iOS Calls SDK v5.
+    // authToken: pass CometChat.getUserAuthToken() in additive (chat + calls)
+    // integrations; nil for session-only apps.
+    CometChatCalls.generateToken(authToken: nil, sessionID: sessionID) { [weak self] token in
+      guard let self = self, let token = token else { return }
+      CometChatCalls.startSession(
+        callToken: token,
+        callSetting: settings,
+        view: self.containerView
+      ) { _ in
+        // session started — delegate already wired via setDelegate
+      } onError: { error in
+        print("startSession failed: \(error?.errorDescription ?? "unknown")")
+      }
     } onError: { error in
-      print("joinSession failed: \(error?.errorDescription ?? "unknown")")
+      print("generateToken failed: \(error?.errorDescription ?? "unknown")")
     }
   }
 
@@ -109,8 +110,7 @@ class CustomOngoingCallViewController: UIViewController {
   }
 
   private func cleanup() {
-    // CometChatCalls.endSession() does NOT exist on iOS — use CallSession.shared.leaveSession()
-    CometChatCallsSDK.CallSession.shared.leaveSession()
+    CometChatCalls.endSession()   // EXISTS on the static facade in v5
     try? AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
   }
 
@@ -142,7 +142,7 @@ class CustomOngoingCallViewController: UIViewController {
   }
 }
 
-extension CustomOngoingCallViewController: CometChatCallsEventsListener {
+extension CustomOngoingCallViewController: CallsEventsDelegate {
   func onCallEnded() {
     DispatchQueue.main.async { [weak self] in
       self?.cleanup()
@@ -150,15 +150,15 @@ extension CustomOngoingCallViewController: CometChatCallsEventsListener {
     }
   }
 
-  func onUserListUpdated(_ users: [Any]) {
+  // swiftinterface: onUserListChanged(userList: NSArray) — payload is NSArray of [String: Any]
+  func onUserListChanged(userList: NSArray) {
     DispatchQueue.main.async { [weak self] in
-      self?.statusLabel.text = "\(users.count) participants"
+      self?.statusLabel.text = "\(userList.count) participants"
     }
   }
 
-  func onError(_ error: Error) {
-    print("Call error: \(error)")
-  }
+  // Note: CallsEventsDelegate has no onError callback. Surface generateToken /
+  // startSession failures from their onError closures (see startCall above).
 }
 ```
 
@@ -222,12 +222,12 @@ override func viewDidLoad() {
   controlPanel.onMute = { [weak self] in
     guard let self = self else { return }
     self.muted.toggle()
-    CometChatCalls.muteAudio(self.muted)
+    CometChatCalls.audioMuted(self.muted)   // NOT muteAudio
   }
   controlPanel.onCamera = { [weak self] in
     guard let self = self else { return }
     self.cameraOff.toggle()
-    CometChatCalls.pauseVideo(self.cameraOff)
+    CometChatCalls.videoPaused(self.cameraOff)   // NOT pauseVideo
   }
   controlPanel.onSwitch = { CometChatCalls.switchCamera() }
   controlPanel.onEnd = { [weak self] in
@@ -265,7 +265,7 @@ private func stopLocalPreview() {
 }
 ```
 
-Stop the preview BEFORE `joinSession` — the SDK takes over the camera and your `AVCaptureSession` will fight with it.
+Stop the preview BEFORE `startSession` — the SDK takes over the camera and your `AVCaptureSession` will fight with it.
 
 ---
 
@@ -311,7 +311,7 @@ class CustomOngoingCallViewController {
 }
 ```
 
-Setting up PiP for WebRTC video is involved — the SDK doesn't expose a `CMSampleBuffer` stream directly. For most apps, `enableDefaultLayout(true)` and let the kit's PiP work; custom UI authors who need PiP can use `CometChatPictureInPicture` (kit class) as a hybrid — kit's PiP, custom rest of UI.
+Setting up your own `AVPictureInPictureController` for WebRTC video is involved — the SDK doesn't expose a `CMSampleBuffer` stream directly. For most apps, use the Calls SDK's built-in PiP instead: `CometChatCalls.enterPIPMode()` / `CometChatCalls.exitPIPMode()` toggle the SDK-managed picture-in-picture for the session view. See `references/picture-in-picture.md`.
 
 ---