@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-ios-calls/references/recording-screen-share.md

@@ -1,252 +0,0 @@
-# Recording + screen-share on iOS
-
-Recording is server-side (same as every family). Screen-share on iOS requires a **separate Xcode target** — the iOS Broadcast Upload Extension — because Apple sandboxes screen capture in a separate process. This is the most involved screen-share integration of any family.
-
-For SDK semantics + browser-side details, read `cometchat-react-calls/references/recording-screen-share.md` first. This reference is the iOS-specific manual setup and bridge code.
-
----
-
-## Recording
-
-### Server-side: dashboard gate
-
-Same as web/RN — enable in **Dashboard → Chat & Messaging → Calls → Recording**. Client flag is no-op without it.
-
-### Client-side flag
-
-```swift
-import CometChatCallsSDK
-
-let settings = CallSettingsBuilder()
-  .setIsAudioOnly(false)
-  .setStartRecordingOnCallStart(true)   // auto-start recording on session start
-  .setShowRecordingButton(true)         // show the kit's user-toggleable REC button
-  .build()
-```
-
-There is no `setSessionType` and no `enableRecording` on the iOS v5 builder. Auto-start is `setStartRecordingOnCallStart(_:)`; button visibility is `setShowRecordingButton(_:)`. To toggle recording programmatically mid-call, use the static `CometChatCalls.startRecording()` / `CometChatCalls.stopRecording()`.
-
-### Lifecycle events (REC indicator)
-
-The iOS Calls SDK v5 has a SINGLE recording callback — `onRecordingToggled(info:)` on `CallsEventsDelegate` (swiftinterface label is `info:`, payload is an `NSDictionary`). There is no `onRecordingStarted`/`onRecordingStopped`/`onRecordingFailed` split, and the delegate is a protocol you conform to (not an object with assignable closure properties).
-
-```swift
-extension CustomOngoingCallViewController: CallsEventsDelegate {
-  // swiftinterface: onRecordingToggled(info: NSDictionary)
-  func onRecordingToggled(info: NSDictionary) {
-    DispatchQueue.main.async { [weak self] in
-      // info carries the current recording state + initiating user.
-      // Drive the REC badge from your own isRecording flag toggled here.
-      self?.isRecording.toggle()
-      self?.recBadge.isHidden = !(self?.isRecording ?? false)
-    }
-  }
-}
-```
-
-Wire the delegate via `CallSettingsBuilder.setDelegate(self)` or `CometChatCalls.addCallEventListener(observerId:delegate:)`. There is no separate recording-failure callback — surface failures from your own start/stop call sites if you toggle programmatically.
-
-The badge: a small "REC" pill with a blinking red dot. Must be visible to all participants — compliance requirement (CCPA, GDPR Art. 6/7, two-party-consent US states).
-
-```swift
-final class RecBadgeView: UIView {
-  override init(frame: CGRect) {
-    super.init(frame: frame)
-    backgroundColor = UIColor(white: 0, alpha: 0.6)
-    layer.cornerRadius = 4
-
-    let dot = UILabel()
-    dot.text = "●"
-    dot.textColor = .systemRed
-    dot.font = .systemFont(ofSize: 12)
-    dot.translatesAutoresizingMaskIntoConstraints = false
-
-    let label = UILabel()
-    label.text = "REC"
-    label.textColor = .white
-    label.font = .systemFont(ofSize: 12, weight: .semibold)
-    label.translatesAutoresizingMaskIntoConstraints = false
-
-    addSubview(dot)
-    addSubview(label)
-    NSLayoutConstraint.activate([
-      dot.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 6),
-      dot.centerYAnchor.constraint(equalTo: centerYAnchor),
-      label.leadingAnchor.constraint(equalTo: dot.trailingAnchor, constant: 4),
-      label.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -6),
-      label.centerYAnchor.constraint(equalTo: centerYAnchor),
-    ])
-
-    // Blink animation
-    UIView.animate(withDuration: 0.8, delay: 0, options: [.repeat, .autoreverse], animations: {
-      dot.alpha = 0.3
-    })
-  }
-  required init?(coder: NSCoder) { fatalError() }
-}
-```
-
-### Recording retrieval
-
-CometChat hosts the file. Same as web/RN — accessible via dashboard UI or REST API from your server. Never expose recording URLs to the iOS client.
-
----
-
-## Screen sharing — iOS Calls SDK v5.x does NOT support INITIATING
-
-**Confirmed against the v5 `CometChatCallsSDK` Swift interface:** the iOS Calls SDK does not support initiating screen sharing. iOS callees can RECEIVE incoming screen shares from web/Android peers — the SDK renders the incoming screen track into the session view automatically — but `CallsEventsDelegate` exposes NO dedicated screen-share callback (no `onScreenShareStarted`/`onScreenShareEnded`, no `onParticipantStartedScreenShare`, no `OngoingCallListener`). iOS cannot SEND.
-
-The symbols previously documented in this file (`CometChatCalls.startScreenShareBroadcast`, `processBroadcastVideoFrame`, `processBroadcastAudioFrame`, `endScreenShareBroadcast`) **do not exist** on `CometChatCallsSDK` v5.x. If you've copied these from an earlier draft of this doc, they will not compile against the actual SDK.
-
-### What works today
-
-| Direction | Status | API |
-|---|---|---|
-| Receive screen share (iOS callee) | ✅ supported (rendered by the SDK into the session view) | no dedicated callback — the screen track renders like any remote video |
-| Initiate screen share (iOS caller → others) | ❌ NOT supported by CometChatCallsSDK v5 | n/a |
-
-For applications that need iOS users to share their screen today, the practical options are:
-
-1. **Defer screen-share initiation to web/Android peers.** Document that iOS callers are receive-only for screen content.
-2. **Wait for vendor support.** Track the CometChat iOS Calls SDK release notes; this is a known gap.
-3. **Build your own WebRTC bridge** in a Broadcast Upload Extension and attach a manual video track to the underlying peer connection. The CometChat session is a WebRTC peer connection internally, but the SDK does not expose the peer-connection handle, so this requires forking/patching the SDK — not recommended.
-
-### Architecture pieces that remain valid (for future SDK support)
-
-Steps 1–4 below (Broadcast Upload Extension target, App Groups capability, `RPBroadcastProcessModeSampleBuffer` Info.plist, `RPSystemBroadcastPickerView`) are all valid iOS-level setup that any future SDK adding sender-side screen-share would also require. Kept here for reference. **Skip Steps 5–6 (SampleHandler.swift + App-Group state pre-write) — they reference SDK symbols that do not exist.**
-
-iOS sandboxes screen capture inside a separate process. To share (IF the SDK supported it), you would need:
-
-1. **A Broadcast Upload Extension target** in your Xcode project
-2. **An App Group capability** shared between the main app and the extension
-3. **An RPSystemBroadcastPickerView** (provided by ReplayKit) that lets the user start sharing
-4. **A WebRTC bridge in the extension** that pipes captured frames into the Calls SDK session
-
-Apple doesn't allow main-app screen capture for privacy reasons; this Extension architecture is unavoidable.
-
-### Step 1 — Create the Broadcast Upload Extension
-
-Xcode → File → New → Target → **Broadcast Upload Extension**.
-
-- Product Name: `YourAppBroadcastExtension`
-- Bundle Identifier: `com.yourcompany.YourApp.BroadcastExtension`
-- Embed in Application: YourApp
-
-Xcode generates a `SampleHandler.swift` with stub methods.
-
-### Step 2 — App Group
-
-Both the main target AND the extension target need this capability.
-
-Main app target → Signing & Capabilities → + Capability → **App Groups** → enable `group.com.yourcompany.yourapp.broadcast`.
-
-Extension target → same capability, same group identifier.
-
-### Step 3 — Info.plist for the extension
-
-The extension's `Info.plist` (auto-generated by Xcode) must have:
-
-```xml
-<key>NSExtension</key>
-<dict>
-  <key>NSExtensionPointIdentifier</key>
-  <string>com.apple.broadcast-services-upload</string>
-  <key>NSExtensionPrincipalClass</key>
-  <string>$(PRODUCT_MODULE_NAME).SampleHandler</string>
-  <key>RPBroadcastProcessMode</key>
-  <string>RPBroadcastProcessModeSampleBuffer</string>
-</dict>
-```
-
-`RPBroadcastProcessModeSampleBuffer` is critical — without it, the extension receives audio/video data in a different format that doesn't fit the Calls SDK's bridge.
-
-### Step 4 — RPSystemBroadcastPickerView in the call screen
-
-```swift
-import ReplayKit
-
-class CustomOngoingCallViewController: UIViewController {
-  private lazy var broadcastPicker: RPSystemBroadcastPickerView = {
-    let picker = RPSystemBroadcastPickerView(frame: CGRect(x: 0, y: 0, width: 50, height: 50))
-    picker.preferredExtension = "com.yourcompany.YourApp.BroadcastExtension"
-    picker.showsMicrophoneButton = false           // SDK handles mic
-    return picker
-  }()
-
-  override func viewDidLoad() {
-    super.viewDidLoad()
-    // Find and customize the actual button inside the picker (Apple's API restriction)
-    if let button = broadcastPicker.subviews.compactMap({ $0 as? UIButton }).first {
-      button.setImage(UIImage(systemName: "rectangle.on.rectangle.angled"), for: .normal)
-    }
-    view.addSubview(broadcastPicker)
-    // Layout broadcastPicker as part of your control panel
-  }
-}
-```
-
-When the user taps the picker, iOS shows the system broadcast UI listing your extension. They tap it; the extension activates; capture begins.
-
-### Steps 5–6 — SDK frame bridge: NOT available
-
-iOS cannot INITIATE screen share (receive-only). `CometChatCallsSDK` v5.x exposes no frame-bridge API (`startScreenShareBroadcast`/`processBroadcastVideoFrame`/`processBroadcastAudioFrame`/`endScreenShareBroadcast` are all absent), so there is no `SampleHandler` pipeline to write — defer screen-share initiation to web/Android peers.
-
----
-
-## Viewer — receiving someone else's screen share
-
-When a web/Android peer starts sharing, the iOS Calls SDK renders the incoming screen track into the session `view` you passed to `startSession` — exactly like any other remote video tile. There is **no** `onScreenShareStarted`/`onScreenShareEnded` callback on `CallsEventsDelegate` to hook (those symbols do not exist on iOS v5).
-
-If you need to react to participant changes around a screen share (e.g. relayout), use the typed participant callbacks — `onUserJoined(rtcUser:)`, `onUserLeft(rtcUser:)`, `onUserListChanged(rtcUsers:)` (swiftinterface:35,38,41 — `RTCUser` objects). For default-UI integrations no code is required: the SDK handles the screen-track layout for you.
-
----
-
-## Common failure modes
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| Picker doesn't show your extension | Bundle ID mismatch in `preferredExtension` | Match the extension target's Bundle ID exactly |
-| "No active session" finishBroadcastWithError | App Group identifier mismatch | Both targets must use the same `group.*` identifier |
-| Extension launches but no video on remote side | Missing `RPBroadcastProcessModeSampleBuffer` in extension Info.plist | Add it |
-| Recording flag set but no recording in dashboard | Plan doesn't include recording, or dashboard toggle off | Enable in dashboard |
-| REC badge missing | Custom UI — must render manually | Subscribe to `onRecordingToggled(info:)` and render badge |
-| Screen share doesn't end on call hangup | `broadcastFinished` not triggering | Manually call `RPBroadcastController.shared.finishBroadcast(...)` from main app on hangup |
-
----
-
-## Anti-patterns
-
-1. **Embedding screen-share logic in the main app target.** iOS doesn't allow it — must be a separate extension.
-2. **App Groups with mismatched identifiers.** Extension can't see main app state; broadcast finishes immediately.
-3. **`RPSystemBroadcastPickerView` with hidden button via removeFromSuperview.** Apple may reject the build for App Store. Customize via subview iteration only.
-4. **No REC indicator.** Compliance violation in two-party-consent jurisdictions.
-5. **Trying to access recording files from the device.** They're not local — server-only access via REST API.
-6. **Implementing the SampleHandler.broadcastStarted/processSampleBuffer/broadcastFinished pipeline against CometChatCallsSDK v5.x.** Per the audit above, the SDK does not expose `startScreenShareBroadcast`, `processBroadcastVideoFrame`, `processBroadcastAudioFrame`, or `endScreenShareBroadcast`. Steps 5–6 of this doc are kept for reference but will not compile against the actual SDK today.
-
----
-
-## Verification checklist
-
-**Recording:**
-- [ ] Dashboard plan includes recording feature
-- [ ] `setStartRecordingOnCallStart(true)` and/or `setShowRecordingButton(true)` on `CallSettingsBuilder` (no `enableRecording`)
-- [ ] `onRecordingToggled(info:)` listener wired (single callback — no Started/Stopped/Failed split)
-- [ ] REC badge visible to all participants when active
-
-**Screen share — receiver side only (iOS Calls SDK v5 cannot INITIATE):**
-- [ ] No code required for default UI — the SDK renders the incoming screen track into the session view
-- [ ] No `onScreenShareStarted`/`onScreenShareEnded`/`onParticipantStartedScreenShare`/`OngoingCallListener` referenced (none exist on iOS v5)
-- [ ] Sender-side screen-share architecture (Broadcast Extension, SampleHandler) NOT implemented against current SDK — the symbols don't exist
-
-**Real-device smoke (receive-only — iOS cannot INITIATE screen share):**
-- [ ] When a participant on another platform (web/Android) shares their screen, it renders in the iOS call view
-- [ ] No sender-side broadcast picker/UI is shown on iOS (there is no initiation API in the v5 SDK)
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/recording-screen-share.md` — sister reference (SDK semantics, browser semantics, server-side recording retrieval)
-- `cometchat-native-calls/references/recording-screen-share.md` — RN reference (same Broadcast Upload Extension pattern; this iOS version is more detailed)
-- `references/group-calls.md` — recording group calls (server composition handles layout)
-- `cometchat-ios-calls` SKILL.md — base hard rules

package/skills/cometchat-ios-calls/references/ringing-integration.md

@@ -1,143 +0,0 @@
-# Ringing — call signaling with custom UI (iOS)
-
-iOS-specific deltas: PushKit + CallKit are mandatory for backgrounded ring delivery; foreground ringing uses the Chat SDK's `CometChatCallDelegate` (NOT the Calls SDK's `CallsEventsDelegate`); AVAudioSession routing.
-
-**Read first:** `cometchat-react-calls/references/ringing-integration.md` — full architecture, hard rules.
-
----
-
-## SDK API
-
-```swift
-import CometChatSDK
-import CometChatCallsSDK
-
-let call = Call(receiverId: receiverUid, callType: .video, receiverType: .user)
-CometChat.initiateCall(call: call, onSuccess: { outgoing in
-  self.showOutgoingCallScreen(outgoing)
-}, onError: { err in
-  print("Initiate failed:", err)
-})
-```
-
----
-
-## Foreground listener
-
-Ringing/signaling events live on the Chat SDK's `CometChatCallDelegate` (its callbacks take TWO params: the call and an error). Implement it and register at app start with the positional `CometChat.addCallListener(_:_:)`:
-
-```swift
-class AppCallListener: NSObject, CometChatCallDelegate {
-  func onIncomingCallReceived(incomingCall: Call?, error: CometChatException?) {
-    guard let call = incomingCall else { return }
-    DispatchQueue.main.async { showIncomingCallScreen(call) }
-  }
-  func onOutgoingCallAccepted(acceptedCall: Call?, error: CometChatException?) {
-    guard let call = acceptedCall else { return }
-    DispatchQueue.main.async { startCallSession(sessionId: call.sessionId) }
-  }
-  func onIncomingCallCancelled(canceledCall: Call?, error: CometChatException?) {
-    DispatchQueue.main.async { dismissIncomingCallScreen() }
-  }
-  func onOutgoingCallRejected(rejectedCall: Call?, error: CometChatException?) {
-    DispatchQueue.main.async { dismissOutgoingCallScreen() }
-  }
-  func onCallEndedMessageReceived(endedCall: Call?, error: CometChatException?) {
-    DispatchQueue.main.async { teardownCallUI() }
-  }
-}
-
-CometChat.addCallListener("app", AppCallListener())   // positional labels
-```
-
-Add this in `AppDelegate.didFinishLaunchingWithOptions` AFTER `CometChat.init` succeeds.
-
----
-
-## Backgrounded ring — PushKit + CallKit (mandatory)
-
-iOS requires PushKit + CallKit for ring delivery when the app is backgrounded or killed. The foreground listener does NOT fire in those states. See `cometchat-ios-calls/references/server-apns-pushkit.md` for the server template.
-
-PushKit delegate flow:
-1. `pushRegistry(_:didReceiveIncomingPushWith:for:completion:)` fires
-2. Within ~5s, call `CXProvider.reportNewIncomingCall(with:update:)` — Apple revokes VoIP entitlement after 3 missed reports
-3. CallKit shows the system incoming-call UI
-4. User taps Accept → `provider(_:perform:CXAnswerCallAction)` fires → start CometChat session
-
----
-
-## SwiftUI incoming-call screen
-
-```swift
-struct IncomingCallScreen: View {
-  let call: Call
-  let onAccept: () -> Void
-  let onReject: () -> Void
-
-  var body: some View {
-    ZStack {
-      Color.black.opacity(0.85).ignoresSafeArea()
-      VStack(spacing: 24) {
-        AsyncImage(url: URL(string: call.callInitiator?.avatar ?? ""))
-          .frame(width: 120, height: 120)
-          .clipShape(Circle())
-        Text(call.callInitiator?.name ?? "Unknown")
-          .font(.title)
-        Text("Incoming \(call.type.rawValue) call")
-          .foregroundStyle(.secondary)
-        HStack(spacing: 32) {
-          Button(action: onReject) {
-            Image(systemName: "phone.down.fill")
-              .padding(20)
-              .background(Color.red, in: Circle())
-              .foregroundStyle(.white)
-          }
-          .accessibilityLabel("Decline call")
-          Button(action: onAccept) {
-            Image(systemName: "phone.fill")
-              .padding(20)
-              .background(Color.green, in: Circle())
-              .foregroundStyle(.white)
-          }
-          .accessibilityLabel("Accept call")
-        }
-      }
-      .foregroundStyle(.white)
-    }
-  }
-}
-```
-
-For backgrounded ring, CallKit's UI takes over — your SwiftUI screen only fires for foreground rings.
-
----
-
-## Anti-patterns
-
-Web sister rules apply, plus iOS-specific:
-
-1. **Listener registered before `CometChat.init`.** Crash. Always register after init's success block.
-2. **Skipping PushKit + CallKit.** Backgrounded calls don't ring. Apple may also revoke VoIP entitlement if you ship with `pushType: .voIP` registered but no CallKit reporting.
-3. **Updating UI from listener callback's thread.** SDK fires off main; always `DispatchQueue.main.async` for UI updates.
-4. **Playing AVAudioPlayer ringtone during CallKit ring.** CallKit plays system ringtone; double-up is jarring.
-
----
-
-## Verification checklist
-
-- [ ] Foreground listener registered after `CometChat.init` resolves
-- [ ] PushKit registry initialized + .p8 key configured
-- [ ] CallKit `CXProvider.reportNewIncomingCall` fires within 5s of push
-- [ ] All listener callbacks dispatch to main queue
-- [ ] `removeCallListener` in app teardown
-- [ ] Real-device smoke: foreground ring, backgrounded ring (push), killed-app ring (push) all surface UI
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/ringing-integration.md` — canonical
-- `cometchat-ios-calls/SKILL.md` — seven hard rules
-- `cometchat-ios-calls/references/server-apns-pushkit.md` — PushKit server-side
-- `cometchat-ios-calls/references/callkit-and-pushkit.md` — CallKit details
-- Canonical docs: https://www.cometchat.com/docs/calls/ios/ringing

