@vouchington/utils 0.7.2 → 0.7.4

package/dist/seo-metadata.d.mts

@@ -0,0 +1,94 @@
+export interface SeoSite {
+    siteName: string;
+    /** Absolute origin, e.g. `https://example.com`. */
+    origin: string;
+    description: string;
+}
+export interface SeoRobots {
+    index: false;
+    follow: false;
+    googleBot: {
+        index: false;
+        follow: false;
+    };
+}
+export interface SeoImage extends ImageSize {
+    url: string;
+}
+export interface SeoOpenGraph {
+    type: 'website' | 'article';
+    siteName: string;
+    title?: string;
+    description: string;
+    locale?: string;
+    url: string;
+    images?: SeoImage[];
+    publishedTime?: string;
+    modifiedTime?: string;
+    authors?: string[];
+}
+export interface SeoTwitter {
+    card: 'summary_large_image';
+    title?: string;
+    description: string;
+    images?: string[];
+}
+export type SeoAlternateTypes = Record<string, string | {
+    url: string;
+    title?: string;
+}[]>;
+/** Assignable to Next.js `Metadata` (the shapes below are subsets of its OpenGraph/Twitter types). */
+export interface SeoMetadata {
+    metadataBase: URL;
+    title?: string | {
+        default: string;
+        template: string;
+    };
+    description: string;
+    alternates?: {
+        canonical: string;
+        types?: SeoAlternateTypes;
+    };
+    robots?: SeoRobots | undefined;
+    openGraph?: SeoOpenGraph;
+    twitter?: SeoTwitter;
+}
+export interface ImageSize {
+    width: number;
+    height: number;
+}
+export interface PageMetadataOptions {
+    title?: string;
+    description?: string;
+    path?: string;
+    noIndex?: boolean;
+    /** Absolute image URL. `null` omits images; undefined uses `fallbackImageUrl`. */
+    imageUrl?: string | null;
+    fallbackImageUrl?: string;
+    type?: 'website' | 'article';
+    publishedTime?: string;
+    modifiedTime?: string;
+    authors?: string[];
+    rssUrl?: string;
+    /** Resolved by the caller (for example `en_US`). */
+    openGraphLocale?: string | null;
+    /** Resolved by the caller; ignored for noindex pages. */
+    markdownAlternatePath?: string | null;
+    imageSize?: ImageSize;
+}
+export declare function buildAbsoluteUrl(origin: string, path?: string): string;
+export declare function createRobotsMetadata(noIndex: boolean): SeoRobots | undefined;
+export { createExcerpt } from './seo-excerpt.mts';
+/** Returns `${path}.md` when `path` is `/prefix/id` for a listed prefix. */
+export declare function getMarkdownAlternatePath(path: string, prefixes: ReadonlySet<string>): string | null;
+export declare function createNoIndexMetadata(site: SeoSite, title?: string): SeoMetadata;
+export declare function createPageMetadata(site: SeoSite, options: PageMetadataOptions): SeoMetadata;
+/** Root layout metadata; icons are passed through untouched. */
+export declare function createRootMetadata<Icons = never>(site: SeoSite, options: {
+    imageUrl: string;
+    openGraphLocale?: string | null;
+    icons?: Icons;
+    imageSize?: ImageSize;
+}): SeoMetadata & {
+    icons?: Icons;
+};

package/dist/seo-metadata.mjs

