@swimmesberger/elarion-webpush 0.2.8 → 0.2.9

package/README.md

@@ -10,7 +10,10 @@ package (`IWebPushSender`, VAPID keys, the subscription store).
 - `enablePush(api)` — asks for permission **inside the click handler** (before any `await`, which Safari
   requires) and subscribes.
 - `subscribe`, `unsubscribe`, `isSubscribed`, and `refreshOnStart(api)` — call the last one on every app start
-  to heal subscriptions the push service rotated or the server cleaned up.
+  to heal subscriptions the push service rotated or the server cleaned up. They subscribe through the page's
+  active service-worker registration (or the `registration` option) and wait at most `registrationTimeoutMs`
+  (10 s) for a worker to activate, then throw a `WebPushRegistrationError` — `navigator.serviceWorker.ready`
+  alone never settles when no worker is registered, for example on a dev server that does not serve one.
 - `@swimmesberger/elarion-webpush/sw` — `registerWebPushHandlers(self)` for the service worker: shows the
   notification, focuses or opens the app at its URL on click, and re-subscribes on `pushsubscriptionchange`.
 

package/dist/index.d.ts

@@ -15,10 +15,19 @@ export type EnablePushOutcome = 'subscribed' | 'denied' | 'dismissed' | 'install
 /** Options shared by the subscription helpers. */
 export interface PushHelperOptions {
     /**
-     * The service-worker registration to subscribe through. Defaults to `navigator.serviceWorker.ready` — which
-     * never settles when no service worker is registered, so register one before calling the helpers.
+     * The service-worker registration to subscribe through — pass the one `navigator.serviceWorker.register(...)`
+     * returned when you have it. Without it the helpers use the page's active registration, and otherwise wait for
+     * `navigator.serviceWorker.ready` for at most {@link registrationTimeoutMs}, failing with a
+     * {@link WebPushRegistrationError} instead of hanging when no service worker ever takes over (a dev server
+     * that does not serve one, a page outside the worker's scope).
      */
     registration?: ServiceWorkerRegistration;
+    /** How long to wait for a service worker to become active when none is yet. Defaults to 10 000 ms. */
+    registrationTimeoutMs?: number;
+}
+/** Thrown when no active service-worker registration is available to subscribe through. */
+export declare class WebPushRegistrationError extends Error {
+    constructor(message: string);
 }
 /** Detects push support; see {@link PushAvailability}. Safe to call during rendering. */
 export declare function pushAvailability(): PushAvailability;

package/dist/index.js

@@ -9,6 +9,14 @@ import { toSubscriptionJson } from './api.js';
 import { isSameKey, urlBase64ToUint8Array } from './base64url.js';
 export { fetchWebPushApi, toSubscriptionJson, } from './api.js';
 export { urlBase64ToUint8Array } from './base64url.js';
+/** Thrown when no active service-worker registration is available to subscribe through. */
+export class WebPushRegistrationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WebPushRegistrationError';
+    }
+}
+const DEFAULT_REGISTRATION_TIMEOUT_MS = 10_000;
 /** Detects push support; see {@link PushAvailability}. Safe to call during rendering. */
 export function pushAvailability() {
     if (typeof navigator === 'undefined' || typeof window === 'undefined')
@@ -90,7 +98,27 @@ export async function refreshOnStart(api, options = {}) {
     return true;
 }
 async function resolveRegistration(options) {
-    return options.registration ?? navigator.serviceWorker.ready;
+    if (options.registration)
+        return options.registration;
+    const container = navigator.serviceWorker;
+    // `ready` waits for a worker to become active and never settles when none is ever registered, so look for an
+    // active registration first and bound the wait for the rest.
+    const existing = await container.getRegistration?.();
+    if (existing?.active)
+        return existing;
+    const timeoutMs = options.registrationTimeoutMs ?? DEFAULT_REGISTRATION_TIMEOUT_MS;
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new WebPushRegistrationError(`No active service worker registration after ${timeoutMs} ms. Web Push needs a registered service worker: ` +
+            `call navigator.serviceWorker.register('/sw.js', { type: 'module' }) first (a dev server that does not ` +
+            `serve the worker never activates one), or pass the registration as the 'registration' option.`)), timeoutMs);
+    });
+    try {
+        return await Promise.race([container.ready, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
 }
 function iosVersion() {
     const userAgent = navigator.userAgent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swimmesberger/elarion-webpush",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "The browser half of Elarion Web Push: push availability detection (including the iOS Home Screen requirement), gesture-safe permission and subscribe/unsubscribe/refresh helpers over a pluggable server API, and a service-worker module for push, notificationclick, and pushsubscriptionchange.",
   "license": "Apache-2.0",
   "type": "module",