tiny-essentials 1.28.19 → 1.29.0

package/dist/v1/libs/sw/service/plugins/ViteFileDetector.mjs

@@ -0,0 +1,148 @@
+import { TinySetMapDatabase, TinySetDb } from '../../../storage/TinySetMapDatabase.mjs';
+import TinyServiceWorkerEngine from '../TinyServiceWorkerEngine.mjs';
+const { TinyPluginLayer } = TinyServiceWorkerEngine;
+const db = new TinySetMapDatabase('tiny-sw-vite-file-detector', [
+    {
+        create: [
+            {
+                name: 'logged-urls',
+                validate: (value) => typeof value === 'string',
+                type: 'set',
+            },
+        ],
+    },
+]);
+/**
+ * Persistent store of URL strings that already emitted a detection log.
+ * Survives service worker restarts by mirroring every write into IndexedDB.
+ * @type {TinySetDb<string>}
+ */
+const loggedUrls = db.tableSet('logged-urls');
+/**
+ * Configuration options for the ViteFileDetectorPlugin to define which paths should be bypassed.
+ * @typedef {Object} ViteFileDetectorOptions
+ * @property {(string|RegExp)[]} paths - An array of strings or regular expressions used to identify URLs that should be bypassed.
+ * @property {string} srcPath - The base path for the source directory to be included in the bypass list.
+ * @property {string} manifestPath - The path to the manifest file to be included in the bypass list.
+ * @property {number} maxCachedUrls - Maximum amount of detected URLs kept in the persistent cache. When the limit is reached, the oldest entries are evicted before the new one is written. Use `Infinity` to keep every URL forever.
+ */
+/**
+ * Default configuration to maintain backward compatibility.
+ * @type {ViteFileDetectorOptions}
+ */
+const DEFAULT_OPTIONS = {
+    paths: ['/@vite', '/@react', '/node_modules'],
+    srcPath: '/src',
+    manifestPath: '/manifest.json',
+    maxCachedUrls: 1000,
+};
+/**
+ * A plugin for TinyServiceWorkerEngine to detect and bypass Vite-specific files.
+ *
+ * @type {import('../TinyServiceWorkerEngine.mjs').SwPluginInstaller<InstanceType<typeof TinyPluginLayer>, 'ViteFileDetector', '1.0.0', [Partial<ViteFileDetectorOptions>]|[]>}
+ * @throws {TypeError} If the engine is invalid or if the provided options do not match the required schema.
+ */
+const ViteFileDetectorPlugin = (instance, options = {}) => {
+    const engine = instance.engine;
+    instance.id = 'ViteFileDetector';
+    instance.version = '1.0.0';
+    instance.description = 'Vite File detector.';
+    instance.authors = ['JasminDreasond'];
+    instance.contributors = ['JasminDreasond'];
+    instance.categories = ['framework-validator'];
+    instance.tags = ['vite', 'framework', 'validator'];
+    if (!(engine instanceof TinyServiceWorkerEngine)) {
+        throw new TypeError('Plugin requires a TinyServiceWorkerEngine instance to function.');
+    }
+    // 1. Merge and Validate Options
+    /** @type {ViteFileDetectorOptions} */
+    const config = { ...DEFAULT_OPTIONS, ...options };
+    if (!Array.isArray(config.paths)) {
+        throw new TypeError('The "paths" property in options must be an array.');
+    }
+    const paths = [...config.paths, config.srcPath, config.manifestPath];
+    // Deep validation of the paths array elements
+    paths.forEach((pattern, index) => {
+        const isValidString = typeof pattern === 'string';
+        const isValidRegExp = pattern instanceof RegExp;
+        if (!isValidString && !isValidRegExp) {
+            throw new TypeError(`Invalid type at paths[${index}]: Expected string or RegExp, but received ${typeof pattern}.`);
+        }
+    });
+    // 2. Validate the cache limit
+    if (typeof config.maxCachedUrls !== 'number') {
+        throw new TypeError(`The "maxCachedUrls" option must be a number, but received ${typeof config.maxCachedUrls}.`);
+    }
+    if (config.maxCachedUrls !== Infinity &&
+        (!Number.isInteger(config.maxCachedUrls) || config.maxCachedUrls < 1)) {
+        throw new RangeError(`The "maxCachedUrls" option must be a positive integer or Infinity, but received ${config.maxCachedUrls}.`);
+    }
+    const { maxCachedUrls } = config;
+    // 3. Implementation
+    // @ts-ignore
+    if (import.meta.env.DEV) {
+        /**
+         * Tail of the detection queue.
+         *
+         * Every cache mutation is chained here because `TinySetDb` only makes each
+         * individual call atomic. Without this queue, two detections that resolve in
+         * the same tick would both read the same `size` and both decide to insert,
+         * letting the cache grow past `maxCachedUrls`.
+         * @type {Promise<void>}
+         */
+        let detectionQueue = Promise.resolve();
+        /**
+         * Runs a detection task after every previously queued task has settled.
+         * @param {() => Promise<void>} task - The task that touches the cache.
+         * @returns {Promise<void>} Resolves when the task settles.
+         */
+        const enqueueDetection = (task) => {
+            const result = detectionQueue.then(task);
+            detectionQueue = result.catch(() => undefined);
+            return result;
+        };
+        /**
+         * Drops the oldest URLs until a single new entry fits inside the limit.
+         *
+         * The `+ 1` reserves the slot for the value that is about to be inserted,
+         * so the cache always ends up with exactly `maxCachedUrls` entries.
+         * @returns {Promise<void>} Resolves once the cache is below the limit.
+         */
+        const evictOldestUrls = async () => {
+            const overflow = loggedUrls.size - maxCachedUrls + 1;
+            if (overflow <= 0)
+                return;
+            const snapshot = await loggedUrls.toArray();
+            /** @type {Promise<any>[]} */
+            const promises = [];
+            for (let index = 0; index < overflow; index += 1) {
+                promises.push(loggedUrls.delete(snapshot[index]));
+            }
+            await Promise.all(promises);
+        };
+        engine.addFetchGlobalListener('ViteFileDetectorPlugin', ({ url }, response) => {
+            const isBypassed = paths.some((pattern) => {
+                if (pattern instanceof RegExp)
+                    return pattern.test(url.pathname);
+                return url.pathname.startsWith(pattern);
+            });
+            if (!isBypassed)
+                return;
+            response.continueCheck = false;
+            response.needValidation = false;
+            response.code = 200;
+            const cacheKey = url.toString();
+            enqueueDetection(async () => {
+                if (await loggedUrls.has(cacheKey))
+                    return;
+                await evictOldestUrls();
+                await loggedUrls.add(cacheKey);
+                instance.log('warn', `File detected: ${cacheKey}`);
+            }).catch((error) => {
+                instance.log('error', `Failed to cache the detected URL "${cacheKey}": ${error.message}`);
+            });
+        });
+    }
+    return new TinyPluginLayer();
+};
+export default ViteFileDetectorPlugin;