@@ -0,0 +1,97 @@
+const DEFAULT_IMAGE_SIZE = { width: 1200, height: 630 };
+export function buildAbsoluteUrl(origin, path = '/') {
+    return new URL(path, origin).toString();
+}
+export function createRobotsMetadata(noIndex) {
+    if (!noIndex)
+        return undefined;
+    return { index: false, follow: false, googleBot: { index: false, follow: false } };
+}
+export { createExcerpt } from './seo-excerpt.mjs';
+/** Returns `${path}.md` when `path` is `/prefix/id` for a listed prefix. */
+export function getMarkdownAlternatePath(path, prefixes) {
+    const parts = path.split('/').filter(Boolean);
+    if (parts.length !== 2)
+        return null;
+    return prefixes.has(parts[0]) ? `${path.replace(/\/$/, '')}.md` : null;
+}
+export function createNoIndexMetadata(site, title) {
+    return {
+        metadataBase: new URL(site.origin),
+        ...(title ? { title } : {}),
+        description: site.description,
+        robots: createRobotsMetadata(true),
+    };
+}
+export function createPageMetadata(site, options) {
+    const { title, path = '/', noIndex = false, type = 'website' } = options;
+    const description = options.description ?? site.description;
+    const imageUrl = options.imageUrl === null ? undefined : (options.imageUrl ?? options.fallbackImageUrl);
+    const size = options.imageSize ?? DEFAULT_IMAGE_SIZE;
+    const markdownPath = noIndex ? null : (options.markdownAlternatePath ?? null);
+    const types = {
+        ...(markdownPath
+            ? { 'text/markdown': [{ url: markdownPath, title: `${title ?? site.siteName} Markdown` }] }
+            : {}),
+        ...(options.rssUrl ? { 'application/rss+xml': options.rssUrl } : {}),
+    };
+    const article = type === 'article'
+        ? {
+            ...(options.publishedTime ? { publishedTime: options.publishedTime } : {}),
+            ...(options.modifiedTime ? { modifiedTime: options.modifiedTime } : {}),
+            ...(options.authors?.length ? { authors: options.authors } : {}),
+        }
+        : {};
+    return {
+        metadataBase: new URL(site.origin),
+        ...(title ? { title } : {}),
+        description,
+        alternates: {
+            canonical: path,
+            ...(Object.keys(types).length > 0 ? { types } : {}),
+        },
+        robots: createRobotsMetadata(noIndex),
+        openGraph: {
+            type,
+            siteName: site.siteName,
+            ...(title ? { title } : {}),
+            description,
+            ...(options.openGraphLocale ? { locale: options.openGraphLocale } : {}),
+            url: buildAbsoluteUrl(site.origin, path),
+            ...(imageUrl ? { images: [{ url: imageUrl, ...size }] } : {}),
+            ...article,
+        },
+        twitter: {
+            card: 'summary_large_image',
+            ...(title ? { title } : {}),
+            description,
+            ...(imageUrl ? { images: [imageUrl] } : {}),
+        },
+    };
+}
+/** Root layout metadata; icons are passed through untouched. */
+export function createRootMetadata(site, options) {
+    const size = options.imageSize ?? DEFAULT_IMAGE_SIZE;
+    return {
+        metadataBase: new URL(site.origin),
+        title: { default: site.siteName, template: `%s | ${site.siteName}` },
+        description: site.description,
+        alternates: { canonical: '/' },
+        ...(options.icons ? { icons: options.icons } : {}),
+        openGraph: {
+            type: 'website',
+            siteName: site.siteName,
+            title: site.siteName,
+            description: site.description,
+            ...(options.openGraphLocale ? { locale: options.openGraphLocale } : {}),
+            url: buildAbsoluteUrl(site.origin, '/'),
+            images: [{ url: options.imageUrl, ...size }],
+        },
+        twitter: {
+            card: 'summary_large_image',
+            title: site.siteName,
+            description: site.description,
+            images: [options.imageUrl],
+        },
+    };
+}

package/dist/speculation-rules.d.mts

@@ -0,0 +1,11 @@
+export interface SpeculationRulesConfig {
+    excludedHrefPatterns: readonly string[];
+    excludedSelectors?: readonly string[];
+    /** Value for `expects_no_vary_search`; omitted when undefined. */
+    noVarySearchHeader?: string;
+    eagerness?: 'immediate' | 'eager' | 'moderate' | 'conservative';
+}
+/** Builds a prefetch speculation-rules object. Serialize it with `serializeJsonLd`-style escaping. */
+export declare function createSpeculationRules(config: SpeculationRulesConfig): Record<string, unknown>;
+/** Returns the origin of an http(s) URL, or null. */
+export declare function getPreconnectOrigin(rawOrigin: string | undefined): string | null;

package/dist/speculation-rules.mjs

