@cometchat/skills 4.3.0 → 4.4.0

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

@@ -3,7 +3,9 @@
 When the kit's default `<CometChatOngoingCall />` doesn't fit your app's design system, drop down to the Calls SDK directly. Two escalation paths:
 
 1. **Style the kit's component** — pass style props / CSS variable overrides. Cheapest. Covers most cases.
-2. **Build your own surface on the SDK** — use `CometChatCalls.joinSession(token, settings, container)` directly with your own DOM container. Maximum control. The kit doesn't render anything; you do. (`startSession` is a deprecated v4 shim — use `joinSession`.)
+2. **Build your own surface on the SDK** — drive the session directly with your own DOM container. Maximum control. The kit doesn't render anything; you do.
+
+> ⚠️ **Two join APIs — pick by which settings type you build.** `joinSession(token, sessionSettings, container)` is the v5 canonical and takes a **`SessionSettings` object** (the `hide*` / `sessionType` / `layout` flags). It does **not** accept the output of `CallSettingsBuilder.build()` — those are incompatible types. The `CallSettingsBuilder` (with `enableDefaultLayout(false)`, `setCallListener`, etc.) produces a `CallSettings` consumed only by the **deprecated** `startSession(token, callSettings, container)`. So: **hybrid / hide-chrome custom UI → object + `joinSession`** (preferred); **fully-custom render-your-own-tiles (`enableDefaultLayout(false)`) → builder + `startSession`** (the one path where the deprecated call is still required, because `enableDefaultLayout` lives only on the builder).
 
 This reference covers path 2 — full custom UI on the SDK. Path 1 is in the kit's component documentation (see `cometchat-customization`).
 