package/dist/v1/libs/sw/service/shared/TinyPushPayload.cjs

@@ -0,0 +1,199 @@
+'use strict';
+
+var utils = require('../../utils.cjs');
+
+/**
+ * @file Shared contract for every message that travels through the Web Push channel.
+ *
+ * The module is isomorphic on purpose: the Service Worker imports it to parse the
+ * incoming payload, and the page imports it to build and validate the payload
+ * before it reaches the backend.
+ */
+
+/** @typedef {import('../../utils.mjs').TinyPushNotification} TinyPushNotification */
+/** @typedef {import('../../utils.mjs').TinyPushMessage} TinyPushMessage */
+
+/**
+ * Holds the fallback values applied when an incoming message omits the
+ * corresponding optional notification field.
+ *
+ * @typedef {Object} TinyPushNotificationDefaults
+ * @property {string} [defaultIcon] - Fallback icon.
+ * @property {string} [defaultBadge] - Fallback badge.
+ * @property {string} [defaultUrl] - Fallback click URL.
+ */
+
+const MAX_TTL_SECONDS = 2419200;
+
+/**
+ * Normalizes, validates and converts Web Push payloads.
+ *
+ * Every method is static and side effect free, so the class is safe to import
+ * from both the page and the Service Worker.
+ * @beta
+ */
+class TinyPushPayload {
+  static #PUSH_TYPE = utils.PUSH_TYPE;
+  static get PUSH_TYPE() {
+    return TinyPushPayload.#PUSH_TYPE;
+  }
+
+  /** @type {number} The current payload schema version. */
+  static VERSION = 1;
+
+  /** @type {number} The maximum allowed TTL, in seconds. */
+  static MAX_TTL = MAX_TTL_SECONDS;
+
+  /**
+   * Builds a normalized message from an untrusted value.
+   *
+   * @param {unknown} raw - The value received from the network.
+   * @returns {TinyPushMessage} A frozen, normalized message.
+   * @throws {TypeError} If `raw` is not a non-null object.
+   */
+  static from(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+      throw new TypeError('[TinyPushPayload] from: raw must be a non-null object.');
+    }
+
+    const source = /** @type {Record<string, unknown>} */ (raw);
+    const type =
+      typeof source.type === 'string' && source.type !== '' ? source.type : utils.PUSH_TYPE.UNKNOWN;
+
+    /** @type {TinyPushMessage} */
+    const message = {
+      v: typeof source.v === 'number' ? source.v : TinyPushPayload.VERSION,
+      type,
+    };
+
+    if (typeof source.id === 'string') message.id = source.id;
+    if (typeof source.topic === 'string') message.topic = source.topic;
+    if (typeof source.expiresAt === 'number') message.expiresAt = source.expiresAt;
+    if (typeof source.ttl === 'number' && Number.isFinite(source.ttl)) {
+      message.ttl = Math.min(Math.max(0, Math.trunc(source.ttl)), MAX_TTL_SECONDS);
+    }
+    if (typeof source.data === 'object' && source.data !== null && !Array.isArray(source.data)) {
+      message.data = /** @type {Record<string, unknown>} */ (source.data);
+    }
+    if (typeof source.notification === 'object' && source.notification !== null) {
+      message.notification = TinyPushPayload.#normalizeNotification(source.notification);
+    }
+
+    return Object.freeze(message);
+  }
+
+  /**
+   * Reads the payload of a `push` event exactly once.
+   *
+   * `PushMessageData` is a one-shot stream: calling `json()` and then `text()`
+   * throws `TypeError`. This method reads the body once and parses it manually.
+   *
+   * @param {PushEvent} event - The native push event.
+   * @returns {Promise<TinyPushMessage>} The normalized message, never `null`.
+   */
+  static async fromEvent(event) {
+    if (typeof event !== 'object' || event === null || !('data' in event)) {
+      throw new TypeError('[TinyPushPayload] fromEvent: event must be a PushEvent.');
+    }
+
+    if (!event.data) {
+      return Object.freeze({ v: TinyPushPayload.VERSION, type: utils.PUSH_TYPE.UNKNOWN });
+    }
+
+    let text;
+
+    try {
+      text = await event.data.text();
+    } catch {
+      return Object.freeze({ v: TinyPushPayload.VERSION, type: utils.PUSH_TYPE.UNKNOWN });
+    }
+
+    if (text === '') {
+      return Object.freeze({ v: TinyPushPayload.VERSION, type: utils.PUSH_TYPE.UNKNOWN });
+    }
+
+    try {
+      return TinyPushPayload.from(JSON.parse(text));
+    } catch {
+      return Object.freeze({
+        v: TinyPushPayload.VERSION,
+        type: utils.PUSH_TYPE.UNKNOWN,
+        notification: { title: 'Notification', body: text },
+      });
+    }
+  }
+
+  /**
+   * Checks whether a message is past its expiration time.
+   *
+   * @param {TinyPushMessage} message - The message to inspect.
+   * @param {number} [now=Date.now()] - Reference time in milliseconds.
+   * @returns {boolean} `true` when the message must be discarded.
+   * @throws {TypeError} If `message` is not a non-null object or `now` is not a finite number.
+   */
+  static isExpired(message, now = Date.now()) {
+    if (typeof message !== 'object' || message === null) {
+      throw new TypeError('[TinyPushPayload] isExpired: message must be a non-null object.');
+    }
+    if (typeof now !== 'number' || !Number.isFinite(now)) {
+      throw new TypeError('[TinyPushPayload] isExpired: now must be a finite number.');
+    }
+
+    return typeof message.expiresAt === 'number' && message.expiresAt <= now;
+  }
+
+  /**
+   * Converts a message into the `[title, options]` pair expected by `showNotification`.
+   *
+   * @param {TinyPushMessage} message - The normalized message.
+   * @param {TinyPushNotificationDefaults} [defaults] - Fallback values.
+   * @returns {{ title: string, options: NotificationOptions & { data: Record<string, unknown> } }} The arguments.
+   * @throws {TypeError} If `message` is not a non-null object.
+   */
+  static toNotification(message, defaults = {}) {
+    if (typeof message !== 'object' || message === null) {
+      throw new TypeError('[TinyPushPayload] toNotification: message must be a non-null object.');
+    }
+
+    const n = message.notification ?? { title: 'Notification' };
+    const { title, body, url, actions, data, ...rest } = n;
+
+    return {
+      title: title ?? 'Notification',
+      options: {
+        ...rest,
+        body: body ?? '',
+        icon: n.icon ?? defaults.defaultIcon,
+        badge: n.badge ?? defaults.defaultBadge,
+        // @ts-ignore
+        actions,
+        data: {
+          ...data,
+          url: url ?? defaults.defaultUrl ?? '/',
+          actions: Object.fromEntries((actions ?? []).map((a) => [a.action, a.url ?? url ?? '/'])),
+          pushId: message.id,
+          pushType: message.type,
+        },
+      },
+    };
+  }
+
+  /**
+   * Validates and normalizes a notification descriptor.
+   *
+   * @param {object} raw - The value to normalize.
+   * @returns {TinyPushNotification} The normalized descriptor.
+   * @throws {TypeError} If `title` is missing or not a string.
+   */
+  static #normalizeNotification(raw) {
+    const source = /** @type {Record<string, unknown>} */ (raw);
+
+    if (typeof source.title !== 'string' || source.title.trim() === '') {
+      throw new TypeError('[TinyPushPayload] notification.title must be a non-empty string.');
+    }
+
+    return /** @type {TinyPushNotification} */ ({ ...source });
+  }
+}
+
+module.exports = TinyPushPayload;

