@cometchat/skills 4.4.2 → 5.0.1

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.

package/skills/cometchat-ios-calls/references/voip-cert-setup.md

@@ -1,166 +0,0 @@
-# VoIP cert setup — the manual Apple Developer steps
-
-The skill cannot automate these. They require browser access to https://developer.apple.com and physical possession of the developer team's signing identity. This reference is the printed instruction sheet the dispatcher hands the user.
-
-Print this verbatim during scaffold; pause execution until the user confirms each step.
-
----
-
-## What you're creating
-
-A **VoIP Services certificate** is a separate certificate from your standard APNs (push notifications) certificate. It's specifically for PushKit VoIP delivery — the high-priority, terminated-app-wakeup channel iOS provides for calling apps.
-
-Without this certificate, your push server cannot deliver VoIP pushes. The OS won't ring the user's lock screen. CallKit never fires.
-
----
-
-## Prerequisites
-
-- Apple Developer Program membership (paid — free accounts can't create VoIP certs)
-- Admin or App Manager role in the developer team
-- The bundle ID of your app already registered in https://developer.apple.com/account/resources/identifiers/list
-- Mac with Keychain Access (the cert must be generated from a CSR signed by your dev keychain)
-
----
-
-## Step-by-step
-
-### 1. Generate a Certificate Signing Request
-
-On your Mac:
-
-1. Open **Keychain Access** (`/Applications/Utilities/Keychain Access.app`)
-2. Menu: **Keychain Access → Certificate Assistant → Request a Certificate from a Certificate Authority...**
-3. Fill in:
-   - **User Email Address:** your Apple ID email
-   - **Common Name:** something like "YourApp VoIP CSR"
-   - **CA Email Address:** leave blank
-   - **Request is:** Saved to disk + Let me specify key pair information (check both)
-4. Click Continue → save the `.certSigningRequest` file (e.g. to Desktop)
-5. On the key-pair-info screen: 2048 bits, RSA → Continue → save
-
-### 2. Create the cert in Apple Developer portal
-
-1. Open https://developer.apple.com/account/resources/certificates/list
-2. Click the "+" button to add a new certificate
-3. Under "Services", select **VoIP Services Certificate** → Continue
-4. Pick the App ID (bundle ID) of your app from the dropdown → Continue
-5. Upload the `.certSigningRequest` file you just created → Continue
-6. Apple generates the cert. Click **Download** → saves a `.cer` file (e.g. `voip_services.cer`)
-
-### 3. Install the cert in Keychain
-
-1. Double-click the `.cer` file → Keychain Access opens with the cert added
-2. Find it in the "My Certificates" category — should expand to show a private key alongside
-
-### 4. Export as .p12
-
-1. Right-click the cert → **Export "VoIP Services: ..."**
-2. File Format: **Personal Information Exchange (.p12)**
-3. Save → enter a passphrase (you'll need this on the push server)
-4. Output: a `.p12` file (e.g. `voip_services.p12`)
-
-### 5. (Optional) Convert .p12 to .pem for some push libs
-
-Some Node.js libraries (e.g. `node-apn` older versions) need `.pem`:
-
-```bash
-openssl pkcs12 -in voip_services.p12 -out voip_cert.pem -nodes -clcerts
-```
-
-The `.pem` contains both cert and key.
-
-### 6. Upload to your push server
-
-Where this goes depends on your stack:
-
-- **Node.js (`node-apn` v3+):** point at the `.p12` file via `cert: { path, passphrase }`
-- **Server-side using `apn` lib:** load the cert + key
-- **Self-managed APNs:** use the .p12 directly via `curl` to APNs HTTP/2 endpoint
-- **Third-party services (OneSignal, Firebase APNs forwarding):** they have UIs to upload the .p12 + passphrase
-
----
-
-## Critical detail: the topic
-
-When sending a VoIP push, the APNs `topic` header MUST be your bundle ID **with `.voip` suffix**:
-
-```
-apns-topic: com.yourcompany.yourapp.voip
-```
-
-NOT just `com.yourcompany.yourapp` — that's the standard APNs topic for non-VoIP pushes. The two are separate channels.
-
-If you set the wrong topic, APNs returns `BadDeviceToken` or `TopicMismatch` and your call doesn't ring.
-
-In `node-apn`:
-
-```ts
-const note = new apn.Notification();
-note.topic = `${process.env.IOS_BUNDLE_ID}.voip`;
-note.pushType = "voip";
-```
-
-`pushType: "voip"` is required by APNs HTTP/2 protocol since iOS 13.
-
----
-
-## Cert expiration
-
-VoIP certs expire after **1 year**. Calendar this — Apple will email a warning ~30 days before expiry, but it's easy to miss in inbox noise. When the cert expires:
-
-- iOS devices keep working briefly (cached subscriptions)
-- New incoming-call pushes silently fail
-- Users complain "I'm not getting calls anymore"
-
-Renew by repeating steps 1-6. The new cert can replace the old in your push server with no client-side change required (devices use the same VoIP push token).
-
----
-
-## Bypassing the cert: APNs Auth Tokens (.p8)
-
-Apple now supports **token-based auth** for APNs (since iOS 10) — a `.p8` key + key ID + team ID instead of a per-app cert. Pros:
-
-- Single key works for all your apps (vs one cert per bundle)
-- Doesn't expire (you rotate manually when you want)
-- Easier rotation
-
-Cons:
-
-- Some older push libraries don't support it
-- Setup process is different
-
-To use:
-
-1. Apple Developer portal → Keys → "+" → APNs (Authentication Key)
-2. Download the `.p8` (one-time download — Apple won't let you download it again)
-3. Note the Key ID + Team ID
-4. Configure your push lib with `{ token: { key: ".p8 contents", keyId, teamId } }`
-
-The skill prefers token-auth for new push servers; uses cert auth if the project already has one.
-
----
-
-## When stuck
-
-| Error | Fix |
-|---|---|
-| `BadDeviceToken` from APNs | Topic mismatch — `.voip` suffix missing, or production token used with sandbox cert |
-| `TopicDisallowed` | The cert is for a different bundle ID |
-| `Unregistered` | Token expired or app uninstalled — drop from your DB |
-| `BadCertificate` | Cert expired or tampered — re-export or re-generate |
-| `BadCertificateEnvironment` | Production cert + sandbox token, or vice versa |
-| `Forbidden` | Cert revoked or topic doesn't match |
-
----
-
-## Sandbox vs production
-
-Apple has two APNs environments:
-
-- **Sandbox** (Xcode debug builds, dev provisioning profile) — uses sandbox APNs (api.sandbox.push.apple.com)
-- **Production** (TestFlight + App Store, distribution profile) — uses production APNs (api.push.apple.com)
-
-VoIP cert covers both — the same cert works for sandbox and production tokens. But the SERVER must hit the right endpoint depending on which environment the device token was registered against.
-
-The skill writes the push server with environment switching (`production: process.env.NODE_ENV === "production"` for `node-apn`).