@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-react-calls/references/share-invite.md

@@ -1,175 +0,0 @@
-# Share invite on web (React)
-
-Let participants share the call link with others. The kit ships a share-invite button (hidden by default); your app intercepts the click and runs the platform's native share UI.
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/javascript/share-invite
-
----
-
-## Hard rule: deep-link routing must work BEFORE you ship share-invite
-
-A share button that copies a URL nobody can open is worse than no share button. Verify your app's `/call/:sessionId` route handles all four states:
-
-1. **User logged in, in-app** → join call directly
-2. **User logged in, fresh tab** → restore session, join call
-3. **User logged out** → login, then redirect to call
-4. **User doesn't have account** → signup flow with `?invite=...` query param
-
-Build the deep-link route first, then turn on the share button.
-
----
-
-## Show the kit's share button
-
-```tsx
-const callSettings = {
-  hideShareInviteButton: false,
-  // ... rest
-};
-```
-
----
-
-## Handle the click
-
-```tsx
-useEffect(() => {
-  const handler = () => shareCallInvite(sessionId);
-  // addEventListener returns an unsubscribe fn — there is no removeEventListener.
-  const off = CometChatCalls.addEventListener("onShareInviteButtonClicked", handler);
-  return () => off();
-}, [sessionId]);
-```
-
----
-
-## Native Web Share API + clipboard fallback
-
-```tsx
-async function shareCallInvite(sessionId: string) {
-  const url = `https://yourapp.com/call/${sessionId}`;
-  const shareData = {
-    title: "Join my call",
-    text: "I'm on a call — tap to join.",
-    url,
-  };
-
-  if (navigator.share && navigator.canShare?.(shareData)) {
-    try {
-      await navigator.share(shareData);
-    } catch (err) {
-      // User cancelled — that's fine, no toast needed
-      if ((err as Error).name !== "AbortError") {
-        console.warn("Share failed", err);
-      }
-    }
-    return;
-  }
-
-  // Fallback: clipboard
-  try {
-    await navigator.clipboard.writeText(url);
-    showToast("Link copied to clipboard");
-  } catch {
-    // Clipboard API requires user gesture + secure context (https) — must always have a manual fallback
-    promptManualCopy(url);
-  }
-}
-```
-
-`navigator.share` is iOS Safari + Android Chrome + recent desktop Chrome. `navigator.clipboard.writeText` is everywhere modern but **only works in secure contexts (https)** — localhost is fine; non-https staging hosts will throw.
-
----
-
-## Custom share dialog (when you want more control)
-
-```tsx
-function ShareDialog({ sessionId, onClose }: Props) {
-  const url = `https://yourapp.com/call/${sessionId}`;
-  return (
-    <dialog open className="share-dialog" role="dialog" aria-label="Share call invite">
-      <button onClick={() => navigator.clipboard.writeText(url)}>Copy link</button>
-      <a href={`mailto:?subject=Join%20my%20call&body=${encodeURIComponent(url)}`}>Email</a>
-      <a href={`sms:?body=${encodeURIComponent(url)}`}>SMS</a>
-      <button onClick={onClose}>Close</button>
-    </dialog>
-  );
-}
-```
-
-`mailto:` opens default email client; `sms:` opens default SMS app on mobile (no-op on most desktops). Both are universal — no provider lock-in.
-
----
-
-## QR code for in-person sharing
-
-For "share to the person sitting next to you" UX, a QR is faster than a link:
-
-```tsx
-import QRCode from "qrcode.react";
-
-function CallQR({ sessionId }: { sessionId: string }) {
-  const url = `https://yourapp.com/call/${sessionId}`;
-  return (
-    <div>
-      <QRCode value={url} size={192} />
-      <p>{url}</p>
-    </div>
-  );
-}
-```
-
----
-
-## Anti-patterns
-
-1. **Sharing the raw `sessionId` instead of a deep link.** Recipients can't open it.
-2. **Wiring share before the deep-link route works.** Recipients click → 404.
-3. **`navigator.clipboard.writeText` without a manual-copy fallback.** Fails in non-https contexts (e.g., embedded iframes, dev tunnels).
-4. **Showing "Link copied!" toast even when share was cancelled.** `AbortError` is the user dismissing the share sheet — silent.
-5. **Forgetting to call the unsubscribe fn on unmount.** `addEventListener` returns a `() => void` — call it in cleanup (there is no `removeEventListener`). Otherwise the listener accumulates → multiple share sheets per click.
-6. **Hard-coding `https://yourapp.com`.** Use `window.location.origin` or `import.meta.env.VITE_APP_URL`.
-
----
-
-## Server-side: deep links + auth bridge
-
-If invitee isn't logged in, `https://yourapp.com/call/SESSION_ID` should redirect them through login THEN to the call. Pattern:
-
-```ts
-// pages/call/[sessionId].tsx (Next.js example)
-export async function getServerSideProps({ params, req }) {
-  const session = await getSession(req);
-  if (!session) {
-    return {
-      redirect: {
-        destination: `/login?next=/call/${params.sessionId}`,
-        permanent: false,
-      },
-    };
-  }
-  return { props: { sessionId: params.sessionId } };
-}
-```
-
-For invitees without an account, send them to `/signup?invite=SESSION_ID` and store the pending invite in `localStorage` until signup completes.
-
----
-
-## Verification checklist
-
-- [ ] Deep-link route `/call/:sessionId` works in 4 states (logged in / logged out / no account / fresh tab)
-- [ ] `hideShareInviteButton: false` in CallSettings
-- [ ] `onShareInviteButtonClicked` listener cleaned up on unmount
-- [ ] `navigator.share` used when available; clipboard fallback; manual-copy fallback for non-https
-- [ ] AbortError silenced
-- [ ] App URL not hard-coded — read from env
-- [ ] Smoke: copy link → paste in incognito → can join call
-
----
-
-## Pointers
-
-- `cometchat-react-calls/SKILL.md` — call architecture
-- `cometchat-react-calls/references/in-call-chat.md` — sister cross-cutting concern
-- Canonical docs: https://www.cometchat.com/docs/calls/javascript/share-invite

