@cometchat/skills 4.0.0 → 4.2.0

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

@@ -0,0 +1,403 @@
+---
+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.
+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"
+metadata:
+  author: "CometChat"
+  version: "4.0.0"
+  tags: "cometchat angular web push notifications service-worker swpush ngsw vapid universal ssr"
+---
+
+## 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.
+
+**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
+
+**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
+
+---
+
+## 1. Architecture (same as web)
+
+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.
+
+---
+
+## 2. Add @angular/service-worker
+
+```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 {}
+```
+
+---
+
+## 3. ngsw-config.json — minimal config for chat push
+
+The default config caches assets for offline-first PWAs. For chat push, you mostly need the data-sources for live API calls:
+
+```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"
+      }
+    }
+  ]
+}
+```
+
+**Don't cache CometChat API responses** — they're real-time. The freshness strategy with `maxAge: "0d"` effectively disables caching.
+
+---
+
+## 4. SwPush registration
+
+```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);
+    });
+  }
+
+  async subscribe(uid: string): Promise<void> {
+    if (!this.swPush.isEnabled) {
+      console.warn("SwPush not enabled — Service Worker not registered or not supported");
+      return;
+    }
+
+    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);
+    }
+  }
+
+  async unsubscribe(uid: string): Promise<void> {
+    if (!this.swPush.isEnabled) return;
+    const subscription = await this.swPush.subscription.toPromise();
+    if (!subscription) return;
+
+    await fetch("/api/push/unsubscribe", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ uid, subscription }),
+    });
+    await this.swPush.unsubscribe();
+  }
+}
+```
+
+**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.
+
+---
+
+## 5. Wire into the auth flow
+
+```ts
+// services/auth.service.ts (or wherever login happens)
+import { PushService } from "./push.service";
+
+@Injectable({ providedIn: "root" })
+export class AuthService {
+  constructor(private pushService: PushService) {}
+
+  async loginAndEnableChat(uid: string): Promise<void> {
+    await CometChatUIKit.login(uid);
+    // Don't auto-subscribe to push — let the user opt in via a button
+  }
+
+  async logout(uid: string): Promise<void> {
+    await this.pushService.unsubscribe(uid);     // CRITICAL — clean up before SDK logout
+    await CometChatUIKit.logout();
+  }
+}
+```
+
+---
+
+## 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;
+
+  constructor(private pushService: PushService, private auth: AuthService) {}
+
+  async enable() {
+    const user = await CometChatUIKit.getLoggedInUser();
+    if (!user) return;
+    await this.pushService.subscribe(user.uid);
+    this.enabled = true;
+  }
+}
+```
+
+Mount this somewhere visible — chat header, settings page, or a one-time onboarding card.
+
+---
+
+## 7. Service Worker push event handler
+
+`@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.
+
+**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.
+
+Two paths:
+
+### Path A — Use the payload shape `ngsw-worker.js` expects
+
+The Angular SW expects this payload shape:
+
+```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"
+    }
+  }
+}
+```
+
+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
+
+Same as `cometchat-react-push` Section 7 — configure in CometChat dashboard, point at your push server, copy the signing secret.
+
+---
+
+## 10. Angular Universal (SSR) considerations
+
+If your app uses Angular Universal:
+
+```ts
+// services/push.service.ts
+import { isPlatformBrowser } from "@angular/common";
+import { Inject, PLATFORM_ID } from "@angular/core";
+
+@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(/* ... */);
+  }
+
+  async subscribe(uid: string): Promise<void> {
+    if (!isPlatformBrowser(this.platformId)) return;
+    if (!this.swPush.isEnabled) return;
+    // ...
+  }
+}
+```
+
+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.
+
+---
+
+## 11. iOS Safari 16.4+ PWA-only caveat
+
+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:
+
+```json
+{
+  "name": "Your App",
+  "short_name": "YourApp",
+  "theme_color": "#1976d2",
+  "background_color": "#fafafa",
+  "display": "standalone",
+  "start_url": "/",
+  "icons": [/* ... */]
+}
+```
+
+iOS users must use Safari → Share → "Add to Home Screen" once for Web Push to work.
+
+---
+
+## 12. HTTPS requirement
+
+Service Workers + Push API both require HTTPS (or `localhost`). `ng serve --ssl` works for local HTTPS dev.
+
+For production: Vercel / Netlify / Cloudflare Pages / Firebase Hosting all default to HTTPS.
+
+---
+
+## 13. Build + deploy
+
+`@angular/service-worker` generates `ngsw-worker.js` at build time:
+
+```bash
+ng build --configuration production
+```
+
+Output: `dist/your-app/ngsw-worker.js` + `dist/your-app/ngsw.json` (the SW config baked in).
+
+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.
+
+---
+
+## 14. 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.
+
+---
+
+## 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
+- [ ] HTTPS or localhost only
+- [ ] `manifest.webmanifest` present for iOS PWA support
+- [ ] Angular Universal: `isPlatformBrowser` guards in PushService
+
+---
+
+## 16. 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