@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-js-v5-sdk/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: cometchat-js-v5-sdk
+description: "Add voice & video calling to any web app FROM SCRATCH with the headless CometChat Calls SDK v5 (`@cometchat/calls-sdk-javascript@5`) — no prebuilt UI Kit. init→login→generateToken→joinSession, event listeners, in-call actions (mute/video/screen-share/record/layout), meet-style session rooms AND 1:1 ringing (Chat SDK signaling + Calls SDK media). Triggers: 'add calling from scratch', 'standalone video call', 'headless calls sdk', 'build my own call UI', 'meeting room join by session id', 'one-on-one ringing call without uikit'."
+license: "MIT"
+compatibility: "Modern WebRTC browser (Chrome 72+/Firefox 68+/Safari 12.1+/Edge 79+); HTTPS (or localhost) for getUserMedia; @cometchat/calls-sdk-javascript@^5 (5.0.5). 1:1 ringing also needs @cometchat/chat-sdk-javascript@^4 for signaling. Framework-agnostic (vanilla JS core; React/Vue/Angular/Next recipes)."
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat calls sdk v5 headless voice video webrtc javascript calling standalone"
+---
+
+> **Ground truth:** `@cometchat/calls-sdk-javascript@5` + catalog `web-calls-v5.json` (the closed symbol list — every `CometChatCalls.*` below exists in it). Official docs: `/calls/javascript/**` = **v5** · Docs MCP. Fetch exact `SessionSettings` fields, event names, and action-method signatures from the docs (`references/docs-map.md`) — never memory. **APPEND to the user's app — additive wiring only** (`RULES.md`). This is the HEADLESS path (no UI Kit); for the prebuilt drop-in call UI use `cometchat-react-v7-calls` instead.
+
+## Companion skills (read first)
+- **Standalone/headless entry** — this skill owns its own package (the Calls SDK) and has no `-core` sibling; it is self-contained for meet-style calling.
+- **For 1:1 RINGING only** it also drives the **Chat SDK** (`@cometchat/chat-sdk-javascript@4`) for call signaling — signatures fetched from docs via `references/docs-map.md` (§ "1:1 RINGING"). It does NOT depend on the React UI Kit.
+- **Prefer the UI Kit instead?** If the app also wants chat and a prebuilt call UI, use `cometchat-react-v7-core` + `cometchat-react-v7-calls` — not this skill.
+
+## Use this skill when
+"add calling from scratch / without the UI Kit", "standalone voice/video", "build my own call screen", "headless calls SDK", "meeting-room join by session id", "one-on-one ringing call". Precondition: the caller chose the **from-scratch / standalone** path (the "add calling" router asks this). If they want the prebuilt call UI, route to `cometchat-react-v7-calls`.
+
+## Prerequisites & install
+```bash
+npm install @cometchat/calls-sdk-javascript@5
+```
+- **1:1 ringing** additionally needs the Chat SDK for signaling:
+  ```bash
+  npm install @cometchat/chat-sdk-javascript@4
+  ```
+- Credentials/env: App ID · Region · Auth Key (dev only). To fetch from the dashboard, load the CLI on demand — `npx @cometchat/skills-cli@3 auth login` → `provision use --app-id <id> --json` (writes `.cometchat/config.json`; `@3` pins the CLI major that matches the v5 skills). Or paste manually from Dashboard → Credentials. Mint **auth tokens server-side** for production; never ship the Auth Key. HTTPS (or `localhost`) is required for camera/mic (`getUserMedia`).
+
+## Init & login ordering (BAKED — invariant)
+`CometChatCalls.init(...)` (once, resolve first) → `CometChatCalls.login(uid, authKey)` **or** `loginWithAuthToken(token)` → then `generateToken` / `joinSession` / listeners. Nothing renders/joins before init+login resolve.
+- **DEFAULT to `CometChatCalls.initFromSettings(settings)`** — the ai-agent / telemetry-attributed path (persists `integrationSource="ai-agent"`), parallel to how the chat core inits via `CometChatUIKit.initFromSettings` / `CometChat.initFromSettings` (RULES §5). It is **INTENTIONALLY undocumented** — ai-agent-only (`@nodoc`, same posture as `CometChatUIKit.initFromSettings` — DOCS-BACKLOG F4/C1) — so the settings-object shape is **baked in `references/docs-map.md`**; pass it **INLINE** (no physical `cometchat-settings.json` file required), never fetched from `/calls/javascript/setup`. The publicly-documented **`CometChatCalls.init({ appId, region })` is the FALLBACK only** (a non-skills / doc-following context).
+- Coexisting with the Chat SDK / UI Kit? Their `login()` can re-init the Calls SDK with only appId/region and wipe custom hosts — re-run your calls init after their login, before `CometChatCalls.login`.
+
+## Two build modes (BAKED — the router picks one)
+- **Meet-style (session room)** — Calls SDK ONLY. Everyone who joins the same `sessionId` lands in the same call: `generateToken(sessionId)` → `joinSession(token, sessionSettings, containerEl)`. No ringing. This is the `/calls/javascript/react-integration` flow.
+- **1:1 ringing** — Chat SDK signals, Calls SDK carries media: `CometChat.initiateCall` → peer `CallListener.onIncomingCallReceived` → `acceptCall`/`rejectCall` → `CometChatCalls.generateToken(call.getSessionId())` → `joinSession(...)`. Fetch Chat-SDK signatures via `references/docs-map.md` § "1:1 RINGING".
+
+## SDK method map (BAKED closed list — from the catalog; signatures → FETCH from docs)
+- **Lifecycle:** `CometChatCalls.init` · `CometChatCalls.initFromSettings` · `CometChatCalls.login` · `CometChatCalls.loginWithAuthToken` · `CometChatCalls.logout` · `CometChatCalls.getLoggedInUser` · `CometChatCalls.isUserLoggedIn`
+- **Session:** `CometChatCalls.generateToken` · `CometChatCalls.joinSession` · `CometChatCalls.leaveSession` (`startSession` is **deprecated** → use `joinSession`)
+- **Events:** `CometChatCalls.addEventListener(eventName, cb, { signal? }) → unsubscribe()` (event names: FETCH the full list from `/calls/javascript/events`)
+- **In-call actions** — ⚠️ **for CUSTOM controls ONLY; the default `joinSession` UI already renders all of these** (see the first pitfall). Only reach for them when the user EXPLICITLY asks to replace the built-in controls: `muteAudio`/`unmuteAudio`/`toggleAudio` · `pauseVideo`/`resumeVideo`/`toggleVideo` · `setLayout` · `startRecording`/`stopRecording` · `startScreenSharing`/`stopScreenSharing` · `raiseHand`/`lowerHand` · `switchCamera` · `pinParticipant`/`unpinParticipant` · `showParticipantList`/`hideParticipantList`
+- **Devices:** `getAudioInputDevices` · `getAudioOutputDevices` · `getVideoInputDevices` · `getCurrent*Device`
+- **Call logs:** `CometChatCalls.CallLogRequestBuilder` → `fetchNext()` (paginated; shape → docs)
+- **Constants:** `CometChatCalls.constants.LAYOUT` (`TILE`/`SIDEBAR`/`SPOTLIGHT`) · `.TYPE` (`VOICE`/`VIDEO`) · `.CAMERA_FACING`
+> This map is a **curated highlight, NOT the full surface** — the AUTHORITATIVE closed list is the **`web-calls-v5.json` catalog** (83 symbols; it also carries `toggleHand`/`toggleParticipantList`/`endSessionForAll`/`muteParticipant`/`pauseParticipantVideo`/`setChatButtonUnreadCount`/`switchToVideoCall`, device setters (`setAudioInputDevice`…), the virtual-background methods, `startStreaming`/`stopStreaming` (**RTMP live-streaming** — with `streamUrl`/`streamKey`/`hideStreamingButton` in `SessionSettings`; neither the SKILL map above nor the `/calls/javascript/actions` doc foregrounds it, but it is real), `startTranscription`/`stopTranscription` (v5.0.5 — see `/calls/javascript/transcription`), and `TranscriptRequestBuilder`, among others). A symbol is real **iff it's in the catalog** — confirm THERE (not just this map), then fetch its exact signature/params from the docs page in `references/docs-map.md`.
+
+## Listener lifecycle (BAKED)
+`addEventListener` RETURNS an unsubscribe function — collect them and call every one on teardown (React: in the effect cleanup), and `CometChatCalls.leaveSession()` on unmount. Register listeners BEFORE `joinSession`. Never leak. You can also pass an `AbortSignal` via the `{ signal }` option for bulk teardown.
+
+## Least-code recipe (meet-style, framework-agnostic)
+```ts
+// STRICT-TS-CLEAN: type the settings with the EXPORTED SessionSettings, narrow region.
+import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
+import type { SessionSettings } from "@cometchat/calls-sdk-javascript"; // exported; SessionType/Layout are NOT
+
+1. await CometChatCalls.initFromSettings({ appId, region: region as "us"|"eu"|"in", credentials: { authKey: AUTH_KEY }, callsSDK: {}, chatSDK: {}, uiKit: {} }) // ai-agent telemetry default (integrationSource="ai-agent"); init({appId,region}) is the public-doc fallback
+2. await CometChatCalls.login(uid, AUTH_KEY)               // or loginWithAuthToken(token)
+3. const { token } = await CometChatCalls.generateToken(sessionId)
+4. const unsub = CometChatCalls.addEventListener("onSessionLeft", () => cleanup())
+5. const callSettings: SessionSettings = { sessionType: "VIDEO", layout: "TILE" } // annotate → literals narrow
+   await CometChatCalls.joinSession(token, callSettings, containerEl)
+6. // NO control buttons needed — joinSession's UI ALREADY renders mute/video/screen-share/raise-hand/leave.
+7. // teardown → unsub(); CometChatCalls.leaveSession()
+```
+The `containerEl` MUST have real dimensions — the SDK renders its call surface into it. Fetch the full `SessionSettings` field list from `/calls/javascript/session-settings`. (In plain JS drop the annotations; the doc pages show that JS form.)
+
+## Framework notes (same SDK, per-framework glue)
+The recipe above is framework-agnostic; the only per-framework part is WHERE you register listeners / mount the container / tear down. Verified live on React and Angular.
+- **React:** provider or component — init via `CometChatCalls.initFromSettings(...)` (the telemetry-attributed default — `integrationSource="ai-agent"`; `init({appId,region})` is the public-doc fallback), then register listeners + `joinSession` in a `useEffect`; teardown in the effect cleanup (call every unsubscribe + `leaveSession`). Recipe: `/calls/javascript/react-integration`.
+- **Angular:** a **DI service** wrapping `CometChatCalls` (init via `CometChatCalls.initFromSettings(...)` — the telemetry-attributed default (`integrationSource="ai-agent"`; `init({appId,region})` is the public-doc fallback) → login, `generateToken`, typed `joinSession`, `leaveSession`; expose readiness via an RxJS `BehaviorSubject`) + a component with a **sized `@ViewChild('callContainer') ElementRef`** container; register listeners BEFORE `joinSession`; teardown in **`ngOnDestroy`** (unsubscribe all + `leaveSession`). Recipe: `/calls/javascript/angular-integration` — but ⚠️ THREE things to override:
+  - **(a)** its example wires external Mute/Video/Leave buttons — **IGNORE them** (pitfall #1: `joinSession`'s UI already has the controls);
+  - **(b)** it targets legacy `@NgModule`/`app.module.ts` — a modern `ng new` is **standalone** (`bootstrapApplication` + `app.config.ts`, class `App`), so use the standalone variant;
+  - **(c) ⚠️ NgZone / change detection (the silent dead-state).** CometChat SDK callbacks — event listeners AND the `login`/`generateToken`/`joinSession` promise resolutions — fire OUTSIDE Angular's zone, so any component state you set inside them **won't trigger change detection** (symptom: readiness/call buttons *silently never enable*, even though the SDK succeeded). Fix: drive the template off your `BehaviorSubject` via the **`async` pipe**, AND/OR wrap state writes in **`this.zone.run(() => …)`** (inject `NgZone`) or call `ChangeDetectorRef.detectChanges()`. Not optional — the app looks broken without it.
+
+## Common pitfalls (BAKED)
+- **Don't duplicate the built-in call controls (the #1 mistake).** `joinSession` renders a COMPLETE call UI — mute, camera on/off, screen-share, raise-hand, participant list, layout switch, and the red leave/end button are ALL built into the surface it mounts in `containerEl`. Do **NOT** add your own Mute / Start-video / Share-screen / Leave buttons around the container: they are redundant, duplicate the SDK's own controls, and drift out of sync with the real call state. The `muteAudio`/`pauseVideo`/`leaveSession`/… methods are for CUSTOM controls ONLY — reach for them **just when the user EXPLICITLY asks** to replace the default controls (and hide the built-in ones first via `SessionSettings` — `hideControlPanel` for the whole bar, or per-button flags like `hideToggleAudioButton`/`hideRaiseHandButton`/`hideChatButton`; the canonical recipe is `/calls/javascript/custom-control-panel`, fields on `/calls/javascript/session-settings`). Default = render the call surface and stop.
+- **Zero-dimension container** — `joinSession` mounts into `containerEl`; if it has `height:0` the call renders invisibly. Give it explicit size (e.g. `height: 500px` / `100dvh`).
+- **HTTP (not HTTPS)** — `getUserMedia` needs a secure context; camera/mic silently fail off `localhost`.
+- **Joining before init+login resolve** — `generateToken`/`joinSession` reject; always `await` init then login first.
+- **Leaked listeners / no `leaveSession`** — every `addEventListener` unsubscribe must run on teardown; call `leaveSession()` on unmount.
+- **`startSession` is deprecated** — use `joinSession`; don't pass the old `CallSettings` builder where a plain `SessionSettings` object is expected.
+- **Host wipe on coexisting Chat-SDK login** — re-init the Calls SDK after the Chat SDK/UI Kit logs in (see Init ordering).
+- **version_conflict** — the Calls SDK is **major 5**, distinct from the Chat SDK's v4; do not "upgrade" the Chat SDK to a non-existent v7.
+- **Assuming a signature** — event names, `SessionSettings` fields, and action params are FETCHED from docs, never guessed.
+- **1:1 ringing: `CometChat.Call` used only as a TYPE trips `TS6133`** — in strict TS, importing `CometChat` and referencing `CometChat.Call` in type positions only (never as a value) fails with `'CometChat' is declared but its value is never read`. Import the **concrete type** instead: `import { CometChat } from "@cometchat/chat-sdk-javascript"` for the VALUES you call (`initiateCall`/`acceptCall`/`addCallListener`) and `import type { Call } from "@cometchat/chat-sdk-javascript"` for the type. (Same class as the `SessionSettings`/`CometChatCalls` strict-TS trap.)
+- **Strict-TS widening (the doc's bare-object form doesn't compile as-is)** — the doc pages pass `joinSession(token, { sessionType: "VIDEO", layout: "TILE" }, el)` and `init({ appId, region })` as plain JS. In a strict-TS app (the stock Vite `react-ts` template: `strict` + `verbatimModuleSyntax` + `noUnusedLocals`) those literals WIDEN to `string` and fail `tsc` (TS2345 vs `SessionSettings`; TS2322 for `region`). Fix: `import type { SessionSettings }` (it's exported; `SessionType`/`Layout` are NOT) and annotate the settings object — `const s: SessionSettings = {…}` (or `satisfies SessionSettings`) — and narrow `region` to `"us"|"eu"|"in"`.
+
+## Verify it works
+- **Tier-1 catalog:** every `CometChatCalls.*` symbol emitted appears in `web-calls-v5.json` (`node test-suite/scripts/verify-catalog.mjs --family web-calls-v5`).
+- **Tier-2 fences:** the emit type-checks against the installed `@cometchat/calls-sdk-javascript@5` `.d.ts`.
+- **Tier-3b headless smoke:** `node test-suite/scripts/sdk-smoke.mjs --family web-calls-v5 [--live|--dry]` runs init→login→generateToken→(join wiring)→listener-teardown. Media/`joinSession` needs a real WebRTC/DOM context, so the node smoke covers the token+listener round-trip (`--dry` proves wiring without a backend); the actual call render is verified in a browser harness. Flag "dry-mock only, not live-certified" honestly where true.

package/skills/cometchat-js-v5-sdk/references/docs-map.md

@@ -0,0 +1,114 @@
+# docs-map — CometChat Calls SDK v5 (JavaScript, headless): intent → the exact docs page to fetch
+
+## Reaching docs — PREFER the CometChat docs MCP; fetch is the fallback
+The canonical doc channel is the **first-party CometChat docs MCP** — tools `search_cometchat_docs`,
+`fetch_cometchat_doc_page`, and `get_cometchat_implementation_bundle`. **If those tools are connected,
+use them instead of a raw web fetch:**
+- **Find the page** → `search_cometchat_docs(query)` — e.g. `search_cometchat_docs("calls javascript join session")`.
+- **Read the page** → `fetch_cometchat_doc_page(path)` — pass the SAME `<path>` the tables below list; the MCP
+  resolves the `.md` twin and returns raw Markdown. A full `https://…/<path>` URL also works.
+- **A whole feature/recipe** → `get_cometchat_implementation_bundle(...)` is **NON-AUTHORITATIVE** — curated
+  STATIC recipes that can lag the live docs. Treat any bundle as a hint only: RECONCILE it against the
+  `fetch_cometchat_doc_page` result + the catalog; never emit bundle code verbatim.
+
+The MCP reads whatever docs environment it is pointed at (production by default; a preview when repointed),
+so it also carries the environment-swap concern below — no hardcoded host on the skill side.
+
+**If the MCP tools are NOT connected:** add it (`claude mcp add --transport http cometchat-docs https://mcp.cometchat.com/mcp`, or reinstall/enable the plugin) and retry; only if it still will not connect, fall back to a plain fetch via `DOCS_BASE` (defined next).
+Either way the `<path>` catalog in this file is the source of truth for WHICH page — MCP-vs-fetch is only HOW.
+
+## DOCS_BASE — the fetch FALLBACK entry point (⚠️ SWAP HERE to change environments)
+```
+DOCS_BASE = https://www.cometchat.com/docs
+```
+> Production docs (`https://www.cometchat.com/docs`). **Fetch rule:** build a URL as `DOCS_BASE` + the path shown,
+> then append `.md`. Never hardcode a host anywhere else; never read `node_modules`/`.d.ts`.
+
+## The convention — Calls v5 lives at the UNVERSIONED root `/calls/javascript/`
+`DOCS_BASE` + `<path>` + `.md` → raw Markdown (verbatim code + prop/parameter tables).
+```
+Fetch:  {DOCS_BASE}/calls/javascript/overview.md
+```
+> **⚠️ VERSION TRAP.** The **unversioned** `/calls/javascript/**` tree IS **v5** (matches the installed
+> `@cometchat/calls-sdk-javascript@5`). The `/calls/v4/**` tree is the OLD v4 SDK — never fetch it for a v5
+> build. Legacy `/sdk/javascript/<n>.0/calling-*` pages are older still. When in doubt, prefer the page whose
+> body says "Calls SDK v5".
+
+## Scoped index (prefer over the global llms.txt)
+```
+{DOCS_BASE}/llms.txt
+```
+Use it to discover any page not listed below (search for `/calls/javascript/`).
+
+## Path catalog — intent → page (all under `/calls/javascript/`)
+| Intent | Path |
+|---|---|
+| SDK overview · architecture · call-flow | `/calls/javascript/overview` |
+| Install + `init` / `initFromSettings` | `/calls/javascript/setup` |
+| Login / auth-token / user mgmt | `/calls/javascript/authentication` |
+| `generateToken` + `joinSession` (meet-style) | `/calls/javascript/join-session` |
+| **1:1 RINGING** — initiate · incoming-call listener + **incoming/outgoing call-screen UI** · accept/reject/cancel · then `generateToken`/`joinSession` | `/calls/javascript/ringing` |
+| Session settings (the `SessionSettings` object) | `/calls/javascript/session-settings` |
+| Events (`addEventListener` — full event list) | `/calls/javascript/events` |
+| In-call actions (mute/pause/leave/layout/record…) | `/calls/javascript/actions` |
+| **Custom control panel** — replace the built-in controls: hide the whole panel (`hideControlPanel`) OR hide INDIVIDUAL buttons, then drive your own UI off the action methods + keep it in sync via events | `/calls/javascript/custom-control-panel` — the canonical recipe for `SKILL.md` pitfall #1's "user EXPLICITLY wants custom controls" path. Carries the per-button hide flags the session-settings page doesn't foreground: `hideRaiseHandButton` · `hideShareInviteButton` · `hideParticipantListButton` · `hideChatButton` (plus `hideLeaveSessionButton`/`hideToggleAudioButton`/`hideToggleVideoButton`/`hideScreenSharingButton`/`hideRecordingButton`/`hideChangeLayoutButton`/`hideVirtualBackgroundButton`) — all real in the installed `.d.ts`. |
+| Call layouts (TILE / SIDEBAR / SPOTLIGHT) | `/calls/javascript/call-layouts` |
+| Participant management (pin / mute / list) | `/calls/javascript/participant-management` |
+| Recording | `/calls/javascript/recording` |
+| Screen sharing | `/calls/javascript/screen-sharing` |
+| Virtual background | `/calls/javascript/virtual-background` |
+| Raise hand | `/calls/javascript/raise-hand` |
+| Idle timeout | `/calls/javascript/idle-timeout` |
+| Share invite | `/calls/javascript/share-invite` |
+| Call logs (`CallLogRequestBuilder`) | `/calls/javascript/call-logs` — ⚠️ **the live example OMITS the REQUIRED `.setAuthToken(token)` — copying it verbatim BREAKS AT RUNTIME.** The page now DOES document the client-SDK `CallLogRequestBuilder` (added in v5.0.5, in its "Transcripts" section) — but its snippet is `new CometChatCalls.CallLogRequestBuilder().setLimit(30).setHasTranscriptions(true).build()` with **no `setAuthToken`**, and the builder does **NOT** implicitly use the logged-in user's token: `fetchNext()` then throws `{ code: "NOT_ENOUGH_PARAMETERS", message: "`Auth Token` is required to use the fetchNext() method." }` (verified live vs installed `@cometchat/calls-sdk-javascript@5.0.5`, explorer `web-calls-v5`). **EMIT THE BAKED RECIPE, not the doc snippet:** `new CometChatCalls.CallLogRequestBuilder().setLimit(n).setAuthToken(CometChatCalls.getUserAuthToken()).build().fetchNext()` → `Promise<CallLog[]>` (paginated; read `getSessionID`/`getType`/`getStatus`/`getTotalDuration`/`getInitiatedAt`/…). `setAuthToken` is REQUIRED; pass the logged-in user's token from `CometChatCalls.getUserAuthToken()`. Use the SDK builder for an in-app call-log list; don't send the user to the REST API. (Docs bug tracked in `DOCS-BACKLOG.md`; this baked recipe stays authoritative over the doc snippet until it's fixed.) |
+| **React** integration (provider + call screen) | `/calls/javascript/react-integration` |
+| Vue / Angular / Next.js / Ionic integration | `/calls/javascript/{vue,angular,nextjs,ionic}-integration` |
+
+## DOCS-GAP — `initFromSettings` shape is NOT on the live docs (bake it here)
+> **Referenced by `SKILL.md` (Init & login ordering).** The `/calls/javascript/setup` page documents ONLY
+> `init({ appId, region })` — it does **not** document `CometChatCalls.initFromSettings(...)`, even though the
+> method is real and shipped (installed `@cometchat/calls-sdk-javascript@5` `.d.ts`). Until the docs add it,
+> the `initFromSettings` argument shape (the non-exported `CometChatSettings` interface — real in the
+> installed `.d.ts`, so absent from the exports-only catalog) is baked here so the skill is not a dead-end:
+> ```ts
+> await CometChatCalls.initFromSettings({
+>   appId: "APP_ID",
+>   region: "us",                         // 'us' | 'eu' | 'in'
+>   credentials: { authKey: "AUTH_KEY" }, // dev-only auth key
+>   callsSDK: { adminHost: null, clientHost: null, host: null },
+>   chatSDK: {},                          // Record<string, unknown>
+>   uiKit: {},                            // Record<string, unknown>
+> });
+> ```
+> The skills **DEFAULT to `CometChatCalls.initFromSettings(settings)`** — pass the settings object **INLINE**
+> (no physical `cometchat-settings.json` file needed). It is the **ai-agent-only telemetry init**
+> (persists `integrationSource="ai-agent"`), **INTENTIONALLY undocumented** (`@nodoc`, same posture as
+> `CometChatUIKit.initFromSettings` — DOCS-BACKLOG F4), which is WHY the shape is baked here. The
+> publicly-documented **`init({ appId, region })` is the FALLBACK only** (a non-skills / doc-following
+> context). Do NOT tell a user to "fetch the shape from `/calls/javascript/setup`": that page does not carry
+> it. (Explorer `web-calls-v5`, AUDIT-169.)
+
+## 1:1 RINGING (meet-style needs none of this) — the signaling layer is the CHAT SDK
+Meet-style (session-id "join a room") uses ONLY the Calls SDK (`generateToken` → `joinSession`). But
+**one-on-one ringing** (call a specific user, they get an incoming-call prompt, accept/reject) combines the
+**Chat SDK** (`@cometchat/chat-sdk-javascript`) for signaling + the Calls SDK for media.
+
+**The COMPLETE, CURRENT recipe is ONE page — fetch it directly:**
+```
+fetch_cometchat_doc_page("/calls/javascript/ringing")
+```
+That page (v5, JS) carries the WHOLE flow, both sides: `CometChat.initiateCall(call, timeout?)` →
+`CometChat.addCallListener({ onIncomingCallReceived → show an incoming-call screen, onOutgoingCallAccepted, onOutgoingCallRejected, onIncomingCallCancelled })`
+→ `CometChat.acceptCall(sessionId)` / `rejectCall(sessionId, status)` / cancel → `CometChatCalls.generateToken(sessionId)`
+→ `CometChatCalls.joinSession(...)` → `leaveSession()` + `CometChat.endCall(sessionId)`. It even includes an
+**incoming-call UI example** and an **outgoing-call UI example**.
+> **Do NOT reach for `search_cometchat_docs("default calling")`** — search surfaces the STALE
+> `/sdk/javascript/3.0/` chat-SDK pages, which end on the deprecated `startSession()` (not `joinSession`) and
+> show no incoming-call UI. `/calls/javascript/ringing` is the canonical v5 source of truth; reconcile any
+> Chat-SDK symbol against the Chat SDK catalog before emitting.
+
+> **⚠️ Testing 1:1 ringing needs TWO live clients** — different users, in **isolated browser sessions**. CometChat
+> stores the logged-in user in `localStorage`, which is SHARED across tabs of the same browser, so two tabs
+> both become the same user and the callee never rings. Use two different browsers (or one normal + one
+> incognito window), each logged in as a different user with the CallListener active. The caller always shows
+> ringing locally; that proves nothing about the callee. This is a two-client protocol, not a bug.

package/skills/cometchat-migrate-from-getstream/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: cometchat-migrate-from-getstream
+description: "Migrate an app from Stream (GetStream) Chat to CometChat end-to-end in ONE prompt, on any platform in this pack (React, Angular, React Native/Expo, iOS, Android, Flutter). Inventories every Stream usage (stream-chat client, the React/Angular/RN/Flutter/Swift/Android SDKs, Stream Video, Activity Feeds, push, server tokens, webhooks), swaps each supported feature for its CometChat equivalent, REMOVES features CometChat has no equivalent for (code, UI, deps), writes a data-migration script for users/channels/history, uninstalls Stream, verifies the build, and ends with a report listing what was migrated, what was removed and what you still need to do. Triggers: 'migrate my app from Stream to CometChat', 'migrate from GetStream', 'migrate my app to CometChat' (Stream detected), 'replace Stream Chat with CometChat', 'switch from getstream', 'move off Stream', 'stream-chat to cometchat', 'port my GetStream chat to CometChat'."
+license: "MIT"
+compatibility: "FROM Stream Chat (`stream-chat` JS client; stream-chat-react, stream-chat-angular, stream-chat-react-native / stream-chat-expo, stream_chat_flutter, StreamChat/StreamChatUI/StreamChatSwiftUI, io.getstream:stream-chat-android-*), Stream Video, Stream Activity Feeds → TO the CometChat family this pack detects (peers.yaml): React UI Kit v7, Angular v5, React Native v5, iOS v5, Android v6, Flutter v6, plus the headless Chat/Calls SDKs. Node >=18 for the data-migration script."
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat migration getstream stream stream-chat competitor switch replace port uikit sdk calls data-import"
+---
+
+> **Ground truth:** the STREAM side (what to look for) is baked in `references/inventory.md` + `references/feature-map.md` — confirm each hit by reading the user's code. The COMETCHAT side is never from memory: symbols come from the target family's skills + catalog, feature existence from that family's `features.json`, signatures from the docs via the family's `-core/references/docs-map.md` (Docs MCP first — `RULES.md` → Fetch discipline). REST pages live under `DOCS_BASE` = `https://www.cometchat.com/docs`.
+
+## Companion skills (read first)
+- `cometchat-<family>-core` — the init → login → render the migrated app lands on. `<family>` is resolved in step 1; this skill ASSUMES that core and never restates its code.
+- `cometchat-<family>-components` / `-features` / `-calls` / `-push` / `-customization` — pulled in only for the Stream features the inventory finds.
+
+## Use this skill when
+The user asks to move an app off Stream: "migrate my app from GetStream/Stream to CometChat", "replace Stream Chat", "switch to CometChat", or "migrate my app to CometChat" when `npx @cometchat/skills detect --json` reports `migrate_from` with vendor `getstream`. Sendbird apps → `cometchat-migrate-from-sendbird`. An app with BOTH vendors: run both skills, one after the other, into one report.
+
+## The single-prompt contract (read before step 1)
+The migration request IS the approval (`RULES.md` → Competitor migration). Run every step below to the end in this one turn:
+- **Do not stop to ask.** No onboarding plan/approve gate, no clarification questions. Where a companion skill would ask, take the default written here, and record it under *Defaults taken* in the report.
+- **Safety net instead of questions:** in a git repo, first `git switch -c cometchat-migration` (carries any uncommitted work along; mention that in the report). Never commit, push, or rewrite history. No git → proceed and say so in the report.
+- **Removing Stream is the requested outcome** — `RULES.md`'s append-never-replace does not protect Stream code. It still protects everything else: touch non-chat code only to rewire it.
+- **Credentials: never ask, never provision.** Reuse `.cometchat/config.json` or existing CometChat env values if present; otherwise write the family's env/settings file with clearly-named placeholders so the build still compiles, and make "add your CometChat credentials" action item #1. **Never write a real key into a git-tracked file:** check `git ls-files <file>` first. If the file is tracked, put real values in the untracked local variant the framework reads (Vite/Next `.env.local`, Android `local.properties`, …) and keep placeholders in the tracked file. Adding a tracked file to `.gitignore` does NOT untrack it. The server's REST API key only ever goes into an untracked file or the hosting env.
+- **Only three STOPs:** (1) no Stream usage found → say so and hand to `cometchat`; (2) the app's platform has no family in this pack (Vue, Unity, .NET, …) → deliver the inventory + feature map as the report, change nothing; (3) the build was already failing before you started → record the pre-existing errors, migrate anyway, and label them as pre-existing.
+
+## Migration workflow (BAKED — do every step, in order)
+Every step applies to every app, however small: a 3-file sample still has vendor users and history, so steps 4 (`toCometChatId`) and 8 (data script) are ALWAYS delivered. Only a step whose subject truly doesn't exist (no server → step 7) may be skipped, and it's listed under *Defaults taken* as `skipped: <why>`. A silent skip is a failed migration.
+1. **Detect.** `npx @cometchat/skills detect --json` → `framework`, `android_variant`, `existing_cometchat`, `migrate_from`. Resolve `<family>` exactly like the router (`peers.yaml` `dir_prefix`; per-platform targets in `references/inventory.md` §Target family). Monorepo: migrate every package that uses Stream, including the server that mints tokens. `existing_cometchat: true` + Stream still present = a half-finished migration: resume it, don't redo it. Read `.cometchat/config.json` if it exists: its `appId`/`region`/`authKey` are THE credentials. Write them into the family's untracked env/settings file (single-prompt contract), never ask. Before editing anything, run the app's build once and record whether it passed.
+2. **Inventory — the usage ledger.** Grep per `references/inventory.md` (packages, imports, client creation, `connectUser`, SDK components, event subscriptions, channel queries, custom attachments, push devices, Video, Feeds, env vars, server tokens, webhooks, tests/mocks). Record every hit as `file:line → what it does`. Classify the app: **UI SDK mode** (Stream's React/Angular/RN/Flutter/iOS/Android UI components render the chat) → the family's CometChat UI Kit replaces them; **client mode** (own UI on the low-level client: `stream-chat`, `stream_chat`, `StreamChat`/`ChatClient`, `stream-chat-android-client`) → KEEP the app's UI and port its data layer to the family's CometChat Chat SDK; **mixed** → both.
+3. **Feature map.** For every Stream feature the ledger shows, look up its row in `references/feature-map.md`, then check the listed CometChat id in the TARGET family's `features.json`. Present → **migrate**. Absent → check BOTH levels — UI Kit (`search_cometchat_docs "<feature> <platform> ui kit"`) AND Chat SDK/REST (`… SDK`); documented at either → migrate (**no UI Kit drop-in is NOT unsupported**), built with the SDK method in the app's own UI (`RULES.md` → UI Kit first, SDK fallback). Mark **UNSUPPORTED only** when NEITHER has it — and **an empty MCP search is NOT proof**: follow the verification ladder (re-query with CometChat vocabulary → live-fetch the likely docs page → cross-check the family CATALOG) in `references/feature-map.md` §Deciding unsupported, before any REMOVE. Never call a feature unsupported from memory or invent an API; if it truly can't be verified, KEEP it as `needs-verification`. **Every UNSUPPORTED row needs evidence in the report** — the `features.json` result + the exact UI Kit AND SDK queries you ran.
+4. **Install CometChat and wire the core** per `cometchat-<family>-core` (its install, `initFromSettings`, login gate, render order, env file). **Identity:** the CometChat UID is the app's existing Stream user ID passed through ONE shared `toCometChatId()` (`references/concept-map.md` §IDs). The GUID is the channel **cid** (`type:id`) through the same helper. The client login, the server token endpoint AND the data script all call the SAME `toCometChatId()` — put it in a shared client module (`src/cometchat/ids.ts`; native → §Native platforms) the login imports, and copy that body verbatim into the data script. **Route the current-user id through it at login even when the Stream id already looks valid** (it's a no-op then); confining `toCometChatId` to the data script is the #1 Stream migration miss and imports users under UIDs the app never logs in as (`references/concept-map.md` §IDs). Login: the app minted Stream user tokens on a server (`createToken`) or used a `tokenProvider` → migrate that endpoint (step 7) and use the auth-token login; the app used `devToken()` → Auth Key login (dev only) + an action item to switch to tokens before production. **Keep every identity source, in the same order:** whatever decides the current user today (URL params, env vars like `VITE_USER_ID`, the auth provider, a stored ID, a demo fallback) still decides it after the migration. Only the Stream-token-derived path becomes the CometChat auth token. Dropping one silently logs a configured deployment in as someone else. **Returning users:** the app already persists who is signed in (localStorage, keychain, prefs, a cookie) from the vendor era. Gate the chat on CometChat's logged-in user, NOT that cached ID. On start, a stored ID with no CometChat session → run the same login path before rendering any CometChat component; if that fails → the sign-in screen. Otherwise every user who was signed in before the upgrade lands on a broken chat. **No UI Kit family for this app?** A headless / vanilla-JS app that draws its own UI on the `stream-chat` client (no framework the pack ships a UI Kit for) has no `-core` to wire — do NOT stop. Install the CometChat **Chat SDK** for the platform (web → `@cometchat/chat-sdk-javascript`) and migrate the data layer straight onto it, taking every method from the SDK docs (`/sdk/<platform>/*`). Keep the app's own UI; there is no UI Kit to install. This is client/SDK mode with no framework core — the concept map's SDK/client-mode section still applies.
+5. **Replace usage, file by file,** using `references/concept-map.md`: client/`connectUser` → CometChat init/login; `ChannelList` → conversations; channel (`Channel`/`Window`/`MessageList`/`MessageInput`/`Thread`) → message pane; member-based distinct channels → user conversations; `client.on(...)`/`channel.on(...)` → listeners (remove them on unmount); attachments/threads/reactions → the core + `-features` skill; theme/CSS variables/i18n → `-customization`; Stream Video → `-calls` (or the headless calls peer); push devices → `-push`. Remove each Stream import as you replace its last use. **Both modes fetch from docs only:** UI Kit component props AND SDK method signatures come from the live docs (the family `core`'s `docs-map.md`), verified against the catalog — never written from memory or ported from the vendor's API shape.
+6. **Remove unsupported features FULLY.** For each UNSUPPORTED row: delete the feature's code path, its UI entry points (buttons, menu items, slash commands, routes, screens, settings toggles), state/stores, types, hooks, assets, tests, env vars, server endpoints and dependencies — no dead buttons, no commented-out blocks, no feature flags left on. Keep the surrounding screen working. **Activity Feeds has no CometChat equivalent**: feed screens, activity writers, follow buttons and the feed server calls all go, and are listed. Log each one for the report: feature · what it did · files changed · what users lose · the closest CometChat alternative (if any).
+7. **Server side.** Replace Stream token minting (`createToken`, `upsertUser` on sign-up) with a CometChat auth-token endpoint (REST: create the user if missing, then create an auth token — `/rest-api/auth-tokens`, REST API key from server env only). Map Stream webhooks (`verifyWebhook`, `x-signature`) to CometChat webhooks (`/rest-api/management-apis/webhooks/overview`); before-message-send hooks, custom-command endpoints and SQS/SNS without an equivalent are REMOVED + listed. Replace other server-client calls with CometChat REST, or remove + list them.
+8. **Data migration script — write it, then run the import for the user.** Generate `scripts/cometchat-migration/` per `references/data-migration.md`: export users, channels, members and messages with the Stream server client → transform with the same `toCometChatId()` → import through the CometChat Data Import API. When the code migration is done, tell the user the **data-import script is ready** and ask for the credentials it needs — the source keys (`STREAM_API_KEY`, `STREAM_API_SECRET`) and the CometChat **App ID, Region and full-access REST API key**. (Asking for these is the ONE question the single-prompt contract allows; everything else still takes the documented default.) As soon as the user provides them, **RUN the import yourself** from env vars — never write the secrets into a repo file: a `--dry-run` first (show the users / channels / members / messages counts), then the real import, then report what landed and what failed. Only messages within CometChat's **6-month retention window** import — tell the user to **reach out to CometChat to import messages older than 6 months**. If the user does not share credentials, leave running the script as an action item.
+9. **Uninstall Stream.** Remove every Stream dependency (package.json + regenerate the lockfile, Podfile/SPM, Gradle, pubspec), CSS imports (`stream-chat-react/dist/css/…`, `@stream-io/stream-chat-css`), i18n setup, env vars, native config, and CI secrets references. Remove Stream-only peer dependencies (offline SQLite, audio recorder, …) **only when nothing else imports them**. `react-native-reanimated`, `react-native-gesture-handler` and `react-native-svg` are usually shared: keep those. Re-run the package manager install. **On iOS/SPM the ROOT manifest counts too**: a vendored-SDK repo declares the vendor in its own `Package.swift`/`*.podspec` at the repo root, not just in the app's `.xcodeproj` — remove the dependency there AND delete any vendored `Framework/*.xcframework`, or the vendor package is still declared after every call site is gone. Update the app's OWN docs (README, setup/deploy guides, `.env.example`): setup steps, env var names and screenshots captions that describe Stream now describe CometChat. Rename Stream-named identifiers (`getstreamUserId` → `userId`).
+10. **Verify** (§Verify it works). Fix every build error you introduced. Don't run live tests unless asked (`RULES.md` → Verification scope).
+11. **Report.** Write `COMETCHAT_MIGRATION.md` at the repo root from `references/report-template.md`, then END your reply with its two lists pasted in full: **Removed — not available in CometChat** and **Your action items**. This final list is the deliverable the user asked for; never skip it, even if nothing was removed (say "none").
+
+## Common pitfalls
+- **Accessibility is never a "missing feature".** Stream-provided skip links, focus management, live regions and keyboard shortcuts are plain HTML/ARIA/host code. Re-create them in the app against the new CometChat layout, and never list them as Removed. Losing them is a regression, not an honest removal.
+- **The provider swap moves wrapper elements.** `CometChatProvider` (and, on web, `CometChatErrorBoundary`) render wrapper elements exactly where the vendor's provider sat. If they now wrap the app's own shell/header, each wrapper needs a height in the chain, or the chat renders at 0px while the build passes. Follow the core's layout reference, and check the chain from the root element down to the conversation list.
+- **IDs that CometChat rejects or merges.** UIDs/GUIDs are alpha-dash (`a-z 0-9 - _`), max 100 characters, and lowercased. Stream cids contain `:`, member-based channel IDs start with `!members-`, and user IDs can contain `@` or `.`. Sanitize with one deterministic function everywhere, and always feed it the full **cid**, so `messaging:general` and `team:general` stay distinct.
+- **1:1 chats are not groups.** A member-based channel (`!members-…` ID, created from exactly two members) becomes a CometChat *user* conversation, not a two-person group.
+- **Livestream channels and large groups.** CometChat sends receipts and typing indicators only in groups up to 300 members (100,000 without them). List that as a behavior change for big channels.
+- **Leftover subscriptions.** Every `client.on(...)`/`channel.on(...)`/`useChatContext` event path needs a CometChat listener that is also removed on unmount/dispose. Missing removals cause duplicate messages.
+- **Custom attachments and `extraData`.** Stream custom fields ride on users, channels and messages; move them into CometChat metadata/custom messages, or they silently disappear.
+- **Half-removed features.** Deleting the API call but leaving the slash command, button or route is a dead end (`RULES.md` → Default-on affordances). Remove the entry point too.
+- **Shared native dependencies.** Removing a Stream peer dependency the app also uses (Reanimated, gesture handler, SVG, image picker) breaks unrelated screens. Grep for other importers first.
+- **Never delete non-Stream code** that just shares a file with Stream code. Rewire it.
+
+## Native platforms (Android · iOS · Flutter) — NOT done until the platform build passes
+Native builds (Android/iOS/Flutter) have extra REQUIRED steps beyond editing code — bump the sample toolchain to the `-core` build floors, add the kit dep AND wire `initFromSettings` in the app entry, port `toCometChatId` to the client language, edit `.pbxproj`/`.xcscheme` as structured build graphs (never a text scrub), and RUN the platform build. **A native migration is NOT done until you have followed `references/native-build.md` in full** — open it and work through every step; it is mandatory, not optional.
+
+## Verify it works
+- The app builds/type-checks with the family's normal command (the core skill's "Verify it works").
+- **RUN it and read the logs — a compile is NOT a working app (do this; don't skip).** When you're done implementing, START the app and confirm it LOADS with the chat surface rendered and NO errors: web → the dev server (or build + preview), open it, watch the **browser console** + the dev-server terminal; native → the platform run + logcat / Xcode console / `flutter` logs. Fix EVERY runtime error you introduced before declaring done — a `Cannot read properties of undefined` from a half-migrated reference, or an SDK enum/class read at module-load before the SDK is ready, is a migration bug, not the user's problem (hand off to `cometchat-<family>-troubleshooting` for symptom → fix). If the app genuinely can't be started here (no dev env / needs a device), SAY SO and give the user the exact run command + what to watch for — never silently skip this.
+- **Zero Stream residue — run exactly this, over ALL file types (docs included):** `grep -rIilE 'stream-chat|stream_chat|@stream-io|getstream|StreamChat|StreamVideo' . --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist --exclude-dir=build --exclude-dir=.claude --exclude-dir=Pods --exclude-dir=.dart_tool --exclude-dir=.gradle | grep -vE 'COMETCHAT_MIGRATION.md|scripts/cometchat-migration'` → must print nothing (repeated `--exclude-dir=` flags on purpose: a `{a,b}` brace list is rejected by the coding agent's command-permission parser, so the check silently never runs). The ONE allowed mention is a single provenance comment above `toCometChatId()`; code identifiers, README lines and env names are residue, not "expected". **This includes a "migrated from <vendor>" line in the README or any doc you write** — a provenance note reads as helpful and is still residue; the migration report is where that belongs, and it is already exempt. Rewrite the app's own README so it describes CometChat, naming the vendor nowhere. The same goes for every other doc the repo ships — `CHANGELOG.md`, `docs/`, `changelogs/`, a vendored SDK's own release notes: if a file is not the migration report, it must not name the vendor. Delete the ones that document the vendor's product rather than your app.
+- `scripts/cometchat-migration/migrate.mjs` + `README.md` exist — **even for a demo/sample app with no data of its own** (it is for the user's real data; step 8 is never skipped).
+- Every CometChat symbol you emitted exists in the family catalog. Every migrated feature is in `features.json` or the docs. Every UNSUPPORTED item is in the report's Removed list with its files.
+- The server token endpoint, the client login and the data script all call the same `toCometChatId()` — from a shared client module, and at login even for already-valid ids (not only inside the data script).
+- **Runtime shape, statically checked:** every element from the root to the conversation list has a height (wrappers included). A user who was signed in before the migration is logged in to CometChat again before the chat renders. No real secret sits in a git-tracked file (`git ls-files` each file you wrote credentials to).

package/skills/cometchat-migrate-from-getstream/references/concept-map.md

@@ -0,0 +1,98 @@
+# Stream → CometChat concept map
+
+This maps **roles**, not code. For every CometChat call, component and prop, take the exact name and signature from the target family's skill (`cometchat-<family>-core` / `-components` / `-features`), its catalog, and the docs (`-core/references/docs-map.md`). The platforms differ: web callbacks are `on*Click`, React Native's are `on*Press`, and Android/iOS/Flutter use their own init shapes. Never port a snippet from one family to another.
+
+## IDs (do this first — everything else depends on it)
+CometChat UIDs and GUIDs are **alpha-dash only** (`a-z`, `0-9`, `-`, `_`), **max 100 characters**, and **lowercased automatically** (`/articles/properties-and-constraints`). Stream user IDs may hold `@`/`.`, cids hold `:`, and member-based channel IDs start with `!members-`. Emit ONE deterministic helper per language the repo uses (client, server, and the data script share its logic exactly):
+
+```js
+// toCometChatId — the single source of truth for Stream ID → CometChat UID/GUID.
+// Deterministic: the same input always yields the same ID, on every platform and in the data script.
+// Channels: ALWAYS pass the full cid ("messaging:general"), never the bare id.
+export function toCometChatId(id) {
+  const raw = String(id);
+  let out = raw.toLowerCase().replace(/[^a-z0-9_-]/g, "_");
+  // Changed or too long → add a short stable hash of the ORIGINAL, so "A.b" and "a_b" never merge.
+  if (out !== raw || out.length > 100) {
+    let h = 0;
+    for (const c of raw) h = (Math.imul(31, h) + c.codePointAt(0)) >>> 0;
+    out = `${out.slice(0, 90)}_${h.toString(36)}`;
+  }
+  return out;
+}
+```
+
+```dart
+// lib/cometchat/ids.dart — the SAME rule as the JS helper (same 32-bit hash, same base-36 suffix); output-identical.
+String toCometChatId(String id) {
+  final raw = id;
+  var out = raw.toLowerCase().replaceAll(RegExp(r'[^a-z0-9_-]'), '_');
+  if (out != raw || out.length > 100) {
+    var h = 0;
+    for (final c in raw.runes) { h = ((31 * h) + c) & 0xFFFFFFFF; }
+    out = '${out.substring(0, out.length > 90 ? 90 : out.length)}_${h.toRadixString(36)}';
+  }
+  return out;
+}
+```
+
+The Dart port above is verbatim; port to Swift/Kotlin the same way: same steps, same 32-bit hash, same base-36 suffix. A user ID that is already valid passes through unchanged. Every cid gets a suffix (it contains `:`), and that's expected: the data script and the app compute the same one.
+
+**Wire it into the CLIENT, not only the data script — this is the #1 Stream migration miss.** Stream user IDs often already *look* valid (`john`, `alice42`), so it is tempting to log in with the raw id and convert only inside the import script. Do NOT. The runtime login/user-creation and the data import must agree on every id, so route the current-user id (and every channel cid) through `toCometChatId()` at login/runtime too — **even when it is a no-op for an already-valid id.** Emit the helper ONCE in a shared client module (e.g. `src/cometchat/ids.ts`) that the login code imports, and copy that exact body verbatim into `scripts/cometchat-migration/id.mjs` (the script can't import app `src`). A `toCometChatId` that exists only in the data script is a **failed migration**: a real user whose Stream id wasn't alpha-dash would be imported under one UID and then logged in under a different one, landing on an empty account.
+
+## Core concepts
+| Stream | CometChat (role) | Notes |
+|---|---|---|
+| API key (client) + API secret (server) | App ID + Region (client), plus a REST API key (server only) | Region comes from the dashboard (`us`/`eu`/`in`). |
+| `StreamChat.getInstance(key)` / `ChatClient.Builder` / `StreamChatClient` / `ChatClientConfig` / `useCreateChatClient` | the family's `initFromSettings` (UI Kit) or the Chat SDK's init | Per core skill. Init once, before login or render. |
+| `connectUser(user, token)` / `tokenProvider` | the auth-token login, with a token from YOUR server (refetch when the session expires) | Production path. |
+| `connectUser(user, client.devToken(id))` | the Auth Key login | Dev only. Action item: move to tokens. |
+| `disconnectUser()` | logout | Also remove the listeners. |
+| User (`id`, `name`, `image`, custom fields) | User (`uid` = `toCometChatId(id)`, name, avatar, metadata) | Users must EXIST before login. The server endpoint creates them; the data script imports the rest. |
+| Member-based channel with 2 members (`!members-…`) | a **user** conversation (1:1) | Receiver = the other member's UID. |
+| Channel with an ID (`messaging:general`, `team:…`) | Group (`guid` = `toCometChatId(cid)`) | Private membership → `private`. Open/livestream → `public`. |
+| `queryChannels` / `ChannelList` filters + sort | the conversations list (UI Kit) or the conversations request builder (SDK) | Stream's filter DSL doesn't carry over. Keep the simple filters (type, membership); list the complex ones as a behavior change. |
+| `channel.watch()` / `channel.query({ messages })` | the message list (UI Kit) or the messages request builder (SDK) | |
+| Message (`text`, `attachments`, custom fields) | text message / media message / custom message + metadata | |
+| `parent_id` / `quoted_message_id` | the parent message ID (thread) / quoted reply (feature row) | |
+| `client.on(event)` / `channel.on(event)` | message / group / user / connection listeners | Add on mount, REMOVE on unmount/dispose. |
+| Channel roles (`channel_moderator`, owner) | group scope `moderator` / `admin` | |
+| `addDevice` | the family's push skill (Notifications product) | |
+
+## UI component map (UI SDK mode)
+| Stream UI (any platform) | CometChat UI Kit role | Where |
+|---|---|---|
+| `<Chat>` / `OverlayProvider` / `StreamChat(…)` wrapper | the kit's provider / init gate from the core | `-core` |
+| `ChannelList` (`<ChannelList>`, `<stream-channel-list>`, `ChatChannelListVC`/`ChatChannelListView`, `ChannelListView`/`ChannelsScreen`, `StreamChannelListView`) | Conversations | `-components` |
+| `Channel` + `Window` + `ChannelHeader` + `MessageList` + `MessageInput` (and platform twins: `ChatChannelVC`, `MessagesScreen`, `MessageListView` + `MessageComposerView`, `StreamMessageListView` + `StreamMessageInput`) | message header + message list + message composer | `-core` / `-components` |
+| `Thread` / `ChatThreadVC` | the thread header + threaded message list | `-features` (`threaded-replies`) |
+| `ChannelSearch` / `SearchBar` | Search | `-features` (`message-search`) |
+| Channel info / members screens (usually app-built) | group details + group members | `-placement` (details panel) |
+
+On React v7 these are `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`, `CometChatThreadHeader`, `CometChatSearch`, `CometChatUsers`, `CometChatGroups` and `CometChatGroupMembers`. Other families: take the names from their `-components` skill.
+
+**Custom Stream components:** a custom `Message`/`Attachment`/`ChannelPreview` component (passed via props or `ViewFactory`/`Components`) maps to the kit's view slots or a custom message type. Use the family's `-customization` skill (slots first, then custom message types). Keep the app's visual intent; don't copy Stream internals.
+
+**Routing and navigation:** keep the app's routes. A param like `/chat/:channelId` becomes `toCometChatId(cid)`. Rebuild the cid from the type the app used, so deep links keep working after the data import.
+
+**Styling:** delete Stream CSS imports and theme objects (`--str-chat__*` variables, `StreamChatTheme`, `ChatTheme`, `Appearance`). Re-apply the brand through `-customization`. Follow-the-OS theming is a core obligation (`RULES.md`).
+
+## Behavioral differences to handle (client-mode gotchas)
+Keeping the app's own UI means matching the vendor's runtime BEHAVIOR, not just method names. The app should look and behave the same after migration — only the data source changed. Watch these:
+- **Optimistic send / local echo.** Stream's `send` channel.sendMessage optimistically inserts the message into channel.state, then reconciles on ack; the message appears instantly, then updates on confirm. CometChat's `CometChat.sendMessage()` resolves with the sent message on success and rejects on failure — there's no separate pending object. To keep the instant-echo UX, insert a local placeholder yourself on submit and replace it with the resolved message (or roll it back on reject). Don't drop the echo and make sends feel laggy.
+- **Pagination.** Stream pages with channel.query({messages:{limit,id_lt}}) / watch. CometChat uses `new CometChat.MessagesRequestBuilder().setUID/setGUID(...).setLimit(n).build()` and `.fetchPrevious()` (older) / `.fetchNext()` (newer), holding ONE builder instance per conversation for the cursor. Map the app's scroll-to-load to the same builder; a fresh builder per page re-fetches from the top.
+- **Listener lifecycle.** Each client.on / channel.on becomes a CometChat listener added with a unique ID and REMOVED on unmount/dispose. Reuse the app's existing subscribe/unsubscribe points; a listener added on every render without removal duplicates messages.
+- **Delivered/read + typing.** These are separate `CometChat` calls and listener events, not fields on the message object. Wire them where the app read the vendor's equivalents.
+- **Fetch every method + shape from the SDK docs** (`/sdk/<platform>/*`) and verify against the catalog — never port the vendor's signature by analogy.
+
+## Client mode (the app draws its own UI)
+Keep every component and screen. Replace only the data layer (the service/store/hook that talks to the Stream client): each method calls the CometChat Chat SDK equivalent, and each `on(...)` subscription becomes a listener. Keep the app's own model types. Map CometChat objects into them at the boundary. **Every CometChat SDK method, its signature, its listener class and its parameter shapes come from the live docs — never from memory and never from the vendor's API by analogy.** For each data-layer call, open the family's SDK docs (`cometchat-<family>-core/references/docs-map.md` → SDK section, or the `-sdk` skill where one ships), fetch the exact method (e.g. `CometChat.getConversationList` via `new CometChat.ConversationsRequestBuilder()`, `CometChat.sendMessage`, `CometChat.addMessageListener`), and verify it against the family catalog before you emit it. A `<vendor>`-method-to-CometChat-method guess that you did not fetch is a defect, even if it compiles. Look up the method list in the family's SDK docs (docs-map → SDK section; React Native: `cometchat-react-native-sdk/references/method-map.md`; Android: `cometchat-android-v5-sdk`).
+
+## Server
+| Stream server piece | CometChat replacement |
+|---|---|
+| Token endpoint (`serverClient.createToken(userId[, exp])`, `upsertUser`) | Your endpoint: create the user if missing (`POST /v3/users`), then `POST /v3/users/{uid}/auth_tokens`. Uses the **REST API key**, server env only (`/rest-api/auth-tokens`). |
+| Webhook receiver (`verifyWebhook`, `x-signature`) | A CometChat webhook receiver with the events mapped (`/rest-api/management-apis/webhooks/overview`). Delete the Stream signature check. |
+| User sync on sign-up / profile update | CometChat REST create/update user, with the same `toCometChatId()` |
+| Before-send hook, custom commands, SQS/SNS | REMOVE + list (feature map) |
+| Env: `STREAM_API_KEY`, `STREAM_API_SECRET` | `COMETCHAT_APP_ID`, `COMETCHAT_REGION`, `COMETCHAT_REST_API_KEY` (placeholders + an action item) |

package/skills/cometchat-migrate-from-getstream/references/data-migration.md

@@ -0,0 +1,74 @@
+# Data migration — Stream history → CometChat (write it; the user runs it)
+
+CometChat supports two approaches (`/fundamentals/data-import-and-migration`):
+- **Historical import:** bulk-load users, groups, members and messages before go-live. It uses the Data Import REST API, and this script does it.
+- **Live migration:** both systems bridged during a gradual rollout. This needs CometChat's team, so if the app can't have a cut-over window, add the action item "contact CometChat sales for live migration".
+
+Emit `scripts/cometchat-migration/` as its OWN tiny package, so it keeps working after Stream is removed from the app:
+- `package.json`: `"type": "module"`. Its only dependency is the Stream server client `stream-chat`, pinned to the major the app's server used.
+- `migrate.mjs`: Node ≥18, uses global `fetch` for CometChat.
+- `id.mjs`: a copy of `toCometChatId()` from `concept-map.md`. Same logic as the app and server.
+- `README.md`: how to run it.
+
+The script reads its secrets from env (`STREAM_API_KEY`, `STREAM_API_SECRET`, `COMETCHAT_APP_ID`, `COMETCHAT_REGION`, `COMETCHAT_REST_API_KEY`), never from a file in the repo. **The agent runs it for the user** once they provide those credentials (SKILL.md step 8): a `--dry-run` first, then the import — always from env vars, never hardcoded into a repo file, and never committed. If the user declines to share credentials, leave running it as an action item instead.
+
+## 1. Export from Stream (server client)
+`const client = StreamChat.getInstance(STREAM_API_KEY, STREAM_API_SECRET)`. The method names come from Stream's server SDK. **Check each one against Stream's current docs while writing the script, and note any difference in the README.**
+
+| Data | Call | Paging |
+|---|---|---|
+| Users | `client.queryUsers({ id: { $gt: lastId } }, { id: 1 }, { limit: 100 })` | keyset on `id` (offset paging is capped) |
+| Channels + members | `client.queryChannels({}, { created_at: 1 }, { limit: 30, offset, state: true, watch: false, member_limit: 100 })` | offset; `channel.queryMembers({}, {}, { limit: 100, offset })` for big channels |
+| Messages | `channel.query({ messages: { limit: 300, id_lt: oldestId } })` | walk backwards until empty |
+| Bulk alternative | `client.exportChannels([{ type, id }, …])` → poll `client.getExportChannelStatus(taskId)` → download `result.url` | better for very large histories |
+
+Back off on HTTP 429. Write each export to `export/*.jsonl` so a failed run can resume.
+
+## 2. Transform
+- **User:** `uid = toCometChatId(user.id)`, `name = user.name || user.id`, `avatar = user.image` (must be a URL), `metadata = { ...customFields, streamUserId: user.id }` (keep it under 5 KB), `createdAt = seconds(user.created_at)`.
+- **Channel:**
+  - Member-based with exactly 2 members (ID starts with `!members-`) → **no group**; its messages become user-to-user messages.
+  - Otherwise: `guid = toCometChatId(channel.cid)`, `name = channel.data.name || channel.id`, `icon = channel.data.image`, `type` = `public` for livestream/open channels, `private` otherwise, `owner = toCometChatId(channel.data.created_by.id)`, `metadata = { streamCid: channel.cid, ...customFields }`, `tags = [channel.type]`.
+- **Member:** the key is `${guid}_member_${uid}`. `owner` → `admin`, `channel_moderator` → `moderator`, else `participant`. `banned` → `isBanned: true`.
+- **Message:**
+  - `muid = message.id`, `sender = toCometChatId(message.user.id)`, `receiverType` + `receiver`, `sentAt = Math.floor(Date.parse(message.created_at) / 1000)`.
+  - `regular`/`reply` with text only → `category:"message"`, `type:"text"`, `data.text`.
+  - With attachments → one media message per attachment: `type` from the attachment (`image`, `video`, `audio`/`voiceRecording` → `audio`, `file`), `data.attachments = [{ url: asset_url || image_url, name: title, mimeType: mime_type, extension, size: file_size }]`, `data.text` = the caption. **CometChat stores the attachment URL by REFERENCE — it does not copy or re-host the file** (verified against the Data Import API), and Stream CDN URLs also expire. So re-host every attachment to your own / CometChat media storage **before decommissioning Stream**, or media breaks. List re-hosting as an action item.
+  - `giphy`/custom attachments → `category:"custom"` with `data.customData` = the attachment.
+  - `system` messages: import as `category:"message", type:"text"` from a system UID so "X joined / renamed" history survives (note the styling change); count them. `deleted` messages: skip.
+  - Mentions → `<@uid:UID>` in the text + `mentionedUserDetails`.
+- **Filter out messages CometChat will reject BEFORE sending — each one, left in a batch, aborts the whole request with HTTP 500 (`ERR_EXCEPTION`) after the good rows have already imported:**
+  - **Older than retention (~6 months):** CometChat retains messages about **6 months** by default and the Data Import API rejects any message whose `sentAt` predates that window (`"Messages older than 6 months cannot be imported"`). This is a **destination limit on the CometChat side — it is the SAME 6 months whether the source is Stream, Sendbird or Twilio**, not a Stream property. Compute `cutoff = now − 6 months`, DROP older messages, count them, and add the action item: *"N messages predate CometChat's 6-month retention window and were not migrated — purchase Extended Storage (contact CometChat sales), then re-run to include them."* (`/fundamentals/data-import-and-migration`; retention: CometChat Help Center → Data Retention.)
+  - **Empty text:** a `type:"text"` message whose `data.text` is empty/whitespace is rejected (`ERR_EMPTY_MESSAGE_TEXT`) — skip it. This also catches body-less `system` lines.
+- **Seconds, not milliseconds:** every CometChat timestamp here is a 10-digit UNIX time.
+- **Not carried by the import API:** thread parent links, quoted-message links, reactions, poll votes, pins, reminders, per-user read state beyond `readAt`/`deliveredAt`. Say so in the report.
+
+## 3. Import into CometChat (Data Import API)
+Base `https://${COMETCHAT_APP_ID}.api-${COMETCHAT_REGION}.cometchat.io/v3/data_import`, with headers `apikey: ${COMETCHAT_REST_API_KEY}` and `content-type: application/json`. Fetch each page for the full payload before writing that call:
+- `/rest-api/data-import-apis/users/import-users`
+- `/rest-api/data-import-apis/groups/import-groups`
+- `/rest-api/data-import-apis/groups/import-group-members`
+- `/rest-api/data-import-apis/messages/import-messages`
+
+| Order | Endpoint | Body shape |
+|---|---|---|
+| 1 | `POST /data_import/users` | `{ "users": { "<uid>": { uid, name, avatar?, metadata?, createdAt? } } }` |
+| 2 | `POST /data_import/groups` | `{ "groups": { "<guid>": { guid, name, type, owner, icon?, metadata?, tags?, createdAt? } } }` |
+| 3 | `POST /data_import/members` | `{ "members": { "<guid>_member_<uid>": { memberId, guid, uid, scope?, isBanned?, joinedAt? } } }` |
+| 4 | `POST /data_import/messages` | `{ "messages": { "<muid>": { muid, sender, receiverType, receiver, category, type, data, sentAt, deliveredAt?, readAt? } } }` |
+
+- **Batching:** at most **50 entities per request** and **60 requests per minute**. Throttle to about one request per second, and retry `ERR_TOO_MANY_REQUESTS` with backoff.
+- **Read PER-ROW results, not the HTTP status.** The response body reports `success` (true/false) per key under `data` — count those, not the status code. A request can even return **HTTP 500 (`ERR_EXCEPTION`) while having imported its rows**, so on any non-2xx do NOT assume nothing landed: re-run (idempotency makes that safe) and rely on the per-row / already-exists signal below.
+- **Treat "already exists" as success, not failure.** On a re-run — or after a 500 that actually landed — rows come back as `ERR_UID_ALREADY_EXISTS` / `ERR_GUID_ALREADY_EXISTS` / `ERR_ALREADY_JOINED` / `ERR_IMPORT_MUID_ALREADY_EXISTS`. These mean the row is present. Log only genuine failures to `import-errors.jsonl` and carry on; never abort the whole run for one bad row.
+- **Idempotency:** re-running with the same uid/guid/muid is safe (overwrite / already-exists).
+- **Order matters:** users → groups → members → messages, oldest messages first.
+
+Finish by printing counts: exported, imported, converted (system→text), skipped (deleted / beyond the 6-month retention window / empty), failed (with a pointer to the error file).
+
+## README.md for the script (emit it)
+1. Create a **REST API key** (full access) in the CometChat dashboard.
+2. `cd scripts/cometchat-migration && npm install`, then export the five env vars.
+3. Dry run: `node migrate.mjs --dry-run`. This exports and transforms, then prints counts without importing.
+4. Import: `node migrate.mjs`.
+5. Spot-check a few conversations in the dashboard, then point production at the new build.
+6. Delete the export files (they hold user data), and delete this folder once the cut-over is done.