package/dist/v1/libs/sw/service/shared/TinyPushPayload.d.mts

@@ -0,0 +1,80 @@
+export type TinyPushNotification = import('../../utils.mjs').TinyPushNotification;
+export type TinyPushMessage = import('../../utils.mjs').TinyPushMessage;
+export type TinyPushNotificationDefaults = {
+    /**
+     * - Fallback icon.
+     */
+    defaultIcon?: string;
+    /**
+     * - Fallback badge.
+     */
+    defaultBadge?: string;
+    /**
+     * - Fallback click URL.
+     */
+    defaultUrl?: string;
+};
+/**
+ * Normalizes, validates and converts Web Push payloads.
+ *
+ * Every method is static and side effect free, so the class is safe to import
+ * from both the page and the Service Worker.
+ * @beta
+ */
+declare class TinyPushPayload {
+    #private;
+    static get PUSH_TYPE(): Readonly<{
+        NOTIFICATION: "notification";
+        DATA: "data";
+        SYNC: "sync";
+        COMMAND: "command";
+        UNKNOWN: "unknown";
+    }>;
+    /** @type {number} The current payload schema version. */
+    static VERSION: number;
+    /** @type {number} The maximum allowed TTL, in seconds. */
+    static MAX_TTL: number;
+    /**
+     * Builds a normalized message from an untrusted value.
+     *
+     * @param {unknown} raw - The value received from the network.
+     * @returns {TinyPushMessage} A frozen, normalized message.
+     * @throws {TypeError} If `raw` is not a non-null object.
+     */
+    static from(raw: unknown): TinyPushMessage;
+    /**
+     * Reads the payload of a `push` event exactly once.
+     *
+     * `PushMessageData` is a one-shot stream: calling `json()` and then `text()`
+     * throws `TypeError`. This method reads the body once and parses it manually.
+     *
+     * @param {PushEvent} event - The native push event.
+     * @returns {Promise<TinyPushMessage>} The normalized message, never `null`.
+     */
+    static fromEvent(event: PushEvent): Promise<TinyPushMessage>;
+    /**
+     * Checks whether a message is past its expiration time.
+     *
+     * @param {TinyPushMessage} message - The message to inspect.
+     * @param {number} [now=Date.now()] - Reference time in milliseconds.
+     * @returns {boolean} `true` when the message must be discarded.
+     * @throws {TypeError} If `message` is not a non-null object or `now` is not a finite number.
+     */
+    static isExpired(message: TinyPushMessage, now?: number): boolean;
+    /**
+     * Converts a message into the `[title, options]` pair expected by `showNotification`.
+     *
+     * @param {TinyPushMessage} message - The normalized message.
+     * @param {TinyPushNotificationDefaults} [defaults] - Fallback values.
+     * @returns {{ title: string, options: NotificationOptions & { data: Record<string, unknown> } }} The arguments.
+     * @throws {TypeError} If `message` is not a non-null object.
+     */
+    static toNotification(message: TinyPushMessage, defaults?: TinyPushNotificationDefaults): {
+        title: string;
+        options: NotificationOptions & {
+            data: Record<string, unknown>;
+        };
+    };
+}
+export default TinyPushPayload;
+//# sourceMappingURL=TinyPushPayload.d.mts.map

