tiny-essentials 1.28.19 → 1.29.1

package/dist/v1/libs/sw/browser/TinyNotificationAdapter.cjs

@@ -0,0 +1,126 @@
+'use strict';
+
+var utils = require('../utils.cjs');
+
+/** @typedef {import('../utils.mjs').TinyPushNotification} TinyPushNotification */
+
+/**
+ * Options accepted by the page level `Notification` constructor.
+ *
+ * @typedef {Object} BrowserNotificationOptions
+ * @property {string} [body] - The main text of the notification, shown below the title.
+ * @property {string} [icon] - URL of the image used as the notification icon.
+ * @property {string} [image] - URL of an image shown inside the notification body.
+ * @property {string} [tag] - Identifier used to group and replace notifications sharing the same tag.
+ * @property {string} [lang] - BCP 47 language tag describing the notification text.
+ * @property {'auto'|'ltr'|'rtl'} [dir] - Text direction used to render the notification content.
+ * @property {boolean} [renotify] - Whether to notify the user again when a notification with the same `tag` is replaced.
+ * @property {boolean} [requireInteraction] - Whether the notification stays visible until the user interacts with it.
+ * @property {boolean} [silent] - Whether the notification is shown without sound or vibration feedback.
+ * @property {number} [timestamp] - Time the notification was created, in milliseconds since the Unix epoch.
+ * @property {number[]} [vibrate] - Vibration pattern, in milliseconds, applied on supported devices.
+ * @property {Record<string, unknown>} [data] - Arbitrary payload attached to the notification for later retrieval.
+ */
+
+/**
+ * A notification already adapted to the page environment.
+ *
+ * @typedef {Object} BrowserNotification
+ * @property {string} title - The headline text displayed at the top of the notification.
+ * @property {BrowserNotificationOptions} options - The configuration applied to the notification.
+ */
+
+/**
+ * Adapts notification descriptors between the Service Worker and the page.
+ *
+ * The class is a static-only utility and is never instantiated. It normalizes
+ * the payload in both directions: a descriptor produced by the Service Worker
+ * can be safely handed to the page level `Notification` constructor through
+ * {@link TinyNotificationAdapter.toBrowser}, and a page level notification can
+ * be converted back into a Service Worker payload through
+ * {@link TinyNotificationAdapter.toServiceWorker}.
+ *
+ * @beta
+ */
+class TinyNotificationAdapter {
+  static PUSH_TYPE = utils.PUSH_TYPE;
+  /** @type {readonly string[]} */
+  static #SW_ONLY_KEYS = Object.freeze(['actions', 'badge']);
+
+  /**
+   * SW -> Browser. Use before `new Notification(...)`.
+   *
+   * @param {TinyPushNotification|null} notification - Descriptor sent by the Service Worker.
+   * @param {Partial<BrowserNotificationOptions>} [overrides] - Values that win over the descriptor.
+   * @returns {BrowserNotification} The notification adapted for the page environment.
+   * @throws {TypeError} If `notification` is neither `null` nor a non-null object.
+   */
+  static toBrowser(notification, overrides = {}) {
+    if (
+      notification !== null &&
+      (typeof notification !== 'object' || Array.isArray(notification))
+    ) {
+      throw new TypeError(
+        '[TinyNotificationAdapter] toBrowser: notification must be a non-null object.',
+      );
+    }
+    if (typeof overrides !== 'object' || overrides === null || Array.isArray(overrides)) {
+      throw new TypeError(
+        '[TinyNotificationAdapter] toBrowser: overrides must be a non-null object.',
+      );
+    }
+    const { title, ...rest } = notification ?? {};
+    /** @type {BrowserNotificationOptions} */
+    const options = {};
+    for (const [key, value] of Object.entries(rest)) {
+      if (TinyNotificationAdapter.#SW_ONLY_KEYS.includes(key)) continue;
+      if (typeof value === 'undefined') continue;
+      // @ts-ignore - the key comes from a validated descriptor.
+      options[key] = value;
+    }
+    // `dir` is the only field whose DOM type is a closed union, so an arbitrary
+    // string coming from the wire must be narrowed before it reaches the
+    // `Notification` constructor.
+    if (options.dir !== 'auto' && options.dir !== 'ltr' && options.dir !== 'rtl') {
+      delete options.dir;
+    }
+    // `renotify` without `tag` throws on Chromium.
+    if (options.renotify === true && typeof options.tag !== 'string') {
+      delete options.renotify;
+    }
+    return {
+      title: typeof title === 'string' && title !== '' ? title : 'Notification',
+      options: { ...options, ...overrides },
+    };
+  }
+
+  /**
+   * Browser -> SW. Use before sending a click/close back to the Service Worker.
+   *
+   * @param {BrowserNotification} notification - The value returned by {@link TinyNotificationAdapter.toBrowser}.
+   * @param {Partial<BrowserNotificationOptions>} [overrides] - Values that win over the descriptor.
+   * @returns {{ title: string, body: string, options: BrowserNotificationOptions }} The payload shaped for the Service Worker, with a guaranteed string `body`.
+   * @throws {TypeError} If `notification` is not a non-null object.
+   */
+  static toServiceWorker(notification, overrides = {}) {
+    if (typeof notification !== 'object' || notification === null || Array.isArray(notification)) {
+      throw new TypeError(
+        '[TinyNotificationAdapter] toServiceWorker: notification must be a non-null object.',
+      );
+    }
+    if (typeof overrides !== 'object' || overrides === null || Array.isArray(overrides)) {
+      throw new TypeError(
+        '[TinyNotificationAdapter] toServiceWorker: overrides must be a non-null object.',
+      );
+    }
+    const { title = 'Notification', options = {} } = notification;
+    const merged = { ...options, ...overrides };
+    return {
+      title,
+      body: typeof merged.body === 'string' ? merged.body : '',
+      options: merged,
+    };
+  }
+}
+
+module.exports = TinyNotificationAdapter;

package/dist/v1/libs/sw/browser/TinyNotificationAdapter.d.mts

@@ -0,0 +1,132 @@
+export type TinyPushNotification = import('../utils.mjs').TinyPushNotification;
+export type BrowserNotificationOptions = {
+    /**
+     * - The main text of the notification, shown below the title.
+     */
+    body?: string;
+    /**
+     * - URL of the image used as the notification icon.
+     */
+    icon?: string;
+    /**
+     * - URL of an image shown inside the notification body.
+     */
+    image?: string;
+    /**
+     * - Identifier used to group and replace notifications sharing the same tag.
+     */
+    tag?: string;
+    /**
+     * - BCP 47 language tag describing the notification text.
+     */
+    lang?: string;
+    /**
+     * - Text direction used to render the notification content.
+     */
+    dir?: 'auto' | 'ltr' | 'rtl';
+    /**
+     * - Whether to notify the user again when a notification with the same `tag` is replaced.
+     */
+    renotify?: boolean;
+    /**
+     * - Whether the notification stays visible until the user interacts with it.
+     */
+    requireInteraction?: boolean;
+    /**
+     * - Whether the notification is shown without sound or vibration feedback.
+     */
+    silent?: boolean;
+    /**
+     * - Time the notification was created, in milliseconds since the Unix epoch.
+     */
+    timestamp?: number;
+    /**
+     * - Vibration pattern, in milliseconds, applied on supported devices.
+     */
+    vibrate?: number[];
+    /**
+     * - Arbitrary payload attached to the notification for later retrieval.
+     */
+    data?: Record<string, unknown>;
+};
+export type BrowserNotification = {
+    /**
+     * - The headline text displayed at the top of the notification.
+     */
+    title: string;
+    /**
+     * - The configuration applied to the notification.
+     */
+    options: BrowserNotificationOptions;
+};
+/** @typedef {import('../utils.mjs').TinyPushNotification} TinyPushNotification */
+/**
+ * Options accepted by the page level `Notification` constructor.
+ *
+ * @typedef {Object} BrowserNotificationOptions
+ * @property {string} [body] - The main text of the notification, shown below the title.
+ * @property {string} [icon] - URL of the image used as the notification icon.
+ * @property {string} [image] - URL of an image shown inside the notification body.
+ * @property {string} [tag] - Identifier used to group and replace notifications sharing the same tag.
+ * @property {string} [lang] - BCP 47 language tag describing the notification text.
+ * @property {'auto'|'ltr'|'rtl'} [dir] - Text direction used to render the notification content.
+ * @property {boolean} [renotify] - Whether to notify the user again when a notification with the same `tag` is replaced.
+ * @property {boolean} [requireInteraction] - Whether the notification stays visible until the user interacts with it.
+ * @property {boolean} [silent] - Whether the notification is shown without sound or vibration feedback.
+ * @property {number} [timestamp] - Time the notification was created, in milliseconds since the Unix epoch.
+ * @property {number[]} [vibrate] - Vibration pattern, in milliseconds, applied on supported devices.
+ * @property {Record<string, unknown>} [data] - Arbitrary payload attached to the notification for later retrieval.
+ */
+/**
+ * A notification already adapted to the page environment.
+ *
+ * @typedef {Object} BrowserNotification
+ * @property {string} title - The headline text displayed at the top of the notification.
+ * @property {BrowserNotificationOptions} options - The configuration applied to the notification.
+ */
+/**
+ * Adapts notification descriptors between the Service Worker and the page.
+ *
+ * The class is a static-only utility and is never instantiated. It normalizes
+ * the payload in both directions: a descriptor produced by the Service Worker
+ * can be safely handed to the page level `Notification` constructor through
+ * {@link TinyNotificationAdapter.toBrowser}, and a page level notification can
+ * be converted back into a Service Worker payload through
+ * {@link TinyNotificationAdapter.toServiceWorker}.
+ *
+ * @beta
+ */
+declare class TinyNotificationAdapter {
+    #private;
+    static PUSH_TYPE: Readonly<{
+        NOTIFICATION: "notification";
+        DATA: "data";
+        SYNC: "sync";
+        COMMAND: "command";
+        UNKNOWN: "unknown";
+    }>;
+    /**
+     * SW -> Browser. Use before `new Notification(...)`.
+     *
+     * @param {TinyPushNotification|null} notification - Descriptor sent by the Service Worker.
+     * @param {Partial<BrowserNotificationOptions>} [overrides] - Values that win over the descriptor.
+     * @returns {BrowserNotification} The notification adapted for the page environment.
+     * @throws {TypeError} If `notification` is neither `null` nor a non-null object.
+     */
+    static toBrowser(notification: TinyPushNotification | null, overrides?: Partial<BrowserNotificationOptions>): BrowserNotification;
+    /**
+     * Browser -> SW. Use before sending a click/close back to the Service Worker.
+     *
+     * @param {BrowserNotification} notification - The value returned by {@link TinyNotificationAdapter.toBrowser}.
+     * @param {Partial<BrowserNotificationOptions>} [overrides] - Values that win over the descriptor.
+     * @returns {{ title: string, body: string, options: BrowserNotificationOptions }} The payload shaped for the Service Worker, with a guaranteed string `body`.
+     * @throws {TypeError} If `notification` is not a non-null object.
+     */
+    static toServiceWorker(notification: BrowserNotification, overrides?: Partial<BrowserNotificationOptions>): {
+        title: string;
+        body: string;
+        options: BrowserNotificationOptions;
+    };
+}
+export default TinyNotificationAdapter;
+//# sourceMappingURL=TinyNotificationAdapter.d.mts.map

package/dist/v1/libs/sw/browser/TinyNotificationAdapter.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TinyNotificationAdapter.d.mts","sourceRoot":"","sources":["../../../../../src/v1/libs/sw/browser/TinyNotificationAdapter.mjs"],"names":[],"mappings":"AAEI,YAAuD,oBAAoB,GAAjE,OAAO,cAAc,EAAE,oBAAoB,CAAsB;AAK5E,YAAkB,0BAA0B,GAC5C;;;;IAAoB,IAAI,AAAxB,CACA,EADW,MAAM,CACjB;;;;IAAoB,IAAI,AAAxB,CACA,EADW,MAAM,CACjB;;;;IAAoB,KAAK,AAAzB,CACA,EADW,MAAM,CACjB;;;;IAAoB,GAAG,AAAvB,CACA,EADW,MAAM,CACjB;;;;IAAoB,IAAI,AAAxB,CACA,EADW,MAAM,CACjB;;;;IAAgC,GAAG,AAAnC,CACA,EADW,MAAM,GAAC,KAAK,GAAC,KAAK,CAC7B;;;;IAAqB,QAAQ,AAA7B,CACA,EADW,OAAO,CAClB;;;;IAAqB,kBAAkB,AAAvC,CACA,EADW,OAAO,CAClB;;;;IAAqB,MAAM,AAA3B,CACA,EADW,OAAO,CAClB;;;;IAAoB,SAAS,AAA7B,CACA,EADW,MAAM,CACjB;;;;IAAsB,OAAO,AAA7B,CACA,EADW,MAAM,EAAE,CACnB;;;;IAAqC,IAAI,AAAzC,CACF,EADa,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACpC;CAAA,CAAA;AAKE,YAAkB,mBAAmB,GACrC;;;;IAAmB,KAAK,EAAb,MAAM,CACjB;;;;IAAuC,OAAO,EAAnC,0BAA0B,CACvC;CAAA,CAAA;AA1BD,kFAAkF;AAElF;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AACH,cAAM,uBAAuB;;IAC3B,MAAM,CAAC,SAAS;;;;;;OAAa;IAI7B;;;;;;;OAOG;IACH,MAAM,CAAC,SAAS,CAAC,YAAY,EALlB,oBAAoB,GAAC,IAKH,EAAE,SAAS,AAJrC,CACA,EADQ,OAAO,CAAC,0BAA0B,CAIA,GAHhC,mBAAmB,CAwC/B;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,eAAe,CAAC,YAAY,EALxB,mBAKwB,EAAE,SAAS,AAJ3C,CACA,EADQ,OAAO,CAAC,0BAA0B,CAIM,GAHtC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,0BAA0B,CAAA;KAAE,CAqBhF;CACF;eAEc,uBAAuB"}

package/dist/v1/libs/sw/browser/TinyNotificationAdapter.mjs

@@ -0,0 +1,109 @@
+import { PUSH_TYPE } from '../utils.mjs';
+/** @typedef {import('../utils.mjs').TinyPushNotification} TinyPushNotification */
+/**
+ * Options accepted by the page level `Notification` constructor.
+ *
+ * @typedef {Object} BrowserNotificationOptions
+ * @property {string} [body] - The main text of the notification, shown below the title.
+ * @property {string} [icon] - URL of the image used as the notification icon.
+ * @property {string} [image] - URL of an image shown inside the notification body.
+ * @property {string} [tag] - Identifier used to group and replace notifications sharing the same tag.
+ * @property {string} [lang] - BCP 47 language tag describing the notification text.
+ * @property {'auto'|'ltr'|'rtl'} [dir] - Text direction used to render the notification content.
+ * @property {boolean} [renotify] - Whether to notify the user again when a notification with the same `tag` is replaced.
+ * @property {boolean} [requireInteraction] - Whether the notification stays visible until the user interacts with it.
+ * @property {boolean} [silent] - Whether the notification is shown without sound or vibration feedback.
+ * @property {number} [timestamp] - Time the notification was created, in milliseconds since the Unix epoch.
+ * @property {number[]} [vibrate] - Vibration pattern, in milliseconds, applied on supported devices.
+ * @property {Record<string, unknown>} [data] - Arbitrary payload attached to the notification for later retrieval.
+ */
+/**
+ * A notification already adapted to the page environment.
+ *
+ * @typedef {Object} BrowserNotification
+ * @property {string} title - The headline text displayed at the top of the notification.
+ * @property {BrowserNotificationOptions} options - The configuration applied to the notification.
+ */
+/**
+ * Adapts notification descriptors between the Service Worker and the page.
+ *
+ * The class is a static-only utility and is never instantiated. It normalizes
+ * the payload in both directions: a descriptor produced by the Service Worker
+ * can be safely handed to the page level `Notification` constructor through
+ * {@link TinyNotificationAdapter.toBrowser}, and a page level notification can
+ * be converted back into a Service Worker payload through
+ * {@link TinyNotificationAdapter.toServiceWorker}.
+ *
+ * @beta
+ */
+class TinyNotificationAdapter {
+    static PUSH_TYPE = PUSH_TYPE;
+    /** @type {readonly string[]} */
+    static #SW_ONLY_KEYS = Object.freeze(['actions', 'badge']);
+    /**
+     * SW -> Browser. Use before `new Notification(...)`.
+     *
+     * @param {TinyPushNotification|null} notification - Descriptor sent by the Service Worker.
+     * @param {Partial<BrowserNotificationOptions>} [overrides] - Values that win over the descriptor.
+     * @returns {BrowserNotification} The notification adapted for the page environment.
+     * @throws {TypeError} If `notification` is neither `null` nor a non-null object.
+     */
+    static toBrowser(notification, overrides = {}) {
+        if (notification !== null &&
+            (typeof notification !== 'object' || Array.isArray(notification))) {
+            throw new TypeError('[TinyNotificationAdapter] toBrowser: notification must be a non-null object.');
+        }
+        if (typeof overrides !== 'object' || overrides === null || Array.isArray(overrides)) {
+            throw new TypeError('[TinyNotificationAdapter] toBrowser: overrides must be a non-null object.');
+        }
+        const { title, ...rest } = notification ?? {};
+        /** @type {BrowserNotificationOptions} */
+        const options = {};
+        for (const [key, value] of Object.entries(rest)) {
+            if (TinyNotificationAdapter.#SW_ONLY_KEYS.includes(key))
+                continue;
+            if (typeof value === 'undefined')
+                continue;
+            // @ts-ignore - the key comes from a validated descriptor.
+            options[key] = value;
+        }
+        // `dir` is the only field whose DOM type is a closed union, so an arbitrary
+        // string coming from the wire must be narrowed before it reaches the
+        // `Notification` constructor.
+        if (options.dir !== 'auto' && options.dir !== 'ltr' && options.dir !== 'rtl') {
+            delete options.dir;
+        }
+        // `renotify` without `tag` throws on Chromium.
+        if (options.renotify === true && typeof options.tag !== 'string') {
+            delete options.renotify;
+        }
+        return {
+            title: typeof title === 'string' && title !== '' ? title : 'Notification',
+            options: { ...options, ...overrides },
+        };
+    }
+    /**
+     * Browser -> SW. Use before sending a click/close back to the Service Worker.
+     *
+     * @param {BrowserNotification} notification - The value returned by {@link TinyNotificationAdapter.toBrowser}.
+     * @param {Partial<BrowserNotificationOptions>} [overrides] - Values that win over the descriptor.
+     * @returns {{ title: string, body: string, options: BrowserNotificationOptions }} The payload shaped for the Service Worker, with a guaranteed string `body`.
+     * @throws {TypeError} If `notification` is not a non-null object.
+     */
+    static toServiceWorker(notification, overrides = {}) {
+        if (typeof notification !== 'object' || notification === null || Array.isArray(notification)) {
+            throw new TypeError('[TinyNotificationAdapter] toServiceWorker: notification must be a non-null object.');
+        }
+        if (typeof overrides !== 'object' || overrides === null || Array.isArray(overrides)) {
+            throw new TypeError('[TinyNotificationAdapter] toServiceWorker: overrides must be a non-null object.');
+        }
+        const { title = 'Notification', options = {} } = notification;
+        const merged = { ...options, ...overrides };
+        return {
+            title,
+            body: typeof merged.body === 'string' ? merged.body : '',
+            options: merged,
+        };
+    }
+}
+export default TinyNotificationAdapter;

package/dist/v1/libs/sw/browser/TinyPushManager.cjs

@@ -0,0 +1,310 @@
+'use strict';
+
+var utils = require('../utils.cjs');
+var utils$1 = require('./utils.cjs');
+
+/**
+ * @file Owns the lifecycle of a `PushSubscription` in the page context.
+ *
+ * The manager never talks to the push service directly: it delegates to
+ * `PushManager` and to two HTTP endpoints that your backend exposes.
+ */
+
+/**
+ * Describes the optional backend routes used to persist or remove a
+ * `PushSubscription`.
+ *
+ * @typedef {Object} TinyPushEndpoints
+ * @property {string} [subscribe] - `POST` route that persists a subscription.
+ * @property {string} [unsubscribe] - `DELETE` route that removes a subscription.
+ */
+
+/**
+ * Describes every option accepted by the `TinyPushManager` constructor.
+ *
+ * @typedef {Object} TinyPushManagerOptions
+ * @property {ServiceWorkerRegistration} registration - The active registration.
+ * @property {string} vapidPublicKey - Base64 URL-safe VAPID public key.
+ * @property {TinyPushEndpoints} [endpoints] - Backend routes.
+ * @property {typeof fetch} [fetch] - Fetch implementation, injectable for tests.
+ * @property {(state: TinyPushState) => void} [onChange] - State observer.
+ */
+
+/**
+ * Represents an immutable snapshot of the manager state exposed to observers.
+ *
+ * @typedef {Object} TinyPushState
+ * @property {'unsupported'|'unsubscribed'|'subscribed'|'denied'|'pending'} status - Current status.
+ * @property {PushSubscription|null} subscription - The active subscription, when any.
+ * @property {string|null} error - The last error message, when any.
+ */
+
+/**
+ * Manages the full lifecycle of a browser `PushSubscription` in the page context.
+ *
+ * The manager is a thin, framework-agnostic wrapper around `PushManager`. It never
+ * talks to a push service directly: it delegates subscription creation to the
+ * `PushManager` API and persistence to two optional backend routes (`subscribe`
+ * and `unsubscribe`). Every state transition is broadcast to the optional
+ * `onChange` observer, which makes it easy to bind the manager to any UI layer.
+ *
+ * @example
+ * const manager = new TinyPushManager({
+ *   registration: await navigator.serviceWorker.ready,
+ *   vapidPublicKey: 'YOUR_PUBLIC_KEY',
+ *   endpoints: { subscribe: '/api/push', unsubscribe: '/api/push' },
+ *   onChange: (state) => console.log(state.status),
+ * });
+ *
+ * await manager.subscribe();
+ *
+ * @beta
+ */
+class TinyPushManager {
+  static #PUSH_TYPE = utils.PUSH_TYPE;
+  static get PUSH_TYPE() {
+    return TinyPushManager.#PUSH_TYPE;
+  }
+
+  /** @type {BufferSource|null} */
+  static #cachedKey = null;
+
+  /** @type {string|null} */
+  static #cachedKeySource = null;
+
+  /**
+   * Reports whether the browser exposes the Push API.
+   * @returns {boolean} `true` when the Push API is available.
+   */
+  static isSupported() {
+    return (
+      typeof globalThis !== 'undefined' &&
+      'serviceWorker' in navigator &&
+      'PushManager' in globalThis &&
+      'Notification' in globalThis
+    );
+  }
+
+  /** @returns {NotificationPermission} The current permission. */
+  static get permission() {
+    return TinyPushManager.isSupported() ? Notification.permission : 'denied';
+  }
+
+  /**
+   * Asks the user for the notification permission.
+   *
+   * @returns {Promise<NotificationPermission>} The resulting permission.
+   * @throws {Error} If the Push API is not supported.
+   */
+  static async requestPermission() {
+    if (!TinyPushManager.isSupported()) {
+      throw new Error('[TinyPushManager] Push API is not supported in this browser.');
+    }
+    return await utils$1.requestNotificationPermission();
+  }
+
+  /**
+   * Decodes a base64 URL-safe VAPID key. The result is memoized per key.
+   *
+   * @param {string} base64 - The VAPID public key.
+   * @returns {BufferSource} The decoded key.
+   * @throws {TypeError} If `base64` is not a non-empty string.
+   */
+  static decodeVapidKey(base64) {
+    if (typeof base64 !== 'string' || base64 === '') {
+      throw new TypeError('[TinyPushManager] decodeVapidKey: base64 must be a non-empty string.');
+    }
+    if (TinyPushManager.#cachedKeySource === base64 && TinyPushManager.#cachedKey) {
+      return TinyPushManager.#cachedKey;
+    }
+
+    const padding = '='.repeat((4 - (base64.length % 4)) % 4);
+    const normalized = (base64 + padding).replace(/-/g, '+').replace(/_/g, '/');
+    const raw = atob(normalized);
+    const bytes = Uint8Array.from(raw, (char) => char.charCodeAt(0));
+
+    TinyPushManager.#cachedKey = bytes;
+    TinyPushManager.#cachedKeySource = base64;
+
+    return bytes;
+  }
+
+  /** @type {ServiceWorkerRegistration} The service worker registration that owns the push subscription. */
+  #registration;
+
+  /** @type {string} The Base64 URL-safe VAPID public key used to create subscriptions. */
+  #vapidPublicKey;
+
+  /** @type {TinyPushEndpoints} The backend routes used to persist and remove subscriptions. */
+  #endpoints;
+
+  /** @type {typeof fetch} The fetch implementation used for backend calls. */
+  #fetch;
+
+  /** @type {((state: TinyPushState) => void)|null} The observer notified whenever the state changes. */
+  #onChange;
+
+  /** @type {TinyPushState} The current internal state of the manager. */
+  #state = { status: 'unsubscribed', subscription: null, error: null };
+
+  /**
+   * Creates a manager bound to a service worker registration.
+   *
+   * @param {TinyPushManagerOptions} options - The manager options.
+   * @throws {TypeError} If `options` is invalid.
+   */
+  constructor(options) {
+    if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+      throw new TypeError('[TinyPushManager] constructor: options must be a non-null object.');
+    }
+
+    const { registration, vapidPublicKey, endpoints = {}, fetch: fetchImpl, onChange } = options;
+
+    if (typeof registration !== 'object' || registration === null) {
+      throw new TypeError('[TinyPushManager] constructor: options.registration is required.');
+    }
+    if (typeof vapidPublicKey !== 'string' || vapidPublicKey === '') {
+      throw new TypeError('[TinyPushManager] constructor: options.vapidPublicKey is required.');
+    }
+    if (endpoints.subscribe !== undefined && typeof endpoints.subscribe !== 'string') {
+      throw new TypeError('[TinyPushManager] constructor: endpoints.subscribe must be a string.');
+    }
+    if (endpoints.unsubscribe !== undefined && typeof endpoints.unsubscribe !== 'string') {
+      throw new TypeError('[TinyPushManager] constructor: endpoints.unsubscribe must be a string.');
+    }
+    if (onChange !== undefined && typeof onChange !== 'function') {
+      throw new TypeError('[TinyPushManager] constructor: onChange must be a function.');
+    }
+
+    this.#registration = registration;
+    this.#vapidPublicKey = vapidPublicKey;
+    this.#endpoints = endpoints;
+    this.#fetch = fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.#onChange = onChange ?? null;
+  }
+
+  /** @returns {TinyPushState} A frozen snapshot of the current state. */
+  get state() {
+    return Object.freeze({ ...this.#state });
+  }
+
+  /**
+   * Returns the current subscription, if any.
+   *
+   * @returns {Promise<PushSubscription|null>} The subscription or `null`.
+   */
+  async getSubscription() {
+    if (!TinyPushManager.isSupported()) return null;
+    return this.#registration.pushManager.getSubscription();
+  }
+
+  /**
+   * Subscribes the user and uploads the subscription to the backend.
+   *
+   * @param {PushSubscriptionOptionsInit} [options] - Extra options merged into `subscribe`.
+   * @returns {Promise<PushSubscription>} The active subscription.
+   * @throws {Error} If the permission is denied or the browser rejects the subscription.
+   */
+  async subscribe(options = {}) {
+    if (!TinyPushManager.isSupported()) {
+      throw new Error('[TinyPushManager] Push API is not supported in this browser.');
+    }
+
+    this.#setState({ status: 'pending', error: null });
+
+    const permission = await TinyPushManager.requestPermission();
+
+    if (permission !== 'granted') {
+      this.#setState({ status: 'denied', subscription: null });
+      throw new Error(`[TinyPushManager] Notification permission was not granted: ${permission}.`);
+    }
+
+    const existing = await this.getSubscription();
+    const subscription =
+      existing ??
+      (await this.#registration.pushManager.subscribe({
+        ...options,
+        userVisibleOnly: true,
+        applicationServerKey: TinyPushManager.decodeVapidKey(this.#vapidPublicKey),
+      }));
+
+    await this.#upload(subscription);
+    this.#setState({ status: 'subscribed', subscription, error: null });
+
+    return subscription;
+  }
+
+  /**
+   * Removes the subscription locally and on the backend.
+   *
+   * @returns {Promise<boolean>} `true` when a subscription was removed.
+   */
+  async unsubscribe() {
+    const subscription = await this.getSubscription();
+
+    if (!subscription) {
+      this.#setState({ status: 'unsubscribed', subscription: null });
+      return false;
+    }
+
+    if (this.#endpoints.unsubscribe) {
+      await this.#fetch(this.#endpoints.unsubscribe, {
+        method: 'DELETE',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ endpoint: subscription.endpoint }),
+      }).catch(() => undefined);
+    }
+
+    await subscription.unsubscribe();
+    this.#setState({ status: 'unsubscribed', subscription: null, error: null });
+
+    return true;
+  }
+
+  /**
+   * Re-uploads the current subscription. Call it after a `pushsubscriptionchange`.
+   *
+   * @returns {Promise<PushSubscription|null>} The refreshed subscription.
+   */
+  async syncWithServer() {
+    const subscription = await this.getSubscription();
+    if (!subscription) return null;
+    await this.#upload(subscription);
+    this.#setState({ status: 'subscribed', subscription, error: null });
+    return subscription;
+  }
+
+  /**
+   * Pushes the subscription to the backend.
+   *
+   * @param {PushSubscription} subscription - The subscription to upload.
+   * @returns {Promise<void>} A promise that resolves once the upload finishes.
+   * @throws {Error} If the backend responds with a non-2xx status.
+   */
+  async #upload(subscription) {
+    if (!this.#endpoints.subscribe) return;
+
+    const response = await this.#fetch(this.#endpoints.subscribe, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(subscription.toJSON()),
+    });
+
+    if (!response.ok) {
+      throw new Error(`[TinyPushManager] Failed to upload subscription: ${response.status}.`);
+    }
+  }
+
+  /**
+   * Updates the internal state and notifies the observer.
+   *
+   * @param {Partial<TinyPushState>} patch - The fields to merge.
+   * @returns {void} Nothing is returned; the state is updated in place.
+   */
+  #setState(patch) {
+    this.#state = { ...this.#state, ...patch };
+    this.#onChange?.(this.state);
+  }
+}
+
+module.exports = TinyPushManager;