@markwharton/pwa-push 1.5.2 → 2.0.0

package/dist/client.d.ts

@@ -0,0 +1,181 @@
+/**
+ * pwa-push/client - Browser-side push notification utilities
+ *
+ * Includes: subscription management, device ID, IndexedDB storage, service worker renewal
+ */
+import { Result } from '@markwharton/pwa-core/shared';
+import { PushSubscription, SubscriptionRequest, SubscriptionData, PushPermissionState } from './shared';
+/**
+ * Converts a base64 URL-encoded string to a Uint8Array.
+ * Used to convert VAPID public keys for the PushManager API.
+ * Works in both main thread and service worker contexts.
+ * @param base64String - The base64 URL-encoded string to convert
+ * @returns A Uint8Array containing the decoded bytes
+ * @example
+ * const applicationServerKey = urlBase64ToUint8Array(vapidPublicKey);
+ * await registration.pushManager.subscribe({
+ *   userVisibleOnly: true,
+ *   applicationServerKey
+ * });
+ */
+export declare function urlBase64ToUint8Array(base64String: string): Uint8Array<ArrayBuffer>;
+/**
+ * Gets or creates a persistent device ID for subscription deduplication.
+ * The ID is stored in localStorage and persists across sessions.
+ * Uses localStorage (main thread only - not available in service workers).
+ * @returns The device ID string (UUID v4 format)
+ * @example
+ * const deviceId = getDeviceId();
+ * // Use deviceId in subscription requests to identify this device
+ */
+export declare function getDeviceId(): string;
+/**
+ * Clears the device ID from localStorage.
+ * Use for testing or when user logs out and wants a fresh device identity.
+ * @example
+ * // On user logout
+ * await unsubscribeFromPush();
+ * clearDeviceId();
+ */
+export declare function clearDeviceId(): void;
+/**
+ * Saves subscription data to IndexedDB for service worker access.
+ * This data is used for subscription renewal when the browser rotates keys.
+ * @param data - The subscription data to persist (VAPID key, deviceId, basePath)
+ * @returns Promise that resolves when data is saved
+ * @example
+ * await saveSubscriptionData({
+ *   publicKey: vapidPublicKey,
+ *   deviceId: getDeviceId(),
+ *   basePath: '/app'
+ * });
+ */
+export declare function saveSubscriptionData(data: SubscriptionData): Promise<void>;
+/**
+ * Retrieves subscription data from IndexedDB.
+ * Used by service workers during subscription renewal.
+ * @returns The stored subscription data, or null if not found
+ * @example
+ * const data = await getSubscriptionData();
+ * if (data) {
+ *   console.log('Device ID:', data.deviceId);
+ * }
+ */
+export declare function getSubscriptionData(): Promise<SubscriptionData | null>;
+/**
+ * Clears subscription data from IndexedDB.
+ * Call when unsubscribing or during cleanup.
+ * @returns Promise that resolves when data is cleared
+ * @example
+ * await unsubscribeFromPush();
+ * await clearSubscriptionData();
+ */
+export declare function clearSubscriptionData(): Promise<void>;
+/**
+ * Gets the current notification permission state.
+ * @returns The current permission state ('granted', 'denied', or 'default')
+ * @example
+ * const state = getPermissionState();
+ * if (state === 'granted') {
+ *   // Can show notifications
+ * }
+ */
+export declare function getPermissionState(): PushPermissionState;
+/**
+ * Requests notification permission from the user.
+ * Shows browser permission dialog if not already granted/denied.
+ * @returns The resulting permission state
+ * @example
+ * const permission = await requestPermission();
+ * if (permission === 'granted') {
+ *   await subscribeToPush(vapidKey);
+ * }
+ */
+export declare function requestPermission(): Promise<PushPermissionState>;
+/**
+ * Checks if push notifications are supported in the current browser.
+ * Requires both Service Worker and Push API support.
+ * @returns True if push notifications are supported
+ * @example
+ * if (!isPushSupported()) {
+ *   console.log('Push not supported on this browser');
+ *   return;
+ * }
+ */
+export declare function isPushSupported(): boolean;
+/**
+ * Converts a browser PushSubscription to the simplified format for backend storage.
+ * Works in both main thread and service worker contexts.
+ * @param browserSub - The native browser PushSubscription object
+ * @returns A simplified PushSubscription with endpoint and keys
+ * @example
+ * const browserSub = await registration.pushManager.subscribe({ ... });
+ * const subscription = toPushSubscription(browserSub);
+ * await fetch('/api/subscribe', { body: JSON.stringify(subscription) });
+ */
+export declare function toPushSubscription(browserSub: globalThis.PushSubscription): PushSubscription;
+/**
+ * Subscribes to push notifications and prepares a request for backend registration.
+ * Handles permission request, service worker subscription, and data persistence.
+ * @param vapidPublicKey - The VAPID public key from your server
+ * @param basePath - Optional base path for notification click handling (default: '/')
+ * @returns Result with subscription request on success, or error message on failure
+ * @example
+ * const result = await subscribeToPush(vapidPublicKey);
+ * if (result.ok) {
+ *   await fetch('/api/push/subscribe', {
+ *     method: 'POST',
+ *     body: JSON.stringify(result.data)
+ *   });
+ * }
+ */
+export declare function subscribeToPush(vapidPublicKey: string, basePath?: string): Promise<Result<SubscriptionRequest>>;
+/**
+ * Unsubscribes from push notifications.
+ * Removes the browser push subscription and clears stored subscription data.
+ * @returns Result with ok=true on success, or error message on failure
+ * @example
+ * const result = await unsubscribeFromPush();
+ * if (result.ok) {
+ *   await fetch('/api/push/unsubscribe', { method: 'POST' });
+ * }
+ */
+export declare function unsubscribeFromPush(): Promise<Result<void>>;
+/**
+ * Gets the current push subscription if one exists.
+ * Useful for checking subscription status or syncing with backend.
+ * @returns Result with the current subscription, or error if not subscribed
+ * @example
+ * const result = await getCurrentSubscription();
+ * if (result.ok) {
+ *   console.log('Endpoint:', result.data.endpoint);
+ * } else {
+ *   console.log('Not subscribed:', result.error);
+ * }
+ */
+export declare function getCurrentSubscription(): Promise<Result<PushSubscription>>;
+/**
+ * Type definition for the pushsubscriptionchange event.
+ * Fired when the browser rotates push subscriptions.
+ */
+interface PushSubscriptionChangeEvent extends ExtendableEvent {
+    /** The old subscription that is being replaced (may be null) */
+    oldSubscription?: PushSubscription;
+    /** The new subscription (may be null if unsubscribed) */
+    newSubscription?: PushSubscription;
+}
+/**
+ * Handles the pushsubscriptionchange event in a service worker.
+ * Call this from your service worker's event listener when the browser
+ * rotates push subscriptions (typically for security reasons).
+ * @param event - The pushsubscriptionchange event from the service worker
+ * @param renewEndpoint - The backend endpoint to send the renewal request to
+ * @returns Result with ok=true on success, or error message on failure
+ * @example
+ * // In your service worker (sw.js):
+ * self.addEventListener('pushsubscriptionchange', (event) => {
+ *   event.waitUntil(handleSubscriptionChange(event, '/api/push/renew'));
+ * });
+ */
+export declare function handleSubscriptionChange(event: PushSubscriptionChangeEvent, renewEndpoint: string): Promise<Result<void>>;
+export type { PushSubscription, SubscriptionRequest, SubscriptionData, PushPermissionState } from './shared';

