@markwharton/pwa-push 1.2.0 → 1.2.1

package/dist/client/indexedDb.js

@@ -11,7 +11,9 @@ const DB_NAME = 'PushSubscriptionDB';
 const STORE_NAME = 'subscriptionData';
 const DATA_KEY = 'current';
 /**
- * Open the IndexedDB database
+ * 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) => {
@@ -27,7 +29,12 @@ function openDatabase() {
     });
 }
 /**
- * Execute an IndexedDB operation within a transaction
+ * 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();
@@ -41,20 +48,41 @@ async function withTransaction(mode, operation) {
     });
 }
 /**
- * Save subscription data to IndexedDB (for service worker access)
+ * 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));
 }
 /**
- * Get subscription data from IndexedDB
+ * 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;
 }
 /**
- * Clear subscription data from IndexedDB
+ * 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));

package/dist/client/renewal.d.ts

@@ -4,22 +4,27 @@
  */
 import { PushSubscription } from '../types';
 /**
- * Handle pushsubscriptionchange event in service worker
- * Call this from your service worker's event listener
- *
- * Usage in sw.js:
- * ```
+ * 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 True if renewal succeeded, false otherwise
+ * @example
+ * // In your service worker (sw.js):
  * self.addEventListener('pushsubscriptionchange', (event) => {
- *     event.waitUntil(handleSubscriptionChange(event, '/api/push/renew'));
+ *   event.waitUntil(handleSubscriptionChange(event, '/api/push/renew'));
  * });
- * ```
  */
 export declare function handleSubscriptionChange(event: PushSubscriptionChangeEvent, renewEndpoint: string): Promise<boolean>;
 /**
- * Type for pushsubscriptionchange event
+ * 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;
 }
 export {};

package/dist/client/renewal.js

@@ -9,15 +9,17 @@ const encoding_1 = require("./encoding");
 const indexedDb_1 = require("./indexedDb");
 const subscribe_1 = require("./subscribe");
 /**
- * Handle pushsubscriptionchange event in service worker
- * Call this from your service worker's event listener
- *
- * Usage in sw.js:
- * ```
+ * 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 True if renewal succeeded, false otherwise
+ * @example
+ * // In your service worker (sw.js):
  * self.addEventListener('pushsubscriptionchange', (event) => {
- *     event.waitUntil(handleSubscriptionChange(event, '/api/push/renew'));
+ *   event.waitUntil(handleSubscriptionChange(event, '/api/push/renew'));
  * });
- * ```
  */
 async function handleSubscriptionChange(event, renewEndpoint) {
     try {
@@ -58,7 +60,10 @@ async function handleSubscriptionChange(event, renewEndpoint) {
     }
 }
 /**
- * Resubscribe to push with stored VAPID key
+ * 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 {

package/dist/client/subscribe.d.ts

@@ -4,37 +4,85 @@
 import { Result } from '@markwharton/pwa-core/types';
 import { PushSubscription, SubscriptionRequest, PushPermissionState } from '../types';
 /**
- * Check current notification permission state
+ * 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;
 /**
- * Request notification permission from user
+ * 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>;
 /**
- * Check if push notifications are supported
+ * 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;
 /**
- * Convert browser PushSubscription to our format
- * Works in both main thread and service worker contexts
+ * 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;
 /**
- * Subscribe to push notifications
- *
- * @returns Result with subscription request ready to send to backend
+ * 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>>;
 /**
- * Unsubscribe from push notifications
- *
- * @returns Result indicating success or failure
+ * Unsubscribes from push notifications.
+ * Removes the browser push subscription if one exists.
+ * @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>>;
 /**
- * Get current push subscription if exists
- *
- * @returns Result with current subscription, or error if not subscribed
+ * 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>>;

package/dist/client/subscribe.js

@@ -15,27 +15,53 @@ const deviceId_1 = require("./deviceId");
 const indexedDb_1 = require("./indexedDb");
 const encoding_1 = require("./encoding");
 /**
- * Check current notification permission state
+ * 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;
 }
 /**
- * Request notification permission from user
+ * 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;
 }
 /**
- * Check if push notifications are supported
+ * 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;
 }
 /**
- * Convert browser PushSubscription to our format
- * Works in both main thread and service worker contexts
+ * 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();
@@ -48,9 +74,19 @@ function toPushSubscription(browserSub) {
     };
 }
 /**
- * Subscribe to push notifications
- *
- * @returns Result with subscription request ready to send to backend
+ * 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()) {
@@ -87,9 +123,14 @@ async function subscribeToPush(vapidPublicKey, basePath = '/') {
     }
 }
 /**
- * Unsubscribe from push notifications
- *
- * @returns Result indicating success or failure
+ * Unsubscribes from push notifications.
+ * Removes the browser push subscription if one exists.
+ * @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 {
@@ -106,9 +147,16 @@ async function unsubscribeFromPush() {
     }
 }
 /**
- * Get current push subscription if exists
- *
- * @returns Result with current subscription, or error if not subscribed
+ * 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 {

package/dist/server/send.d.ts

@@ -1,8 +1,18 @@
 import { Result } from '@markwharton/pwa-core/types';
 import { PushSubscription, NotificationPayload } from '../types';
 /**
- * Initialize VAPID configuration - call once at startup
- * Fails fast if keys are missing
+ * Initializes VAPID configuration for Web Push. Call once at application startup.
+ * @param config - VAPID configuration
+ * @param config.publicKey - The VAPID public key
+ * @param config.privateKey - The VAPID private key
+ * @param config.subject - Contact email (mailto:) or URL
+ * @throws Error if any required configuration is missing
+ * @example
+ * initPush({
+ *   publicKey: process.env.VAPID_PUBLIC_KEY,
+ *   privateKey: process.env.VAPID_PRIVATE_KEY,
+ *   subject: 'mailto:admin@example.com'
+ * });
  */
 export declare function initPush(config: {
     publicKey?: string;
@@ -10,30 +20,67 @@ export declare function initPush(config: {
     subject?: string;
 }): void;
 /**
- * Auto-initialize from environment variables
+ * Initializes VAPID from environment variables.
+ * Reads VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, and VAPID_SUBJECT.
+ * @throws Error if required environment variables are missing
+ * @example
+ * initPushFromEnv(); // Uses process.env automatically
  */
 export declare function initPushFromEnv(): void;
 /**
- * Get the VAPID public key (for client subscription)
+ * Gets the VAPID public key for client-side subscription.
+ * @returns The VAPID public key string
+ * @throws Error if initPush() has not been called
+ * @example
+ * // Server endpoint
+ * app.get('/api/vapid-key', (req, res) => {
+ *   res.json({ publicKey: getVapidPublicKey() });
+ * });
  */
 export declare function getVapidPublicKey(): string;
 /**
- * Send a push notification to a single subscription
- *
- * @returns Result with ok status, or error details on failure
+ * Sends a push notification to a single subscription.
+ * @param subscription - The push subscription to send to
+ * @param payload - The notification payload (title, body, etc.)
+ * @returns Result with ok=true on success, or error message and statusCode on failure
+ * @example
+ * const result = await sendPushNotification(subscription, {
+ *   title: 'New Message',
+ *   body: 'You have a new message'
+ * });
  */
 export declare function sendPushNotification(subscription: PushSubscription, payload: NotificationPayload): Promise<Result<void>>;
 /**
- * Send a push notification to multiple subscriptions
- * Returns array of results, one per subscription
+ * Sends a push notification to multiple subscriptions in parallel.
+ * @param subscriptions - Array of push subscriptions
+ * @param payload - The notification payload (title, body, etc.)
+ * @returns Array of Results, one per subscription (in same order)
+ * @example
+ * const results = await sendPushToAll(subscriptions, { title: 'Alert', body: 'System update' });
+ * const failed = results.filter(r => !r.ok);
  */
 export declare function sendPushToAll(subscriptions: PushSubscription[], payload: NotificationPayload): Promise<Result<void>[]>;
 /**
- * Send push notification with detailed error information
- * Auto-injects basePath from subscription to payload if not already set
+ * Sends a push notification with detailed error information.
+ * Automatically injects basePath from subscription if not set in payload.
+ * @param subscription - The push subscription to send to
+ * @param payload - The notification payload
+ * @returns Result with ok=true on success, or error with statusCode on failure
+ * @example
+ * const result = await sendPushWithDetails(subscription, { title: 'Alert' });
+ * if (!result.ok && isSubscriptionExpired(result.statusCode)) {
+ *   await deleteSubscription(subscription);
+ * }
  */
 export declare function sendPushWithDetails(subscription: PushSubscription, payload: NotificationPayload): Promise<Result<void>>;
 /**
- * Check if a subscription is expired (410 Gone)
+ * Checks if a status code indicates an expired subscription (410 Gone).
+ * Use this to clean up stale subscriptions from your database.
+ * @param statusCode - The HTTP status code from a failed push attempt
+ * @returns True if the subscription should be deleted
+ * @example
+ * if (!result.ok && isSubscriptionExpired(result.statusCode)) {
+ *   await db.deleteSubscription(subscription.endpoint);
+ * }
  */
 export declare function isSubscriptionExpired(statusCode: number | undefined): boolean;

package/dist/server/send.js

@@ -17,8 +17,18 @@ const types_1 = require("@markwharton/pwa-core/types");
  */
 let vapidConfig = null;
 /**
- * Initialize VAPID configuration - call once at startup
- * Fails fast if keys are missing
+ * Initializes VAPID configuration for Web Push. Call once at application startup.
+ * @param config - VAPID configuration
+ * @param config.publicKey - The VAPID public key
+ * @param config.privateKey - The VAPID private key
+ * @param config.subject - Contact email (mailto:) or URL
+ * @throws Error if any required configuration is missing
+ * @example
+ * initPush({
+ *   publicKey: process.env.VAPID_PUBLIC_KEY,
+ *   privateKey: process.env.VAPID_PRIVATE_KEY,
+ *   subject: 'mailto:admin@example.com'
+ * });
  */
 function initPush(config) {
     const { publicKey, privateKey, subject } = config;
@@ -32,7 +42,11 @@ function initPush(config) {
     web_push_1.default.setVapidDetails(subject, publicKey, privateKey);
 }
 /**
- * Auto-initialize from environment variables
+ * Initializes VAPID from environment variables.
+ * Reads VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, and VAPID_SUBJECT.
+ * @throws Error if required environment variables are missing
+ * @example
+ * initPushFromEnv(); // Uses process.env automatically
  */
 function initPushFromEnv() {
     initPush({
@@ -42,7 +56,14 @@ function initPushFromEnv() {
     });
 }
 /**
- * Get the VAPID public key (for client subscription)
+ * Gets the VAPID public key for client-side subscription.
+ * @returns The VAPID public key string
+ * @throws Error if initPush() has not been called
+ * @example
+ * // Server endpoint
+ * app.get('/api/vapid-key', (req, res) => {
+ *   res.json({ publicKey: getVapidPublicKey() });
+ * });
  */
 function getVapidPublicKey() {
     if (!vapidConfig) {
@@ -51,24 +72,43 @@ function getVapidPublicKey() {
     return vapidConfig.publicKey;
 }
 /**
- * Send a push notification to a single subscription
- *
- * @returns Result with ok status, or error details on failure
+ * Sends a push notification to a single subscription.
+ * @param subscription - The push subscription to send to
+ * @param payload - The notification payload (title, body, etc.)
+ * @returns Result with ok=true on success, or error message and statusCode on failure
+ * @example
+ * const result = await sendPushNotification(subscription, {
+ *   title: 'New Message',
+ *   body: 'You have a new message'
+ * });
  */
 async function sendPushNotification(subscription, payload) {
     return sendPushWithDetails(subscription, payload);
 }
 /**
- * Send a push notification to multiple subscriptions
- * Returns array of results, one per subscription
+ * Sends a push notification to multiple subscriptions in parallel.
+ * @param subscriptions - Array of push subscriptions
+ * @param payload - The notification payload (title, body, etc.)
+ * @returns Array of Results, one per subscription (in same order)
+ * @example
+ * const results = await sendPushToAll(subscriptions, { title: 'Alert', body: 'System update' });
+ * const failed = results.filter(r => !r.ok);
  */
 async function sendPushToAll(subscriptions, payload) {
     const results = await Promise.all(subscriptions.map(sub => sendPushWithDetails(sub, payload)));
     return results;
 }
 /**
- * Send push notification with detailed error information
- * Auto-injects basePath from subscription to payload if not already set
+ * Sends a push notification with detailed error information.
+ * Automatically injects basePath from subscription if not set in payload.
+ * @param subscription - The push subscription to send to
+ * @param payload - The notification payload
+ * @returns Result with ok=true on success, or error with statusCode on failure
+ * @example
+ * const result = await sendPushWithDetails(subscription, { title: 'Alert' });
+ * if (!result.ok && isSubscriptionExpired(result.statusCode)) {
+ *   await deleteSubscription(subscription);
+ * }
  */
 async function sendPushWithDetails(subscription, payload) {
     if (!vapidConfig) {
@@ -89,7 +129,14 @@ async function sendPushWithDetails(subscription, payload) {
     }
 }
 /**
- * Check if a subscription is expired (410 Gone)
+ * Checks if a status code indicates an expired subscription (410 Gone).
+ * Use this to clean up stale subscriptions from your database.
+ * @param statusCode - The HTTP status code from a failed push attempt
+ * @returns True if the subscription should be deleted
+ * @example
+ * if (!result.ok && isSubscriptionExpired(result.statusCode)) {
+ *   await db.deleteSubscription(subscription.endpoint);
+ * }
  */
 function isSubscriptionExpired(statusCode) {
     return statusCode === 410;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/pwa-push",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Web push notifications for Azure PWA projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",