@rapidmx/web-client 0.8.0 → 0.10.0

package/dist/apps/shared/mail/folderCounts.d.ts

@@ -0,0 +1,78 @@
+import { Folder, FolderType, Mailbox, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+/**
+ * The folder badges' numbers, kept right without a reload.
+ *
+ * A folder's `unreadCount`/`totalCount` come from the server (`GET /mail/folders`, the server-published `Folder` update
+ * event, and the poll), but waiting for a round trip to see a badge move after reading a message feels broken, so a change
+ * made here is applied to the badge at once - **optimistically** - and then *reconciled*: every so often, and after every
+ * change, the real counts are read back and replace whatever this page worked out. So the page can be wrong for a moment,
+ * never for good.
+ *
+ * What the server sends (`@rapidmx/restapi`): `GET /mail/folders` returns each folder with a derived `unreadCount`/`totalCount`
+ * (unread messages, all messages), and after any change to a folder's messages it publishes
+ * `{ type: /^Folder/, action: "update", data: { uid, mailboxUid, unreadCount, totalCount } }` on the folder's push channel *and* its
+ * mailbox's, so each is heard twice - the values are absolute and applying one again changes nothing. Nothing here fails without
+ * that event, or for a write that publishes none (ActiveSync/MAPI, erasure jobs): the read-back after each change and the poll do
+ * the same job a little later, and overlapping writes to one folder are unordered, so they always have the last word.
+ */
+export interface FolderCount {
+    unread: number;
+    total: number;
+}
+/** A change to one folder's counts. */
+export interface CountDelta {
+    folderUid: string;
+    unread: number;
+    total: number;
+}
+/** What one message change - a new message (`previous` absent), a deletion (`next` absent), a read/unread flip, a move - does to the folders' counts. */
+export declare function countDeltas(previous: Message | null | undefined, next: Message | null | undefined): CountDelta[];
+/** A folder's count as it should be shown: what this page last worked out or was told, else what the folder was listed with. */
+export declare function countOfFolder(folder: Folder, counts: Record<string, FolderCount>): FolderCount;
+/** What a folder's badge shows: how many unread, or (Drafts and Outbox, Outlook-style) how many messages are in it. */
+export interface FolderBadge {
+    kind: "unread" | "total";
+    value: number;
+}
+/**
+ * The badge a folder gets, if any. Inbox, Archive and the user's own folders show their unread count when it is above
+ * zero; Drafts and Outbox show how many messages they hold (an unread count means nothing there); Sent Items, Deleted
+ * Items and Junk Email show nothing.
+ */
+export declare function badgeFor(type: FolderType, count: FolderCount): FolderBadge | undefined;
+/** The badge's text for assistive technology: "3 unread", "2 messages". */
+export declare function badgeLabel(badge: FolderBadge): string;
+/** The unread messages in every mailbox's Inbox - what the tab title counts. */
+export declare function inboxUnreadTotal(mailboxFolders: {
+    folders: Folder[];
+}[], counts: Record<string, FolderCount>): number;
+/** How long after the last change of this page's own has finished a server-published count is trusted again: one published
+ * about an earlier state of the folder could otherwise arrive late and put back what the change just took away. */
+export declare const COUNT_QUIET_MS = 1500;
+/** How long after a change the counts are read back from the server. */
+export declare const COUNT_REFRESH_DELAY_MS = 600;
+/** An optimistic change in flight: call exactly one of these once the server has answered. */
+export interface CountTracker {
+    /** The server accepted the change: keep what was applied, and read the real counts back. */
+    settle(): void;
+    /** The server refused it (or it failed): put the counts back as they were, and read the real ones back. */
+    revert(): void;
+}
+export interface FolderCounts {
+    /** The counts this page has worked out or been told since load, by folder uid - see `countOfFolder()`. */
+    counts: Record<string, FolderCount>;
+    /** Applies the effect of changing `previous` into `next` now, before the server has answered - see `CountTracker`. */
+    track(previous: Message | null | undefined, next: Message | null | undefined): CountTracker;
+    /** A new message arrived over the push connection: counts it (once per message) until the real counts are read back.
+     * `false` when this one was already counted - a duplicate event. */
+    noteCreated(message: Message): boolean;
+    /** The server's `Folder` update event's `data`: the folder's real counts - when this page has nothing of its own in flight. */
+    applyFolderEvent(data: unknown): void;
+    /** Reads every mailbox's real counts back and shows them, after `delayMs` (at once for 0). A later call replaces one still waiting. */
+    refresh(delayMs?: number): void;
+}
+/**
+ * Holds the folder counts overlay for `MailShell`. `folders` is every folder the sidebar lists (the overlay starts from what
+ * each was loaded with); `mailboxes` is whose folders to read back. The overlay starts again whenever `mailboxes` does.
+ */
+export declare function useFolderCounts(mailboxes: Mailbox[], folders: Folder[]): FolderCounts;

package/dist/apps/shared/mail/folderCounts.js

@@ -0,0 +1,212 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useEffect, useRef, useState } from "react";
+import { listFolders } from "@rapidmx/react-shared/mail/mailApi.js";
+/** What one message change - a new message (`previous` absent), a deletion (`next` absent), a read/unread flip, a move - does to the folders' counts. */
+export function countDeltas(previous, next) {
+    const byFolder = new Map();
+    function add(message, sign) {
+        const entry = byFolder.get(message.folderUid) ?? { folderUid: message.folderUid, unread: 0, total: 0 };
+        entry.total += sign;
+        entry.unread += message.flags.read === true ? 0 : sign;
+        byFolder.set(message.folderUid, entry);
+    }
+    if (previous) {
+        add(previous, -1);
+    }
+    if (next) {
+        add(next, 1);
+    }
+    return [...byFolder.values()].filter((delta) => delta.unread !== 0 || delta.total !== 0);
+}
+/** A folder's count as it should be shown: what this page last worked out or was told, else what the folder was listed with. */
+export function countOfFolder(folder, counts) {
+    return counts[folder.uid] ?? { unread: folder.unreadCount, total: folder.totalCount };
+}
+/**
+ * The badge a folder gets, if any. Inbox, Archive and the user's own folders show their unread count when it is above
+ * zero; Drafts and Outbox show how many messages they hold (an unread count means nothing there); Sent Items, Deleted
+ * Items and Junk Email show nothing.
+ */
+export function badgeFor(type, count) {
+    switch (type) {
+        case "sent_items":
+        case "deleted_items":
+        case "junk":
+            return undefined;
+        case "drafts":
+        case "outbox":
+            return count.total > 0 ? { kind: "total", value: count.total } : undefined;
+        default:
+            return count.unread > 0 ? { kind: "unread", value: count.unread } : undefined;
+    }
+}
+/** The badge's text for assistive technology: "3 unread", "2 messages". */
+export function badgeLabel(badge) {
+    return badge.kind === "unread" ? `${badge.value} unread` : `${badge.value} ${badge.value === 1 ? "message" : "messages"}`;
+}
+/** The unread messages in every mailbox's Inbox - what the tab title counts. */
+export function inboxUnreadTotal(mailboxFolders, counts) {
+    return mailboxFolders.reduce((total, entry) => total + entry.folders.filter((folder) => folder.type === "inbox").reduce((sum, folder) => sum + countOfFolder(folder, counts).unread, 0), 0);
+}
+/** How long after the last change of this page's own has finished a server-published count is trusted again: one published
+ * about an earlier state of the folder could otherwise arrive late and put back what the change just took away. */
+export const COUNT_QUIET_MS = 1500;
+/** How long after a change the counts are read back from the server. */
+export const COUNT_REFRESH_DELAY_MS = 600;
+/** How many message uids the "already counted this new message" memory holds. */
+const SEEN_LIMIT = 500;
+/**
+ * Holds the folder counts overlay for `MailShell`. `folders` is every folder the sidebar lists (the overlay starts from what
+ * each was loaded with); `mailboxes` is whose folders to read back. The overlay starts again whenever `mailboxes` does.
+ */
+export function useFolderCounts(mailboxes, folders) {
+    const [counts, setCounts] = useState({});
+    const latestRef = useRef({ mailboxes, folders });
+    latestRef.current = { mailboxes, folders };
+    // Bumped by every change of the overlay this page makes, so a read that started before one can tell it is out of date.
+    const changesRef = useRef(0);
+    const inFlightRef = useRef(0);
+    const lastDoneRef = useRef(0);
+    const runRef = useRef(0);
+    // Assigned during every render, before anything can call it.
+    const readBackRef = useRef(undefined);
+    const timerRef = useRef(undefined);
+    const stoppedRef = useRef(false);
+    const seenRef = useRef(new Set());
+    const adjust = useCallback((deltas) => {
+        const known = deltas.filter((delta) => latestRef.current.folders.some((folder) => folder.uid === delta.folderUid));
+        if (known.length === 0) {
+            return;
+        }
+        changesRef.current++;
+        setCounts((previous) => {
+            const next = { ...previous };
+            for (const delta of known) {
+                const folder = latestRef.current.folders.find((f) => f.uid === delta.folderUid);
+                const base = next[delta.folderUid] ?? { unread: folder.unreadCount, total: folder.totalCount };
+                next[delta.folderUid] = {
+                    unread: Math.max(0, base.unread + delta.unread),
+                    total: Math.max(0, base.total + delta.total),
+                };
+            }
+            return next;
+        });
+    }, []);
+    const refresh = useCallback((delayMs = COUNT_REFRESH_DELAY_MS) => {
+        if (stoppedRef.current) {
+            return;
+        }
+        clearTimeout(timerRef.current);
+        if (delayMs <= 0) {
+            timerRef.current = undefined;
+            void readBackRef.current();
+            return;
+        }
+        timerRef.current = setTimeout(() => void readBackRef.current(), delayMs);
+    }, []);
+    // Re-assigned on every render so it reads the latest mailboxes; `refresh` (stable) calls whichever is current.
+    readBackRef.current = async () => {
+        timerRef.current = undefined;
+        const run = ++runRef.current;
+        const startedAt = changesRef.current;
+        const results = await Promise.all(latestRef.current.mailboxes.map((mailbox) => listFolders(mailbox.uid).catch(() => undefined)));
+        if (stoppedRef.current || run !== runRef.current) {
+            return;
+        }
+        if (inFlightRef.current > 0 || changesRef.current !== startedAt) {
+            // A change of this page's own began or ended while that was being read, so it may predate it: read again.
+            refresh();
+            return;
+        }
+        const fresh = {};
+        for (const list of results) {
+            for (const folder of list ?? []) {
+                fresh[folder.uid] = { unread: folder.unreadCount, total: folder.totalCount };
+            }
+        }
+        setCounts((previous) => {
+            const changed = Object.entries(fresh).some(([uid, count]) => previous[uid]?.unread !== count.unread || previous[uid]?.total !== count.total);
+            return changed ? { ...previous, ...fresh } : previous;
+        });
+    };
+    const track = useCallback((previous, next) => {
+        const deltas = countDeltas(previous, next);
+        inFlightRef.current++;
+        adjust(deltas);
+        let finished = false;
+        /** Whether this call was the one that ended it (a tracker ends once). */
+        function finish() {
+            if (finished) {
+                return false;
+            }
+            finished = true;
+            inFlightRef.current--;
+            lastDoneRef.current = Date.now();
+            changesRef.current++;
+            return true;
+        }
+        return {
+            settle() {
+                if (finish()) {
+                    refresh();
+                }
+            },
+            revert() {
+                if (finish()) {
+                    adjust(deltas.map((delta) => ({ folderUid: delta.folderUid, unread: -delta.unread, total: -delta.total })));
+                    refresh();
+                }
+            },
+        };
+    }, [adjust, refresh]);
+    const noteCreated = useCallback((message) => {
+        const seen = seenRef.current;
+        if (seen.has(message.uid)) {
+            return false;
+        }
+        seen.add(message.uid);
+        if (seen.size > SEEN_LIMIT) {
+            seen.delete(seen.values().next().value);
+        }
+        adjust(countDeltas(null, message));
+        refresh();
+        return true;
+    }, [adjust, refresh]);
+    const applyFolderEvent = useCallback((data) => {
+        const event = data;
+        const uid = event?.uid;
+        const folder = typeof uid === "string" ? latestRef.current.folders.find((f) => f.uid === uid) : undefined;
+        if (!folder) {
+            return;
+        }
+        if (inFlightRef.current > 0 || Date.now() - lastDoneRef.current < COUNT_QUIET_MS) {
+            // Its number may be about a state older than this page's own change: let a fresh read settle it.
+            refresh();
+            return;
+        }
+        const valid = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
+        setCounts((previous) => {
+            const current = previous[folder.uid] ?? { unread: folder.unreadCount, total: folder.totalCount };
+            const unread = valid(event.unreadCount) ? event.unreadCount : current.unread;
+            const total = valid(event.totalCount) ? event.totalCount : current.total;
+            return unread === current.unread && total === current.total && previous[folder.uid] ? previous : { ...previous, [folder.uid]: { unread, total } };
+        });
+    }, [refresh]);
+    // A fresh load of the mailboxes is a fresh start: the folders come with counts of their own. (Keyed on the uids, not the array.)
+    const mailboxKey = mailboxes.map((mailbox) => mailbox.uid).join("|");
+    useEffect(() => {
+        changesRef.current++;
+        setCounts((previous) => (Object.keys(previous).length > 0 ? {} : previous));
+    }, [mailboxKey]);
+    useEffect(() => {
+        stoppedRef.current = false;
+        return () => {
+            stoppedRef.current = true;
+            clearTimeout(timerRef.current);
+        };
+    }, []);
+    return { counts, track, noteCreated, applyFolderEvent, refresh };
+}