package/dist/v1/libs/sw/service/shared/TinyPushPayload.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TinyPushPayload.d.mts","sourceRoot":"","sources":["../../../../../../../src/v1/libs/sw/service/shared/TinyPushPayload.mjs"],"names":[],"mappings":"AAUI,YAA0D,oBAAoB,GAApE,OAAO,iBAAiB,EAAE,oBAAoB,CAAsB;AAC9E,YAAqD,eAAe,GAA1D,OAAO,iBAAiB,EAAE,eAAe,CAAiB;AAMrE,YAAkB,4BAA4B,GAC9C;;;;IAAoB,WAAW,AAA/B,CACA,EADW,MAAM,CACjB;;;;IAAoB,YAAY,AAAhC,CACA,EADW,MAAM,CACjB;;;;IAAoB,UAAU,AAA9B,CACF,EADa,MAAM,CACnB;CAAA,CAAA;AAID;;;;;;GAMG;AACH,cAAM,eAAe;;IAEnB,MAAM,KAAK,SAAS;;;;;;OAEnB;IAED,yDAAyD;IACzD,MAAM,CAAC,OAAO,EADH,MAAM,CACE;IAEnB,0DAA0D;IAC1D,MAAM,CAAC,OAAO,EADH,MAAM,CACgB;IAEjC;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CAAC,GAAG,EAJJ,OAII,GAHF,eAAe,CAgC3B;IAED;;;;;;;;OAQG;IACH,OAAa,SAAS,CAAC,KAAK,EAHjB,SAGiB,GAFf,OAAO,CAAC,eAAe,CAAC,CAgCpC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,SAAS,CAAC,OAAO,EALb,eAKa,EAAE,GAAG,AAJ1B,CACA,EADQ,MAI+B,GAH7B,OAAO,CAYnB;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EALlB,eAKkB,EAAE,QAAQ,AAJpC,CACA,EADQ,4BAIiC,GAH/B;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,mBAAmB,GAAG;YAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,CAAA;KAAE,CA6B/F;CAkBF;eAEc,eAAe"}

