@rapidmx/web-client 0.30.0 → 0.31.0

package/lib/mail/mailboxImportApi.ts

@@ -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 { ApiClient, ApiRequestError, apiUrl, withClient, withCsrfHeader } from "../util/api.js";
+import { ApiClient, withClient, withClientRaw } from "../util/api.js";
 import { RequestListParams, buildRequestListQuery } from "../util/apiQuery.js";
 
 export type { RequestListParams };
@@ -51,24 +51,18 @@ export interface UploadMailboxImportInput {
  * 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: File, input: UploadMailboxImportInput): Promise<MailboxImportRequest> {
+export function uploadMailboxImport(file: File, input: UploadMailboxImportInput, client?: ApiClient): Promise<MailboxImportRequest> {
     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 as MailboxImportRequest;
+    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

package/lib/mail/messageBodySanitizer.ts

@@ -27,6 +27,37 @@ export function stripRemoteCssUrls(css: string): string {
         .replace(/url\(\s*(["']?)(.*?)\1\s*\)/gi, (match, _quote: string, uri: string) => (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: string): string[] {
+    const urls: string[] = [];
+    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;
+}
+
 type Purifier = ReturnType<typeof DOMPurify>;
 let bodyPurifier: Purifier | undefined;
 
@@ -58,7 +89,7 @@ function getBodyPurifier(): Purifier | undefined {
         }
         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;
             }
@@ -106,6 +137,21 @@ const QUOTE_FORBIDDEN_TAGS = [
     // svg/math are already in DISPLAY_FORBIDDEN_TAGS, spread above — not repeated here.
 ];
 
+let signaturePurifier: Purifier | undefined;
+
+/**
+ * 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: string): string {
+    if (typeof window === "undefined") {
+        return "";
+    }
+    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/lib/search/queryGrammar.ts

@@ -64,15 +64,24 @@ const VALID_ENTITY_TYPES: ReadonlySet<string> = new Set<SearchEntityType>(["mess
  * `parseSearchQuery()` itself, after every extraction has run. */
 function extractFirst(input: string, key: string): { value?: string; rest: string } {
     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: string): string {
+    return input.replace(/"([^"]*)"/g, (_phrase, inner: string) => `"${"\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"]`. */
@@ -98,7 +107,7 @@ function extractAll(input: string, key: string): { values: string[]; rest: strin
  * spec defines for this operator — there is no `has:<other value>` form. */
 function extractHasAttachment(input: string): { found: boolean; rest: string } {
     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/lib/search/searchTier3.ts

@@ -23,7 +23,7 @@ import { evaluateMessageSecurity, type MessageSecurityResult } from "../crypto/m
 import { getMessage, getMessageRawContent } from "../mail/mailApi.js";
 import type { ParsedSearchQuery } from "./queryGrammar.js";
 import { SEARCH_FIELD_WEIGHTS } from "./searchScoring.js";
-import { candidates, SearchResult } from "./searchApi.js";
+import { candidates, type CandidateResultPage, SearchResult } from "./searchApi.js";
 
 /** Longest decrypted HTML body `stripHtml()` examines, in UTF-16 code units - content past it is ignored
  * for Tier 3 matching. A hostile sender controls this input entirely, so it is bounded on top of the
@@ -271,6 +271,11 @@ function hasAnyFilter(parsed: ParsedSearchQuery): boolean {
  * 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<T, R>(
@@ -301,7 +306,8 @@ export interface SearchEncryptedCandidatesOptions {
 }
 
 /**
- * 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
@@ -330,41 +336,68 @@ export async function searchEncryptedCandidates(
 
     const participants = [parsed.from, parsed.to, parsed.cc].filter((value): value is string => 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 results: SearchResult[] = [];
+    let cursor: string | undefined;
+    for (let pageNumber = 0; pageNumber < TIER3_MAX_CANDIDATE_PAGES; pageNumber++) {
+        let page: CandidateResultPage;
+        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 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) {
+        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 rawMime = await getMessageRawContent(candidate.entityUid);
-            if (unlocked.destroyed) {
-                return undefined;
-            }
-            const security: MessageSecurityResult = await evaluateMessageSecurity(rawMime, unlocked);
-            return { entityUid: candidate.entityUid, security };
-        },
-    );
+                const security: MessageSecurityResult = 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 [];
+        if (unlocked.destroyed) {
+            // 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;
+        }
     }
+    return results;
+}
+
+/** The decrypted candidates of one page whose real content matches `parsed`, scored and with their snippets. */
+function matchDecrypted(
+    parsed: ParsedSearchQuery,
+    settled: PromiseSettledResult<{ entityUid: string; security: MessageSecurityResult } | undefined>[],
+): SearchResult[] {
     const subjectFilter = parsed.subject?.toLowerCase();
     const results: SearchResult[] = [];
     for (const outcome of settled) {

package/lib/tasks/tasksApi.ts

@@ -6,7 +6,7 @@
  * comment for the shared ACL/authorization model every wrapper file here follows. */
 
 import { ApiClient, withClient } from "../util/api.js";
-import { ListParams, buildQuery } from "../util/apiQuery.js";
+import { ListParams, SETTINGS_LIST_LIMIT, buildQuery } from "../util/apiQuery.js";
 
 export type TaskPriority = "low" | "normal" | "high";
 
@@ -39,7 +39,7 @@ export interface Task {
 
 /** Lists a folder's tasks, soonest due date first (tasks with no due date sort last). */
 export function listTasks(folderUid: string, params: ListParams = {}, client?: ApiClient): Promise<Task[]> {
-    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 interface CreateTaskInput {
@@ -109,7 +109,7 @@ export interface TaskList {
 
 /** Lists a mailbox's task lists (Outlook To-Do-style custom lists), alphabetically by name. */
 export function listTaskLists(mailboxUid: string, params: ListParams = {}, client?: ApiClient): Promise<TaskList[]> {
-    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: { mailboxUid: string; name: string }, client?: ApiClient): Promise<TaskList> {

package/lib/util/api.ts

@@ -157,12 +157,18 @@ export async function apiFetch<T = unknown>(path: string, init: RequestInit = {}
     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<T>(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: string, init: RequestInit): Promise<Response> {
+    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<T>(res, (error) => unauthorizedObserver?.(error));
+    return res;
 }
 
 let sessionRecovery: (() => Promise<boolean>) | undefined;
@@ -196,15 +202,16 @@ async function recoverSession(): 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 async function authApiFetch<T = unknown>(authServerUrl: string, path: string, init: RequestInit = {}): Promise<T> {
     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<T>(res);
@@ -228,13 +235,19 @@ export function setApiUnauthorizedObserver(observer: ((error: ApiRequestError) =
  * `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<T>(res: Response, onUnauthorized?: (error: ApiRequestError) => void): Promise<T> {
+async function decodeApiResponse<T>(
+    res: Response,
+    onUnauthorized?: (error: ApiRequestError) => void,
+    failureMessage: string = "Request failed.",
+): Promise<T> {
     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);
@@ -259,6 +272,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()`
@@ -308,18 +327,34 @@ export function createApiClient(options: CreateApiClientOptions): ApiClient {
     const { getAccessToken } = options;
     let unauthorizedObserver: ((error: ApiRequestError) => void) | undefined;
 
-    async function clientFetch<T = unknown>(path: string, init: RequestInit = {}): Promise<T> {
+    async function send(path: string, init: RequestInit, json: boolean): Promise<Response> {
         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<T>(res, (error) => unauthorizedObserver?.(error));
+        return fetch(`${baseUrl}/api${path}`, { ...init, headers });
+    }
+
+    async function clientFetch<T = unknown>(path: string, init: RequestInit = {}): Promise<T> {
+        return decodeApiResponse<T>(await send(path, init, true), (error) => unauthorizedObserver?.(error));
+    }
+
+    async function clientFetchBlob(path: string, init: RequestInit = {}): Promise<Blob> {
+        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<never>(res, (error) => unauthorizedObserver?.(error));
+        }
+        return res.blob();
     }
 
     return {
         fetch: clientFetch,
+        fetchBlob: clientFetchBlob,
         setUnauthorizedObserver(observer) {
             unauthorizedObserver = observer;
         },
@@ -339,3 +374,51 @@ export function createApiClient(options: CreateApiClientOptions): ApiClient {
 export function withClient<T = unknown>(client: ApiClient | undefined, path: string, init?: RequestInit): Promise<T> {
     return client ? client.fetch<T>(path, init) : apiFetch<T>(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<T = unknown>(
+    client: ApiClient | undefined,
+    path: string,
+    method: string,
+    file: Blob,
+    contentType: string = file.type,
+    failureMessage: string = "Upload failed.",
+): Promise<T> {
+    if (client) {
+        return client.fetch<T>(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<T>(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: ApiClient | undefined,
+    path: string,
+    failureMessage: string = "Download failed.",
+): Promise<Blob> {
+    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<never>(res, (error) => unauthorizedObserver?.(error), failureMessage);
+    }
+    return res.blob();
+}

package/lib/util/apiQuery.ts

@@ -16,6 +16,10 @@ export interface ListParams {
 
 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(...)`).
@@ -28,6 +32,15 @@ export function buildQuery(params: ListParams, extra: Record<string, string> = {
     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: Record<string, "ASC" | "DESC">): { sort: string } {
+    return { sort: JSON.stringify(sort) };
+}
+
 /**
  * Optional paging/scope params for the async-request list endpoints (`listExportRequests()`,
  * `listImportRequests()`, `listErasureRequests()`, `listMatterExportRequests()`,

package/lib/util/settleWithLimit.ts

@@ -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<T, R>(items: readonly T[], limit: number, task: (item: T) => Promise<R>): Promise<PromiseSettledResult<R>[]> {
+    const outcomes = new Array<PromiseSettledResult<R>>(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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rapidmx/web-client",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "RapidMX's webmail and admin console React UI for web-based clients.",
   "type": "module",
   "repository": "https://github.com/rapidmx/web-client",