@cometchat/skills 4.1.0 → 4.2.0

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

@@ -0,0 +1,175 @@
+# Idle timeout on web
+
+Auto-ends calls where the local user is the only remaining participant. Two timers: a "you're alone, are you still there?" prompt fires after the first interval, then the session ends if the user doesn't respond before the second interval. SDK first-party — just two settings keys + one event.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/javascript/idle-timeout
+**Use it for:** any group call (preventing zombie sessions when everyone else hangs up), waiting rooms (auto-close empty rooms), classroom calls (instructor's screen doesn't stay live overnight).
+
+---
+
+## SDK API
+
+```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();
+
+CometChatCalls.addEventListener("onSessionTimedOut", () => {
+  // Navigate away, show "session ended" UI
+});
+```
+
+| Setting | Default | Min | Use case |
+|---|---|---|---|
+| `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 |
+
+The SDK shows the prompt overlay automatically (kit's default UI). For custom UI you handle the prompt yourself.
+
+---
+
+## Recommended timeouts per app archetype
+
+| App | Before-prompt | After-prompt | Why |
+|---|---|---|---|
+| Marketplace 1:1 | 30s | 60s | Buyers lose interest fast; reclaim resources |
+| Telehealth (provider waiting) | 5min | 5min | Patients run late; don't punish them |
+| Classroom / instructor | 10min | 10min | Instructor may step away; don't interrupt class |
+| Internal team meeting | 60s | 120s | Default — meetings end abruptly anyway |
+| Customer support | 30s | 60s | Agent moves to next ticket; reclaim |
+
+---
+
+## Custom prompt UI (when default isn't enough)
+
+The kit's default prompt is functional but plain. Custom UI uses `enableDefaultLayout(false)` + listens for the prompt internally — though the SDK doesn't expose a direct "prompt fired" event. Two patterns:
+
+### Pattern A — Track time-since-alone yourself
+
+```tsx
+import { useEffect, useRef, useState } from "react";
+import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
+
+function useIdleTimeoutPrompt({
+  beforePromptMs = 60_000,
+  afterPromptMs = 120_000,
+}: { beforePromptMs?: number; afterPromptMs?: number; }) {
+  const [showPrompt, setShowPrompt] = useState(false);
+  const aloneSinceRef = useRef<number | null>(null);
+  const promptTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const sessionTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    const listener = new CometChatCalls.OngoingCallListener({
+      onUserListUpdated: (users: { uid: string }[]) => {
+        const localUid = CometChat.getLoggedinUser()?.getUid();
+        const remoteCount = users.filter(u => u.uid !== localUid).length;
+
+        if (remoteCount === 0 && aloneSinceRef.current === null) {
+          // Just became alone
+          aloneSinceRef.current = Date.now();
+          promptTimerRef.current = setTimeout(() => {
+            setShowPrompt(true);
+            sessionTimerRef.current = setTimeout(() => {
+              CometChatCalls.leaveSession();
+            }, afterPromptMs);
+          }, beforePromptMs);
+        } else if (remoteCount > 0) {
+          // Someone joined — clear timers
+          aloneSinceRef.current = null;
+          if (promptTimerRef.current) clearTimeout(promptTimerRef.current);
+          if (sessionTimerRef.current) clearTimeout(sessionTimerRef.current);
+          setShowPrompt(false);
+        }
+      },
+    });
+
+    // Attach listener... (see custom-ui.md for the full setup)
+
+    return () => {
+      if (promptTimerRef.current) clearTimeout(promptTimerRef.current);
+      if (sessionTimerRef.current) clearTimeout(sessionTimerRef.current);
+    };
+  }, [beforePromptMs, afterPromptMs]);
+
+  function dismiss() {
+    setShowPrompt(false);
+    if (sessionTimerRef.current) clearTimeout(sessionTimerRef.current);
+    aloneSinceRef.current = null;
+  }
+
+  return { showPrompt, dismiss };
+}
+```
+
+Usage:
+
+```tsx
+function CustomCallView() {
+  const { showPrompt, dismiss } = useIdleTimeoutPrompt({
+    beforePromptMs: 30_000,
+    afterPromptMs: 60_000,
+  });
+
+  return (
+    <>
+      {/* call UI */}
+      {showPrompt && (
+        <div role="alertdialog" aria-modal="true" aria-labelledby="idle-title">
+          <h2 id="idle-title">Still there?</h2>
+          <p>You're alone in this call. It'll end in 60 seconds.</p>
+          <button onClick={dismiss}>Stay</button>
+          <button onClick={() => CometChatCalls.leaveSession()}>End now</button>
+        </div>
+      )}
+    </>
+  );
+}
+```
+
+### 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();
+```
+
+Then implement your own timeout via Pattern A. Useful when you want UX-customized prompts instead of the SDK's default overlay.
+
+---
+
+## Anti-patterns
+
+1. **`idleTimeoutPeriodAfterPrompt < 60_000` (60s).** SDK rejects values below 60s. Setting it lower silently fails — the SDK uses 60s instead.
+2. **Disabling idle timeout entirely** by setting both timers to `Infinity`. Sessions hang forever, server-side resources leak, billing dings you. Always set a reasonable upper bound.
+3. **Showing the prompt at the same time as call notifications/banners.** Stacks on top of incoming-message notifications. Z-index conflicts. Render the idle prompt at the highest z-level for the call surface.
+4. **Auto-ending without a goodbye animation.** Jarring. Fade-out the call surface over 500ms before disconnecting.
+5. **Prompt UI without `role="alertdialog"`.** Screen readers don't pause to announce; user gets disconnected mid-listen. Use `role="alertdialog"` + `aria-modal="true"`.
+6. **Restarting `aloneSinceRef.current` on EVERY participant change.** Want to track "alone since" only when transitioning from N>0 to 0. Don't reset when participants join/leave while still N>0.
+
+---
+
+## Verification checklist
+
+- [ ] `setIdleTimeoutPeriodBeforePrompt` + `setIdleTimeoutPeriodAfterPrompt` set on CallSettings
+- [ ] After-prompt period ≥ 60_000 (60s)
+- [ ] `onSessionTimedOut` event handler navigates away cleanly (not just `console.log`)
+- [ ] Custom prompt UI uses `role="alertdialog"` + `aria-modal="true"`
+- [ ] Custom prompt has both "Stay" and "End now" buttons
+- [ ] Timer cleanup in `useEffect` return — no leaked setTimeout
+- [ ] Browser smoke: 2 tabs in call, close tab B, watch tab A's timer fire (set short timeouts for testing)
+- [ ] After-prompt smoke: dismiss the prompt → timer clears → no auto-disconnect
+
+---
+
+## Pointers
+
+- `cometchat-react-calls` SKILL.md — the seven hard rules
+- `references/group-calls.md` — group call architecture (idle-timeout matters most for groups)
+- `references/custom-ui.md` — custom call UI integration
+- `cometchat-a11y` — `role="alertdialog"` patterns
+- Canonical docs: https://www.cometchat.com/docs/calls/javascript/idle-timeout

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

