@cometchat/skills 4.3.0 → 4.4.1

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

@@ -1,403 +1,389 @@
 ---
 name: cometchat-angular-push
-description: Push notifications for CometChat Angular UI Kit v4 in Angular 12-15 projects. Web doesn't have native push — covers @angular/service-worker setup, ngsw-config.json, SwPush subscription, server-side webhook to send pushes, click-through routing via Angular Router, Angular Universal SSR considerations, and HTTPS requirements.
+description: Push notifications for CometChat Angular UI Kit v5 (@cometchat/chat-uikit-angular@5) — web push via Firebase Cloud Messaging (FCM) + the CometChat Notifications API. Covers dashboard FCM provider setup, the firebase-messaging-sw.js service worker, Notification permission, getting the FCM token, registering it with CometChatNotifications.registerPushToken + PushPlatforms.FCM_WEB AFTER login, an Angular PushService, environment config, foreground vs background handling, click-through routing, and logout cleanup.
 license: "MIT"
-compatibility: "Angular 12-15 (LTS focus on 15); @angular/service-worker (matched to Angular major); Web Push API (Chrome 50+, Firefox 44+, Edge 17+, Safari 16+ desktop, Safari 16.4+ iOS PWA-only); HTTPS required"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
+compatibility: "Angular >=17 <22; @cometchat/chat-uikit-angular ^5.0; @cometchat/chat-sdk-javascript ^4.1"
 metadata:
   author: "CometChat"
   version: "4.0.0"
-  tags: "cometchat angular web push notifications service-worker swpush ngsw vapid universal ssr"
+  tags: "cometchat angular web push notifications fcm firebase service-worker registerPushToken PushPlatforms notifications-api standalone v5"
 ---
 
 ## Purpose
 
-Web Push for Angular CometChat integrations. Angular's `@angular/service-worker` package provides `SwPush` — a thin wrapper over the Push API — that integrates with Angular's DI tree and Router, so it's the recommended path over hand-rolled Service Workers.
+Web push for CometChat **Angular UI Kit v5** (`@cometchat/chat-uikit-angular@5`). On the web, CometChat push runs through **Firebase Cloud Messaging (FCM)** plus the **CometChat Notifications API** — CometChat hosts the send path. You do NOT build your own push server or webhook for the basic flow: configure an FCM provider in the CometChat dashboard, register the browser's FCM token with `CometChatNotifications.registerPushToken(...)`, and CometChat delivers a push whenever a message arrives for that user.
 
-**Read these other skills first:**
-- `cometchat-angular-core` — UIKitSettingsBuilder, login order
-- `cometchat-angular-patterns` — module setup
-- `cometchat-react-push` — same Web Push spec, React-flavored explanation; shared concepts (VAPID, server-side webhook, iOS PWA caveat) covered there in depth
+This is the v5 (standalone, Angular 17–21) rewrite. The previous v4 skill used `@angular/service-worker` + `SwPush` + a self-hosted VAPID web-push server + a CometChat webhook. **That hand-rolled path is replaced** — v5 uses FCM end-to-end through the CometChat Notifications API, which is the documented, supported web-push path.
 
-**Ground truth:**
-- `@angular/service-worker` — https://angular.io/guide/service-worker-intro
-- `SwPush` API — https://angular.io/api/service-worker/SwPush
-- Web Push spec — https://datatracker.ietf.org/doc/html/rfc8030
+**Read these skills first:**
+- `cometchat-angular-core` — `UIKitSettingsBuilder` init, Promise-based `login(uid)` (bare string), `loggedInUser$`, environment config. Push registration hangs off the same login lifecycle.
+- `cometchat-react-push` is the React sibling for the *self-hosted* Web Push model; the FCM + `CometChatNotifications` plumbing in THIS skill is the shared web SDK API and is the recommended path for both. Where they differ, this skill wins for Angular.
+- `cometchat-angular-production` — server-minted auth tokens (push registration is tied to the logged-in auth token).
 
----
-
-## 1. Architecture (same as web)
+**Ground truth (verify before relying on any symbol):** **Official docs:** https://www.cometchat.com/docs/notifications/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP).
+- Chat SDK types: `node_modules/@cometchat/chat-sdk-javascript/CometChat.d.ts` — `CometChatNotifications`, `PushPlatforms`.
+- FCM (web): https://firebase.google.com/docs/cloud-messaging/js/client
+- CometChat dashboard → **Notifications** → **Push Notifications** (FCM provider config).
 
