@rapidmx/web-client 0.20.0 → 0.22.0

package/dist/lib/mail/messageBodySanitizer.js

@@ -0,0 +1,118 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Client-side sanitizing for message bodies the server never sanitized (decrypted or verified content) and for
+ * message HTML re-embedded elsewhere (a reply's quote). DOMPurify's defaults drop scripts, `on*` handlers and
+ * `javascript:` URLs; on top of that every remote resource reference is removed, so rendering or quoting a body
+ * can't ping a tracker. Only `data:` and `cid:` references survive.
+ */
+import DOMPurify from "dompurify";
+const EMBEDDED_URI = /^\s*(?:data|cid):/i;
+/** Attributes whose value makes the browser fetch a resource (as opposed to a user-clicked link). */
+const RESOURCE_URI_ATTRIBUTES = new Set(["src", "srcset", "background", "poster", "lowsrc", "dynsrc", "xlink:href", "action", "formaction"]);
+/** Decodes CSS escapes first (so an escaped `u\72l(` can't hide from the checks below), then drops every
+ * `@import` and neutralizes every `url()`/`image-set()` reference that isn't a `data:`/`cid:` URI. */
+export function stripRemoteCssUrls(css) {
+    return css
+        .replace(/\\([0-9a-f]{1,6})\s?/gi, (_match, hex) => String.fromCodePoint(Math.min(parseInt(hex, 16), 0x10ffff)))
+        .replace(/\\(.)/g, "$1")
+        .replace(/@import[^;]*;?/gi, "")
+        .replace(/(?:-webkit-)?image-set\((?:[^()]|\([^()]*\))*\)/gi, (match) => [...match.matchAll(/(["'])(.*?)\1/g)].every(([, , uri]) => EMBEDDED_URI.test(uri)) ? match : "none")
+        .replace(/url\(\s*(["']?)(.*?)\1\s*\)/gi, (match, _quote, uri) => (EMBEDDED_URI.test(uri) ? match : "none"));
+}
+let bodyPurifier;
+/** A dedicated DOMPurify instance (hooks registered here never leak into any other DOMPurify caller) that
+ * additionally strips every remote resource reference - see `stripRemoteCssUrls()`. `undefined` without a DOM
+ * (server-side rendering), where DOMPurify can't sanitize at all. */
+function getBodyPurifier() {
+    if (bodyPurifier) {
+        return bodyPurifier;
+    }
+    if (typeof window === "undefined") {
+        return undefined;
+    }
+    const purifier = DOMPurify(window);
+    if (!purifier.isSupported) {
+        return undefined;
+    }
+    purifier.addHook("uponSanitizeElement", (node, data) => {
+        if (data.tagName === "style") {
+            // An element's `textContent` is always a string (only documents/doctypes yield null).
+            node.textContent = stripRemoteCssUrls(node.textContent);
+        }
+    });
+    purifier.addHook("uponSanitizeAttribute", (node, data) => {
+        const name = data.attrName.toLowerCase();
+        if (name === "style") {
+            data.attrValue = stripRemoteCssUrls(data.attrValue);
+            return;
+        }
+        const isNavigationLink = name === "href" && ["a", "area"].includes(node.nodeName.toLowerCase());
+        if (RESOURCE_URI_ATTRIBUTES.has(name) || (name === "href" && !isNavigationLink)) {
+            const candidates = name === "srcset" ? data.attrValue.split(/,\s+/) : [data.attrValue];
+            if (!candidates.every((candidate) => EMBEDDED_URI.test(candidate))) {
+                data.keepAttr = false;
+            }
+        }
+    });
+    bodyPurifier = purifier;
+    return purifier;
+}
+/** Tags a displayed body may never carry, whatever else is allowed. `svg`/`math` are forbidden here too (not just
+ * on the quote path below) because this function renders a RECEIVED message's HTML — attacker-controlled content —
+ * and DOMPurify's default SVG/MathML allowlist has a history of mutation-XSS bypasses; there's no legitimate need
+ * for either in a mail body display. */
+const DISPLAY_FORBIDDEN_TAGS = ["link", "meta", "base", "svg", "math"];
+/**
+ * Sanitizes a message body for display (a sandboxed `srcDoc`, behind its own CSP): DOMPurify's defaults plus the
+ * remote-resource stripping above, and no `<link>`, `<meta>` or `<base>`. Returns `""` when there is no DOM to
+ * sanitize with - never the unsanitized input.
+ */
+export function sanitizeMessageBodyHtml(html) {
+    return getBodyPurifier()?.sanitize(html, { FORBID_TAGS: DISPLAY_FORBIDDEN_TAGS }) ?? "";
+}
+/** On top of the display policy: nothing that styles, frames or submits from inside the compose editor. */
+const QUOTE_FORBIDDEN_TAGS = [
+    ...DISPLAY_FORBIDDEN_TAGS,
+    "style",
+    "title",
+    "form",
+    "input",
+    "button",
+    "select",
+    "option",
+    "textarea",
+    "iframe",
+    "frame",
+    "frameset",
+    "object",
+    "embed",
+    "audio",
+    "video",
+    "source",
+    "track",
+    // svg/math are already in DISPLAY_FORBIDDEN_TAGS, spread above — not repeated here.
+];
+/**
+ * Sanitizes message HTML for quoting into a compose body: the display policy (`sanitizeMessageBodyHtml()`), without
+ * the tags in `QUOTE_FORBIDDEN_TAGS`, and without any image that isn't embedded as a `data:` URI - a `cid:` image
+ * refers to a part of the original message the reply doesn't carry. Returns `""` when there is no DOM to sanitize
+ * with.
+ */
+export function sanitizeQuotedHtml(html) {
+    const purifier = getBodyPurifier();
+    if (!purifier) {
+        return "";
+    }
+    const fragment = purifier.sanitize(html, { FORBID_TAGS: QUOTE_FORBIDDEN_TAGS, RETURN_DOM_FRAGMENT: true });
+    for (const image of Array.from(fragment.querySelectorAll("img"))) {
+        if (!/^\s*data:/i.test(image.getAttribute("src") ?? "")) {
+            image.remove();
+        }
+    }
+    const container = document.createElement("div");
+    container.appendChild(fragment);
+    return container.innerHTML;
+}

package/dist/lib/mail/pushClient.d.ts

@@ -0,0 +1,106 @@
+/** The subset of the browser's `WebSocket` this client uses - what a test's fake implements. */
+export interface PushSocket {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+}
+export type PushSocketFactory = (url: string) => PushSocket;
+/** An event delivered over the push channel, normalised - see this module's doc comment. */
+export interface PushEvent {
+    /** The published `type`: the model class name (`MessageMongo`), or `"MESSAGE"` for an unstructured payload. */
+    type: string;
+    action?: string;
+    data?: unknown;
+    /** Only present when the server wrapped the event with its channel. */
+    channel?: string;
+}
+/** `"open"`: connected and subscribed. `"closed"`: shut down for good by `close()` - it will not reconnect. */
+export type PushStatus = "idle" | "connecting" | "open" | "reconnecting" | "closed";
+/**
+ * How many channels one tab asks for. The server allows a user 50 in total, shared by every tab and duplicates counting
+ * again, so a tab stays well under it and leaves room for a second one. `setChannels()` keeps the first this many, so a
+ * caller orders its channels most important first.
+ */
+export declare const PUSH_MAX_CHANNELS = 40;
+/** The first reconnect waits about this long, and each further failure doubles it ... */
+export declare const PUSH_BACKOFF_BASE_MS = 1000;
+/** ... up to this. */
+export declare const PUSH_BACKOFF_MAX_MS = 60000;
+/** The push WebSocket's URL: the configured API origin (`configureApiBaseUrl()`), else this page's own, on `ws:`/`wss:`
+ * to match. `undefined` where there is no origin to use (server-side rendering). */
+export declare function pushUrl(): string | undefined;
+export interface PushClientOptions {
+    /** The URL to connect to. Defaults to `pushUrl()`. */
+    url?: () => string | undefined;
+    /** Creates the socket. Defaults to the browser's `WebSocket`, if there is one. */
+    createSocket?: PushSocketFactory;
+    /** A `Math.random()` stand-in, for the backoff's jitter. */
+    random?: () => number;
+}
+export declare class PushClient {
+    private readonly options;
+    private socket;
+    private closed;
+    private started;
+    private ready;
+    private attempt;
+    private timer;
+    private nextRequestId;
+    private current;
+    /** What the caller wants to hear about, most important first. */
+    private desired;
+    /** What this socket is subscribed to (including whatever the server put it on at connect). */
+    private subscribed;
+    /** The channels this client itself asked for and was granted - the only ones it may unsubscribe. */
+    private granted;
+    /** Requests awaiting their reply, by id: the channels asked for. */
+    private pending;
+    private readonly eventListeners;
+    private readonly statusListeners;
+    constructor(options?: PushClientOptions);
+    get status(): PushStatus;
+    /** Connects (once - a second call does nothing) and keeps reconnecting until `close()`. */
+    start(): void;
+    /**
+     * Shuts the client down for good: closes the socket, stops reconnecting and drops nothing else. For sign-out, when
+     * the session behind the socket has ended. A closed client cannot be started again.
+     */
+    close(): void;
+    /**
+     * Sets the channels (folder and mailbox uids) to receive events for. Deduplicated and cut to `PUSH_MAX_CHANNELS`; on
+     * an open socket the difference is subscribed/unsubscribed at once, otherwise it is sent when the socket opens.
+     */
+    setChannels(channels: readonly string[]): void;
+    /** Calls `listener` with every event; returns the function that stops it. */
+    onEvent(listener: (event: PushEvent) => void): () => void;
+    /** Calls `listener` whenever `status` changes; returns the function that stops it. */
+    onStatus(listener: (status: PushStatus) => void): () => void;
+    /** Reconnects now, without waiting out the backoff - for the browser coming back online. A no-op unless the client is
+     * between attempts. */
+    reconnectNow(): void;
+    private setStatus;
+    private connect;
+    /**
+     * Waits out an exponentially growing, jittered delay ("equal jitter": half of it fixed, half random) and reconnects.
+     * Only ever reached with no timer pending and the client open: a socket's close is ignored once it is replaced or
+     * `close()` has detached it, and `close()`/`reconnectNow()` clear the timer before anything else can run.
+     */
+    private scheduleReconnect;
+    private handleFrame;
+    private handleSubscribed;
+    /** Asks for the wanted channels the socket isn't on yet, and drops the ones this client asked for and no longer wants. */
+    private syncSubscriptions;
+    private send;
+    private emit;
+}
+/** The tab's one push client (created on first use). Sharing it is what keeps a tab to one socket. */
+export declare function getPushClient(): PushClient;
+/** Closes the tab's push client and forgets it, so the next `getPushClient()` makes a fresh one. For a test, or a page
+ * that stays open after its session ended and might sign in again; ordinary sign-out just navigates away. */
+export declare function resetPushClient(): void;

package/dist/lib/mail/pushClient.js

@@ -0,0 +1,317 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * A client for the server's real-time push channel (`@rapidmx/restapi`'s `MailPushRoute`, `@rapidrest/service-core`'s
+ * `BasePushRoute`), which the webmail uses to learn of new mail without a page reload.
+ *
+ * The protocol, as `BasePushRoute` implements it:
+ *
+ * - The WebSocket is `wss://<origin>/push` - the route's own base path, **not** under `/api` and with no `/connect`
+ * suffix. It authenticates from the `jwt` cookie the browser sends with the upgrade (a script can't read that
+ * cookie, so there is no token to send). One user may hold at most 10 sockets, and be subscribed to at most 50 channels
+ * in total *across all of them* - see `PUSH_MAX_CHANNELS`.
+ * - Right after connecting the server sends `{ id: 0, type: "SUBSCRIBED", data: [<channels this socket is already on>] }`.
+ * - A client subscribes with `{ id, type: "SUBSCRIBE", data: [channel, ...] }` and gets `{ id, type: "SUBSCRIBED", data:
+ * [<the channels it was allowed>] }`; `UNSUBSCRIBE`/`UNSUBSCRIBED` mirror that. A channel is a bare `Folder.uid` or
+ * `Mailbox.uid`, permission-checked (read) per channel; a channel that is refused is simply left out of the reply.
+ * - An event arrives as the JSON `NotificationUtils.sendMessage()` published: `{ type, action, data }`, where `type` is
+ * the model class name (`MessageMongo`, `MessageSQL`, ...), `action` is `create`/`update`/`delete` and `data` the
+ * entity - for a message, the whole `Message`, including its `folderUid`. The frame does **not** say which channel it
+ * came over. (A message sent through the route's `POST /push/:id` is instead wrapped `{ type: "MESSAGE", channel, data:
+ * { type, action, data } }`; both shapes are accepted and normalised to a `PushEvent`.)
+ * - Delivery is fire-and-forget over Redis pub/sub: an event published while the socket was down is never replayed. A UI
+ * must therefore also poll (see `MailShell`) and refetch after a reconnect.
+ *
+ * One `PushClient` is shared by the whole tab (`getPushClient()`), since the per-user socket cap is small. It reconnects by
+ * itself with exponential backoff and jitter, and re-subscribes each time. Everything is a no-op where there is no
+ * `WebSocket` (server-side rendering, an old browser), so a caller need not check.
+ */
+import { apiOrigin } from "../util/api.js";
+/** The `WebSocket.OPEN` readyState. */
+const SOCKET_OPEN = 1;
+/**
+ * How many channels one tab asks for. The server allows a user 50 in total, shared by every tab and duplicates counting
+ * again, so a tab stays well under it and leaves room for a second one. `setChannels()` keeps the first this many, so a
+ * caller orders its channels most important first.
+ */
+export const PUSH_MAX_CHANNELS = 40;
+/** The first reconnect waits about this long, and each further failure doubles it ... */
+export const PUSH_BACKOFF_BASE_MS = 1000;
+/** ... up to this. */
+export const PUSH_BACKOFF_MAX_MS = 60000;
+/** The push WebSocket's URL: the configured API origin (`configureApiBaseUrl()`), else this page's own, on `ws:`/`wss:`
+ * to match. `undefined` where there is no origin to use (server-side rendering). */
+export function pushUrl() {
+    const origin = apiOrigin() || (typeof window !== "undefined" ? window.location.origin : "");
+    return origin ? `${origin.replace(/^http/i, "ws")}/push` : undefined;
+}
+function defaultSocketFactory() {
+    return typeof WebSocket === "undefined" ? undefined : (url) => new WebSocket(url);
+}
+export class PushClient {
+    constructor(options = {}) {
+        this.options = options;
+        this.closed = false;
+        this.started = false;
+        this.ready = false;
+        this.attempt = 0;
+        this.nextRequestId = 1;
+        this.current = "idle";
+        /** What the caller wants to hear about, most important first. */
+        this.desired = [];
+        /** What this socket is subscribed to (including whatever the server put it on at connect). */
+        this.subscribed = new Set();
+        /** The channels this client itself asked for and was granted - the only ones it may unsubscribe. */
+        this.granted = new Set();
+        /** Requests awaiting their reply, by id: the channels asked for. */
+        this.pending = new Map();
+        this.eventListeners = new Set();
+        this.statusListeners = new Set();
+    }
+    get status() {
+        return this.current;
+    }
+    /** Connects (once - a second call does nothing) and keeps reconnecting until `close()`. */
+    start() {
+        if (this.started || this.closed) {
+            return;
+        }
+        this.started = true;
+        this.connect();
+    }
+    /**
+     * Shuts the client down for good: closes the socket, stops reconnecting and drops nothing else. For sign-out, when
+     * the session behind the socket has ended. A closed client cannot be started again.
+     */
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        const socket = this.socket;
+        this.socket = undefined;
+        this.ready = false;
+        if (socket) {
+            socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
+            try {
+                socket.close(1000, "closing");
+            }
+            catch {
+                // Already gone.
+            }
+        }
+        this.setStatus("closed");
+    }
+    /**
+     * Sets the channels (folder and mailbox uids) to receive events for. Deduplicated and cut to `PUSH_MAX_CHANNELS`; on
+     * an open socket the difference is subscribed/unsubscribed at once, otherwise it is sent when the socket opens.
+     */
+    setChannels(channels) {
+        this.desired = [...new Set(channels)].slice(0, PUSH_MAX_CHANNELS);
+        if (this.ready) {
+            this.syncSubscriptions();
+        }
+    }
+    /** Calls `listener` with every event; returns the function that stops it. */
+    onEvent(listener) {
+        this.eventListeners.add(listener);
+        return () => this.eventListeners.delete(listener);
+    }
+    /** Calls `listener` whenever `status` changes; returns the function that stops it. */
+    onStatus(listener) {
+        this.statusListeners.add(listener);
+        return () => this.statusListeners.delete(listener);
+    }
+    /** Reconnects now, without waiting out the backoff - for the browser coming back online. A no-op unless the client is
+     * between attempts. */
+    reconnectNow() {
+        if (this.closed || !this.started || this.socket) {
+            return;
+        }
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.attempt = 0;
+        this.connect();
+    }
+    setStatus(status) {
+        if (status === this.current) {
+            return;
+        }
+        this.current = status;
+        for (const listener of [...this.statusListeners]) {
+            listener(status);
+        }
+    }
+    connect() {
+        const url = (this.options.url ?? pushUrl)();
+        const createSocket = this.options.createSocket ?? defaultSocketFactory();
+        if (!url || !createSocket) {
+            // Nothing to connect with (server-side rendering, or no WebSocket): the caller's polling is all there is.
+            return;
+        }
+        let socket;
+        try {
+            socket = createSocket(url);
+        }
+        catch {
+            this.scheduleReconnect();
+            return;
+        }
+        this.socket = socket;
+        this.setStatus(this.attempt === 0 ? "connecting" : "reconnecting");
+        socket.onmessage = (event) => this.handleFrame(event.data);
+        socket.onclose = () => {
+            if (this.socket !== socket) {
+                return;
+            }
+            this.socket = undefined;
+            this.ready = false;
+            this.subscribed.clear();
+            this.granted.clear();
+            this.pending.clear();
+            this.scheduleReconnect();
+        };
+        // A failed connection is followed by a close, which is what triggers the retry.
+        socket.onerror = () => undefined;
+    }
+    /**
+     * Waits out an exponentially growing, jittered delay ("equal jitter": half of it fixed, half random) and reconnects.
+     * Only ever reached with no timer pending and the client open: a socket's close is ignored once it is replaced or
+     * `close()` has detached it, and `close()`/`reconnectNow()` clear the timer before anything else can run.
+     */
+    scheduleReconnect() {
+        const ceiling = Math.min(PUSH_BACKOFF_MAX_MS, PUSH_BACKOFF_BASE_MS * 2 ** Math.min(this.attempt, 30));
+        const delay = ceiling / 2 + ((this.options.random ?? Math.random)() * ceiling) / 2;
+        this.attempt += 1;
+        this.setStatus("reconnecting");
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.connect();
+        }, delay);
+    }
+    handleFrame(raw) {
+        if (typeof raw !== "string") {
+            return;
+        }
+        let frame;
+        try {
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== "object") {
+                return;
+            }
+            frame = parsed;
+        }
+        catch {
+            return;
+        }
+        switch (frame.type) {
+            case "SUBSCRIBED":
+                this.handleSubscribed(frame);
+                return;
+            case "UNSUBSCRIBED":
+                for (const channel of channelsOf(frame.data)) {
+                    this.subscribed.delete(channel);
+                    this.granted.delete(channel);
+                }
+                return;
+            case "LOGIN_RESPONSE":
+                return;
+            case "MESSAGE":
+                this.emit(unwrap(frame));
+                return;
+            default:
+                if (typeof frame.type === "string") {
+                    this.emit({ type: frame.type, action: asString(frame.action), data: frame.data });
+                }
+        }
+    }
+    handleSubscribed(frame) {
+        const channels = channelsOf(frame.data);
+        for (const channel of channels) {
+            this.subscribed.add(channel);
+        }
+        if (typeof frame.id === "number" && this.pending.delete(frame.id)) {
+            // The reply to one of our own SUBSCRIBE requests: those are the channels we were granted.
+            for (const channel of channels) {
+                this.granted.add(channel);
+            }
+            return;
+        }
+        if (frame.id === 0 && !this.ready) {
+            // The greeting sent as soon as the server has set the socket up: connected. Only now is a reconnect
+            // delay forgotten - a socket the server closes at once (over the cap, not signed in) never gets here.
+            this.ready = true;
+            this.attempt = 0;
+            this.setStatus("open");
+            this.syncSubscriptions();
+        }
+    }
+    /** Asks for the wanted channels the socket isn't on yet, and drops the ones this client asked for and no longer wants. */
+    syncSubscriptions() {
+        const wanted = new Set(this.desired);
+        const add = this.desired.filter((channel) => !this.subscribed.has(channel));
+        const remove = [...this.granted].filter((channel) => !wanted.has(channel));
+        if (add.length > 0) {
+            const id = this.nextRequestId++;
+            this.pending.set(id, add);
+            this.send({ id, type: "SUBSCRIBE", data: add });
+        }
+        if (remove.length > 0) {
+            this.send({ id: this.nextRequestId++, type: "UNSUBSCRIBE", data: remove });
+        }
+    }
+    send(message) {
+        const socket = this.socket;
+        if (!socket || socket.readyState !== SOCKET_OPEN) {
+            return;
+        }
+        try {
+            socket.send(JSON.stringify(message));
+        }
+        catch {
+            // The close that follows a dead socket reconnects and re-subscribes.
+        }
+    }
+    emit(event) {
+        for (const listener of [...this.eventListeners]) {
+            try {
+                listener(event);
+            }
+            catch {
+                // One listener's failure never stops another hearing the event.
+            }
+        }
+    }
+}
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function channelsOf(data) {
+    return Array.isArray(data) ? data.filter((channel) => typeof channel === "string") : [];
+}
+/** A `{ type: "MESSAGE", channel, data: { type, action, data } }` frame as the event it wraps. */
+function unwrap(frame) {
+    const channel = asString(frame.channel);
+    const inner = frame.data;
+    if (inner && typeof inner === "object" && typeof inner.type === "string") {
+        const { type, action, data } = inner;
+        return { type, action: asString(action), data, channel };
+    }
+    return { type: "MESSAGE", data: inner, channel };
+}
+let shared;
+/** The tab's one push client (created on first use). Sharing it is what keeps a tab to one socket. */
+export function getPushClient() {
+    shared ?? (shared = new PushClient());
+    return shared;
+}
+/** Closes the tab's push client and forgets it, so the next `getPushClient()` makes a fresh one. For a test, or a page
+ * that stays open after its session ended and might sign in again; ordinary sign-out just navigates away. */
+export function resetPushClient() {
+    shared?.close();
+    shared = undefined;
+}

package/dist/lib/mail/sendEvents.d.ts

@@ -0,0 +1,33 @@
+import type { PushEvent } from "./pushClient.js";
+import { SendFailure } from "./sendFailure.js";
+/**
+ * The outcome of a message sent in the background (`queueMessageSend()`), as the server publishes it on the sender's mailbox,
+ * Outbox and Sent Items channels once it has relayed - or failed to relay - the message:
+ * `{ type: <the Message model's class name>, action: "send-succeeded" | "send-failed" | "send-retrying", data: {...} }`.
+ */
+export type SendEventAction = "send-succeeded" | "send-failed" | "send-retrying";
+export interface SendEvent {
+    action: SendEventAction;
+    /** The message's uid. */
+    uid: string;
+    mailboxUid?: string;
+    subject: string;
+    /** Everyone the message was addressed to, as addresses. */
+    recipients: string[];
+    /** Which delivery attempt this outcome is about, from 1. */
+    attempt: number;
+    /** `send-retrying`: when the next attempt is made (ISO 8601). */
+    nextAttemptAt?: string;
+    /** `send-failed` / `send-retrying`: why the attempt failed. `details` is the shape `describeSendFailure()` reads. */
+    error?: {
+        message: string;
+        details?: unknown;
+    };
+}
+/**
+ * The send outcome a push event carries, or `undefined` when it is not one (another action, another type, a malformed payload).
+ * Read defensively: the payload is data from the network, so every field is checked and nothing is assumed.
+ */
+export declare function parseSendEvent(event: PushEvent): SendEvent | undefined;
+/** A send event's `error`, ready to show: the same plain message and technical lines a synchronous failure has. */
+export declare function describeSendEventError(error: SendEvent["error"], fallback: string): SendFailure;

package/dist/lib/mail/sendEvents.js

@@ -0,0 +1,44 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ApiRequestError } from "../util/api.js";
+import { describeSendFailure } from "./sendFailure.js";
+const ACTIONS = new Set(["send-succeeded", "send-failed", "send-retrying"]);
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+/**
+ * The send outcome a push event carries, or `undefined` when it is not one (another action, another type, a malformed payload).
+ * Read defensively: the payload is data from the network, so every field is checked and nothing is assumed.
+ */
+export function parseSendEvent(event) {
+    if (!/^Message/.test(event.type) || !event.action || !ACTIONS.has(event.action)) {
+        return undefined;
+    }
+    const data = event.data;
+    const uid = asString(data?.uid);
+    if (!data || !uid) {
+        return undefined;
+    }
+    const recipients = Array.isArray(data.recipients) ? data.recipients.filter((r) => typeof r === "string") : [];
+    const attempt = typeof data.attempt === "number" && Number.isFinite(data.attempt) && data.attempt >= 1 ? Math.floor(data.attempt) : 1;
+    const error = data.error;
+    return {
+        action: event.action,
+        uid,
+        mailboxUid: asString(data.mailboxUid),
+        subject: asString(data.subject) ?? "",
+        recipients,
+        attempt,
+        nextAttemptAt: asString(data.nextAttemptAt),
+        error: error && typeof error === "object" ? { message: asString(error.message) ?? "", details: error.details } : undefined,
+    };
+}
+/** A send event's `error`, ready to show: the same plain message and technical lines a synchronous failure has. */
+export function describeSendEventError(error, fallback) {
+    if (!error) {
+        return { message: fallback, lines: [] };
+    }
+    return describeSendFailure(new ApiRequestError(error.message || fallback, 0, undefined, error.details === undefined ? undefined : { details: error.details }), fallback);
+}

package/dist/lib/mail/sendFailure.d.ts

@@ -0,0 +1,16 @@
+/** A failed send, ready to show: the plain `message`, and the technical `lines` behind it (none when the server said no more). */
+export interface SendFailure {
+    message: string;
+    /** One line per fact the server gave - a per-recipient SMTP result, a transport error - as `key: value` text. Empty
+     * when the response carried nothing beyond its message. */
+    lines: string[];
+}
+/**
+ * Turns whatever a failed send threw into something a compose window can show. `message` is the server's own
+ * (the error's message, else `fallback`); `lines` are the structured `details` the send endpoint adds to its error body
+ * - typically per-recipient SMTP codes, enhanced status codes, the remote server's response text and any transport
+ * error. That shape is not fixed, so this reads it defensively: the body's `details` (an object or a list), or, without
+ * one, whatever else the body carries besides its message and code. Nothing is assumed, nothing throws, and a response
+ * with no details gives no lines - the caller then shows the message alone.
+ */
+export declare function describeSendFailure(err: unknown, fallback: string): SendFailure;