@@ -0,0 +1,36 @@
+/** Builds a prefetch speculation-rules object. Serialize it with `serializeJsonLd`-style escaping. */
+export function createSpeculationRules(config) {
+    return {
+        prefetch: [
+            {
+                source: 'document',
+                where: {
+                    and: [
+                        { href_matches: '/*' },
+                        ...config.excludedHrefPatterns.map((pattern) => ({ not: { href_matches: pattern } })),
+                        ...(config.excludedSelectors ?? []).map((selector) => ({
+                            not: { selector_matches: selector },
+                        })),
+                    ],
+                },
+                eagerness: config.eagerness ?? 'conservative',
+                ...(config.noVarySearchHeader ? { expects_no_vary_search: config.noVarySearchHeader } : {}),
+            },
+        ],
+    };
+}
+/** Returns the origin of an http(s) URL, or null. */
+export function getPreconnectOrigin(rawOrigin) {
+    const trimmed = rawOrigin?.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const url = new URL(trimmed);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            return null;
+        return url.origin;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/web-push-binding.d.mts

@@ -0,0 +1,51 @@
+export interface WebPushBinding {
+    endpoint: string;
+    subscription_id: string;
+}
+export type WebPushWorkerState = {
+    status: 'uninitialized';
+} | {
+    status: 'bound';
+    binding: WebPushBinding;
+    revision: string;
+} | {
+    status: 'reconciling';
+    binding?: WebPushBinding;
+    revision: string;
+} | {
+    status: 'disabled';
+    binding?: WebPushBinding;
+    revision: string;
+};
+export interface WebPushWorkerResponse {
+    type: string;
+    version: 1;
+    ok: boolean;
+    state?: unknown;
+    error?: string;
+}
+export interface WorkerRequestOptions {
+    /** Caller-owned message `type` tag shared with the service worker. */
+    messageType: string;
+    /** Caller-owned check that the acknowledged state is the one the request expects. */
+    accept?: (state: WebPushWorkerState) => boolean;
+    timeoutMs?: number;
+}
+export declare function isWebPushBinding(value: unknown): value is WebPushBinding;
+export declare function isWebPushWorkerState(value: unknown): value is WebPushWorkerState;
+/** Envelope check only: tag, version, `ok`, and a well-formed state. */
+export declare function isWebPushWorkerResponse(response: WebPushWorkerResponse | undefined, messageType: string): response is WebPushWorkerResponse & {
+    state: WebPushWorkerState;
+};
+/**
+ * One request/acknowledge round trip over a MessageChannel to the active service worker.
+ * `request` is sent as `{ type, version: 1, ...request }`. Which requests to send, in what
+ * order, and which acknowledged states are acceptable belong to the caller.
+ */
+export declare function requestWorkerState(registration: {
+    active: {
+        postMessage(message: unknown, transfer: unknown[]): void;
+    } | null;
+}, request: Record<string, unknown>, options: WorkerRequestOptions): Promise<WebPushWorkerState>;
+/** Runs `operation` under a named Web Lock; throws when the browser has no lock manager. */
+export declare function withWebLock<T>(name: string, operation: () => Promise<T>): Promise<T>;

package/dist/web-push-binding.mjs

@@ -0,0 +1,67 @@
+const DEFAULT_ACK_TIMEOUT_MS = 5000;
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+export function isWebPushBinding(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const binding = value;
+    return isNonEmptyString(binding.endpoint) && isNonEmptyString(binding.subscription_id);
+}
+export function isWebPushWorkerState(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const state = value;
+    if (state.status === 'uninitialized')
+        return state.binding === undefined;
+    if (state.status === 'bound') {
+        return isWebPushBinding(state.binding) && isNonEmptyString(state.revision);
+    }
+    return ((state.status === 'reconciling' || state.status === 'disabled') &&
+        isNonEmptyString(state.revision) &&
+        (state.binding === undefined || isWebPushBinding(state.binding)));
+}
+/** Envelope check only: tag, version, `ok`, and a well-formed state. */
+export function isWebPushWorkerResponse(response, messageType) {
+    return (!!response &&
+        response.type === messageType &&
+        response.version === 1 &&
+        response.ok &&
+        isWebPushWorkerState(response.state));
+}
+/**
+ * One request/acknowledge round trip over a MessageChannel to the active service worker.
+ * `request` is sent as `{ type, version: 1, ...request }`. Which requests to send, in what
+ * order, and which acknowledged states are acceptable belong to the caller.
+ */
+export function requestWorkerState(registration, request, options) {
+    const worker = registration.active;
+    if (!worker)
+        return Promise.reject(new Error('The active service worker is unavailable.'));
+    const channel = new MessageChannel();
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            channel.port1.close();
+            reject(new Error('The service worker did not acknowledge the push binding request.'));
+        }, options.timeoutMs ?? DEFAULT_ACK_TIMEOUT_MS);
+        channel.port1.onmessage = (event) => {
+            clearTimeout(timeout);
+            channel.port1.close();
+            const response = event.data;
+            if (!isWebPushWorkerResponse(response, options.messageType) ||
+                (options.accept && !options.accept(response.state))) {
+                reject(new Error(response?.error ?? 'The service worker rejected the push binding request.'));
+                return;
+            }
+            resolve(response.state);
+        };
+        worker.postMessage({ type: options.messageType, version: 1, ...request }, [channel.port2]);
+    });
+}
+/** Runs `operation` under a named Web Lock; throws when the browser has no lock manager. */
+export async function withWebLock(name, operation) {
+    const lockManager = typeof navigator === 'undefined' ? undefined : navigator.locks;
+    if (!lockManager)
+        throw new Error('This browser cannot safely coordinate push notifications.');
+    return lockManager.request(name, operation);
+}