package/dist/apps/shared/mail/listSnapshots.d.ts

@@ -0,0 +1,46 @@
+import type { ConversationSummary } from "@rapidmx/react-shared/mail/conversationsApi.js";
+import type { Message } from "@rapidmx/react-shared/mail/mailApi.js";
+/**
+ * A short-lived, in-memory copy of a folder's listing, so that switching to a folder that was shown a moment ago (or coming back
+ * to Mail from another app) shows its rows on the very frame of the click and revalidates behind them (stale-while-revalidate),
+ * instead of replacing the list with a loading state and waiting for the network. It is the client-side router's answer to
+ * "folder navigation takes seconds": the list of the folder being switched to is usually already known.
+ *
+ * Only a plain folder's listing is kept - a search's, an aggregate ("All Mailboxes") view's and a load-more page's rows are not -
+ * and what is kept is exactly what was on screen, including the rows "load more" added, the selection and the scroll position,
+ * so returning to a folder puts the reader where they left it. A snapshot only makes the first paint fast; the listing is always
+ * fetched again and folded in (`mergeFirstPage()`), so nothing shown from here is ever taken as current.
+ */
+export interface ListSnapshot {
+    messages: Message[];
+    conversations: ConversationSummary[];
+    hasMore: boolean;
+    /** The message that was selected (the reading pane's), if it is still in `messages` when the snapshot is shown. */
+    selectedUid: string | null;
+    /** The list's `scrollTop`, saved when the listing was left. */
+    scrollTop: number;
+    /** When it was last written. */
+    at: number;
+}
+/** How long a snapshot may be shown after it was last written. Longer than that the folder is shown as loading, as before. */
+export declare const LIST_SNAPSHOT_TTL_MS: number;
+/** How many folders are remembered; the least recently written is dropped first. */
+export declare const LIST_SNAPSHOT_MAX = 16;
+/** Everything that makes one listing different from another: which folder, as messages or conversations, and how it is
+ * filtered and sorted. */
+export declare function listSnapshotKey(parts: {
+    mailboxUid: string | undefined;
+    folderUid: string | undefined;
+    conversations: boolean;
+    filter: string;
+    labels: string;
+    sort: string;
+}): string;
+/** The snapshot for `key`, or `undefined` when there is none or it is older than `LIST_SNAPSHOT_TTL_MS`. */
+export declare function readListSnapshot(key: string, now?: number): ListSnapshot | undefined;
+/** Remembers a listing as it is on screen (keeping the scroll position saved for it, if any). */
+export declare function writeListSnapshot(key: string, listing: Omit<ListSnapshot, "scrollTop" | "at">, now?: number): void;
+/** Records how far `key`'s list was scrolled when it was left. A no-op for a listing that was never remembered. */
+export declare function saveListScroll(key: string, scrollTop: number): void;
+/** Forgets every snapshot (sign-out, and tests). */
+export declare function clearListSnapshots(): void;

