@cometchat/skills 4.1.0 → 4.2.0

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

@@ -0,0 +1,198 @@
+# 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).
+
+---
+
+## 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 {
+      setSessionID() { return this; }
+      setIsAudioOnly() { 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/voip-and-web-push.md

@@ -0,0 +1,165 @@
+# 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).

package/skills/cometchat-react-patterns/SKILL.md

@@ -3,7 +3,7 @@ name: cometchat-react-patterns
 description: "Framework-specific patterns for integrating CometChat React UI Kit v6 into React projects (Vite or CRA). Covers provider setup, routing, layout integration, env vars, and common pitfalls."
 license: "MIT"
 compatibility: "Node.js >=18; React >=18; Vite >=4 or react-scripts (CRA); @cometchat/chat-uikit-react ^6; @cometchat/chat-sdk-javascript ^4"
-allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"