package/skills/cometchat-ios-calls/references/server-apns-pushkit.md

@@ -1,267 +0,0 @@
-# Server-side APNs PushKit for iOS VoIP
-
-When a CometChat call event fires (`onIncomingCallReceived` → CometChat backend webhook), your server sends a **VoIP push** to the recipient's iPhone via Apple's PushKit. Your app's PushKit delegate then triggers CallKit's incoming-call UI. Without VoIP push, the recipient's phone won't ring when the app is backgrounded.
-
-**Canonical docs:** https://developer.apple.com/documentation/pushkit, https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns
-
----
-
-## Hard rules
-
-1. **VoIP push is .p8 only** (token-auth). Old .pem cert auth was deprecated in 2020 and is no longer supported for VoIP.
-2. **Use a separate APNs topic.** VoIP topic = `<bundle-id>.voip`. NOT the same as your regular APNs topic.
-3. **`apns-push-type: voip`** header is mandatory. Apple drops the push silently if missing.
-4. **`apns-priority: 10`** (immediate). VoIP must be high-priority.
-5. **Must report to CallKit within ~5 seconds.** PushKit gives you a tiny window — if you don't call `CXProvider.reportNewIncomingCall(with:update:)` fast, iOS terminates your app and counts a strike. Three strikes in 24h and Apple revokes your VoIP entitlement.
-6. **VoIP push payload size ≤ 4KB.** Include the minimum (`sessionId`, `callerName`, `callType`); fetch the rest after CallKit is reported.
-
----
-
-## .p8 setup
-
-1. Apple Developer Portal → Certificates, Identifiers & Profiles → **Keys** → "+"
-2. Enable **Apple Push Notifications service (APNs)** → Continue → Register
-3. Download the `.p8` file. **Save it — Apple shows it once.**
-4. Note the **Key ID** (10-char alphanumeric).
-5. Note your **Team ID** (top-right of Apple Developer dashboard).
-
-Store securely on your server (Secret Manager / Vault — never in source).
-
----
-
-## Node.js template
-
-```js
-// npm install @parse/node-apn
-import apn from "@parse/node-apn";
-import fs from "fs";
-
-const provider = new apn.Provider({
-  token: {
-    key: fs.readFileSync("/secrets/AuthKey_ABC123.p8"),
-    keyId: process.env.APNS_KEY_ID,       // e.g. "ABC123XYZ"
-    teamId: process.env.APNS_TEAM_ID,     // e.g. "TEAM12345"
-  },
-  production: process.env.NODE_ENV === "production",
-});
-
-/**
- * Called from your CometChat call-event webhook handler.
- * Looks up the recipient's PushKit token (you stored it when their app
- * registered) and fires the VoIP push.
- */
-export async function sendVoipPush(opts) {
-  const { recipientUid, sessionId, callerName, callerUid, callType } = opts;
-
-  const pushKitToken = await db.getVoipToken(recipientUid);
-  if (!pushKitToken) return; // user not on iOS or token expired
-
-  const note = new apn.Notification();
-  note.topic = `${process.env.APNS_BUNDLE_ID}.voip`;  // <bundle>.voip — required
-  note.pushType = "voip";                              // apns-push-type: voip
-  note.priority = 10;                                  // apns-priority: 10 — immediate
-  note.expiry = Math.floor(Date.now() / 1000) + 30;    // 30s — VoIP push must fire fast
-
-  // Custom payload — keep ≤4KB, include only what CallKit needs
-  note.rawPayload = {
-    aps: { "content-available": 1 },
-    sessionId,
-    callerName,
-    callerUid,
-    callType,        // "audio" | "video"
-    timestamp: Date.now(),
-  };
-
-  const result = await provider.send(note, pushKitToken);
-  if (result.failed.length > 0) {
-    const fail = result.failed[0];
-    if (fail.status === "410" || fail.response?.reason === "Unregistered") {
-      // Token is dead — remove from DB so we don't keep retrying
-      await db.removeVoipToken(recipientUid, pushKitToken);
-    }
-    console.error("APNs VoIP push failed", fail);
-    return;
-  }
-}
-```
-
----
-
-## Python template
-
-```python
-# pip install httpx pyjwt cryptography
-import time, json, jwt, httpx
-from cryptography.hazmat.primitives.serialization import load_pem_private_key
-
-PRIVATE_KEY = load_pem_private_key(
-    open("/secrets/AuthKey_ABC123.p8", "rb").read(), password=None
-)
-KEY_ID = os.environ["APNS_KEY_ID"]
-TEAM_ID = os.environ["APNS_TEAM_ID"]
-BUNDLE_ID = os.environ["APNS_BUNDLE_ID"]
-APNS_HOST = "https://api.push.apple.com" if os.environ.get("ENV") == "production" else "https://api.sandbox.push.apple.com"
-
-# Provider tokens are valid for 1h; cache + refresh
-_token_cache = {"token": None, "issued_at": 0}
-
-def provider_token() -> str:
-    if time.time() - _token_cache["issued_at"] < 3000:  # refresh every 50min
-        return _token_cache["token"]
-    token = jwt.encode(
-        {"iss": TEAM_ID, "iat": int(time.time())},
-        PRIVATE_KEY,
-        algorithm="ES256",
-        headers={"kid": KEY_ID},
-    )
-    _token_cache.update(token=token, issued_at=time.time())
-    return token
-
-async def send_voip_push(pushkit_token: str, payload: dict):
-    headers = {
-        "authorization": f"bearer {provider_token()}",
-        "apns-topic": f"{BUNDLE_ID}.voip",
-        "apns-push-type": "voip",
-        "apns-priority": "10",
-        "apns-expiration": str(int(time.time()) + 30),
-    }
-    async with httpx.AsyncClient(http2=True) as client:
-        r = await client.post(
-            f"{APNS_HOST}/3/device/{pushkit_token}",
-            headers=headers,
-            content=json.dumps(payload),
-        )
-        if r.status_code == 410:
-            # Token unregistered — remove from DB
-            return "unregistered"
-        if r.status_code != 200:
-            raise RuntimeError(f"APNs error {r.status_code}: {r.text}")
-```
-
----
-
-## Webhook payload from CometChat
-
-In the CometChat dashboard, configure a **Webhook** → "Call events" → POST to `https://yourserver.com/webhooks/call`. The body shape:
-
-```json
-{
-  "trigger": "call_initiated",
-  "data": {
-    "id": "session-uuid",
-    "sessionId": "session-uuid",
-    "type": "video",
-    "initiator": { "uid": "alice", "name": "Alice" },
-    "receiver": { "uid": "bob", "name": "Bob" },
-    "receiverType": "user"
-  }
-}
-```
-
-Your handler:
-
-```js
-app.post("/webhooks/call", async (req, res) => {
-  // 1. Verify webhook signature (X-CometChat-Signature header)
-  const sig = req.headers["x-cometchat-signature"];
-  const expected = crypto.createHmac("sha256", process.env.COMETCHAT_WEBHOOK_SECRET)
-    .update(req.rawBody).digest("hex");
-  if (sig !== expected) return res.status(401).end();
-
-  // 2. Only fire VoIP push on call_initiated (not on call-ended)
-  if (req.body.trigger !== "call_initiated") return res.status(200).end();
-
-  // 3. Forward to platform-specific push
-  const { sessionId, type, initiator, receiver } = req.body.data;
-  await sendVoipPush({
-    recipientUid: receiver.uid,
-    sessionId,
-    callerName: initiator.name,
-    callerUid: initiator.uid,
-    callType: type,
-  });
-
-  res.status(200).end();
-});
-```
-
----
-
-## Token registration (the round-trip)
-
-When your iOS app launches, register PushKit and POST the token to your server:
-
-```swift
-// AppDelegate or dedicated VoIP manager
-import PushKit
-
-class VoipPushHandler: NSObject, PKPushRegistryDelegate {
-  let registry = PKPushRegistry(queue: .main)
-
-  override init() {
-    super.init()
-    registry.delegate = self
-    registry.desiredPushTypes = [.voIP]
-  }
-
-  func pushRegistry(_ registry: PKPushRegistry, didUpdate credentials: PKPushCredentials, for type: PKPushType) {
-    guard type == .voIP else { return }
-    let token = credentials.token.map { String(format: "%02x", $0) }.joined()
-    Task { try? await api.registerVoipToken(uid: currentUserUid, token: token) }
-  }
-
-  func pushRegistry(_ registry: PKPushRegistry, didInvalidatePushTokenFor type: PKPushType) {
-    Task { try? await api.removeVoipToken(uid: currentUserUid) }
-  }
-
-  func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) {
-    // Report to CallKit IMMEDIATELY — Apple gives you ~5s
-    let dict = payload.dictionaryPayload
-    let update = CXCallUpdate()
-    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"
-
-    let uuid = UUID()
-    callProvider.reportNewIncomingCall(with: uuid, update: update) { error in
-      if let error = error { print("CallKit reportNewIncomingCall failed:", error) }
-      completion()
-    }
-  }
-}
-```
-
----
-
-## Anti-patterns
-
-1. **Using regular APNs token, not VoIP.** Push arrives but CallKit doesn't trigger — the app got woken up, not put into "incoming call" state.
-2. **Forgetting `apns-push-type: voip`.** Apple drops the push, no error to your server.
-3. **Not calling `reportNewIncomingCall` from `didReceiveIncomingPushWith`.** Three strikes → entitlement revoked.
-4. **Sending too much in the VoIP payload.** Apple throttles or rejects >4KB. Send minimum, fetch the rest after CallKit fires.
-5. **Webhook handler doing slow work synchronously.** Push to a queue (Redis, SQS, BullMQ); return 200 immediately. Slow webhook = CometChat retries = duplicate calls.
-6. **Same token for chat push and VoIP push.** Different tokens — you must register both via `UNUserNotificationCenter` (regular) AND `PKPushRegistry` (VoIP).
-
----
-
-## Verification checklist
-
-- [ ] `.p8` key stored in secret manager
-- [ ] `apns-topic = <bundle-id>.voip`
-- [ ] `apns-push-type: voip` + `apns-priority: 10`
-- [ ] `reportNewIncomingCall` fires from PushKit delegate inside ~5s
-- [ ] 410 responses purge dead tokens from DB
-- [ ] Webhook signature verified before processing
-- [ ] Webhook returns 200 within 1s (push enqueued, not awaited)
-- [ ] Real-device smoke: backgrounded recipient → caller dials → recipient phone rings on lock screen
-
----
-
-## Pointers
-
-- `cometchat-ios-calls/SKILL.md` — the seven hard rules (init order, IncomingCall mounting, hangup teardown)
-- `cometchat-ios-push/SKILL.md` — chat push (sister, different APNs topic)
-- `cometchat-android-v5-calls/references/server-fcm-voip.md` — Android sibling (FCM HTTP v1)
-- `cometchat-react-calls/references/server-web-push-vapid.md` — Web sibling
-- Apple PushKit: https://developer.apple.com/documentation/pushkit
-- APNs HTTP/2 reference: https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns