@rapidmx/web-client 0.30.0 → 0.31.0

package/dist/lib/mail/mailboxImportApi.js

@@ -9,7 +9,7 @@
  * stages the upload and returns the `pending` request; poll `getImportRequest()`/`listImportRequests()`
  * for `status` to become `"completed"` (with `importedCount`/`failedCount`) or `"failed"`.
  */
-import { ApiRequestError, apiUrl, withClient, withCsrfHeader } from "../util/api.js";
+import { withClient, withClientRaw } from "../util/api.js";
 import { buildRequestListQuery } from "../util/apiQuery.js";
 /**
  * Uploads `file`'s raw bytes as a new mailbox-import request. Bypasses `apiFetch` — that helper always
@@ -18,24 +18,12 @@ import { buildRequestListQuery } from "../util/apiQuery.js";
  * with `format`/`targetFolderUid`/`mailboxUid` as query-string parameters, not a JSON body — the same
  * shape `mailApi.ts`'s `uploadAttachment()` already establishes for a raw-bytes upload.
  */
-export async function uploadMailboxImport(file, input) {
+export function uploadMailboxImport(file, input, client) {
     const params = new URLSearchParams({ format: input.format, targetFolderUid: input.targetFolderUid });
     if (input.mailboxUid) {
         params.set("mailboxUid", input.mailboxUid);
     }
-    const res = await fetch(apiUrl(`/mail/mailbox-import-requests?${params.toString()}`), {
-        method: "POST",
-        credentials: "include",
-        headers: withCsrfHeader({ "Content-Type": input.format === "pst" ? "application/vnd.ms-outlook" : "application/mbox" }),
-        body: file,
-    });
-    const contentType = res.headers.get("content-type") ?? "";
-    const responseBody = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
-    if (!res.ok) {
-        const message = (responseBody && (responseBody.message || responseBody.error)) || res.statusText || "Upload failed.";
-        throw new ApiRequestError(message, res.status, responseBody?.code);
-    }
-    return responseBody;
+    return withClientRaw(client, `/mail/mailbox-import-requests?${params.toString()}`, "POST", file, input.format === "pst" ? "application/vnd.ms-outlook" : "application/mbox");
 }
 /** `client`, given by every function below that isn't a raw-bytes upload, is an explicit `ApiClient` from
  * `createApiClient()` (e.g. one account of a multi-account app) to call instead of the default global

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

@@ -7,6 +7,12 @@ export declare function stripRemoteCssUrls(css: string): string;
  * sanitize with - never the unsanitized input.
  */
 export declare function sanitizeMessageBodyHtml(html: string): string;
+/**
+ * Sanitizes a signature's HTML for the compose body: DOMPurify's defaults (no scripts, handlers or `javascript:` URLs) and
+ * the quote's tag list (nothing that styles, frames or submits). Unlike a quoted message, a signature is the sender's own
+ * and may carry pictures from the web, so remote images and links stay. Returns `""` when there is no DOM to sanitize with.
+ */
+export declare function sanitizeSignatureHtml(html: string): string;
 /**
  * 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

package/dist/lib/mail/messageBodySanitizer.js

@@ -22,6 +22,36 @@ export function stripRemoteCssUrls(css) {
         .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"));
 }
+/** The candidate URLs of a `srcset` value, parsed as the HTML spec does: a candidate's URL is a run of non-whitespace
+ * characters (it may itself contain commas - a `data:` URI always does), so a comma that ends a URL or follows its
+ * descriptors separates candidates whether or not whitespace follows it. */
+function srcsetUrls(value) {
+    const urls = [];
+    let position = 0;
+    while (position < value.length) {
+        const start = value.slice(position).search(/[^\s,]/);
+        if (start < 0) {
+            break;
+        }
+        position += start;
+        const end = value.slice(position).search(/\s/);
+        const token = end < 0 ? value.slice(position) : value.slice(position, position + end);
+        position += token.length;
+        urls.push(token.replace(/,+$/, ""));
+        if (!token.endsWith(",")) {
+            // Skip the descriptors, up to the comma that ends the candidate.
+            const comma = value.indexOf(",", position);
+            const descriptors = value.slice(position, comma < 0 ? value.length : comma);
+            if (descriptors.includes("(")) {
+                // The spec's tokenizer ignores commas inside parentheses, so a browser may read the candidates that follow differently from
+                // the way this does. No valid descriptor has one: refuse the whole value.
+                urls.push(descriptors);
+            }
+            position = comma < 0 ? value.length : comma + 1;
+        }
+    }
+    return urls;
+}
 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
@@ -51,7 +81,7 @@ function getBodyPurifier() {
         }
         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];
