@rapidmx/web-client 0.21.0 → 0.22.0

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

@@ -0,0 +1,160 @@
+/**
+ * Minimal client-side helper shared by every app in this project: a `fetch` wrapper that talks to the
+ * same-origin RapidMX API. There is no client router or HTTP client shipped by `@rapidrest/react`, so this
+ * is deliberately small and framework-free.
+ *
+ * This service never issues its own JWTs — identity comes entirely from a separate `auth-server` deployment
+ * (see `.claude/NOTES.md`). Authentication rides along via the `jwt` HttpOnly cookie that auth-server sets on
+ * sign-in — the browser attaches it automatically to every same-origin `fetch()` call (the default
+ * `credentials: "same-origin"` mode), and this server's `JWTStrategy` accepts it as a credential for every
+ * authenticated request, not just SSR page loads. There is no local elevation/step-up flow here (unlike
+ * auth-server's own `api.ts`, which this is a trimmed sibling of): a request to an elevation-gated endpoint
+ * (`@RequiresElevation()` on the server) made with a non-elevated token fails with an `ApiRequestError` of
+ * status 403 and code `"api-104"`, and it is up to the caller to send the browser to auth-server's
+ * `/auth/elevate?return_to=...` page, which returns it to `return_to` once the user has confirmed their identity
+ * (the admin console does exactly that - see `AdminShell` in `@rapidmx/web-client`). Code `"api-103"` is a
+ * different 403 - the caller lacks a required role, and elevating won't help.
+ */
+export declare class ApiRequestError extends Error {
+    status: number;
+    code?: string;
+    /**
+     * The response's whole parsed JSON body, for an endpoint that says more than `message` - e.g. a failed send's
+     * per-recipient SMTP results under `details`. `undefined` when the response had no JSON body (or the error
+     * was raised on the client), so a caller must treat it as untyped, untrusted data and read it defensively.
+     */
+    details?: unknown;
+    constructor(message: string, status: number, code?: string, details?: unknown);
+}
+/**
+ * Points `apiFetch()` at `baseUrl` (e.g. `"https://mail.example.com"`) instead of the default
+ * same-origin relative path. Only needed by a consumer whose own origin genuinely differs from the
+ * RapidMX server's - see `apiBaseUrl`'s own doc comment. Requires that server's `cors:origins` config
+ * include this consumer's own origin (see `@rapidrest/service-core`'s `Server.js` CORS middleware,
+ * which only reflects `access-control-allow-credentials` for an explicitly allow-listed origin - the
+ * default "allow every origin" behavior when `cors:origins` is unset does NOT carry credentials) and
+ * that whatever sets the `jwt` cookie issues it with `SameSite=None; Secure` - a same-origin deployment
+ * never needed either, and this function alone does not make a cross-origin deployment secure or
+ * functional on its own.
+ */
+export declare function configureApiBaseUrl(baseUrl: string): void;
+/**
+ * The origin `configureApiBaseUrl()` set - `""` (same origin) when it never was. For a caller that talks to the
+ * RapidMX server some way `apiFetch()` can't, such as the push WebSocket, which must go to the same origin.
+ */
+export declare function apiOrigin(): string;
+/**
+ * The full URL for an `@ApiRoute`-declared `path` (e.g. `/mail/attachments/a1/content`) - the `/api`
+ * prefix plus whatever origin `configureApiBaseUrl()` set (a same-origin relative `/api/...` path when
+ * it was never called). Every call site that can't go through `apiFetch()` - a raw-bytes upload, a
+ * non-JSON download, or a plain URL handed to an `<a href>`/`<img src>` - must build its URL here rather
+ * than hard-coding `/api...`, or it silently ignores a configured cross-origin base URL. A raw `fetch()`
+ * built on this should also pass `credentials: "include"` so a cross-origin call still carries the `jwt`
+ * cookie (harmless for a same-origin one).
+ */
+export declare function apiUrl(path: string): string;
+/**
+ * `headers` as a `Headers` with the CSRF double-submit header added, for a mutating request that is built without `apiFetch()` - an upload of a
+ * file's own bytes, which cannot go through `apiFetch()` because that always sends JSON. Without it the server refuses the request as "missing a valid
+ * CSRF token". `method` defaults to `POST`; a safe method or no cookie leaves the headers as they were, exactly as `apiFetch()` does.
+ */
+export declare function withCsrfHeader(headers: Record<string, string>, method?: string): Headers;
+/**
+ * `fetch()` against the RapidMX server's API - same-origin unless `configureApiBaseUrl()` has been
+ * called, in which case this also switches to `credentials: "include"` so the configured cross-origin
+ * call still carries the `jwt` cookie (a plain relative fetch never needs this - `credentials:
+ * "same-origin"`, fetch's own default, already attaches it). `path` is the route as declared by
+ * `@ApiRoute` (e.g. `/mail/mailboxes`) — the `/api` prefix that decorator always adds is applied here,
+ * in one place, rather than repeated at every call site.
+ */
+export declare function apiFetch<T = unknown>(path: string, init?: RequestInit): Promise<T>;
+/**
+ * `fetch()` against auth-server's API — a *different* origin than this app, unlike `apiFetch()` above. Used
+ * only for the handful of actions that must be issued by auth-server itself (e.g. admin impersonation, which
+ * needs to mint a token with the target user's real roles/scopes the way auth-server's own sign-in does —
+ * see `.claude/NOTES.md`).
+ *
+ * Requires `credentials: "include"` so the browser both attaches this app's own `jwt` cookie to the request
+ * and accepts whatever `Set-Cookie` auth-server's response carries back. This only actually works when
+ * auth-server and this app are deployed under a shared parent cookie domain (e.g. `Domain=.example.com`) —
+ * 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.
+ */
+export declare function authApiFetch<T = unknown>(authServerUrl: string, path: string, init?: RequestInit): Promise<T>;
+/**
+ * Registers the one function that hears about every `401` this server's API (`apiFetch()`, not auth-server's) answers - the
+ * signed-in session has ended or expired. It only observes: the request still rejects with the same `ApiRequestError`, so
+ * a caller's own handling is unchanged. The app frame uses it to say "Your session expired" once, whichever request noticed
+ * first (a background refresh included). Pass `undefined` to remove it. A throwing observer never affects the request.
+ */
+export declare function setApiUnauthorizedObserver(observer: ((error: ApiRequestError) => void) | undefined): void;
+/**
+ * The low-level shape both the default global client (`apiFetch()`, driven by `configureApiBaseUrl()` and the
+ * `jwt` cookie) and an explicit `createApiClient()` instance expose - so a `mailApi.ts`-style module can be
+ * written once against this interface and used from either. There is deliberately no `authFetch`/cross-origin
+ * counterpart here: `authApiFetch()`'s `authServerUrl` is already explicit per call, so it doesn't need this
+ * abstraction the way the single implicit `apiBaseUrl` global does.
+ */
+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>;
+    /**
+     * 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()`
+     * (or across other `ApiClient` instances).
+     */
+    setUnauthorizedObserver(observer: ((error: ApiRequestError) => void) | undefined): void;
+}
+/** `createApiClient()`'s options. */
+export interface CreateApiClientOptions {
+    /** This client's origin, e.g. `"https://mail.example.com"` - always used, never the global
+     * `configureApiBaseUrl()` value. A trailing slash is stripped, matching `configureApiBaseUrl()`. */
+    baseUrl: string;
+    /**
+     * Called fresh before every single request this client makes - never cached or reused across calls, so a
+     * caller can transparently rotate/refresh the underlying session token between requests (e.g. a
+     * background refresh keyed on this one account) without this client needing to know anything about
+     * refresh logic itself. Its resolved value is sent as `Authorization: jwt <token>` - the same header
+     * format `JWTStrategy` already accepts server-side alongside the `jwt` cookie - never `credentials:
+     * "include"`, since a native multi-account app has no relevant cookie jar for a given account's origin.
+     * A rejection here rejects the request itself (the underlying `fetch()` is never called).
+     */
+    getAccessToken: () => Promise<string>;
+}
+/**
+ * Builds an explicit-context `ApiClient`: everything `apiFetch()` does, but always against `baseUrl` (never
+ * the `configureApiBaseUrl()` global) and always authenticated with a bearer token from `getAccessToken()`
+ * (never the `jwt` cookie / `credentials: "include"`). ADDITIVE to the existing global-config mode -
+ * `apiFetch()`/`authApiFetch()`/`configureApiBaseUrl()` are untouched and keep working exactly as before for
+ * every existing caller; this is for a consumer (the Tauri multi-account client) that needs several fully
+ * independent origin/session contexts open at once, which the single module-level `apiBaseUrl` global can't
+ * represent.
+ *
+ * Distinct instances never share state: each closes over its own `baseUrl`, `getAccessToken` and unauthorized
+ * observer, so two accounts' clients never cross-talk even when both are live in the same process.
+ *
+ * **401 handling is per-instance, not global.** The existing `setApiUnauthorizedObserver()` is one process-wide
+ * "you're signed out" signal, correct for a single-session app (one browser tab, one Electron window - there is
+ * only ever one session to lose). A multi-account app has no single account whose 401 means "the app" is
+ * unauthorized, so an `ApiClient` from `createApiClient()` does NOT invoke the global observer at all; instead
+ * each instance has its own `setUnauthorizedObserver()` a caller can register per account (e.g. to mark that
+ * one account's tab as needing re-authentication without touching the others).
+ */
+export declare function createApiClient(options: CreateApiClientOptions): ApiClient;
+/**
+ * Routes a request to `client.fetch()` when `client` is given, else to the default global `apiFetch()` - the
+ * one call every REST client module (`mailApi.ts` etc.) uses to add optional explicit-`ApiClient` support to
+ * each of its exported functions with minimal churn: give the function a trailing `client?: ApiClient`
+ * parameter (so every existing call site, which never passes one, is unaffected - `undefined` here means
+ * exactly what calling `apiFetch()` directly always meant), and swap its `apiFetch(...)` call for
+ * `withClient(client, ...)`. A function that calls another exported function of the same module internally
+ * (e.g. `mailApi.ts`'s `grantMailboxAccess()` calling `getMailboxAcl()`) threads its own `client` through
+ * 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>;

package/dist/lib/util/api.js

@@ -0,0 +1,251 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Minimal client-side helper shared by every app in this project: a `fetch` wrapper that talks to the
+ * same-origin RapidMX API. There is no client router or HTTP client shipped by `@rapidrest/react`, so this
+ * is deliberately small and framework-free.
+ *
+ * This service never issues its own JWTs — identity comes entirely from a separate `auth-server` deployment
+ * (see `.claude/NOTES.md`). Authentication rides along via the `jwt` HttpOnly cookie that auth-server sets on
+ * sign-in — the browser attaches it automatically to every same-origin `fetch()` call (the default
+ * `credentials: "same-origin"` mode), and this server's `JWTStrategy` accepts it as a credential for every
+ * authenticated request, not just SSR page loads. There is no local elevation/step-up flow here (unlike
+ * auth-server's own `api.ts`, which this is a trimmed sibling of): a request to an elevation-gated endpoint
+ * (`@RequiresElevation()` on the server) made with a non-elevated token fails with an `ApiRequestError` of
+ * status 403 and code `"api-104"`, and it is up to the caller to send the browser to auth-server's
+ * `/auth/elevate?return_to=...` page, which returns it to `return_to` once the user has confirmed their identity
+ * (the admin console does exactly that - see `AdminShell` in `@rapidmx/web-client`). Code `"api-103"` is a
+ * different 403 - the caller lacks a required role, and elevating won't help.
+ */
+export class ApiRequestError extends Error {
+    constructor(message, status, code, details) {
+        super(message);
+        this.name = "ApiRequestError";
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+/**
+ * Absolute origin `apiFetch()` targets instead of a same-origin relative path - unset (`""`, the
+ * default) everywhere this library has run until now (the SSR web/admin apps, always served from the
+ * same origin as the API they call). Set once via `configureApiBaseUrl()` by a consumer that genuinely
+ * runs on a *different* origin than the API - e.g. the Electron desktop client, whose renderer has no
+ * "same origin as the server" to rely on the way a browser tab loaded from that server does.
+ */
+let apiBaseUrl = "";
+/**
+ * Points `apiFetch()` at `baseUrl` (e.g. `"https://mail.example.com"`) instead of the default
+ * same-origin relative path. Only needed by a consumer whose own origin genuinely differs from the
+ * RapidMX server's - see `apiBaseUrl`'s own doc comment. Requires that server's `cors:origins` config
+ * include this consumer's own origin (see `@rapidrest/service-core`'s `Server.js` CORS middleware,
+ * which only reflects `access-control-allow-credentials` for an explicitly allow-listed origin - the
+ * default "allow every origin" behavior when `cors:origins` is unset does NOT carry credentials) and
+ * that whatever sets the `jwt` cookie issues it with `SameSite=None; Secure` - a same-origin deployment
+ * never needed either, and this function alone does not make a cross-origin deployment secure or
+ * functional on its own.
+ */
+export function configureApiBaseUrl(baseUrl) {
+    apiBaseUrl = baseUrl.replace(/\/$/, "");
+}
+/**
+ * The origin `configureApiBaseUrl()` set - `""` (same origin) when it never was. For a caller that talks to the
+ * RapidMX server some way `apiFetch()` can't, such as the push WebSocket, which must go to the same origin.
+ */
+export function apiOrigin() {
+    return apiBaseUrl;
+}
+/**
+ * The full URL for an `@ApiRoute`-declared `path` (e.g. `/mail/attachments/a1/content`) - the `/api`
+ * prefix plus whatever origin `configureApiBaseUrl()` set (a same-origin relative `/api/...` path when
+ * it was never called). Every call site that can't go through `apiFetch()` - a raw-bytes upload, a
+ * non-JSON download, or a plain URL handed to an `<a href>`/`<img src>` - must build its URL here rather
+ * than hard-coding `/api...`, or it silently ignores a configured cross-origin base URL. A raw `fetch()`
+ * built on this should also pass `credentials: "include"` so a cross-origin call still carries the `jwt`
+ * cookie (harmless for a same-origin one).
+ */
+export function apiUrl(path) {
+    return `${apiBaseUrl}/api${path}`;
+}
+/**
+ * Mirrors `@rapidrest/service-core`'s `DEFAULT_CSRF_COOKIE_NAME`/`DEFAULT_CSRF_HEADER_NAME` — kept as
+ * local literals since this package has no dependency on that one.
+ */
+const CSRF_COOKIE_NAME = "csrf";
+const CSRF_HEADER_NAME = "x-csrf-token";
+const CSRF_SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+/**
+ * Reads the CSRF double-submit cookie a `jwt`-cookie-issuing server sets (see `@rapidrest/auth`'s
+ * `CsrfUtils`) directly off `document.cookie`. That cookie is deliberately host-only and non-`HttpOnly`
+ * — see `@rapidrest/service-core`'s `src/http/csrf/csrf.ts` for the full rationale, in particular why a
+ * *cross-origin* call (`authApiFetch()` below) can never find one here: a cookie set by auth-server's
+ * host is never present in this app's own `document.cookie`, by design — that's what makes the cookie
+ * host-only in the first place, and it's why `authApiFetch()`'s CSRF protection has to come from the
+ * server checking its Origin allow-list instead (see its own doc comment).
+ */
+function readCsrfCookie() {
+    if (typeof document === "undefined") {
+        return undefined;
+    }
+    for (const part of document.cookie.split("; ")) {
+        const idx = part.indexOf("=");
+        if (idx > 0 && part.slice(0, idx) === CSRF_COOKIE_NAME) {
+            return part.slice(idx + 1);
+        }
+    }
+    return undefined;
+}
+/**
+ * Echoes the CSRF double-submit cookie back as a header on `headers`, for a mutating request that doesn't
+ * already carry one — the browser-side half of the double-submit check `@rapidrest/service-core`'s
+ * `RouteUtils.checkCsrf()` enforces server-side. A safe method, a caller-supplied header already present,
+ * or simply no cookie yet (e.g. this page's very first request) all leave `headers` untouched — the
+ * server itself never requires this for any of those cases.
+ */
+function applyCsrfHeader(headers, method) {
+    const m = (method ?? "GET").toUpperCase();
+    if (CSRF_SAFE_METHODS.has(m) || headers.has(CSRF_HEADER_NAME)) {
+        return;
+    }
+    const token = readCsrfCookie();
+    if (token) {
+        headers.set(CSRF_HEADER_NAME, token);
+    }
+}
+/**
+ * `headers` as a `Headers` with the CSRF double-submit header added, for a mutating request that is built without `apiFetch()` - an upload of a
+ * file's own bytes, which cannot go through `apiFetch()` because that always sends JSON. Without it the server refuses the request as "missing a valid
+ * CSRF token". `method` defaults to `POST`; a safe method or no cookie leaves the headers as they were, exactly as `apiFetch()` does.
+ */
+export function withCsrfHeader(headers, method = "POST") {
+    const result = new Headers(headers);
+    applyCsrfHeader(result, method);
+    return result;
+}
+/**
+ * `fetch()` against the RapidMX server's API - same-origin unless `configureApiBaseUrl()` has been
+ * called, in which case this also switches to `credentials: "include"` so the configured cross-origin
+ * call still carries the `jwt` cookie (a plain relative fetch never needs this - `credentials:
+ * "same-origin"`, fetch's own default, already attaches it). `path` is the route as declared by
+ * `@ApiRoute` (e.g. `/mail/mailboxes`) — the `/api` prefix that decorator always adds is applied here,
+ * in one place, rather than repeated at every call site.
+ */
+export async function apiFetch(path, init = {}) {
+    const headers = new Headers(init.headers);
+    headers.set("Content-Type", "application/json");
+    applyCsrfHeader(headers, init.method);
+    const credentials = apiBaseUrl ? "include" : init.credentials;
+    const res = await fetch(apiUrl(path), { ...init, headers, credentials });
+    return decodeApiResponse(res, (error) => unauthorizedObserver?.(error));
+}
+/**
+ * `fetch()` against auth-server's API — a *different* origin than this app, unlike `apiFetch()` above. Used
+ * only for the handful of actions that must be issued by auth-server itself (e.g. admin impersonation, which
+ * needs to mint a token with the target user's real roles/scopes the way auth-server's own sign-in does —
+ * see `.claude/NOTES.md`).
+ *
+ * Requires `credentials: "include"` so the browser both attaches this app's own `jwt` cookie to the request
+ * and accepts whatever `Set-Cookie` auth-server's response carries back. This only actually works when
+ * auth-server and this app are deployed under a shared parent cookie domain (e.g. `Domain=.example.com`) —
+ * 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.
+ */
+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);
+}
+let unauthorizedObserver;
+/**
+ * Registers the one function that hears about every `401` this server's API (`apiFetch()`, not auth-server's) answers - the
+ * signed-in session has ended or expired. It only observes: the request still rejects with the same `ApiRequestError`, so
+ * a caller's own handling is unchanged. The app frame uses it to say "Your session expired" once, whichever request noticed
+ * first (a background refresh included). Pass `undefined` to remove it. A throwing observer never affects the request.
+ */
+export function setApiUnauthorizedObserver(observer) {
+    unauthorizedObserver = observer;
+}
+/**
+ * `onUnauthorized`, when given, is invoked (never awaited) for a `401` response only - `apiFetch()` passes one
+ * that forwards to whatever `setApiUnauthorizedObserver()` last registered; `authApiFetch()` and a plain
+ * `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) {
+    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);
+        if (res.status === 401 && onUnauthorized) {
+            try {
+                onUnauthorized(error);
+            }
+            catch {
+                // An observer's failure must not change what the caller sees.
+            }
+        }
+        throw error;
+    }
+    return body;
+}
+/**
+ * Builds an explicit-context `ApiClient`: everything `apiFetch()` does, but always against `baseUrl` (never
+ * the `configureApiBaseUrl()` global) and always authenticated with a bearer token from `getAccessToken()`
+ * (never the `jwt` cookie / `credentials: "include"`). ADDITIVE to the existing global-config mode -
+ * `apiFetch()`/`authApiFetch()`/`configureApiBaseUrl()` are untouched and keep working exactly as before for
+ * every existing caller; this is for a consumer (the Tauri multi-account client) that needs several fully
+ * independent origin/session contexts open at once, which the single module-level `apiBaseUrl` global can't
+ * represent.
+ *
+ * Distinct instances never share state: each closes over its own `baseUrl`, `getAccessToken` and unauthorized
+ * observer, so two accounts' clients never cross-talk even when both are live in the same process.
+ *
+ * **401 handling is per-instance, not global.** The existing `setApiUnauthorizedObserver()` is one process-wide
+ * "you're signed out" signal, correct for a single-session app (one browser tab, one Electron window - there is
+ * only ever one session to lose). A multi-account app has no single account whose 401 means "the app" is
+ * unauthorized, so an `ApiClient` from `createApiClient()` does NOT invoke the global observer at all; instead
+ * each instance has its own `setUnauthorizedObserver()` a caller can register per account (e.g. to mark that
+ * one account's tab as needing re-authentication without touching the others).
+ */
+export function createApiClient(options) {
+    const baseUrl = options.baseUrl.replace(/\/$/, "");
+    const { getAccessToken } = options;
+    let unauthorizedObserver;
+    async function clientFetch(path, init = {}) {
+        const headers = new Headers(init.headers);
+        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: clientFetch,
+        setUnauthorizedObserver(observer) {
+            unauthorizedObserver = observer;
+        },
+    };
+}
+/**
+ * Routes a request to `client.fetch()` when `client` is given, else to the default global `apiFetch()` - the
+ * one call every REST client module (`mailApi.ts` etc.) uses to add optional explicit-`ApiClient` support to
+ * each of its exported functions with minimal churn: give the function a trailing `client?: ApiClient`
+ * parameter (so every existing call site, which never passes one, is unaffected - `undefined` here means
+ * exactly what calling `apiFetch()` directly always meant), and swap its `apiFetch(...)` call for
+ * `withClient(client, ...)`. A function that calls another exported function of the same module internally
+ * (e.g. `mailApi.ts`'s `grantMailboxAccess()` calling `getMailboxAcl()`) threads its own `client` through
+ * that call too, so a whole call chain stays pinned to one account.
+ */
+export function withClient(client, path, init) {
+    return client ? client.fetch(path, init) : apiFetch(path, init);
+}

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

