@cometchat/skills 4.1.0 → 4.2.0

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

@@ -0,0 +1,448 @@
+---
+name: cometchat-react-push
+description: Push notifications for CometChat React UI Kit v6 in Vite / Next.js / React Router / Astro projects. Web doesn't have native push — covers Web Push (Service Worker + Push API + Notification API + VAPID keys), CometChat dashboard PushPlatform configuration, server-side webhook to send pushes when a message arrives, click-through to chat, foreground vs background handling, iOS Safari 16.4+ PWA-only quirks, and HTTPS requirements.
+license: "MIT"
+compatibility: "React >= 18; Web Push API (Chrome 50+, Firefox 44+, Edge 17+, Safari 16+ desktop, Safari 16.4+ iOS PWA-only); HTTPS required (or localhost); CometChat dashboard PushPlatform configured"
+allowed-tools: "shell, file-read, file-search, file-list, ask-user"
+metadata:
+  author: "CometChat"
+  version: "4.0.0"
+  tags: "cometchat react web push notifications service-worker vapid push-api notification-api ios-safari-pwa nextjs astro react-router"
+---
+
+## Purpose
+
+Web Push for CometChat chat. The web has no native VoIP-push equivalent for incoming-call ringing (see `cometchat-react-calls/references/voip-and-web-push.md` for that limit), but it does have **Web Push** for new-message notifications when the user's tab is backgrounded or closed. This skill wires the full path: client subscription → server webhook → push send → notification → click-through.
+
+**Not the same as the calls Web Push.** Calls Web Push tries to ring the device through a closed tab (best-effort, browser-dependent). Chat Web Push notifies on new messages — fundamentally similar plumbing, different payload + UX. Many apps need both.
+
+**Read these other skills first:**
+- `cometchat-core` — provider pattern, login order
+- `cometchat-{react,nextjs,react-router,astro}-patterns` — framework-specific Service Worker registration
+- `cometchat-react-calls/references/voip-and-web-push.md` — calls-specific Web Push (overlap with this; both can coexist)
+- `cometchat-production` — server-minted auth tokens (push payloads should NOT contain Auth Key)
+
+**Ground truth:**
+- Web Push spec — https://datatracker.ietf.org/doc/html/rfc8030
+- VAPID — https://datatracker.ietf.org/doc/html/rfc8292
+- Push API — https://developer.mozilla.org/en-US/docs/Web/API/Push_API
+- CometChat dashboard `PushNotifications` (formerly Extensions → Enhanced Push Notifications)
+
+---
+
+## 1. Architecture
+
+```
+Browser (your React app)
+  ├── Service Worker — long-lived; receives push events
+  ├── Push subscription — issued by browser, sent to your server
+  └── Notification UI — fired by SW on push event
+
+CometChat backend
+  └── Webhook → your push server when a message is sent
+
+Your push server (Node, Cloudflare Worker, Lambda, etc.)
+  ├── Stores push subscriptions per UID
+  ├── Receives CometChat webhook
+  └── Sends push payload via web-push lib → browser
+```
+
+Three pieces, all yours: client SW, push server, webhook integration. CometChat doesn't host the push server for you — its dashboard's "PushPlatform" config is for FCM/APNs (mobile), not Web Push.
+
+---
+
+## 2. Generate VAPID keys (server-side, one-time)
+
+VAPID = Voluntary Application Server Identification — proves to the browser that the push originated from an authorized server.
+
+```bash
+npx web-push generate-vapid-keys
+```
+
+Output:
+```
+=======================================
+Public Key: BLBz-...
+Private Key: 9tT...
+=======================================
+```
+
+Public key → client (env var). Private key → push server only (never ship to client).
+
+---
+
+## 3. Service Worker
+
+### `public/sw.js` (Vite / CRA / React Router) or `app/sw.js` (Next.js / Astro)
+
+```js
+// Fired when a push payload arrives
+self.addEventListener("push", (event) => {
+  if (!event.data) return;
+
+  let payload;
+  try {
+    payload = event.data.json();
+  } catch {
+    return;
+  }
+
+  if (payload.type !== "new_message") return;
+
+  event.waitUntil(
+    self.registration.showNotification(payload.senderName, {
+      body: payload.preview,                          // truncated message
+      icon: payload.senderAvatar ?? "/icons/chat.png",
+      tag: `chat-${payload.conversationId}`,          // dedupe — replace prior unread for same conversation
+      badge: "/icons/badge.png",
+      data: {
+        conversationId: payload.conversationId,
+        senderUid: payload.senderUid,
+        receiverType: payload.receiverType,           // "user" or "group"
+      },
+    }),
+  );
+});
+
+// Fired when user clicks the notification
+self.addEventListener("notificationclick", (event) => {
+  event.notification.close();
+
+  const data = event.notification.data;
+  const targetUrl = data.receiverType === "group"
+    ? `/messages?group=${data.conversationId}`
+    : `/messages?user=${data.senderUid}`;
+
+  event.waitUntil(
+    clients.matchAll({ type: "window", includeUncontrolled: true }).then((wins) => {
+      // Focus existing tab if open
+      for (const w of wins) {
+        if (w.url.includes(self.registration.scope)) {
+          w.focus();
+          w.postMessage({ type: "open_conversation", ...data });
+          return;
+        }
+      }
+      // Otherwise open a new tab
+      return clients.openWindow(targetUrl);
+    }),
+  );
+});
+
+// Optional: fired when a notification is dismissed without click
+self.addEventListener("notificationclose", (event) => {
+  // Send a "dismissed" beacon to your server if you track this
+});
+```
+
+---
+
+## 4. Client-side registration
+
+```ts
+// cometchat/registerWebPush.ts
+const VAPID_PUBLIC = import.meta.env.VITE_VAPID_PUBLIC_KEY;     // adjust prefix per framework
+
+export async function registerWebPushForChat(uid: string): Promise<void> {
+  if (!("serviceWorker" in navigator) || !("PushManager" in window)) return;
+
+  // Register the SW (one-time per origin)
+  const reg = await navigator.serviceWorker.register("/sw.js");
+
+  // Wait for SW activation
+  await navigator.serviceWorker.ready;
+
+  // Ask permission — must be in response to a user gesture (click)
+  const permission = await Notification.requestPermission();
+  if (permission !== "granted") return;
+
+  // Get or create subscription
+  let subscription = await reg.pushManager.getSubscription();
+  if (!subscription) {
+    subscription = await reg.pushManager.subscribe({
+      userVisibleOnly: true,                          // required by Chrome
+      applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC),
+    });
+  }
+
+  // Send subscription to YOUR push 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));
+}
+```
+
+Call this from your CometChatProvider AFTER login resolves:
+
+```tsx
+// CometChatProvider.tsx
+useEffect(() => {
+  if (!user) return;
+  registerWebPushForChat(user.uid).catch((err) => {
+    // surface to UI but don't block chat — push is opt-in
+    console.warn("Web Push registration failed:", err);
+  });
+}, [user]);
+```
+
+**The permission prompt rule:** Chrome / Firefox / Safari all require permission requests in response to a user gesture. If you call `Notification.requestPermission()` from a top-level `useEffect` that runs on page load, browsers reject it. Best pattern: a "Enable notifications" button the user clicks once.
+
+---
+
+## 5. Listen for SW messages in the React app
+
+```tsx
+// CometChatProvider.tsx
+useEffect(() => {
+  if (!("serviceWorker" in navigator)) return;
+
+  const handler = (event: MessageEvent) => {
+    if (event.data?.type === "open_conversation") {
+      navigate(`/messages?${event.data.receiverType}=${event.data.conversationId}`);
+    }
+  };
+  navigator.serviceWorker.addEventListener("message", handler);
+  return () => navigator.serviceWorker.removeEventListener("message", handler);
+}, [navigate]);
+```
+
+When the SW posts `open_conversation`, the React app navigates to the right thread.
+
+---
+
+## 6. Server-side push send
+
+Your push server runs on Node.js / Cloudflare Worker / Lambda / Vercel Functions. The shape:
+
+```ts
+// server/push.ts
+import express from "express";
+import webpush from "web-push";
+import { z } from "zod";
+
+webpush.setVapidDetails(
+  "mailto:notifications@yourapp.com",
+  process.env.VAPID_PUBLIC!,
+  process.env.VAPID_PRIVATE!,
+);
+
+const app = express();
+app.use(express.json());
+
+// 1. Client registers a subscription
+app.post("/api/push/subscribe", async (req, res) => {
+  const { uid, subscription } = req.body;          // validate with zod in production
+  await db.savePushSubscription(uid, subscription);
+  res.status(204).send();
+});
+
+// 2. CometChat fires a webhook when a message is sent
+app.post("/webhook/cometchat/message-sent", async (req, res) => {
+  const { receiver, sender, data } = req.body.data;
+
+  // Don't notify the sender — they sent the message
+  const subs = await db.getPushSubscriptions(receiver);
+  if (!subs.length) return res.status(204).send();
+
+  const payload = JSON.stringify({
+    type: "new_message",
+    conversationId: receiver,
+    senderUid: sender.uid,
+    senderName: sender.name,
+    senderAvatar: sender.avatar,
+    preview: truncate(data.text, 80),
+    receiverType: data.entityType,                 // "user" or "group"
+  });
+
+  // Send to all of receiver's subscriptions in parallel; clean up dead ones
+  await Promise.allSettled(
+    subs.map(async (sub) => {
+      try {
+        await webpush.sendNotification(sub, payload);
+      } catch (err: unknown) {
+        if ((err as { statusCode?: number }).statusCode === 410) {
+          await db.removePushSubscription(receiver, sub);   // browser unsubscribed
+        }
+      }
+    }),
+  );
+
+  res.status(204).send();
+});
+
+function truncate(s: string, n: number) {
+  return s.length <= n ? s : s.slice(0, n - 1) + "…";
+}
+
+app.listen(3000);
+```
+
+The skill writes a starter version of this server file (`server/push.example.ts`) with a README pointing at env vars; the user owns the actual deployment.
+
+---
+
+## 7. CometChat webhook setup (manual)
+
+In the CometChat dashboard:
+
+1. Navigate to **Webhooks**.
+2. Click **+ Webhook**.
+3. URL: `https://your-push-server.example.com/webhook/cometchat/message-sent`
+4. Trigger: **Message sent**
+5. Verification: copy the signing secret to your push server's env (`COMETCHAT_WEBHOOK_SECRET`).
+
+The webhook fires for EVERY message — your server filters out the sender, dedupes per conversation, and respects user notification preferences.
+
+---
+
+## 8. Webhook signature verification
+
+```ts
+import crypto from "crypto";
+
+app.use("/webhook/cometchat", (req, res, next) => {
+  const signature = req.header("x-cometchat-signature");
+  const expected = crypto
+    .createHmac("sha256", process.env.COMETCHAT_WEBHOOK_SECRET!)
+    .update(JSON.stringify(req.body))
+    .digest("hex");
+  if (signature !== expected) return res.status(401).send({ error: "invalid signature" });
+  next();
+});
+```
+
+Without this, anyone with your endpoint URL can flood your users with fake notifications.
+
+---
+
+## 9. Browser support matrix + iOS PWA caveat
+
+| Browser | Web Push | Notification while closed | Notes |
+|---|---|---|---|
+| Chrome desktop | ✓ | ✓ if Chrome process alive | Service Worker terminates after ~30s idle |
+| Edge desktop | ✓ | ✓ | Same as Chrome |
+| Firefox desktop | ✓ | ✓ | Slightly more SW survival |
+| Safari 16+ desktop | ✓ | ✓ if Safari running | macOS 13+ |
+| Safari 16.4+ iOS | ✓ | **Only when added to Home Screen as PWA** | Critical caveat |
+| Chrome mobile | ✓ | ✓ | Aggressive throttling on Android |
+| Edge mobile | ✓ | ✓ | Same as Chrome mobile |
+
+**iOS PWA-only requirement:** iOS 16.4+ supports Web Push, but ONLY for sites added to the Home Screen as a PWA. Safari-the-browser-app does NOT receive Web Push. To unlock iOS Web Push:
+
+1. App must have a `manifest.json` (PWA manifest)
+2. User must use Safari → Share → "Add to Home Screen"
+3. Subsequent push subscriptions and notifications work as expected
+
+This is a real production constraint. The skill detects whether the project ships a `manifest.json` and warns if not.
+
+---
+
+## 10. Framework-specific Service Worker registration
+
+### Vite / React (CRA)
+
+`public/sw.js` is served from `/sw.js`. `register("/sw.js")` works directly.
+
+### Next.js (App Router)
+
+Service Workers + Next.js have a known gotcha: the SW can't be inside `app/` because Next handles those routes. Place it in `public/sw.js` and serve from `/sw.js`. Register from a `"use client"` component that runs after hydration.
+
+### Next.js (Pages Router)
+
+Same — `public/sw.js`.
+
+### React Router
+
+`public/sw.js` works. If using SSR (loaders), the SW registration code must be guarded by `typeof window !== "undefined"`.
+
+### Astro
+
+Place the SW at `public/sw.js`. Register from a `client:only="react"` island.
+
+The framework-specific patterns skills cover the SSR guards in detail.
+
+---
+
+## 11. HTTPS requirement
+
+Service Workers + Push API both require HTTPS (or `localhost` for dev). The skill detects the dev server protocol and warns:
+
+```
+⚠️  Web Push requires HTTPS or localhost. Your dev server is running on http://192.168.x.x.
+   Web Push subscriptions will fail. Either:
+   - Use http://localhost (Chrome/Firefox/Safari all allow Push API on localhost), or
+   - Set up HTTPS dev (mkcert, ngrok, or Vite's --https flag)
+```
+
+For production, the Vercel / Netlify / Cloudflare default deploys are HTTPS — no extra work.
+
+---
+
+## 12. Anti-patterns
+
+1. **Calling `Notification.requestPermission()` on page load.** Browsers reject this. Wire to a user-clicked "Enable notifications" button.
+2. **Sending the Auth Key in push payloads.** Push payloads are visible in the SW; never include credentials. Use the user's UID as a key into your server's session store.
+3. **Missing webhook signature verification.** Without HMAC verification, anyone with the URL can spoof notifications.
+4. **Showing notifications even when the chat tab is open.** Check `clients.matchAll()` from the SW and skip if the user already has the chat focused.
+5. **Skipping the iOS PWA warning.** iOS users will silently get nothing. The skill explicitly tells them to "Add to Home Screen."
+6. **Service Worker registered before login completes.** Race conditions where the subscription exists but the server doesn't know whose UID it belongs to. Register from inside the auth state effect.
+7. **Forgetting subscription cleanup on logout.** The previous user's subscription keeps notifying them with the new user's messages. Call `subscription.unsubscribe()` and DELETE the server record on logout.
+
+---
+
+## 13. Logout cleanup
+
+```ts
+async function unsubscribeWebPush(uid: string): Promise<void> {
+  const reg = await navigator.serviceWorker.getRegistration();
+  if (!reg) return;
+  const subscription = await reg.pushManager.getSubscription();
+  if (!subscription) return;
+
+  await fetch("/api/push/unsubscribe", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ uid, subscription }),
+  });
+  await subscription.unsubscribe();
+}
+```
+
+Call this from your logout flow before `CometChat.logout()`.
+
+---
+
+## 14. Verification checklist
+
+- [ ] `public/sw.js` (or framework equivalent) exists and listens for `push` + `notificationclick` events
+- [ ] VAPID public key in client env vars (correct framework prefix)
+- [ ] VAPID private key in server env, NOT client
+- [ ] `Notification.requestPermission()` triggered from a user gesture, not page load
+- [ ] Push subscription registered AFTER login resolves
+- [ ] Subscription POSTed to your push server, keyed by CometChat UID
+- [ ] CometChat dashboard webhook configured for `Message sent` events
+- [ ] Webhook signature verification on the push server (HMAC SHA256)
+- [ ] Notifications dedupe per conversation via `tag` field
+- [ ] `notificationclick` focuses existing tab via `clients.matchAll` OR opens new tab
+- [ ] Foreground tab does NOT show notifications (check tab focus before `showNotification`)
+- [ ] Logout flow calls `subscription.unsubscribe()` and deletes server record
+- [ ] HTTPS or localhost only (warned otherwise)
+- [ ] `manifest.json` shipped if iOS users are expected (PWA caveat)
+- [ ] Server cleanup of dead subscriptions on 410 response
+
+---
+
+## 15. Pointers
+
+- `cometchat-react-calls/references/voip-and-web-push.md` — Web Push for incoming calls (overlap; both can coexist on the same SW)
+- `cometchat-{react,nextjs,react-router,astro}-patterns` — framework-specific SSR handling
+- `cometchat-production` — auth tokens, security
+- `cometchat-troubleshooting` — Web Push debugging (chrome://serviceworker-internals, Firefox about:debugging)

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

@@ -3,7 +3,7 @@ name: cometchat-react-router-patterns
 description: "Framework-specific patterns for integrating CometChat React UI Kit v6 into React Router projects (v6 library mode and v7 framework mode). Covers SSR prevention, routing patterns, outlet nesting, and common pitfalls."
 license: "MIT"
 compatibility: "Node.js >=18; React >=18; react-router-dom ^6 or react-router ^7; @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"