+            const candidates = name === "srcset" ? srcsetUrls(data.attrValue) : [data.attrValue];
             if (!candidates.every((candidate) => EMBEDDED_URI.test(candidate))) {
                 data.keepAttr = false;
             }
@@ -95,6 +125,19 @@ const QUOTE_FORBIDDEN_TAGS = [
     "track",
     // svg/math are already in DISPLAY_FORBIDDEN_TAGS, spread above — not repeated here.
 ];
+let signaturePurifier;
+/**
+ * Sanitizes a signature's HTML for the compose body: DOMPurify's defaults (no scripts, handlers or `javascript:` URLs) and
+ * the quote's tag list (nothing that styles, frames or submits). Unlike a quoted message, a signature is the sender's own
+ * and may carry pictures from the web, so remote images and links stay. Returns `""` when there is no DOM to sanitize with.
+ */
+export function sanitizeSignatureHtml(html) {
+    if (typeof window === "undefined") {
+        return "";
+    }
+    signaturePurifier ?? (signaturePurifier = DOMPurify(window));
+    return signaturePurifier.isSupported ? signaturePurifier.sanitize(html, { FORBID_TAGS: QUOTE_FORBIDDEN_TAGS }) : "";
+}
 /**
  * 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

package/dist/lib/search/queryGrammar.js

@@ -7,14 +7,22 @@ const VALID_ENTITY_TYPES = new Set(["message", "contact", "calendarEvent", "note
  * `parseSearchQuery()` itself, after every extraction has run. */
 function extractFirst(input, key) {
     const pattern = new RegExp(`(^|\\s)${key}:(?:"([^"]*)"|(\\S+))`, "i");
-    const match = pattern.exec(input);
-    if (!match) {
+    const found = pattern.exec(maskQuoted(input));
+    if (!found) {
         return { rest: input };
     }
+    // The masked text only says where the operator is - what it holds is read from the real one.
+    const match = pattern.exec(input.slice(found.index));
     const value = match[2] ?? match[3] ?? "";
-    const rest = input.slice(0, match.index) + match[1] + input.slice(match.index + match[0].length);
+    const rest = input.slice(0, found.index) + match[1] + input.slice(found.index + match[0].length);
     return { value, rest };
 }
+/** `input` with the inside of every quoted phrase blanked out (the length stays the same, so positions carry over to
+ * `input`): a word that looks like an operator inside a phrase - `"meeting from:bob"` - is part of the phrase, never an
+ * operator. */
+function maskQuoted(input) {
+    return input.replace(/"([^"]*)"/g, (_phrase, inner) => `"${"\0".repeat(inner.length)}"`);
+}
 /** Repeatedly applies `extractFirst()` for `key` until no more occurrences remain, splitting any
  * comma-separated value into individual entries — so `is:read is:flagged` and `is:read,flagged` both
  * produce `["read", "flagged"]`. */