-Same shape as `cometchat-react-push`: client SW + push server + CometChat webhook. Angular's `SwPush` is the client-side primitive; everything else is the same.
+> The Chat SDK is `@cometchat/chat-sdk-javascript@^4.1`. The web push API documented below is its **real** notification API — `CometChatNotifications.registerPushToken`, `PushPlatforms.FCM_WEB`, `CometChatNotifications.unregisterPushToken`. Do not substitute mobile-only symbols (APNs, FCM_ANDROID, etc.) — the only web platform enum value is `FCM_WEB`.
 
 ---
 
-## 2. Add @angular/service-worker
+## 1. Architecture
 
-```bash
-ng add @angular/service-worker
 ```
-
-This:
-- Adds `@angular/service-worker` to dependencies
-- Creates `ngsw-config.json` at project root
-- Imports `ServiceWorkerModule.register('ngsw-worker.js', ...)` in `AppModule`
-- Sets `serviceWorker: true` in `angular.json` build options
-
-Verify in `app.module.ts`:
-
-```ts
-@NgModule({
-  imports: [
-    BrowserModule,
-    ServiceWorkerModule.register('ngsw-worker.js', {
-      enabled: !isDevMode(),                              // SW disabled in dev mode by default
-      registrationStrategy: 'registerWhenStable:30000',
-    }),
-  ],
-})
-export class AppModule {}
+Browser (your Angular app)
+  ├── Firebase JS SDK (firebase/messaging)  — gets the FCM registration token
+  ├── firebase-messaging-sw.js              — service worker; receives background push
+  └── Notification permission               — granted by the user
+
+CometChat backend
+  ├── FCM provider config (server key / service account)  ← set in dashboard
+  └── Notifications service — sends an FCM push to the user's registered token(s)
+                              whenever a message arrives for them
+
+Your Angular code
+  └── After login → get FCM token → CometChatNotifications.registerPushToken(token, FCM_WEB)
 ```
 
+You own: the Firebase project, the service worker file, the permission prompt, token registration after login, and token cleanup on logout. CometChat owns the actual send. No self-hosted push server, no VAPID web-push library, no CometChat webhook for the basic flow.
+
 ---
 
-## 3. ngsw-config.json — minimal config for chat push
+## 2. Dashboard — enable the FCM push provider (one-time)
 
-The default config caches assets for offline-first PWAs. For chat push, you mostly need the data-sources for live API calls:
+In the CometChat dashboard:
 
-```json
-{
-  "$schema": "./node_modules/@angular/service-worker/config/schema.json",
-  "index": "/index.html",
-  "assetGroups": [
-    {
-      "name": "app",
-      "installMode": "prefetch",
-      "resources": {
-        "files": ["/favicon.ico", "/index.html", "/manifest.webmanifest", "/*.css", "/*.js"]
-      }
-    },
-    {
-      "name": "assets",
-      "installMode": "lazy",
-      "updateMode": "prefetch",
-      "resources": {
-        "files": ["/assets/**", "/*.(svg|cur|jpg|jpeg|png|apng|webp|avif|gif|otf|ttf|woff|woff2)"]
-      }
-    }
-  ],
-  "dataGroups": [
-    {
-      "name": "cometchat-api",
-      "urls": ["https://api-*.cometchat.io/**"],
-      "cacheConfig": {
-        "maxSize": 100,
-        "maxAge": "0d",
-        "strategy": "freshness"
-      }
-    }
-  ]
-}
-```
+1. **Notifications** → **Push Notifications** → enable.
+2. Add a **provider** of type **FCM**.
+3. Supply your Firebase credentials. Modern FCM (HTTP v1) wants the **service-account JSON** (from Firebase Console → Project settings → Service accounts → Generate new private key). Older configs accept the legacy **Server Key** + **Sender ID** (Cloud Messaging tab). Match whatever the dashboard's FCM form currently asks for.
+4. Note the **Provider ID** you assign (default is `default`). You pass this same string as the third arg to `registerPushToken` if you used a non-default provider.
 
-**Don't cache CometChat API responses** — they're real-time. The freshness strategy with `maxAge: "0d"` effectively disables caching.
+The Firebase **web app config** (`apiKey`, `authDomain`, `projectId`, `messagingSenderId`, `appId`) and the **VAPID key pair** (Firebase Console → Cloud Messaging → Web configuration → "Web Push certificates") are client-side — they go in `environment.ts` (§4). The service-account JSON / Server Key is **server-side only** — it lives in the CometChat dashboard, never in your Angular bundle.
 
 ---
 