@@ -0,0 +1,7 @@
+import { ApiClient } from "./api.js";
+/** The active account's `ApiClient`, or `undefined` when nothing above the caller provided one — see this
+ * file's own doc comment. */
+export declare const ApiClientContext: import("react").Context<ApiClient | undefined>;
+/** The nearest `ApiClientContext.Provider`'s value, or `undefined` when there is none — the same `client`
+ * every converted REST function's own optional trailing parameter accepts. */
+export declare function useApiClient(): ApiClient | undefined;

package/dist/lib/util/apiClientContext.js

@@ -0,0 +1,32 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Lets a deeply-nested component reach "the active account's `ApiClient`" without prop-drilling it through
+ * every layer in between — the missing piece `createApiClient()` (see `api.ts`) left open: that function
+ * gives a host app (e.g. the native, multi-account `tauri-client`) a way to *build* a per-account client, but
+ * nothing let a component *read* one back out short of threading it through every prop list by hand.
+ *
+ * Same shape as `overlays/overlayStack.ts`'s `OverlayDepthContext` — a bare `createContext()` plus a `useX()`
+ * reader, no dedicated `<Provider>` wrapper component, so a host app wraps its tree in `ApiClientContext.Provider`
+ * directly (e.g. `<ApiClientContext.Provider value={client}>{children}</ApiClientContext.Provider>`) exactly the
+ * way `Modal.tsx`/`Drawer.tsx` already do for `OverlayDepthContext`.
+ *
+ * The default value is `undefined`, meaning "no override" — every existing consumer (the SSR web/admin apps,
+ * the Electron client) renders with no `ApiClientContext.Provider` anywhere above it, so `useApiClient()` there
+ * always returns `undefined`, which is exactly what every converted REST function's own `client?: ApiClient`
+ * parameter already treats as "use the default global cookie-based `apiFetch()` path" (see `withClient()`'s doc
+ * comment in `api.ts`). A component under a `tauri-client`-style provider instead gets that account's own
+ * `ApiClient` back, and can pass it straight through as the trailing `client` argument of any converted
+ * function with no adapter needed: `const client = useApiClient(); await listMessages(params, client);`.
+ */
+import { createContext, useContext } from "react";
+/** The active account's `ApiClient`, or `undefined` when nothing above the caller provided one — see this
+ * file's own doc comment. */
+export const ApiClientContext = createContext(undefined);
+/** The nearest `ApiClientContext.Provider`'s value, or `undefined` when there is none — the same `client`
+ * every converted REST function's own optional trailing parameter accepts. */
+export function useApiClient() {
+    return useContext(ApiClientContext);
+}

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