package/skills/cometchat-react-calls/references/testing-calls-on-web.md

@@ -1,216 +0,0 @@
-# Testing calls on web
-
-Calls are the hardest CometChat surface to unit-test because they touch native browser APIs (`getUserMedia`, `RTCPeerConnection`) that don't exist in jsdom. Three layers, three strategies:
-
-1. **Unit tests** — mock the entire Calls SDK; assert your code calls the right methods in the right order.
-2. **Component tests** — Vitest + React Testing Library; mock `getUserMedia` and `RTCPeerConnection`; assert your custom UI renders correctly given mocked SDK events.
-3. **E2E tests** — Playwright with the headless WebRTC flag; real two-tab call between two test users.
-
-This reference covers all three. For chat-side testing patterns, see `cometchat-react-testing` (sibling skill).
-
----
-
-## ⚠️ Ringing-mode manual testing needs TWO ISOLATED browser contexts (not two tabs)
-
-The single most common "incoming call never rings / Accept never appears" report is a **test-setup** problem, not a code bug:
-
-**The Chat SDK is one session per browser origin.** `CometChat.login()` persists the logged-in user in **IndexedDB/localStorage keyed by `appId`** and maintains **one WebSocket per origin** — both **shared across every tab** of `localhost:5173`. Two tabs in the *same* browser therefore CANNOT hold two different logins: the second tab's login overwrites the shared session, so there is no independent callee connected to receive `onIncomingCallReceived`. A per-tab `sessionStorage` "user switcher" only changes what *your app* thinks the user is — the Chat SDK underneath is still a single shared session.
-
-- **Ringing mode (1:1 / `initiateCall` → `onIncomingCallReceived`)** → needs **two isolated contexts**: a normal window for the caller + an **Incognito/Private window** (or a different browser, or a second device) for the callee. Only then are there two distinct Chat-SDK sessions + sockets.
-- **Session/meeting mode (`joinSession` on a shared `sessionId`)** → two tabs in the *same* browser are fine — it doesn't depend on two live Chat-SDK logins; both sides just join the same session id.
-
-Sanity-check in the callee context's console — it must show the callee, not the caller:
-```js
-await CometChat.getLoggedinUser()   // → User { uid: "cometchat-uid-2", ... }
-```
-If it shows the caller's uid (or `null`), the callee isn't an independent receiver — that's the shared-session symptom.
-
-Two devices on a LAN need HTTPS for `getUserMedia` (secure-context), but the ring itself arrives over plain `localhost` in incognito.
-
----
-
-## 1. Unit tests — mock the SDK module
-
-Vitest's `vi.mock` with a hoisted factory:
-
-```ts
-// __tests__/CallButton.test.tsx
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, screen, fireEvent } from "@testing-library/react";
-import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
-import { CallButton } from "../src/components/CallButton";
-
-vi.mock("@cometchat/chat-sdk-javascript", () => ({
-  CometChat: {
-    initiateCall: vi.fn().mockResolvedValue({ getSessionId: () => "session-123" }),
-    Call: vi.fn((uid, type, recv) => ({ uid, type, recv })),
-    CALL_TYPE: { VOICE: "voice", VIDEO: "video" },
-    RECEIVER_TYPE: { USER: "user" },
-  },
-}));
-
-vi.mock("@cometchat/calls-sdk-javascript", () => ({
-  CometChatCalls: {
-    init: vi.fn(),
-    generateToken: vi.fn().mockResolvedValue({ token: "rtc-token" }),
-    startSession: vi.fn(),
-    endSession: vi.fn(),
-    CallSettingsBuilder: class {
-      setIsAudioOnlyCall() { return this; }
-      enableDefaultLayout() { return this; }
-      build() { return {}; }
-    },
-  },
-}));
-
-beforeEach(() => vi.clearAllMocks());
-
-describe("CallButton", () => {
-  it("initiates a video call when video button clicked", async () => {
-    const { CometChat } = await import("@cometchat/chat-sdk-javascript");
-    render(<CallButton user={{ uid: "alice" }} />);
-
-    await fireEvent.click(screen.getByLabelText("Start video call"));
-
-    expect(CometChat.initiateCall).toHaveBeenCalledWith(
-      expect.objectContaining({ uid: "alice", type: "video" }),
-    );
-  });
-});
-```
-
----
-
-## 2. Component tests — mock `getUserMedia` + `RTCPeerConnection`
-
-For tests that exercise your custom UI's reaction to track-arrived events:
-
-```ts
-// vitest.setup.ts
-import { vi } from "vitest";
-
-beforeAll(() => {
-  // jsdom doesn't have navigator.mediaDevices — polyfill it
-  Object.defineProperty(navigator, "mediaDevices", {
-    writable: true,
-    value: {
-      getUserMedia: vi.fn().mockResolvedValue({
-        getTracks: () => [
-          { kind: "audio", stop: vi.fn() },
-          { kind: "video", stop: vi.fn() },
-        ],
-      }),
-      getDisplayMedia: vi.fn().mockResolvedValue({ getTracks: () => [{ stop: vi.fn() }] }),
-      enumerateDevices: vi.fn().mockResolvedValue([]),
-    },
-  });
-
-  // Polyfill RTCPeerConnection
-  (global as Record<string, unknown>).RTCPeerConnection = class {
-    addTrack = vi.fn();
-    addEventListener = vi.fn();
-    createOffer = vi.fn().mockResolvedValue({ sdp: "fake-offer", type: "offer" });
-    createAnswer = vi.fn().mockResolvedValue({ sdp: "fake-answer", type: "answer" });
-    setLocalDescription = vi.fn();
-    setRemoteDescription = vi.fn();
-    close = vi.fn();
-  };
-});
-```
-
-Reference this in `vitest.config.ts`:
-
-```ts
-export default defineConfig({
-  test: {
-    setupFiles: ["./vitest.setup.ts"],
-    environment: "jsdom",
-  },
-});
-```
-
----
-
-## 3. E2E tests — Playwright with WebRTC enabled
-
-Playwright supports real WebRTC in headless mode with the right Chromium flag:
-
-```ts
-// playwright.config.ts
-import { defineConfig } from "@playwright/test";
-
-export default defineConfig({
-  use: {
-    launchOptions: {
-      args: [
-        "--use-fake-ui-for-media-stream",          // auto-grants getUserMedia
-        "--use-fake-device-for-media-stream",      // synthetic camera (animated pattern)
-        "--allow-running-insecure-content",
-      ],
-    },
-  },
-});
-```
-
-Then a two-page test exercises the full call flow:
-
-```ts
-import { test, expect, type Page } from "@playwright/test";
-
-async function login(page: Page, uid: string) {
-  await page.goto("/");
-  await page.evaluate((uid) => localStorage.setItem("cc-test-uid", uid), uid);
-  await page.reload();
-  await expect(page.getByTestId("logged-in-banner")).toBeVisible();
-}
-
-test("alice calls bob; bob answers; both see two-way video", async ({ browser }) => {
-  const aliceCtx = await browser.newContext();
-  const bobCtx = await browser.newContext();
-  const alice = await aliceCtx.newPage();
-  const bob = await bobCtx.newPage();
-
-  await login(alice, "cometchat-uid-1");
-  await login(bob, "cometchat-uid-2");
-
-  // Alice clicks call on Bob's profile
-  await alice.goto("/users/cometchat-uid-2");
-  await alice.getByLabel("Start video call").click();
-
-  // Bob's IncomingCall overlay appears
-  await expect(bob.getByText("Incoming call from")).toBeVisible({ timeout: 10_000 });
-  await bob.getByRole("button", { name: "Accept" }).click();
-
-  // Both see the ongoing-call view
-  await expect(alice.getByTestId("ongoing-call")).toBeVisible();
-  await expect(bob.getByTestId("ongoing-call")).toBeVisible();
-
-  // Verify two video elements are playing (synthetic streams)
-  const aliceVideos = await alice.locator("video").count();
-  expect(aliceVideos).toBeGreaterThanOrEqual(2);   // local + remote
-
-  // Hangup
-  await alice.getByRole("button", { name: "End" }).click();
-  await expect(alice.getByTestId("ongoing-call")).not.toBeVisible();
-  await expect(bob.getByTestId("ongoing-call")).not.toBeVisible();
-});
-```
-
-**Synthetic stream gotcha:** the `--use-fake-device-for-media-stream` flag makes Chrome stream a green-and-blue animated pattern. Real cameras / mics are NOT used, so you cannot assert "this video shows the user's face." You CAN assert "two video elements with `srcObject` set," which is what 90% of tests need.
-
----
-
-## CI gotchas
-
-- **Linux GPU + WebRTC:** GitHub Actions Ubuntu runners have headless Chrome but no GPU. Pass `--disable-gpu` if you see WebRTC errors about GPU process crash; the synthetic stream still works.
-- **Test isolation:** real CometChat App ID + Auth Key in CI. Use a dedicated test app (Dashboard → New App → "ci-tests"); don't reuse production credentials.
-- **Rate limits:** the CometChat backend rate-limits `initiateCall` per user. Tests that loop call/hangup quickly hit limits; throttle to ~5 calls/minute per test UID or rotate UIDs (`cometchat-uid-1` through `cometchat-uid-5` are pre-seeded).
-- **Cleanup:** kill any active calls between tests via `CometChatCalls.leaveSession()` in afterEach. Stale sessions cause the next test's `initiateCall` to fail.
-
----
-
-## What NOT to mock
-
-- **Don't mock `useEffect` cleanup.** It's where rule 1.3's track-stop happens; mocking hides bugs in the cleanup path.
-- **Don't mock `navigator.mediaDevices` to return synchronous values.** Real APIs are async; mocks should be too, otherwise you mask race conditions in your real code.
-- **Don't mock the kit components themselves** (`<CometChatIncomingCall />` etc.) for unit tests — they're tested by CometChat. Mock the SDK that the kit calls.