-## 4. SwPush registration
+## 3. Install Firebase + add the service worker
 
-```ts
-// services/push.service.ts
-import { Injectable } from "@angular/core";
-import { SwPush } from "@angular/service-worker";
-import { Router } from "@angular/router";
-import { environment } from "../../environments/environment";
-
-@Injectable({ providedIn: "root" })
-export class PushService {
-  constructor(private swPush: SwPush, private router: Router) {
-    // Listen for notification clicks — fired when user taps a push notification
-    this.swPush.notificationClicks.subscribe(({ notification }) => {
-      const data = notification.data;
-      const targetUrl = data.receiverType === "group"
-        ? `/messages/group/${data.conversationId}`
-        : `/messages/user/${data.senderUid}`;
-      this.router.navigateByUrl(targetUrl);
-    });
-  }
+```bash
+npm install firebase
+```
 
-  async subscribe(uid: string): Promise<void> {
-    if (!this.swPush.isEnabled) {
-      console.warn("SwPush not enabled — Service Worker not registered or not supported");
-      return;
-    }
+> Do **not** use `@angular/service-worker` / `SwPush` for CometChat web push — FCM ships its own service worker contract (`firebase-messaging-sw.js`) and the Firebase JS SDK manages the token. The v4 `ngsw` path is gone.
 
-    try {
-      const subscription = await this.swPush.requestSubscription({
-        serverPublicKey: environment.vapidPublic,
-      });
-
-      // Send to YOUR push server, keyed by uid
-      await fetch("/api/push/subscribe", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ uid, subscription }),
-      });
-    } catch (err) {
-      // User denied permission, or push not supported
-      console.warn("Web Push subscription failed:", err);
-    }
-  }
+### `src/firebase-messaging-sw.js`
 
-  async unsubscribe(uid: string): Promise<void> {
-    if (!this.swPush.isEnabled) return;
-    const subscription = await this.swPush.subscription.toPromise();
-    if (!subscription) return;
+This file MUST be served from the origin root (`/firebase-messaging-sw.js`) — `firebase.messaging()` registers it by that exact path. Add it as an Angular asset so the build copies it to the output root.
 
-    await fetch("/api/push/unsubscribe", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ uid, subscription }),
-    });
-    await this.swPush.unsubscribe();
-  }
-}
-```
+```js
+// src/firebase-messaging-sw.js
+// Loaded by the browser as a service worker — runs OUTSIDE Angular.
+// Use the compat builds; ES module imports are not available in classic SWs.
+importScripts("https://www.gstatic.com/firebasejs/10.12.0/firebase-app-compat.js");
+importScripts("https://www.gstatic.com/firebasejs/10.12.0/firebase-messaging-compat.js");
 
-**Permission gesture rule:** `requestSubscription` triggers the browser's permission prompt. Browsers require this in response to a user gesture (click). Don't call this from `OnInit` — wire it to a button click.
+firebase.initializeApp({
+  apiKey: "YOUR_FIREBASE_API_KEY",
+  authDomain: "YOUR_PROJECT.firebaseapp.com",
+  projectId: "YOUR_PROJECT_ID",
+  messagingSenderId: "YOUR_SENDER_ID",
+  appId: "YOUR_APP_ID",
+});
 
----
+const messaging = firebase.messaging();
+
+// Background handler — fires when the tab is closed/backgrounded.
+messaging.onBackgroundMessage((payload) => {
+  const title = payload.notification?.title ?? payload.data?.senderName ?? "New message";
+  self.registration.showNotification(title, {
+    body: payload.notification?.body ?? payload.data?.text ?? "",
+    icon: payload.notification?.icon ?? "/assets/chat-icon.png",
+    tag: payload.data?.conversationId,          // dedupe per conversation
+    data: payload.data ?? {},                   // carried into notificationclick
+  });
+});
 
-## 5. Wire into the auth flow
+// Click-through — focus an open tab or open a new one, deep-linking to the thread.
+self.addEventListener("notificationclick", (event) => {
+  event.notification.close();
+  const data = event.notification.data || {};
+  const url = data.receiverType === "group"
+    ? `/messages/group/${data.conversationId}`
+    : `/messages/user/${data.sender}`;
+  event.waitUntil(
+    clients.matchAll({ type: "window", includeUncontrolled: true }).then((wins) => {
+      for (const w of wins) {
+        if ("focus" in w) { w.focus(); w.postMessage({ type: "open_conversation", ...data }); return; }
+      }
+      return clients.openWindow(url);
+    })
+  );
+});
+```
 
