@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-react-calls/references/add-calls-to-existing-chat.md

@@ -1,146 +0,0 @@
-# Adding calls to an existing chat integration (web)
-
-You already have CometChat chat working (`@cometchat/chat-sdk-javascript` + `@cometchat/chat-uikit-react`). This guide adds calling on top with minimum disruption.
-
-**Read first:** `cometchat-react-calls/SKILL.md` — the seven hard rules. They apply whether you're starting fresh or migrating.
-
----
-
-## Pre-flight
-
-Confirm what's already in place:
-
-```bash
-# Should show chat SDK + UI Kit
-grep -E '"@cometchat/(chat-sdk|chat-uikit)' package.json
-
-# Should NOT yet show calls SDK
-grep -E '"@cometchat/calls-sdk' package.json
-```
-
-If you already have `@cometchat/calls-sdk-javascript` installed, you're not migrating — re-running `/cometchat-calls` will integrate calls features (recording, share-invite, etc.) one at a time.
-
----
-
-## Step 1 — Install the calls SDK
-
-```bash
-npm install @cometchat/calls-sdk-javascript@5
-```
-
-This is a pure additive change. The chat SDK is unaffected.
-
----
-
-## Step 2 — Add calls init AFTER chat init
-
-The seven hard rules: chat must init before calls. If your existing init looks like:
-
-```ts
-// src/cometchat-init.ts
-import { CometChat } from "@cometchat/chat-sdk-javascript";
-
-const settings = new CometChat.AppSettingsBuilder()
-  .subscribePresenceForAllUsers()
-  .setRegion(REGION)
-  .build();
-
-await CometChat.init(APP_ID, settings);
-```
-
-Append the calls init:
-
-```ts
-import { CometChat } from "@cometchat/chat-sdk-javascript";
-import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
-
-const settings = new CometChat.AppSettingsBuilder()
-  .subscribePresenceForAllUsers()
-  .setRegion(REGION)
-  .build();
-
-await CometChat.init(APP_ID, settings);
-
-// NEW — calls init AFTER chat init
-await CometChatCalls.init({ appId: APP_ID, region: REGION });
-```
-
----
-
-## Step 3 — Add Calls SDK login after chat login
-
-Wherever you call `CometChat.login(uid, authKey)` (or your auth-token equivalent), add:
-
-```ts
-const user = await CometChat.login(uid, authKey);
-const authToken = user.getAuthToken();
-// CometChatCalls.login(uid, authKey?) takes a UID — pass a token via loginWithAuthToken.
-await CometChatCalls.loginWithAuthToken(authToken);
-```
-
-If you use server-minted auth tokens (production hygiene — see `cometchat-production`), the same auth token works for both SDKs.
-
----
-
-## Step 4 — Mount IncomingCall at the app root
-
-Add `CometChatIncomingCall` somewhere that's always rendered (the root layout, app shell, or a portal):
-
-```tsx
-// src/App.tsx (or your root layout)
-import { CometChatIncomingCall } from "@cometchat/chat-uikit-react";
-
-function App() {
-  return (
-    <>
-      <YourExistingRoutes />
-      <CometChatIncomingCall />
-    </>
-  );
-}
-```
-
-This component listens for incoming-call events and renders the accept/reject UI. **Without it, your users won't see incoming calls.**
-
----
-
-## Step 5 — Add call buttons to existing chat surfaces
-
-If you're rendering `CometChatMessageHeader` (the per-conversation header), call buttons appear automatically once the calls SDK is initialized. **You don't add anything for this** — the UI Kit detects the calls SDK and wires the buttons.
-
-Verify by opening any 1:1 chat — voice + video icons should appear in the header.
-
----
-
-## Step 6 — (Optional) Custom call surface
-
-If you want a custom call experience instead of the kit's default UI, see `cometchat-react-calls/SKILL.md` Step 4 for the dispatcher pattern.
-
----
-
-## Verification checklist
-
-- [ ] `@cometchat/calls-sdk-javascript@^5` in package.json
-- [ ] Calls SDK init runs AFTER chat SDK init
-- [ ] `CometChatCalls.loginWithAuthToken(authToken)` runs AFTER `CometChat.login`
-- [ ] `CometChatIncomingCall` mounted at app root
-- [ ] Call buttons visible in CometChatMessageHeader
-- [ ] Run `cometchat verify --calls` — should pass all 20 checks
-- [ ] Smoke test: **two ISOLATED browser contexts** (normal + Incognito window, or two browsers/devices — NOT two tabs of one browser; the Chat SDK shares one session per origin), call from one, ringing in the other
-
----
-
-## Common pitfalls when migrating
-
-1. **Calls init before chat init.** Calls SDK throws "App not initialized." Order matters.
-2. **Forgetting `CometChatCalls.login`.** Token-mint endpoints fail with 401.
-3. **Mounting `CometChatIncomingCall` per-route.** Missed when user is on a non-chat route. Mount at root.
-4. **Hand-rolling call UI before installing the SDK.** Easy to skip the seven hard rules. Use the kit's components first; customize after a working baseline.
-
----
-
-## Pointers
-
-- `cometchat-react-calls/SKILL.md` — full architecture + seven hard rules
-- `cometchat-react-calls/references/recording.md` etc. — feature-specific add-ons
-- `cometchat verify --calls` — automated check (see `cometchat-cli`)

