@cometchat/skills 4.4.2 → 5.0.1

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

@@ -1,181 +0,0 @@
-# Adding calls to an existing chat integration (iOS)
-
-You have `CometChatUIKitSwift` working. This guide adds `CometChatCallsSDK` plus PushKit + CallKit + the seven hard rules.
-
-**Read first:** `cometchat-ios-calls/SKILL.md` — seven hard rules (init order, IncomingCall mount, hangup teardown, VoIP push, etc.).
-
----
-
-## Step 1 — Install Calls SDK
-
-**SwiftPM:**
-- File → Add Packages → `https://github.com/cometchat/calls-sdk-ios` → version `5.0.0+`
-- Add `CometChatCallsSDK` to your app target
-
-**CocoaPods:**
-```ruby
-pod 'CometChatCallsSDK', '~> 5.0'
-```
-```bash
-pod install --repo-update
-```
-
----
-
-## Step 2 — Add capabilities + Info.plist entries
-
-**Xcode → target → Signing & Capabilities:**
-- Push Notifications
-- Background Modes → check Audio, AirPlay, and Picture in Picture + Voice over IP + Remote notifications
-
-**Info.plist:**
-```xml
-<key>UIBackgroundModes</key>
-<array>
-  <string>audio</string>
-  <string>voip</string>
-  <string>remote-notification</string>
-</array>
-<key>NSCameraUsageDescription</key>
-<string>Camera access is required for video calls.</string>
-<key>NSMicrophoneUsageDescription</key>
-<string>Microphone access is required for calls.</string>
-```
-
----
-
-## Step 3 — Init order: chat → calls
-
-Wherever you currently call `CometChatUIKit.init(uikitSettings:)`, append the calls init:
-
-```swift
-import CometChatSDK
-import CometChatCallsSDK
-import CometChatUIKitSwift
-
-// Existing chat init
-CometChatUIKit.init(uikitSettings: chatSettings) { result in
-  switch result {
-  case .success:
-    // NEW: Calls init AFTER chat init succeeded.
-    // File-based init (CometChatCallsSDK >= 5.0.2 — requires iOS 15.1+ deployment
-    // target or CocoaPods silently resolves 5.0.1 without this API):
-    // reads the same bundled cometchat-settings.json the chat side uses and
-    // attributes the integration as ai-agent — see cometchat-ios-calls SKILL.md §2.
-    CometChatCalls.initFromSettings(onSuccess: { _ in
-      // calls ready
-    }, onError: { error in
-      print("CometChatCalls init failed: \(error?.errorDescription ?? "")")
-    })
-    // Pre-5.0.2 fallback: CallAppSettingsBuilder().setAppId(...).setRegion(...).build()
-    // passed to CometChatCalls.init(callsAppSettings:onSuccess:onError:).
-  case .onError(let error):
-    print(error)
-  }
-}
-```
-
----
-
-## Step 4 — Login
-
-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
-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), use the `CometChat.login(UID:authToken:...)` overload instead of `authKey`.
-
----
-
-## Step 5 — Mount IncomingCall at root
-
-In SwiftUI:
-
-```swift
-@main
-struct YourApp: App {
-  var body: some Scene {
-    WindowGroup {
-      RootView()
-        .overlay(alignment: .top) {
-          CometChatIncomingCall()
-        }
-    }
-  }
-}
-```
-
-In UIKit:
-- Make a `RootViewController` that holds your existing app + the `CometChatIncomingCallView`
-- Or use `UIWindow.rootViewController` swap pattern when an incoming call arrives
-
----
-
-## Step 6 — PushKit + CallKit registration
-
-Implement `PKPushRegistryDelegate` (see `cometchat-ios-calls/references/server-apns-pushkit.md`):
-
-```swift
-class VoipPushHandler: NSObject, PKPushRegistryDelegate {
-  let registry = PKPushRegistry(queue: .main)
-  let callProvider: CXProvider
-
-  func pushRegistry(_ registry: PKPushRegistry, didUpdate credentials: PKPushCredentials, for type: PKPushType) {
-    let token = credentials.token.map { String(format: "%02x", $0) }.joined()
-    Task { try await api.registerVoipToken(uid: currentUid, token: token) }
-  }
-
-  func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) {
-    // Report to CallKit IMMEDIATELY
-    let update = CXCallUpdate()
-    let dict = payload.dictionaryPayload
-    update.remoteHandle = CXHandle(type: .generic, value: dict["callerUid"] as? String ?? "Unknown")
-    update.localizedCallerName = dict["callerName"] as? String ?? "Unknown"
-    update.hasVideo = (dict["callType"] as? String) == "video"
-    callProvider.reportNewIncomingCall(with: UUID(), update: update) { _ in completion() }
-  }
-}
-```
-
-Init this handler from your `AppDelegate.didFinishLaunchingWithOptions`.
-
----
-
-## Step 7 — Hangup teardown
-
-```swift
-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)
-}
-```
-
----
-
-## Verification checklist
-
-- [ ] `CometChatCallsSDK` in SwiftPM/CocoaPods
-- [ ] Background Modes capability + Info.plist UIBackgroundModes (audio + voip + remote-notification)
-- [ ] NSCameraUsageDescription + NSMicrophoneUsageDescription
-- [ ] Calls init runs AFTER chat init succeeds
-- [ ] 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
-- [ ] Real-device smoke: backgrounded incoming call rings on lock screen
-- [ ] Run `cometchat verify --calls` — should pass
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/add-calls-to-existing-chat.md` — canonical (no native modules)
-- `cometchat-ios-calls/SKILL.md` — seven hard rules
-- `cometchat-ios-calls/references/server-apns-pushkit.md` — server-side PushKit

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

@@ -1,45 +0,0 @@
-# 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

@@ -1,188 +0,0 @@
-# AVAudioSession routing for iOS calls
-
-The most-overlooked piece of iOS calls. Without correct `AVAudioSession` configuration, calls sound like the user is talking through an earpiece even with the speaker on, or background music doesn't resume after hangup.
-
----
-
-## The four states that matter
-
-| State | When |
-|---|---|
-| Inactive | App not in a call |
-| Active + .playAndRecord, .voiceChat | Active call (voice or video) |
-| Active + .playAndRecord, .videoChat | Active video call (slightly different routing — closer to face) |
-| Inactive + .notifyOthersOnDeactivation | Just hung up — tells music apps to resume |
-
----
-
-## On call start
-
-```swift
-import AVFoundation
-
-func configureForCall(isVideo: Bool) throws {
-  let session = AVAudioSession.sharedInstance()
-
-  try session.setCategory(
-    .playAndRecord,
-    mode: isVideo ? .videoChat : .voiceChat,
-    options: [.allowBluetooth, .allowBluetoothA2DP, .defaultToSpeaker]
-  )
-
-  try session.setActive(true)
-}
-```
-
-`mode: .voiceChat` enables echo cancellation and noise suppression optimized for voice calls. `mode: .videoChat` does the same but defaults to a slightly louder speaker volume (designed for handsfree use).
-
-`.allowBluetooth` allows AirPods, hearing aids. `.allowBluetoothA2DP` allows Bluetooth speakers. `.defaultToSpeaker` makes voice calls speakerphone by default — without it, calls route to the earpiece, which feels wrong for a video call.
-
----
-
-## On hangup — the canonical bug fix
-
-```swift
-func endCall() {
-  CometChatCalls.endSession()   // EXISTS on the static facade in v5
-
-  do {
-    try AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
-  } catch {
-    // Best-effort — don't block hangup on this
-    print("Failed to deactivate audio session: \(error)")
-  }
-}
-```
-
-`.notifyOthersOnDeactivation` is the magic. Without it:
-
-- Music app was paused by the call → stays paused
-- Other apps' audio was ducked → stays ducked
-- The user thinks the music app is broken
-
-With it, the system tells other audio sessions "the call's done, resume what you were doing."
-
----
-
-## Switching speaker on/off mid-call
-
-```swift
-func toggleSpeaker(on: Bool) throws {
-  let session = AVAudioSession.sharedInstance()
-  try session.overrideOutputAudioPort(on ? .speaker : .none)
-}
-```
-
-`.none` doesn't mean "no audio" — it means "use the system's default routing for this category" (which for `.playAndRecord` + `.voiceChat` is the receiver/earpiece).
-
----
-
-## Detecting Bluetooth + AirPods + hearing aids
-
-```swift
-func currentAudioRoute() -> String {
-  let route = AVAudioSession.sharedInstance().currentRoute
-  let outputs = route.outputs.map { $0.portType.rawValue }
-  // Common values: "Speaker", "Receiver", "BluetoothA2DPOutput", "BluetoothHFP", "BuiltInReceiver"
-  return outputs.first ?? "unknown"
-}
-
-func observeRouteChanges() {
-  NotificationCenter.default.addObserver(
-    forName: AVAudioSession.routeChangeNotification,
-    object: nil,
-    queue: .main
-  ) { notification in
-    // User plugged in headphones / unplugged AirPods
-    print("Route changed: \(self.currentAudioRoute())")
-  }
-}
-```
-
-For UI: show a "Speaker / AirPods / Bluetooth" indicator in the call control panel based on `currentAudioRoute()`.
-
----
-
-## CallKit + AVAudioSession — they fight if you don't coordinate
-
-CallKit's `provider(_:didActivate:)` callback fires when CallKit takes over the audio session (typically when the user answers from the lock screen). If you call `setActive(true)` yourself in the answer handler, CallKit might do it again and you get warnings.
-
-**Pattern:**
-
-```swift
-extension CallManager: CXProviderDelegate {
-  func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
-    // CallKit just activated the session — do post-activation work
-    // (e.g. start the WebRTC session)
-    if let pendingSessionId = self.pendingActivation {
-      startCometChatCallsSession(sessionID: pendingSessionId)
-      self.pendingActivation = nil
-    }
-  }
-
-  func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
-    // CallKit deactivated — your cleanup runs in CXEndCallAction
-  }
-
-  func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
-    // Configure category but DO NOT set active
-    try? AVAudioSession.sharedInstance().setCategory(
-      .playAndRecord, mode: .voiceChat,
-      options: [.allowBluetooth, .defaultToSpeaker]
-    )
-
-    // 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 `startSession` (after `generateToken`) from `didActivate`.
-
-For non-CallKit-driven calls (outgoing from inside the app), you do `setActive(true)` yourself.
-
----
-
-## Common failure modes
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| 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 `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 |
-
----
-
-## Audio session interruptions
-
-Phone calls (the actual phone, not your VoIP) can interrupt your call:
-
-```swift
-NotificationCenter.default.addObserver(
-  forName: AVAudioSession.interruptionNotification,
-  object: AVAudioSession.sharedInstance(),
-  queue: .main
-) { notification in
-  guard let userInfo = notification.userInfo,
-        let typeValue = userInfo[AVAudioSessionInterruptionTypeKey] as? UInt,
-        let type = AVAudioSession.InterruptionType(rawValue: typeValue) else { return }
-
-  switch type {
-  case .began:
-    // Phone call started — pause our call's audio (CallKit may auto-handle this for you)
-    CometChatCalls.audioMuted(true)   // NOT muteAudio
-  case .ended:
-    // Phone call ended — resume
-    CometChatCalls.audioMuted(false)
-    try? AVAudioSession.sharedInstance().setActive(true)
-  @unknown default:
-    break
-  }
-}
-```
-
-If you've integrated CallKit fully, iOS handles most of this — your VoIP call shows up as a "second call" in the system UI and the user can choose which to keep.

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

@@ -1,76 +0,0 @@
-# Call layouts on iOS
-
-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
-
----
-
-## SDK API
-
-```swift
-import CometChatCallsSDK
-
-let settings = CallSettingsBuilder()
-  .setIsAudioOnly(false)
-  .setMode(.default)         // swiftinterface:281 setMode(_ value: DisplayModes) -> Self
-  .build()
-```
-
-`setMode` takes a `DisplayModes` value:
-
-| Value | Meaning |
-|---|---|
-| `.default` | Standard grid of participant tiles |
-| `.single` | One participant fills the surface |
-| `.spotlight` | Active speaker enlarged, others as a strip |
-
-> **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).
-
----
-
-## Picking a layout at session start
-
-```swift
-// 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
-  }
-}()
-let settings = CallSettingsBuilder()
-  .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
-
-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
-
-- [ ] 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
-
----
-
-## Pointers
-
-- `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