From 49c90b929dd3ce31f50f53b9c06cad7d63cf66bf Mon Sep 17 00:00:00 2001
From: Scrum4Me Agent <30029041+madhura68@users.noreply.github.com>
Date: Thu, 7 May 2026 21:22:09 +0200
Subject: [PATCH] ST-cmovs8vxj: docs/patterns/web-push.md pattern-documentatie

Architectuur-diagram, payload-shape, foutcodes, VAPID-config,
iOS-quirks, demo-users blokkade, trigger-voorbeelden (server +
HTTP) en admin-testroute curl-voorbeeld.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/INDEX.md             |   1 +
 docs/patterns/web-push.md | 111 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 112 insertions(+)
 create mode 100644 docs/patterns/web-push.md

diff --git a/docs/INDEX.md b/docs/INDEX.md
index 3c7670c..d391d49 100644
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -80,6 +80,7 @@ Auto-generated on 2026-05-07 from front-matter and headings.
 | [Server Action](./patterns/server-action.md) | active | 2026-05-03 |
 | [Float sort_order (drag-and-drop volgorde)](./patterns/sort-order.md) | active | 2026-05-03 |
 | [Story met UI-component](./patterns/story-with-ui-component.md) | active | 2026-05-03 |
+| [Web Push](./patterns/web-push.md) | active | 2026-05-07 |
 | [Zustand optimistische update + rollback](./patterns/zustand-optimistic.md) | active | 2026-05-03 |
 
 ## Other Docs
diff --git a/docs/patterns/web-push.md b/docs/patterns/web-push.md
new file mode 100644
index 0000000..24c83ff
--- /dev/null
+++ b/docs/patterns/web-push.md
@@ -0,0 +1,111 @@
+---
+title: "Web Push"
+status: active
+audience: [ai-agent, contributor]
+language: nl
+last_updated: 2026-05-07
+when_to_read: "When sending push notifications from the server or MCP layer, or when troubleshooting PWA push on iOS."
+---
+
+# Patroon: Web Push
+
+## Wat & wanneer
+
+Gebruik Web Push voor OS-niveau notificaties die ook verschijnen wanneer de browser-tab gesloten is (b.v. Claude-vragen, sprint-completion). Gebruik het **niet** voor in-app realtime feedback — daarvoor dient de SSE/realtime/notifications-stack (`stores/notifications-store`).
+
+## Architectuur
+
+```
+MCP / cron
+  │
+  ▼
+POST /api/internal/push/send   ← Bearer: INTERNAL_PUSH_SECRET
+  │
+  ▼
+lib/push-server.ts → sendPushToUser(userId, payload)
+  │  • VAPID-check (disabled = warn + return)
+  │  • prisma.pushSubscription.findMany
+  │  • Promise.allSettled(sendOne[])
+  │  • 404/410 → auto-delete stale subscription
+  ▼
+Web Push Service (FCM / APNS)
+  │
+  ▼
+public/sw.js  →  showNotification + notificationclick
+```
+
+## Payload-shape
+
+```ts
+type PushPayload = {
+  title: string   // max 80 tekens
+  body:  string   // max 300 tekens
+  url:   string   // absoluut pad ('/dashboard') of volledige URL
+  tag?:  string   // dedupliceert notificaties met dezelfde tag
+}
+```
+
+## Foutcodes
+
+| Code | Betekenis | Actie |
+|------|-----------|-------|
+| 404 / 410 | Stale endpoint (browser heeft sub verwijderd) | Auto-delete in `sendOne` |
+| 5xx | Tijdelijke fout push-service | Geen automatische retry in v1 — log + swallow |
+| 401 (send-route) | Verkeerd of ontbrekend Bearer-secret | Check `INTERNAL_PUSH_SECRET` |
+| 422 (send-route) | Ongeldige body | Zie payload-shape hierboven |
+| 503 (send-route) | `INTERNAL_PUSH_SECRET` niet geconfigureerd | Zet env-var |
+
+## VAPID-configuratie
+
+Genereer sleutels eenmalig:
+```bash
+npx web-push generate-vapid-keys
+```
+
+Zet in `.env.local`:
+```bash
+NEXT_PUBLIC_VAPID_PUBLIC_KEY="<public key>"
+VAPID_PRIVATE_KEY="<private key>"
+VAPID_SUBJECT="mailto:admin@example.com"
+INTERNAL_PUSH_SECRET="<min 32 chars, openssl rand -base64 32>"
+```
+
+Als de VAPID-envs ontbreken, returnt `sendPushToUser` vroeg met een `console.warn`; de app crasht **niet**.
+
+## iOS-quirks
+
+- Vereist iOS 16.4+ (Safari 16.4).
+- De gebruiker moet de app eerst via **Zet op beginscherm** als PWA installeren. Push werkt niet vanuit een normale Safari-tab.
+- In de EU (iOS 17.4+ na DMA) worden meldingen door Apple beperkt voor alternatieve browser-engines; test op Safari specifiek.
+- `isIOSSafari()` + `!isStandalonePWA()` → `PushToggle` toont de installatie-banner in plaats van een toggle.
+
+## Demo-users
+
+`subscribeToPushAction` controleert `session.isDemo` en returnt zonder schrijven. Demo-gebruikers kunnen zich dus niet aanmelden voor push.
+
+## Triggeren vanuit MCP of server-code
+
+```ts
+// Directe server-aanroep (binnen Next.js):
+import { sendPushToUser } from '@/lib/push-server'
+await sendPushToUser(userId, { title: 'Vraag van Claude', body: question, url: `/products/${productId}` })
+
+// Vanuit MCP / externe service (HTTP):
+await fetch(`${BASE_URL}/api/internal/push/send`, {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${INTERNAL_PUSH_SECRET}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({ userId, payload: { title, body, url } }),
+})
+// 204 = verzonden, 503 = VAPID niet geconfigureerd
+```
+
+## Admin testroute
+
+```bash
+curl -X POST https://<host>/api/internal/push/test-send \
+  -H "Cookie: <admin session cookie>"
+# Vereist ingelogde admin-sessie; stuurt push naar eigen account.
+```