package/dist/apps/shared/mail/listSnapshots.js

@@ -0,0 +1,43 @@
+/** How long a snapshot may be shown after it was last written. Longer than that the folder is shown as loading, as before. */
+export const LIST_SNAPSHOT_TTL_MS = 5 * 60000;
+/** How many folders are remembered; the least recently written is dropped first. */
+export const LIST_SNAPSHOT_MAX = 16;
+const snapshots = new Map();
+/** Everything that makes one listing different from another: which folder, as messages or conversations, and how it is
+ * filtered and sorted. */
+export function listSnapshotKey(parts) {
+    return [parts.mailboxUid, parts.folderUid, parts.conversations ? "conversations" : "messages", parts.filter, parts.labels, parts.sort].join("|");
+}
+/** The snapshot for `key`, or `undefined` when there is none or it is older than `LIST_SNAPSHOT_TTL_MS`. */
+export function readListSnapshot(key, now = Date.now()) {
+    const snapshot = snapshots.get(key);
+    if (!snapshot) {
+        return undefined;
+    }
+    if (now - snapshot.at > LIST_SNAPSHOT_TTL_MS) {
+        snapshots.delete(key);
+        return undefined;
+    }
+    return snapshot;
+}
+/** Remembers a listing as it is on screen (keeping the scroll position saved for it, if any). */
+export function writeListSnapshot(key, listing, now = Date.now()) {
+    const previous = snapshots.get(key);
+    // Re-inserted so that the Map's order is least-recently-written first.
+    snapshots.delete(key);
+    snapshots.set(key, { ...listing, scrollTop: previous?.scrollTop ?? 0, at: now });
+    while (snapshots.size > LIST_SNAPSHOT_MAX) {
+        snapshots.delete(snapshots.keys().next().value);
+    }
+}
+/** Records how far `key`'s list was scrolled when it was left. A no-op for a listing that was never remembered. */
+export function saveListScroll(key, scrollTop) {
+    const snapshot = snapshots.get(key);
+    if (snapshot) {
+        snapshot.scrollTop = scrollTop;
+    }
+}
+/** Forgets every snapshot (sign-out, and tests). */
+export function clearListSnapshots() {
+    snapshots.clear();
+}