-```ts
-// services/auth.service.ts (or wherever login happens)
-import { PushService } from "./push.service";
+> The `payload.data` keys (`conversationId`, `sender`, `receiverType`, `text`, `senderName`) are whatever CometChat's FCM payload carries — confirm the exact field names against a real push in DevTools → Application → Service Workers, and adjust. Do not assume; CometChat's data-payload shape is the source of truth.
 
-@Injectable({ providedIn: "root" })
-export class AuthService {
-  constructor(private pushService: PushService) {}
+### Register the SW file as an Angular asset
 
-  async loginAndEnableChat(uid: string): Promise<void> {
-    await CometChatUIKit.login(uid);
-    // Don't auto-subscribe to push — let the user opt in via a button
-  }
+`angular.json` → `projects.<app>.architect.build.options.assets` (alongside the mandatory CometChat assets glob from `cometchat-angular-core` §2):
 
-  async logout(uid: string): Promise<void> {
-    await this.pushService.unsubscribe(uid);     // CRITICAL — clean up before SDK logout
-    await CometChatUIKit.logout();
-  }
-}
+```json
+{ "glob": "firebase-messaging-sw.js", "input": "src", "output": "/" }
 ```
 
----
+Build output then serves it at `/firebase-messaging-sw.js`. Verify after `ng build` that the file is at the dist root, not under `assets/`.
 
-## 6. "Enable notifications" button
+---
 
-```ts
-// components/notification-prompt.component.ts
-@Component({
-  selector: "app-notification-prompt",
-  template: `
-    <button (click)="enable()" *ngIf="!enabled">
-      Enable notifications
-    </button>
-  `,
-})
-export class NotificationPromptComponent {
-  enabled = false;
+## 4. Environment config
 
-  constructor(private pushService: PushService, private auth: AuthService) {}
+Angular has no `process.env`. The Firebase web config + VAPID key live in `src/environments/environment.ts` (these are publishable client values — `apiKey` here is a Firebase identifier, not a secret):
 
-  async enable() {
-    const user = await CometChatUIKit.getLoggedInUser();
-    if (!user) return;
-    await this.pushService.subscribe(user.uid);
-    this.enabled = true;
-  }
-}
+```typescript
+// src/environments/environment.ts
+export const environment = {
+  production: false,
+  cometchat: {
+    appId: "YOUR_APP_ID",
+    region: "us",                 // "us" | "eu" | "in"
+    authKey: "YOUR_AUTH_KEY",     // dev only
+  },
+  firebase: {
+    apiKey: "YOUR_FIREBASE_API_KEY",
+    authDomain: "YOUR_PROJECT.firebaseapp.com",
+    projectId: "YOUR_PROJECT_ID",
+    messagingSenderId: "YOUR_SENDER_ID",
+    appId: "YOUR_FIREBASE_APP_ID",
+    vapidKey: "YOUR_WEB_PUSH_CERTIFICATE_KEY_PAIR",   // FCM → Web configuration
+  },
+  // Provider ID set in the dashboard (§2). Omit / "default" if you didn't change it.
+  cometchatPushProviderId: "default",
+};
 ```
 
-Mount this somewhere visible — chat header, settings page, or a one-time onboarding card.
+Keep the same shape in `environment.prod.ts`. The CometChat **REST API Key** and the Firebase **service-account JSON** never appear in any `src/` file — Angular ships `src/` to the client.
 
 ---
 
-## 7. Service Worker push event handler
+## 5. PushService — get the FCM token and register it
 
