@cometchat/skills 4.4.1 → 5.0.0

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

package/skills/cometchat-ios-calls/references/share-invite.md

@@ -1,148 +0,0 @@
-# Share invite on iOS
-
-Same SDK API. iOS-specific: `UIActivityViewController` is the native share sheet (handles iMessage, Mail, AirDrop, third-party apps). Universal Links must be configured for the call link to deep into the app.
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/ios/share-invite
-**Read first:** `cometchat-react-calls/references/share-invite.md` — deep-link rule + share dialog UX.
-
----
-
-## Hard rule: Universal Links + apple-app-site-association
-
-For `https://yourapp.com/call/SESSION_ID` to open your app:
-
-1. Add `Associated Domains` capability with `applinks:yourapp.com`
-2. Host `apple-app-site-association` JSON at `https://yourapp.com/.well-known/apple-app-site-association`:
-
-```json
-{
-  "applinks": {
-    "apps": [],
-    "details": [{
-      "appID": "TEAMID.com.yourapp.bundle",
-      "paths": ["/call/*"]
-    }]
-  }
-}
-```
-
-3. In `SceneDelegate` / `AppDelegate`, handle `NSUserActivity` with `activityType == NSUserActivityTypeBrowsingWeb`:
-
-```swift
-func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
-  guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
-        let url = userActivity.webpageURL,
-        url.pathComponents.count >= 3,
-        url.pathComponents[1] == "call" else { return }
-  let sessionId = url.pathComponents[2]
-  router.routeToCall(sessionId: sessionId)
-}
-```
-
-Without these, share-invite URLs open in Safari instead of your app.
-
----
-
-## No SDK share-invite button — build your own
-
-> The iOS Calls SDK v5 has **no** share-invite affordance. There is no `setHideShareInviteButton` on `CallSettingsBuilder` and no `onShareInviteButtonClicked` callback on `CallsEventsDelegate`. Share-invite is an app-level feature: add your own button to your call UI and present a `UIActivityViewController` over the session's deep link (below).
-
-```swift
-// Your own button in the call control panel:
-let inviteButton = UIButton(type: .system)
-inviteButton.addAction(UIAction { [weak self] _ in
-  self?.shareCallInvite()      // already on main
-}, for: .touchUpInside)
-```
-
----
-
-## UIActivityViewController
-
-```swift
-extension CallViewController {
-  func shareCallInvite() {
-    let url = URL(string: "https://yourapp.com/call/\(sessionId)")!
-    let title = "Join my call"
-    let text = "I'm on a call — tap to join."
-
-    let items: [Any] = [text, url]
-    let activityVC = UIActivityViewController(
-      activityItems: items,
-      applicationActivities: nil
-    )
-
-    // Optional: exclude activities you don't want
-    activityVC.excludedActivityTypes = [.assignToContact, .saveToCameraRoll]
-
-    // iPad: must set source for popover
-    if let popover = activityVC.popoverPresentationController {
-      popover.sourceView = self.view
-      popover.sourceRect = CGRect(
-        x: self.view.bounds.midX,
-        y: self.view.bounds.midY,
-        width: 0,
-        height: 0
-      )
-      popover.permittedArrowDirections = []
-    }
-
-    present(activityVC, animated: true)
-  }
-}
-```
-
-iOS auto-renders link preview if your URL has Open Graph tags + universal-link routing — the share sheet shows app icon + name + "Join my call" instead of a raw URL.
-
----
-
-## SwiftUI ShareLink (iOS 16+)
-
-If you build the share button yourself in SwiftUI:
-
-```swift
-import SwiftUI
-
-struct CallShareButton: View {
-  let sessionId: String
-
-  var body: some View {
-    let url = URL(string: "https://yourapp.com/call/\(sessionId)")!
-    ShareLink(item: url, subject: Text("Join my call"), message: Text("I'm on a call — tap to join.")) {
-      Label("Share invite", systemImage: "square.and.arrow.up")
-    }
-  }
-}
-```
-
----
-
-## Anti-patterns
-
-Web sister rules apply, plus iOS-specific:
-
-1. **iPad without `popoverPresentationController.sourceView`.** Crashes on iPad — popover requires an anchor.
-2. **`UIPasteboard.general.string = url.absoluteString` instead of UIActivityVC.** Skips iOS's curated share sheet — bad UX.
-3. **Universal Links not configured.** Recipients tap link → opens Safari, not your app.
-4. **`activityItems: [url]` without title text.** Recipients see just a URL, no context.
-5. **Presenting from background queue.** Crash. Always main.
-
----
-
-## Verification checklist
-
-- [ ] Associated Domains entitlement added
-- [ ] `apple-app-site-association` JSON hosted + reachable
-- [ ] `NSUserActivity` continuation in SceneDelegate routes to call
-- [ ] `UIActivityViewController` (UIKit) or `ShareLink` (SwiftUI 16+) used
-- [ ] iPad popover anchored
-- [ ] Real-device smoke: share via Messages → tap from another iPhone → opens your app at call
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/share-invite.md` — sister
-- `cometchat-ios-calls` SKILL.md — seven hard rules
-- `references/universal-links.md`
-- Canonical docs: https://www.cometchat.com/docs/calls/ios/share-invite

package/skills/cometchat-ios-calls/references/swiftui-uikit-hosting.md

@@ -1,246 +0,0 @@
-# SwiftUI + UIKit hosting for iOS calls
-
-CometChat's iOS Calls UI Kit ships UIKit `UIViewController`s. SwiftUI apps host them via `UIViewControllerRepresentable`. Mixed projects (SwiftUI app shell with UIKit feature screens) work natively.
-
----
-
-## Pure UIKit project — direct usage
-
-```swift
-import UIKit
-import CometChatUIKitSwift
-
-class ProfileViewController: UIViewController {
-  override func viewDidLoad() {
-    super.viewDidLoad()
-
-    let callButton = CometChatCallButtons(width: 100, height: 44).set(user: user)  // class is plural; user via .set(user:), no (user:) init
-    callButton.translatesAutoresizingMaskIntoConstraints = false
-    view.addSubview(callButton)
-    NSLayoutConstraint.activate([
-      callButton.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -16),
-      callButton.centerYAnchor.constraint(equalTo: nameLabel.centerYAnchor),
-    ])
-  }
-}
-```
-
-For ongoing call:
-
-```swift
-let ongoingCallVC = CometChatOngoingCall()
-ongoingCallVC.set(sessionID: sessionId)
-present(ongoingCallVC, animated: true)
-```
-
----
-
-## Pure SwiftUI project — UIViewControllerRepresentable
-
-Wrap each UIKit VC in a SwiftUI view:
-
-```swift
-import SwiftUI
-import CometChatUIKitSwift
-
-struct CallButtonView: UIViewRepresentable {
-  let user: User
-
-  func makeUIView(context: Context) -> CometChatCallButtons {
-    CometChatCallButtons(width: 100, height: 44).set(user: user)
-  }
-
-  func updateUIView(_ uiView: CometChatCallButtons, context: Context) {
-    // Re-bind on user change if your view supports that
-  }
-}
-
-struct OngoingCallView: UIViewControllerRepresentable {
-  let sessionID: String
-  @Binding var isPresented: Bool
-
-  func makeUIViewController(context: Context) -> CometChatOngoingCall {
-    let vc = CometChatOngoingCall()
-    vc.set(sessionID: sessionID)
-    return vc
-  }
-
-  func updateUIViewController(_ vc: CometChatOngoingCall, context: Context) {}
-}
-
-struct CallLogsView: UIViewControllerRepresentable {
-  func makeUIViewController(context: Context) -> CometChatCallLogs {
-    CometChatCallLogs()
-  }
-
-  func updateUIViewController(_ vc: CometChatCallLogs, context: Context) {}
-}
-```
-
-Use them like any SwiftUI view:
-
-```swift
-struct ProfileView: View {
-  let user: User
-  @State private var ongoingSessionID: String?
-
-  var body: some View {
-    VStack {
-      Text(user.name)
-      CallButtonView(user: user)
-        .frame(width: 100, height: 44)
-    }
-    .fullScreenCover(isPresented: Binding(
-      get: { ongoingSessionID != nil },
-      set: { if !$0 { ongoingSessionID = nil } }
-    )) {
-      if let id = ongoingSessionID {
-        OngoingCallView(sessionID: id, isPresented: Binding(
-          get: { true }, set: { _ in ongoingSessionID = nil }
-        ))
-      }
-    }
-  }
-}
-```
-
----
-
-## Mixed-stack — SwiftUI app, UIKit feature screen
-
-Common in apps that started UIKit and adopted SwiftUI for new features. Calls can stay UIKit; chat can be SwiftUI; both interop.
-
-```swift
-// SwiftUI screen pushing a UIKit call screen via UIHostingController bridge
-import SwiftUI
-
-struct ChatView: View {
-  let user: User
-
-  var body: some View {
-    NavigationLink(destination: UIKitCallScreenWrapper(user: user)) {
-      Text("Start call")
-    }
-  }
-}
-
-struct UIKitCallScreenWrapper: UIViewControllerRepresentable {
-  let user: User
-
-  func makeUIViewController(context: Context) -> UINavigationController {
-    let vc = OngoingCallViewController(user: user)   // your custom UIKit VC
-    return UINavigationController(rootViewController: vc)
-  }
-
-  func updateUIViewController(_ vc: UINavigationController, context: Context) {}
-}
-```
-
----
-
-## Where the IncomingCall UI goes (additive mode)
-
-In standalone mode, **CallKit owns the incoming-call UI** — no in-app rendering needed.
-
-In additive mode (chat already integrated and user is foregrounded when a call comes in), the kit's `CometChatIncomingCall` view can render. Mount it at the root:
-
-### SwiftUI app — root mount
-
-```swift
-@main
-struct YourApp: App {
-  @StateObject private var callState = CallState.shared
-
-  var body: some Scene {
-    WindowGroup {
-      ZStack {
-        ContentView()
-        if let call = callState.foregroundIncomingCall {
-          IncomingCallView(call: call, callState: callState)
-            .transition(.move(edge: .top))
-        }
-      }
-    }
-  }
-}
-
-struct IncomingCallView: UIViewControllerRepresentable {
-  let call: Call
-  let callState: CallState
-
-  func makeUIViewController(context: Context) -> CometChatIncomingCall {
-    let vc = CometChatIncomingCall()
-    vc.set(call: call)
-    vc.setOnAccept { [weak callState] _ in callState?.accept(call) }
-    vc.setOnDecline { [weak callState] _ in callState?.decline(call) }
-    return vc
-  }
-
-  func updateUIViewController(_ vc: CometChatIncomingCall, context: Context) {}
-}
-```
-
-### UIKit app — present from root window
-
-```swift
-class CallObserver: NSObject {
-  func showIncomingCallUI(call: Call) {
-    let vc = CometChatIncomingCall()
-    vc.set(call: call)
-    UIApplication.shared.windows.first?.rootViewController?.present(vc, animated: true)
-  }
-}
-```
-
-In standalone, neither — CallKit handles it.
-
----
-
-## When to use SwiftUI navigation vs UIKit modal
-
-For ongoing calls specifically, **modal full-screen** is the right pattern on both stacks:
-
-- SwiftUI: `.fullScreenCover(isPresented:)` (NOT `.sheet`, which is dismissable by swipe)
-- UIKit: `present(_:animated:)` with `vc.modalPresentationStyle = .fullScreen`
-
-Reason: in-call UI shouldn't be navigable-back-to (the user shouldn't accidentally swipe-down and lose the call view). Full-screen modal forces explicit "End" button to dismiss.
-
----
-
-## CometChatUIKit init for SwiftUI
-
-Init in `App.init()`:
-
-```swift
-@main
-struct YourApp: App {
-  init() {
-    let settings = UIKitSettings()
-      .set(appID: Secrets.cometchatAppID)
-      .set(region: Secrets.cometchatRegion)
-      .set(authKey: Secrets.cometchatAuthKey)
-      .subscribePresenceForAllUsers()
-      .build()
-
-    CometChatUIKit.init(uiKitSettings: settings) { result in
-      switch result {
-      case .success: print("Init OK")
-      case .onError(let error): print("Init failed: \(error)")
-      }
-    }
-  }
-
-  var body: some Scene { /* ... */ }
-}
-```
-
-Reference `cometchat-ios-core` for the full init pattern with login.
-
----
-
-## Things that don't work cleanly in SwiftUI
-
-- **Custom theming via Storyboard inspection** — UIKit-only. SwiftUI projects override theme via `CometChatTheme` API in code (see `cometchat-ios-theming`).
-- **NavigationLink to a `CometChat*` VC without representable wrapper** — must wrap.
-- **Sharing UIKit and SwiftUI navigation stacks** — possible but messy. Pick one for any single feature.
-- **Presenting `CometChatIncomingCall` from a SwiftUI sheet** — sheets dismiss on swipe; calls shouldn't. Use `fullScreenCover` or a manually-rendered ZStack overlay.