package/dist/v1/libs/sw/service/shared/TinyPushPayload.mjs

@@ -0,0 +1,174 @@
+import { PUSH_TYPE } from '../../utils.mjs';
+/**
+ * @file Shared contract for every message that travels through the Web Push channel.
+ *
+ * The module is isomorphic on purpose: the Service Worker imports it to parse the
+ * incoming payload, and the page imports it to build and validate the payload
+ * before it reaches the backend.
+ */
+/** @typedef {import('../../utils.mjs').TinyPushNotification} TinyPushNotification */
+/** @typedef {import('../../utils.mjs').TinyPushMessage} TinyPushMessage */
+/**
+ * Holds the fallback values applied when an incoming message omits the
+ * corresponding optional notification field.
+ *
+ * @typedef {Object} TinyPushNotificationDefaults
+ * @property {string} [defaultIcon] - Fallback icon.
+ * @property {string} [defaultBadge] - Fallback badge.
+ * @property {string} [defaultUrl] - Fallback click URL.
+ */
+const MAX_TTL_SECONDS = 2419200;
+/**
+ * Normalizes, validates and converts Web Push payloads.
+ *
+ * Every method is static and side effect free, so the class is safe to import
+ * from both the page and the Service Worker.
+ * @beta
+ */
+class TinyPushPayload {
+    static #PUSH_TYPE = PUSH_TYPE;
+    static get PUSH_TYPE() {
+        return TinyPushPayload.#PUSH_TYPE;
+    }
+    /** @type {number} The current payload schema version. */
+    static VERSION = 1;
+    /** @type {number} The maximum allowed TTL, in seconds. */
+    static MAX_TTL = MAX_TTL_SECONDS;
+    /**
+     * Builds a normalized message from an untrusted value.
+     *
+     * @param {unknown} raw - The value received from the network.
+     * @returns {TinyPushMessage} A frozen, normalized message.
+     * @throws {TypeError} If `raw` is not a non-null object.
+     */
+    static from(raw) {
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            throw new TypeError('[TinyPushPayload] from: raw must be a non-null object.');
+        }
+        const source = /** @type {Record<string, unknown>} */ (raw);
+        const type = typeof source.type === 'string' && source.type !== '' ? source.type : PUSH_TYPE.UNKNOWN;
+        /** @type {TinyPushMessage} */
+        const message = {
+            v: typeof source.v === 'number' ? source.v : TinyPushPayload.VERSION,
+            type,
+        };
+        if (typeof source.id === 'string')
+            message.id = source.id;
+        if (typeof source.topic === 'string')
+            message.topic = source.topic;
+        if (typeof source.expiresAt === 'number')
+            message.expiresAt = source.expiresAt;
+        if (typeof source.ttl === 'number' && Number.isFinite(source.ttl)) {
+            message.ttl = Math.min(Math.max(0, Math.trunc(source.ttl)), MAX_TTL_SECONDS);
+        }
+        if (typeof source.data === 'object' && source.data !== null && !Array.isArray(source.data)) {
+            message.data = /** @type {Record<string, unknown>} */ (source.data);
+        }
+        if (typeof source.notification === 'object' && source.notification !== null) {
+            message.notification = TinyPushPayload.#normalizeNotification(source.notification);
+        }
+        return Object.freeze(message);
+    }
+    /**
+     * Reads the payload of a `push` event exactly once.
+     *
+     * `PushMessageData` is a one-shot stream: calling `json()` and then `text()`
+     * throws `TypeError`. This method reads the body once and parses it manually.
+     *
+     * @param {PushEvent} event - The native push event.
+     * @returns {Promise<TinyPushMessage>} The normalized message, never `null`.
+     */
+    static async fromEvent(event) {
+        if (typeof event !== 'object' || event === null || !('data' in event)) {
+            throw new TypeError('[TinyPushPayload] fromEvent: event must be a PushEvent.');
+        }
+        if (!event.data) {
+            return Object.freeze({ v: TinyPushPayload.VERSION, type: PUSH_TYPE.UNKNOWN });
+        }
+        let text;
+        try {
+            text = await event.data.text();
+        }
+        catch {
+            return Object.freeze({ v: TinyPushPayload.VERSION, type: PUSH_TYPE.UNKNOWN });
+        }
+        if (text === '') {
+            return Object.freeze({ v: TinyPushPayload.VERSION, type: PUSH_TYPE.UNKNOWN });
+        }
+        try {
+            return TinyPushPayload.from(JSON.parse(text));
+        }
+        catch {
+            return Object.freeze({
+                v: TinyPushPayload.VERSION,
+                type: PUSH_TYPE.UNKNOWN,
+                notification: { title: 'Notification', body: text },
+            });
+        }
+    }
+    /**
+     * Checks whether a message is past its expiration time.
+     *
+     * @param {TinyPushMessage} message - The message to inspect.
+     * @param {number} [now=Date.now()] - Reference time in milliseconds.
+     * @returns {boolean} `true` when the message must be discarded.
+     * @throws {TypeError} If `message` is not a non-null object or `now` is not a finite number.
+     */
+    static isExpired(message, now = Date.now()) {
+        if (typeof message !== 'object' || message === null) {
+            throw new TypeError('[TinyPushPayload] isExpired: message must be a non-null object.');
+        }
+        if (typeof now !== 'number' || !Number.isFinite(now)) {
+            throw new TypeError('[TinyPushPayload] isExpired: now must be a finite number.');
+        }
+        return typeof message.expiresAt === 'number' && message.expiresAt <= now;
+    }
+    /**
+     * Converts a message into the `[title, options]` pair expected by `showNotification`.
+     *
+     * @param {TinyPushMessage} message - The normalized message.
+     * @param {TinyPushNotificationDefaults} [defaults] - Fallback values.
+     * @returns {{ title: string, options: NotificationOptions & { data: Record<string, unknown> } }} The arguments.
+     * @throws {TypeError} If `message` is not a non-null object.
+     */
+    static toNotification(message, defaults = {}) {
+        if (typeof message !== 'object' || message === null) {
+            throw new TypeError('[TinyPushPayload] toNotification: message must be a non-null object.');
+        }
+        const n = message.notification ?? { title: 'Notification' };
+        const { title, body, url, actions, data, ...rest } = n;
+        return {
+            title: title ?? 'Notification',
+            options: {
+                ...rest,
+                body: body ?? '',
+                icon: n.icon ?? defaults.defaultIcon,
+                badge: n.badge ?? defaults.defaultBadge,
+                // @ts-ignore
+                actions,
+                data: {
+                    ...data,
+                    url: url ?? defaults.defaultUrl ?? '/',
+                    actions: Object.fromEntries((actions ?? []).map((a) => [a.action, a.url ?? url ?? '/'])),
+                    pushId: message.id,
+                    pushType: message.type,
+                },
+            },
+        };
+    }
+    /**
+     * Validates and normalizes a notification descriptor.
+     *
+     * @param {object} raw - The value to normalize.
+     * @returns {TinyPushNotification} The normalized descriptor.
+     * @throws {TypeError} If `title` is missing or not a string.
+     */
+    static #normalizeNotification(raw) {
+        const source = /** @type {Record<string, unknown>} */ (raw);
+        if (typeof source.title !== 'string' || source.title.trim() === '') {
+            throw new TypeError('[TinyPushPayload] notification.title must be a non-empty string.');
+        }
+        return /** @type {TinyPushNotification} */ ({ ...source });
+    }
+}
+export default TinyPushPayload;

