@cometchat/skills 4.3.0 → 4.4.1

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

@@ -1,24 +1,30 @@
 # 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.
+**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.
+**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
+## SDK API (RN)
 
 ```ts
-import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+import { CometChatCalls, AUDIO_MODE } from "@cometchat/calls-sdk-react-native";
 
-const cameras = await CometChatCalls.getVideoInputDevices();
-const mics = await CometChatCalls.getAudioInputDevices();
+// Front ↔ rear camera toggle (no enumeration / no device ids on RN):
+CometChatCalls.switchCamera();
 
-await CometChatCalls.setVideoInputDevice(deviceId);
+// Audio output route (mobile only):
+CometChatCalls.setAudioMode(AUDIO_MODE.SPEAKER);   // or EARPIECE / BLUETOOTH / HEADPHONES
 ```
 
-Camera + mic enumeration works the same as web. Speaker/output is where it diverges.
+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.
 
 ---
 
@@ -68,39 +74,55 @@ InCallManager.startProximitySensor();   // optional — auto-screen-off when pho
 
 ---
 
-## Camera picker UI
+## Camera switch UI (front ↔ rear)
+
+There's no device picker on RN — just a flip button calling `switchCamera()`:
 
 ```tsx
-import { TouchableOpacity, Text, FlatList } from "react-native";
+import { TouchableOpacity, Text } from "react-native";
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
 
-function CameraPicker({ onClose }: { onClose: () => void }) {
-  const [cameras, setCameras] = useState<MediaDevice[]>([]);
+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)
 
-  useEffect(() => {
-    CometChatCalls.getVideoInputDevices().then(setCameras);
-  }, []);
+```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 (
-    <FlatList
-      data={cameras}
-      keyExtractor={(d) => d.id}
-      renderItem={({ item }) => (
+    <View>
+      {MODES.map((mode) => (
         <TouchableOpacity
-          onPress={async () => {
-            await CometChatCalls.setVideoInputDevice(item.id);
-            onClose();
-          }}
+          key={mode}
+          onPress={() => CometChatCalls.setAudioMode(mode)}
           accessibilityRole="button"
-          accessibilityLabel={`Select ${item.label}`}
+          accessibilityLabel={`Route audio to ${mode}`}
         >
-          <Text>{item.label || `Camera ${item.id.slice(0, 6)}`}</Text>
+          <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
@@ -108,8 +130,8 @@ function CameraPicker({ onClose }: { onClose: () => void }) {
 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).
+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.
 
 ---
@@ -120,7 +142,8 @@ Web sister rules apply, plus RN-specific:
 - [ ] `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
+- [ ] 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

package/skills/cometchat-native-calls/references/group-calls.md

@@ -96,16 +96,19 @@ CometChat plan-driven. Common ceilings:
 | Production | 25 |
 | Enterprise | configurable up to 100 |
 
-The SDK doesn't reject calls at capacity — it just stops admitting new joiners with `OngoingCallListener.onError` firing on the would-be joiner's side. Surface this to the user:
+The SDK doesn't reject calls at capacity — it just stops admitting new joiners. In v5, observe the roster via `addEventListener('onParticipantListChanged', ...)` (returns the full list, not a delta — clone `skills/event-listeners`) and surface the ceiling to the user:
 
 ```ts
-const listener = new CometChatCalls.OngoingCallListener({
-  onError: (error: { code: string; message: string }) => {
-    if (error.code === "ERR_CALL_FULL") {
+const MAX_PARTICIPANTS = 25; // your plan's ceiling
+const off = CometChatCalls.addEventListener(
+  "onParticipantListChanged",
+  (participants: Array<{ uid: string; name: string }>) => {
+    if (participants.length >= MAX_PARTICIPANTS) {
       Alert.alert("Call is full", "This meeting has reached its participant limit.");
     }
   },
-});
+);
+// cleanup: off();
 ```
 
 ---
@@ -113,12 +116,16 @@ const listener = new CometChatCalls.OngoingCallListener({
 ## Roster — who's in the call
 
 ```ts
-const listener = new CometChatCalls.OngoingCallListener({
-  onUserListUpdated: (users: Array<{ uid: string; name: string; avatar?: string }>) => {
+// v5: addEventListener('onParticipantListChanged', ...) — the v4 OngoingCallListener.onUserListUpdated
+// is deprecated (clone skills/event-listeners + skills/migration-v4-to-v5 mapping).
+const off = CometChatCalls.addEventListener(
+  "onParticipantListChanged",
+  (users: Array<{ uid: string; name: string; avatar?: string }>) => {
     // Re-render the participant strip
     setParticipants(users);
   },
-});
+);
+// cleanup: off();
 ```
 
 Fires whenever a participant joins or leaves. The roster includes the local user — filter them out of the "remote participants" UI:
@@ -132,14 +139,13 @@ const remoteParticipants = users.filter((u) => u.uid !== localUid);
 
 ## Active speaker detection
 
-The SDK fires `onActiveSpeakerUpdated` when the dominant audio source changes:
+The SDK fires `onDominantSpeakerChanged` when the dominant audio source changes (there is no `onActiveSpeakerUpdated` event). Prefer `addEventListener` (returns an unsubscribe fn); `OngoingCallListener` is the @deprecated v4 path:
 
 ```ts
-const listener = new CometChatCalls.OngoingCallListener({
-  onActiveSpeakerUpdated: (uid: string) => {
-    setActiveSpeakerUid(uid);
-  },
+const off = CometChatCalls.addEventListener("onDominantSpeakerChanged", (uid: string) => {
+  setActiveSpeakerUid(uid);
 });
+// cleanup: off();
 ```
 
 Use this to drive a "spotlight" layout — large tile for the active speaker, small thumbnails for the rest:
@@ -162,7 +168,7 @@ function SpotlightLayout({ participants, activeSpeakerUid }: Props) {
 }
 ```
 
-**Throttle re-layout** — `onActiveSpeakerUpdated` can fire multiple times per second in a noisy room. Debounce the layout swap to ~500ms minimum, otherwise tiles jitter.
+**Throttle re-layout** — `onDominantSpeakerChanged` can fire multiple times per second in a noisy room. Debounce the layout swap to ~500ms minimum, otherwise tiles jitter.
 
 ---
 
@@ -173,28 +179,27 @@ These require the local user to be a group **owner** or **moderator** (CometChat
 ```ts
 import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
 
-// Mute a specific participant (moderator action — kicks them off audio)
-async function mutParticipant(uid: string) {
-  await CometChatCalls.muteUser(uid);
+// Mute a specific participant. The method is muteParticipant(participantId) — synchronous,
+// returns void. There is NO muteUser()/removeUser() on the RN SDK.
+function muteParticipant(participantId: string) {
+  CometChatCalls.muteParticipant(participantId);
 }
 
 // Mute everyone except local user
-async function muteAll() {
+function muteAll() {
   for (const p of participants) {
     if (p.uid === localUid) continue;
-    await CometChatCalls.muteUser(p.uid);
+    CometChatCalls.muteParticipant(p.uid);
   }
 }
 
-// Kick a participant out of the call
-async function kickParticipant(uid: string) {
-  await CometChatCalls.removeUser(uid);
-}
+// NOTE: there is NO "kick / remove participant" API on the RN Calls SDK.
+// Removal must be done via the Chat SDK group management (e.g. CometChat.kickGroupMember),
+// which removes them from the group — not a per-call eject.
 
-// Local user "raises hand" — signals to moderator
-async function raiseHand() {
-  await CometChatCalls.raiseHand();
-  // The moderator's onUserRaisedHand listener fires
+// Local user "raises hand" — signals to moderator (synchronous, returns void)
+function raiseHand() {
+  CometChatCalls.raiseHand();
 }
 ```
 
@@ -234,7 +239,7 @@ import * as Battery from "expo-battery";
 
 const level = await Battery.getBatteryLevelAsync();
 if (level < 0.2) {
-  await CometChatCalls.pauseVideo(true);
+  CometChatCalls.pauseVideo();   // no-arg; resumeVideo() to resume (synchronous, returns void)
   Alert.alert("Battery saver", "Video paused to save battery.");
 }
 ```
@@ -261,8 +266,8 @@ Use this to render a "Join meeting" button on the group screen during an active
 ## Anti-patterns
 
 1. **Rendering tiles for every participant.** At 25 people, you have 25 `<RTCView />` instances; that's where RN's bridge starts choking. Render the active speaker + max 6 thumbnails.
-2. **Updating layout on every `onActiveSpeakerUpdated`.** Debounce to 500ms minimum.
-3. **Allowing non-moderators to call `muteUser` / `removeUser`.** SDK rejects, but the UI shouldn't expose buttons for it.
+2. **Updating layout on every `onDominantSpeakerChanged`.** Debounce to 500ms minimum.
+3. **Allowing non-moderators to call `muteParticipant`.** Only owners/moderators should see the button. (Per-call "kick" doesn't exist on the RN SDK — see above.)
 4. **No bandwidth warning.** A user on cellular joining a 10-person call burns their data plan in minutes. Show a "Switch to audio-only" prompt at the threshold.
 5. **Forgetting to filter local user from the roster.** "Speaking with myself" tile.
 6. **Initiating group calls without group membership check.** Non-members get "ERR_NOT_GROUP_MEMBER" silently.

package/skills/cometchat-native-calls/references/idle-timeout.md

@@ -1,6 +1,6 @@
 # Idle timeout on React Native
 
-Same SDK API as web — `setIdleTimeoutPeriodBeforePrompt` + `setIdleTimeoutPeriodAfterPrompt` on CallSettings, `onSessionTimedOut` event. RN-specific deltas are background-handling integration (call doesn't time out while the app is foregrounded; needs special handling in background) and the alert UI surface.
+Same SDK API as web — `idleTimeoutPeriodBeforePrompt` + `idleTimeoutPeriodAfterPrompt` are SessionSettings **object fields** (ms), `onSessionTimedOut` event. RN-specific deltas are background-handling integration (call doesn't time out while the app is foregrounded; needs special handling in background) and the alert UI surface.
 
 **Canonical docs:** https://www.cometchat.com/docs/calls/react-native/idle-timeout
 **Read first:** `cometchat-react-calls/references/idle-timeout.md` — settings shape + recommended timeouts per archetype + custom prompt pattern.
@@ -12,11 +12,11 @@ Same SDK API as web — `setIdleTimeoutPeriodBeforePrompt` + `setIdleTimeoutPeri
 ```ts
 import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
 
-const settings = new CometChatCalls.CallSettingsBuilder()
-  .setSessionID(sessionId)
-  .setIdleTimeoutPeriodBeforePrompt(60_000)
-  .setIdleTimeoutPeriodAfterPrompt(120_000)
-  .build();
+// SessionSettings OBJECT fields (ms) — NOT builder methods:
+const settings = {
+  idleTimeoutPeriodBeforePrompt: 60_000,
+  idleTimeoutPeriodAfterPrompt: 120_000,
+};
 
 CometChatCalls.addEventListener("onSessionTimedOut", () => {
   navigation.navigate("Home");

package/skills/cometchat-native-calls/references/in-call-chat.md

@@ -12,12 +12,14 @@ Same SDK API as web. RN-specific: BottomSheet panel UX (matches mobile patterns)
 ```ts
 import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
 
-const settings = new CometChatCalls.CallSettingsBuilder()
-  .setSessionID(sessionId)
-  .hideChatButton(false)
-  .build();
-
-CometChatCalls.addEventListener("onChatButtonClicked", () => setOpen(true));
+// SessionSettings OBJECT field, not a builder method:
+const settings = {
+  hideChatButton: false,
+};
+
+// addEventListener returns the unsubscribe fn — call it on cleanup.
+const off = CometChatCalls.addEventListener("onChatButtonClicked", () => setOpen(true));
+// later: off();
 CometChatCalls.setChatButtonUnreadCount(5);
 ```
 
@@ -47,8 +49,8 @@ function InCallChatSheet({ sessionId }: Props) {
 
   useEffect(() => {
     const handler = () => sheetRef.current?.snapToIndex(1);
-    CometChatCalls.addEventListener("onChatButtonClicked", handler);
-    return () => CometChatCalls.removeEventListener("onChatButtonClicked", handler);
+    const off = CometChatCalls.addEventListener("onChatButtonClicked", handler);
+    return () => off();
   }, []);
 
   useEffect(() => {

package/skills/cometchat-native-calls/references/migration-v4-to-v5.md

@@ -46,10 +46,10 @@ If any of these are stale, calls may fail silently with WebRTC negotiation error
 ## Migration steps (same as web)
 
 1. Migrate init to plain object
-2. Add `CometChatCalls.login(authToken)` after `CometChat.login`
+2. Add `CometChatCalls.login(uid, authKey)` after `CometChat.login` (UID-based; the auth-token form is `CometChatCalls.loginWithAuthToken(authToken)` — verified against calls-sdk-react-native `skills/setup` + `skills/migration-v4-to-v5`)
 3. Replace `CallSettingsBuilder` with plain `sessionSettings` object — **watch inverted booleans** (`show*` → `hide*`)
 4. Replace `OngoingCallListener` with `addEventListener` calls
-5. Rename methods: `endSession` → `leaveSession`, `startSession` → `joinSession`, `setMode` → `setLayout`
+5. Rename methods: `endSession` → `leaveSession`; `setMode('DEFAULT')` → the `sessionSettings.layout: 'SIDEBAR'` prop (DEFAULT maps to SIDEBAR). An imperative `CometChatCalls.setLayout('TILE' | 'SIDEBAR' | 'SPOTLIGHT')` does exist for runtime layout changes (calls-sdk-react-native `skills/custom-ui`). **RN has no imperative `joinSession`/`startSession`** — on RN the session is the declarative `<CometChatCalls.Component callToken={...} />` primitive (mint the token with `CometChatCalls.generateToken(sessionId)` and render the Component). There is no start/join method to call.
 6. Cleanup: `addEventListener` returns an unsubscribe — call it on unmount
 
 ---

package/skills/cometchat-native-calls/references/raise-hand.md

@@ -15,13 +15,14 @@ import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
 CometChatCalls.raiseHand();
 CometChatCalls.lowerHand();
 
-CometChatCalls.addEventListener("onParticipantHandRaised", (p) => { ... });
-CometChatCalls.addEventListener("onParticipantHandLowered", (p) => { ... });
-
-const settings = new CometChatCalls.CallSettingsBuilder()
-  .setSessionID(sessionId)
-  .hideRaiseHandButton(true)
-  .build();
+// addEventListener returns an unsubscribe function — capture it, call it in cleanup.
+const off = CometChatCalls.addEventListener("onParticipantHandRaised", (p) => { ... });
+// later: off();
+
+// Button visibility is a SessionSettings OBJECT field, not a builder method:
+const settings = {
+  hideRaiseHandButton: true,
+};
 ```
 
 ---
@@ -102,11 +103,12 @@ function RaisedHandsSheet() {
       });
     };
 
-    CometChatCalls.addEventListener("onParticipantHandRaised", onRaised);
-    CometChatCalls.addEventListener("onParticipantHandLowered", onLowered);
+    // addEventListener returns an unsubscribe fn; collect them and call on cleanup.
+    const offRaised = CometChatCalls.addEventListener("onParticipantHandRaised", onRaised);
+    const offLowered = CometChatCalls.addEventListener("onParticipantHandLowered", onLowered);
     return () => {
-      CometChatCalls.removeEventListener("onParticipantHandRaised", onRaised);
-      CometChatCalls.removeEventListener("onParticipantHandLowered", onLowered);
+      offRaised();
+      offLowered();
     };
   }, [raised.size]);
 
@@ -149,8 +151,8 @@ useEffect(() => {
       position: "top",
     });
   };
-  CometChatCalls.addEventListener("onParticipantHandRaised", onRaised);
-  return () => CometChatCalls.removeEventListener("onParticipantHandRaised", onRaised);
+  const off = CometChatCalls.addEventListener("onParticipantHandRaised", onRaised);
+  return () => off();
 }, []);
 ```