package/skills/cometchat-react-calls/references/call-layouts.md

@@ -1,160 +0,0 @@
-# Call layouts on web (React)
-
-CometChat Calls SDK ships three layout modes: TILE (grid), SIDEBAR (main speaker + filmstrip), SPOTLIGHT (active speaker hero). Each participant picks their own layout — the choice is local, not session-wide.
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/javascript/call-layouts
-
----
-
-## Available layouts
-
-| Layout | What it shows | Best for |
-|--------|---------------|----------|
-| `TILE` | Equally-sized grid tiles | Group meetings, equal participation |
-| `SIDEBAR` | Main speaker, others in sidebar | Presentations, webinars |
-| `SPOTLIGHT` | Hero active speaker, small thumbnails | 1:1 calls, focused discussions |
-
-Default layout: kit picks based on participant count (`SPOTLIGHT` for 1:1, `TILE` for groups). Override only when your UX requires it.
-
----
-
-## Set initial layout
-
-Pass `layout` into call settings when joining:
-
-```tsx
-import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
-
-const callSettings = {
-  layout: "TILE", // or "SIDEBAR" | "SPOTLIGHT"
-  // ... rest of your CallSettings
-};
-
-await CometChatCalls.joinSession(callToken, callSettings, containerEl);
-```
-
-Use the constants instead of string literals to avoid typos:
-
-```tsx
-const layouts = CometChatCalls.constants.LAYOUT;
-// layouts.TILE === "TILE"
-// layouts.SIDEBAR === "SIDEBAR"
-// layouts.SPOTLIGHT === "SPOTLIGHT"
-```
-
----
-
-## Change layout during a call
-
-```tsx
-function LayoutSwitcher() {
-  const [layout, setLayout] = useState<"TILE" | "SIDEBAR" | "SPOTLIGHT">("TILE");
-
-  function handleChange(next: typeof layout) {
-    CometChatCalls.setLayout(next);
-    setLayout(next);
-  }
-
-  return (
-    <div role="radiogroup" aria-label="Call layout">
-      {(["TILE", "SIDEBAR", "SPOTLIGHT"] as const).map((opt) => (
-        <button
-          key={opt}
-          role="radio"
-          aria-checked={layout === opt}
-          onClick={() => handleChange(opt)}
-        >
-          {opt}
-        </button>
-      ))}
-    </div>
-  );
-}
-```
-
-`setLayout` is local — only the caller's view changes. Other participants stay on whatever layout they had.
-
----
-
-## Listen for layout changes
-
-The kit fires `onCallLayoutChanged` when the user picks a different layout via the kit's built-in switcher. Listen so your custom controls stay in sync:
-
-```tsx
-useEffect(() => {
-  const handler = (newLayout: string) => {
-    setLayout(newLayout as typeof layout);
-  };
-  // addEventListener returns an unsubscribe fn — there is no removeEventListener.
-  const off = CometChatCalls.addEventListener("onCallLayoutChanged", handler);
-  return () => off();
-}, []);
-```
-
----
-
-## Hide the kit's layout switcher
-
-If you ship your own layout UI:
-
-```tsx
-const callSettings = {
-  hideChangeLayoutButton: true,
-  // ... rest
-};
-```
-
-Or to suppress layout changing entirely (locked layout):
-
-```tsx
-// hide the button AND don't ship your own switcher
-const callSettings = { hideChangeLayoutButton: true, layout: "TILE" };
-```
-
----
-
-## When to lock a layout
-
-Lock to `SPOTLIGHT`:
-- Telehealth provider/patient calls (focus on faces)
-- 1:1 sales/demo calls
-- Coaching sessions
-
-Lock to `TILE`:
-- Standups, retros, team meetings (everyone equally visible)
-- Classroom or training calls
-
-Lock to `SIDEBAR`:
-- Webinars (presenter dominant)
-- Live broadcasts with fixed roles
-
-For general meetings: don't lock. Let users pick.
-
----
-
-## Anti-patterns
-
-1. **Calling `setLayout` before `joinSession` resolves.** Throws — the call surface isn't bound yet. Set the initial layout via `callSettings.layout` instead.
-2. **Storing layout in URL or shared state.** Layout is per-participant local. Sharing it via URL/Firestore causes layout flicker as multiple peers fight to set it.
-3. **String literals everywhere.** Use `CometChatCalls.constants.LAYOUT` so typos surface at autocomplete time, not runtime.
-4. **Forgetting to call the unsubscribe fn on unmount.** `addEventListener` returns a `() => void` — call it in cleanup (there is no `removeEventListener`). Otherwise the listener accumulates across calls → `setLayout` fires N times.
-5. **Custom switcher AND kit's switcher both visible.** Confusing. Set `hideChangeLayoutButton: true` if you ship your own.
-
----
-
-## Verification checklist
-
-- [ ] Initial layout passed via `callSettings.layout`
-- [ ] `setLayout` only called after `joinSession` resolves
-- [ ] `onCallLayoutChanged` listener cleaned up on unmount
-- [ ] Layout constants used instead of string literals
-- [ ] Smoke test: 3-person call, each participant picks different layout, nobody else's view changes
-
----
-
-## Pointers
-
-- `cometchat-react-calls/SKILL.md` — call surface architecture
-- `cometchat-react-calls/references/recording-screen-share.md` — sister cross-cutting concern
-- `cometchat-react-calls/references/in-call-chat.md` — chat panel sits beside layout
-- Canonical docs: https://www.cometchat.com/docs/calls/javascript/call-layouts

