@cometchat/skills 4.1.0 → 4.2.0

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

@@ -0,0 +1,185 @@
+# 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.
+
+**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
+
+```swift
+import CometChatCallsSDK
+
+let settings = CallSettingsBuilder()
+  .setSessionType(.video)
+  .setIsAudioOnly(false)
+  .setIdleTimeoutPeriodBeforePrompt(60_000)   // ms
+  .setIdleTimeoutPeriodAfterPrompt(120_000)
+  .build()
+```
+
+Listener — implement on the `CometChatCallsEventsListener`:
+
+```swift
+class CallListener: NSObject, CometChatCallsEventsListener {
+  func onSessionTimedOut() {
+    DispatchQueue.main.async {
+      // Report end to CallKit (rule 1.5 — hangup cleanup)
+      CallManager.shared.endCall(reason: .answeredElsewhere)
+      // Navigate away
+    }
+  }
+  // ...
+}
+```
+
+The `CallManager.shared.endCall(reason:)` call is critical — see `references/callkit-and-pushkit.md`. CallKit's call card persists on the lock screen unless you report the end.
+
+---
+
+## CallKit interaction — endCall reason
+
+When the SDK fires `onSessionTimedOut`, you must report the call end to CallKit. The reason matters for system UI:
+
+```swift
+let endReason: CXCallEndedReason = .remoteEnded
+// Other options:
+//   .failed           — error / network issue
+//   .remoteEnded      — counterparty hung up
+//   .unanswered       — incoming call not answered
+//   .answeredElsewhere — answered on another device
+//   .declinedElsewhere — declined on another device
+
+provider.reportCall(
+  with: callUUID,
+  endedAt: Date(),
+  reason: endReason,
+)
+```
+
+Use `.remoteEnded` for idle timeout — it's the closest semantic match (the "remote" effectively ended the call by leaving). Don't use `.failed` (implies error; iOS shows a "call failed" UI).
+
+---
+
+## Foreground/background gotcha
+
+iOS suspends background JavaScript / WebRTC threads aggressively. If the user backgrounds the app, the call session may pause. The idle timer continues running in the SDK's tracking, but participant-leave events may queue until foreground.
+
+Practical implication: idle timeout fires immediately on app return, even if the user only backgrounded for a few seconds. Same as RN.
+
+If using CallKit (rule 1.7 in SKILL.md), the background-mode `voip` capability keeps the call alive — but participant tracking may still lag. Test the foreground transition.
+
+---
+
+## Custom prompt — SwiftUI
+
+```swift
+struct IdleTimeoutPrompt: View {
+  let onStay: () -> Void
+  let onEnd: () -> Void
+
+  var body: some View {
+    VStack(spacing: 16) {
+      Text("Still there?")
+        .font(.headline)
+      Text("You're alone in this call. It'll end in 60 seconds.")
+        .multilineTextAlignment(.center)
+        .foregroundColor(.secondary)
+      HStack(spacing: 12) {
+        Button("End now", role: .destructive, action: onEnd)
+          .buttonStyle(.bordered)
+        Button("Stay", action: onStay)
+          .buttonStyle(.borderedProminent)
+      }
+    }
+    .padding(24)
+    .background(.regularMaterial, in: RoundedRectangle(cornerRadius: 16))
+    .accessibilityElement(children: .contain)
+    .accessibilityAddTraits(.isModal)
+  }
+}
+```
+
+Used as an overlay:
+
+```swift
+struct CallView: View {
+  @State private var showIdlePrompt = false
+
+  var body: some View {
+    ZStack {
+      // Call surface
+      if showIdlePrompt {
+        Color.black.opacity(0.5)
+          .ignoresSafeArea()
+          .onTapGesture { /* prevent dismiss on backdrop */ }
+        IdleTimeoutPrompt(
+          onStay: { showIdlePrompt = false; resetIdleTimer() },
+          onEnd: { CometChatCallsSDK.CallSession.shared.leaveSession() },
+        )
+      }
+    }
+  }
+}
+```
+
+`accessibilityAddTraits(.isModal)` is the SwiftUI equivalent of web's `aria-modal="true"`. VoiceOver focus stays trapped within the prompt.
+
+---
+
+## UIKit pattern — UIAlertController
+
+For UIKit projects, the simplest path is `UIAlertController`:
+
+```swift
+let alert = UIAlertController(
+  title: "Still there?",
+  message: "You're alone in this call. It'll end in 60 seconds.",
+  preferredStyle: .alert,
+)
+alert.addAction(UIAlertAction(title: "Stay", style: .default) { _ in
+  resetIdleTimer()
+})
+alert.addAction(UIAlertAction(title: "End now", style: .destructive) { _ in
+  CometChatCallsSDK.CallSession.shared.leaveSession()
+})
+alert.preferredAction = alert.actions.first  // make Stay the default
+present(alert, animated: true)
+```
+
+`alert.preferredAction` makes "Stay" the default highlighted action — VoiceOver activates it on triple-click home button as the default response.
+
+---
+
+## Anti-patterns
+
+Web sister reference rules apply, plus iOS-specific:
+
+1. **`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`.
+
+---
+
+## Verification checklist
+
+- [ ] CallSettingsBuilder sets both idle periods
+- [ ] `onSessionTimedOut` listener reports end to CallKit with `.remoteEnded` reason
+- [ ] Custom prompt uses `accessibilityAddTraits(.isModal)` (SwiftUI) or `UIAlertController.preferredStyle = .alert`
+- [ ] Backdrop dimmed; prevents accidental dismiss
+- [ ] All UIKit alert presentations on main thread
+- [ ] Real-device smoke: 2 iPhones in call, hangup from one → other shows prompt after configured delay
+- [ ] Lock-screen smoke: when call times out, lock-screen card disappears (CallKit reported)
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/idle-timeout.md` — sister reference (settings, archetype timeouts)
+- `cometchat-ios-calls` SKILL.md
+- `references/callkit-and-pushkit.md` — CallKit reporting end
+- `references/swiftui-uikit-hosting.md` — embedding SwiftUI prompts in UIKit nav
+- Canonical docs: https://www.cometchat.com/docs/calls/ios/idle-timeout

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

@@ -0,0 +1,183 @@
+# 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.
+
+**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
+
+```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()
+  }
+}
+
+// Unread badge
+CometChatCalls.setChatButtonUnreadCount(5)
+CometChatCalls.setChatButtonUnreadCount(0)
+```
+
+---
+
+## Sheet presentation (iOS 15+)
+
+```swift
+import UIKit
+
+class CallViewController: UIViewController {
+  func presentChatSheet() {
+    let chatVC = InCallChatViewController(sessionId: sessionId)
+    let nav = UINavigationController(rootViewController: chatVC)
+
+    if #available(iOS 15.0, *) {
+      if let sheet = nav.sheetPresentationController {
+        sheet.detents = [.medium(), .large()]
+        sheet.prefersGrabberVisible = true
+        sheet.preferredCornerRadius = 16
+      }
+    }
+
+    present(nav, animated: true)
+  }
+}
+```
+
+`.detents = [.medium(), .large()]` is iOS 15+'s pull-up sheet API. Matches the BottomSheet UX from RN/Flutter.
+
+---
+
+## InCallChatViewController
+
+```swift
+class InCallChatViewController: UIViewController {
+  let sessionId: String
+  private var group: Group?
+  private var listenerId: String!
+
+  init(sessionId: String) {
+    self.sessionId = sessionId
+    super.init(nibName: nil, bundle: nil)
+    self.title = "Chat"
+  }
+  required init?(coder: NSCoder) { fatalError() }
+
+  override func viewDidLoad() {
+    super.viewDidLoad()
+    listenerId = "in-call-chat-\(sessionId)"
+
+    Task {
+      do {
+        group = try await ensureGroup(sessionId: sessionId)
+        try await joinGroup(sessionId: sessionId)
+        await MainActor.run {
+          self.embedMessageList()
+        }
+      } catch {
+        print("Failed to set up in-call chat:", error)
+      }
+    }
+  }
+
+  override func viewWillDisappear(_ animated: Bool) {
+    super.viewWillDisappear(animated)
+    // Clear badge on close
+    CometChatCalls.setChatButtonUnreadCount(0)
+  }
+
+  private func embedMessageList() {
+    guard let group = group else { return }
+    // The kit's CometChatMessageList is a UIViewController
+    let messageList = CometChatMessageList()
+    messageList.group = group
+    addChild(messageList)
+    view.addSubview(messageList.view)
+    // ... AutoLayout pinning to fill view
+    messageList.didMove(toParent: self)
+
+    // Composer
+    let composer = CometChatMessageComposer()
+    composer.group = group
+    addChild(composer)
+    view.addSubview(composer.view)
+    // ... AutoLayout pinning to bottom
+    composer.didMove(toParent: self)
+  }
+}
+
+func ensureGroup(sessionId: String) async throws -> Group {
+  do {
+    return try await fetchGroup(sessionId)   // CometChat.getGroup wrapper
+  } catch {
+    let group = Group(guid: sessionId, name: "Call \(sessionId)", groupType: .public, password: "")
+    return try await createGroup(group)
+  }
+}
+```
+
+---
+
+## Audio ducking when keyboard opens
+
+iOS auto-ducks call audio when the system keyboard opens (the kit handles this). For custom UI you may want to maintain unducked audio for the whole call — explicit override:
+
+```swift
+NotificationCenter.default.addObserver(
+  forName: UIResponder.keyboardWillShowNotification,
+  object: nil, queue: .main
+) { _ in
+  // Re-assert non-ducking audio category
+  try? AVAudioSession.sharedInstance().setCategory(
+    .playAndRecord,
+    mode: .voiceChat,
+    options: [.allowBluetooth, .defaultToSpeaker]
+  )
+}
+```
+
+Most apps don't need this; the kit's defaults are sensible. Override only if user testing surfaces the audio ducking as confusing.
+
+---
+
+## Anti-patterns
+
+Web sister rules apply, plus iOS-specific:
+
+1. **`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`).
+3. **Mutating `group` from background.** `group` updates must be on main; `Task { @MainActor in ... }` or `DispatchQueue.main.async`.
+4. **Forgetting `dismiss(animated: true)` on call end.** Sheet stays up over the post-call screen — looks broken.
+
+---
+
+## Verification checklist
+
+- [ ] `setHideChatButton(false)` in CallSettings
+- [ ] `onChatButtonClicked` presents the chat sheet on main queue
+- [ ] `UISheetPresentationController` with `[.medium(), .large()]` detents (iOS 15+)
+- [ ] `CometChatMessageList` + `CometChatMessageComposer` embedded as child VCs
+- [ ] Sheet dismissed on call end
+- [ ] Real-device smoke: 2 iPhones in call, send message → badge in other
+- [ ] Sheet drag-down dismisses cleanly
+- [ ] Lock-screen smoke: backgrounded → return → chat sheet still visible if open
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/in-call-chat.md` — sister web reference (group-as-session pattern)
+- `cometchat-ios-calls` SKILL.md — the seven hard rules
+- `references/swiftui-uikit-hosting.md` — embedding SwiftUI sheets
+- Canonical docs: https://www.cometchat.com/docs/calls/ios/in-call-chat

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