-`@angular/service-worker` ships its own `ngsw-worker.js` that handles push events automatically — when a push arrives, it calls `ServiceWorkerRegistration.showNotification` with the push payload.
+```typescript
+// src/app/services/push.service.ts
+import { Injectable, Inject, PLATFORM_ID } from "@angular/core";
+import { isPlatformBrowser } from "@angular/common";
+import { Router } from "@angular/router";
+import { initializeApp } from "firebase/app";
+import { getMessaging, getToken, onMessage, deleteToken, Messaging } from "firebase/messaging";
+import { CometChatNotifications } from "@cometchat/chat-sdk-javascript";
+import { environment } from "../../environments/environment";
 
-**However**, the default behavior shows the entire payload as the notification body. For chat, you want a custom UI: sender name as title, preview as body, conversation tag for dedup.
+@Injectable({ providedIn: "root" })
+export class PushService {
+  private messaging: Messaging | null = null;
 
-Two paths:
+  constructor(
+    private router: Router,
+    @Inject(PLATFORM_ID) private platformId: object,
+  ) {
+    if (!isPlatformBrowser(this.platformId)) return;       // SSR / prerender guard
+    if (!("serviceWorker" in navigator) || !("Notification" in window)) return;
+
+    const app = initializeApp(environment.firebase);
+    this.messaging = getMessaging(app);
+
+    // Foreground messages: the SW background handler does NOT fire while the tab
+    // is focused. Decide your own UX here (toast, in-app banner, or a manual
+    // Notification). Don't double-notify.
+    onMessage(this.messaging, (payload) => {
+      // e.g. show an in-app toast; skip an OS notification if the chat is focused.
+      console.debug("Foreground push:", payload);
+    });
 
-### Path A — Use the payload shape `ngsw-worker.js` expects
+    // SW → app messages from notificationclick (deep-link into the thread).
+    navigator.serviceWorker?.addEventListener("message", (event: MessageEvent) => {
+      const d = event.data;
+      if (d?.type === "open_conversation") {
+        const url = d.receiverType === "group"
+          ? `/messages/group/${d.conversationId}`
+          : `/messages/user/${d.sender}`;
+        this.router.navigateByUrl(url);
+      }
+    });
+  }
 
-The Angular SW expects this payload shape:
+  /** Call AFTER CometChatUIKit.login(uid) resolves. Must be user-gesture-initiated
+   *  (Notification.requestPermission requires it on most browsers). */
+  async register(): Promise<void> {
+    if (!this.messaging) return;
+
+    const permission = await Notification.requestPermission();
+    if (permission !== "granted") return;                  // user declined — bail quietly
+
+    // The Firebase SDK registers /firebase-messaging-sw.js itself; pass the
+    // VAPID key from the FCM Web configuration.
+    const fcmToken = await getToken(this.messaging, { vapidKey: environment.firebase.vapidKey });
+    if (!fcmToken) return;
+
+    // The ONE call that wires the browser into CometChat's push pipeline.
+    await CometChatNotifications.registerPushToken(
+      fcmToken,
+      CometChatNotifications.PushPlatforms.FCM_WEB,   // = "fcm_web" — the only web value
+      environment.cometchatPushProviderId,                     // optional; defaults to "default"
+    );
+  }
 
-```json
-{
-  "notification": {
-    "title": "Alice",
-    "body": "Hi there",
-    "icon": "/avatars/alice.png",
-    "tag": "chat-conversation-123",
-    "data": {
-      "conversationId": "conversation-123",
-      "senderUid": "cometchat-uid-1",
-      "receiverType": "user"
+  /** Call BEFORE CometChatUIKit.logout(). Order matters — registration is tied
+   *  to the current auth token, which logout invalidates. */
+  async unregister(): Promise<void> {
+    if (!this.messaging) return;
+    try {
+      await CometChatNotifications.unregisterPushToken();   // clears CometChat-side
+    } finally {
+      await deleteToken(this.messaging).catch(() => {});              // clears the FCM token too
     }
   }
 }
 ```
 
-Your push server sends this exact shape. `ngsw-worker.js` extracts `notification` and shows it.
-
-### Path B — Custom Service Worker
-
-If you need behavior beyond what Angular's SW provides (e.g. checking if the chat tab is focused before notifying), eject from `ngsw-worker.js` and write a custom SW. Heavier maintenance — only needed for advanced cases.
-
----
-
-## 8. Server-side push send
-
-Same shape as `cometchat-react-push` Section 6. Different payload shape — Angular SW expects the wrapped `{ notification: {...} }` form:
-
-```ts
-const payload = JSON.stringify({
-  notification: {
-    title: sender.name,
-    body: truncate(data.text, 80),
-    icon: sender.avatar ?? "/icons/chat.png",
-    tag: `chat-${receiver}`,
-    data: {
-      conversationId: receiver,
-      senderUid: sender.uid,
-      receiverType: data.entityType,
-    },
-  },
-});
-```
-
-The webhook setup, signature verification, and dead-subscription cleanup are identical to the React version.
-
----
-
-## 9. CometChat webhook setup
+**API notes (verified against the v5 Chat SDK `.d.ts`):**
+- `CometChatNotifications.registerPushToken(pushToken: string, platform: PushPlatforms, providerId?: string): Promise<string>` — registers the FCM token against the **current logged-in auth token**. Third arg is optional and defaults to `"default"`.
+- `PushPlatforms.FCM_WEB = "fcm_web"` — the **only** web platform value in the enum. There is no web APNs/Android variant.
+- `CometChatNotifications.unregisterPushToken(): Promise<string>` — unregisters the token for the current auth token. Takes **no arguments**.
+- Both are static members of the **top-level** `CometChatNotifications` class — import it directly: `import { CometChatNotifications } from "@cometchat/chat-sdk-javascript"`. It is NOT nested under the `CometChat` namespace (there is no `CometChat.CometChatNotifications`).
+- `PushPlatforms` is itself a top-level export of the SDK; the enum is also re-exposed as a static on the class (`CometChatNotifications.PushPlatforms`). Either `PushPlatforms.FCM_WEB` (with a top-level import) or `CometChatNotifications.PushPlatforms.FCM_WEB` is valid — both resolve to `"fcm_web"`.
 
-Same as `cometchat-react-push` Section 7 — configure in CometChat dashboard, point at your push server, copy the signing secret.
+> Legacy note: the SDK also exposes the deprecated `CometChat.registerTokenForPushNotification(token, settings?)`. It predates the Notifications service. Do **not** use it for new v5 integrations — `CometChatNotifications.registerPushToken` is the current API.
 
 ---
 
-## 10. Angular Universal (SSR) considerations
+## 6. Wire into the login lifecycle
 
-If your app uses Angular Universal:
+Registration MUST happen **after** `login(uid)` resolves — `registerPushToken` binds the token to the live auth token. (See `cometchat-angular-core` §3–§4 for the init → login order; init resolves in `main.ts` before `bootstrapApplication` — the v5 canonical path; `APP_INITIALIZER` is an alternative — and login happens in your auth service / route guard.)
 
-```ts
-// services/push.service.ts
-import { isPlatformBrowser } from "@angular/common";
-import { Inject, PLATFORM_ID } from "@angular/core";
+```typescript
+// src/app/services/auth.service.ts
+import { Injectable } from "@angular/core";
+import { CometChatUIKit } from "@cometchat/chat-uikit-angular";
+import { PushService } from "./push.service";
 
 @Injectable({ providedIn: "root" })
-export class PushService {
-  constructor(
-    private swPush: SwPush,
-    private router: Router,
-    @Inject(PLATFORM_ID) private platformId: object,
-  ) {
-    if (!isPlatformBrowser(this.platformId)) return;        // skip on server
-    this.swPush.notificationClicks.subscribe(/* ... */);
+export class AuthService {
+  constructor(private push: PushService) {}
+
+  async login(uid: string): Promise<void> {
+    const existing = CometChatUIKit.getLoggedInUser();      // sync getter, capital "In"
+    if (!existing) {
+      await CometChatUIKit.login(uid);                      // bare string in v5
+    }
+    // Push is opt-in + gesture-gated — do NOT auto-register here.
+    // Call this.push.register() from a button click (see §7).
   }
 
-  async subscribe(uid: string): Promise<void> {
-    if (!isPlatformBrowser(this.platformId)) return;
-    if (!this.swPush.isEnabled) return;
-    // ...
+  async logout(): Promise<void> {
+    await this.push.unregister();                           // CRITICAL: before logout
+    await CometChatUIKit.logout();
   }
 }
 ```
 
-Without these guards, the SSR build crashes at boot with `ReferenceError: ServiceWorkerRegistration is not defined`.
+---
 
-`@angular/service-worker` itself ships with SSR-safe stubs, but downstream code that touches `swPush.subscription` etc. needs guards.
+## 7. "Enable notifications" button (gesture requirement)
 
----
+`Notification.requestPermission()` must be called from a user gesture on most browsers — calling it from `ngOnInit` is silently rejected. Wire `register()` to a click:
 
-## 11. iOS Safari 16.4+ PWA-only caveat
+```typescript
+// src/app/components/enable-push.component.ts
+import { Component } from "@angular/core";
+import { CommonModule } from "@angular/common";
+import { PushService } from "../services/push.service";
+import { CometChatUIKit } from "@cometchat/chat-uikit-angular";
 
-Same as `cometchat-react-push` Section 9 — iOS Web Push works ONLY for sites added to the Home Screen as PWAs. Angular CLI generates `manifest.webmanifest` automatically when you `ng add @angular/pwa`; verify it's present and correct:
+@Component({
+  selector: "app-enable-push",
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <button *ngIf="!enabled" (click)="enable()">Enable notifications</button>
+  `,
+})
+export class EnablePushComponent {
+  enabled = Notification.permission === "granted";
 
-```json
-{
-  "name": "Your App",
-  "short_name": "YourApp",
-  "theme_color": "#1976d2",
-  "background_color": "#fafafa",
-  "display": "standalone",
-  "start_url": "/",
-  "icons": [/* ... */]
+  constructor(private push: PushService) {}
+
+  async enable(): Promise<void> {
+    if (!CometChatUIKit.getLoggedInUser()) return;          // must be logged in first
+    await this.push.register();
+    this.enabled = Notification.permission === "granted";
+  }
 }
 ```
 
-iOS users must use Safari → Share → "Add to Home Screen" once for Web Push to work.
+Mount it in the chat header, a settings page, or a one-time onboarding card.
 
 ---
 
-## 12. HTTPS requirement
+## 8. Foreground vs background
 
-Service Workers + Push API both require HTTPS (or `localhost`). `ng serve --ssl` works for local HTTPS dev.
+- **Background / tab closed:** `onBackgroundMessage` in `firebase-messaging-sw.js` fires; you call `showNotification` (§3).
+- **Foreground / tab focused:** the SW handler does **not** fire. `onMessage` in `PushService` fires instead (§5). Show an in-app toast/banner, or skip entirely if the relevant conversation is already on screen — never both, or the user sees a duplicate. CometChat's UI Kit already updates the message list live when the tab is focused, so a silent foreground handler is often the right call.
 
-For production: Vercel / Netlify / Cloudflare Pages / Firebase Hosting all default to HTTPS.
+---
+
+## 9. Notification permission states
+
+`Notification.permission` is `"default"` (not yet asked), `"granted"`, or `"denied"`. Once `"denied"`, you cannot re-prompt programmatically — the user must change it in browser site settings. Reflect this in the UI: show the enable button only when `permission === "default"`, and a "notifications blocked — enable in browser settings" hint when `"denied"`.
 
 ---
 
-## 13. Build + deploy
+## 10. HTTPS requirement
 
-`@angular/service-worker` generates `ngsw-worker.js` at build time:
+Service Workers, the Push API, and FCM all require **HTTPS** (or `http://localhost` for dev). On a LAN IP or plain `http://`, `getToken` and SW registration fail. Use `ng serve` (localhost is allowed) or `ng serve --ssl` for HTTPS-in-dev. Production hosts (Vercel / Netlify / Cloudflare Pages / Firebase Hosting) are HTTPS by default.
 
-```bash
-ng build --configuration production
-```
+---
 
-Output: `dist/your-app/ngsw-worker.js` + `dist/your-app/ngsw.json` (the SW config baked in).
+## 11. SSR / prerender (Angular Universal)
 
-Deploy these files alongside `index.html`. The SW updates automatically when `ngsw.json` changes (a hash of all included assets); users get the new SW on next page load.
+If the app uses SSR or prerendering, every Firebase/Notification touch must be browser-guarded — the `PushService` constructor already short-circuits with `isPlatformBrowser` (§5). Without it, `initializeApp` / `navigator.serviceWorker` throw `ReferenceError` at server boot. Keep all `firebase/messaging` access behind that guard; never call `register()` from server-rendered code paths.
 
 ---
 
-## 14. Anti-patterns
+## 12. Anti-patterns
 
-1. **Calling `swPush.requestSubscription()` from `ngOnInit`.** Browsers reject permission requests not tied to user gestures. Wire to a button click.
-2. **Subscribing on `OnInit` of a lazy module.** Lazy modules instantiate after navigation; user has already missed pushes during navigation. Subscribe in eager AppModule.
-3. **Sending the Auth Key in push payloads.** Visible in the Service Worker. Use the user's UID as a key into your server.
-4. **Skipping the SSR guard** in Angular Universal projects. SSR boot crashes.
-5. **Not unsubscribing on logout.** Previous user keeps getting notifications for the new user's messages.
-6. **Hardcoding the VAPID public key in `environment.ts`.** It's not secret (it's "public"), but rotate-able is better — read from runtime config.
-7. **Using `*ngIf="enabled"` based on a local boolean** instead of `swPush.subscription` observable. Multi-tab scenarios get out of sync.
+1. **Registering the token before login resolves.** `registerPushToken` ties the token to the current auth token — call it only after `CometChatUIKit.login(uid)` succeeds.
+2. **Calling `Notification.requestPermission()` from `ngOnInit`.** Browsers reject permission requests not tied to a user gesture. Use a clicked button (§7).
+3. **Using `@angular/service-worker` / `SwPush`.** That was the v4 path. v5 web push uses Firebase's own `firebase-messaging-sw.js` + the FCM token — the two SW systems conflict if both register.
+4. **Inventing platform enum values.** The only web value is `PushPlatforms.FCM_WEB` (`"fcm_web"`). There is no `FCM_ANDROID`/`APNS` for web.
+5. **Using the deprecated `registerTokenForPushNotification`.** It predates the Notifications service; use `CometChatNotifications.registerPushToken`.
+6. **Putting the Firebase service-account JSON / CometChat REST API Key in `environment.ts`.** Those are server-only (dashboard). The Firebase web config + VAPID key are the only push values that belong client-side.
+7. **Serving `firebase-messaging-sw.js` from `/assets/`.** It must be at the origin root (`/firebase-messaging-sw.js`) or Firebase can't register it.
+8. **Not unregistering on logout.** The previous user keeps receiving pushes. Call `unregisterPushToken()` (+ `deleteToken`) before `CometChatUIKit.logout()`.
+9. **Double-notifying in the foreground.** `onMessage` and the SW `onBackgroundMessage` are mutually exclusive by tab focus — don't manually `showNotification` from foreground on top of the SW.
+10. **No SSR guard in a Universal app.** `initializeApp` at server boot throws. Guard with `isPlatformBrowser`.
 
 ---
 
