@markwharton/pwa-push 1.1.0 → 1.2.1

package/dist/server/send.d.ts

@@ -1,7 +1,18 @@
-import { PushSubscription, NotificationPayload, SendResult } from '../types';
+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;
@@ -9,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<SendResult>;
+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<SendResult[]>;
+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<SendResult>;
+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

@@ -11,13 +11,24 @@ exports.sendPushToAll = sendPushToAll;
 exports.sendPushWithDetails = sendPushWithDetails;
 exports.isSubscriptionExpired = isSubscriptionExpired;
 const web_push_1 = __importDefault(require("web-push"));
+const types_1 = require("@markwharton/pwa-core/types");
 /**
  * Server-side Web Push notification utilities
  */
 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;
@@ -31,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({
@@ -41,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) {
@@ -50,28 +72,47 @@ 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) {
-        return { ok: false, error: 'Push not initialized' };
+        return (0, types_1.err)('Push not initialized');
     }
     // Auto-inject basePath from subscription if not set in payload
     const payloadWithBasePath = {
@@ -80,19 +121,22 @@ async function sendPushWithDetails(subscription, payload) {
     };
     try {
         await web_push_1.default.sendNotification(subscription, JSON.stringify(payloadWithBasePath));
-        return { ok: true };
+        return (0, types_1.okVoid)();
     }
     catch (error) {
         const webPushError = error;
-        return {
-            ok: false,
-            error: webPushError.message || 'Unknown error',
-            statusCode: webPushError.statusCode
-        };
+        return (0, types_1.err)(webPushError.message || 'Unknown error', webPushError.statusCode);
     }
 }
 /**
- * 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/dist/sw.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Service Worker bundle entry point
+ * Exports functions for use via importScripts()
+ *
+ * Usage in sw.js:
+ * ```
+ * importScripts('/path/to/pwa-push-sw.js');
+ *
+ * self.addEventListener('pushsubscriptionchange', (event) => {
+ *     event.waitUntil(PwaPush.handleSubscriptionChange('/api/push/renew'));
+ * });
+ * ```
+ */
+export { handleSubscriptionChange } from './client/renewal';

package/dist/sw.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Service Worker bundle entry point
+ * Exports functions for use via importScripts()
+ *
+ * Usage in sw.js:
+ * ```
+ * importScripts('/path/to/pwa-push-sw.js');
+ *
+ * self.addEventListener('pushsubscriptionchange', (event) => {
+ *     event.waitUntil(PwaPush.handleSubscriptionChange('/api/push/renew'));
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleSubscriptionChange = void 0;
+var renewal_1 = require("./client/renewal");
+Object.defineProperty(exports, "handleSubscriptionChange", { enumerable: true, get: function () { return renewal_1.handleSubscriptionChange; } });

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 /**
  * Push notification types - shared between server and client
  */
+export { Result, ok, okVoid, err } from '@markwharton/pwa-core/types';
 export interface PushSubscription {
     endpoint: string;
     keys: {
@@ -25,24 +26,6 @@ export interface VapidConfig {
     privateKey: string;
     subject: string;
 }
-/**
- * Result type for push operations.
- * Aligned with Result<T> pattern from @markwharton/pwa-core
- */
-export interface SendResult {
-    ok: boolean;
-    error?: string;
-    statusCode?: number;
-}
-/**
- * Generic result type for client operations.
- * Aligned with Result<T> pattern from @markwharton/pwa-core
- */
-export interface ClientResult<T> {
-    ok: boolean;
-    data?: T;
-    error?: string;
-}
 export interface SubscriptionRequest {
     subscription: PushSubscription;
     deviceId: string;

package/dist/types.js

@@ -3,3 +3,9 @@
  * Push notification types - shared between server and client
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.err = exports.okVoid = exports.ok = void 0;
+// Re-export Result from pwa-core for convenience
+var types_1 = require("@markwharton/pwa-core/types");
+Object.defineProperty(exports, "ok", { enumerable: true, get: function () { return types_1.ok; } });
+Object.defineProperty(exports, "okVoid", { enumerable: true, get: function () { return types_1.okVoid; } });
+Object.defineProperty(exports, "err", { enumerable: true, get: function () { return types_1.err; } });

package/package.json

@@ -1,24 +1,29 @@
 {
   "name": "@markwharton/pwa-push",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Web push notifications for Azure PWA projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
     "./server": "./dist/server/index.js",
-    "./client": "./dist/client/index.js"
+    "./client": "./dist/client/index.js",
+    "./sw": "./dist/pwa-push-sw.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && npm run build:sw",
+    "build:sw": "esbuild src/sw.ts --bundle --outfile=dist/pwa-push-sw.js --format=iife --global-name=PwaPush",
     "clean": "rm -rf dist"
   },
   "peerDependencies": {
+    "@markwharton/pwa-core": "^1.1.0",
     "web-push": "^3.6.0"
   },
   "devDependencies": {
+    "@markwharton/pwa-core": "^1.1.0",
     "@types/node": "^20.10.0",
     "@types/web-push": "^3.6.4",
+    "esbuild": "^0.27.2",
     "typescript": "^5.3.0",
     "web-push": "^3.6.7"
   },
@@ -27,7 +32,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/MarkWharton/pwa-packages.git",
+    "url": "git+https://github.com/MarkWharton/pwa-packages.git",
     "directory": "packages/push"
   },
   "author": "Mark Wharton",