@cometchat/skills 4.4.1 → 5.0.0

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

@@ -1,254 +0,0 @@
-# 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={() => {
-          // No-arg methods: muteAudio() / unmuteAudio() (no boolean param).
-          if (muted) CometChatCalls.unmuteAudio();
-          else CometChatCalls.muteAudio();
-          setMuted(!muted);
-        }}
-        onToggleCamera={() => {
-          // No-arg methods: pauseVideo() / resumeVideo() (no boolean param).
-          if (cameraOff) CometChatCalls.resumeVideo();
-          else CometChatCalls.pauseVideo();
-          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:
-
-The event is `onDominantSpeakerChanged` (there is no `onActiveSpeakerUpdated`). Use `addEventListener` (returns an unsubscribe fn) — `OngoingCallListener` is the @deprecated v4 path:
-
-```ts
-const off = CometChatCalls.addEventListener("onDominantSpeakerChanged", (uid: string) => {
-  setActiveSpeakerUid(uid);
-  // Re-layout: move that uid's tile to a larger position
-});
-// cleanup: off();
-```
-
-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

@@ -1,158 +0,0 @@
-# Device management on React Native
-
-**RN is NOT web.** The web `getVideoInputDevices()` / `getAudioInputDevices()` / `setVideoInputDevice()` enumeration getters **do not exist on the RN Calls SDK** — there is no `MediaDevices.enumerateDevices()` equivalent. On mobile there are only two cameras (front / rear) and a fixed set of audio routes (earpiece / speaker / Bluetooth / wired), so the RN SDK exposes:
-
-- **Camera:** `CometChatCalls.switchCamera()` — toggles front ↔ rear (no device-id picker).
-- **Audio output:** `CometChatCalls.setAudioMode(mode)` where `mode` is an `AUDIO_MODE` value (`"SPEAKER" | "EARPIECE" | "BLUETOOTH" | "HEADPHONES"`).
-
-The thesis of this reference is therefore **`react-native-incall-manager`** for real-world routing UX.
-
-**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 (web-only enumeration semantics; do NOT carry the getters over to RN).
-
----
-
-## SDK API (RN)
-
-```ts
-import { CometChatCalls, AUDIO_MODE } from "@cometchat/calls-sdk-react-native";
-
-// Front ↔ rear camera toggle (no enumeration / no device ids on RN):
-CometChatCalls.switchCamera();
-
-// Audio output route (mobile only):
-CometChatCalls.setAudioMode(AUDIO_MODE.SPEAKER);   // or EARPIECE / BLUETOOTH / HEADPHONES
-```
-
-There is no camera/mic device list to enumerate — `switchCamera()` flips between the two on-device cameras. For fine-grained audio routing (and reliable Bluetooth/headset detection) use `react-native-incall-manager` below.
-
----
-
-## 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 switch UI (front ↔ rear)
-
-There's no device picker on RN — just a flip button calling `switchCamera()`:
-
-```tsx
-import { TouchableOpacity, Text } from "react-native";
-import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
-
-function FlipCameraButton() {
-  return (
-    <TouchableOpacity
-      onPress={() => CometChatCalls.switchCamera()}   // toggles front ↔ rear; returns void
-      accessibilityRole="button"
-      accessibilityLabel="Switch camera"
-    >
-      <Text>Flip camera</Text>
-    </TouchableOpacity>
-  );
-}
-```
-
-## Audio output picker (SPEAKER / EARPIECE / BLUETOOTH / HEADPHONES)
-
-```tsx
-import { TouchableOpacity, Text, View } from "react-native";
-import { CometChatCalls, AUDIO_MODE } from "@cometchat/calls-sdk-react-native";
-
-const MODES = [AUDIO_MODE.SPEAKER, AUDIO_MODE.EARPIECE, AUDIO_MODE.BLUETOOTH, AUDIO_MODE.HEADPHONES];
-
-function AudioOutputPicker() {
-  return (
-    <View>
-      {MODES.map((mode) => (
-        <TouchableOpacity
-          key={mode}
-          onPress={() => CometChatCalls.setAudioMode(mode)}
-          accessibilityRole="button"
-          accessibilityLabel={`Route audio to ${mode}`}
-        >
-          <Text>{mode}</Text>
-        </TouchableOpacity>
-      ))}
-    </View>
-  );
-}
-```
-
-Note: `setAudioMode` is the SDK-level route hint; `react-native-incall-manager` (above) remains the most reliable cross-platform path for forcing speaker/Bluetooth and detecting headset plug/unplug.
-
----
-
-## Anti-patterns
-
-Web sister rules apply, plus RN-specific:
-
-1. **Forgetting `InCallManager.stop()` on hangup.** Music + phone audio sound wrong until reboot.
-2. **Spamming `switchCamera()` rapidly.** The SDK queues the front/rear toggle; double-tapping can drop the second toggle. Debounce the flip button.
-3. **Assuming web-style device enumeration on RN.** There is no `getVideoInputDevices()`/`getAudioInputDevices()`/`setVideoInputDevice()` — use `switchCamera()` + `setAudioMode()`.
-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
-- [ ] Camera flip uses `CometChatCalls.switchCamera()` (no device enumeration on RN)
-- [ ] Audio route changes use `CometChatCalls.setAudioMode(AUDIO_MODE.*)` and/or InCallManager
-- [ ] 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

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