@@ -0,0 +1,212 @@
+# In-call chat on web
+
+Text messaging during a video/voice call. SDK provides the chat button in the control panel + events; the actual chat UI is yours to build (the kit's existing `<CometChatMessageList>` + `<CometChatMessageComposer>` work great here).
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/javascript/in-call-chat
+**Use it for:** classroom side chat, team meeting links/notes, customer support secondary channel, AV-impaired participant text fallback.
+
+---
+
+## SDK API
+
+```ts
+const settings = new CometChatCalls.CallSettingsBuilder()
+  .setSessionID(sessionId)
+  .hideChatButton(false)               // show the kit's built-in chat button
+  .build();
+
+CometChatCalls.addEventListener("onChatButtonClicked", () => {
+  // Open your chat panel
+  setChatOpen(true);
+});
+
+// Update unread badge
+CometChatCalls.setChatButtonUnreadCount(5);
+CometChatCalls.setChatButtonUnreadCount(0);   // clear
+```
+
+The button + badge live on the SDK's control panel. Your job is to render the chat UI when the button is tapped.
+
+---
+
+## Architecture: group-as-session
+
+The recommended pattern: use a CometChat **group** keyed to the call session. Every participant joins the group when they join the call; messages flow through the group's normal CometChat Chat SDK channel. When the call ends, the group either persists (logged history) or is deleted (ephemeral).
+
+```ts
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+
+async function ensureCallGroup(sessionId: string): Promise<CometChat.Group> {
+  // Try to get existing
+  try {
+    return await CometChat.getGroup(sessionId);
+  } catch {
+    // Create
+    const group = new CometChat.Group(
+      sessionId,                    // GUID == session ID
+      `Call ${sessionId}`,          // display name
+      CometChat.GROUP_TYPE.PUBLIC,  // anyone in the call can join
+    );
+    return await CometChat.createGroup(group);
+  }
+}
+
+async function joinCallGroup(sessionId: string): Promise<void> {
+  await CometChat.joinGroup(sessionId, CometChat.GROUP_TYPE.PUBLIC, "");
+}
+```
+
+Wire this into your call-start flow: after `startSession` succeeds, `joinCallGroup`.
+
+---
+
+## Chat panel UI
+
+```tsx
+import { useState, useEffect } from "react";
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
+import {
+  CometChatMessageList,
+  CometChatMessageComposer,
+} from "@cometchat/chat-uikit-react";
+
+interface InCallChatPanelProps {
+  sessionId: string;
+}
+
+function InCallChatPanel({ sessionId }: InCallChatPanelProps) {
+  const [open, setOpen] = useState(false);
+  const [unread, setUnread] = useState(0);
+  const [group, setGroup] = useState<CometChat.Group>();
+
+  // Listen for the SDK's button click
+  useEffect(() => {
+    const handler = () => setOpen(true);
+    CometChatCalls.addEventListener("onChatButtonClicked", handler);
+    return () => CometChatCalls.removeEventListener("onChatButtonClicked", handler);
+  }, []);
+
+  // Resolve the group object for the message list
+  useEffect(() => {
+    CometChat.getGroup(sessionId).then(setGroup).catch(() => {});
+  }, [sessionId]);
+
+  // Track unread when panel is closed
+  useEffect(() => {
+    const listenerId = `in-call-chat-${sessionId}`;
+    const messageListener = new CometChat.MessageListener({
+      onTextMessageReceived: (msg: CometChat.TextMessage) => {
+        if (
+          msg.getReceiverType() === CometChat.RECEIVER_TYPE.GROUP &&
+          msg.getReceiverId() === sessionId &&
+          !open
+        ) {
+          setUnread((u) => {
+            const next = u + 1;
+            CometChatCalls.setChatButtonUnreadCount(next);
+            return next;
+          });
+        }
+      },
+    });
+    CometChat.addMessageListener(listenerId, messageListener);
+    return () => CometChat.removeMessageListener(listenerId);
+  }, [sessionId, open]);
+
+  // Clear badge on open
+  useEffect(() => {
+    if (open) {
+      setUnread(0);
+      CometChatCalls.setChatButtonUnreadCount(0);
+    }
+  }, [open]);
+
+  if (!open || !group) return null;
+
+  return (
+    <div
+      role="dialog"
+      aria-label="In-call chat"
+      style={{
+        position: "fixed",
+        right: 0,
+        top: 0,
+        bottom: 0,
+        width: 360,
+        background: "var(--cometchat-background-color-01)",
+        borderLeft: "1px solid var(--cometchat-border-color-light)",
+        display: "flex",
+        flexDirection: "column",
+        zIndex: 200,
+      }}
+    >
+      <div style={{ padding: "12px 16px", borderBottom: "1px solid var(--cometchat-border-color-light)", display: "flex", justifyContent: "space-between", alignItems: "center" }}>
+        <strong>Chat</strong>
+        <button onClick={() => setOpen(false)} aria-label="Close chat">×</button>
+      </div>
+      {/* The flex-1 + minHeight:0 dance applies here too — long chat → composer would push down */}
+      <div style={{ flex: "1 1 0", minHeight: 0, overflow: "hidden" }}>
+        <CometChatMessageList group={group} hideReplyInThreadOption />
+      </div>
+      <div style={{ flex: "0 0 auto" }}>
+        <CometChatMessageComposer group={group} />
+      </div>
+    </div>
+  );
+}
+```
+
+The flex-1 + minHeight:0 + wrap-each-component pattern from `cometchat-react-patterns` rule 6a applies inside the chat panel too.
+
+---
+
+## Compact UX patterns
+
+For 1:1 calls or small groups, an in-call chat panel is overkill. Two lighter patterns:
+
+### A — Floating message strip (top of call)
+
+Show only the latest message inline; tap to open full chat. Minimal UI for "just the gist."
+
+### B — System-toast on each message
+
+`onTextMessageReceived` → toast at top of call. Auto-dismiss after 4s. No persistent panel.
+
+The full panel pattern above is for 5+-person calls or when chat is a load-bearing part of the experience (e.g. classroom Q&A).
+
+---
+
+## Anti-patterns
+
+1. **Polling for unread count.** SDK's `setChatButtonUnreadCount` is push-based; respond to message events.
+2. **Chat panel grows past viewport on long sessions.** flex-shrink trap (see `cometchat-react-patterns` rule 6a).
+3. **Forgetting to clear the unread badge on panel open.** User opens, sees "12 new" badge that doesn't update — looks broken.
+4. **Persisting the call group forever.** For ephemeral calls (consultations, support), delete the group on call end. Hosts of recurring meetings keep groups.
+5. **Sending messages without auth.** Make sure CometChat.login resolved before joining the group. Race conditions on early call accept.
+6. **Reusing one chat-panel instance across multiple calls.** Group reference goes stale. Re-mount per call.
+
+---
+
+## Verification checklist
+
+- [ ] `hideChatButton: false` in CallSettings
+- [ ] `onChatButtonClicked` listener opens the panel
+- [ ] CometChat group created/resolved with sessionId as GUID
+- [ ] Local user joins the group on call start
+- [ ] Unread badge updates from `onTextMessageReceived` only when panel closed
+- [ ] Badge cleared on panel open
+- [ ] Chat panel uses flex-1 + minHeight:0 + wrap-each-component pattern
+- [ ] `role="dialog"` + `aria-label` on the panel container
+- [ ] Cleanup: remove message + chat-button listeners on call end
+- [ ] Browser smoke: 2 tabs in call, send message from A → unread badge in B → tap → message visible
+
+---
+
+## Pointers
+
+- `cometchat-react-calls` SKILL.md
+- `cometchat-react-patterns` — minHeight:0 rule 6a (applies to in-call chat panel)
+- `references/group-calls.md` — group call architecture
+- `cometchat-android-v5-calls/references/in-call-chat.md` — Android V5 sibling reference
+- Canonical docs: https://www.cometchat.com/docs/calls/javascript/in-call-chat

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

@@ -0,0 +1,172 @@
+# Calls SDK v4 → v5 migration (web)
+
+CometChat Calls SDK v5 is a **drop-in replacement** for v4 — bump the package, your existing code keeps working through deprecation shims. Migrate to v5 APIs to get granular event listeners, simpler init, and strongly-typed enums.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/javascript/migration-guide-v5
+
+---
+
+## Step 1 — Bump the package
+
+```bash
+npm install @cometchat/calls-sdk-javascript@5
+```
+
+If you're using CometChat UI Kits, this is enough — the kit's calls integration uses the v4 deprecated layer. **You can ship to production at this step** and migrate v5 APIs incrementally.
+
+---
+
+## Step 2 — Migrate init (optional but cleaner)
+
+```diff
+- const callAppSettings = new CometChatCalls.CallAppSettingsBuilder()
+-   .setAppId("APP_ID")
+-   .setRegion("REGION")
+-   .build();
+- await CometChatCalls.init(callAppSettings);
+
++ await CometChatCalls.init({ appId: "APP_ID", region: "REGION" });
+```
+
+---
+
+## Step 3 — Add `login()` after Chat SDK login
+
+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);
+```
+
+After this, `generateToken()` and `joinSession()` no longer need an authToken parameter.
+
+---
+
+## Step 4 — Migrate session settings to plain object
+
+```diff
+- const callSettings = new CometChatCalls.CallSettingsBuilder()
+-   .setIsAudioOnlyCall(true)
+-   .showRecordingButton(true)
+-   .startWithAudioMuted(false)
+-   .build();
+
++ const sessionSettings = {
++   sessionType: "VOICE",       // was setIsAudioOnlyCall(true)
++   hideRecordingButton: false,  // was showRecordingButton(true) — INVERTED
++   startAudioMuted: false,
++   layout: "TILE",
++ };
+```
+
+**Watch out:** the boolean logic is **inverted** for many settings (v4 `show*` → v5 `hide*`). Search-and-replace doesn't work — review each manually.
+
+---
+
+## Step 5 — Migrate events to granular listeners
+
+```diff
+- const callSettings = new CometChatCalls.CallSettingsBuilder()
+-   .setCallListener(new CometChatCalls.OngoingCallListener({
+-     onCallEnded: () => { /* ... */ },
+-     onUserJoined: (user) => { /* ... */ },
+-     onUserLeft: (user) => { /* ... */ },
+-     onError: (error) => { /* ... */ },
+-   }))
+-   .build();
+
++ const unsub1 = CometChatCalls.addEventListener("onSessionLeft", () => { /* ... */ });
++ const unsub2 = CometChatCalls.addEventListener("onParticipantJoined", (p) => { /* ... */ });
++ const unsub3 = CometChatCalls.addEventListener("onParticipantLeft", (p) => { /* ... */ });
++ // Errors now come back via Promise rejection from joinSession() etc.
++
++ // Cleanup
++ return () => { unsub1(); unsub2(); unsub3(); };
+```
+
+**Event-name mapping (most common):**
+
+| v4 | v5 |
+|---|---|
+| `onCallEnded` | `onSessionLeft` |
+| `onCallEndButtonPressed` | `onLeaveSessionButtonClicked` |
+| `onUserJoined(user)` | `onParticipantJoined(participant)` |
+| `onUserLeft(user)` | `onParticipantLeft(participant)` |
+| `onUserListUpdated(list)` | `onParticipantListChanged(list)` |
+| `onUserMuted(info)` | `onParticipantAudioMuted(participant)` |
+| `onRecordingToggled(info)` | `onRecordingStarted` / `onRecordingStopped` |
+
+---
+
+## Step 6 — Migrate session control method names
+
+```diff
+- CometChatCalls.endSession()
++ CometChatCalls.leaveSession()
+
+- CometChatCalls.muteAudio(true)
++ CometChatCalls.muteAudio()
+- CometChatCalls.muteAudio(false)
++ CometChatCalls.unmuteAudio()
+
+- CometChatCalls.pauseVideo(true)
++ CometChatCalls.pauseVideo()
+- CometChatCalls.pauseVideo(false)
++ CometChatCalls.resumeVideo()
+
+- CometChatCalls.setMode(mode)
++ CometChatCalls.setLayout(layout)
+
+- CometChatCalls.startScreenShare()
++ CometChatCalls.startScreenSharing()
+
+- CometChatCalls.enterPIPMode()
++ CometChatCalls.enablePictureInPictureLayout()
+```
+
+---
+
+## Step 7 — `startSession` → `joinSession`
+
+```diff
+- CometChatCalls.generateToken(sessionId, authToken).then((token) => {
+-   CometChatCalls.startSession(token, callSettings, container);
+- });
+
++ CometChatCalls.generateToken(sessionId).then((token) => {
++   CometChatCalls.joinSession(token, sessionSettings, container);
++ });
++
++ // Or — pass the sessionId directly (no manual token mint):
++ CometChatCalls.joinSession(sessionId, sessionSettings, container);
+```
+
+---
+
+## Removed methods (no v5 replacement)
+
+- `CometChatCalls.switchToVideoCall()` — start a fresh session with `sessionType: "VIDEO"` instead
+- `CometChatCalls.getCallDetails()` — track session state via events
+
+---
+
+## Verification checklist
+
+- [ ] `package.json` lists `@cometchat/calls-sdk-javascript@^5`
+- [ ] `await CometChatCalls.login(authToken)` called after `CometChat.login`
+- [ ] `OngoingCallListener` removed; granular `addEventListener` calls in place with cleanup
+- [ ] `startSession` replaced with `joinSession`
+- [ ] `endSession` replaced with `leaveSession`
+- [ ] Inverted booleans audited (show* → hide* with `!`)
+- [ ] No use of removed methods (`switchToVideoCall`, `getCallDetails`)
+- [ ] Existing call flows tested end-to-end (incoming, accept, mute, screen-share, end)
+
+---
+
+## Pointers
+
+- 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