package/dist/web-push-vapid.d.mts

@@ -0,0 +1,26 @@
+export interface VapidKeyPair {
+    /** Uncompressed P-256 point, base64url (the browser `applicationServerKey`). */
+    publicKey: string;
+    /** Raw 32-byte private scalar, base64url. */
+    privateKey: string;
+}
+export interface VapidJwtInput {
+    keys: VapidKeyPair;
+    /** Push service origin, for example `getPushServiceAudience(endpoint)`. */
+    audience: string;
+    /** `mailto:` or `https:` contact URI. */
+    subject: string;
+    /** Seconds since epoch; injectable for tests. */
+    now?: number;
+    /** Lifetime in seconds; RFC 8292 caps it at 24 hours. */
+    expiresInSeconds?: number;
+}
+export declare function generateVapidKeys(): VapidKeyPair;
+/** Returns whether the private scalar corresponds to the public point. */
+export declare function vapidKeysMatch(keys: VapidKeyPair): boolean;
+/** Accepts `mailto:user@host` or an https URL with a host. */
+export declare function isValidVapidSubject(subject: string): boolean;
+/** Signs an ES256 VAPID JWT (RFC 8292). */
+export declare function createVapidJwt(input: VapidJwtInput): string;
+/** Builds the `Authorization` header value for the `vapid` scheme. */
+export declare function createVapidAuthorization(jwt: string, publicKey: string): string;

package/dist/web-push-vapid.mjs