package/dist/apps/shared/mail/mergeFirstPage.d.ts

@@ -0,0 +1,23 @@
+/** What `mergeFirstPage()` made of a fresh first page and the rows already on screen. */
+export interface MergedPage<T> {
+    /** The rows to show. */
+    rows: T[];
+    /** How many of the fresh page's rows were not on screen yet - the mail that arrived since. */
+    added: number;
+    /** `true` when `rows` is exactly the fresh page, because the whole listing fits on it. */
+    complete: boolean;
+}
+/**
+ * Folds a freshly fetched first page of a list into the rows already loaded (the first page plus whatever "load more"
+ * added), for the quiet refresh that follows a push event or a poll - so new mail appears without the list being reset,
+ * re-scrolled or re-selected the way a full reload would.
+ *
+ * - A page shorter than `pageSize` is the whole listing, so it simply replaces what is shown - which also drops what was
+ * deleted or moved elsewhere.
+ * - A full page is only the top of a longer listing. Its rows go first, in the server's order, followed by the loaded rows
+ * it did not repeat (older ones the reader has scrolled to). What was removed elsewhere from a long, partly loaded list
+ * stays until the next real load; nothing here can tell it from a row that merely slid off the first page.
+ * - A row in both keeps whichever copy `pick` prefers - by default the fresh one - so, for messages, a row the reader has
+ * just changed (a higher `version`) is not put back by a fetch that started before the change landed.
+ */
+export declare function mergeFirstPage<T>(current: T[], fresh: T[], idOf: (row: T) => string, pageSize: number, pick?: (current: T, fresh: T) => T): MergedPage<T>;