@@ -0,0 +1,138 @@
+# 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.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/ios/migration-guide-v5
+
+---
+
+## Step 1 — Bump the SDK
+
+**SwiftPM:** Update the `CometChatCallsSDK` package version pin to `5.0.0` or higher.
+
+**CocoaPods:**
+```ruby
+# Podfile
+pod 'CometChatCallsSDK', '~> 5.0'
+```
+
+```bash
+pod install --repo-update
+```
+
+---
+
+## Step 2 — Migrate init to plain struct
+
+```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)
+```
+
+V5 ships async/await. The completion-handler form still works for backwards compat.
+
+---
+
+## Step 3 — Add Calls SDK login
+
+```swift
+// After CometChat.login() resolves with a User:
+let authToken = user.authToken
+try await CometChatCalls.login(authToken: authToken)
+```
+
+After this, `generateToken()` and `joinSession()` no longer need an authToken parameter.
+
+---
+
+## Step 4 — Migrate session settings
+
+```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
++ )
+```
+
+---
+
+## Step 5 — Migrate events to delegates / closures
+
+```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() }
+```
+
+---
+
+## Step 6 — Method renames
+
+```diff
+// session lifecycle — receiver changed from CometChatCalls (static) to CallSession.shared (singleton)
+- CometChatCalls.endSession()
++ CallSession.shared.leaveSession()
+
+- CometChatCalls.muteAudio(true)
++ CallSession.shared.muteAudio()
+- CometChatCalls.muteAudio(false)
++ CallSession.shared.unmuteAudio()
+
+- CometChatCalls.startScreenShare()
++ CallSession.shared.startScreenShare()
+
+// layout stays static on CometChatCalls
+- CometChatCalls.setMode(mode)
++ CometChatCalls.setLayout(layout)
+```
+
+**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.
+
+---
+
+## Verification checklist
+
+- [ ] Podfile / Package.swift updated
+- [ ] `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)
+- [ ] Real-device smoke: incoming call from iPhone → answer → mute → end
+
+---
+
+## Pointers
+
+- Canonical migration: https://www.cometchat.com/docs/calls/ios/migration-guide-v5
+- `cometchat-ios-calls/SKILL.md` — seven hard rules (still apply post-v5)
+- `cometchat-ios-calls/references/server-apns-pushkit.md` — PushKit setup (unchanged in v5)