@cometchat/skills 4.0.0 → 4.2.0

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

@@ -0,0 +1,290 @@
+# Recording + screen-share on React Native
+
+Both features live in the Calls SDK; both have RN-specific gotchas the kit's defaults don't handle. Sister of `cometchat-react-calls/references/recording-screen-share.md` — same SDK semantics, different platform plumbing for screen capture.
+
+---
+
+## Recording
+
+### Server-side: dashboard gate
+
+Recording is a paid feature on most CometChat plans. Enable in **Dashboard → Chat & Messaging → Calls → Recording**. The client-side flag below is a no-op without it.
+
+### Client-side: opt-in per session
+
+```ts
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+
+const settings = new CometChatCalls.CallSettingsBuilder()
+  .setSessionID(sessionId)
+  .setIsAudioOnly(false)
+  .enableRecording(true)              // server starts recording when session begins
+  .setShowRecordingButton(true)       // user can toggle mid-call (with kit's default UI)
+  .build();
+```
+
+### Recording lifecycle events
+
+```ts
+const listener = new CometChatCalls.OngoingCallListener({
+  onRecordingStarted: () => {
+    // Update UI — show a "REC" indicator (compliance requirement in some jurisdictions)
+    setRecording(true);
+  },
+  onRecordingStopped: () => {
+    setRecording(false);
+  },
+  onRecordingFailed: (error) => {
+    // Surface to UI — usually plan limits or storage quota
+    Alert.alert("Recording failed", error.message);
+  },
+});
+```
+
+### REC indicator (compliance)
+
+In some regions, you must visually notify all participants when recording is active. The kit's default `CometChatOngoingCall` shows a small "Recording" badge. Custom UI must render this:
+
+```tsx
+{recording && (
+  <View style={styles.recBadge}>
+    <Text style={styles.recDot}>●</Text>
+    <Text style={styles.recLabel}>REC</Text>
+  </View>
+)}
+```
+
+Don't omit this — the legal exposure is real (CCPA, GDPR, two-party-consent US states).
+
+### Where the recordings go
+
+CometChat hosts the file. It appears in **Dashboard → Calls → Recordings** with a download link. There is no client-side download API — the file isn't exposed to the device for security/compliance reasons.
+
+For programmatic access:
+
+```ts
+// Server-side — your backend with the dashboard bearer token
+const res = await fetch(
+  `https://${region}.api-management.cometchat.io/v3/apps/${appId}/recordings`,
+  { headers: { Authorization: `Bearer ${dashboardToken}` } },
+);
+const recordings = await res.json();
+```
+
+The skill points users at this REST endpoint; it doesn't generate client code (recordings shouldn't be downloadable from the device).
+
+---
+
+## Screen sharing
+
+Screen capture on RN is platform-specific. iOS uses an iOS Broadcast Extension (separate target); Android uses MediaProjection. Both are exposed by `react-native-webrtc` ≥ 119, which is a peer of the Calls SDK.
+
+### Presenter — start sharing
+
+```ts
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+
+async function startScreenShare() {
+  try {
+    await CometChatCalls.startScreenShare();
+  } catch (err) {
+    if ((err as Error).message.includes("permission")) {
+      Alert.alert("Screen recording permission denied");
+      return;
+    }
+    Alert.alert("Couldn't start screen share");
+  }
+}
+
+async function endScreenShare() {
+  await CometChatCalls.endScreenShare();
+}
+```
+
+### iOS — Broadcast Extension target setup
+
+iOS screen capture requires a separate target in Xcode (a "Broadcast Upload Extension"). The skill walks the user through this manual setup:
+
+1. Xcode → File → New → Target → **Broadcast Upload Extension**
+2. Name: `YourAppBroadcastExtension`
+3. Bundle ID: `com.yourapp.YourAppBroadcastExtension`
+4. Group: `group.com.yourapp.broadcast` (App Group — both targets must opt into this)
+5. Add the App Group capability to BOTH the main target AND the extension
+6. Replace the extension's `SampleHandler.swift` with the WebRTC bridge stub `react-native-webrtc` provides
+7. Add `RPSystemBroadcastPickerView` to your call screen so the user can start/stop sharing via the system UI
+
+The Broadcast Extension picker UI:
+
+```tsx
+// CallScreen.tsx
+import { Platform, requireNativeComponent } from "react-native";
+
+const BroadcastPickerView = Platform.OS === "ios"
+  ? requireNativeComponent<{ preferredExtension: string }>("RPSystemBroadcastPickerView")
+  : null;
+
+export function CallScreen() {
+  return (
+    <View>
+      {/* ... call UI ... */}
+      {Platform.OS === "ios" && BroadcastPickerView && (
+        <BroadcastPickerView preferredExtension="com.yourapp.YourAppBroadcastExtension" />
+      )}
+    </View>
+  );
+}
+```
+
+The picker renders as a small system-styled button. iOS doesn't allow custom UI for screen-share initiation — must use this picker.
+
+### Android — MediaProjection setup
+
+Android is simpler. Add the permission to `AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />   <!-- Android 14+ -->
+```
+
+The screen-share service needs `foregroundServiceType="mediaProjection"`:
+
+```xml
+<service
+  android:name="com.cometchat.calls.ScreenShareService"
+  android:foregroundServiceType="mediaProjection"
+  android:exported="false" />
+```
+
+`react-native-webrtc` registers this internally; verify it's in the merged manifest.
+
+The MediaProjection consent prompt is system-rendered — when `startScreenShare()` is called, Android shows "Start recording or casting with YourApp?". User accepts → screen share begins.
+
+### Viewer — receive screen share
+
+```ts
+const listener = new CometChatCalls.OngoingCallListener({
+  onScreenShareStarted: (presenterUid: string) => {
+    // The kit's default UI auto-renders the screen-share tile.
+    // Custom UI: query the SDK for the screen-share track and pipe into <RTCView />
+    setScreenSharePresenter(presenterUid);
+  },
+  onScreenShareEnded: () => {
+    setScreenSharePresenter(null);
+  },
+});
+```
+
+Custom-UI viewer composition:
+
+```tsx
+function CustomCallView() {
+  const [screenSharePresenter, setScreenSharePresenter] = useState<string | null>(null);
+  const [participants, setParticipants] = useState<Participant[]>([]);
+
+  return (
+    <View style={styles.container}>
+      {screenSharePresenter ? (
+        <ScreenShareView presenterUid={screenSharePresenter} />
+      ) : (
+        <ParticipantTilesGrid participants={participants} />
+      )}
+    </View>
+  );
+}
+```
+
+When someone shares their screen, switch the layout to "screen share + participant strip"; switch back when they stop.
+
+---
+
+## Combining recording + screen-share
+
+Server-side recording captures whatever video composition the SFU is forwarding. When a participant is screen-sharing, the recording shows their screen. When they stop, it switches back to the camera composition.
+
+You don't compose this client-side — the server handles it. Custom UI just needs to render the screen-share track when present.
+
+---
+
+## iOS App Group setup (Broadcast Extension data passing)
+
+The iOS Broadcast Extension runs in a separate process from your main app. To share state (the call's session ID, auth context, etc.):
+
+```
+Both targets in Xcode:
+  Signing & Capabilities → + Capability → App Groups
+  Add: group.com.yourapp.broadcast
+```
+
+In the main app, write to the shared group container:
+
+```swift
+// AppDelegate or CometChat init code (RN bridges this)
+let userDefaults = UserDefaults(suiteName: "group.com.yourapp.broadcast")
+userDefaults?.set(currentSessionID, forKey: "cometchat.sessionID")
+userDefaults?.set(currentAuthToken, forKey: "cometchat.authToken")
+```
+
+In the Broadcast Extension (`SampleHandler.swift`):
+
+```swift
+override func broadcastStarted(withSetupInfo setupInfo: [String : NSObject]?) {
+  let userDefaults = UserDefaults(suiteName: "group.com.yourapp.broadcast")
+  guard let sessionID = userDefaults?.string(forKey: "cometchat.sessionID"),
+        let authToken = userDefaults?.string(forKey: "cometchat.authToken") else {
+    finishBroadcastWithError(NSError(domain: "CometChat", code: 1, userInfo: nil))
+    return
+  }
+  // Initialize the WebRTC bridge with these credentials
+  // (react-native-webrtc handles the heavy lifting)
+}
+```
+
+Without the App Group, the extension can't see the main app's CometChat state — screen capture starts but can't deliver to the call session.
+
+---
+
+## Anti-patterns
+
+1. **iOS without Broadcast Extension** target. Compiles and runs, but `startScreenShare()` returns a "no broadcast extension found" error. Manual Xcode step is required.
+2. **Mismatched App Group identifiers** between targets. Extension can't read the session ID; screen share fails silently.
+3. **Android without `FOREGROUND_SERVICE_MEDIA_PROJECTION` permission** on Android 14+. Service starts → silent crash → screen share dies.
+4. **No "REC" indicator in custom UI.** Compliance violation in two-party-consent jurisdictions.
+5. **Trying to download recordings from the device.** They live on CometChat's servers. Use the dashboard or REST API.
+6. **`enableRecording(true)` without dashboard gate.** Client flag silently no-ops; user thinks recording is active when it isn't.
+7. **Not handling `onScreenShareEnded` in custom UI.** Layout doesn't switch back; viewer sees the last screen-share frame frozen.
+
+---
+
+## Verification checklist
+
+**Recording:**
+- [ ] Dashboard gate enabled (Recording feature on the plan)
+- [ ] `enableRecording(true)` on `CallSettingsBuilder`
+- [ ] `onRecordingStarted` / `onRecordingStopped` listeners wired
+- [ ] "REC" indicator visible to all participants when active
+- [ ] `onRecordingFailed` surfaces to UI
+
+**Screen share:**
+- [ ] iOS: Broadcast Extension target created in Xcode
+- [ ] iOS: App Group capability on BOTH main + extension targets, matching identifiers
+- [ ] iOS: `RPSystemBroadcastPickerView` rendered in call screen
+- [ ] Android: `FOREGROUND_SERVICE_MEDIA_PROJECTION` permission in manifest
+- [ ] Android: ScreenShareService registered with `foregroundServiceType="mediaProjection"`
+- [ ] Custom UI: layout switches to screen-share view on `onScreenShareStarted`
+- [ ] Custom UI: layout switches back on `onScreenShareEnded`
+
+**Real-device smoke:**
+- [ ] iOS: tap broadcast picker → consent → screen share visible to other participants
+- [ ] Android: tap "Share screen" → MediaProjection prompt → screen share begins
+- [ ] Both: end screen share returns to camera view smoothly
+- [ ] Both: recording starts, "REC" shows, recording appears in dashboard within ~30 seconds
+
+---
+
+## Pointers
+
+- `references/custom-ui.md` — building custom call surfaces with screen-share viewer
+- `references/group-calls.md` — group calls + screen share interplay (one share at a time)
+- `references/voip-push-end-to-end.md` — push payloads
+- `cometchat-native-calls` SKILL.md — base hard rules
+- `cometchat-react-calls/references/recording-screen-share.md` — sister web reference (same SDK semantics)

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

@@ -0,0 +1,118 @@
+# 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

@@ -0,0 +1,135 @@
+# 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)