package/dist/apps/shared/mail/mergeFirstPage.js

@@ -0,0 +1,30 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Folds a freshly fetched first page of a list into the rows already loaded (the first page plus whatever "load more"
+ * added), for the quiet refresh that follows a push event or a poll - so new mail appears without the list being reset,
+ * re-scrolled or re-selected the way a full reload would.
+ *
+ * - A page shorter than `pageSize` is the whole listing, so it simply replaces what is shown - which also drops what was
+ * deleted or moved elsewhere.
+ * - A full page is only the top of a longer listing. Its rows go first, in the server's order, followed by the loaded rows
+ * it did not repeat (older ones the reader has scrolled to). What was removed elsewhere from a long, partly loaded list
+ * stays until the next real load; nothing here can tell it from a row that merely slid off the first page.
+ * - A row in both keeps whichever copy `pick` prefers - by default the fresh one - so, for messages, a row the reader has
+ * just changed (a higher `version`) is not put back by a fetch that started before the change landed.
+ */
+export function mergeFirstPage(current, fresh, idOf, pageSize, pick = (_current, next) => next) {
+    const currentById = new Map(current.map((row) => [idOf(row), row]));
+    const added = fresh.filter((row) => !currentById.has(idOf(row))).length;
+    const rows = fresh.map((row) => {
+        const existing = currentById.get(idOf(row));
+        return existing ? pick(existing, row) : row;
+    });
+    if (fresh.length < pageSize) {
+        return { rows, added, complete: true };
+    }
+    const freshIds = new Set(fresh.map(idOf));
+    return { rows: [...rows, ...current.filter((row) => !freshIds.has(idOf(row)))], added, complete: false };
+}