package/dist/v1/libs/sw/utils.cjs

@@ -0,0 +1,57 @@
+'use strict';
+
+/**
+ * @typedef {Object} TinyPushAction
+ * @property {string} action - Identifier echoed back on `notificationclick`.
+ * @property {string} title - Human readable label.
+ * @property {string} [icon] - Absolute URL of the action icon.
+ * @property {string} [url] - URL opened when the action is clicked.
+ * @property {boolean} [dismiss] - When `true`, the action only closes the notification.
+ */
+
+/**
+ * @typedef {Object} TinyPushNotification
+ * @property {string} title - Notification title.
+ * @property {string} [body] - Notification body.
+ * @property {string} [icon] - Absolute URL of the icon.
+ * @property {string} [badge] - Absolute URL of the badge.
+ * @property {string} [image] - Absolute URL of the hero image.
+ * @property {string} [tag] - Collapse key. Notifications with the same tag replace each other.
+ * @property {string} [lang] - BCP 47 language tag.
+ * @property {string} [dir] - Text direction: `ltr` or `rtl`.
+ * @property {string} [url] - URL opened when the notification body is clicked.
+ * @property {boolean} [renotify] - Whether to vibrate on replacement.
+ * @property {boolean} [requireInteraction] - Whether the notification stays until dismissed.
+ * @property {boolean} [silent] - Whether to suppress vibration and sound.
+ * @property {number} [timestamp] - Creation time in milliseconds since the epoch.
+ * @property {number[]} [vibrate] - Vibration pattern in milliseconds.
+ * @property {TinyPushAction[]} [actions] - Action buttons.
+ * @property {Record<string, unknown>} [data] - Opaque data echoed back on click.
+ */
+
+/**
+ * @typedef {Object} TinyPushMessage
+ * @property {number} v - Contract version.
+ * @property {string} type - Routing key, see {@link PUSH_TYPE}.
+ * @property {string} [id] - Idempotency identifier.
+ * @property {number} [ttl] - Time to live in seconds.
+ * @property {string} [topic] - Collapse key at the transport level.
+ * @property {number} [expiresAt] - Absolute expiration time in milliseconds since the epoch.
+ * @property {TinyPushNotification} [notification] - Notification descriptor.
+ * @property {Record<string, unknown>} [data] - Arbitrary payload for custom handlers.
+ */
+
+/**
+ * Discriminator used by the router to pick a handler.
+ * @readonly
+ * @enum {string}
+ */
+const PUSH_TYPE = Object.freeze({
+  NOTIFICATION: 'notification',
+  DATA: 'data',
+  SYNC: 'sync',
+  COMMAND: 'command',
+  UNKNOWN: 'unknown',
+});
+
+exports.PUSH_TYPE = PUSH_TYPE;