package/skills/cometchat-react-calls/references/call-session.md

@@ -1,235 +0,0 @@
-# Call session — joinSession with no ringing (web)
-
-The Call Session flow uses **only the Calls SDK**. Both parties enter a known `sessionId` directly via `CometChatCalls.joinSession` — no Chat SDK call entity, no ringing, no incoming-call notification. This is the right pattern for **scheduled meetings, conference rooms, and shareable meeting links**.
-
-**Three calling modes — pick the right one:**
-
-| Mode | Driver | When to use |
-|---|---|---|
-| **Standard** | UI Kit (`CometChatCallButtons`) | 80% case — chat-driven calls with prebuilt UI |
-| **Ringing** (see `ringing-integration.md`) | Chat SDK call entity + Calls SDK session | Custom incoming/outgoing call UI on top of CometChat signaling |
-| **Call Session (this doc)** | Calls SDK `joinSession` directly | Meeting-room URLs, scheduled calls, no ringing |
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/javascript/join-session
-
----
-
-## When this is the right mode
-
-- "Join meeting" link sent in calendar invite
-- Conference rooms — same sessionId for repeated meetings
-- Webinars / town halls (combined with Tier 4 broadcast use-case)
-- Team huddles — sessionId derived from the team channel ID
-- Office hours — fixed sessionId, anyone can join during hours
-
-If your UX has *one party initiating and another being notified*, you want **Ringing**, not Call Session.
-
----
-
-## Hard rules
-
-1. **All participants need the same `sessionId`.** Generate it server-side; share via your app's existing channels (chat custom message, email link, push notification).
-2. **`generateToken(sessionId)` is per-user, per-session.** Each participant generates their own token; the token embeds the user's identity. Don't share tokens between users.
-3. **The container element must exist before `joinSession` runs AND must have measurable, viewport-anchored dimensions.** Use `position: fixed; top: 0; left: 0; width: 100vw; height: 100vh` (matches the upstream sample), OR explicit pixel dimensions. Flex-derived sizing inside nested layouts has produced "container exists but iframe renders at 0×0 → no video" in customer integrations. The SDK measures the container at the moment `joinSession` is called.
-4. **`CometChatCalls.login(uid)` must run before `generateToken`.** Otherwise `ERROR_AUTH_TOKEN_MISSING`. Pass `authKey` once at `CometChatCalls.init({appId, region, authKey})` time so `login(uid)` needs no second arg — matches the sample app pattern.
-5. **`joinSession` returns an object with `error`** — check it. Don't assume a resolved Promise = success.
-6. **No `CometChat.endCall` needed** — Call Session has no chat-side call entity. Just `CometChatCalls.leaveSession`.
-7. **For session-only integrations, the Chat SDK is OPTIONAL.** The upstream sample app uses ONLY the Calls SDK — no `CometChat.init` / `CometChat.login` anywhere. Keep the dual-SDK contract for additive (chat + calls) integrations; drop the Chat SDK entirely for standalone session-mode (calls-only meeting-room UX).
-8. **Pass an empty settings object `{}` and let the SDK pick defaults** unless you have a specific reason to override. Explicit values like `{ sessionType: "VIDEO", layout: "TILE", ... }` are technically valid per the type defs but have caused unexplained rendering issues in some version combinations — the sample app uses `{}`.
-
----
-
-## SessionId generation strategy
-
-Pick ONE strategy and stick with it across your app:
-
-| Strategy | Example sessionId | Use when |
-|---|---|---|
-| **UUID per meeting** | `uuid-v4-string` | One-off meetings, calendar invites |
-| **Stable per resource** | `team-${teamId}` or `appt-${appointmentId}` | Recurring meetings, persistent rooms |
-| **Time-bucketed** | `office-hours-${dateYYYYMMDD}` | Drop-in events |
-
-Generate server-side so you can store metadata (start time, allowed participants, expiry) and authorize joins.
-
----
-
-## Token generation
-
-```ts
-import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
-
-async function getCallToken(sessionId: string): Promise<string> {
-  const result = await CometChatCalls.generateToken(sessionId);
-  if (!result?.token) throw new Error("Token generation failed");
-  return result.token;
-}
-```
-
-Each user calls this with the SAME `sessionId` but gets a token tied to their own identity. The token is short-lived (typically 5 min); don't cache aggressively.
-
----
-
-## Join session
-
-This pattern mirrors the upstream sample exactly: `calls-sdk-javascript-5/sample-apps/cometchat-calls-sample-app-react/src/pages/join-session/JoinSession.tsx`. Customer-validated against the v5 SDK as the known-good shape.
-
-```tsx
-import { useEffect, useRef, useState } from "react";
-import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
-
-function CallRoom({ sessionId }: { sessionId: string }) {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const [inMeeting, setInMeeting] = useState(false);
-
-  // Auto-join once we have a sessionId. The state flip gates joinSession
-  // away from StrictMode's mount-phase double-effect (which raced
-  // leaveSession against an in-flight joinSession in prior versions).
-  useEffect(() => {
-    if (sessionId) setInMeeting(true);
-  }, [sessionId]);
-
-  // Reset state when the SDK reports the connection closed (peer left,
-  // network died, user clicked the in-iframe Leave button).
-  useEffect(() => {
-    const off = CometChatCalls.addEventListener("onConnectionClosed", () => {
-      setInMeeting(false);
-    });
-    return () => off();
-  }, []);
-
-  // The actual join happens in an effect that depends on `inMeeting` —
-  // the container ref is guaranteed populated because the <div> renders
-  // on every status, not behind a conditional.
-  useEffect(() => {
-    if (!inMeeting || !sessionId) return;
-
-    CometChatCalls.generateToken(sessionId).then(({ token }) => {
-      if (containerRef.current) {
-        // Empty settings = SDK defaults (matches sample app).
-        // The third arg is the container element; the SDK draws into it.
-        CometChatCalls.joinSession(token, {}, containerRef.current);
-      }
-    });
-
-    return () => {
-      try {
-        CometChatCalls.leaveSession();
-      } catch {
-        // ignore — not joined or already left
-      }
-    };
-  }, [inMeeting, sessionId]);
-
-  return (
-    <div
-      ref={containerRef}
-      style={{
-        position: "fixed",
-        top: 0,
-        left: 0,
-        width: "100vw",
-        height: "100vh",
-      }}
-    />
-  );
-}
-```
-
-**Why this shape (not the obvious alternatives):**
-
-- **`position: fixed; 100vw × 100vh`** instead of flex-sizing — gives the SDK a deterministic, viewport-anchored container the moment `joinSession` measures it. Customer integrations using `flex: 1` + `minHeight: 400` reported "container visible but iframe renders at 0×0 → no video" in some browser × React-version combinations. Match the sample exactly.
-- **Empty `{}` settings** instead of explicit `{ sessionType, layout, ... }` — both are type-valid, but the sample's `{}` is the empirically-validated combination. Override only when you have a specific reason.
-- **`onConnectionClosed`** instead of `onSessionLeft` — fires on ANY session termination (peer left, network dropped, in-iframe Leave clicked), which is what most customers actually want for cleanup. `onSessionLeft` is narrower.
-- **State-flag gating** (`inMeeting`) instead of `joinedRef` — the state flip puts `joinSession` in a state-triggered effect (which StrictMode doesn't double-run), avoiding the join↔leave race entirely.
-
----
-
-## Sharing the meeting link
-
-Sample URL pattern: `https://yourapp.com/meet/${sessionId}`
-
-```tsx
-function StartMeetingButton() {
-  async function start() {
-    // Server generates a unique sessionId, returns the meeting URL
-    const { sessionId, url } = await api.createMeeting();
-    // Copy to clipboard or open share sheet (see share-invite.md)
-    await navigator.clipboard.writeText(url);
-    // Navigate the host to the call room
-    window.location.href = `/meet/${sessionId}`;
-  }
-  return <button onClick={start}>Start meeting</button>;
-}
-```
-
-For end-to-end share UX (deep linking, login redirect, etc.), see `share-invite.md`.
-
----
-
-## Authorization (server-side)
-
-Don't trust client-side `joinSession`. Your server should gate `generateToken` requests:
-
-```ts
-// Server-side route called by the client BEFORE generateToken
-app.post("/api/meetings/:sessionId/authorize", async (req, res) => {
-  const { sessionId } = req.params;
-  const userId = req.session.userId;
-
-  const meeting = await db.getMeeting(sessionId);
-  if (!meeting) return res.status(404).json({ error: "Meeting not found" });
-  if (meeting.expiresAt < Date.now()) return res.status(410).json({ error: "Meeting expired" });
-  if (meeting.allowList && !meeting.allowList.includes(userId)) {
-    return res.status(403).json({ error: "Not authorized" });
-  }
-
-  res.json({ ok: true });
-});
-```
-
-Client-side flow: call `/authorize` → if 200, call `generateToken` → joinSession. Skipping authorization lets anyone with a sessionId join.
-
----
-
-## Anti-patterns
-
-1. **Sharing one user's token with another user.** Tokens are user-bound; each participant calls `generateToken` with their own auth.
-2. **Caching tokens across sessions.** Tokens are session-bound and short-lived. Generate fresh each join.
-3. **Calling `joinSession` before the container element renders.** `joinSession` mounts UI into the element — if it's null, you get a runtime error.
-4. **`joinedRef` boolean guard for StrictMode.** The cleanup function races against an in-flight `joinSession` and fires `leaveSession` before join completes — observed as "session connects then immediately leaves." Use the state-flag pattern shown above instead.
-5. **Flex-derived container sizing.** `flex: 1`, `height: 100%`, or `position: absolute; inset: 0` inside a nested flex parent can produce a measurable-looking container that renders the SDK iframe at 0×0 in some combinations. **Use `position: fixed; width: 100vw; height: 100vh`** — matches the sample app.
-6. **Explicit `{ sessionType, layout, ... }` settings.** Type-valid but has caused unexplained black-tile-on-local-preview behaviour in customer integrations. The sample app uses `{}` and lets the SDK pick defaults.
-7. **No `error` check on the `joinSession` result.** It returns `{data, error}` not a thrown error — Promise resolves on validation failure too.
-8. **Mixing Ringing + Call Session in one route.** If you accept a ringing call AND mount a Call Session room with the same sessionId, both try to join — undefined behavior.
-9. **No expiry / authorization on sessionIds.** Anyone with the URL can join forever. Always server-side gate.
-10. **Initializing Chat SDK for a session-only integration.** Wastes time and adds two extra failure modes (Chat init failure, Chat login race) for zero benefit — session mode never touches the Chat SDK call entity. Drop `CometChat.init` / `CometChat.login` entirely for standalone session apps; keep them only for additive (chat + calls) integrations.
-11. **`CometChatCalls.getLoggedInUser().getUid()`.** Runtime crash: `existing.getUid is not a function`. The Calls SDK's `getLoggedInUser()` returns a plain `User_2` interface (`{ uid, name, avatar, ... }`), NOT the Chat SDK's `User` class. Access the uid as a property: `existing.uid`. Same applies to `.name`, `.avatar` — all plain properties. The `.getUid()` / `.getName()` / `.getAvatar()` getters belong to Chat SDK's `User` class, which session-only code does not import.
-
----
-
-## Verification checklist
-
-- [ ] Server generates sessionIds; client doesn't mint them
-- [ ] `/authorize` endpoint gates `generateToken`
-- [ ] Tokens generated fresh per join (no caching)
-- [ ] Container element rendered before `joinSession` runs
-- [ ] Container uses `position: fixed; width: 100vw; height: 100vh` (sample-app pattern), NOT flex-derived sizing
-- [ ] StrictMode handled via state-flag gating (not `joinedRef`) — see anti-pattern #4
-- [ ] Settings passed as empty `{}`, not explicit `{ sessionType, layout, ... }`
-- [ ] `result.error` checked
-- [ ] `onConnectionClosed` listener handles session end (not just `onSessionLeft`)
-- [ ] `leaveSession` runs on unmount even if user closed tab
-- [ ] **Standalone session-only:** no `CometChat.init` / `CometChat.login` — Calls SDK alone
-- [ ] **Additive (chat + calls):** dual-SDK contract preserved (Chat first, then Calls)
-- [ ] Smoke: 2 tabs, both navigate to `/meet/${sessionId}` → both join → media flows → either leaves → other sees them gone
-
----
-
-## Pointers
-
-- `cometchat-react-calls/SKILL.md` — architecture
-- `cometchat-react-calls/references/ringing-integration.md` — Mode 2 (ringing)
-- `cometchat-react-calls/references/share-invite.md` — meeting-link sharing
-- `cometchat-calls/references/use-case-broadcast.md` — broadcast pattern uses Call Session
-- `cometchat-calls/references/use-case-team.md` — team huddles use Call Session
-- Canonical docs: https://www.cometchat.com/docs/calls/javascript/join-session