-## 15. Verification checklist
-
-- [ ] `@angular/service-worker` installed via `ng add`
-- [ ] `ngsw-config.json` exists and excludes CometChat API from caching
-- [ ] `ServiceWorkerModule.register('ngsw-worker.js', { enabled: !isDevMode() })` in AppModule
-- [ ] `PushService` injects `SwPush`
-- [ ] `swPush.notificationClicks.subscribe` routes to the conversation
-- [ ] VAPID public key in `environment.ts`; private key in server env (NOT client)
-- [ ] Subscribe via a user-clicked button, not OnInit
-- [ ] Subscription registered AFTER login resolves
-- [ ] Logout unsubscribes BEFORE `CometChatUIKit.logout()`
-- [ ] Server sends `{ notification: {...} }` payload shape (Angular SW format)
-- [ ] CometChat dashboard webhook configured + signature verified
+## 13. Verification checklist
+
+- [ ] Dashboard: **Notifications → Push Notifications** enabled with an **FCM** provider; service-account JSON (or Server Key) supplied server-side
+- [ ] `firebase` installed; `firebase-messaging-sw.js` in `src/`, registered as an Angular asset, served at `/firebase-messaging-sw.js` after build
+- [ ] Firebase web config + VAPID key in `environment.ts`; service-account JSON / REST API Key NOT in any `src/` file
+- [ ] `PushService` guards on `isPlatformBrowser` + `"serviceWorker" in navigator`
+- [ ] `Notification.requestPermission()` fired from a user gesture (button), not `ngOnInit`
+- [ ] FCM token fetched via `getToken(messaging, { vapidKey })`
+- [ ] Token registered with `CometChatNotifications.registerPushToken(token, PushPlatforms.FCM_WEB, providerId)` **after** `login(uid)` resolves
+- [ ] `onMessage` foreground handler defined; does not double-notify with the SW
+- [ ] `onBackgroundMessage` + `notificationclick` in the SW deep-link to the conversation
+- [ ] Logout calls `unregisterPushToken()` (+ `deleteToken`) BEFORE `CometChatUIKit.logout()`
 - [ ] HTTPS or localhost only
-- [ ] `manifest.webmanifest` present for iOS PWA support
-- [ ] Angular Universal: `isPlatformBrowser` guards in PushService
+- [ ] SSR projects keep all `firebase/messaging` access behind the browser guard
 
 ---
 
-## 16. Pointers
+## 14. Pointers
 
-- `cometchat-react-push` — sister skill; covers VAPID, server-side webhook, iOS PWA caveat in depth
-- `cometchat-angular-core` — login order
-- `cometchat-angular-patterns` — module setup, lazy loading
-- `cometchat-angular-troubleshooting` — SW registration debugging, ngsw issues
+- `cometchat-angular-core` — init → login order, `loggedInUser$`, environment config
+- `cometchat-angular-production` — server-minted auth tokens (registration binds to the auth token)
+- `cometchat-react-push` — sibling web-push concepts (self-hosted Web Push model; FCM + Notifications API here is the shared, recommended SDK path)
+- `cometchat-angular-troubleshooting` — SW registration / FCM token debugging