@markwharton/pwa-push 1.1.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

@@ -1,39 +1,88 @@
 /**
  * Push subscription helpers for main thread
  */
-import { PushSubscription, SubscriptionRequest, PushPermissionState, ClientResult } from '../types';
+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<ClientResult<SubscriptionRequest>>;
+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<ClientResult<void>>;
+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<ClientResult<PushSubscription>>;
+export declare function getCurrentSubscription(): Promise<Result<PushSubscription>>;

package/dist/client/subscribe.js

@@ -10,31 +10,58 @@ exports.toPushSubscription = toPushSubscription;
 exports.subscribeToPush = subscribeToPush;
 exports.unsubscribeFromPush = unsubscribeFromPush;
 exports.getCurrentSubscription = getCurrentSubscription;
+const types_1 = require("@markwharton/pwa-core/types");
 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();
@@ -47,17 +74,27 @@ 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()) {
-        return { ok: false, error: 'Push notifications not supported' };
+        return (0, types_1.err)('Push notifications not supported');
     }
     const permission = await requestPermission();
     if (permission !== 'granted') {
-        return { ok: false, error: 'Push permission denied' };
+        return (0, types_1.err)('Push permission denied');
     }
     try {
         const registration = await navigator.serviceWorker.ready;
@@ -74,24 +111,26 @@ async function subscribeToPush(vapidPublicKey, basePath = '/') {
             deviceId,
             basePath
         });
-        return {
-            ok: true,
-            data: {
-                subscription: toPushSubscription(browserSub),
-                deviceId,
-                basePath
-            }
-        };
+        return (0, types_1.ok)({
+            subscription: toPushSubscription(browserSub),
+            deviceId,
+            basePath
+        });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : 'Subscription failed';
-        return { ok: false, error: message };
+        return (0, types_1.err)(message);
     }
 }
 /**
- * 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 {
@@ -100,29 +139,36 @@ async function unsubscribeFromPush() {
         if (subscription) {
             await subscription.unsubscribe();
         }
-        return { ok: true };
+        return (0, types_1.okVoid)();
     }
     catch (error) {
         const message = error instanceof Error ? error.message : 'Unsubscribe failed';
-        return { ok: false, error: message };
+        return (0, types_1.err)(message);
     }
 }
 /**
- * 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 {
         const registration = await navigator.serviceWorker.ready;
         const subscription = await registration.pushManager.getSubscription();
         if (!subscription) {
-            return { ok: false, error: 'No active subscription' };
+            return (0, types_1.err)('No active subscription');
         }
-        return { ok: true, data: toPushSubscription(subscription) };
+        return (0, types_1.ok)(toPushSubscription(subscription));
     }
     catch (error) {
         const message = error instanceof Error ? error.message : 'Failed to get subscription';
-        return { ok: false, error: message };
+        return (0, types_1.err)(message);
     }
 }

package/dist/pwa-push-sw.js

@@ -0,0 +1,172 @@
+"use strict";
+var PwaPush = (() => {
+  var __create = Object.create;
+  var __defProp = Object.defineProperty;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __getProtoOf = Object.getPrototypeOf;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __commonJS = (cb, mod) => function __require() {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  };
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, { get: all[name], enumerable: true });
+  };
+  var __copyProps = (to, from, except, desc) => {
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (let key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(to, key) && key !== except)
+          __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+    }
+    return to;
+  };
+  var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+    // If the importer is in node compatibility mode or this is not an ESM
+    // file that has been converted to a CommonJS file using a Babel-
+    // compatible transform (i.e. "__esModule" has not been set), then set
+    // "default" to the CommonJS "module.exports" for node compatibility.
+    isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+    mod
+  ));
+  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+  // ../core/dist/types.js
+  var require_types = __commonJS({
+    "../core/dist/types.js"(exports) {
+      "use strict";
+      Object.defineProperty(exports, "__esModule", { value: true });
+      exports.ok = ok2;
+      exports.okVoid = okVoid2;
+      exports.err = err2;
+      function ok2(data) {
+        return { ok: true, data };
+      }
+      function okVoid2() {
+        return { ok: true };
+      }
+      function err2(error, statusCode) {
+        return statusCode !== void 0 ? { ok: false, error, statusCode } : { ok: false, error };
+      }
+    }
+  });
+
+  // src/sw.ts
+  var sw_exports = {};
+  __export(sw_exports, {
+    handleSubscriptionChange: () => handleSubscriptionChange
+  });
+
+  // src/client/encoding.ts
+  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;
+  }
+
+  // src/client/indexedDb.ts
+  var DB_NAME = "PushSubscriptionDB";
+  var STORE_NAME = "subscriptionData";
+  var DATA_KEY = "current";
+  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);
+        }
+      };
+    });
+  }
+  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();
+    });
+  }
+  async function getSubscriptionData() {
+    const result = await withTransaction(
+      "readonly",
+      (store) => store.get(DATA_KEY)
+    );
+    return result || null;
+  }
+
+  // src/client/subscribe.ts
+  var import_types = __toESM(require_types());
+  function toPushSubscription(browserSub) {
+    const json = browserSub.toJSON();
+    return {
+      endpoint: browserSub.endpoint,
+      keys: {
+        p256dh: json.keys?.p256dh || "",
+        auth: json.keys?.auth || ""
+      }
+    };
+  }
+
+  // src/client/renewal.ts
+  async function handleSubscriptionChange(event, renewEndpoint) {
+    try {
+      const data = await getSubscriptionData();
+      if (!data) {
+        console.error("No subscription data found for renewal");
+        return false;
+      }
+      const newSubscription = await resubscribe(data);
+      if (!newSubscription) {
+        console.error("Failed to create new subscription");
+        return false;
+      }
+      const renewalRequest = {
+        subscription: newSubscription,
+        deviceId: data.deviceId,
+        basePath: data.basePath
+      };
+      const response = await fetch(renewEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(renewalRequest)
+      });
+      if (!response.ok) {
+        console.error("Renewal request failed:", response.status);
+        return false;
+      }
+      console.log("Push subscription renewed successfully");
+      return true;
+    } catch (error) {
+      console.error("Subscription renewal failed:", error);
+      return false;
+    }
+  }
+  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;
+    }
+  }
+  return __toCommonJS(sw_exports);
+})();