@mdbase-dev/sdk 0.0.0-stage → 0.1.0-beta.149

package/dist/native/sqlite3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite3.js","sourceRoot":"","sources":["../../src/native/sqlite3.ts"],"names":[],"mappings":"AAAA,OAAO,iBAAiB,MAAM,yBAAyB,CAAC;AAGxD;+EAC+E;AAC/E,gFAAgF;AAChF,iFAAiF;AACjF,MAAM,UAAU,GAAuC,OAAO,CAAA,EAAE,CAAA,OAAO,CAAC,KAAK,CAAC,iBAAiB,EAAC,SAAS,EAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AACrH,eAAe,UAAU,CAAC"}

package/dist/node.d.ts

@@ -0,0 +1,63 @@
+import type { Uuid } from "./wire.js";
+import { KeyPair, StaticKey } from "./transport/noise.js";
+import { WebSocketFactory } from "./transport/noise-session.js";
+import { LocalLink } from "./transport/local-link.js";
+import type { Connector } from "./transport/port.js";
+/**
+ * The daemon's per-user state directory, as `crates/daemon` (`paths.rs`) defines it:
+ * - Linux: `~/.local/state/mdbase` (fixed: `XDG_STATE_HOME` is **not** honoured, so
+ *   apps and a daemon started from different environments always agree)
+ * - macOS: `~/Library/Application Support/mdbase`
+ * - Windows: `%LOCALAPPDATA%\mdbase\state`
+ */
+export declare function defaultDaemonStateDir(os?: NodeJS.Platform): string;
+/** The daemon's replica endpoint for the current user (§12.2). */
+export declare function defaultIpcPath(sid?: string, os?: NodeJS.Platform): string;
+export interface DaemonIdentity {
+    /** The daemon's device ID (the Noise target). */
+    device: Uuid;
+    /** Its replica Noise public key. */
+    noisePublicKey: Uint8Array;
+}
+/**
+ * Where `daemon.json` lives: the daemon's state directory, **never** beside the socket.
+ * A named pipe's "directory" is `\\.\pipe\`, a namespace any local user can create
+ * names in, so deriving the file from the pipe path would let them supply their own
+ * Noise key. Throws for a location that isn't an ordinary per-user path.
+ */
+export declare function daemonIdentityFile(stateDir: string, os?: NodeJS.Platform): string;
+/**
+ * Read the daemon's identity, `{"device": "<uuid>", "noise_pk": "<64 hex>"}`, from
+ * `daemon.json` in its state directory, after checking who owns it.
+ */
+export declare function readDaemonIdentity(stateDir?: string): Promise<DaemonIdentity>;
+/**
+ * The localhost link (§12.4): `local-link.json` (`{port, token}`) plus the pinned
+ * identity from `daemon.json`, both owner-checked.
+ */
+export declare function readLocalLink(stateDir?: string): Promise<LocalLink>;
+/**
+ * Connect to the desktop daemon over the localhost link as the hosting session of
+ * `collection` (§12.4). Re-reads the link files on every reconnect (new port and token
+ * at each daemon start). For Obsidian, pass `webSocket` if the global one isn't used.
+ */
+export declare function connectDaemonLocalhost(o: {
+    collection: Uuid;
+    localOnly?: boolean;
+    stateDir?: string;
+    webSocket?: WebSocketFactory;
+}): Connector;
+export interface IpcConnectorOptions {
+    collection: Uuid;
+    /** The app's grant, or null for the hosting app itself. */
+    grant: Uuid | null;
+    staticKey: KeyPair | StaticKey;
+    /** Socket or pipe path; default {@link defaultIpcPath}. */
+    path?: string;
+    /** The daemon's identity; default read from `daemon.json` in its state directory. */
+    daemon?: DaemonIdentity;
+    /** The daemon's state directory (isolated daemons); default {@link defaultDaemonStateDir}. */
+    stateDir?: string;
+}
+/** A connector to the desktop daemon over local IPC. */
+export declare function ipcConnector(o: IpcConnectorOptions): Connector;

package/dist/node.js