@@ -39,7 +47,7 @@ function extractAll(input, key) {
  * spec defines for this operator — there is no `has:<other value>` form. */
 function extractHasAttachment(input) {
     const pattern = /(^|\s)has:attachment\b/i;
-    const match = pattern.exec(input);
+    const match = pattern.exec(maskQuoted(input));
     if (!match) {
         return { found: false, rest: input };
     }

package/dist/lib/search/searchTier3.d.ts

@@ -38,13 +38,18 @@ export declare function stripHtml(html: string): string;
 /** How many candidates are fetched/decrypted at once - bounds the burst of raw-MIME requests and
  * concurrent WebCrypto work a large candidate page would otherwise fire all at once. */
 export declare const TIER3_DECRYPT_CONCURRENCY = 4;
+/** The most candidate pages one search walks (`nextCursor` onwards) while it is still short of `limit` results - a
+ * search that matches little must not download and decrypt a whole mailbox, but an encrypted message beyond the first
+ * page of candidates is still found. */
+export declare const TIER3_MAX_CANDIDATE_PAGES = 4;
 export interface SearchEncryptedCandidatesOptions {
     /** Forwarded to `candidates()` - which accessible mailbox to search (e.g. the one currently open).
      * Omitted, the server uses the caller's own mailbox. */
     mailboxUid?: string;
 }
 /**
- * Runs Tier 3 for one parsed query: fetches a bounded candidate set from the server, decrypts each
+ * Runs Tier 3 for one parsed query: fetches a bounded candidate set from the server (following `nextCursor` for up to
+ * `TIER3_MAX_CANDIDATE_PAGES` pages while fewer than `limit` messages have matched), decrypts each
  * candidate this device can open (at most `TIER3_DECRYPT_CONCURRENCY` at a time), and returns only the
  * ones whose real (decrypted) content actually matches - each with a raw (not yet normalized) score the
  * caller should run through `searchScoring.ts#normalizeServerScores()` alongside Tier 1's own scores

package/dist/lib/search/searchTier3.js

@@ -224,6 +224,10 @@ function hasAnyFilter(parsed) {
 /** How many candidates are fetched/decrypted at once - bounds the burst of raw-MIME requests and
  * concurrent WebCrypto work a large candidate page would otherwise fire all at once. */
 export const TIER3_DECRYPT_CONCURRENCY = 4;
+/** The most candidate pages one search walks (`nextCursor` onwards) while it is still short of `limit` results - a
+ * search that matches little must not download and decrypt a whole mailbox, but an encrypted message beyond the first
+ * page of candidates is still found. */
+export const TIER3_MAX_CANDIDATE_PAGES = 4;
 /** `Promise.allSettled()` over `items`, but never running more than `concurrency` `task`s at a time.
  * Outcomes are returned in `items`' own order. */
 async function settleWithConcurrency(items, concurrency, task) {
@@ -244,7 +248,8 @@ async function settleWithConcurrency(items, concurrency, task) {
     return outcomes;
 }
 /**
- * Runs Tier 3 for one parsed query: fetches a bounded candidate set from the server, decrypts each
+ * Runs Tier 3 for one parsed query: fetches a bounded candidate set from the server (following `nextCursor` for up to
+ * `TIER3_MAX_CANDIDATE_PAGES` pages while fewer than `limit` messages have matched), decrypts each
  * candidate this device can open (at most `TIER3_DECRYPT_CONCURRENCY` at a time), and returns only the
  * ones whose real (decrypted) content actually matches - each with a raw (not yet normalized) score the
  * caller should run through `searchScoring.ts#normalizeServerScores()` alongside Tier 1's own scores
@@ -266,35 +271,59 @@ export async function searchEncryptedCandidates(parsed, unlocked, limit = 50, op
         return [];
     }
     const participants = [parsed.from, parsed.to, parsed.cc].filter((value) => Boolean(value));
-    const page = await candidates({
-        types: ["message"],
-        participants: participants.length > 0 ? participants : undefined,
-        before: parsed.before,
-        after: parsed.after,
-        folderUid: parsed.folderUid,
-        flags: parsed.flags,
-        labels: parsed.labels,
-        limit,
-        mailboxUid: options.mailboxUid,
-    });
-    const settled = await settleWithConcurrency(page.candidates.filter((candidate) => candidate.entityType === "message"), TIER3_DECRYPT_CONCURRENCY, async (candidate) => {
-        if (parsed.hasAttachment !== undefined) {
-            const message = await getMessage(candidate.entityUid);
-            if (Boolean(message.hasAttachments) !== parsed.hasAttachment) {
-                return undefined;
+    const results = [];
+    let cursor;
+    for (let pageNumber = 0; pageNumber < TIER3_MAX_CANDIDATE_PAGES; pageNumber++) {
+        let page;
+        try {
+            page = await candidates({
+                types: ["message"],
+                participants: participants.length > 0 ? participants : undefined,
+                before: parsed.before,
+                after: parsed.after,
+                folderUid: parsed.folderUid,
+                flags: parsed.flags,
+                labels: parsed.labels,
+                limit,
+                cursor,
+                mailboxUid: options.mailboxUid,
+            });
+        }
+        catch (err) {
+            if (pageNumber === 0) {
+                throw err;
             }
+            // A later page failing keeps what the earlier ones found.
+            break;
         }
-        const rawMime = await getMessageRawContent(candidate.entityUid);
+        const settled = await settleWithConcurrency(page.candidates.filter((candidate) => candidate.entityType === "message"), TIER3_DECRYPT_CONCURRENCY, async (candidate) => {
+            if (parsed.hasAttachment !== undefined) {
+                const message = await getMessage(candidate.entityUid);
+                if (Boolean(message.hasAttachments) !== parsed.hasAttachment) {
+                    return undefined;
+                }
+            }
+            const rawMime = await getMessageRawContent(candidate.entityUid);
+            if (unlocked.destroyed) {
+                return undefined;
+            }
+            const security = await evaluateMessageSecurity(rawMime, unlocked);
+            return { entityUid: candidate.entityUid, security };
+        });
         if (unlocked.destroyed) {
-            return undefined;
+            // Locked while candidates were being fetched/decrypted - don't surface decrypted content after a lock.
+            return [];
+        }
+        results.push(...matchDecrypted(parsed, settled));
+        cursor = page.nextCursor;
+        if (!cursor || results.length >= limit) {
+            break;
         }
-        const security = await evaluateMessageSecurity(rawMime, unlocked);
-        return { entityUid: candidate.entityUid, security };
-    });
-    if (unlocked.destroyed) {
-        // Locked while candidates were being fetched/decrypted - don't surface decrypted content after a lock.
-        return [];
     }
+    return results;
+}
+/** The decrypted candidates of one page whose real content matches `parsed`, scored and with their snippets. */
+function matchDecrypted(parsed, settled) {
     const subjectFilter = parsed.subject?.toLowerCase();
     const results = [];
     for (const outcome of settled) {

package/dist/lib/tasks/tasksApi.js

@@ -5,13 +5,13 @@
 /** Typed wrappers over `@rapidmx/restapi`'s `/mail/tasks` REST surface — see `mailApi.ts`'s own header
  * comment for the shared ACL/authorization model every wrapper file here follows. */
 import { withClient } from "../util/api.js";
-import { buildQuery } from "../util/apiQuery.js";
+import { SETTINGS_LIST_LIMIT, buildQuery } from "../util/apiQuery.js";
 /** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
  * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
  * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
 /** Lists a folder's tasks, soonest due date first (tasks with no due date sort last). */
 export function listTasks(folderUid, params = {}, client) {
-    return withClient(client, `/mail/tasks?${buildQuery(params, { folderUid, sort: JSON.stringify({ dueDate: "ASC" }) })}`);
+    return withClient(client, `/mail/tasks?${buildQuery(params, { folderUid, sort: JSON.stringify({ dueDate: "ASC", uid: "ASC" }) })}`);
 }
 export function createTask(input, client) {
     return withClient(client, "/mail/tasks", {
@@ -39,7 +39,7 @@ export function deleteTask(uid, version, client) {
 }
 /** Lists a mailbox's task lists (Outlook To-Do-style custom lists), alphabetically by name. */
 export function listTaskLists(mailboxUid, params = {}, client) {
-    return withClient(client, `/mail/task-lists?${buildQuery(params, { mailboxUid, sort: JSON.stringify({ name: "ASC" }) })}`);
+    return withClient(client, `/mail/task-lists?${buildQuery({ limit: SETTINGS_LIST_LIMIT, ...params }, { mailboxUid, sort: JSON.stringify({ name: "ASC", uid: "ASC" }) })}`);
 }
 export function createTaskList(input, client) {
     return withClient(client, "/mail/task-lists", { method: "POST", body: JSON.stringify(input) });

package/dist/lib/util/api.d.ts

@@ -86,10 +86,12 @@ export declare function setApiSessionRecovery(recovery: (() => Promise<boolean>)
  * a deployment-level requirement owned by auth-server/the Helm chart, not configured here — and auth-server's
  * CORS config must explicitly allow this app's origin with credentials.
  *
- * `applyCsrfHeader()` is still called here for consistency, but it never actually finds a token for a truly
- * cross-origin call — see its own doc comment on `readCsrfCookie()` for why that's correct rather than a
- * gap: auth-server's CSRF protection for this call shape comes from its own Origin allow-list check, not a
- * double-submit cookie this app's JavaScript could never read in the first place.
+ * No `x-csrf-token` header is sent, deliberately. A double-submit token is only meaningful to the server that issued it, and the `csrf`
+ * cookie this app's JavaScript can read is *this* host's own (`mail.example.com`), never auth-server's - so echoing it
+ * would be a wrong token for the wrong server. Worse, auth-server's CORS rules do not allow that header, so the browser
+ * blocked the preflight of every such call (the silent session refresh, sign-out) before it ever reached the server: "Request header
+ * field x-csrf-token is not allowed by Access-Control-Allow-Headers". Auth-server's CSRF protection for this cross-origin call shape is
+ * its Origin allow-list check, which needs no header.
  */
 export declare function authApiFetch<T = unknown>(authServerUrl: string, path: string, init?: RequestInit): Promise<T>;
 /**
@@ -110,6 +112,12 @@ export interface ApiClient {
     /** Same contract as `apiFetch()`: prefixes `path` with `/api`, parses a JSON response, and rejects with
      * `ApiRequestError` on a non-ok response. */
     fetch<T = unknown>(path: string, init?: RequestInit): Promise<T>;
+    /**
+     * Like `fetch()` - same origin, authentication and error decoding - but resolves the response's own bytes instead of parsing JSON, for a picture or other
+     * file. An `<img src>` cannot send an `Authorization` header, so a token-authenticated client shows such a file by fetching it here and displaying a
+     * `blob:` URL. No `Content-Type` is added.
+     */
+    fetchBlob(path: string, init?: RequestInit): Promise<Blob>;
     /**
      * This client instance's own `setApiUnauthorizedObserver()` equivalent - see `createApiClient()`'s doc
      * comment for why it is per-instance rather than shared with the module-level `setApiUnauthorizedObserver()`
@@ -164,3 +172,17 @@ export declare function createApiClient(options: CreateApiClientOptions): ApiCli
  * that call too, so a whole call chain stays pinned to one account.
  */
 export declare function withClient<T = unknown>(client: ApiClient | undefined, path: string, init?: RequestInit): Promise<T>;
+/**
+ * Sends a file's own bytes (not JSON) to `path` - the upload counterpart of `withClient()`. With an explicit `client` the request goes through it, so it
+ * reaches that account's origin with its token (the client keeps the `Content-Type` given here). Without one it is a plain `fetch()` to the global
+ * origin that carries the `jwt` cookie and the CSRF header, exactly as a same-origin upload always was. Resolves the decoded JSON response and rejects with
+ * an `ApiRequestError` (`failureMessage` when the server gave no message) on a non-ok one.
+ */
+export declare function withClientRaw<T = unknown>(client: ApiClient | undefined, path: string, method: string, file: Blob, contentType?: string, failureMessage?: string): Promise<T>;
+/**
+ * Fetches `path`'s own bytes (a message's raw source, say) rather than JSON - the download counterpart of `withClient()`. With an explicit `client` the
+ * request goes through its `fetchBlob()`, so it reaches that account's origin with its token. Without one it is a plain `fetch()` to the global origin
+ * with the `jwt` cookie, renewing the session and asking again once on a `401`, as `apiFetch()` does. Rejects with an `ApiRequestError`
+ * (`failureMessage` when the server gave no message) on a non-ok response.
+ */
+export declare function withClientBlob(client: ApiClient | undefined, path: string, failureMessage?: string): Promise<Blob>;

package/dist/lib/util/api.js

@@ -137,12 +137,17 @@ export async function apiFetch(path, init = {}) {
     headers.set("Content-Type", "application/json");
     applyCsrfHeader(headers, init.method);
     const credentials = apiBaseUrl ? "include" : init.credentials;
-    let res = await fetch(apiUrl(path), { ...init, headers, credentials });
-    // The access token has run out (a sleeping tab or laptop stops the timer that renews it in time): renew the session, and ask again once.
+    const res = await fetchWithRecovery(path, { ...init, headers, credentials });
+    return decodeApiResponse(res, (error) => unauthorizedObserver?.(error));
+}
+/** `fetch()` of `path` against the global origin. When the access token has run out (a sleeping tab or laptop stops the timer that renews it in
+ * time) it renews the session, and asks again once. */
+async function fetchWithRecovery(path, init) {
+    let res = await fetch(apiUrl(path), init);
     if (res.status === 401 && sessionRecovery && (await recoverSession())) {
-        res = await fetch(apiUrl(path), { ...init, headers, credentials });
+        res = await fetch(apiUrl(path), init);
     }
-    return decodeApiResponse(res, (error) => unauthorizedObserver?.(error));
+    return res;
 }
 let sessionRecovery;
 /**
@@ -173,15 +178,16 @@ async function recoverSession() {
  * a deployment-level requirement owned by auth-server/the Helm chart, not configured here — and auth-server's
  * CORS config must explicitly allow this app's origin with credentials.
  *
- * `applyCsrfHeader()` is still called here for consistency, but it never actually finds a token for a truly
- * cross-origin call — see its own doc comment on `readCsrfCookie()` for why that's correct rather than a
- * gap: auth-server's CSRF protection for this call shape comes from its own Origin allow-list check, not a
- * double-submit cookie this app's JavaScript could never read in the first place.
+ * No `x-csrf-token` header is sent, deliberately. A double-submit token is only meaningful to the server that issued it, and the `csrf`
+ * cookie this app's JavaScript can read is *this* host's own (`mail.example.com`), never auth-server's - so echoing it
+ * would be a wrong token for the wrong server. Worse, auth-server's CORS rules do not allow that header, so the browser
+ * blocked the preflight of every such call (the silent session refresh, sign-out) before it ever reached the server: "Request header
+ * field x-csrf-token is not allowed by Access-Control-Allow-Headers". Auth-server's CSRF protection for this cross-origin call shape is
+ * its Origin allow-list check, which needs no header.
  */
 export async function authApiFetch(authServerUrl, path, init = {}) {
     const headers = new Headers(init.headers);
     headers.set("Content-Type", "application/json");
-    applyCsrfHeader(headers, init.method);
     const res = await fetch(`${authServerUrl}/api${path}`, { ...init, headers, credentials: "include" });
     return decodeApiResponse(res);
 }
@@ -201,12 +207,14 @@ export function setApiUnauthorizedObserver(observer) {
  * `createApiClient()`-made client's `fetch()` (which forwards to that instance's own
  * `setUnauthorizedObserver()`) pass their own. A throwing `onUnauthorized` never changes what the caller sees.
  */
-async function decodeApiResponse(res, onUnauthorized) {
+async function decodeApiResponse(res, onUnauthorized, failureMessage = "Request failed.") {
     const contentType = res.headers.get("content-type") ?? "";
     const body = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
     if (!res.ok) {
-        const message = (body && (body.message || body.error)) || res.statusText || "Request failed.";
-        const error = new ApiRequestError(message, res.status, body?.code, body);
+        // A body is untrusted: only a non-empty string is a message (anything else would read "[object Object]"), only a string a code.
+        const reported = body && (body.message || body.error);
+        const message = (typeof reported === "string" && reported) || res.statusText || failureMessage;
+        const error = new ApiRequestError(message, res.status, typeof body?.code === "string" ? body.code : undefined, body);
         if (res.status === 401 && onUnauthorized) {
             try {
                 onUnauthorized(error);
@@ -242,16 +250,30 @@ export function createApiClient(options) {
     const baseUrl = options.baseUrl.replace(/\/$/, "");
     const { getAccessToken } = options;
     let unauthorizedObserver;
-    async function clientFetch(path, init = {}) {
+    async function send(path, init, json) {
         const headers = new Headers(init.headers);
-        headers.set("Content-Type", "application/json");
+        // JSON unless the caller sent a body of its own kind (an upload names the file's type).
+        if (json && !headers.has("Content-Type")) {
+            headers.set("Content-Type", "application/json");
+        }
         const token = await getAccessToken();
         headers.set("Authorization", `jwt ${token}`);
-        const res = await fetch(`${baseUrl}/api${path}`, { ...init, headers });
-        return decodeApiResponse(res, (error) => unauthorizedObserver?.(error));
+        return fetch(`${baseUrl}/api${path}`, { ...init, headers });
+    }
+    async function clientFetch(path, init = {}) {
+        return decodeApiResponse(await send(path, init, true), (error) => unauthorizedObserver?.(error));
+    }
+    async function clientFetchBlob(path, init = {}) {
+        const res = await send(path, init, false);
+        if (!res.ok) {
+            // Throws the same `ApiRequestError` (and tells the observer of a 401) as every other request.
+            await decodeApiResponse(res, (error) => unauthorizedObserver?.(error));
+        }
+        return res.blob();
     }
     return {
         fetch: clientFetch,
+        fetchBlob: clientFetchBlob,
         setUnauthorizedObserver(observer) {
             unauthorizedObserver = observer;
         },
@@ -270,3 +292,38 @@ export function createApiClient(options) {
 export function withClient(client, path, init) {
     return client ? client.fetch(path, init) : apiFetch(path, init);
 }
+/**
+ * Sends a file's own bytes (not JSON) to `path` - the upload counterpart of `withClient()`. With an explicit `client` the request goes through it, so it
+ * reaches that account's origin with its token (the client keeps the `Content-Type` given here). Without one it is a plain `fetch()` to the global
+ * origin that carries the `jwt` cookie and the CSRF header, exactly as a same-origin upload always was. Resolves the decoded JSON response and rejects with
+ * an `ApiRequestError` (`failureMessage` when the server gave no message) on a non-ok one.
+ */
+export async function withClientRaw(client, path, method, file, contentType = file.type, failureMessage = "Upload failed.") {
+    if (client) {
+        return client.fetch(path, { method, headers: { "Content-Type": contentType }, body: file });
+    }
+    const res = await fetchWithRecovery(path, {
+        method,
+        credentials: "include",
+        headers: withCsrfHeader({ "Content-Type": contentType }, method),
+        body: file,
+    });
+    return decodeApiResponse(res, (error) => unauthorizedObserver?.(error), failureMessage);
+}
+/**
+ * Fetches `path`'s own bytes (a message's raw source, say) rather than JSON - the download counterpart of `withClient()`. With an explicit `client` the
+ * request goes through its `fetchBlob()`, so it reaches that account's origin with its token. Without one it is a plain `fetch()` to the global origin
+ * with the `jwt` cookie, renewing the session and asking again once on a `401`, as `apiFetch()` does. Rejects with an `ApiRequestError`
+ * (`failureMessage` when the server gave no message) on a non-ok response.
+ */
+export async function withClientBlob(client, path, failureMessage = "Download failed.") {
+    if (client) {
+        return client.fetchBlob(path);
+    }
+    const res = await fetchWithRecovery(path, { credentials: "include" });
+    if (!res.ok) {
+        // Throws the same `ApiRequestError` (and tells the observer of a 401) as every other request.
+        await decodeApiResponse(res, (error) => unauthorizedObserver?.(error), failureMessage);
+    }
+    return res.blob();
+}

package/dist/lib/util/apiQuery.d.ts

@@ -8,11 +8,22 @@ export interface ListParams {
     page?: number;
     limit?: number;
 }
+/** The page size of a list that a settings screen shows whole (labels, signatures, filter rules, task lists, contact lists): a few dozen rows at most in practice, so one
+ * large page rather than the default 25 that would hide everything after the 25th with no way to reach it. */
+export declare const SETTINGS_LIST_LIMIT = 200;
 /**
  * Builds a `limit`/`page` query string, plus any extra scope/filter params (e.g. `folderUid`,
  * or one of `@rapidmx/restapi`'s generic query-operator values like `startDate=lte(...)`).
  */
 export declare function buildQuery(params: ListParams, extra?: Record<string, string>): string;
+/**
+ * The `sort` query value for `buildQuery()`'s extra params, in the order the keys are given. Paging with no sort leaves the order to the
+ * database, which on SQL can repeat or skip a row between two pages and on MongoDB is the oldest first: end the sort with a unique key (`uid`)
+ * so every row lands on exactly one page.
+ */
+export declare function sortQuery(sort: Record<string, "ASC" | "DESC">): {
+    sort: string;
+};
 /**
  * Optional paging/scope params for the async-request list endpoints (`listExportRequests()`,
  * `listImportRequests()`, `listErasureRequests()`, `listMatterExportRequests()`,

package/dist/lib/util/apiQuery.js

@@ -9,6 +9,9 @@
  * other than it happening to live there first.
  */
 const DEFAULT_PAGE_SIZE = 25;
+/** The page size of a list that a settings screen shows whole (labels, signatures, filter rules, task lists, contact lists): a few dozen rows at most in practice, so one
+ * large page rather than the default 25 that would hide everything after the 25th with no way to reach it. */
+export const SETTINGS_LIST_LIMIT = 200;
 /**
  * Builds a `limit`/`page` query string, plus any extra scope/filter params (e.g. `folderUid`,
  * or one of `@rapidmx/restapi`'s generic query-operator values like `startDate=lte(...)`).
@@ -20,6 +23,14 @@ export function buildQuery(params, extra = {}) {
     }
     return parts.join("&");
 }
+/**
+ * The `sort` query value for `buildQuery()`'s extra params, in the order the keys are given. Paging with no sort leaves the order to the
+ * database, which on SQL can repeat or skip a row between two pages and on MongoDB is the oldest first: end the sort with a unique key (`uid`)
+ * so every row lands on exactly one page.
+ */
+export function sortQuery(sort) {
+    return { sort: JSON.stringify(sort) };
+}
 /**
  * Builds a `?limit=&page=&matterId=` suffix from only the params actually supplied - unlike
  * `buildQuery()`, applies no default page size (these endpoints historically returned every request

package/dist/lib/util/settleWithLimit.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Runs `task` for each of `items`, never more than `limit` of them at once, and resolves to what became of every one in the order of `items`, as
+ * `Promise.allSettled()` does - a task that fails does not stop the others. For a batch of requests too big to send all at once (a thousand rows ticked).
+ */
+export declare function settleWithLimit<T, R>(items: readonly T[], limit: number, task: (item: T) => Promise<R>): Promise<PromiseSettledResult<R>[]>;

package/dist/lib/util/settleWithLimit.js

@@ -0,0 +1,25 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Runs `task` for each of `items`, never more than `limit` of them at once, and resolves to what became of every one in the order of `items`, as
+ * `Promise.allSettled()` does - a task that fails does not stop the others. For a batch of requests too big to send all at once (a thousand rows ticked).
+ */
+export async function settleWithLimit(items, limit, task) {
+    const outcomes = new Array(items.length);
+    let next = 0;
+    async function worker() {
+        while (next < items.length) {
+            const index = next++;
+            try {
+                outcomes[index] = { status: "fulfilled", value: await task(items[index]) };
+            }
+            catch (reason) {
+                outcomes[index] = { status: "rejected", reason };
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return outcomes;
+}

package/lib/admin/auditLogApi.ts

@@ -10,7 +10,7 @@
  */
 
 import { ApiClient, withClient } from "../util/api.js";
-import { ListParams, buildQuery } from "../util/apiQuery.js";
+import { ListParams, buildQuery, sortQuery } from "../util/apiQuery.js";
 
 export type { ListParams };
 
@@ -44,5 +44,5 @@ export function listAuditLog(filters: AuditLogFilters = {}, params: ListParams =
     if (filters.actorUserUid) extra.actorUserUid = filters.actorUserUid;
     if (filters.action) extra.action = filters.action;
     if (filters.targetType) extra.targetType = filters.targetType;
-    return withClient(client, `/mail/audit-log?${buildQuery(params, extra)}`);
+    return withClient(client, `/mail/audit-log?${buildQuery(params, { ...extra, ...sortQuery({ dateCreated: "DESC", uid: "ASC" }) })}`);
 }

package/lib/admin/distributionListsApi.ts

@@ -8,7 +8,7 @@
  */
 
 import { ApiClient, withClient } from "../util/api.js";
-import { ListParams, buildQuery } from "../util/apiQuery.js";
+import { ListParams, buildQuery, sortQuery } from "../util/apiQuery.js";
 
 export type { ListParams };
 
@@ -31,7 +31,7 @@ export interface DistributionList {
  * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
  * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
 export function listDistributionLists(params: ListParams = {}, client?: ApiClient): Promise<DistributionList[]> {
-    return withClient(client, `/mail/distribution-lists?${buildQuery(params)}`);
+    return withClient(client, `/mail/distribution-lists?${buildQuery(params, sortQuery({ uid: "ASC" }))}`);
 }
 
 export function getDistributionList(uid: string, client?: ApiClient): Promise<DistributionList> {

package/lib/admin/domainsApi.ts

@@ -9,7 +9,7 @@
  */
 
 import { ApiClient, withClient } from "../util/api.js";
-import { ListParams, buildQuery } from "../util/apiQuery.js";
+import { ListParams, buildQuery, sortQuery } from "../util/apiQuery.js";
 
 export type { ListParams };
 
@@ -37,7 +37,7 @@ export interface Domain {
  * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
  * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
 export function listDomains(params: ListParams = {}, client?: ApiClient): Promise<Domain[]> {
-    return withClient(client, `/mail/domains?${buildQuery(params)}`);
+    return withClient(client, `/mail/domains?${buildQuery(params, sortQuery({ uid: "ASC" }))}`);
 }
 
 export function getDomain(uid: string, client?: ApiClient): Promise<Domain> {