package/dist/client.js

@@ -0,0 +1,412 @@
+"use strict";
+/**
+ * pwa-push/client - Browser-side push notification utilities
+ *
+ * Includes: subscription management, device ID, IndexedDB storage, service worker renewal
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.urlBase64ToUint8Array = urlBase64ToUint8Array;
+exports.getDeviceId = getDeviceId;
+exports.clearDeviceId = clearDeviceId;
+exports.saveSubscriptionData = saveSubscriptionData;
+exports.getSubscriptionData = getSubscriptionData;
+exports.clearSubscriptionData = clearSubscriptionData;
+exports.getPermissionState = getPermissionState;
+exports.requestPermission = requestPermission;
+exports.isPushSupported = isPushSupported;
+exports.toPushSubscription = toPushSubscription;
+exports.subscribeToPush = subscribeToPush;
+exports.unsubscribeFromPush = unsubscribeFromPush;
+exports.getCurrentSubscription = getCurrentSubscription;
+exports.handleSubscriptionChange = handleSubscriptionChange;
+const shared_1 = require("@markwharton/pwa-core/shared");
+// =============================================================================
+// Base64 Encoding
+// =============================================================================
+/**
+ * Converts a base64 URL-encoded string to a Uint8Array.
+ * Used to convert VAPID public keys for the PushManager API.
+ * Works in both main thread and service worker contexts.
+ * @param base64String - The base64 URL-encoded string to convert
+ * @returns A Uint8Array containing the decoded bytes
+ * @example
+ * const applicationServerKey = urlBase64ToUint8Array(vapidPublicKey);
+ * await registration.pushManager.subscribe({
+ *   userVisibleOnly: true,
+ *   applicationServerKey
+ * });
+ */
+function urlBase64ToUint8Array(base64String) {
+    const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
+    const base64 = (base64String + padding)
+        .replace(/-/g, '+')
+        .replace(/_/g, '/');
+    const rawData = atob(base64);
+    const buffer = new ArrayBuffer(rawData.length);
+    const outputArray = new Uint8Array(buffer);
+    for (let i = 0; i < rawData.length; ++i) {
+        outputArray[i] = rawData.charCodeAt(i);
+    }
+    return outputArray;
+}
+// =============================================================================
+// Device ID Management
+// =============================================================================
+const DEVICE_ID_KEY = 'push_device_id';
+/**
+ * Generates a cryptographically secure UUID v4.
+ * Uses Web Crypto API for secure random number generation.
+ * @returns A UUID v4 string (e.g., '550e8400-e29b-41d4-a716-446655440000')
+ */
+function generateUUID() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant 1
+    const hex = [...bytes].map(b => b.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/**
+ * Gets or creates a persistent device ID for subscription deduplication.
+ * The ID is stored in localStorage and persists across sessions.
+ * Uses localStorage (main thread only - not available in service workers).
+ * @returns The device ID string (UUID v4 format)
+ * @example
+ * const deviceId = getDeviceId();
+ * // Use deviceId in subscription requests to identify this device
+ */
+function getDeviceId() {
+    let deviceId = localStorage.getItem(DEVICE_ID_KEY);
+    if (!deviceId) {
+        deviceId = generateUUID();
+        localStorage.setItem(DEVICE_ID_KEY, deviceId);
+    }
+    return deviceId;
+}
+/**
+ * Clears the device ID from localStorage.
+ * Use for testing or when user logs out and wants a fresh device identity.
+ * @example
+ * // On user logout
+ * await unsubscribeFromPush();
+ * clearDeviceId();
+ */
+function clearDeviceId() {
+    localStorage.removeItem(DEVICE_ID_KEY);
+}
+// =============================================================================
+// IndexedDB Storage
+// =============================================================================
+const DB_NAME = 'PushSubscriptionDB';
+const STORE_NAME = 'subscriptionData';
+const DATA_KEY = 'current';
+/**
+ * Opens the IndexedDB database, creating the object store if needed.
+ * Internal helper for subscription data persistence.
+ * @returns Promise resolving to the opened database
+ */
+function openDatabase() {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.open(DB_NAME, 1);
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => resolve(request.result);
+        request.onupgradeneeded = (event) => {
+            const db = event.target.result;
+            if (!db.objectStoreNames.contains(STORE_NAME)) {
+                db.createObjectStore(STORE_NAME);
+            }
+        };
+    });
+}
+/**
+ * Executes an IndexedDB operation within a transaction.
+ * Handles database opening, transaction management, and cleanup.
+ * @typeParam T - The expected result type from the operation
+ * @param mode - Transaction mode ('readonly' or 'readwrite')
+ * @param operation - Function that performs the IndexedDB operation
+ * @returns Promise resolving to the operation result
+ */
+async function withTransaction(mode, operation) {
+    const db = await openDatabase();
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction(STORE_NAME, mode);
+        const store = transaction.objectStore(STORE_NAME);
+        const request = operation(store);
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => resolve(request.result);
+        transaction.oncomplete = () => db.close();
+    });
+}
+/**
+ * Saves subscription data to IndexedDB for service worker access.
+ * This data is used for subscription renewal when the browser rotates keys.
+ * @param data - The subscription data to persist (VAPID key, deviceId, basePath)
+ * @returns Promise that resolves when data is saved
+ * @example
+ * await saveSubscriptionData({
+ *   publicKey: vapidPublicKey,
+ *   deviceId: getDeviceId(),
+ *   basePath: '/app'
+ * });
+ */
+function saveSubscriptionData(data) {
+    return withTransaction('readwrite', (store) => store.put(data, DATA_KEY));
+}
+/**
+ * Retrieves subscription data from IndexedDB.
+ * Used by service workers during subscription renewal.
+ * @returns The stored subscription data, or null if not found
+ * @example
+ * const data = await getSubscriptionData();
+ * if (data) {
+ *   console.log('Device ID:', data.deviceId);
+ * }
+ */
+async function getSubscriptionData() {
+    const result = await withTransaction('readonly', (store) => store.get(DATA_KEY));
+    return result || null;
+}
+/**
+ * Clears subscription data from IndexedDB.
+ * Call when unsubscribing or during cleanup.
+ * @returns Promise that resolves when data is cleared
+ * @example
+ * await unsubscribeFromPush();
+ * await clearSubscriptionData();
+ */
+function clearSubscriptionData() {
+    return withTransaction('readwrite', (store) => store.delete(DATA_KEY));
+}
+// =============================================================================
+// Push Support Detection
+// =============================================================================
+/**
+ * Gets the current notification permission state.
+ * @returns The current permission state ('granted', 'denied', or 'default')
+ * @example
+ * const state = getPermissionState();
+ * if (state === 'granted') {
+ *   // Can show notifications
+ * }
+ */
+function getPermissionState() {
+    return Notification.permission;
+}
+/**
+ * Requests notification permission from the user.
+ * Shows browser permission dialog if not already granted/denied.
+ * @returns The resulting permission state
+ * @example
+ * const permission = await requestPermission();
+ * if (permission === 'granted') {
+ *   await subscribeToPush(vapidKey);
+ * }
+ */
+async function requestPermission() {
+    const result = await Notification.requestPermission();
+    return result;
+}
+/**
+ * Checks if push notifications are supported in the current browser.
+ * Requires both Service Worker and Push API support.
+ * @returns True if push notifications are supported
+ * @example
+ * if (!isPushSupported()) {
+ *   console.log('Push not supported on this browser');
+ *   return;
+ * }
+ */
+function isPushSupported() {
+    return 'serviceWorker' in navigator && 'PushManager' in window;
+}
+// =============================================================================
+// Subscription Conversion
+// =============================================================================
+/**
+ * Converts a browser PushSubscription to the simplified format for backend storage.
+ * Works in both main thread and service worker contexts.
+ * @param browserSub - The native browser PushSubscription object
+ * @returns A simplified PushSubscription with endpoint and keys
+ * @example
+ * const browserSub = await registration.pushManager.subscribe({ ... });
+ * const subscription = toPushSubscription(browserSub);
+ * await fetch('/api/subscribe', { body: JSON.stringify(subscription) });
+ */
+function toPushSubscription(browserSub) {
+    const json = browserSub.toJSON();
+    return {
+        endpoint: browserSub.endpoint,
+        keys: {
+            p256dh: json.keys?.p256dh || '',
+            auth: json.keys?.auth || ''
+        }
+    };
+}
+// =============================================================================
+// Subscription Lifecycle
+// =============================================================================
+/**
+ * Subscribes to push notifications and prepares a request for backend registration.
+ * Handles permission request, service worker subscription, and data persistence.
+ * @param vapidPublicKey - The VAPID public key from your server
+ * @param basePath - Optional base path for notification click handling (default: '/')
+ * @returns Result with subscription request on success, or error message on failure
+ * @example
+ * const result = await subscribeToPush(vapidPublicKey);
+ * if (result.ok) {
+ *   await fetch('/api/push/subscribe', {
+ *     method: 'POST',
+ *     body: JSON.stringify(result.data)
+ *   });
+ * }
+ */
+async function subscribeToPush(vapidPublicKey, basePath = '/') {
+    if (!isPushSupported()) {
+        return (0, shared_1.err)('Push notifications not supported');
+    }
+    const permission = await requestPermission();
+    if (permission !== 'granted') {
+        return (0, shared_1.err)('Push permission denied');
+    }
+    try {
+        const registration = await navigator.serviceWorker.ready;
+        const deviceId = getDeviceId();
+        // Convert VAPID key to Uint8Array
+        const applicationServerKey = urlBase64ToUint8Array(vapidPublicKey);
+        const browserSub = await registration.pushManager.subscribe({
+            userVisibleOnly: true,
+            applicationServerKey
+        });
+        // Save data for service worker renewal
+        await saveSubscriptionData({
+            publicKey: vapidPublicKey,
+            deviceId,
+            basePath
+        });
+        return (0, shared_1.ok)({
+            subscription: toPushSubscription(browserSub),
+            deviceId,
+            basePath
+        });
+    }
+    catch (error) {
+        return (0, shared_1.err)((0, shared_1.getErrorMessage)(error, 'Subscription failed'));
+    }
+}
+/**
+ * Unsubscribes from push notifications.
+ * Removes the browser push subscription and clears stored subscription data.
+ * @returns Result with ok=true on success, or error message on failure
+ * @example
+ * const result = await unsubscribeFromPush();
+ * if (result.ok) {
+ *   await fetch('/api/push/unsubscribe', { method: 'POST' });
+ * }
+ */
+async function unsubscribeFromPush() {
+    try {
+        const registration = await navigator.serviceWorker.ready;
+        const subscription = await registration.pushManager.getSubscription();
+        if (subscription) {
+            await subscription.unsubscribe();
+        }
+        // Clear stored subscription data from IndexedDB
+        await clearSubscriptionData();
+        return (0, shared_1.okVoid)();
+    }
+    catch (error) {
+        return (0, shared_1.err)((0, shared_1.getErrorMessage)(error, 'Unsubscribe failed'));
+    }
+}
+/**
+ * Gets the current push subscription if one exists.
+ * Useful for checking subscription status or syncing with backend.
+ * @returns Result with the current subscription, or error if not subscribed
+ * @example
+ * const result = await getCurrentSubscription();
+ * if (result.ok) {
+ *   console.log('Endpoint:', result.data.endpoint);
+ * } else {
+ *   console.log('Not subscribed:', result.error);
+ * }
+ */
+async function getCurrentSubscription() {
+    try {
+        const registration = await navigator.serviceWorker.ready;
+        const subscription = await registration.pushManager.getSubscription();
+        if (!subscription) {
+            return (0, shared_1.err)('No active subscription');
+        }
+        return (0, shared_1.ok)(toPushSubscription(subscription));
+    }
+    catch (error) {
+        return (0, shared_1.err)((0, shared_1.getErrorMessage)(error, 'Failed to get subscription'));
+    }
+}
+/**
+ * Resubscribes to push notifications using stored VAPID key.
+ * Internal helper for subscription renewal in service worker context.
+ * @param data - The stored subscription data containing VAPID key
+ * @returns The new PushSubscription, or null on failure
+ */
+async function resubscribe(data) {
+    try {
+        const self = globalThis;
+        const registration = self.registration;
+        const applicationServerKey = urlBase64ToUint8Array(data.publicKey);
+        const subscription = await registration.pushManager.subscribe({
+            userVisibleOnly: true,
+            applicationServerKey
+        });
+        return toPushSubscription(subscription);
+    }
+    catch (error) {
+        console.error('Resubscribe failed:', error);
+        return null;
+    }
+}
+/**
+ * Handles the pushsubscriptionchange event in a service worker.
+ * Call this from your service worker's event listener when the browser
+ * rotates push subscriptions (typically for security reasons).
+ * @param event - The pushsubscriptionchange event from the service worker
+ * @param renewEndpoint - The backend endpoint to send the renewal request to
+ * @returns Result with ok=true on success, or error message on failure
+ * @example
+ * // In your service worker (sw.js):
+ * self.addEventListener('pushsubscriptionchange', (event) => {
+ *   event.waitUntil(handleSubscriptionChange(event, '/api/push/renew'));
+ * });
+ */
+async function handleSubscriptionChange(event, renewEndpoint) {
+    try {
+        // Get stored data from IndexedDB
+        const data = await getSubscriptionData();
+        if (!data) {
+            return (0, shared_1.err)('No subscription data found for renewal');
+        }
+        // Resubscribe with same VAPID key
+        const newSubscription = await resubscribe(data);
+        if (!newSubscription) {
+            return (0, shared_1.err)('Failed to create new subscription');
+        }
+        // Build renewal request (uses SubscriptionRequest type)
+        const renewalRequest = {
+            subscription: newSubscription,
+            deviceId: data.deviceId,
+            basePath: data.basePath
+        };
+        // Send to backend
+        const response = await fetch(renewEndpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(renewalRequest)
+        });
+        if (!response.ok) {
+            return (0, shared_1.err)(`Renewal request failed: ${response.status}`);
+        }
+        return (0, shared_1.okVoid)();
+    }
+    catch (error) {
+        return (0, shared_1.err)((0, shared_1.getErrorMessage)(error, 'Subscription renewal failed'));
+    }
+}

package/dist/index.d.ts

@@ -1,2 +1,11 @@
+/**
+ * pwa-push - Web push notifications for Azure PWA projects
+ *
+ * Import paths:
+ * - '@markwharton/pwa-push/shared' - Types and Result pattern (browser-safe)
+ * - '@markwharton/pwa-push/server' - VAPID config, send notifications (Node.js only)
+ * - '@markwharton/pwa-push/client' - Subscription lifecycle, device ID (browser only)
+ * - '@markwharton/pwa-push' - Server + shared (for convenience in Node.js)
+ */
 export * from './shared';
 export * from './server';

package/dist/index.js

@@ -1,4 +1,13 @@
 "use strict";
+/**
+ * pwa-push - Web push notifications for Azure PWA projects
+ *
+ * Import paths:
+ * - '@markwharton/pwa-push/shared' - Types and Result pattern (browser-safe)
+ * - '@markwharton/pwa-push/server' - VAPID config, send notifications (Node.js only)
+ * - '@markwharton/pwa-push/client' - Subscription lifecycle, device ID (browser only)
+ * - '@markwharton/pwa-push' - Server + shared (for convenience in Node.js)
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);