@@ -0,0 +1,86 @@
+import { createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from 'node:crypto';
+import { decodeBase64Url, decodeVapidPublicKey, encodeBase64Url } from './web-push.mjs';
+const MAX_VAPID_LIFETIME_SECONDS = 24 * 60 * 60;
+export function generateVapidKeys() {
+    const { publicKey, privateKey } = generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
+    const pub = publicKey.export({ format: 'jwk' });
+    const priv = privateKey.export({ format: 'jwk' });
+    const point = new Uint8Array([
+        0x04,
+        ...decodeBase64Url(pub.x),
+        ...decodeBase64Url(pub.y),
+    ]);
+    return { publicKey: encodeBase64Url(point), privateKey: priv.d };
+}
+function toPrivateKey({ publicKey, privateKey }) {
+    const point = decodeVapidPublicKey(publicKey);
+    return createPrivateKey({
+        key: {
+            kty: 'EC',
+            crv: 'P-256',
+            x: encodeBase64Url(point.slice(1, 33)),
+            y: encodeBase64Url(point.slice(33)),
+            d: privateKey,
+        },
+        format: 'jwk',
+    });
+}
+/** Returns whether the private scalar corresponds to the public point. */
+export function vapidKeysMatch(keys) {
+    try {
+        // Sign/verify rather than comparing exported points: some Node/OpenSSL builds keep the
+        // imported public coordinates instead of deriving them from the private scalar.
+        const point = decodeVapidPublicKey(keys.publicKey);
+        const publicKey = createPublicKey({
+            key: {
+                kty: 'EC',
+                crv: 'P-256',
+                x: encodeBase64Url(point.slice(1, 33)),
+                y: encodeBase64Url(point.slice(33)),
+            },
+            format: 'jwk',
+        });
+        const probe = Buffer.from('vapid-key-check');
+        const signature = sign('sha256', probe, toPrivateKey(keys));
+        return verify('sha256', probe, publicKey, signature);
+    }
+    catch {
+        return false;
+    }
+}
+/** Accepts `mailto:user@host` or an https URL with a host. */
+export function isValidVapidSubject(subject) {
+    const url = URL.parse(subject);
+    if (!url)
+        return false;
+    if (url.protocol === 'https:')
+        return url.hostname.length > 0;
+    return url.protocol === 'mailto:' && /^[^@\s]+@[^@\s]+$/.test(decodeURIComponent(url.pathname));
+}
+/** Signs an ES256 VAPID JWT (RFC 8292). */
+export function createVapidJwt(input) {
+    const lifetime = input.expiresInSeconds ?? MAX_VAPID_LIFETIME_SECONDS;
+    if (!(lifetime > 0) || lifetime > MAX_VAPID_LIFETIME_SECONDS) {
+        throw new RangeError('VAPID JWT lifetime must be between 1 second and 24 hours');
+    }
+    if (!isValidVapidSubject(input.subject)) {
+        throw new TypeError('VAPID subject must be a valid mailto: address or https: URL');
+    }
+    const now = input.now ?? Math.floor(Date.now() / 1000);
+    const encode = (value) => encodeBase64Url(new TextEncoder().encode(JSON.stringify(value)));
+    const signingInput = `${encode({ typ: 'JWT', alg: 'ES256' })}.${encode({
+        aud: input.audience,
+        exp: now + lifetime,
+        sub: input.subject,
+    })}`;
+    const signature = sign('sha256', Buffer.from(signingInput), {
+        key: toPrivateKey(input.keys),
+        dsaEncoding: 'ieee-p1363',
+    });
+    return `${signingInput}.${encodeBase64Url(signature)}`;
+}
+/** Builds the `Authorization` header value for the `vapid` scheme. */
+export function createVapidAuthorization(jwt, publicKey) {
+    decodeVapidPublicKey(publicKey);
+    return `vapid t=${jwt}, k=${publicKey}`;
+}

package/dist/web-push.d.mts

@@ -0,0 +1,36 @@
+export interface WebPushSubscriptionJson {
+    endpoint: string;
+    expirationTime: number | null;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+}
+export interface WebPushSubscriptionOptions {
+    /** Extra endpoint policy, for example a push-service host allowlist. Defaults to any https URL. */
+    allowEndpoint?: (url: URL) => boolean;
+    maxEndpointLength?: number;
+}
+export interface WebPushPayload {
+    title: string;
+    body?: string;
+    url?: string;
+    icon?: string;
+    tag?: string;
+    data?: Record<string, unknown>;
+}
+/** RFC 8291 section 4: the largest plaintext every push service must accept (4096 - 103). */
+export declare const MAX_WEB_PUSH_PAYLOAD_BYTES = 3993;
+/** Decodes unpadded or padded base64url; throws TypeError on invalid characters. */
+export declare function decodeBase64Url(value: string): Uint8Array;
+export declare function encodeBase64Url(bytes: Uint8Array): string;
+/** Validates a VAPID public key (uncompressed P-256 point) and returns `applicationServerKey` bytes. */
+export declare function decodeVapidPublicKey(key: string): Uint8Array;
+export declare function getPushServiceAudience(endpoint: string): string;
+/** Validates the JSON shape of `PushSubscription.toJSON()`; throws TypeError when invalid. */
+export declare function parseWebPushSubscription(value: unknown, options?: WebPushSubscriptionOptions): WebPushSubscriptionJson;
+export declare function isWebPushSubscription(value: unknown, options?: WebPushSubscriptionOptions): value is WebPushSubscriptionJson;
+/** Serializes a payload to UTF-8 JSON bytes, rejecting payloads over `maxBytes`. */
+export declare function buildWebPushPayload(payload: WebPushPayload, maxBytes?: number): Uint8Array;
+/** Parses payload text inside a service worker; returns null for anything malformed. */
+export declare function parseWebPushPayload(text: string): WebPushPayload | null;

package/dist/web-push.mjs

@@ -0,0 +1,114 @@
+/** RFC 8291 section 4: the largest plaintext every push service must accept (4096 - 103). */
+export const MAX_WEB_PUSH_PAYLOAD_BYTES = 3993;
+const P256DH_BYTES = 65;
+const AUTH_BYTES = 16;
+/** Decodes unpadded or padded base64url; throws TypeError on invalid characters. */
+export function decodeBase64Url(value) {
+    if (!/^[A-Za-z0-9_-]*={0,2}$/.test(value))
+        throw new TypeError('Invalid base64url string');
+    const base64 = value.replace(/=+$/, '').replaceAll('-', '+').replaceAll('_', '/');
+    if (base64.length % 4 === 1)
+        throw new TypeError('Invalid base64url string');
+    return Uint8Array.from(atob(base64.padEnd(Math.ceil(base64.length / 4) * 4, '=')), (c) => c.charCodeAt(0));
+}
+export function encodeBase64Url(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+}
+/** Validates a VAPID public key (uncompressed P-256 point) and returns `applicationServerKey` bytes. */
+export function decodeVapidPublicKey(key) {
+    const bytes = decodeBase64Url(key);
+    if (bytes.length !== P256DH_BYTES || bytes[0] !== 0x04) {
+        throw new TypeError('VAPID public key must be an uncompressed P-256 point');
+    }
+    return bytes;
+}
+export function getPushServiceAudience(endpoint) {
+    return new URL(endpoint).origin;
+}
+function keyOfLength(value, length, name) {
+    if (typeof value !== 'string')
+        throw new TypeError(`Push subscription ${name} must be a string`);
+    if (decodeBase64Url(value).length !== length) {
+        throw new TypeError(`Push subscription ${name} has an invalid length`);
+    }
+    return value;
+}
+/** Validates the JSON shape of `PushSubscription.toJSON()`; throws TypeError when invalid. */
+export function parseWebPushSubscription(value, options = {}) {
+    if (typeof value !== 'object' || value === null) {
+        throw new TypeError('Push subscription must be an object');
+    }
+    const { endpoint, expirationTime, keys } = value;
+    if (typeof endpoint !== 'string' || endpoint.length > (options.maxEndpointLength ?? 2048)) {
+        throw new TypeError('Push subscription endpoint is invalid');
+    }
+    const url = URL.parse(endpoint);
+    if (!url || url.protocol !== 'https:' || (options.allowEndpoint && !options.allowEndpoint(url))) {
+        throw new TypeError('Push subscription endpoint is not allowed');
+    }
+    if (expirationTime != null && (typeof expirationTime !== 'number' || !(expirationTime >= 0))) {
+        throw new TypeError('Push subscription expirationTime is invalid');
+    }
+    if (typeof keys !== 'object' || keys === null) {
+        throw new TypeError('Push subscription keys are required');
+    }
+    const { p256dh, auth } = keys;
+    return {
+        endpoint,
+        expirationTime: expirationTime ?? null,
+        keys: {
+            p256dh: keyOfLength(p256dh, P256DH_BYTES, 'p256dh'),
+            auth: keyOfLength(auth, AUTH_BYTES, 'auth'),
+        },
+    };
+}
+export function isWebPushSubscription(value, options) {
+    try {
+        parseWebPushSubscription(value, options);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Serializes a payload to UTF-8 JSON bytes, rejecting payloads over `maxBytes`. */
+export function buildWebPushPayload(payload, maxBytes = MAX_WEB_PUSH_PAYLOAD_BYTES) {
+    if (!payload.title)
+        throw new TypeError('Push payload title is required');
+    const bytes = new TextEncoder().encode(JSON.stringify(payload));
+    if (bytes.length > maxBytes)
+        throw new RangeError(`Push payload exceeds ${maxBytes} bytes`);
+    return bytes;
+}
+function optionalString(value) {
+    return typeof value === 'string' && value ? value : undefined;
+}
+/** Parses payload text inside a service worker; returns null for anything malformed. */
+export function parseWebPushPayload(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const record = parsed;
+    const title = optionalString(record.title);
+    if (!title)
+        return null;
+    const { data } = record;
+    const isData = typeof data === 'object' && data !== null && !Array.isArray(data);
+    return {
+        title,
+        ...(optionalString(record.body) ? { body: record.body } : {}),
+        ...(optionalString(record.url) ? { url: record.url } : {}),
+        ...(optionalString(record.icon) ? { icon: record.icon } : {}),
+        ...(optionalString(record.tag) ? { tag: record.tag } : {}),
+        ...(isData ? { data: data } : {}),
+    };
+}