@@ -0,0 +1,32 @@
+/**
+ * The pagination query-string convention shared by every `*Api.ts` wrapper (`mailApi.ts`,
+ * `contactsApi.ts`, `tasksApi.ts`, `calendarApi.ts`) — split out of `mailApi.ts` once more than one of
+ * them needed it, rather than each reimplementing it or importing it from `mailApi.ts` for no reason
+ * other than it happening to live there first.
+ */
+export interface ListParams {
+    page?: number;
+    limit?: number;
+}
+/**
+ * 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;
+/**
+ * Optional paging/scope params for the async-request list endpoints (`listExportRequests()`,
+ * `listImportRequests()`, `listErasureRequests()`, `listMatterExportRequests()`,
+ * `listAccessRequests()`). Server contract: newest first, `limit` capped at 500, `page` zero-based,
+ * `matterId` honored only by the Matter-scoped (escrow) endpoints.
+ */
+export interface RequestListParams extends ListParams {
+    /** Restricts the list to one Matter - only meaningful for Matter-scoped request lists. */
+    matterId?: string;
+}
+/**
+ * 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
+ * with no params at all, so a caller passing nothing keeps that exact request). Returns `""` when no
+ * param is set.
+ */
+export declare function buildRequestListQuery(params?: RequestListParams): string;