package/skills/cometchat-react-calls/references/virtual-background.md

@@ -1,32 +0,0 @@
-# Virtual Background (web)
-
-Verified against `@cometchat/calls-sdk-javascript@5`. Web (React/Angular) is one of the few platforms that supports virtual background (native iOS/Android do not). Two ways to expose it:
-
-## A. Let the kit show its built-in setting (additive / kit components)
-
-Enable the kit's own Virtual Background button on the call settings builder — it renders a blur/image/clear picker inside the call UI, no custom code:
-
-```ts
-const settings = new CometChatCalls.CallSettingsBuilder()
-  .enableDefaultLayout(true)
-  .showVirtualBackgroundSetting(true)   // ← shows the built-in VB control
-  .build();
-```
-
-To read the current state, call `getVirtualBackground()` on a built `CallSettings` instance — it's an **instance** method on `CallSettings` (`callSettings.getVirtualBackground(): VirtualBackground`), not a `CometChatCalls` static.
-
-## B. Apply programmatically (custom call surface)
-
-Three static methods on `CometChatCalls`, callable during an active session:
-
-```ts
-import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
-
-CometChatCalls.setVirtualBackgroundBlurLevel(50);              // blur (0–100)
-CometChatCalls.setVirtualBackgroundImage("https://…/bg.jpg");  // custom image
-CometChatCalls.clearVirtualBackground();                        // remove
-```
-
-> The older `setBackgroundBlur()` / `setBackgroundImage()` names are **deprecated** — use the `setVirtualBackground*` forms above.
-
-Verified (calls-sdk `index.d.ts`): `CallSettingsBuilder.showVirtualBackgroundSetting(boolean)`, instance `CallSettings.getVirtualBackground(): VirtualBackground`, and the statics `CometChatCalls.setVirtualBackgroundBlurLevel(number)` / `setVirtualBackgroundImage(string)` / `clearVirtualBackground()`.