package/dist/apps/shared/mail/messageReadState.d.ts

@@ -0,0 +1,32 @@
+import { Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { CountTracker } from "./folderCounts.js";
+/**
+ * The one way a message's read state changes in the webmail, so that every place that shows it moves together: the row in
+ * the list (and the conversation row's unread count), the folder badge, and the unread styling.
+ *
+ * It is **optimistic**: the row and the badge change the moment the user acts, the server is asked, and if it refuses the
+ * change is taken back. What each place is handed to do that is a `ReadStateSink`.
+ */
+export interface ReadStateSink {
+    /**
+     * Shows a message wherever the caller lists it - the message list, the conversation list's child rows, the open thread.
+     * `previous` is given with the optimistic copy (and with the revert of it) and is the copy being replaced, so a
+     * conversation row can tell that its unread count went up or down; it is absent for the server's own copy, which
+     * differs only in its `version`.
+     */
+    patch(updated: Message, previous?: Message): void;
+    /** Applies the change to the folder badges: `MailShell`'s `trackMessageChange`. */
+    track(previous: Message, next: Message): CountTracker;
+}
+/**
+ * Marks one message read (`read: true`) or unread. Resolves the server's updated copy, or `undefined` when nothing needed
+ * doing (it already was that way) or the server refused - in which case everything has already been put back as it was.
+ * Never rejects: like the old mark-as-read, a failure must not get in the way of reading the message.
+ */
+export declare function setReadState(message: Message, read: boolean, sink: ReadStateSink): Promise<Message | undefined>;
+/**
+ * The same for a whole selection, in one request. Resolves the updated messages, in request order. Unlike `setReadState()`
+ * it rejects when the server refuses (after putting everything back), because a bulk update is not atomic - some of it may
+ * have landed - and the caller's own handling reloads the list and says so (see `bulkUpdateMessages()`).
+ */
+export declare function setReadStateMany(messages: Message[], read: boolean, sink: ReadStateSink): Promise<Message[]>;

package/dist/apps/shared/mail/messageReadState.js

@@ -0,0 +1,63 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { setMessageRead, setMessagesRead } from "@rapidmx/react-shared/mail/mailApi.js";
+function withRead(message, read) {
+    return { ...message, flags: { ...message.flags, read } };
+}
+/** Whether `message` is not yet in the state `read` asks for. A message with no `read` flag counts as unread. */
+function needsChange(message, read) {
+    return (message.flags.read === true) !== read;
+}
+/**
+ * Marks one message read (`read: true`) or unread. Resolves the server's updated copy, or `undefined` when nothing needed
+ * doing (it already was that way) or the server refused - in which case everything has already been put back as it was.
+ * Never rejects: like the old mark-as-read, a failure must not get in the way of reading the message.
+ */
+export async function setReadState(message, read, sink) {
+    if (!needsChange(message, read)) {
+        return undefined;
+    }
+    const optimistic = withRead(message, read);
+    sink.patch(optimistic, message);
+    const tracker = sink.track(message, optimistic);
+    try {
+        const updated = await setMessageRead(message, read);
+        sink.patch(updated);
+        tracker.settle();
+        return updated;
+    }
+    catch {
+        sink.patch(message, optimistic);
+        tracker.revert();
+        return undefined;
+    }
+}
+/**
+ * The same for a whole selection, in one request. Resolves the updated messages, in request order. Unlike `setReadState()`
+ * it rejects when the server refuses (after putting everything back), because a bulk update is not atomic - some of it may
+ * have landed - and the caller's own handling reloads the list and says so (see `bulkUpdateMessages()`).
+ */
+export async function setReadStateMany(messages, read, sink) {
+    const changes = messages.filter((message) => needsChange(message, read)).map((message) => ({ message, optimistic: withRead(message, read) }));
+    const trackers = changes.map(({ message, optimistic }) => {
+        sink.patch(optimistic, message);
+        return sink.track(message, optimistic);
+    });
+    try {
+        const updated = await setMessagesRead(messages, read);
+        for (const message of updated) {
+            sink.patch(message);
+        }
+        trackers.forEach((tracker) => tracker.settle());
+        return updated;
+    }
+    catch (err) {
+        changes.forEach(({ message, optimistic }, index) => {
+            sink.patch(message, optimistic);
+            trackers[index].revert();
+        });
+        throw err;
+    }
+}

package/dist/apps/shared/mail/newMailNotifications.d.ts

@@ -0,0 +1,62 @@
+import type { Folder, Mailbox, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+/**
+ * What decides whether a new message is announced, what the announcement says, and the two settings behind it (both per
+ * browser, in `localStorage`): whether new-mail pop-ups are on at all, and what the user told the "turn on desktop
+ * notifications" offer.
+ *
+ * The announcement is built only from what the push event carries - the whole `Message`, including `bodyPreview` - and only
+ * ever as text: React escapes it on screen and the Notifications API takes plain strings, so nothing here is HTML.
+ */
+/** `localStorage` key of the pop-ups switch. Absent means on; `"off"` means the user turned them off. */
+export declare const NEW_MAIL_POPUPS_KEY = "rapidmx-new-mail-popups";
+/** `localStorage` key of the answer to the desktop-notifications offer: `"later"` (not now) or `"asked"` (they were asked). */
+export declare const DESKTOP_OFFER_KEY = "rapidmx-desktop-notifications-offer";
+/** How much of the body an announcement quotes. */
+export declare const PREVIEW_MAX_LENGTH = 140;
+/** A message received longer ago than this is not "new": mail imported or migrated in bulk arrives as `create` events too. */
+export declare const MAX_NEW_AGE_MS: number;
+/** Whether new-mail pop-ups are on (the default). */
+export declare function getNewMailPopupsEnabled(): boolean;
+export declare function setNewMailPopupsEnabled(enabled: boolean): void;
+/** Whether the "turn on desktop notifications" offer has been put away with "Not now" (or answered). */
+export declare function getDesktopOfferDismissed(): boolean;
+export declare function setDesktopOfferDismissed(dismissed: boolean): void;
+/** The browser's notification permission, or `"unsupported"` where there is no Notifications API. */
+export type DesktopPermission = NotificationPermission | "unsupported";
+export declare function desktopPermission(): DesktopPermission;
+/** Asks the browser for permission - call it from a click. Resolves the answer; never rejects. */
+export declare function requestDesktopPermission(): Promise<DesktopPermission>;
+/** What an announcement shows. */
+export interface NewMailNotice {
+    /** The message's uid: the announcement's identity (and the desktop notification's `tag`). */
+    uid: string;
+    mailboxUid: string;
+    folderUid: string;
+    /** The sender's display name, `""` when there is none. */
+    senderName: string;
+    /** The sender's address - always shown, so a name can't stand in for who really sent it. */
+    senderAddress: string;
+    subject: string;
+    /** About `PREVIEW_MAX_LENGTH` characters of the body as plain text; `Encrypted message` for an encrypted one. */
+    preview: string;
+    /** Where opening it goes. */
+    href: string;
+}
+/** `text` with those characters replaced by spaces, whitespace folded, and cut to `max` characters (with an ellipsis). */
+export declare function cleanPreview(text: string, max?: number): string;
+/** The text of an announcement of `message`. */
+export declare function noticeFor(message: Message): NewMailNotice;
+/** Every address that is this user's own, lowercased - a message from one of them is not new mail worth announcing. */
+export declare function ownAddressesOf(mailboxes: Mailbox[]): Set<string>;
+/**
+ * Whether the arrival of `message` is worth announcing: unread mail in an Inbox (not Drafts, Sent Items, Outbox, Deleted Items,
+ * Junk Email or quarantine, which are other folders), that Focused Inbox did not put under Other, that its own user did not
+ * send, and that is not old (a bulk import).
+ */
+export declare function shouldAnnounce(message: Message, context: {
+    folders: Folder[];
+    ownAddresses: Set<string>;
+    now?: number;
+}): boolean;
+/** `Name <address>`, or the address alone - the desktop notification's title. */
+export declare function noticeSender(notice: Pick<NewMailNotice, "senderName" | "senderAddress">): string;