@@ -47,6 +49,8 @@ export function CustomOngoingCallView({ sessionId, authToken, onCallEnded }: Pro
   const remoteVideoRef = useRef<HTMLVideoElement>(null);
 
   useEffect(() => {
+    // ⚠️ CometChatCalls.OngoingCallListener is @deprecated (use addEventListener).
+    // It's only here because enableDefaultLayout(false) + startSession require it.
     const callListener = new CometChatCalls.OngoingCallListener({
       onUserListUpdated: (userList: unknown) => {
         // userList = current participants — re-render your custom roster
@@ -62,9 +66,6 @@ export function CustomOngoingCallView({ sessionId, authToken, onCallEnded }: Pro
       onError: (error: unknown) => {
         console.error("Call error:", error);
       },
-      onAudioModesUpdated: (audioModes: unknown[]) => {
-        // available mic / speaker devices
-      },
       onCallSwitchedToVideo: (call: unknown) => {
         // remote upgraded the call from voice to video
       },
@@ -73,11 +74,15 @@ export function CustomOngoingCallView({ sessionId, authToken, onCallEnded }: Pro
       },
     });
 
+    // ⚠️ CallSettingsBuilder method names (verified against calls-sdk-javascript@5):
+    //   - there is NO .setSessionID() on the builder — sessionId flows through
+    //     generateToken(sessionId) below, NOT the builder
+    //   - it's .setIsAudioOnlyCall(bool), not .setIsAudioOnly()
+    //   - it's .setCallListener(listener), not .setCallEventListener()
     const settings = new CometChatCalls.CallSettingsBuilder()
-      .setSessionID(sessionId)
-      .setIsAudioOnly(false)
+      .setIsAudioOnlyCall(false)
       .enableDefaultLayout(false)            // ← key: we render the UI ourselves
-      .setCallEventListener(callListener)
+      .setCallListener(callListener)
       .build();
 
     // v5 generateToken takes ONLY sessionId — authToken is internal after CometChatCalls.login().
@@ -86,8 +91,11 @@ export function CustomOngoingCallView({ sessionId, authToken, onCallEnded }: Pro
       // With custom UI you typically render your own <video> elements; the
       // container can be hidden but must still be a real DOM node.
       const container = document.getElementById("calls-container")!;
-      // joinSession is the v5 canonical — startSession is a deprecated shim.
-      CometChatCalls.joinSession(tokenRes.token, settings, container);
+      // This example builds CallSettings via CallSettingsBuilder (enableDefaultLayout(false)),
+      // so it MUST use startSession — joinSession only accepts a SessionSettings object,
+      // not the builder's CallSettings output. startSession is deprecated but is the only
+      // consumer of enableDefaultLayout(false)-style fully-custom settings.
+      CometChatCalls.startSession(tokenRes.token, settings, container);
     });
 
     return () => cleanup();
@@ -105,10 +113,10 @@ export function CustomOngoingCallView({ sessionId, authToken, onCallEnded }: Pro
       <video ref={remoteVideoRef} autoPlay playsInline className="remote-tile" />
       <video ref={localVideoRef} autoPlay playsInline muted className="local-tile" />
       <ControlPanel
-        onMute={() => CometChatCalls.muteAudio(true)}
-        onUnmute={() => CometChatCalls.muteAudio(false)}
-        onCameraOff={() => CometChatCalls.pauseVideo(true)}
-        onCameraOn={() => CometChatCalls.pauseVideo(false)}
+        onMute={() => CometChatCalls.muteAudio()}
+        onUnmute={() => CometChatCalls.unmuteAudio()}
+        onCameraOff={() => CometChatCalls.pauseVideo()}
+        onCameraOn={() => CometChatCalls.resumeVideo()}
         onSwitchCamera={() => CometChatCalls.switchCamera()}
         onEnd={() => {
           CometChatCalls.leaveSession();
@@ -151,7 +159,45 @@ function ControlPanel(props: {
 }
 ```
 
-The SDK methods (`muteAudio`, `pauseVideo`, `switchCamera`) propagate to all participants via the SDK's signaling — you don't manage track state yourself.
+The SDK methods (`muteAudio`/`unmuteAudio`, `pauseVideo`/`resumeVideo`, `switchCamera`) propagate to all participants via the SDK's signaling — you don't manage track state yourself.
+
+> ⚠️ **These are no-argument methods.** `muteAudio(): void` / `pauseVideo(): void` — there is NO boolean parameter. `CometChatCalls.muteAudio(false)` does **not** unmute (the arg is ignored — it still mutes). Use the explicit pair: `muteAudio()` / `unmuteAudio()` and `pauseVideo()` / `resumeVideo()`. (There is **no** `toggleAudio()` / `toggleVideo()` in the v5 SDK — track the muted/paused state yourself and call the matching method of the pair.)
+
+> ⚠️ **Optimistic local state desyncs.** A control panel that only flips its own `useState` on click (as the example above does) will show a stale label whenever mute/camera/screen-share change from *outside* your bar — a join-muted call (`startAudioMuted`), the browser's own "Stop sharing" button, or another surface. Reconcile by subscribing to the SDK's media events and driving state from them: `onAudioMuted` / `onAudioUnMuted` / `onVideoPaused` / `onVideoResumed` / `onScreenShareStarted` / `onScreenShareStopped` / `onRecordingStarted` / `onRecordingStopped`. Seed the initial state from your join options so the first render is correct too.
+
+---
+
+## Two custom-panel models — and the `hideHeaderPanel` footgun
+
+There are **two** ways to put your own controls on a call, and they are very different:
+
+**Model A — fully custom (`enableDefaultLayout(false)`).** The SDK draws nothing; you render every tile, every button, the whole surface. That's the path above. It leans on **two deprecated V5 APIs** — `startSession` (the only consumer of builder-produced `CallSettings`) and the `CometChatCalls.OngoingCallListener` accessor (the SDK marks it `@deprecated → use addEventListener`) — because `enableDefaultLayout(false)` exists only on the builder and has no `SessionSettings`-object equivalent. Use it only when you truly must render your own video tiles, and accept owning a11y, recording/screen-share plumbing, and the eventual migration off these shims. **For everything else, prefer Model B — it's 100% current V5 (`joinSession` + object + `addEventListener`).**
+
+**Model B — hybrid (keep the SDK layout, replace only the bottom bar).** Far cheaper and far more common. You keep the SDK's default layout but pass `SessionSettings` flags to `joinSession` to hide just the control bar, then render your own bar over it:
+
+```ts
+const settings = {
+  sessionType: 'VIDEO',
+  layout: 'TILE',
+  hideControlPanel: true,   // ← hide ONLY the bottom control bar; render your own
+  // hideHeaderPanel: true,  // ← ⚠️ DO NOT add this unless you mean it (see below)
+};
+await CometChatCalls.joinSession(token, settings, container);
+```
+
+> ⚠️ **`hideHeaderPanel: true` silently disables Virtual Background, In-Call Chat, and the Participant List.** Those three features live in the SDK's **header** panel, not the control bar. If you set `hideHeaderPanel: true` to "clean up" a custom-bar call, you remove them with no replacement — and there are **no plain `CometChatCalls` static methods** to rebuild VB or in-call chat in your own bar (VB is exposed only as call-session instance methods / action constants like `setBackgroundBlur`, not statics). So a custom *control* bar should hide only `hideControlPanel`; leave `hideHeaderPanel` false so VB / chat / participant-list stay reachable. Real customer bug, 2026-06: ticking a "custom control panel" option flipped both flags and made VB + chat vanish.
+
+If you genuinely don't want the header either, you're back in Model A territory — own those features yourself.
+
+### Participant count from a custom bar
+
+Don't derive the roster from `onParticipantJoined` / `onParticipantLeft` increments — those fire only for participants who join/leave **after** you, so a counter seeded at 0 (or 1) **undercounts when you join a call already in progress**. Subscribe to the authoritative full-list event instead:
+
+```ts
+CometChatCalls.addEventListener('onParticipantListChanged', (list) =>
+  setParticipants(Math.max(1, list.length)),  // list includes the local user
+);
+```
 
 ---
 
@@ -185,7 +231,7 @@ Once `startSession` runs, the SDK takes over the camera/mic — release your pre
 
 The Calls SDK is layout-agnostic when `enableDefaultLayout(false)`. You compose remote tiles in any CSS layout:
 
-- **Spotlight** — one large remote tile + small thumbnails for others. Track which user is speaking (`onActiveSpeakerUpdated` event in some SDK builds) and swap the spotlight.
+- **Spotlight** — one large remote tile + small thumbnails for others. Track who's speaking via the `onDominantSpeakerChanged` event (NOT `onActiveSpeakerUpdated` — that name doesn't exist) and swap the spotlight.
 - **Grid** — CSS grid with auto-fit columns, 1-N participant tiles equally sized.
 - **Picture-in-picture** — small floating remote video that survives navigation. Mount it in a portal at the layout root (similar to `<CometChatIncomingCall />`).
 

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

@@ -12,32 +12,35 @@ Camera / mic / speaker enumeration + switching mid-call. SDK exposes `getAudioIn
 ```ts
 import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
 
-// Enumerate
-const mics = await CometChatCalls.getAudioInputDevices();
-const speakers = await CometChatCalls.getAudioOutputDevices();
-const cameras = await CometChatCalls.getVideoInputDevices();
+// Enumerate — these getters are SYNCHRONOUS (they return arrays, not promises;
+// do NOT `await` them).
+const mics = CometChatCalls.getAudioInputDevices();
+const speakers = CometChatCalls.getAudioOutputDevices();
+const cameras = CometChatCalls.getVideoInputDevices();
 
 // Currently selected
 const currentMic = CometChatCalls.getCurrentAudioInputDevice();
 
-// Switch (mid-call OK)
-await CometChatCalls.setAudioInputDevice(deviceId);
-await CometChatCalls.setAudioOutputDevice(deviceId);
-await CometChatCalls.setVideoInputDevice(deviceId);
+// Switch (mid-call OK) — also synchronous, return void.
+CometChatCalls.setAudioInputDevice(deviceId);
+CometChatCalls.setAudioOutputDevice(deviceId);
+CometChatCalls.setVideoInputDevice(deviceId);
 
-// Listen for device changes (user plugs in headphones, etc.)
-CometChatCalls.addEventListener("onAudioModesUpdated", (devices) => {
+// Listen for device changes (user plugs in headphones, etc.). The valid event
+// keys are onAudioInputDevicesChanged / onAudioOutputDevicesChanged /
+// onVideoInputDevicesChanged (there is NO "onAudioModesUpdated"). addEventListener
+// returns an unsubscribe function — there is no removeEventListener.
+const off = CometChatCalls.addEventListener("onAudioInputDevicesChanged", (devices) => {
   // re-enumerate; show toast "AirPods connected"
 });
+// later: off();
 ```
 
-Each device looks like:
+Each device is a standard `MediaDeviceInfo` (the SDK types are `AudioInputDevice = MediaDeviceInfo & { kind: 'audioinput' }`, etc.). The fields you use:
 ```ts
-interface MediaDevice {
-  id: string;          // browser-assigned ID
-  label: string;       // "Built-in Microphone", "AirPods Pro"
-  // ... other fields per browser
-}
+// deviceId: string   ← the ID you pass to setAudioInputDevice() (NOT `id`)
+// label:    string   ← "Built-in Microphone" / "AirPods Pro" (empty until mic permission granted)
+// kind:     'audioinput' | 'videoinput' | 'audiooutput'
 ```
 
 ---
@@ -48,12 +51,11 @@ interface MediaDevice {
 import { useEffect, useState } from "react";
 import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
 
-interface MediaDevice { id: string; label: string; }
-
 function DevicePicker({ onConfirm }: { onConfirm: () => void }) {
-  const [mics, setMics] = useState<MediaDevice[]>([]);
-  const [cameras, setCameras] = useState<MediaDevice[]>([]);
-  const [speakers, setSpeakers] = useState<MediaDevice[]>([]);
+  // Devices are MediaDeviceInfo objects — use `deviceId`, NOT `id`.
+  const [mics, setMics] = useState<MediaDeviceInfo[]>([]);
+  const [cameras, setCameras] = useState<MediaDeviceInfo[]>([]);
+  const [speakers, setSpeakers] = useState<MediaDeviceInfo[]>([]);
   const [selectedMic, setSelectedMic] = useState<string>();
   const [selectedCamera, setSelectedCamera] = useState<string>();
   const [selectedSpeaker, setSelectedSpeaker] = useState<string>();
@@ -67,24 +69,24 @@ function DevicePicker({ onConfirm }: { onConfirm: () => void }) {
         // permission denied — labels will be empty; offer settings link
       }
 
-      const [m, c, s] = await Promise.all([
-        CometChatCalls.getAudioInputDevices(),
-        CometChatCalls.getVideoInputDevices(),
-        CometChatCalls.getAudioOutputDevices(),
-      ]);
+      // These getters are SYNCHRONOUS — no await / Promise.all needed.
+      const m = CometChatCalls.getAudioInputDevices();
+      const c = CometChatCalls.getVideoInputDevices();
+      const s = CometChatCalls.getAudioOutputDevices();
       setMics(m); setCameras(c); setSpeakers(s);
 
-      setSelectedMic(CometChatCalls.getCurrentAudioInputDevice()?.id ?? m[0]?.id);
-      setSelectedCamera(CometChatCalls.getCurrentVideoInputDevice()?.id ?? c[0]?.id);
-      setSelectedSpeaker(CometChatCalls.getCurrentAudioOutputDevice()?.id ?? s[0]?.id);
+      setSelectedMic(CometChatCalls.getCurrentAudioInputDevice()?.deviceId ?? m[0]?.deviceId);
+      setSelectedCamera(CometChatCalls.getCurrentVideoInputDevice()?.deviceId ?? c[0]?.deviceId);
+      setSelectedSpeaker(CometChatCalls.getCurrentAudioOutputDevice()?.deviceId ?? s[0]?.deviceId);
     }
     load();
   }, []);
 
-  async function confirm() {
-    if (selectedMic) await CometChatCalls.setAudioInputDevice(selectedMic);
-    if (selectedCamera) await CometChatCalls.setVideoInputDevice(selectedCamera);
-    if (selectedSpeaker) await CometChatCalls.setAudioOutputDevice(selectedSpeaker);
+  function confirm() {
+    // setters are synchronous, return void
+    if (selectedMic) CometChatCalls.setAudioInputDevice(selectedMic);
+    if (selectedCamera) CometChatCalls.setVideoInputDevice(selectedCamera);
+    if (selectedSpeaker) CometChatCalls.setAudioOutputDevice(selectedSpeaker);
     onConfirm();
   }
 
@@ -93,19 +95,19 @@ function DevicePicker({ onConfirm }: { onConfirm: () => void }) {
       <label>
         Microphone
         <select value={selectedMic} onChange={(e) => setSelectedMic(e.target.value)}>
-          {mics.map(d => <option key={d.id} value={d.id}>{d.label || `Mic ${d.id.slice(0, 6)}`}</option>)}
+          {mics.map(d => <option key={d.deviceId} value={d.deviceId}>{d.label || `Mic ${d.deviceId.slice(0, 6)}`}</option>)}
         </select>
       </label>
       <label>
         Camera
         <select value={selectedCamera} onChange={(e) => setSelectedCamera(e.target.value)}>
-          {cameras.map(d => <option key={d.id} value={d.id}>{d.label || `Camera ${d.id.slice(0, 6)}`}</option>)}
+          {cameras.map(d => <option key={d.deviceId} value={d.deviceId}>{d.label || `Camera ${d.deviceId.slice(0, 6)}`}</option>)}
         </select>
       </label>
       <label>
         Speaker
         <select value={selectedSpeaker} onChange={(e) => setSelectedSpeaker(e.target.value)}>
-          {speakers.map(d => <option key={d.id} value={d.id}>{d.label || `Speaker ${d.id.slice(0, 6)}`}</option>)}
+          {speakers.map(d => <option key={d.deviceId} value={d.deviceId}>{d.label || `Speaker ${d.deviceId.slice(0, 6)}`}</option>)}
         </select>
       </label>
       <button type="button" onClick={confirm}>Join call</button>
@@ -123,21 +125,23 @@ function DevicePicker({ onConfirm }: { onConfirm: () => void }) {
 ```tsx
 function InCallDeviceSettings() {
   const [showMenu, setShowMenu] = useState(false);
-  const [mics, setMics] = useState<MediaDevice[]>([]);
+  const [mics, setMics] = useState<MediaDeviceInfo[]>([]);
 
   useEffect(() => {
     if (!showMenu) return;
-    CometChatCalls.getAudioInputDevices().then(setMics);
-    
-    const onModesUpdated = () => {
-      CometChatCalls.getAudioInputDevices().then(setMics);
-    };
-    CometChatCalls.addEventListener("onAudioModesUpdated", onModesUpdated);
-    return () => CometChatCalls.removeEventListener("onAudioModesUpdated", onModesUpdated);
+    // getAudioInputDevices() is synchronous — returns an array, no .then().
+    setMics(CometChatCalls.getAudioInputDevices());
+
+    // addEventListener returns an unsubscribe fn — call it to clean up
+    // (there is no removeEventListener on the SDK).
+    const off = CometChatCalls.addEventListener("onAudioInputDevicesChanged", () => {
+      setMics(CometChatCalls.getAudioInputDevices());
+    });
+    return () => off();
   }, [showMenu]);
 
-  async function selectMic(id: string) {
-    await CometChatCalls.setAudioInputDevice(id);
+  function selectMic(id: string) {
+    CometChatCalls.setAudioInputDevice(id);   // synchronous, returns void
     setShowMenu(false);
   }
 
@@ -147,8 +151,8 @@ function InCallDeviceSettings() {
       {showMenu && (
         <ul role="menu">
           {mics.map(d => (
-            <li key={d.id}>
-              <button role="menuitem" onClick={() => selectMic(d.id)}>{d.label}</button>
+            <li key={d.deviceId}>
+              <button role="menuitem" onClick={() => selectMic(d.deviceId)}>{d.label}</button>
             </li>
           ))}
         </ul>
@@ -158,7 +162,7 @@ function InCallDeviceSettings() {
 }
 ```
 
-`onAudioModesUpdated` fires when the user plugs in headphones, AirPods connect, etc. Re-enumerate on the event.
+`onAudioInputDevicesChanged` (and `onAudioOutputDevicesChanged` / `onVideoInputDevicesChanged`) fire when the user plugs in headphones, AirPods connect, etc. Re-enumerate on the event.
 
 ---
 
@@ -179,7 +183,7 @@ if (safari) {
 ## Anti-patterns
 
 1. **Calling `getAudioInputDevices` before requesting permission.** Returns devices with empty `label` strings — UI shows "undefined" or empty entries.
-2. **Caching device list.** Devices change (plug/unplug). Re-enumerate on every menu open AND on `onAudioModesUpdated`.
+2. **Caching device list.** Devices change (plug/unplug). Re-enumerate on every menu open AND on `onAudioInputDevicesChanged`.
 3. **Hardcoding the first device as default.** Browsers may sort differently (built-in vs USB). Read `getCurrent*Device` first; only fall back to first if no current selection.
 4. **Switching speakers in Safari.** `setAudioOutputDevice` silently fails. Detect Safari and hide the speaker picker (or show a "iOS uses system routing" tooltip).
 5. **No listener cleanup on unmount.** Event accumulates listeners on remount; spam every device change.
@@ -190,7 +194,7 @@ if (safari) {
 
 - [ ] Permission requested before enumeration (empty-label fix)
 - [ ] `getCurrent*Device()` used as default in pickers
-- [ ] `onAudioModesUpdated` listener for hot-swap detection
+- [ ] `onAudioInputDevicesChanged` listener for hot-swap detection (unsubscribe via the returned fn)
 - [ ] Listener cleanup on unmount
 - [ ] Safari speaker picker hidden / fallback message
 - [ ] Browser smoke: plug/unplug headphones during call, picker updates

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

@@ -106,19 +106,17 @@ async function startGroupCall(guid: string, callType: "audio" | "video") {
   const authToken = loggedInUser.getAuthToken();
   const { token: callToken } = await CometChatCalls.generateToken(sessionId);
 
-  const callSettings = new CometChatCalls.CallSettingsBuilder()
-    .setIsAudioOnlyCall(callType === "audio")
-    .enableDefaultLayout(true)
-    .setCallListener(
-      new CometChatCalls.OngoingCallListener({
-        onCallEnded: () => { /* hangup UI */ },
-        onError: (err) => { /* show error */ },
-      }),
-    )
-    .build();
+  // joinSession takes a SessionSettings OBJECT (NOT CallSettingsBuilder.build() —
+  // that CallSettings is for the deprecated startSession). Events come from the
+  // static addEventListener bus, not OngoingCallListener.
+  const settings = { sessionType: callType === "audio" ? "VOICE" : "VIDEO" };
+  const offClosed = CometChatCalls.addEventListener("onConnectionClosed", () => {
+    /* hangup UI */
+  });
+  // later, on teardown: offClosed();
 
   // 3. Mount the WebRTC view into your container element
-  await CometChatCalls.joinSession(callToken, callSettings, containerElement);
+  await CometChatCalls.joinSession(callToken, settings, containerElement);
 }
 ```
 
@@ -182,17 +180,14 @@ async function joinGroupCall(sessionId: string, callType: "audio" | "video", con
   const authToken = loggedInUser!.getAuthToken();
   const { token: callToken } = await CometChatCalls.generateToken(sessionId);
 
-  const callSettings = new CometChatCalls.CallSettingsBuilder()
-    .setIsAudioOnlyCall(callType === "audio")
-    .enableDefaultLayout(true)
-    .setCallListener(
-      new CometChatCalls.OngoingCallListener({
-        onCallEnded: () => { /* hangup UI */ },
-      }),
-    )
-    .build();
-
-  await CometChatCalls.joinSession(callToken, callSettings, container);
+  // SessionSettings OBJECT for joinSession (not CallSettingsBuilder output).
+  const settings = { sessionType: callType === "audio" ? "VOICE" : "VIDEO" };
+  const offClosed = CometChatCalls.addEventListener("onConnectionClosed", () => {
+    /* hangup UI */
+  });
+  // later, on teardown: offClosed();
+
+  await CometChatCalls.joinSession(callToken, settings, container);
 }
 ```
 
@@ -259,4 +254,4 @@ Since meetings don't ring, there's no "missed call" entity. If you want missed-m
 - `call-session.md` — pure session-mode (URL-based, no chat-side signaling at all)
 - `cometchat-react-calls/SKILL.md` rule 1.7 — IncomingCall mount (1:1 only; group calls don't use this)
 - Canonical docs: https://www.cometchat.com/docs/calls/javascript/group-calls
-- Kit source (verified 2026-05-15): `node_modules/@cometchat/chat-uikit-react-native/src/calls/CometChatCallButtons/CometChatCallButtons.tsx:138-201`
+- Kit source (web React): `@cometchat/chat-uikit-react` → `src/components/Calling/CometChatCallButtons/CometChatCallButtons.tsx` (group call buttons send the `meeting` custom message)

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

@@ -9,22 +9,34 @@ Auto-ends calls where the local user is the only remaining participant. Two time
 
 ## SDK API
 
+> ⚠️ **VALUES ARE IN MILLISECONDS.** `idleTimeoutPeriodBeforePrompt: 180` is **180 ms**, not 180 seconds — so the prompt fires the instant you join alone and the call exits in a fraction of a second (real customer bug, 2026-06). Always `* 1000`: 3 minutes = `180_000`.
+
+Two equivalent ways to set it — **match whichever your join path uses:**
+
 ```ts
-const settings = new CometChatCalls.CallSettingsBuilder()
-  .setSessionID(sessionId)
-  .setIdleTimeoutPeriodBeforePrompt(60_000)   // 60s — first warning fires
-  .setIdleTimeoutPeriodAfterPrompt(120_000)   // 120s — session ends if no response
-  .build();
+// (a) SessionSettings OBJECT — the session-mode path: joinSession(token, settings, container)
+const settings = {
+  idleTimeoutPeriodBeforePrompt: 180_000,  // 180s before the "still there?" prompt
+  idleTimeoutPeriodAfterPrompt: 60_000,    // 60s grace (this is the SDK MINIMUM)
+};
+await CometChatCalls.joinSession(token, settings, containerRef.current);
+
+// (b) Builder — the kit's callSettingsBuilder prop. ⚠️ The builder has ONLY a
+// single .setIdleTimeoutPeriod(ms) — there are NO setIdleTimeoutPeriodBeforePrompt /
+// setIdleTimeoutPeriodAfterPrompt builder methods. The before/after-prompt SPLIT
+// exists only as the SessionSettings object fields in form (a) above.
+const builder = new CometChatCalls.CallSettingsBuilder()
+  .setIdleTimeoutPeriod(180_000);
 
 CometChatCalls.addEventListener("onSessionTimedOut", () => {
   // Navigate away, show "session ended" UI
 });
 ```
 
-| Setting | Default | Min | Use case |
+| Setting | Default | Min | Unit |
 |---|---|---|---|
-| `idleTimeoutPeriodBeforePrompt` | 60_000 (60s) | 0 (immediate) | Time alone before the "still there?" prompt |
-| `idleTimeoutPeriodAfterPrompt` | 120_000 (120s) | 60_000 (60s) | Grace period after the prompt before forced disconnect |
+| `idleTimeoutPeriodBeforePrompt` | 60_000 (60s) | — (don't use 0 / tiny — instant prompt) | **milliseconds** |
+| `idleTimeoutPeriodAfterPrompt` | 120_000 (120s) | **60_000 (60s)** — smaller is silently clamped to 60s | **milliseconds** |
 
 The SDK shows the prompt overlay automatically (kit's default UI). For custom UI you handle the prompt yourself.
 
@@ -132,10 +144,11 @@ function CustomCallView() {
 ### Pattern B — Long timeouts + custom prompt only
 
 ```ts
-const settings = new CometChatCalls.CallSettingsBuilder()
-  .setIdleTimeoutPeriodBeforePrompt(86_400_000)   // 24 hours — effectively disabled
-  .setIdleTimeoutPeriodAfterPrompt(86_400_000)
-  .build();
+// SessionSettings object for joinSession (these before/after fields are object-only).
+const settings = {
+  idleTimeoutPeriodBeforePrompt: 86_400_000,   // 24 hours — effectively disabled
+  idleTimeoutPeriodAfterPrompt: 86_400_000,
+};
 ```
 
 Then implement your own timeout via Pattern A. Useful when you want UX-customized prompts instead of the SDK's default overlay.

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

@@ -10,10 +10,9 @@ Text messaging during a video/voice call. SDK provides the chat button in the co
 ## SDK API
 
 ```ts
-const settings = new CometChatCalls.CallSettingsBuilder()
-  .setSessionID(sessionId)
-  .hideChatButton(false)               // show the kit's built-in chat button
-  .build();
+// SessionSettings object passed to joinSession(token, settings, container).
+// hideChatButton is a SessionSettings field, not a CallSettingsBuilder method.
+const settings = { hideChatButton: false };   // show the kit's built-in chat button
 
 CometChatCalls.addEventListener("onChatButtonClicked", () => {
   // Open your chat panel
@@ -56,7 +55,7 @@ async function joinCallGroup(sessionId: string): Promise<void> {
 }
 ```
 
-Wire this into your call-start flow: after `startSession` succeeds, `joinCallGroup`.
+Wire this into your call-start flow: after `joinSession` succeeds, `joinCallGroup`.
 
 ---
 
@@ -83,8 +82,9 @@ function InCallChatPanel({ sessionId }: InCallChatPanelProps) {
   // Listen for the SDK's button click
   useEffect(() => {
     const handler = () => setOpen(true);
-    CometChatCalls.addEventListener("onChatButtonClicked", handler);
-    return () => CometChatCalls.removeEventListener("onChatButtonClicked", handler);
+    // addEventListener returns an unsubscribe fn — there is no removeEventListener.
+    const off = CometChatCalls.addEventListener("onChatButtonClicked", handler);
+    return () => off();
   }, []);
 
   // Resolve the group object for the message list

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

@@ -35,8 +35,8 @@ If you're using CometChat UI Kits, this is enough — the kit's calls integratio
 v5 introduces a dedicated Calls SDK auth step. After the user logs into the Chat SDK, call:
 
 ```ts
-const authToken = (await CometChat.getLoggedinUser())!.getAuthToken();
-await CometChatCalls.login(authToken);
+const authToken = (await CometChat.getLoggedInUser())!.getAuthToken();
+await CometChatCalls.loginWithAuthToken(authToken);  // login() takes a uid; use loginWithAuthToken for a token
 ```
 
 After this, `generateToken()` and `joinSession()` no longer need an authToken parameter.
@@ -120,11 +120,10 @@ After this, `generateToken()` and `joinSession()` no longer need an authToken pa
 
 - CometChatCalls.startScreenShare()
 + CometChatCalls.startScreenSharing()
-
-- CometChatCalls.enterPIPMode()
-+ CometChatCalls.enablePictureInPictureLayout()
 ```
 
+> PiP rename: v4's `enterPIPMode()` became the static `CometChatCalls.enablePictureInPictureLayout()` in v5 (paired with `disablePictureInPictureLayout()`). Note the `onPictureInPictureLayoutEnabled` / `...Disabled` **callbacks are on `MobileSDKEvents`, not `WebSDKEvents`** — they are NOT subscribable via `CometChatCalls.addEventListener` on the web SDK (verified in `@cometchat/calls-sdk-javascript` `index.d.ts`: `MobileSDKEvents` vs `WebSDKEvents`). On **web**, prefer browser-native picture-in-picture — see `references/picture-in-picture.md`.
+
 ---
 
 ## Step 7 — `startSession` → `joinSession`
@@ -134,14 +133,13 @@ After this, `generateToken()` and `joinSession()` no longer need an authToken pa
 -   CometChatCalls.startSession(token, callSettings, container);
 - });
 
-+ CometChatCalls.generateToken(sessionId).then((token) => {
++ CometChatCalls.generateToken(sessionId).then(({ token }) => {
 +   CometChatCalls.joinSession(token, sessionSettings, container);
 + });
-+
-+ // Or — pass the sessionId directly (no manual token mint):
-+ CometChatCalls.joinSession(sessionId, sessionSettings, container);
 ```
 
+> `joinSession`'s first arg is the **callToken** (from `generateToken`), not a sessionId — there is no token-free join. `generateToken` resolves to `{ token }`, so destructure it.
+
 ---
 
 ## Removed methods (no v5 replacement)
@@ -154,7 +152,7 @@ After this, `generateToken()` and `joinSession()` no longer need an authToken pa
 ## Verification checklist
 
 - [ ] `package.json` lists `@cometchat/calls-sdk-javascript@^5`
-- [ ] `await CometChatCalls.login(authToken)` called after `CometChat.login`
+- [ ] `await CometChatCalls.loginWithAuthToken(authToken)` called after `CometChat.login`
 - [ ] `OngoingCallListener` removed; granular `addEventListener` calls in place with cleanup
 - [ ] `startSession` replaced with `joinSession`
 - [ ] `endSession` replaced with `leaveSession`
@@ -169,4 +167,4 @@ After this, `generateToken()` and `joinSession()` no longer need an authToken pa
 - Canonical migration guide: https://www.cometchat.com/docs/calls/javascript/migration-guide-v5
 - `cometchat-react-calls/SKILL.md` — current architecture (v5)
 - `cometchat-react-calls/references/call-layouts.md` — layout enum migration
-- `cometchat-react-calls/references/recording.md` — recording events migration
+- `cometchat-react-calls/references/recording-screen-share.md` — recording events migration

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

@@ -31,10 +31,11 @@ CometChatCalls.addEventListener("onParticipantHandLowered", (participant) => {
 The SDK ships a built-in raise-hand button in the default control panel. Hide it via call settings if you're rolling custom UI:
 
 ```ts
-const callSettings = new CometChatCalls.CallSettingsBuilder()
-  .setSessionID(sessionId)
-  .hideRaiseHandButton(true)         // suppress the SDK's button — your UI takes over
-  .build();
+// SessionSettings object passed to joinSession(token, settings, container).
+// hideRaiseHandButton is a SessionSettings field — NOT a CallSettingsBuilder
+// method, and there is no setSessionID (the session is carried by the token
+// from generateToken(sessionId)).
+const settings = { hideRaiseHandButton: true };  // suppress the SDK's button — your UI takes over
 ```
 
 ---
@@ -108,12 +109,13 @@ function RaisedHandsList() {
       });
     };
 
-    CometChatCalls.addEventListener("onParticipantHandRaised", onRaised);
-    CometChatCalls.addEventListener("onParticipantHandLowered", onLowered);
+    // addEventListener returns an unsubscribe fn — there is no removeEventListener.
+    const offRaised = CometChatCalls.addEventListener("onParticipantHandRaised", onRaised);
+    const offLowered = CometChatCalls.addEventListener("onParticipantHandLowered", onLowered);
 
     return () => {
-      CometChatCalls.removeEventListener("onParticipantHandRaised", onRaised);
-      CometChatCalls.removeEventListener("onParticipantHandLowered", onLowered);
+      offRaised();
+      offLowered();
     };
   }, []);
 
@@ -144,8 +146,8 @@ useEffect(() => {
   const onRaised = (p: { name: string }) => {
     toast.info(`${p.name} raised their hand`, { duration: 4000 });
   };
-  CometChatCalls.addEventListener("onParticipantHandRaised", onRaised);
-  return () => CometChatCalls.removeEventListener("onParticipantHandRaised", onRaised);
+  const offRaised = CometChatCalls.addEventListener("onParticipantHandRaised", onRaised);
+  return () => offRaised();
 }, []);
 ```
 
@@ -194,10 +196,8 @@ If using the kit's `<CometChatOngoingCall />` and want raise-hand off entirely (
 ```tsx
 import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
 
-const settings = new CometChatCalls.CallSettingsBuilder()
-  .setSessionID(sessionId)
-  .hideRaiseHandButton(true)
-  .build();
+// SessionSettings object for joinSession (hideRaiseHandButton is an object field).
+const settings = { hideRaiseHandButton: true };
 ```
 
 For 1:1 calls, default to hidden. For group calls > 5 participants, default to shown.