@rapidmx/web-client 0.15.1 → 0.17.0

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

@@ -0,0 +1,11 @@
+import type { Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
+/** Forgets every remembered answer - for the tests, and anything that changes the caller's access mid-session. */
+export declare function clearMailboxUpdateAccessCache(): void;
+/**
+ * Whether the reader may change the messages of `mailbox`: `false` only for a mailbox shared with them (`accessRole: "delegate"`) that
+ * the server says they may not update - a view-only share. Everything else is `true` from the first render: the reader's own mailbox
+ * needs no request, and a mailbox that is unknown (the shell has not listed it), or whose access could not be read, is treated as
+ * writable - the server still refuses what is not allowed, and hiding a usable action over a failed lookup is worse than offering one
+ * that then says why it failed.
+ */
+export declare function useMailboxUpdateAccess(mailbox: Mailbox | undefined): boolean;

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

@@ -0,0 +1,52 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { getMyMailboxAccess } from "@rapidmx/react-shared/mail/mailboxAccessApi.js";
+/** What the server said about the caller's update access to a mailbox, remembered per mailbox for the page load. */
+const answers = new Map();
+/** Forgets every remembered answer - for the tests, and anything that changes the caller's access mid-session. */
+export function clearMailboxUpdateAccessCache() {
+    answers.clear();
+}
+/** Whether the caller may change things in `mailboxUid` (move, mark and flag its messages, add its filters): the server's own ACL check. Never rejects; `undefined` when it could not be asked (which is not cached). */
+function fetchUpdateAccess(mailboxUid) {
+    let answer = answers.get(mailboxUid);
+    if (!answer) {
+        answer = getMyMailboxAccess(mailboxUid).then((access) => access.canUpdate, () => {
+            answers.delete(mailboxUid);
+            return undefined;
+        });
+        answers.set(mailboxUid, answer);
+    }
+    return answer;
+}
+/**
+ * Whether the reader may change the messages of `mailbox`: `false` only for a mailbox shared with them (`accessRole: "delegate"`) that
+ * the server says they may not update - a view-only share. Everything else is `true` from the first render: the reader's own mailbox
+ * needs no request, and a mailbox that is unknown (the shell has not listed it), or whose access could not be read, is treated as
+ * writable - the server still refuses what is not allowed, and hiding a usable action over a failed lookup is worse than offering one
+ * that then says why it failed.
+ */
+export function useMailboxUpdateAccess(mailbox) {
+    const uid = mailbox?.uid;
+    const delegated = mailbox?.accessRole === "delegate";
+    const [writable, setWritable] = useState(true);
+    useEffect(() => {
+        setWritable(true);
+        if (!uid || !delegated) {
+            return;
+        }
+        let cancelled = false;
+        void fetchUpdateAccess(uid).then((canUpdate) => {
+            if (!cancelled && canUpdate === false) {
+                setWritable(false);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [uid, delegated]);
+    return writable;
+}

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

@@ -0,0 +1,35 @@
+import { ReactElement } from "react";
+import type { Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import { EmptyFolderOutcome, PurgeOutcome } from "./permanentDelete.js";
+/** The folder "Empty folder" is about. */
+export interface EmptiableFolder {
+    uid: string;
+    name: string;
+}
+export interface PermanentDelete {
+    /**
+     * Asks, then permanently deletes `messages` (Delete in Deleted Items - the Delete menu item of a message card calls this too). Resolves
+     * with what came of it once the dialog is gone, and everything a delete has to tell has been told: the folder badges follow, the local
+     * search index drops the messages, and a notification says "N messages permanently deleted" or which could not be and why. Resolves
+     * `null` - and sends nothing - when the reader cancels, when `messages` is empty, or while another request is already open.
+     */
+    requestPermanentDelete: (messages: Message[]) => Promise<PurgeOutcome | null>;
+    /**
+     * Asks, then permanently deletes everything in `folder`. `count` is how many messages it holds when that is known (the dialog and the
+     * notification then say so). Resolves as `requestPermanentDelete()` does; a request that failed outright (the server is down) has said so and resolves an
+     * outcome with nothing deleted, so the caller reloads what it lists.
+     */
+    requestEmptyFolder: (folder: EmptiableFolder, count?: number) => Promise<EmptyFolderOutcome | null>;
+    /** A request is open (the dialog is up, or the delete is on the wire): what should hold every other action of the list meanwhile. */
+    busy: boolean;
+    /** The confirmation dialog - render it once, anywhere (it is a portal). */
+    dialog: ReactElement;
+}
+/**
+ * The one place a permanent delete is confirmed and carried out - for the mail list (the selection bar, the Delete key, Empty folder) and
+ * for a message card's own Delete, so all of them ask the same question, delete the same way and report the same way. Call it inside the
+ * mail shell (it keeps that shell's folder badges right).
+ *
+ * The reader always confirms: nothing is remembered between requests.
+ */
+export declare function usePermanentDelete(): PermanentDelete;

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

@@ -0,0 +1,96 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useRef, useState } from "react";
+import PermanentDeleteDialog from "../components/mail/PermanentDeleteDialog.js";
+import { useMailShell } from "../components/mail/layout/MailShell.js";
+import { notifyApiError } from "../notifications/apiErrors.js";
+import { removeLocalEntity } from "../search/localIndexRpcClient.js";
+import { messageCount, notifyFolderEmptied, notifyPurged, purgeFolder, purgeMessages, } from "./permanentDelete.js";
+/**
+ * The one place a permanent delete is confirmed and carried out - for the mail list (the selection bar, the Delete key, Empty folder) and
+ * for a message card's own Delete, so all of them ask the same question, delete the same way and report the same way. Call it inside the
+ * mail shell (it keeps that shell's folder badges right).
+ *
+ * The reader always confirms: nothing is remembered between requests.
+ */
+export function usePermanentDelete() {
+    const { trackMessageChange, refreshFolderCounts } = useMailShell();
+    const [pending, setPending] = useState(null);
+    const [running, setRunning] = useState(false);
+    // Set at once (state is a render later), so a key pressed twice does not open two dialogs.
+    const pendingRef = useRef(null);
+    function ask(request) {
+        if (pendingRef.current) {
+            return Promise.resolve(null);
+        }
+        return new Promise((resolve) => {
+            const next = { request, resolve };
+            pendingRef.current = next;
+            setPending(next);
+        });
+    }
+    function requestPermanentDelete(messages) {
+        return messages.length === 0 ? Promise.resolve(null) : ask({ kind: "messages", messages });
+    }
+    function requestEmptyFolder(folder, count) {
+        return ask({ kind: "folder", folder, count });
+    }
+    /** Closes the dialog and hands the caller what came of it. */
+    function finish(outcome) {
+        const current = pendingRef.current;
+        pendingRef.current = null;
+        setPending(null);
+        setRunning(false);
+        current.resolve(outcome);
+    }
+    /** What every delete tells the rest of the page: the badges (each message is one fewer in its folder) and the local search index. */
+    function afterDeleted(deleted) {
+        for (const message of deleted) {
+            trackMessageChange(message, null).settle();
+            void removeLocalEntity(message.mailboxUid, message.uid);
+        }
+    }
+    async function confirm() {
+        const { request } = pendingRef.current;
+        setRunning(true);
+        if (request.kind === "messages") {
+            const outcome = await purgeMessages(request.messages);
+            afterDeleted(outcome.deleted);
+            notifyPurged(outcome);
+            finish(outcome);
+            return;
+        }
+        let outcome;
+        try {
+            outcome = await purgeFolder(request.folder.uid);
+        }
+        catch (err) {
+            notifyApiError(err, `Couldn't empty ${request.folder.name}`);
+            // Part of it may have gone before the failure: the caller reloads rather than assume nothing did.
+            outcome = { emptied: false, deleted: [], failed: [] };
+        }
+        afterDeleted(outcome.deleted);
+        // The whole-folder request does not say which messages went, so the counts are read back rather than adjusted.
+        refreshFolderCounts();
+        if (outcome.emptied || outcome.deleted.length > 0 || outcome.failed.length > 0) {
+            notifyFolderEmptied(request.folder.name, outcome, request.count);
+        }
+        finish(outcome);
+    }
+    function cancel() {
+        finish(null);
+    }
+    const request = pending?.request;
+    const folderRequest = request?.kind === "folder" ? request : undefined;
+    const dialog = (_jsx(PermanentDeleteDialog, { open: pending !== null, title: folderRequest ? `Empty ${folderRequest.folder.name}` : "Delete permanently", message: folderRequest
+            ? `Permanently delete ${folderRequest.count === undefined
+                ? "all items"
+                : folderRequest.count === 1
+                    ? "the only item"
+                    : `all ${folderRequest.count} items`} in ${folderRequest.folder.name}? This can't be undone.`
+            : `Permanently delete ${messageCount(request?.kind === "messages" ? request.messages.length : 0)}? This can't be undone.`, confirmLabel: folderRequest ? "Delete all permanently" : "Delete permanently", busy: running, onConfirm: () => void confirm(), onCancel: cancel }));
+    return { requestPermanentDelete, requestEmptyFolder, busy: pending !== null, dialog };
+}

package/dist/apps/shared/navigation/frameContext.d.ts

@@ -1,6 +1,6 @@
 import React, { PropsWithChildren } from "react";
 /**
- * What the persistent app frame (`AppRouter`'s one mounted `AppShell` chrome) offers to what is rendered inside it. `null`
+ * What the persistent app frame (the webmail's router shell, `apps/www/_shell.tsx`, whose one mounted `AppChrome` never unmounts) offers to what is rendered inside it. `null`
  * outside a frame - a page not shown by the router (an admin page, a plugin page, a test) renders its own chrome.
  */
 export interface AppFrameContextValue {

package/dist/apps/shared/navigation/index.d.ts

@@ -0,0 +1,16 @@
+export interface NavigateOptions {
+    /** Replaces the current history entry instead of adding one (a redirect, or a state change that isn't a "place"). */
+    replace?: boolean;
+}
+/** Goes to `href`: without a page load when it is a page of the app, else as an ordinary navigation. */
+export type NavigateFn = (href: string, options?: NavigateOptions) => void;
+/**
+ * The function to go somewhere with, for what code decides (after a save, a select, a folder change). `navigate("/calendar")`
+ * changes the page and the URL without a page load when the router knows the page (Mail, Calendar, Contacts, Tasks, Settings
+ * and their subpages), and loads it normally otherwise (another app, a plugin's page); outside a router it is always a
+ * normal navigation. A destination with the path the page is at - only its query string is different (`/?mailboxUid=a&folderUid=b`,
+ * `/tasks?mailboxUid=b`) - is a shallow navigation: the page instance keeps its state, and what reads the location follows. Prefer
+ * a plain `<a href>` for anything the user clicks - the router takes it over, and it stays a real link. The returned function is
+ * stable across renders.
+ */
+export declare function useNavigate(): NavigateFn;

package/dist/apps/shared/navigation/index.js

@@ -0,0 +1,34 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * What the web client's code uses to go somewhere. The client-side router is `@rapidrest/react`'s (`router = true` on the
+ * route, the app's `_shell.tsx` as the persistent frame - see `apps/www/_shell.tsx`); this is the one thing on top of it: a
+ * `navigate()` that keeps the page when only the query string changes.
+ */
+import { useCallback, useRef } from "react";
+import { useRouter } from "@rapidrest/react/client";
+/**
+ * The function to go somewhere with, for what code decides (after a save, a select, a folder change). `navigate("/calendar")`
+ * changes the page and the URL without a page load when the router knows the page (Mail, Calendar, Contacts, Tasks, Settings
+ * and their subpages), and loads it normally otherwise (another app, a plugin's page); outside a router it is always a
+ * normal navigation. A destination with the path the page is at - only its query string is different (`/?mailboxUid=a&folderUid=b`,
+ * `/tasks?mailboxUid=b`) - is a shallow navigation: the page instance keeps its state, and what reads the location follows. Prefer
+ * a plain `<a href>` for anything the user clicks - the router takes it over, and it stays a real link. The returned function is
+ * stable across renders.
+ */
+export function useNavigate() {
+    const { navigate, pathname } = useRouter();
+    // The latest, through a ref: the router value is replaced whenever the location or a navigation's pending state changes, and
+    // callers keep this function in effect dependencies (the mail connection's `open`).
+    const latest = useRef({ navigate, pathname });
+    latest.current = { navigate, pathname };
+    return useCallback((href, options = {}) => {
+        const { navigate: go, pathname: here } = latest.current;
+        // A relative or absolute-path destination is resolved against the page's own address, and only ever compared by path.
+        const destination = new URL(href, `http://router.invalid${here}`);
+        const shallow = destination.origin === "http://router.invalid" && destination.pathname === here;
+        void go(href, { replace: options.replace, shallow });
+    }, []);
+}

package/dist/apps/shared/navigation/pageTitle.d.ts

@@ -0,0 +1,11 @@
+import type { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
+/** The name the deployment goes by in the browser tab: its branding title, else its company name, else RapidMX. */
+export declare function brandName(branding?: Pick<Branding, "title" | "companyName"> | null): string;
+/**
+ * The `title` export of a webmail page: `export const title = pageTitle("Calendar")`. `@rapidrest/react` renders it into the
+ * document's `<title>` on the server - so the tab is right from the first byte, and a crawler sees it - and sends it with every
+ * client navigation, so the tab follows the page. `label` is the app's name (`Acme: Calendar`), the same for all of an app's pages.
+ */
+export declare function pageTitle(label: string): (props: {
+    branding?: Pick<Branding, "title" | "companyName"> | null;
+}) => string;

package/dist/apps/shared/navigation/pageTitle.js

@@ -0,0 +1,12 @@
+/** The name the deployment goes by in the browser tab: its branding title, else its company name, else RapidMX. */
+export function brandName(branding) {
+    return branding?.title || branding?.companyName || "RapidMX";
+}
+/**
+ * The `title` export of a webmail page: `export const title = pageTitle("Calendar")`. `@rapidrest/react` renders it into the
+ * document's `<title>` on the server - so the tab is right from the first byte, and a crawler sees it - and sends it with every
+ * client navigation, so the tab follows the page. `label` is the app's name (`Acme: Calendar`), the same for all of an app's pages.
+ */
+export function pageTitle(label) {
+    return ({ branding }) => `${brandName(branding)}: ${label}`;
+}

package/dist/apps/shared/search/crossMailboxSearch.d.ts

@@ -0,0 +1,72 @@
+import type { SearchResult } from "@rapidmx/react-shared/search/searchApi.js";
+/**
+ * How far a cross-mailbox search fans out. Exported (and mutable) so a test can shrink them instead of building 26 mailboxes or waiting a
+ * minute for a timeout; nothing else writes to it.
+ */
+export declare const SEARCH_LIMITS: {
+    /** How many mailboxes are worked on at once. */
+    concurrency: number;
+    /** The most mailboxes one search covers - the caller's own first, then the shared ones (`orderMailboxes()`); a note says how many were left out. */
+    maxMailboxes: number;
+    /** How long one mailbox's Tier 1 (server) request may take before that mailbox is given up on, so one wedged mailbox cannot hold the search. */
+    tier1TimeoutMs: number;
+    /** The same for a mailbox's Tier 3 pass (fetching and decrypting up to a couple of hundred candidates, so much longer). */
+    tier3TimeoutMs: number;
+    /** The most result rows a search keeps on screen (the page's own cap for a list, `MAX_LOADED_ROWS`, applies to a search too). */
+    maxRows: number;
+};
+/**
+ * How many results each mailbox contributes to one page. One mailbox gives the whole page; with several the page is shared out between them
+ * (never below `MIN_MAILBOX_PAGE_SIZE`), so the merged first page stays about one page long instead of growing by the number of mailboxes.
+ */
+export declare function searchPageSize(mailboxCount: number, pageSize: number): number;
+/** A search hit that remembers which mailbox it was found in. */
+export interface MailboxHit extends SearchResult {
+    mailboxUid: string;
+}
+export declare function tagHits(mailboxUid: string, hits: SearchResult[]): MailboxHit[];
+/** One hit's identity across mailboxes: the same entity uid found in two mailboxes is two hits. */
+export declare function hitKey(hit: {
+    mailboxUid: string;
+    entityUid: string;
+}): string;
+/**
+ * Merges Tier 1 (server, possibly `metadataOnly` for an encrypted message), Tier 2 (local index, fully decrypted and re-scored) and Tier 3
+ * (server-narrowed candidates, decrypted and re-scored) results into one ranked list, per `specs/search.md` §7's "client MUST re-score all
+ * results it can see... normalise into the same space rather than interleaving raw scores": each tier is normalized independently via
+ * `normalizeServerScores()` before merging, since a Postgres/OpenSearch score, a local `bm25()` score, and Tier 3's own term-count score all
+ * occupy unrelated ranges. A hit present in more than one list keeps only the last-inserted entry (Tier 2 wins over Tier 3 wins over Tier 1) -
+ * Tier 2 and Tier 3 both represent genuine, content-verified scores for the same message, so which one "wins" on overlap doesn't change
+ * correctness, only which of two equally-valid scores is shown; either supersedes Tier 1's metadata-only guess for the same message.
+ *
+ * Each tier's list is pooled across every mailbox searched before it is normalized, so one mailbox's best hit is not automatically "1.0"
+ * next to another's: the ranking is the same rule as for one mailbox, applied to the merged lists. A hit's identity is its mailbox and its
+ * entity uid (`hitKey()`), so the same uid can only collapse within a mailbox. Ties keep the order the lists were given in (a stable sort), which
+ * the caller makes the mailboxes' display order.
+ *
+ * Called progressively - each time with whatever tiers have reported so far (an empty array for the rest). Pure and stateless.
+ */
+export declare function mergeSearchResults(tier1: MailboxHit[], tier2: MailboxHit[], tier3: MailboxHit[]): MailboxHit[];
+/** Raised by `withTimeout()`. */
+export declare class SearchTimeoutError extends Error {
+    constructor();
+}
+/** `promise`, or a rejection with `SearchTimeoutError` if it has not settled after `ms` (never, for a non-finite `ms`). The work is not aborted - a late answer is just dropped. */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T>;
+/**
+ * Runs `task` for every item, at most `concurrency` at a time, starting them in order. Stops starting new ones once `isCancelled()` (the search
+ * was superseded) or once one has rejected - which is then this function's own rejection, after the ones already running have settled.
+ */
+export declare function runLimited<T>(items: readonly T[], concurrency: number, task: (item: T) => Promise<void>, isCancelled: () => boolean): Promise<void>;
+/** Why one mailbox's search failed, as a short phrase for the notice: the class of failure, never the server's own text. */
+export declare function classifyFailure(err: unknown): string;
+/** A mailbox that could not be (fully) searched. `encrypted` is set when only its Tier 3 pass (the encrypted mail) failed - its other results are in. */
+export interface MailboxFailure {
+    mailboxUid: string;
+    /** The mailbox's display name, as it was when the search ran. */
+    mailboxName: string;
+    encrypted: boolean;
+    reason: string;
+}
+/** The body of the "Some results may be missing" notice: which mailboxes, and why each. */
+export declare function describeFailures(failures: readonly MailboxFailure[]): string;

package/dist/apps/shared/search/crossMailboxSearch.js

@@ -0,0 +1,136 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The pieces of searching several mailboxes at once (Mail's "All mailboxes" views, and a search widened from one mailbox's folder to every
+ * mailbox the reader can read). Nothing here talks to the server: `apps/www/index.tsx` fans its own per-mailbox pipeline (Tier 1 server search,
+ * Tier 2 local index, Tier 3 server-narrowed encrypted candidates) out across mailboxes and uses these to bound that fan-out, to merge what
+ * comes back into one ranked list and to say, in words, which mailbox could not be searched and why.
+ *
+ * A search of one mailbox is the same code with a list of one: nothing here changes what that returns.
+ */
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { normalizeServerScores } from "@rapidmx/react-shared/search/searchScoring.js";
+/**
+ * How far a cross-mailbox search fans out. Exported (and mutable) so a test can shrink them instead of building 26 mailboxes or waiting a
+ * minute for a timeout; nothing else writes to it.
+ */
+export const SEARCH_LIMITS = {
+    /** How many mailboxes are worked on at once. */
+    concurrency: 4,
+    /** The most mailboxes one search covers - the caller's own first, then the shared ones (`orderMailboxes()`); a note says how many were left out. */
+    maxMailboxes: 25,
+    /** How long one mailbox's Tier 1 (server) request may take before that mailbox is given up on, so one wedged mailbox cannot hold the search. */
+    tier1TimeoutMs: 15000,
+    /** The same for a mailbox's Tier 3 pass (fetching and decrypting up to a couple of hundred candidates, so much longer). */
+    tier3TimeoutMs: 60000,
+    /** The most result rows a search keeps on screen (the page's own cap for a list, `MAX_LOADED_ROWS`, applies to a search too). */
+    maxRows: 500,
+};
+/** The least a mailbox is asked for on one page while several are searched, so a search over many mailboxes still moves at a sensible pace. */
+const MIN_MAILBOX_PAGE_SIZE = 10;
+/**
+ * How many results each mailbox contributes to one page. One mailbox gives the whole page; with several the page is shared out between them
+ * (never below `MIN_MAILBOX_PAGE_SIZE`), so the merged first page stays about one page long instead of growing by the number of mailboxes.
+ */
+export function searchPageSize(mailboxCount, pageSize) {
+    return Math.max(MIN_MAILBOX_PAGE_SIZE, Math.ceil(pageSize / Math.max(1, mailboxCount)));
+}
+export function tagHits(mailboxUid, hits) {
+    return hits.map((hit) => ({ ...hit, mailboxUid }));
+}
+/** One hit's identity across mailboxes: the same entity uid found in two mailboxes is two hits. */
+export function hitKey(hit) {
+    return `${hit.mailboxUid}\u0000${hit.entityUid}`;
+}
+/**
+ * Merges Tier 1 (server, possibly `metadataOnly` for an encrypted message), Tier 2 (local index, fully decrypted and re-scored) and Tier 3
+ * (server-narrowed candidates, decrypted and re-scored) results into one ranked list, per `specs/search.md` §7's "client MUST re-score all
+ * results it can see... normalise into the same space rather than interleaving raw scores": each tier is normalized independently via
+ * `normalizeServerScores()` before merging, since a Postgres/OpenSearch score, a local `bm25()` score, and Tier 3's own term-count score all
+ * occupy unrelated ranges. A hit present in more than one list keeps only the last-inserted entry (Tier 2 wins over Tier 3 wins over Tier 1) -
+ * Tier 2 and Tier 3 both represent genuine, content-verified scores for the same message, so which one "wins" on overlap doesn't change
+ * correctness, only which of two equally-valid scores is shown; either supersedes Tier 1's metadata-only guess for the same message.
+ *
+ * Each tier's list is pooled across every mailbox searched before it is normalized, so one mailbox's best hit is not automatically "1.0"
+ * next to another's: the ranking is the same rule as for one mailbox, applied to the merged lists. A hit's identity is its mailbox and its
+ * entity uid (`hitKey()`), so the same uid can only collapse within a mailbox. Ties keep the order the lists were given in (a stable sort), which
+ * the caller makes the mailboxes' display order.
+ *
+ * Called progressively - each time with whatever tiers have reported so far (an empty array for the rest). Pure and stateless.
+ */
+export function mergeSearchResults(tier1, tier2, tier3) {
+    const merged = new Map();
+    for (const tier of [tier1, tier3, tier2]) {
+        for (const entry of normalizeServerScores(tier)) {
+            merged.set(hitKey(entry.result), entry);
+        }
+    }
+    return Array.from(merged.values())
+        .sort((a, b) => b.normalizedScore - a.normalizedScore)
+        .map((entry) => entry.result);
+}
+/** Raised by `withTimeout()`. */
+export class SearchTimeoutError extends Error {
+    constructor() {
+        super("The search took too long.");
+        this.name = "SearchTimeoutError";
+    }
+}
+/** `promise`, or a rejection with `SearchTimeoutError` if it has not settled after `ms` (never, for a non-finite `ms`). The work is not aborted - a late answer is just dropped. */
+export function withTimeout(promise, ms) {
+    if (!Number.isFinite(ms)) {
+        return promise;
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new SearchTimeoutError()), ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (reason) => {
+            clearTimeout(timer);
+            reject(reason);
+        });
+    });
+}
+/**
+ * Runs `task` for every item, at most `concurrency` at a time, starting them in order. Stops starting new ones once `isCancelled()` (the search
+ * was superseded) or once one has rejected - which is then this function's own rejection, after the ones already running have settled.
+ */
+export async function runLimited(items, concurrency, task, isCancelled) {
+    let next = 0;
+    let failed = false;
+    const worker = async () => {
+        while (!failed && !isCancelled() && next < items.length) {
+            const item = items[next++];
+            try {
+                await task(item);
+            }
+            catch (err) {
+                failed = true;
+                throw err;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+}
+/** Why one mailbox's search failed, as a short phrase for the notice: the class of failure, never the server's own text. */
+export function classifyFailure(err) {
+    if (err instanceof SearchTimeoutError) {
+        return "timed out";
+    }
+    if (err instanceof ApiRequestError) {
+        if (err.status === 401 || err.status === 403) {
+            return "access denied";
+        }
+        return err.status >= 500 ? "server error" : "rejected by the server";
+    }
+    return "network error";
+}
+/** The body of the "Some results may be missing" notice: which mailboxes, and why each. */
+export function describeFailures(failures) {
+    return `${failures
+        .map((failure) => `${failure.mailboxName} (${failure.encrypted ? "encrypted mail: " : ""}${failure.reason})`)
+        .join(", ")} could not be searched.`;
+}