@rapidmx/web-client 0.30.0 → 0.32.0

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.32.0",
   "description": "RapidMX's webmail and admin console React UI for web-based clients.",
   "type": "module",
   "repository": "https://github.com/rapidmx/web-client",