@cometchat/skills 4.0.0 → 4.2.0

package/skills/cometchat-native-calls/references/custom-ui.md

@@ -0,0 +1,250 @@
+# Custom call UI on React Native
+
+Two paths:
+
+1. **Style the kit's `<CometChatOngoingCall />`** — pass style props. Cheapest. Path-of-least-resistance for 80% of apps.
+2. **Render `<CometChatCalls.Component callToken={...} />` with the SDK's default-UI elements hidden, then overlay your own controls.** This is the canonical RN custom-UI path — the SDK's Component handles WebRTC + tile rendering; your code controls the chrome.
+
+This reference covers path 2.
+
+> **Note on raw WebRTC bypass:** Earlier versions of this skill suggested using `react-native-webrtc`'s `<RTCView />` directly with `CometChatCalls.startSession`. That API does NOT exist on RN session mode — the SDK exposes only the declarative `<CometChatCalls.Component>` primitive. The example below shows the supported pattern.
+
+---
+
+## Architecture
+
+```
+Your screen component
+├── <RTCView /> for local user (preview + during call)
+├── <RTCView /> for remote participant(s)
+├── Custom control panel (mute / camera / end / switch)
+└── Custom layout (Stack / Modal / etc.)
+```
+
+`react-native-webrtc` ships `<RTCView />` — a native view that renders a `MediaStream` directly. The Calls SDK pipes streams to it through events.
+
+---
+
+## Required peer deps for custom UI
+
+```bash
+npm install react-native-webrtc react-native-incall-manager
+```
+
+`react-native-incall-manager` handles audio routing (speaker vs earpiece, Bluetooth, AirPods) — without it, voice calls default to earpiece-only and the user can't switch to speaker.
+
+---
+
+## Custom OngoingCallScreen
+
+```tsx
+import { useEffect, useRef, useState } from "react";
+import { View, StyleSheet } from "react-native";
+import { RTCView, MediaStream } from "react-native-webrtc";
+import InCallManager from "react-native-incall-manager";
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+import { ControlPanel } from "./ControlPanel";
+
+interface Props {
+  sessionId: string;
+  authToken: string;
+  isAudioOnly: boolean;
+  onCallEnded: () => void;
+}
+
+export function CustomOngoingCallScreen({ sessionId, authToken, isAudioOnly, onCallEnded }: Props) {
+  const [localStream, setLocalStream] = useState<MediaStream | null>(null);
+  const [remoteStream, setRemoteStream] = useState<MediaStream | null>(null);
+  const [muted, setMuted] = useState(false);
+  const [cameraOff, setCameraOff] = useState(false);
+
+  const [callToken, setCallToken] = useState<string | null>(null);
+
+  useEffect(() => {
+    InCallManager.start({ media: isAudioOnly ? "audio" : "video" });
+    if (!isAudioOnly) InCallManager.setForceSpeakerphoneOn(true);
+
+    // Subscribe to lifecycle events. Use the v5 addEventListener API,
+    // not the deprecated OngoingCallListener.
+    const offClosed = CometChatCalls.addEventListener("onConnectionClosed", () => {
+      cleanup();
+      onCallEnded();
+    });
+
+    // Mint a fresh token for this session (v5 — generateToken takes only sessionId).
+    CometChatCalls.generateToken(sessionId).then(({ token }) => {
+      setCallToken(token);
+    });
+
+    return () => {
+      offClosed();
+      cleanup();
+    };
+
+    function cleanup() {
+      InCallManager.stop();
+      // leaveSession is v5 canonical (endSession is a deprecated shim).
+      CometChatCalls.leaveSession();
+    }
+  }, [sessionId, isAudioOnly, onCallEnded]);
+
+  return (
+    <View style={styles.container}>
+      {!isAudioOnly && remoteStream && (
+        <RTCView
+          streamURL={remoteStream.toURL()}
+          objectFit="cover"
+          style={styles.remoteVideo}
+        />
+      )}
+      {!isAudioOnly && localStream && (
+        <RTCView
+          streamURL={localStream.toURL()}
+          objectFit="cover"
+          style={styles.localVideo}
+        />
+      )}
+      <ControlPanel
+        muted={muted}
+        cameraOff={cameraOff}
+        onToggleMute={() => {
+          CometChatCalls.muteAudio(!muted);
+          setMuted(!muted);
+        }}
+        onToggleCamera={() => {
+          CometChatCalls.pauseVideo(!cameraOff);
+          setCameraOff(!cameraOff);
+        }}
+        onSwitchCamera={() => CometChatCalls.switchCamera()}
+        onEnd={() => {
+          // leaveSession is v5 canonical (endSession is a deprecated shim).
+          CometChatCalls.leaveSession();
+          onCallEnded();
+        }}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, backgroundColor: "#000" },
+  remoteVideo: { ...StyleSheet.absoluteFillObject },
+  localVideo: { position: "absolute", top: 60, right: 20, width: 120, height: 160, borderRadius: 8 },
+});
+```
+
+`react-native-webrtc`'s `<RTCView />` requires `streamURL`, not the `MediaStream` directly — call `.toURL()`.
+
+---
+
+## Control panel
+
+```tsx
+import { View, TouchableOpacity, Text, StyleSheet } from "react-native";
+
+interface Props {
+  muted: boolean;
+  cameraOff: boolean;
+  onToggleMute: () => void;
+  onToggleCamera: () => void;
+  onSwitchCamera: () => void;
+  onEnd: () => void;
+}
+
+export function ControlPanel({ muted, cameraOff, onToggleMute, onToggleCamera, onSwitchCamera, onEnd }: Props) {
+  return (
+    <View style={styles.row}>
+      <TouchableOpacity onPress={onToggleMute} style={styles.btn}>
+        <Text>{muted ? "Unmute" : "Mute"}</Text>
+      </TouchableOpacity>
+      <TouchableOpacity onPress={onToggleCamera} style={styles.btn}>
+        <Text>{cameraOff ? "Cam on" : "Cam off"}</Text>
+      </TouchableOpacity>
+      <TouchableOpacity onPress={onSwitchCamera} style={styles.btn}>
+        <Text>Flip</Text>
+      </TouchableOpacity>
+      <TouchableOpacity onPress={onEnd} style={[styles.btn, styles.endBtn]}>
+        <Text style={styles.endText}>End</Text>
+      </TouchableOpacity>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: { position: "absolute", bottom: 40, left: 0, right: 0, flexDirection: "row", justifyContent: "space-around" },
+  btn: { backgroundColor: "rgba(255,255,255,0.2)", padding: 16, borderRadius: 32 },
+  endBtn: { backgroundColor: "red" },
+  endText: { color: "white" },
+});
+```
+
+---
+
+## Audio routing — InCallManager
+
+The most-overlooked piece of custom RN call UI:
+
+```ts
+// On call start
+InCallManager.start({ media: "video" });           // audio routed to speaker by default for video
+InCallManager.setForceSpeakerphoneOn(true);
+
+// User toggles speaker
+function toggleSpeaker(on: boolean) {
+  InCallManager.setForceSpeakerphoneOn(on);
+}
+
+// On call end
+InCallManager.stop();                              // CRITICAL — restores normal audio routing
+```
+
+Without `InCallManager.stop()`, the app's other audio (music, video) routes through the call audio path until the user's device reboots. Particularly bad for podcast/music apps that have a chat screen.
+
+---
+
+## Active speaker detection (custom layout polish)
+
+For multi-party calls where you want to highlight whoever's speaking:
+
+```ts
+const listener = new CometChatCalls.OngoingCallListener({
+  onActiveSpeakerUpdated: (uid: string) => {
+    setActiveSpeakerUid(uid);
+    // Re-layout: move that uid's tile to a larger position
+  },
+  // ...
+});
+```
+
+Not all SDK versions emit this event reliably; verify with the version you're on before relying on it.
+
+---
+
+## Picture-in-picture (Android only)
+
+Android supports system PiP; iOS supports it for video calls but requires CallKit integration (out of scope for custom UI).
+
+```ts
+import { Platform } from "react-native";
+import { enterPictureInPictureMode } from "react-native-webrtc";   // helper if available
+// or use a native module — varies by RN version
+
+function enterPip() {
+  if (Platform.OS !== "android") return;
+  // call your native bridge here
+}
+```
+
+The SKILL.md's verification checklist doesn't require PiP — it's an enhancement, not a hard rule.
+
+---
+
+## When NOT to go custom
+
+Same calculus as web:
+
+- 80% of apps are fine with the kit's default `<CometChatOngoingCall />`
+- Custom code is yours to maintain across SDK upgrades
+- Recording / screen-share / participant management have their own SDK plumbing — covered in the kit components for free, manual in custom
+
+The dispatcher asks before scaffolding custom and defaults to "no — use kit."