package/skills/cometchat-react-calls/references/voip-and-web-push.md

@@ -1,165 +0,0 @@
-# VoIP push on web — there isn't any
-
-Web browsers do not have VoIP push. You cannot ring a user whose tab is closed. The closest equivalents are:
-
-1. **Web Push** (Service Worker + Push API + Notification API) — can fire a system-level notification while the browser is open even if the tab is backgrounded. Limitations:
-   - Service Worker must be installed (one prior visit required)
-   - User must have granted notification permission
-   - Browser must be running (Chrome/Edge can deliver to closed tabs IF the browser process is alive; Safari requires Safari to be running; Firefox stops Service Workers aggressively)
-   - Does NOT bypass closed browser. Production calling apps on web pair this with email/SMS fallback for missed calls.
-
-2. **Email/SMS missed-call fallback** — server-side. When a call rings unanswered for ~30 seconds, send a "missed call from X" email/SMS with a deep link back into the app.
-
-This reference covers Web Push end-to-end. Email/SMS is out of scope (server-side only, not skill-scaffoldable).
-
----
-
-## Web Push setup (Service Worker + push subscription)
-
-### 1. Generate VAPID keys (server-side, one-time)
-
-```bash
-npx web-push generate-vapid-keys
-```
-
-Stores public + private keys. Public goes to the client; private stays on the push server.
-
-### 2. Register the Service Worker
-
-`public/sw.js`:
-
-```js
-self.addEventListener("push", (event) => {
-  if (!event.data) return;
-  const payload = event.data.json();
-  if (payload.type !== "incoming_call") return;
-
-  event.waitUntil(
-    self.registration.showNotification("Incoming call", {
-      body: `${payload.callerName} is calling`,
-      icon: "/icons/call.png",
-      tag: `call-${payload.sessionId}`,           // dedupe — only one ring per session
-      requireInteraction: true,                    // don't auto-dismiss
-      data: { sessionId: payload.sessionId, callerUid: payload.callerUid },
-    }),
-  );
-});
-
-self.addEventListener("notificationclick", (event) => {
-  event.notification.close();
-  event.waitUntil(
-    clients.matchAll({ type: "window", includeUncontrolled: true }).then((wins) => {
-      // Focus existing tab if open, otherwise open a new one
-      for (const w of wins) {
-        if (w.url.includes(self.registration.scope)) {
-          w.focus();
-          w.postMessage({ type: "incoming_call_click", ...event.notification.data });
-          return;
-        }
-      }
-      return clients.openWindow(`/calls/incoming?sessionId=${event.notification.data.sessionId}`);
-    }),
-  );
-});
-```
-
-### 3. Register from the app
-
-```ts
-// cometchat/registerWebPush.ts
-const VAPID_PUBLIC = import.meta.env.VITE_VAPID_PUBLIC_KEY;
-
-export async function registerWebPushForCalls(uid: string): Promise<void> {
-  if (!("serviceWorker" in navigator) || !("PushManager" in window)) return;
-
-  const reg = await navigator.serviceWorker.register("/sw.js");
-  const permission = await Notification.requestPermission();
-  if (permission !== "granted") return;
-
-  const subscription = await reg.pushManager.subscribe({
-    userVisibleOnly: true,
-    applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC),
-  });
-
-  // Send subscription to YOUR server, keyed by uid
-  await fetch("/api/push/subscribe", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ uid, subscription }),
-  });
-}
-
-function urlBase64ToUint8Array(base64: string): Uint8Array {
-  const padding = "=".repeat((4 - (base64.length % 4)) % 4);
-  const raw = atob((base64 + padding).replace(/-/g, "+").replace(/_/g, "/"));
-  return Uint8Array.from(raw, (c) => c.charCodeAt(0));
-}
-```
-
-### 4. Listen for SW messages in your React app
-
-```tsx
-// CometChatProvider.tsx
-useEffect(() => {
-  const handler = (event: MessageEvent) => {
-    if (event.data?.type === "incoming_call_click") {
-      // Navigate to the call screen and let CometChatIncomingCall pick it up
-      navigate(`/calls/incoming?sessionId=${event.data.sessionId}`);
-    }
-  };
-  navigator.serviceWorker.addEventListener("message", handler);
-  return () => navigator.serviceWorker.removeEventListener("message", handler);
-}, [navigate]);
-```
-
-### 5. Server-side push send (signaling integration)
-
-Your CometChat backend (or webhook listener) detects an incoming call event and sends Web Push to the receiver's subscription:
-
-```ts
-// server (Node.js) — runs when CometChat fires the call.received webhook
-import webpush from "web-push";
-
-webpush.setVapidDetails("mailto:you@example.com", VAPID_PUBLIC, VAPID_PRIVATE);
-
-async function sendIncomingCallPush(receiverUid: string, sessionId: string, callerName: string, callerUid: string) {
-  const subs = await getSubscriptionsForUid(receiverUid);  // your DB
-  await Promise.allSettled(
-    subs.map((sub) =>
-      webpush.sendNotification(sub, JSON.stringify({
-        type: "incoming_call",
-        sessionId,
-        callerName,
-        callerUid,
-      })),
-    ),
-  );
-}
-```
-
-The webhook setup itself is server-side; the skill scaffolds the client side and points users at this template for the server.
-
----
-
-## Browser support matrix
-
-| Browser | Push API | Notification while tab closed | Service Worker terminated background |
-|---|---|---|---|
-| Chrome/Edge desktop | ✓ | ✓ if browser process alive | After ~30s idle |
-| Chrome/Edge mobile | ✓ | ✓ | Aggressive; Web Push is best-effort |
-| Firefox desktop | ✓ | ✓ | After ~30s idle |
-| Safari 16+ desktop | ✓ | ✓ if Safari running | Tighter |
-| Safari iOS 16.4+ | ✓ | Only when added to Home Screen as PWA | N/A — PWA only |
-| Mobile Web (any) | Limited | Often not delivered when browser killed | OS-driven |
-
-**Bottom line:** Web Push is "best-effort ring" — it works often enough to be worth wiring, but production calling apps must have a missed-call email/SMS fallback. The skill warns the user about this explicitly during scaffold.
-
----
-
-## When NOT to bother with Web Push
-
-- Internal tools where users keep the tab open during work hours — `<CometChatIncomingCall />` mounted at root rings the tab itself, which is enough.
-- Apps where the call surface is a route the user navigates to deliberately (telehealth waiting room) — the ring happens when they arrive on the route; they don't need to be paged.
-- Greenfield projects that haven't shipped to production yet — add it later when missed-calls become a real complaint.
-
-The dispatcher's Step 3 in `cometchat-react-calls/SKILL.md` asks the user whether to scaffold Web Push. Default = no for "just exploring" / "messaging app" intents; default = yes for "support" / "marketplace" intents (where users may receive a call without expecting it).