@cometchat/skills 4.4.1 → 5.0.0

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

@@ -1,118 +0,0 @@
-# Ringing — call signaling with custom UI (React Native)
-
-Same SDK shape as web; RN-specific deltas: navigation-aware listener mount, CallKeep + VoIP push for backgrounded ring delivery, audio file paths via require.
-
-**Read first:** `cometchat-react-calls/references/ringing-integration.md` — full architecture, hard rules, web reference.
-
----
-
-## SDK API
-
-```ts
-import { CometChat } from "@cometchat/chat-sdk-react-native";
-import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
-
-const call = new CometChat.Call(
-  receiverUid,
-  CometChat.CALL_TYPE.VIDEO,
-  CometChat.RECEIVER_TYPE.USER,
-);
-const outgoingCall = await CometChat.initiateCall(call, 60);
-```
-
----
-
-## Listener mount: at NavigationContainer root, NOT inside a screen
-
-```tsx
-// App.tsx — sibling of NavigationContainer's content
-import { useEffect } from "react";
-import { NavigationContainer } from "@react-navigation/native";
-
-export default function App() {
-  useCometChatCallListener();
-  return (
-    <NavigationContainer>
-      <RootNavigator />
-    </NavigationContainer>
-  );
-}
-
-function useCometChatCallListener() {
-  useEffect(() => {
-    CometChat.addCallListener("app", new CometChat.CallListener({
-      onIncomingCallReceived: (call) => navigationRef.current?.navigate("IncomingCall", { call }),
-      onOutgoingCallAccepted: (call) => navigationRef.current?.navigate("ActiveCall", { sessionId: call.getSessionId() }),
-      onIncomingCallCancelled: () => navigationRef.current?.goBack(),
-      onOutgoingCallRejected: () => navigationRef.current?.goBack(),
-      onCallEndedMessageReceived: () => navigationRef.current?.popToTop(),
-    }));
-    return () => CometChat.removeCallListener("app");
-  }, []);
-}
-```
-
-Use a `navigationRef` (per `@react-navigation/native` docs) so listener callbacks can navigate without prop-drilling.
-
----
-
-## Backgrounded ring delivery — VoIP push is the bridge
-
-When the app is backgrounded or killed, `addCallListener` doesn't fire — the JS bundle isn't running. **VoIP push** wakes the app + surfaces the ring via CallKit (iOS) / ConnectionService (Android). On accept, route the user to the same screen the foreground listener would.
-
-Wire VoIP push per `cometchat-native-calls/references/server-push-bridge.md`. Server fires push → CallKeep shows OS-level UI → user taps Accept → app launches/foregrounds → call session starts.
-
----
-
-## Ringtone via expo-av or react-native-sound
-
-```tsx
-import { Audio } from "expo-av";  // Expo
-// OR: import Sound from "react-native-sound";
-
-let ringtoneSound: Audio.Sound | null = null;
-
-async function playRingtone() {
-  ringtoneSound = new Audio.Sound();
-  await ringtoneSound.loadAsync(require("../assets/ringtone.mp3"));
-  await ringtoneSound.setIsLoopingAsync(true);
-  await ringtoneSound.playAsync();
-}
-
-async function stopRingtone() {
-  await ringtoneSound?.stopAsync();
-  await ringtoneSound?.unloadAsync();
-  ringtoneSound = null;
-}
-```
-
-For backgrounded ring, **don't** play ringtone from JS — CallKit/ConnectionService plays the system ringtone. JS-side ringtone is for in-foreground ringing only.
-
----
-
-## Anti-patterns
-
-Web sister rules apply, plus RN-specific:
-
-1. **`addCallListener` inside a screen component.** Listener tears down on screen unmount → backgrounded calls miss.
-2. **Expecting `addCallListener` to fire when app is killed.** It doesn't — VoIP push is the only way. If you skipped VoIP push, your "background ring" doesn't work.
-3. **Playing JS ringtone during a CallKit/ConnectionService ring.** Two ringtones at once. Suppress JS-side when OS UI is active.
-
----
-
-## Verification checklist
-
-- [ ] Listener registered at NavigationContainer level
-- [ ] navigationRef wired (forwards refs from listener callbacks)
-- [ ] VoIP push registered for backgrounded ring delivery
-- [ ] Ringtone plays in foreground only (suppressed when CallKit/ConnectionService active)
-- [ ] Real-device smoke: 2 phones, foreground ring, backgrounded ring, killed-app ring all work
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/ringing-integration.md` — canonical (architecture + hard rules)
-- `cometchat-native-calls/SKILL.md` — RN seven hard rules
-- `cometchat-native-calls/references/server-push-bridge.md` — VoIP push for backgrounded ring
-- Canonical docs: https://www.cometchat.com/docs/calls/react-native/ringing

package/skills/cometchat-native-calls/references/server-push-bridge.md

@@ -1,135 +0,0 @@
-# Server-side push routing for React Native (iOS PushKit + Android FCM)
-
-React Native projects target iOS and Android — your server needs to dispatch the right kind of push to each platform. Use the iOS canonical (APNs PushKit + .p8) for iPhone tokens and the Android canonical (FCM HTTP v1 + service account) for Android tokens.
-
-**Canonical docs:**
-- iOS: `cometchat-ios-calls/references/server-apns-pushkit.md`
-- Android: `cometchat-android-v5-calls/references/server-fcm-voip.md`
-
----
-
-## Token registration (RN client)
-
-```tsx
-// On app start, after CometChat login completes
-import VoipPushNotification from "react-native-voip-push-notification";
-import messaging from "@react-native-firebase/messaging";
-import { Platform } from "react-native";
-
-async function registerCallPushTokens(userUid: string) {
-  if (Platform.OS === "ios") {
-    VoipPushNotification.addEventListener("register", async (token) => {
-      await api.registerCallToken({
-        uid: userUid,
-        platform: "ios-voip",
-        token,
-      });
-    });
-    VoipPushNotification.addEventListener("notification", (payload) => {
-      // CallKeep takes over from here — see cometchat-native-calls/SKILL.md rule 4
-    });
-    VoipPushNotification.registerVoipToken();
-  } else if (Platform.OS === "android") {
-    await messaging().requestPermission();
-    const fcmToken = await messaging().getToken();
-    await api.registerCallToken({
-      uid: userUid,
-      platform: "android-fcm",
-      token: fcmToken,
-    });
-
-    messaging().onTokenRefresh(async (newToken) => {
-      await api.registerCallToken({
-        uid: userUid,
-        platform: "android-fcm",
-        token: newToken,
-      });
-    });
-  }
-}
-```
-
----
-
-## Server-side dispatcher
-
-Single webhook handler routes by platform:
-
-```js
-import { sendVoipPush as sendApns } from "./apns-pushkit.js";   // iOS canonical template
-import { sendAndroidVoipPush } from "./fcm-voip.js";             // Android canonical template
-
-app.post("/webhooks/call", verifyCometChatWebhook, async (req, res) => {
-  if (req.body.trigger !== "call_initiated") return res.status(200).end();
-
-  const { sessionId, type, initiator, receiver } = req.body.data;
-  const tokens = await db.getActiveCallTokens(receiver.uid);  // returns [{platform, token}, ...]
-
-  // Fan out to all the user's devices in parallel
-  const sends = tokens.map((t) => {
-    const payload = {
-      recipientUid: receiver.uid,
-      sessionId,
-      callerName: initiator.name,
-      callerUid: initiator.uid,
-      callType: type,
-    };
-    if (t.platform === "ios-voip") return sendApns({ ...payload, pushKitToken: t.token });
-    if (t.platform === "android-fcm") return sendAndroidVoipPush({ ...payload, fcmToken: t.token });
-    return Promise.resolve();
-  });
-
-  await Promise.allSettled(sends);
-  res.status(200).end();
-});
-```
-
----
-
-## Schema for tokens
-
-```sql
-CREATE TABLE call_push_tokens (
-  uid          text NOT NULL,
-  platform     text NOT NULL CHECK (platform IN ('ios-voip', 'android-fcm')),
-  token        text NOT NULL,
-  device_id    text,
-  registered_at timestamptz NOT NULL DEFAULT now(),
-  PRIMARY KEY (uid, platform, token)
-);
-
-CREATE INDEX idx_call_push_tokens_uid ON call_push_tokens(uid);
-```
-
-Why include `device_id`: a user may have iPhone + iPad + Android tablet. Allow multiple tokens per (uid, platform).
-
----
-
-## Anti-patterns
-
-iOS + Android sister rules apply, plus RN-specific:
-
-1. **Single token table without `platform` column.** Can't tell which dispatcher to use → wrong push API → silent failure.
-2. **Registering FCM token before login.** No user UID, can't store correctly. Register tokens AFTER `CometChat.login` resolves.
-3. **Forgetting `messaging().onTokenRefresh`.** FCM tokens rotate every few months. Without refresh, push silently breaks.
-4. **Returning the Promise.allSettled to the webhook caller.** CometChat retries on slow/failed webhooks; awaiting all pushes can block 5+ seconds. Use a queue (BullMQ/SQS): enqueue job, return 200 immediately.
-
----
-
-## Verification checklist
-
-- [ ] iOS: VoipPushNotification configured + token registered post-login
-- [ ] Android: messaging() permission requested + token registered + onTokenRefresh handler
-- [ ] Server has both apns-pushkit + fcm-voip dispatchers wired
-- [ ] Webhook returns 200 within 1s (push enqueued)
-- [ ] Token table supports multiple devices per user
-- [ ] Real-device smoke: iPhone + Android both ring when caller dials
-
----
-
-## Pointers
-
-- `cometchat-ios-calls/references/server-apns-pushkit.md` — iOS canonical
-- `cometchat-android-v5-calls/references/server-fcm-voip.md` — Android canonical
-- `cometchat-native-calls` SKILL.md — RN seven hard rules (CallKeep + VoipPush wiring)
-- `cometchat-native-push/SKILL.md` — chat push (sister, different payload)

package/skills/cometchat-native-calls/references/server-push-payloads.md

@@ -1,193 +0,0 @@
-# Server-side push payloads for RN calls
-
-The RN client only handles received pushes. The server side — building and sending the payloads — is yours to implement. This reference is a copy-paste-ready Node.js example the skill points users at.
-
----
-
-## What the server has to do
-
-1. Subscribe to CometChat's `call.received` webhook (Dashboard → Webhooks)
-2. When fired, look up the receiver UID's stored push tokens (PushKit + FCM)
-3. Send a VoIP-shaped payload to each platform with the right priority + cert
-
-Two endpoints, two payload shapes, one webhook. Simple but easy to get wrong.
-
----
-
-## Express skeleton
-
-```ts
-// server/push-handler.ts
-import express from "express";
-import apn from "node-apn";                                  // npm i node-apn
-import admin from "firebase-admin";                          // npm i firebase-admin
-
-const app = express();
-app.use(express.json());
-
-// Initialize APNs (PushKit) provider with your VoIP cert
-const voipCert = apn.Provider({
-  token: undefined,
-  cert: process.env.APNS_VOIP_CERT_PATH,                    // path to your VoIP .p12 / .pem
-  key: process.env.APNS_VOIP_KEY_PATH,
-  passphrase: process.env.APNS_VOIP_PASSPHRASE,
-  production: process.env.NODE_ENV === "production",
-});
-
-// Initialize Firebase Admin
-admin.initializeApp({
-  credential: admin.credential.cert({
-    projectId: process.env.FIREBASE_PROJECT_ID!,
-    clientEmail: process.env.FIREBASE_CLIENT_EMAIL!,
-    privateKey: process.env.FIREBASE_PRIVATE_KEY!.replace(/\\n/g, "\n"),
-  }),
-});
-
-// CometChat webhook — fired when a call is initiated
-app.post("/webhook/cometchat/call-received", async (req, res) => {
-  const { receiver, sender, sessionId, type } = req.body.data;
-  const subs = await getPushSubscriptionsForUid(receiver);  // your DB
-
-  await Promise.allSettled([
-    ...subs.ios.map((token) => sendIOSVoip(token, { sessionId, callerName: sender.name, callerUid: sender.uid, callType: type })),
-    ...subs.android.map((token) => sendAndroidVoip(token, { sessionId, callerName: sender.name, callerUid: sender.uid, callType: type })),
-  ]);
-
-  res.status(200).send({ ok: true });
-});
-
-async function sendIOSVoip(token: string, payload: { sessionId: string; callerName: string; callerUid: string; callType: string }) {
-  const note = new apn.Notification();
-  note.topic = `${process.env.IOS_BUNDLE_ID}.voip`;          // CRITICAL: voip topic, not the bundle id
-  note.pushType = "voip";                                     // CRITICAL
-  note.priority = 10;
-  note.expiry = Math.floor(Date.now() / 1000) + 30;          // expire in 30s — call rings or doesn't
-  note.payload = {
-    "content-available": 1,
-    data: payload,
-  };
-
-  const result = await voipCert.send(note, token);
-  if (result.failed.length > 0) {
-    console.error("PushKit send failed:", result.failed);
-  }
-}
-
-async function sendAndroidVoip(token: string, payload: { sessionId: string; callerName: string; callerUid: string; callType: string }) {
-  await admin.messaging().send({
-    token,
-    android: {
-      priority: "high",                                       // CRITICAL — without this, FCM may delay
-      ttl: 30 * 1000,                                         // 30s TTL
-    },
-    data: {                                                   // CRITICAL — `data`, not `notification`
-      type: "incoming_call",
-      sessionId: payload.sessionId,
-      callerName: payload.callerName,
-      callerUid: payload.callerUid,
-      callType: payload.callType,
-    },
-  });
-}
-
-app.listen(3000);
-```
-
-The skill writes this file as `server/push.example.ts` next to a README pointing at the env vars + cert paths.
-
----
-
-## Token registration endpoint
-
-The client sends its tokens to your server when the user logs in:
-
-```ts
-// Client side
-import VoipPushNotification from "react-native-voip-push-notification";
-import messaging from "@react-native-firebase/messaging";
-
-async function registerPushTokens(cometchatUid: string) {
-  if (Platform.OS === "ios") {
-    VoipPushNotification.addEventListener("register", async (token) => {
-      await fetch("/api/push/register", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ uid: cometchatUid, platform: "ios", token }),
-      });
-    });
-    VoipPushNotification.registerVoipToken();
-  } else {
-    const token = await messaging().getToken();
-    await fetch("/api/push/register", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ uid: cometchatUid, platform: "android", token }),
-    });
-  }
-}
-```
-
-Server stores tokens keyed by `(cometchatUid, platform)`. On logout, call `/api/push/unregister` to clean up.
-
----
-
-## Token rotation
-
-Both PushKit and FCM tokens can rotate without warning (OS upgrades, app reinstalls, expirations).
-
-- iOS PushKit: handle `didInvalidatePushToken` and re-register
-- FCM: handle `messaging().onTokenRefresh` and re-register
-
-```ts
-// iOS
-VoipPushNotification.addEventListener("didInvalidatePushToken", async () => {
-  // wait for next register event, will fire automatically
-});
-
-// Android
-messaging().onTokenRefresh(async (newToken) => {
-  await fetch("/api/push/register", {
-    method: "POST",
-    body: JSON.stringify({ uid: getCurrentUid(), platform: "android", token: newToken }),
-  });
-});
-```
-
----
-
-## Webhook verification
-
-CometChat signs webhooks. Verify the signature before trusting payloads:
-
-```ts
-import crypto from "crypto";
-
-app.post("/webhook/cometchat/call-received", (req, res, next) => {
-  const signature = req.header("x-cometchat-signature");
-  const expected = crypto
-    .createHmac("sha256", process.env.COMETCHAT_WEBHOOK_SECRET!)
-    .update(JSON.stringify(req.body))
-    .digest("hex");
-  if (signature !== expected) return res.status(401).send({ error: "invalid signature" });
-  next();
-});
-```
-
-Without this, anyone with your endpoint URL can ring your users.
-
----
-
-## Rate limits
-
-- **APNs:** 4000 notifications/sec per cert. Far above what an app needs for VoIP.
-- **FCM:** 1000 tokens per `send()` call (use `sendMulticast` for batches). Per-token rate limits not enforced strictly.
-
-For one-call-at-a-time semantics, you won't hit either. For broadcast scenarios (multi-party "ring everyone"), batch sends instead of looping `send()`.
-
----
-
-## Testing the server locally
-
-ngrok the webhook endpoint to a public URL, register it in CometChat dashboard. Two real devices (one iOS, one Android) on real networks. Trigger a call from device A to device B; watch the server logs for the webhook fire and the push send.
-
-For unit tests, mock the apn + firebase-admin modules. Don't try to test real APNs/FCM in CI — certs and rate limits make it hostile.

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

@@ -1,146 +0,0 @@
-# Share invite on React Native
-
-Same SDK API as web. RN-specific: use the platform's native share sheet via `Share.share()` (built into RN) or `react-native-share` for richer options.
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/react-native/share-invite
-**Read first:** `cometchat-react-calls/references/share-invite.md` — deep-link routing rule + dialog UX.
-
----
-
-## Hard rule: deep-link routing
-
-Same rule as web. Configure your app's URL scheme + universal/app links so `https://yourapp.com/call/:sessionId` opens the app:
-
-```tsx
-// App.tsx — react-navigation linking config
-const linking = {
-  prefixes: ["https://yourapp.com", "yourapp://"],
-  config: {
-    screens: {
-      Call: "call/:sessionId",
-    },
-  },
-};
-
-<NavigationContainer linking={linking}>
-  {/* ... */}
-</NavigationContainer>
-```
-
-iOS: configure Associated Domains entitlement.
-Android: add `<intent-filter>` with `android:autoVerify="true"` to `AndroidManifest.xml`.
-
-Without these, share-invite URLs land in browser, not the app.
-
----
-
-## SDK API
-
-```ts
-import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
-
-// SessionSettings OBJECT field — there is NO setHideShareInviteButton builder method:
-const callSettings = {
-  hideShareInviteButton: false,
-};
-
-useEffect(() => {
-  const handler = () => shareCallInvite(sessionId);
-  // addEventListener returns the unsubscribe fn — call it on cleanup.
-  const off = CometChatCalls.addEventListener("onShareInviteButtonClicked", handler);
-  return () => off();
-}, [sessionId]);
-```
-
----
-
-## Native share sheet
-
-RN ships `Share` from `react-native`:
-
-```tsx
-import { Share, Platform } from "react-native";
-
-async function shareCallInvite(sessionId: string) {
-  const url = `https://yourapp.com/call/${sessionId}`;
-  const message = "I'm on a call — tap to join.";
-
-  try {
-    const result = await Share.share({
-      url: Platform.OS === "ios" ? url : undefined,  // iOS prefers `url`
-      message: Platform.OS === "android" ? `${message}\n${url}` : message,
-      title: "Join my call",  // Android only
-    });
-
-    if (result.action === Share.dismissedAction) {
-      // User cancelled — silent
-    }
-  } catch (err) {
-    console.warn("Share failed", err);
-  }
-}
-```
-
-`Share.share` opens iOS UIActivityViewController and Android's chooser intent. For both: pass `url` on iOS (separate field), append URL to `message` on Android (the `url` field is iOS-only).
-
----
-
-## Clipboard fallback
-
-```tsx
-import Clipboard from "@react-native-clipboard/clipboard";
-import { Alert } from "react-native";
-
-async function copyLink(url: string) {
-  Clipboard.setString(url);
-  Alert.alert("Copied", "Call link copied to clipboard");
-}
-```
-
-Most apps don't need this — `Share.share` always succeeds, even if no targets are available it shows the system "no apps installed" toast. Clipboard is a nice-to-have alongside the share sheet, not a fallback.
-
----
-
-## react-native-share for richer UX
-
-For per-channel buttons (just WhatsApp, just SMS, etc.):
-
-```tsx
-import Share from "react-native-share";
-
-await Share.shareSingle({
-  social: Share.Social.WHATSAPP,
-  message: "Join my call",
-  url: callLink,
-});
-```
-
-Use only if your UX requires it. Native share sheet is usually enough.
-
----
-
-## Anti-patterns
-
-Web sister rules apply, plus RN-specific:
-
-1. **Setting `url` on Android Share.share.** Android ignores it; URL doesn't appear in shared content. Concat to `message` instead.
-2. **No deep-link config.** URL opens in browser → web fallback or 404.
-3. **Sharing without `await`.** Caller doesn't know if the user cancelled, success messaging fires for cancelled shares.
-
----
-
-## Verification checklist
-
-- [ ] `react-navigation` `linking` config maps `/call/:sessionId`
-- [ ] Universal links (iOS) + auto-verified app links (Android) configured
-- [ ] `Share.share` URL field passed on iOS, concat'd to message on Android
-- [ ] Listener cleaned up on unmount
-- [ ] Real-device smoke: share via WhatsApp/Messages → tap → opens your app at the call
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/share-invite.md` — sister
-- `cometchat-native-calls` SKILL.md
-- Canonical docs: https://www.cometchat.com/docs/calls/react-native/share-invite