@@ -0,0 +1,255 @@
+/**
+ * `@mdbase-dev/sdk/node`: local IPC to the desktop daemon (`replica-client-api.md`
+ * §12.2). Node only (Electron main, CLIs, MCP servers, tests).
+ *
+ * - Linux: `$XDG_RUNTIME_DIR/mdbase/replica.sock`
+ * - macOS: `~/Library/Application Support/mdbase/replica.sock`
+ * - Windows: `\\.\pipe\mdbase-replica-<user SID>`
+ *
+ * Authentication is the same Noise IK handshake as remote clients, with the daemon's
+ * replica Noise key. Noise messages travel as `u16be(length) ‖ message`. The key comes
+ * from `daemon.json` in the daemon's owner-checked state directory, never from beside
+ * the socket or pipe, so whoever holds the endpoint name can't impersonate
+ * the daemon.
+ */
+import { constants as fsConstants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { connect as netConnect } from "node:net";
+import { homedir, platform } from "node:os";
+import { join, win32 } from "node:path";
+import { fromHex } from "./cbor.js";
+import { uuidToBytes } from "./codec.js";
+import { mdbaseError } from "./errors.js";
+import { clientPrologue } from "./transport/noise.js";
+import { noiseConnector, streamCarrier } from "./transport/noise-session.js";
+import { localLinkConnector } from "./transport/local-link.js";
+function env(name) {
+    const v = process.env[name];
+    return v && v.length ? v : undefined;
+}
+/**
+ * The daemon's per-user state directory, as `crates/daemon` (`paths.rs`) defines it:
+ * - Linux: `~/.local/state/mdbase` (fixed: `XDG_STATE_HOME` is **not** honoured, so
+ *   apps and a daemon started from different environments always agree)
+ * - macOS: `~/Library/Application Support/mdbase`
+ * - Windows: `%LOCALAPPDATA%\mdbase\state`
+ */
+export function defaultDaemonStateDir(os = platform()) {
+    switch (os) {
+        case "win32": {
+            const base = env("LOCALAPPDATA");
+            if (!base)
+                throw mdbaseError("unavailable", "LOCALAPPDATA is not set");
+            return win32.join(base, "mdbase", "state");
+        }
+        case "darwin":
+            return join(homedir(), "Library", "Application Support", "mdbase");
+        default:
+            return join(homedir(), ".local", "state", "mdbase");
+    }
+}
+/** The daemon's replica endpoint for the current user (§12.2). */
+export function defaultIpcPath(sid, os = platform()) {
+    switch (os) {
+        case "win32":
+            if (!sid)
+                throw mdbaseError("invalid_request", "pass the user SID for the named pipe path");
+            return `\\\\.\\pipe\\mdbase-replica-${sid}`;
+        case "darwin":
+            return join(defaultDaemonStateDir(os), "replica.sock");
+        default: {
+            const run = env("XDG_RUNTIME_DIR");
+            return run ? join(run, "mdbase", "replica.sock") : join(defaultDaemonStateDir(os), "run", "replica.sock");
+        }
+    }
+}
+/**
+ * Where `daemon.json` lives: the daemon's state directory, **never** beside the socket.
+ * A named pipe's "directory" is `\\.\pipe\`, a namespace any local user can create
+ * names in, so deriving the file from the pipe path would let them supply their own
+ * Noise key. Throws for a location that isn't an ordinary per-user path.
+ */
+export function daemonIdentityFile(stateDir, os = platform()) {
+    if (os === "win32") {
+        const norm = stateDir.replace(/\//g, "\\");
+        if (norm.startsWith("\\\\")) {
+            throw mdbaseError("invalid_request", `daemon state directory must be a local path, not ${stateDir}`, "untrusted_identity");
+        }
+        if (!win32.isAbsolute(norm))
+            throw mdbaseError("invalid_request", "daemon state directory must be absolute");
+        return win32.join(norm, "daemon.json");
+    }
+    if (!stateDir.startsWith("/"))
+        throw mdbaseError("invalid_request", "daemon state directory must be absolute");
+    return join(stateDir, "daemon.json");
+}
+function untrusted(p, st) {
+    const uid = process.getuid?.();
+    if (st.isSymbolicLink())
+        return `${p} is a symlink`;
+    if (uid !== undefined && st.uid !== uid)
+        return `${p} is owned by another user`;
+    if ((st.mode & 0o022) !== 0)
+        return `${p} is writable by group or others`;
+    return null;
+}
+function refuse(why) {
+    throw mdbaseError("unauthenticated", `refusing the daemon identity: ${why}`, "untrusted_identity");
+}
+function notRunning(p) {
+    throw mdbaseError("unavailable", `the mdbase daemon is not running (no ${p})`, "daemon_not_running");
+}
+/**
+ * Read the daemon's identity, `{"device": "<uuid>", "noise_pk": "<64 hex>"}`, from
+ * `daemon.json` in its state directory, after checking who owns it.
+ */
+/**
+ * Read an owner-only JSON file from the daemon's state directory: the directory is
+ * `lstat`-checked, the file is opened (`O_NOFOLLOW`) and then the **opened handle** is
+ * checked (regular file, owned by this uid, no group/other write), so there is no
+ * check-then-read race.
+ */
+async function readOwnerOnlyJson(stateDir, name) {
+    const file = daemonIdentityFile(stateDir).replace(/daemon\.json$/, name);
+    const posix = platform() !== "win32";
+    if (posix) {
+        let st;
+        try {
+            st = await lstat(stateDir);
+        }
+        catch {
+            notRunning(stateDir);
+        }
+        const why = untrusted(stateDir, st);
+        if (why)
+            refuse(why);
+    }
+    let fh;
+    try {
+        fh = await open(file, posix ? fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW : "r");
+    }
+    catch (e) {
+        if (e.code === "ELOOP")
+            refuse(`${file} is a symlink`);
+        notRunning(file);
+    }
+    let raw;
+    try {
+        const st = await fh.stat();
+        if (!st.isFile())
+            refuse(`${file} is not a regular file`);
+        if (posix) {
+            const why = untrusted(file, { isSymbolicLink: () => false, uid: st.uid, mode: st.mode });
+            if (why)
+                refuse(why);
+        }
+        raw = await fh.readFile("utf8");
+    }
+    finally {
+        await fh.close();
+    }
+    try {
+        return { file, json: JSON.parse(raw) };
+    }
+    catch {
+        throw mdbaseError("internal", `${file} is not valid JSON`);
+    }
+}
+/**
+ * Read the daemon's identity, `{"device": "<uuid>", "noise_pk": "<64 hex>"}`, from
+ * `daemon.json` in its state directory, after checking who owns it.
+ */
+export async function readDaemonIdentity(stateDir = defaultDaemonStateDir()) {
+    const { file, json: j } = await readOwnerOnlyJson(stateDir, "daemon.json");
+    if (j.schema_version !== undefined && j.schema_version !== 1) {
+        throw mdbaseError("upgrade_required", `${file} has schema_version ${j.schema_version}`);
+    }
+    if (!j.device || !j.noise_pk || !/^[0-9a-f]{64}$/.test(j.noise_pk)) {
+        throw mdbaseError("internal", `${file} is incomplete`);
+    }
+    return { device: j.device, noisePublicKey: fromHex(j.noise_pk) };
+}
+/**
+ * The localhost link (§12.4): `local-link.json` (`{port, token}`) plus the pinned
+ * identity from `daemon.json`, both owner-checked.
+ */
+export async function readLocalLink(stateDir = defaultDaemonStateDir()) {
+    const id = await readDaemonIdentity(stateDir);
+    const { file, json: j } = await readOwnerOnlyJson(stateDir, "local-link.json");
+    if (!Number.isInteger(j.port) || !j.token || !/^[0-9a-f]{64}$/.test(j.token)) {
+        throw mdbaseError("internal", `${file} is incomplete`);
+    }
+    return { port: j.port, token: fromHex(j.token), device: id.device, noisePublicKey: id.noisePublicKey };
+}
+/**
+ * Connect to the desktop daemon over the localhost link as the hosting session of
+ * `collection` (§12.4). Re-reads the link files on every reconnect (new port and token
+ * at each daemon start). For Obsidian, pass `webSocket` if the global one isn't used.
+ */
+export function connectDaemonLocalhost(o) {
+    return localLinkConnector({
+        collection: o.collection,
+        ...(o.localOnly ? { localOnly: true } : {}),
+        ...(o.webSocket ? { webSocket: o.webSocket } : {}),
+        link: () => readLocalLink(o.stateDir),
+    });
+}
+function socketStream(sock) {
+    const s = {
+        ondata: null,
+        onclose: null,
+        write: (b) => void sock.write(b),
+        close: () => sock.destroy(),
+    };
+    sock.on("data", (d) => s.ondata?.(new Uint8Array(d.buffer, d.byteOffset, d.byteLength)));
+    sock.on("close", () => s.onclose?.());
+    sock.on("error", (e) => s.onclose?.(e));
+    return s;
+}
+function openSocket(path, signal) {
+    return new Promise((resolve, reject) => {
+        const sock = netConnect(path);
+        const onAbort = () => {
+            sock.destroy();
+            reject(mdbaseError("cancelled", "connect aborted"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        sock.once("connect", () => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve(streamCarrier(socketStream(sock)));
+        });
+        sock.once("error", (e) => {
+            signal?.removeEventListener("abort", onAbort);
+            const notRunning = e.code === "ENOENT" || e.code === "ECONNREFUSED";
+            reject(mdbaseError("unavailable", notRunning ? "the mdbase daemon is not running" : e.message, {
+                ...(notRunning ? { reason: "daemon_not_running" } : {}),
+                retryAfterMs: 1000,
+            }));
+        });
+    });
+}
+/** A connector to the desktop daemon over local IPC. */
+export function ipcConnector(o) {
+    const collection = uuidToBytes(o.collection);
+    const grant = o.grant ? uuidToBytes(o.grant) : null;
+    return noiseConnector({
+        description: `ipc:${o.path ?? "default"}`,
+        staticKey: o.staticKey,
+        target: async () => {
+            const path = o.path ?? defaultIpcPath();
+            const daemon = o.daemon ?? (await readDaemonIdentity(o.stateDir));
+            const prologue = clientPrologue(collection, grant, uuidToBytes(daemon.device));
+            return {
+                prologue,
+                remoteStatic: daemon.noisePublicKey,
+                // One daemon serves many collections on one socket: the prologue goes first,
+                // in clear, as one `u16be(64) ‖ prologue` record so the daemon can pick the
+                // collection and grant (daemon interface note §3). Tampering fails the handshake.
+                preamble: prologue,
+                device: daemon.device,
+                openCarrier: (signal) => openSocket(path, signal),
+            };
+        },
+    });
+}
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"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"}

package/dist/notifications.d.ts

@@ -0,0 +1,95 @@
+export declare const MDBASE_NOTIFICATION_TYPE = "mdbase.notification";
+/** The message `handleMdbaseNotificationClick` posts to the app window it focuses. */
+export declare const MDBASE_NOTIFICATION_CLICK = "mdbase.notification.click";
+export interface MdbaseNotificationPresentation {
+    title: string;
+    body?: string;
+    tag?: string;
+}
+/** A validated envelope. */
+export interface MdbaseNotification {
+    version: 1;
+    /** Idempotency key: the same signal may be delivered more than once. */
+    signalId: string;
+    /** The app's manifest criterion id. Its meaning is the app's own. */
+    criterionId: string;
+    /** Opaque wake cursor. Never parse it. */
+    cursor: string;
+    /** Static manifest text. `null` for native data, where the OS shows the text. */
+    presentation: MdbaseNotificationPresentation | null;
+}
+export interface MdbaseNotificationClickMessage {
+    type: typeof MDBASE_NOTIFICATION_CLICK;
+    notification: MdbaseNotification;
+}
+export interface MdbaseNotificationDisplayOptions {
+    icon?: string;
+    badge?: string;
+}
+/** The parts of a `ServiceWorkerRegistration` the helpers use. */
+export interface MdbaseNotificationRegistration {
+    readonly scope?: string;
+    showNotification(title: string, options?: NotificationOptions): Promise<void>;
+}
+/** The parts of a service-worker `PushEvent` the helpers use. */
+export interface MdbasePushEvent {
+    readonly data: {
+        text(): string;
+    } | null;
+    waitUntil(promise: Promise<unknown>): void;
+}
+/** The parts of a service-worker `NotificationEvent` the helpers use. */
+export interface MdbaseNotificationClickEvent {
+    readonly notification: {
+        readonly data: unknown;
+        close(): void;
+    };
+    waitUntil(promise: Promise<unknown>): void;
+}
+interface WindowClientLike {
+    readonly url: string;
+    focus(): Promise<unknown>;
+    postMessage(message: unknown): void;
+}
+/** The parts of a service worker's `Clients` the helpers use. */
+export interface MdbaseNotificationClients {
+    matchAll(options: {
+        type: "window";
+        includeUncontrolled: boolean;
+    }): Promise<readonly WindowClientLike[]>;
+    openWindow(url: string): Promise<unknown>;
+}
+export interface HandleMdbasePushOptions extends MdbaseNotificationDisplayOptions {
+    /** Defaults to the service worker's own `registration`. */
+    registration?: MdbaseNotificationRegistration;
+}
+export interface HandleMdbaseNotificationClickOptions {
+    /** The page to open when no app window is open. Defaults to the registration scope. */
+    url?: string;
+    /** Defaults to the service worker's own `clients`. */
+    clients?: MdbaseNotificationClients;
+    /** Defaults to the service worker's own `registration.scope`. */
+    scope?: string;
+}
+/** Parse a Web Push payload: an object, a JSON string or `PushMessageData`. */
+export declare function parseMdbasePush(value: unknown): MdbaseNotification;
+/** Parse the string-valued data of an FCM/APNs notification (`version` "1" or 1). */
+export declare function parseMdbaseNativeNotification(data: unknown): MdbaseNotification;
+/** Read the envelope kept on a shown notification, or on a native tap. `null` if it is not one. */
+export declare function readMdbaseNotificationData(data: unknown): MdbaseNotification | null;
+/** Validate a Web Push payload and show it. Resolves with the envelope. */
+export declare function showMdbaseNotification(registration: MdbaseNotificationRegistration, value: unknown, options?: MdbaseNotificationDisplayOptions): Promise<MdbaseNotification>;
+/**
+ * A service-worker `push` handler. Returns `false` for a push that is not an
+ * mdbase notification, so the app can handle its own pushes. Otherwise it
+ * shows the notification inside `event.waitUntil` and returns `true`.
+ */
+export declare function handleMdbasePush(event: MdbasePushEvent, options?: HandleMdbasePushOptions): boolean;
+/**
+ * A service-worker `notificationclick` handler. Returns `false` for a
+ * notification that is not an mdbase one. Otherwise it closes it, focuses an
+ * open app window (posting `MdbaseNotificationClickMessage` to it) or opens
+ * `url`, and returns `true`.
+ */
+export declare function handleMdbaseNotificationClick(event: MdbaseNotificationClickEvent, options?: HandleMdbaseNotificationClickOptions): boolean;
+export {};

package/dist/notifications.js

@@ -0,0 +1,226 @@
+/**
+ * `@mdbase-dev/sdk/notifications`: the mdbase push delivery envelope
+ * (`docs/contracts/push-envelope.md`) and service-worker helpers.
+ *
+ * The envelope is opaque. It carries a dedupe key, an opaque wake cursor, the
+ * app's own manifest criterion id and the criterion's static presentation. It
+ * never carries record, timer or collection identifiers or app data. Treat the
+ * presentation as untrusted text and a push as a wake-up hint: on wake, the app
+ * reads current state through its connection.
+ *
+ * This module imports no Worker, wasm or client code, so a service worker can
+ * import it on its own.
+ */
+import { MdbaseError, mdbaseError } from "./errors.js";
+export const MDBASE_NOTIFICATION_TYPE = "mdbase.notification";
+/** The message `handleMdbaseNotificationClick` posts to the app window it focuses. */
+export const MDBASE_NOTIFICATION_CLICK = "mdbase.notification.click";
+// Visible ASCII: today `tmr_` + base64url for timers; connector signals may differ.
+const OPAQUE = /^[\x21-\x7e]{1,256}$/;
+const CRITERION = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
+const invalid = (message) => mdbaseError("invalid_request", message, "invalid_push_payload");
+const unsupported = () => mdbaseError("upgrade_required", "The push uses an envelope version this SDK does not support.", "unsupported_push_version");
+function object(value) {
+    if (typeof value === "string") {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            throw invalid("The push payload is not JSON.");
+        }
+    }
+    else if (value && typeof value === "object" && typeof value.json === "function") {
+        try {
+            value = value.json();
+        }
+        catch {
+            throw invalid("The push payload is not JSON.");
+        }
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw invalid("The push payload is not an object.");
+    return value;
+}
+function text(value, min, max) {
+    return typeof value === "string" && value.length >= min && value.length <= max;
+}
+function presentation(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const p = value;
+    if (!text(p.title, 1, 80) || (p.body !== undefined && !text(p.body, 0, 160))
+        || (p.tag !== undefined && !text(p.tag, 1, 80)))
+        return null;
+    return Object.freeze({
+        title: p.title,
+        ...(typeof p.body === "string" && p.body.length ? { body: p.body } : {}),
+        ...(typeof p.tag === "string" ? { tag: p.tag } : {}),
+    });
+}
+function envelope(raw, version, shown) {
+    if (raw.type !== MDBASE_NOTIFICATION_TYPE)
+        throw invalid("The payload is not an mdbase notification.");
+    if (version !== 1) {
+        if (typeof version === "number" && Number.isSafeInteger(version) && version > 1)
+            throw unsupported();
+        throw invalid("The payload has no valid envelope version.");
+    }
+    if (!text(raw.signal_id, 1, 256) || !OPAQUE.test(raw.signal_id) || !text(raw.cursor, 1, 256) || !OPAQUE.test(raw.cursor)
+        || !text(raw.criterion_id, 1, 100) || !CRITERION.test(raw.criterion_id)) {
+        throw invalid("The payload is not an mdbase notification.");
+    }
+    // Unknown fields are ignored: v1 may gain optional fields.
+    return Object.freeze({ version: 1, signalId: raw.signal_id, criterionId: raw.criterion_id, cursor: raw.cursor, presentation: shown });
+}
+/** Parse a Web Push payload: an object, a JSON string or `PushMessageData`. */
+export function parseMdbasePush(value) {
+    const raw = object(value);
+    const result = envelope(raw, raw.version, presentation(raw.presentation));
+    if (!result.presentation)
+        throw invalid("The push has no valid presentation.");
+    return result;
+}
+/** Parse the string-valued data of an FCM/APNs notification (`version` "1" or 1). */
+export function parseMdbaseNativeNotification(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        throw invalid("The native notification data is not an object.");
+    const raw = data;
+    const version = typeof raw.version === "string" && /^[1-9][0-9]{0,8}$/.test(raw.version) ? Number(raw.version) : raw.version;
+    return envelope(raw, version, null);
+}
+/** Read the envelope kept on a shown notification, or on a native tap. `null` if it is not one. */
+export function readMdbaseNotificationData(data) {
+    try {
+        return parseMdbaseNativeNotification(data);
+    }
+    catch {
+        return null;
+    }
+}
+/** The `data` kept on a shown notification. Same shape as prod Connect builds. */
+function shownData(n) {
+    return { type: MDBASE_NOTIFICATION_TYPE, version: n.version, signal_id: n.signalId, criterion_id: n.criterionId, cursor: n.cursor };
+}
+/** Validate a Web Push payload and show it. Resolves with the envelope. */
+export async function showMdbaseNotification(registration, value, options = {}) {
+    const n = parseMdbasePush(value);
+    const p = n.presentation;
+    await registration.showNotification(p.title, {
+        ...(p.body ? { body: p.body } : {}),
+        ...(p.tag ? { tag: p.tag } : {}),
+        ...(options.icon ? { icon: options.icon } : {}),
+        ...(options.badge ? { badge: options.badge } : {}),
+        data: shownData(n),
+    });
+    return n;
+}
+function own(name) {
+    return globalThis[name];
+}
+/** The service worker's own origin (its location, else its registration scope). */
+function workerOrigin(registrationScope) {
+    const location = globalThis.location;
+    if (typeof location?.origin === "string" && location.origin !== "null")
+        return location.origin;
+    try {
+        return registrationScope ? new URL(registrationScope).origin : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Click `url`/`scope` must stay on the app's own origin. Without a known
+ * origin only a root-relative path is accepted. */
+function sameOrigin(value, origin, name) {
+    const reject = () => mdbaseError("invalid_request", `The notification click ${name} must be on the app's own origin.`, "click_target_cross_origin");
+    if (typeof value !== "string")
+        throw reject();
+    if (origin === null) {
+        if (!value.startsWith("/") || value.startsWith("//") || value.startsWith("/\\"))
+            throw reject();
+        return value;
+    }
+    let url;
+    try {
+        url = new URL(value, `${origin}/`);
+    }
+    catch {
+        throw reject();
+    }
+    if (url.origin !== origin)
+        throw reject();
+    return url.href;
+}
+/**
+ * A service-worker `push` handler. Returns `false` for a push that is not an
+ * mdbase notification, so the app can handle its own pushes. Otherwise it
+ * shows the notification inside `event.waitUntil` and returns `true`.
+ */
+export function handleMdbasePush(event, options = {}) {
+    let raw;
+    try {
+        raw = object(event.data?.text() ?? null);
+    }
+    catch {
+        return false;
+    }
+    if (raw.type !== MDBASE_NOTIFICATION_TYPE)
+        return false;
+    const registration = options.registration ?? own("registration");
+    if (!registration)
+        throw mdbaseError("invalid_request", "No service worker registration to show the notification.", "push_registration_missing");
+    const display = { ...(options.icon ? { icon: options.icon } : {}), ...(options.badge ? { badge: options.badge } : {}) };
+    event.waitUntil((async () => {
+        try {
+            parseMdbasePush(raw);
+        }
+        catch (error) {
+            // Only a NEWER envelope major falls back: it still carries a displayable
+            // presentation, shown without data rather than a browser's generic
+            // "updated in the background". Malformed v1 stays rejected.
+            const shown = error instanceof MdbaseError && error.reason === "unsupported_push_version" ? presentation(raw.presentation) : null;
+            if (!shown)
+                throw error;
+            await registration.showNotification(shown.title, {
+                ...(shown.body ? { body: shown.body } : {}),
+                ...(shown.tag ? { tag: shown.tag } : {}),
+                ...display,
+            });
+            return null;
+        }
+        // Display failures propagate; they are not a compatibility case.
+        return showMdbaseNotification(registration, raw, display);
+    })());
+    return true;
+}
+/**
+ * A service-worker `notificationclick` handler. Returns `false` for a
+ * notification that is not an mdbase one. Otherwise it closes it, focuses an
+ * open app window (posting `MdbaseNotificationClickMessage` to it) or opens
+ * `url`, and returns `true`.
+ */
+export function handleMdbaseNotificationClick(event, options = {}) {
+    const n = readMdbaseNotificationData(event.notification.data);
+    if (!n)
+        return false;
+    event.notification.close();
+    const clients = options.clients ?? own("clients");
+    const registrationScope = own("registration")?.scope;
+    const origin = workerOrigin(registrationScope);
+    const scope = options.scope === undefined ? registrationScope : sameOrigin(options.scope, origin, "scope");
+    const target = options.url === undefined ? scope ?? "/" : sameOrigin(options.url, origin, "url");
+    if (!clients)
+        return true;
+    event.waitUntil((async () => {
+        const windows = await clients.matchAll({ type: "window", includeUncontrolled: true });
+        const open = windows.find(client => !scope || client.url.startsWith(scope));
+        if (!open)
+            return clients.openWindow(target);
+        await open.focus();
+        const message = { type: MDBASE_NOTIFICATION_CLICK, notification: n };
+        open.postMessage(message);
+        return open;
+    })());
+    return true;
+}
+//# sourceMappingURL=notifications.js.map