+-----------------------------------------------------------------------------------------+
|                  Universal Web Push Architecture (Chrome, Safari, Firefox)              |
+-----------------------------------------------------------------------------------------+

[BACKEND SERVER (Node.js / Go)]
  │
  ▼ (Signs payload with VAPID Private Key .p256 via ECDSA)
+-----------------------------------------------------------------+
| DISPATCH WEB PUSH (Standard RFC 8292 / 8291 Web Push Protocol):  |
| - POST to Push Service Endpoint (Apple APNs / Google FCM Edge)  |
| - Includes VAPID Authorization JWT & Encrypted AesGcm Payload!  |
+--------------------------------+--------------------------------+
                                 │
        +------------------------+------------------------+
        | (Target: Safari iOS PWA)                        | (Target: Chrome / Android / Desktop)
        ▼                                                 ▼
+---------------------------------+             +---------------------------------+
| APPLE APNs GATEWAY              |             | GOOGLE FCM / MOZILLA GATEWAY    |
+----------------+----------------+             +----------------+----------------+
                 │                                               │
                 ▼                                               ▼
+-----------------------------------------------------------------+
| CLIENT DEVICE SERVICE WORKER (Background Execution):            |
| 1. 'self.addEventListener("push", ...)' wakes up in background. |
| 2. Decrypts JSON payload -> Calls 'registration.showNotification'|
| 3. User taps alert -> 'notificationclick' navigates to target!  |
+-----------------------------------------------------------------+

+-----------------------------------------------------------------------------------------+
|                  Safari iOS PWA Push Prerequisites                                      |
+-----------------------------------------------------------------------------------------+

1. "ADD TO HOME SCREEN" MANDATORY:
   - Push notifications DO NOT run inside a Safari browser tab on iOS.
   - The user MUST add the web app to their Home Screen via the Share menu.

2. WEB APP MANIFEST ('manifest.json'):
   - Must declare '"display": "standalone"' or '"display": "fullscreen"'.

3. EXPLICIT USER GESTURE:
   - Calling 'Notification.requestPermission()' MUST be triggered by a direct user tap 
     (e.g., clicking a "Enable Order Alerts" button).

4. STRICT NOTIFICATION DISPLAY RULE:
   - When the 'push' event fires in the Service Worker, you MUST call 'showNotification()'.
   - Silent background push without showing a notification will cause iOS to revoke permissions!

# Generate VAPID Key Pair via CLI
npx web-push generate-vapid-keys

// server/pushDispatcher.ts
import webpush from "web-push";

// 1. Configure VAPID Keys
const publicVapidKey = process.env.VAPID_PUBLIC_KEY!;
const privateVapidKey = process.env.VAPID_PRIVATE_KEY!;

webpush.setVapidDetails(
  "mailto:[email protected]", // Contact email required by push gateways!
  publicVapidKey,
  privateVapidKey
);

export interface PushSubscriptionPayload {
  endpoint: string;
  keys: {
    p256dh: string;
    auth: string;
  };
}

export async function sendWebPushNotification(
  subscription: PushSubscriptionPayload,
  title: string,
  body: string,
  targetUrl: string
) {
  const payload = JSON.stringify({
    title,
    body,
    icon: "/icons/icon-192x192.png",
    badge: "/icons/badge-72x72.png",
    data: { url: targetUrl },
  });

  try {
    // 2. Dispatch Cryptographically Signed Web Push
    const response = await webpush.sendNotification(subscription, payload, {
      TTL: 60 * 60 * 24, // 24 Hours Time-To-Live
      urgency: "high",   // Prioritizes instant delivery
    });
    console.log(`[WebPush Sent] HTTP ${response.statusCode}`);
    return { success: true };
  } catch (error: any) {
    if (error.statusCode === 410 || error.statusCode === 404) {
      console.warn("[WebPush Token Dead] Subscription expired or revoked. Delete from DB!");
      // deleteSubscriptionFromDb(subscription.endpoint);
    }
    throw error;
  }
}

// public/sw.js

// 1. Listen for Background Push Event
self.addEventListener("push", (event) => {
  if (!event.data) return;

  const data = event.data.json();
  const title = data.title || "New Notification";
  const options = {
    body: data.body,
    icon: data.icon || "/icons/icon-192x192.png",
    badge: data.badge || "/icons/badge-72x72.png",
    vibrate: [100, 50, 100],
    data: data.data || {}, // Contains deep-link URL: { url: "/orders/101" }
  };

  // MUST show notification immediately on iOS/Safari!
  event.waitUntil(self.registration.showNotification(title, options));
});

// 2. Handle User Clicking the Notification
self.addEventListener("notificationclick", (event) => {
  event.notification.close();

  const targetUrl = event.notification.data?.url || "/";

  event.waitUntil(
    clients.matchAll({ type: "window", includeUncontrolled: true }).then((windowClients) => {
      // If tab is already open, focus it and navigate
      for (const client of windowClients) {
        if (client.url.includes(self.location.origin) && "focus" in client) {
          client.navigate(targetUrl);
          return client.focus();
        }
      }
      // Otherwise open a new window
      if (clients.openWindow) {
        return clients.openWindow(targetUrl);
      }
    })
  );
});

// components/PushSubscriptionButton.tsx
"use client";

import React, { useState } from "react";

function urlBase64ToUint8Array(base64String: string) {
  const padding = "=".repeat((4 - (base64String.length % 4)) % 4);
  const base64 = (base64String + padding).replace(/-/g, "+").replace(/_/g, "/");
  const rawData = window.atob(base64);
  const outputArray = new Uint8Array(rawData.length);
  for (let i = 0; i < rawData.length; ++i) {
    outputArray[i] = rawData.charCodeAt(i);
  }
  return outputArray;
}

export function PushSubscriptionButton({ publicVapidKey }: { publicVapidKey: string }) {
  const [isSubscribed, setIsSubscribed] = useState(false);
  const [loading, setLoading] = useState(false);

  const handleSubscribe = async () => {
    setLoading(true);
    try {
      // 1. Request Permission upon User Gesture
      const permission = await Notification.requestPermission();
      if (permission !== "granted") {
        alert("Notification permission denied!");
        return;
      }

      // 2. Register Service Worker & Subscribe via PushManager
      const registration = await navigator.serviceWorker.register("/sw.js");
      const subscription = await registration.pushManager.subscribe({
        userVisibleOnly: true,
        applicationServerKey: urlBase64ToUint8Array(publicVapidKey),
      });

      // 3. Send Subscription to Backend Database
      await fetch("/api/push/subscribe", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(subscription),
      });

      setIsSubscribed(true);
    } catch (err) {
      console.error("Failed to subscribe to Web Push", err);
    } finally {
      setLoading(false);
    }
  };

  return (
    <button
      onClick={handleSubscribe}
      disabled={loading || isSubscribed}
      className={`px-6 py-3 rounded-xl font-bold text-white transition ${
        isSubscribed ? "bg-green-600" : "bg-red-600 hover:bg-red-700"
      }`}
    >
      {isSubscribed ? "✅ Push Notifications Enabled" : "🔔 Enable Push Alerts"}
    </button>
  );
}

       +-------------------------------------------------------------+
       |             End-to-End Push Delivery Latency (ms)           |
       +-------------------------------------------------------------+
 Chrome Desktop / Android (FCM Gateway)| = [450 ms]
 Safari iOS Home Screen PWA (APNs Gate)| = [680 ms]
 Safari Desktop macOS Gateway          | = [520 ms]
                                       +-------------------------------------+
                                       0ms    250ms   500ms   750ms   1000ms