package/dist/lib/util/apiQuery.js

@@ -0,0 +1,42 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The pagination query-string convention shared by every `*Api.ts` wrapper (`mailApi.ts`,
+ * `contactsApi.ts`, `tasksApi.ts`, `calendarApi.ts`) — split out of `mailApi.ts` once more than one of
+ * them needed it, rather than each reimplementing it or importing it from `mailApi.ts` for no reason
+ * other than it happening to live there first.
+ */
+const DEFAULT_PAGE_SIZE = 25;
+/**
+ * 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 function buildQuery(params, extra = {}) {
+    const parts = [`limit=${params.limit ?? DEFAULT_PAGE_SIZE}`, `page=${params.page ?? 0}`];
+    for (const [key, value] of Object.entries(extra)) {
+        parts.push(`${key}=${encodeURIComponent(value)}`);
+    }
+    return parts.join("&");
+}
+/**
+ * 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
+ * with no params at all, so a caller passing nothing keeps that exact request). Returns `""` when no
+ * param is set.
+ */
+export function buildRequestListQuery(params = {}) {
+    const query = new URLSearchParams();
+    if (params.limit !== undefined) {
+        query.set("limit", String(params.limit));
+    }
+    if (params.page !== undefined) {
+        query.set("page", String(params.page));
+    }
+    if (params.matterId) {
+        query.set("matterId", params.matterId);
+    }
+    const encoded = query.toString();
+    return encoded ? `?${encoded}` : "";
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Copies `text` to the system clipboard and reports whether it worked - never rejects, so a caller can
+ * simply show "Copied" or "Couldn't copy". Tries `navigator.clipboard.writeText()` first and, when that is
+ * unavailable or rejects, the hidden-textarea `execCommand("copy")` fallback. Must run from a user gesture
+ * (a click handler) for either route to be allowed.
+ */
+export declare function copyTextToClipboard(text: string): Promise<boolean>;

package/dist/lib/util/clipboard.js

@@ -0,0 +1,56 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The legacy copy path: selects `text` in an off-screen, read-only `<textarea>` and runs
+ * `document.execCommand("copy")`. Used where the async Clipboard API is missing (an insecure `http:` origin,
+ * an older browser) or refuses (permission denied, the document isn't focused). Puts focus back where it was,
+ * since selecting the textarea moves it. `false` when there is no DOM or the browser declines the command.
+ */
+function copyWithExecCommand(text) {
+    if (typeof document === "undefined") {
+        return false;
+    }
+    const previouslyFocused = document.activeElement;
+    const textarea = document.createElement("textarea");
+    textarea.value = text;
+    textarea.setAttribute("readonly", "");
+    textarea.setAttribute("aria-hidden", "true");
+    textarea.style.cssText = "position:fixed;top:0;left:0;width:1px;height:1px;padding:0;border:0;opacity:0;pointer-events:none";
+    document.body.appendChild(textarea);
+    let copied = false;
+    try {
+        textarea.select();
+        textarea.setSelectionRange(0, text.length);
+        copied = typeof document.execCommand === "function" && document.execCommand("copy");
+    }
+    catch {
+        copied = false;
+    }
+    finally {
+        textarea.remove();
+        if (previouslyFocused instanceof HTMLElement) {
+            previouslyFocused.focus();
+        }
+    }
+    return copied;
+}
+/**
+ * Copies `text` to the system clipboard and reports whether it worked - never rejects, so a caller can
+ * simply show "Copied" or "Couldn't copy". Tries `navigator.clipboard.writeText()` first and, when that is
+ * unavailable or rejects, the hidden-textarea `execCommand("copy")` fallback. Must run from a user gesture
+ * (a click handler) for either route to be allowed.
+ */
+export async function copyTextToClipboard(text) {
+    try {
+        if (typeof navigator !== "undefined" && typeof navigator.clipboard?.writeText === "function") {
+            await navigator.clipboard.writeText(text);
+            return true;
+        }
+    }
+    catch {
+        // Denied or unavailable right now - the legacy path below may still succeed.
+    }
+    return copyWithExecCommand(text);
+}

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

@@ -0,0 +1,6 @@
+/** Shared by every form with a `<input type="datetime-local">` bound to a server-side ISO instant
+ * (originally `EventModal.tsx`'s own private helper, split out once the Settings Auto-Reply page needed
+ * the identical conversion — same "extract once a second consumer needs it" precedent as `apiQuery.ts`). */
+/** `<input type="datetime-local">` reads/writes local time with no timezone suffix — `new Date(str)`
+ * parses that as the browser's own local time, matching what the picker visually showed the user. */
+export declare function toDatetimeLocal(iso: string): string;

package/dist/lib/util/dateInput.js

@@ -0,0 +1,14 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** Shared by every form with a `<input type="datetime-local">` bound to a server-side ISO instant
+ * (originally `EventModal.tsx`'s own private helper, split out once the Settings Auto-Reply page needed
+ * the identical conversion — same "extract once a second consumer needs it" precedent as `apiQuery.ts`). */
+/** `<input type="datetime-local">` reads/writes local time with no timezone suffix — `new Date(str)`
+ * parses that as the browser's own local time, matching what the picker visually showed the user. */
+export function toDatetimeLocal(iso) {
+    const d = new Date(iso);
+    const local = new Date(d.getTime() - d.getTimezoneOffset() * 60000);
+    return local.toISOString().slice(0, 16);
+}

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

@@ -0,0 +1,12 @@
+/** The time zone a mailbox has when nothing better is known - the server's own default. */
+export declare const DEFAULT_TIME_ZONE = "UTC";
+/**
+ * The IANA time zone of the device this is running on (`"America/Los_Angeles"`), as the browser reports it, or `"UTC"` where it
+ * can't say (server-side rendering, an old engine). What a new mailbox, and a settings form with nothing chosen yet, start with.
+ */
+export declare function deviceTimeZone(): string;
+/**
+ * Every time zone the browser can name, for a picker: `Intl.supportedValuesOf("timeZone")` where there is one (it leaves out `UTC`,
+ * which is added), else just `extra` - the zones the caller already holds, such as a mailbox's current one.
+ */
+export declare function timeZoneOptions(...extra: string[]): string[];