package/skills/cometchat-native-calls/references/device-management.md

@@ -0,0 +1,135 @@
+# Device management on React Native
+
+Same SDK API as web. RN-specific: `react-native-incall-manager` for audio routing (speaker / earpiece / Bluetooth) — the SDK's `setAudioOutputDevice` doesn't reach iOS/Android system audio routing the way it does in browsers.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/react-native/device-management
+**Read first:** `cometchat-react-calls/references/device-management.md` — pre-call picker pattern + empty-label gotcha + Bluetooth caveats.
+
+---
+
+## SDK API
+
+```ts
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+
+const cameras = await CometChatCalls.getVideoInputDevices();
+const mics = await CometChatCalls.getAudioInputDevices();
+
+await CometChatCalls.setVideoInputDevice(deviceId);
+```
+
+Camera + mic enumeration works the same as web. Speaker/output is where it diverges.
+
+---
+
+## Audio routing — react-native-incall-manager
+
+For speaker on/off + Bluetooth/earpiece routing, RN integrates `react-native-incall-manager` (already a peer dep of the kit when calls are integrated):
+
+```ts
+import InCallManager from "react-native-incall-manager";
+
+// Force speakerphone on (default for video calls)
+InCallManager.setForceSpeakerphoneOn(true);
+
+// Earpiece (small speaker near top of phone — for private 1:1 voice calls)
+InCallManager.setForceSpeakerphoneOn(false);
+
+// Toggle Bluetooth audio
+InCallManager.setBluetoothScoOn(true);
+
+// Stop on call end (CRITICAL — restores normal audio routing)
+InCallManager.stop();
+```
+
+`InCallManager.stop()` MUST be called on hangup or the device's audio routing stays "in-call mode" — affects other apps' audio until phone reboots. (Same canonical "music doesn't resume" bug as iOS rule 1.5.)
+
+---
+
+## Bluetooth detection
+
+```ts
+import InCallManager from "react-native-incall-manager";
+
+// Listen for Bluetooth connection events (iOS + Android)
+const sub = InCallManager.addListener("WiredHeadset", (data) => {
+  if (data.isPlugged) {
+    console.log("Headphones plugged in");
+  } else {
+    console.log("Headphones unplugged");
+  }
+});
+
+// Bluetooth state
+InCallManager.startProximitySensor();   // optional — auto-screen-off when phone near ear
+```
+
+`react-native-incall-manager` doesn't fire a clean "Bluetooth connected" event consistently across platforms. The reliable signal: poll `InCallManager.getAudioRoute()` periodically, or use platform-channel native bridges for production-grade Bluetooth detection.
+
+---
+
+## Camera picker UI
+
+```tsx
+import { TouchableOpacity, Text, FlatList } from "react-native";
+
+function CameraPicker({ onClose }: { onClose: () => void }) {
+  const [cameras, setCameras] = useState<MediaDevice[]>([]);
+
+  useEffect(() => {
+    CometChatCalls.getVideoInputDevices().then(setCameras);
+  }, []);
+
+  return (
+    <FlatList
+      data={cameras}
+      keyExtractor={(d) => d.id}
+      renderItem={({ item }) => (
+        <TouchableOpacity
+          onPress={async () => {
+            await CometChatCalls.setVideoInputDevice(item.id);
+            onClose();
+          }}
+          accessibilityRole="button"
+          accessibilityLabel={`Select ${item.label}`}
+        >
+          <Text>{item.label || `Camera ${item.id.slice(0, 6)}`}</Text>
+        </TouchableOpacity>
+      )}
+    />
+  );
+}
+```
+
+---
+
+## Anti-patterns
+
+Web sister rules apply, plus RN-specific:
+
+1. **Forgetting `InCallManager.stop()` on hangup.** Music + phone audio sound wrong until reboot.
+2. **Switching cameras mid-call without checking `setVideoInputDevice` await.** SDK queues the switch; switching twice rapidly without awaiting causes the second switch to drop.
+3. **Skipping permissions check before enumeration.** Empty labels (same as web).
+4. **Hardcoding speakerphone-on for voice calls.** User holding phone to ear wants earpiece. Default to earpiece for voice; speaker for video.
+
+---
+
+## Verification checklist
+
+- [ ] `react-native-incall-manager` installed (it's a peer dep of the kit)
+- [ ] `InCallManager.start({ media: "video"|"audio" })` on call start
+- [ ] `InCallManager.stop()` on call end
+- [ ] `setForceSpeakerphoneOn(true)` for video; `false` for voice
+- [ ] Permissions checked before device enumeration
+- [ ] Real-device smoke: AirPods connect mid-call → audio routes to AirPods
+- [ ] Real-device smoke: speaker toggle on/off works
+- [ ] Hangup smoke: music app's playback resumes correctly after call end
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/device-management.md` — sister web reference
+- `cometchat-native-calls` SKILL.md — the seven hard rules (rule 1.5 = audio teardown)
+- `references/voip-push-end-to-end.md` — incall manager + callkeep coordination
+- Canonical docs: https://www.cometchat.com/docs/calls/react-native/device-management

package/skills/cometchat-native-calls/references/expo-vs-bare.md

@@ -0,0 +1,179 @@
+# Expo managed vs bare RN — calls integration paths
+
+Calls require native modules. Expo managed workflows have three states; only two of them can run calls.
+
+| Expo state | Calls work? | What the skill does |
+|---|---|---|
+| **Bare RN CLI** | ✓ | Edit native files directly |
+| **Expo + dev client** | ✓ | Config plugins regenerate native projects on prebuild |
+| **Expo Go (the public client)** | ✗ | Skill refuses to scaffold; tells the user to add `expo-dev-client` or eject |
+
+---
+
+## Detect which mode the project is in
+
+The skill checks (in order):
+
+1. `app.json` exists with `"expo"` key → Expo project
+2. `expo-dev-client` in `package.json` deps → has dev client
+3. `ios/` and `android/` directories committed → bare or prebuild already ran
+4. `expo-modules-core` in `package.json` → managed
+
+The dispatcher branches:
+
+- **Bare RN** (no `expo` in app.json): edit `ios/` + `android/` directly. Run `cd ios && pod install` after package install.
+- **Expo + dev client**: write config plugins to `app.json`, run `npx expo prebuild --clean`, the prebuild regenerates `ios/` + `android/` with the calls config baked in.
+- **Expo Go**: print the message below and exit.
+
+---
+
+## Expo Go message
+
+When the project is Expo managed without a dev client, the dispatcher prints:
+
+> Calls require native modules that Expo Go cannot load (`react-native-callkeep`, `react-native-voip-push-notification`, `react-native-webrtc`). To proceed:
+>
+> **Option A — Add expo-dev-client (recommended for managed projects):**
+> ```bash
+> npx expo install expo-dev-client
+> npx expo prebuild --clean
+> npx expo run:ios     # or run:android
+> ```
+> This builds a custom dev client locally. Re-run `/cometchat-calls` after that.
+>
+> **Option B — Eject to bare:**
+> ```bash
+> npx expo prebuild --no-install
+> ```
+> This generates `ios/` + `android/` directories permanently. After this, you're a bare RN project; the calls flow runs normally.
+>
+> **Option C — Use EAS Build:**
+> If you don't want to build locally, EAS can build the dev client for you. Configure `eas.json` profiles, then `eas build --profile development`.
+>
+> Pick one and re-run `/cometchat-calls`.
+
+---
+
+## Config plugins for Expo + dev client
+
+The skill writes the following to `app.json` `expo.plugins`:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "react-native-callkeep",
+        {
+          "ios": {
+            "appName": "YourApp",
+            "supportsVideo": true,
+            "imageName": "callkit_icon"
+          }
+        }
+      ],
+      "@react-native-firebase/app",
+      "@react-native-firebase/messaging",
+      [
+        "expo-build-properties",
+        {
+          "ios": { "useFrameworks": "static" },
+          "android": { "minSdkVersion": 26 }
+        }
+      ]
+    ],
+    "ios": {
+      "infoPlist": {
+        "UIBackgroundModes": ["audio", "voip", "remote-notification"],
+        "NSMicrophoneUsageDescription": "So you can talk during voice and video calls.",
+        "NSCameraUsageDescription": "So you can be seen during video calls."
+      },
+      "googleServicesFile": "./GoogleService-Info.plist"
+    },
+    "android": {
+      "permissions": [
+        "RECORD_AUDIO",
+        "CAMERA",
+        "MANAGE_OWN_CALLS",
+        "BIND_TELECOM_CONNECTION_SERVICE",
+        "FOREGROUND_SERVICE",
+        "FOREGROUND_SERVICE_PHONE_CALL",
+        "FOREGROUND_SERVICE_MICROPHONE",
+        "FOREGROUND_SERVICE_CAMERA",
+        "POST_NOTIFICATIONS"
+      ],
+      "googleServicesFile": "./google-services.json"
+    }
+  }
+}
+```
+
+Then `npx expo prebuild --clean` regenerates `ios/` + `android/` from this config. Re-run after every config change.
+
+---
+
+## EAS Build profile for the dev client
+
+`eas.json`:
+
+```json
+{
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal",
+      "ios": { "simulator": false },
+      "android": { "buildType": "apk" }
+    },
+    "preview": {
+      "distribution": "internal"
+    },
+    "production": {}
+  }
+}
+```
+
+Run `eas build --profile development --platform ios` (or `android`). Wait ~10-15 min, install the resulting `.ipa` / `.apk` to a real device, and `expo start --dev-client` connects to it.
+
+**Real device only** for VoIP testing — simulators don't deliver PushKit / FCM VoIP messages.
+
+---
+
+## When to recommend bare over Expo
+
+The dispatcher defaults to keeping projects on Expo if they're already there. But for calls specifically, bare can be simpler if:
+
+- The project will need many native modules (calls is one of several)
+- The team is comfortable with Xcode + Android Studio
+- They want full control of `Podfile`, `build.gradle`, `Info.plist`
+
+Bare's downside: no `expo prebuild` to regenerate from config — every native config change is manual. For most teams, Expo + dev client is the right balance.
+
+---
+
+## File-tree differences
+
+Bare:
+
+```
+ios/
+  Podfile                    ← edit directly
+  YourApp/Info.plist         ← edit directly
+  YourApp/AppDelegate.mm     ← edit for PushKit registration
+android/
+  app/build.gradle           ← edit directly
+  app/src/main/AndroidManifest.xml
+  app/google-services.json   ← drop in directly
+```
+
+Expo + dev client:
+
+```
+app.json                     ← single source of truth (config plugins)
+google-services.json         ← root of project
+GoogleService-Info.plist     ← root of project
+ios/                         ← regenerated by prebuild; DO NOT edit directly
+android/                     ← regenerated by prebuild; DO NOT edit directly
+```
+
+The skill is aware of this and writes to `app.json` for Expo, to native files for bare.