@swimmesberger/elarion-webpush 0.0.0

package/README.md

@@ -0,0 +1,57 @@
+# @swimmesberger/elarion-webpush
+
+The browser half of [Elarion Web Push](https://elarion.wimmesberger.dev/docs/capabilities/web-push): reach a
+user's browser or installed PWA while the app is closed. The server half is the `Elarion.WebPush` NuGet
+package (`IWebPushSender`, VAPID keys, the subscription store).
+
+- `pushAvailability()` → `'available' | 'install-first' | 'unsupported'`. `install-first` is iOS/iPadOS Safari
+  outside a Home Screen app, where `PushManager` does not exist yet: show "Add to Home Screen first" instead of
+  a switch that can never turn on.
+- `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.
+- `@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`.
+
+## Page
+
+```ts
+import { enablePush, fetchWebPushApi, pushAvailability, refreshOnStart } from '@swimmesberger/elarion-webpush'
+
+const api = fetchWebPushApi() // the endpoints app.MapElarionWebPush() maps under /webpush
+
+await navigator.serviceWorker.register('/sw.js', { type: 'module' })
+void refreshOnStart(api)
+
+switch (pushAvailability()) {
+  case 'available':
+    button.onclick = async () => console.log(await enablePush(api)) // 'subscribed' | 'denied' | 'dismissed'
+    break
+  case 'install-first':
+    hint.textContent = 'Add this app to your Home Screen to turn on notifications.'
+    break
+}
+```
+
+When the application exposes its own `webPush.*` handlers instead of `MapElarionWebPush`, adapt the generated
+JSON-RPC client:
+
+```ts
+const api: WebPushServerApi = {
+  getPublicKey: async () => (await rpc.webPush.publicKey({})).publicKey,
+  subscribe: async (subscription) => { await rpc.webPush.subscribe(subscription) },
+  unsubscribe: async (endpoint) => { await rpc.webPush.unsubscribe({ endpoint }) },
+}
+```
+
+## Service worker
+
+```ts
+import { registerWebPushHandlers } from '@swimmesberger/elarion-webpush/sw'
+
+registerWebPushHandlers(self, { icon: '/icons/192.png', badge: '/icons/badge.png' })
+```
+
+The module is ESM: bundle the worker (e.g. vite-plugin-pwa `injectManifest`) or register it with
+`{ type: 'module' }`.

package/dist/api.d.ts

@@ -0,0 +1,42 @@
+/** A browser subscription as `PushSubscription.toJSON()` serializes it — the body the server stores. */
+export interface WebPushSubscriptionJson {
+    endpoint: string;
+    expirationTime?: number | null;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+}
+/**
+ * The three server calls the helpers need. Use {@link fetchWebPushApi} with `MapElarionWebPush()`, or adapt the
+ * generated JSON-RPC client when the application exposes its own `webPush.*` handlers:
+ *
+ * ```ts
+ * const api: WebPushServerApi = {
+ *   getPublicKey: async () => (await rpc.webPush.publicKey({})).publicKey,
+ *   subscribe: async (subscription) => { await rpc.webPush.subscribe(subscription) },
+ *   unsubscribe: async (endpoint) => { await rpc.webPush.unsubscribe({ endpoint }) },
+ * }
+ * ```
+ */
+export interface WebPushServerApi {
+    /** The VAPID public key (base64url) to subscribe against. */
+    getPublicKey(): Promise<string>;
+    /** Stores the subscription for the signed-in user (idempotent). */
+    subscribe(subscription: WebPushSubscriptionJson): Promise<void>;
+    /** Deletes the signed-in user's subscription for the endpoint. */
+    unsubscribe(endpoint: string): Promise<void>;
+}
+/** Options for {@link fetchWebPushApi}. */
+export interface FetchWebPushApiOptions {
+    /** The prefix `MapElarionWebPush` was mapped at. Defaults to `/webpush`. */
+    baseUrl?: string;
+    /** Extra headers per request, e.g. a bearer token. Cookies are sent same-origin by default. */
+    headers?: () => HeadersInit | Promise<HeadersInit>;
+    /** The `fetch` implementation. Defaults to the global one. */
+    fetch?: typeof fetch;
+}
+/** A {@link WebPushServerApi} over the endpoints `app.MapElarionWebPush()` maps. */
+export declare function fetchWebPushApi(options?: FetchWebPushApiOptions): WebPushServerApi;
+/** Serializes a live subscription, failing loudly if the browser omitted its keys. */
+export declare function toSubscriptionJson(subscription: PushSubscription): WebPushSubscriptionJson;

package/dist/api.js

@@ -0,0 +1,40 @@
+/** A {@link WebPushServerApi} over the endpoints `app.MapElarionWebPush()` maps. */
+export function fetchWebPushApi(options = {}) {
+    const baseUrl = (options.baseUrl ?? '/webpush').replace(/\/+$/, '');
+    async function call(path, body) {
+        const doFetch = options.fetch ?? globalThis.fetch;
+        const headers = new Headers(options.headers ? await options.headers() : undefined);
+        if (body !== undefined)
+            headers.set('Content-Type', 'application/json');
+        const response = await doFetch(`${baseUrl}${path}`, {
+            method: body === undefined ? 'GET' : 'POST',
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+            credentials: 'same-origin',
+        });
+        if (!response.ok)
+            throw new Error(`Web Push ${path} failed with HTTP ${response.status}.`);
+        return response;
+    }
+    return {
+        async getPublicKey() {
+            const { publicKey } = (await (await call('/public-key')).json());
+            return publicKey;
+        },
+        async subscribe(subscription) {
+            await call('/subscribe', subscription);
+        },
+        async unsubscribe(endpoint) {
+            await call('/unsubscribe', { endpoint });
+        },
+    };
+}
+/** Serializes a live subscription, failing loudly if the browser omitted its keys. */
+export function toSubscriptionJson(subscription) {
+    const json = subscription.toJSON();
+    const p256dh = json.keys?.['p256dh'];
+    const auth = json.keys?.['auth'];
+    if (!json.endpoint || !p256dh || !auth)
+        throw new Error('The push subscription has no endpoint or keys.');
+    return { endpoint: json.endpoint, expirationTime: json.expirationTime ?? null, keys: { p256dh, auth } };
+}

package/dist/base64url.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Decodes a base64url string (the VAPID public key as the server hands it out) into the bytes
+ * `pushManager.subscribe({ applicationServerKey })` expects.
+ */
+export declare function urlBase64ToUint8Array(value: string): Uint8Array<ArrayBuffer>;
+/** Whether a subscription's `options.applicationServerKey` is the given key. */
+export declare function isSameKey(current: ArrayBuffer | null | undefined, expected: Uint8Array): boolean;

package/dist/base64url.js

@@ -0,0 +1,22 @@
+/**
+ * Decodes a base64url string (the VAPID public key as the server hands it out) into the bytes
+ * `pushManager.subscribe({ applicationServerKey })` expects.
+ */
+export function urlBase64ToUint8Array(value) {
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (value.length % 4)) % 4);
+    const binary = atob(base64);
+    const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+/** Whether a subscription's `options.applicationServerKey` is the given key. */
+export function isSameKey(current, expected) {
+    if (!current || current.byteLength !== expected.byteLength)
+        return false;
+    const actual = new Uint8Array(current);
+    for (let i = 0; i < actual.length; i++)
+        if (actual[i] !== expected[i])
+            return false;
+    return true;
+}

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { type WebPushServerApi } from './api.js';
+export { fetchWebPushApi, toSubscriptionJson, type FetchWebPushApiOptions, type WebPushServerApi, type WebPushSubscriptionJson, } from './api.js';
+export { urlBase64ToUint8Array } from './base64url.js';
+/**
+ * Whether this browser can receive pushes:
+ * - `available` — offer the switch.
+ * - `install-first` — iOS/iPadOS Safari outside a Home Screen app, where `PushManager` does not exist until
+ *   the site is added to the Home Screen (iOS 16.4+). Say "add to Home Screen first" instead of offering a
+ *   switch that can never turn on.
+ * - `unsupported` — no Web Push here (an old browser or iOS before 16.4, a non-secure context, …).
+ */
+export type PushAvailability = 'available' | 'install-first' | 'unsupported';
+/** What {@link enablePush} achieved. `dismissed` means the prompt was closed without a choice — it may be offered again. */
+export type EnablePushOutcome = 'subscribed' | 'denied' | 'dismissed' | 'install-first' | 'unsupported';
+/** 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.
+     */
+    registration?: ServiceWorkerRegistration;
+}
+/** Detects push support; see {@link PushAvailability}. Safe to call during rendering. */
+export declare function pushAvailability(): PushAvailability;
+/**
+ * Asks for notification permission and subscribes. Call it directly from a click handler: the permission
+ * request is issued before the first `await`, because Safari only honours one made synchronously inside the
+ * user gesture.
+ */
+export declare function enablePush(api: WebPushServerApi, options?: PushHelperOptions): Promise<EnablePushOutcome>;
+/**
+ * Subscribes this browser (permission must already be granted) and stores the subscription on the server.
+ * An existing subscription for the same server key is reused; one for a rotated key is replaced.
+ */
+export declare function subscribe(api: WebPushServerApi, options?: PushHelperOptions): Promise<PushSubscription>;
+/**
+ * Removes this browser's subscription — on the server first, so a failed call leaves both sides subscribed
+ * rather than the server holding a dead subscription. Returns `false` when there was none.
+ */
+export declare function unsubscribe(api: WebPushServerApi, options?: PushHelperOptions): Promise<boolean>;
+/** Whether this browser currently holds a push subscription with notification permission granted. */
+export declare function isSubscribed(options?: PushHelperOptions): Promise<boolean>;
+/**
+ * Call once on app start. When the user has granted permission, re-sends (or re-creates) the subscription so
+ * the server's copy heals after the push service rotated it, the server key changed, or a cleanup deleted
+ * it — and so its last-seen time stays fresh. Never prompts. Returns whether a subscription was refreshed.
+ */
+export declare function refreshOnStart(api: WebPushServerApi, options?: PushHelperOptions): Promise<boolean>;

package/dist/index.js

@@ -0,0 +1,110 @@
+// The browser half of Elarion Web Push (ADR-0076): detect whether this browser can receive pushes at all,
+// ask for permission inside the user gesture, and keep the server's copy of the subscription in step with
+// the browser's. Server calls go through a pluggable WebPushServerApi, so the same helpers work against
+// `MapElarionWebPush()` or an application's own `webPush.*` handlers via the generated JSON-RPC client.
+//
+// The service-worker half (showing the notification, handling its click, and re-subscribing when the push
+// service rotates a subscription) is the `/sw` sub-export.
+import { toSubscriptionJson } from './api.js';
+import { isSameKey, urlBase64ToUint8Array } from './base64url.js';
+export { fetchWebPushApi, toSubscriptionJson, } from './api.js';
+export { urlBase64ToUint8Array } from './base64url.js';
+/** Detects push support; see {@link PushAvailability}. Safe to call during rendering. */
+export function pushAvailability() {
+    if (typeof navigator === 'undefined' || typeof window === 'undefined')
+        return 'unsupported';
+    if ('serviceWorker' in navigator && 'PushManager' in window && 'Notification' in window)
+        return 'available';
+    const ios = iosVersion();
+    if (ios === undefined || isStandalone())
+        return 'unsupported';
+    // Web Push reached iOS/iPadOS in 16.4, and only for Home Screen apps.
+    return ios[0] > 16 || (ios[0] === 16 && ios[1] >= 4) ? 'install-first' : 'unsupported';
+}
+/**
+ * Asks for notification permission and subscribes. Call it directly from a click handler: the permission
+ * request is issued before the first `await`, because Safari only honours one made synchronously inside the
+ * user gesture.
+ */
+export function enablePush(api, options = {}) {
+    const availability = pushAvailability();
+    if (availability !== 'available')
+        return Promise.resolve(availability);
+    const permission = Notification.permission === 'granted' ? Promise.resolve('granted') : Notification.requestPermission();
+    return permission.then(async (result) => {
+        if (result === 'denied')
+            return 'denied';
+        if (result !== 'granted')
+            return 'dismissed';
+        await subscribe(api, options);
+        return 'subscribed';
+    });
+}
+/**
+ * Subscribes this browser (permission must already be granted) and stores the subscription on the server.
+ * An existing subscription for the same server key is reused; one for a rotated key is replaced.
+ */
+export async function subscribe(api, options = {}) {
+    const registration = await resolveRegistration(options);
+    const key = urlBase64ToUint8Array(await api.getPublicKey());
+    let subscription = await registration.pushManager.getSubscription();
+    if (subscription && !isSameKey(subscription.options.applicationServerKey, key)) {
+        await subscription.unsubscribe();
+        subscription = null;
+    }
+    subscription ??= await registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: key });
+    await api.subscribe(toSubscriptionJson(subscription));
+    return subscription;
+}
+/**
+ * Removes this browser's subscription — on the server first, so a failed call leaves both sides subscribed
+ * rather than the server holding a dead subscription. Returns `false` when there was none.
+ */
+export async function unsubscribe(api, options = {}) {
+    if (pushAvailability() !== 'available')
+        return false;
+    const registration = await resolveRegistration(options);
+    const subscription = await registration.pushManager.getSubscription();
+    if (!subscription)
+        return false;
+    await api.unsubscribe(subscription.endpoint);
+    await subscription.unsubscribe();
+    return true;
+}
+/** Whether this browser currently holds a push subscription with notification permission granted. */
+export async function isSubscribed(options = {}) {
+    if (pushAvailability() !== 'available' || Notification.permission !== 'granted')
+        return false;
+    const registration = await resolveRegistration(options);
+    return (await registration.pushManager.getSubscription()) !== null;
+}
+/**
+ * Call once on app start. When the user has granted permission, re-sends (or re-creates) the subscription so
+ * the server's copy heals after the push service rotated it, the server key changed, or a cleanup deleted
+ * it — and so its last-seen time stays fresh. Never prompts. Returns whether a subscription was refreshed.
+ */
+export async function refreshOnStart(api, options = {}) {
+    if (pushAvailability() !== 'available' || Notification.permission !== 'granted')
+        return false;
+    await subscribe(api, options);
+    return true;
+}
+async function resolveRegistration(options) {
+    return options.registration ?? navigator.serviceWorker.ready;
+}
+function iosVersion() {
+    const userAgent = navigator.userAgent;
+    const match = /(?:iPhone|iPad|iPod).* OS (\d+)_(\d+)/.exec(userAgent);
+    if (match)
+        return [Number(match[1]), Number(match[2])];
+    // iPadOS 13+ Safari presents a desktop Mac user agent; a touch-capable "Mac" is an iPad.
+    if (navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1) {
+        const version = /Version\/(\d+)\.(\d+)/.exec(userAgent);
+        return version ? [Number(version[1]), Number(version[2])] : undefined;
+    }
+    return undefined;
+}
+function isStandalone() {
+    return (navigator.standalone === true ||
+        (typeof window.matchMedia === 'function' && window.matchMedia('(display-mode: standalone)').matches));
+}

package/dist/sw.d.ts

@@ -0,0 +1,50 @@
+import { type WebPushServerApi } from './api.js';
+/** The payload `IWebPushSender` sends. */
+export interface WebPushPayload {
+    title: string;
+    body: string;
+    url?: string;
+    tag?: string;
+}
+/** Options for {@link registerWebPushHandlers}. */
+export interface WebPushServiceWorkerOptions {
+    /**
+     * Where a `pushsubscriptionchange` re-subscription is sent. Defaults to `fetchWebPushApi()` (the
+     * `MapElarionWebPush` endpoints, authenticated by same-origin cookies). A bearer-token app, which has no
+     * token in the worker, can rely on the page's `refreshOnStart` instead and pass `null` to skip it.
+     */
+    api?: WebPushServerApi | null;
+    /** The notification icon URL. */
+    icon?: string;
+    /** The monochrome status-bar badge URL (Android). */
+    badge?: string;
+    /** Where a click navigates when the payload has no `url`. Defaults to the service worker's scope. */
+    defaultUrl?: string;
+    /** The title shown when a push carries no parseable payload (its text becomes the body). Defaults to 'New notification'. */
+    fallbackTitle?: string;
+    /** Adds or overrides notification options per payload (actions, vibration, `requireInteraction`, …). */
+    notificationOptions?: (payload: WebPushPayload) => NotificationOptions;
+}
+/**
+ * The parts of `ServiceWorkerGlobalScope` the handlers use — structural, so the real `self` fits without this
+ * package depending on the WebWorker type library.
+ */
+export interface WebPushServiceWorkerScope {
+    addEventListener(type: string, listener: (event: any) => void): void;
+    readonly registration: {
+        readonly scope: string;
+        readonly pushManager: PushManager;
+        showNotification(title: string, options?: NotificationOptions): Promise<void>;
+    };
+    readonly clients: {
+        matchAll(options?: {
+            type?: 'window';
+            includeUncontrolled?: boolean;
+        }): Promise<ReadonlyArray<{
+            readonly url: string;
+        }>>;
+        openWindow(url: string): Promise<unknown>;
+    };
+}
+/** Registers the `push`, `notificationclick`, and `pushsubscriptionchange` handlers on `scope`. */
+export declare function registerWebPushHandlers(scope: WebPushServiceWorkerScope, options?: WebPushServiceWorkerOptions): void;

package/dist/sw.js

@@ -0,0 +1,92 @@
+// The service-worker half of Elarion Web Push (ADR-0076). Import it into the application's service worker —
+// through its bundler (e.g. vite-plugin-pwa's injectManifest) or a `type: 'module'` registration — and call
+// registerWebPushHandlers(self) once at the top level:
+//
+//   import { registerWebPushHandlers } from '@swimmesberger/elarion-webpush/sw'
+//   registerWebPushHandlers(self, { icon: '/icons/192.png' })
+//
+// It shows the `{title, body, url, tag}` payload IWebPushSender sends, focuses or opens the app at the
+// payload's URL on click, and re-subscribes when the push service rotates a subscription.
+import { fetchWebPushApi, toSubscriptionJson } from './api.js';
+import { urlBase64ToUint8Array } from './base64url.js';
+/** Registers the `push`, `notificationclick`, and `pushsubscriptionchange` handlers on `scope`. */
+export function registerWebPushHandlers(scope, options = {}) {
+    const api = options.api === undefined ? fetchWebPushApi() : options.api;
+    scope.addEventListener('push', (event) => {
+        const payload = parsePayload(event.data?.text(), options);
+        // Always show something: a push with userVisibleOnly that displays nothing is penalized by the browser.
+        event.waitUntil(scope.registration.showNotification(payload.title, {
+            body: payload.body,
+            tag: payload.tag,
+            icon: options.icon,
+            badge: options.badge,
+            data: { url: payload.url },
+            ...options.notificationOptions?.(payload),
+        }));
+    });
+    scope.addEventListener('notificationclick', (event) => {
+        event.notification.close();
+        const data = event.notification.data;
+        const relative = typeof data?.url === 'string' ? data.url : (options.defaultUrl ?? scope.registration.scope);
+        event.waitUntil(focusOrOpen(scope, new URL(relative, scope.registration.scope).href));
+    });
+    scope.addEventListener('pushsubscriptionchange', (event) => {
+        if (!api)
+            return;
+        event.waitUntil(resubscribe(scope, api, event).catch(() => {
+            // Nothing else to do from the worker; the page's refreshOnStart heals it on the next visit.
+        }));
+    });
+}
+function parsePayload(text, options) {
+    if (text) {
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed.title === 'string') {
+                return {
+                    title: parsed.title,
+                    body: typeof parsed.body === 'string' ? parsed.body : '',
+                    url: typeof parsed.url === 'string' ? parsed.url : undefined,
+                    tag: typeof parsed.tag === 'string' ? parsed.tag : undefined,
+                };
+            }
+        }
+        catch {
+            // Not our JSON payload — show it as plain text below.
+        }
+    }
+    return { title: options.fallbackTitle ?? 'New notification', body: text ?? '' };
+}
+async function focusOrOpen(scope, url) {
+    // type: 'window' makes every match a WindowClient.
+    const windows = (await scope.clients.matchAll({ type: 'window', includeUncontrolled: true }));
+    const exact = windows.find((client) => client.url === url);
+    if (exact) {
+        await exact.focus();
+        return;
+    }
+    // Prefer reusing an open window of the app (one installed-PWA window) over opening a second one.
+    const same = windows.find((client) => new URL(client.url).origin === new URL(url).origin && client.navigate);
+    if (same?.navigate) {
+        try {
+            await same.navigate(url);
+            await same.focus();
+            return;
+        }
+        catch {
+            // An uncontrolled client cannot be navigated; fall through to a new window.
+        }
+    }
+    await scope.clients.openWindow(url);
+}
+async function resubscribe(scope, api, event) {
+    const old = event.oldSubscription ?? null;
+    const replacement = event.newSubscription ??
+        (await scope.registration.pushManager.subscribe({
+            userVisibleOnly: true,
+            applicationServerKey: old?.options.applicationServerKey ?? urlBase64ToUint8Array(await api.getPublicKey()),
+        }));
+    await api.subscribe(toSubscriptionJson(replacement));
+    if (old && old.endpoint !== replacement.endpoint)
+        await api.unsubscribe(old.endpoint).catch(() => undefined);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@swimmesberger/elarion-webpush",
+  "version": "0.0.0",
+  "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",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sw": {
+      "types": "./dist/sw.d.ts",
+      "import": "./dist/sw.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json && tsc --noEmit -p tsconfig.sw-test.json",
+    "test": "npm run typecheck && vitest run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/swimmesberger/Elarion.git",
+    "directory": "src/elarion-webpush"
+  },
+  "bugs": {
+    "url": "https://github.com/swimmesberger/Elarion/issues"
+  },
+  "homepage": "https://github.com/swimmesberger/Elarion#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}