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/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.
+```