@rapidmx/web-client 0.20.0 → 0.22.0

package/dist/lib/admin/transportRulesApi.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `TransportRule` CRUD route (`BaseTransportRuleRoute`) —
+ * trusted-role-only, org-wide (evaluated once per SMTP transaction, before per-mailbox fan-out). No
+ * uid-derivation on create (unlike `Domain`/`Mailbox`/`DistributionList`) — a transport rule has no
+ * natural address of its own.
+ */
+import { ApiClient } from "../util/api.js";
+import { ListParams } from "../util/apiQuery.js";
+export type { ListParams };
+export type TransportRuleActionType = "reject" | "quarantine" | "add_header" | "add_recipient";
+export interface TransportRuleAction {
+    type: TransportRuleActionType;
+    /** Required for `add_header`. */
+    headerName?: string;
+    /** Required for `add_header`. */
+    headerValue?: string;
+    /** Required for `add_recipient`. */
+    recipientAddress?: string;
+}
+export interface TransportRuleConditions {
+    fromContains?: string[];
+    subjectContains?: string[];
+    bodyContains?: string[];
+    recipientContains?: string[];
+    anyRecipientExternal?: boolean;
+    hasAttachment?: boolean;
+    attachmentNameContains?: string[];
+}
+export interface TransportRule {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    name: string;
+    enabled: boolean;
+    sequence: number;
+    stopProcessingRules: boolean;
+    conditions: TransportRuleConditions;
+    actions: TransportRuleAction[];
+}
+/** `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. */
+export declare function listTransportRules(params?: ListParams, client?: ApiClient): Promise<TransportRule[]>;
+export declare function getTransportRule(uid: string, client?: ApiClient): Promise<TransportRule>;
+export interface CreateTransportRuleInput {
+    name: string;
+    enabled?: boolean;
+    sequence?: number;
+    stopProcessingRules?: boolean;
+    conditions?: TransportRuleConditions;
+    actions?: TransportRuleAction[];
+}
+export declare function createTransportRule(input: CreateTransportRuleInput, client?: ApiClient): Promise<TransportRule>;
+export interface UpdateTransportRuleInput {
+    uid: string;
+    version: number;
+    name?: string;
+    enabled?: boolean;
+    sequence?: number;
+    stopProcessingRules?: boolean;
+    conditions?: TransportRuleConditions;
+    actions?: TransportRuleAction[];
+}
+export declare function updateTransportRule(input: UpdateTransportRuleInput, client?: ApiClient): Promise<TransportRule>;
+export declare function deleteTransportRule(uid: string, version: number, client?: ApiClient): Promise<void>;

package/dist/lib/admin/transportRulesApi.js

@@ -0,0 +1,43 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `TransportRule` CRUD route (`BaseTransportRuleRoute`) —
+ * trusted-role-only, org-wide (evaluated once per SMTP transaction, before per-mailbox fan-out). No
+ * uid-derivation on create (unlike `Domain`/`Mailbox`/`DistributionList`) — a transport rule has no
+ * natural address of its own.
+ */
+import { withClient } from "../util/api.js";
+import { 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. */
+export function listTransportRules(params = {}, client) {
+    return withClient(client, `/mail/transport-rules?${buildQuery(params)}`);
+}
+export function getTransportRule(uid, client) {
+    return withClient(client, `/mail/transport-rules/${encodeURIComponent(uid)}`);
+}
+export function createTransportRule(input, client) {
+    return withClient(client, "/mail/transport-rules", {
+        method: "POST",
+        body: JSON.stringify({
+            enabled: true,
+            sequence: 0,
+            stopProcessingRules: false,
+            conditions: {},
+            actions: [],
+            ...input,
+        }),
+    });
+}
+export function updateTransportRule(input, client) {
+    return withClient(client, `/mail/transport-rules/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+export function deleteTransportRule(uid, version, client) {
+    return withClient(client, `/mail/transport-rules/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}

package/dist/lib/appearance/preferencesApi.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Typed client for the signed-in user's appearance preferences - their colour scheme, theme colours and app background
+ * (`@rapidmx/restapi`'s `/mail/preferences/appearance` routes):
+ *
+ * - `GET  /mail/preferences/appearance` reads the `AppearancePreferences` object (never a 404: a user with none gets the defaults). `PUT`
+ * the same path **merges** a partial `AppearanceUpdate` into it (each colour and each background field on its own; `null` clears a
+ * colour) and answers with the saved object - so a client sends what changed (`diffAppearance()`), never the whole thing.
+ * - `POST /mail/preferences/appearance/background` stores the request body (a raw image, `Content-Type` = the file's own) as the
+ * background and answers with the updated preferences; `DELETE` the same path removes it.
+ * - `GET  /mail/preferences/appearance/background/:version` is the image itself - immutable per version, so an `<img>`/CSS `url()`
+ * pointing at `appearanceBackgroundUrl()` is cached for good.
+ * - A change is also pushed to the user's other tabs and devices as `{ type: /^AppearancePreferences/, action: "update", data }` on
+ * the user's own uid channel - `parseAppearanceEvent()` reads it.
+ *
+ * Everything that comes from outside - the response, a push event, the page's server-rendered props, `localStorage` - goes through
+ * `normalizeAppearance()`, which keeps only well-formed values (so a stale or hostile value can never reach a CSS declaration).
+ */
+import { ApiClient } from "../util/api.js";
+export type AppearanceMode = "system" | "light" | "dark";
+export type BackgroundKind = "none" | "color" | "image";
+export type BackgroundFit = "cover" | "contain" | "tile";
+/** Theme colours, each `#rrggbb` and each optional: an unset one keeps the app's (or the deployment's branding's) own. */
+export interface AppearanceColors {
+    primary?: string;
+    accent?: string;
+    surface?: string;
+    text?: string;
+}
+export interface AppearanceBackground {
+    kind: BackgroundKind;
+    /** `kind: "color"`: the colour. `kind: "image"`: the colour shown behind the image (letterboxing, while it loads). `#rrggbb`. */
+    color?: string;
+    /** Which stored image `kind: "image"` shows - part of its URL (`appearanceBackgroundUrl()`), so a new upload is a new URL. */
+    imageVersion?: string | number;
+    /** How much of the scheme's surface colour is laid over the image, `0` to `BACKGROUND_DIM_MAX`. */
+    dim: number;
+    /** Blur radius in CSS pixels, `0` to `BACKGROUND_BLUR_MAX`. */
+    blur: number;
+    fit: BackgroundFit;
+}
+export interface AppearancePreferences {
+    version: 1;
+    mode: AppearanceMode;
+    colors?: AppearanceColors;
+    background?: AppearanceBackground;
+    /** When the server last stored these. Opaque to the client (compared for equality, never parsed). */
+    updatedAt?: string | number;
+}
+/** Preferences without the server's own timestamp. */
+export type AppearanceInput = Omit<AppearancePreferences, "updatedAt">;
+/**
+ * What `PUT` takes, a partial that the server merges into what is stored: `mode`; `colors` (a colour is set by its `#rrggbb` and cleared by
+ * `null`, and `colors: null` clears all four); `background` (any of its fields, merged one by one - `color: null` clears the colour). It cannot
+ * name an `imageVersion` (uploading is what makes one), and `kind: "image"` needs an image already uploaded.
+ */
+export interface AppearanceUpdate {
+    version?: 1;
+    mode?: AppearanceMode;
+    colors?: Partial<Record<ColorKey, string | null>> | null;
+    background?: Partial<Omit<AppearanceBackground, "color" | "imageVersion">> & {
+        color?: string | null;
+    };
+}
+export declare const APPEARANCE_MODES: readonly AppearanceMode[];
+export declare const BACKGROUND_KINDS: readonly BackgroundKind[];
+export declare const BACKGROUND_FITS: readonly BackgroundFit[];
+export declare const COLOR_KEYS: readonly ["primary", "accent", "surface", "text"];
+export type ColorKey = (typeof COLOR_KEYS)[number];
+/** The largest dim the server accepts - beyond it the picture is not worth having. */
+export declare const BACKGROUND_DIM_MAX = 0.8;
+/** The largest blur, in CSS pixels. */
+export declare const BACKGROUND_BLUR_MAX = 20;
+/** The image types a background may be - raster only: an SVG is a document that can carry script. */
+export declare const BACKGROUND_IMAGE_TYPES: readonly string[];
+/** The largest background image, in bytes. */
+export declare const BACKGROUND_MAX_BYTES: number;
+/** The preferences a user who never chose anything has. */
+export declare const DEFAULT_APPEARANCE: AppearanceInput;
+/** The starting background when the user first picks a kind: a light dim and no blur, covering the whole app. */
+export declare const DEFAULT_BACKGROUND: AppearanceBackground;
+/**
+ * The well-formed part of `value` as `AppearancePreferences`, or `undefined` when it is not preferences at all (not an object, or not
+ * `version: 1`). Unknown keys are dropped, colours must be `#rrggbb` (lower-cased), numbers are clamped into their range, and an enum
+ * that isn't one of its values falls back to the default - so what comes out is always safe to turn into CSS.
+ */
+export declare function normalizeAppearance(value: unknown): AppearancePreferences | undefined;
+/**
+ * The reason `file` can't be a background, worded for the person choosing it, or `undefined` when it can. Checked before anything is
+ * uploaded (the server checks again). Takes anything with a `type` and a `size`, so it is testable without a real `File`.
+ */
+export declare function validateBackgroundFile(file: {
+    type: string;
+    size: number;
+}): string | undefined;
+/**
+ * The `PUT` that takes what the server has (`server`, `undefined` for nothing yet) to `next`: only what differs, in the merge form the
+ * server takes - a colour that is gone is `null`, all of them gone is `colors: null`, and a background that is gone is `kind: "none"`
+ * (the server refuses `background: null`). `undefined` when there is nothing to send. The image is never named: its `imageVersion` is
+ * the server's to choose, and `kind: "image"` is only sent once `next` shows the very image the server holds - an image that is still
+ * uploading (a version the server doesn't know) can't be switched to yet.
+ */
+export declare function diffAppearance(server: AppearancePreferences | undefined, next: AppearanceInput): AppearanceUpdate | undefined;
+/** `true` when nothing meaningful is set - a user who has changed nothing, or reset everything. */
+export declare function isDefaultAppearance(prefs: AppearanceInput | undefined): boolean;
+/** `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
+ * `apiFetch()` - see `withClient()`'s own doc comment in `util/api.ts`. Omitted (the default), every
+ * function here behaves exactly as before. */
+/** The user's stored preferences, or `undefined` when there are none to read (a `404`, or a body that isn't preferences). */
+export declare function getAppearance(client?: ApiClient): Promise<AppearancePreferences | undefined>;
+/** Merges `update` into the user's preferences and returns what the server stored. */
+export declare function saveAppearance(update: AppearanceUpdate, client?: ApiClient): Promise<AppearancePreferences>;
+/** Stores `file` (already checked with `validateBackgroundFile()`) as the background: its raw bytes, with its own content type - which
+ * bypasses `apiFetch()`, as it always sends JSON. Answers with the updated preferences. */
+export declare function uploadAppearanceBackground(file: Blob): Promise<AppearancePreferences>;
+/** Removes the stored background image. Answers with the updated preferences when the server sends them, else `undefined`. */
+export declare function deleteAppearanceBackground(client?: ApiClient): Promise<AppearancePreferences | undefined>;
+/** The URL of the stored background image `version` - what CSS `url()` and `<img src>` use. Immutable per version. */
+export declare function appearanceBackgroundUrl(version: string | number): string;
+/**
+ * What a push event says about the appearance: the new preferences for a `create`/`update` of an `AppearancePreferences...` model
+ * (whose `data` normalises), `null` for its `delete` (the user's back to the defaults), and `undefined` for any other event.
+ */
+export declare function parseAppearanceEvent(event: {
+    type: string;
+    action?: string;
+    data?: unknown;
+}): AppearancePreferences | null | undefined;

package/dist/lib/appearance/preferencesApi.js

@@ -0,0 +1,257 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed client for the signed-in user's appearance preferences - their colour scheme, theme colours and app background
+ * (`@rapidmx/restapi`'s `/mail/preferences/appearance` routes):
+ *
+ * - `GET  /mail/preferences/appearance` reads the `AppearancePreferences` object (never a 404: a user with none gets the defaults). `PUT`
+ * the same path **merges** a partial `AppearanceUpdate` into it (each colour and each background field on its own; `null` clears a
+ * colour) and answers with the saved object - so a client sends what changed (`diffAppearance()`), never the whole thing.
+ * - `POST /mail/preferences/appearance/background` stores the request body (a raw image, `Content-Type` = the file's own) as the
+ * background and answers with the updated preferences; `DELETE` the same path removes it.
+ * - `GET  /mail/preferences/appearance/background/:version` is the image itself - immutable per version, so an `<img>`/CSS `url()`
+ * pointing at `appearanceBackgroundUrl()` is cached for good.
+ * - A change is also pushed to the user's other tabs and devices as `{ type: /^AppearancePreferences/, action: "update", data }` on
+ * the user's own uid channel - `parseAppearanceEvent()` reads it.
+ *
+ * Everything that comes from outside - the response, a push event, the page's server-rendered props, `localStorage` - goes through
+ * `normalizeAppearance()`, which keeps only well-formed values (so a stale or hostile value can never reach a CSS declaration).
+ */
+import { ApiRequestError, apiUrl, withClient, withCsrfHeader } from "../util/api.js";
+export const APPEARANCE_MODES = ["system", "light", "dark"];
+export const BACKGROUND_KINDS = ["none", "color", "image"];
+export const BACKGROUND_FITS = ["cover", "contain", "tile"];
+export const COLOR_KEYS = ["primary", "accent", "surface", "text"];
+/** The largest dim the server accepts - beyond it the picture is not worth having. */
+export const BACKGROUND_DIM_MAX = 0.8;
+/** The largest blur, in CSS pixels. */
+export const BACKGROUND_BLUR_MAX = 20;
+/** The image types a background may be - raster only: an SVG is a document that can carry script. */
+export const BACKGROUND_IMAGE_TYPES = ["image/png", "image/jpeg", "image/webp", "image/avif"];
+/** The largest background image, in bytes. */
+export const BACKGROUND_MAX_BYTES = 8 * 1024 * 1024;
+/** The preferences a user who never chose anything has. */
+export const DEFAULT_APPEARANCE = { version: 1, mode: "system" };
+/** The starting background when the user first picks a kind: a light dim and no blur, covering the whole app. */
+export const DEFAULT_BACKGROUND = { kind: "none", dim: 0.2, blur: 0, fit: "cover" };
+const HEX_COLOR = /^#[0-9a-f]{6}$/i;
+/** An image version becomes part of a URL path: only characters that need no escaping. */
+const IMAGE_VERSION = /^[A-Za-z0-9._-]{1,64}$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hexOrUndefined(value) {
+    return typeof value === "string" && HEX_COLOR.test(value) ? value.toLowerCase() : undefined;
+}
+function clampNumber(value, min, max, fallback) {
+    return typeof value === "number" && Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : fallback;
+}
+function normalizeBackground(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const color = hexOrUndefined(value.color);
+    const rawVersion = value.imageVersion;
+    const imageVersion = typeof rawVersion === "number" && Number.isFinite(rawVersion) && rawVersion >= 0
+        ? rawVersion
+        : typeof rawVersion === "string" && IMAGE_VERSION.test(rawVersion)
+            ? rawVersion
+            : undefined;
+    let kind = BACKGROUND_KINDS.includes(value.kind) ? value.kind : "none";
+    // A kind without what it shows is nothing: an "image" that has no stored image, a "color" with no colour.
+    if ((kind === "image" && imageVersion === undefined) || (kind === "color" && color === undefined)) {
+        kind = "none";
+    }
+    const background = {
+        kind,
+        dim: clampNumber(value.dim, 0, BACKGROUND_DIM_MAX, DEFAULT_BACKGROUND.dim),
+        blur: clampNumber(value.blur, 0, BACKGROUND_BLUR_MAX, DEFAULT_BACKGROUND.blur),
+        fit: BACKGROUND_FITS.includes(value.fit) ? value.fit : DEFAULT_BACKGROUND.fit,
+    };
+    if (color !== undefined) {
+        background.color = color;
+    }
+    if (imageVersion !== undefined) {
+        background.imageVersion = imageVersion;
+    }
+    return background;
+}
+/**
+ * The well-formed part of `value` as `AppearancePreferences`, or `undefined` when it is not preferences at all (not an object, or not
+ * `version: 1`). Unknown keys are dropped, colours must be `#rrggbb` (lower-cased), numbers are clamped into their range, and an enum
+ * that isn't one of its values falls back to the default - so what comes out is always safe to turn into CSS.
+ */
+export function normalizeAppearance(value) {
+    if (!isRecord(value) || value.version !== 1) {
+        return undefined;
+    }
+    const prefs = {
+        version: 1,
+        mode: APPEARANCE_MODES.includes(value.mode) ? value.mode : "system",
+    };
+    if (isRecord(value.colors)) {
+        const colors = {};
+        for (const key of COLOR_KEYS) {
+            const hex = hexOrUndefined(value.colors[key]);
+            if (hex !== undefined) {
+                colors[key] = hex;
+            }
+        }
+        if (Object.keys(colors).length > 0) {
+            prefs.colors = colors;
+        }
+    }
+    const background = normalizeBackground(value.background);
+    if (background) {
+        prefs.background = background;
+    }
+    if (typeof value.updatedAt === "string" || (typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt))) {
+        prefs.updatedAt = value.updatedAt;
+    }
+    return prefs;
+}
+/**
+ * The reason `file` can't be a background, worded for the person choosing it, or `undefined` when it can. Checked before anything is
+ * uploaded (the server checks again). Takes anything with a `type` and a `size`, so it is testable without a real `File`.
+ */
+export function validateBackgroundFile(file) {
+    if (!BACKGROUND_IMAGE_TYPES.includes(file.type)) {
+        return "Choose a PNG, JPEG, WebP or AVIF image.";
+    }
+    if (file.size > BACKGROUND_MAX_BYTES) {
+        return `That image is ${(file.size / (1024 * 1024)).toFixed(1)} MB; the limit is ${BACKGROUND_MAX_BYTES / (1024 * 1024)} MB.`;
+    }
+    if (file.size === 0) {
+        return "That file is empty.";
+    }
+    return undefined;
+}
+const PATH = "/mail/preferences/appearance";
+/** What a background is until the user sets anything, as the server has it. */
+const SERVER_DEFAULT_BACKGROUND = { kind: "none", dim: 0, blur: 0, fit: "cover" };
+/**
+ * The `PUT` that takes what the server has (`server`, `undefined` for nothing yet) to `next`: only what differs, in the merge form the
+ * server takes - a colour that is gone is `null`, all of them gone is `colors: null`, and a background that is gone is `kind: "none"`
+ * (the server refuses `background: null`). `undefined` when there is nothing to send. The image is never named: its `imageVersion` is
+ * the server's to choose, and `kind: "image"` is only sent once `next` shows the very image the server holds - an image that is still
+ * uploading (a version the server doesn't know) can't be switched to yet.
+ */
+export function diffAppearance(server, next) {
+    const update = {};
+    if (next.mode !== (server?.mode ?? "system")) {
+        update.mode = next.mode;
+    }
+    const colors = {};
+    for (const key of COLOR_KEYS) {
+        if (next.colors?.[key] !== server?.colors?.[key]) {
+            colors[key] = next.colors?.[key] ?? null;
+        }
+    }
+    if (Object.keys(colors).length > 0) {
+        update.colors = !next.colors ? null : colors;
+    }
+    const base = server?.background ?? SERVER_DEFAULT_BACKGROUND;
+    const wanted = next.background;
+    if (!wanted) {
+        if (base.kind !== "none") {
+            update.background = { kind: "none" };
+        }
+    }
+    else {
+        const changes = {};
+        const heldImage = wanted.imageVersion !== undefined && wanted.imageVersion === base.imageVersion;
+        if (wanted.kind !== base.kind && (wanted.kind !== "image" || heldImage)) {
+            changes.kind = wanted.kind;
+        }
+        if (wanted.color !== base.color) {
+            changes.color = wanted.color ?? null;
+        }
+        for (const key of ["dim", "blur", "fit"]) {
+            if (wanted[key] !== base[key]) {
+                changes[key] = wanted[key];
+            }
+        }
+        if (Object.keys(changes).length > 0) {
+            update.background = changes;
+        }
+    }
+    return Object.keys(update).length > 0 ? { version: 1, ...update } : undefined;
+}
+/** `true` when nothing meaningful is set - a user who has changed nothing, or reset everything. */
+export function isDefaultAppearance(prefs) {
+    return (!prefs ||
+        (prefs.mode === "system" &&
+            !prefs.colors &&
+            (!prefs.background || prefs.background.kind === "none")));
+}
+/** `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
+ * `apiFetch()` - see `withClient()`'s own doc comment in `util/api.ts`. Omitted (the default), every
+ * function here behaves exactly as before. */
+/** The user's stored preferences, or `undefined` when there are none to read (a `404`, or a body that isn't preferences). */
+export async function getAppearance(client) {
+    try {
+        return normalizeAppearance(await withClient(client, PATH));
+    }
+    catch (err) {
+        if (err instanceof ApiRequestError && err.status === 404) {
+            return undefined;
+        }
+        throw err;
+    }
+}
+/** Merges `update` into the user's preferences and returns what the server stored. */
+export async function saveAppearance(update, client) {
+    const stored = normalizeAppearance(await withClient(client, PATH, { method: "PUT", body: JSON.stringify(update) }));
+    if (!stored) {
+        throw new ApiRequestError("The server did not return the saved appearance.", 502);
+    }
+    return stored;
+}
+/** Stores `file` (already checked with `validateBackgroundFile()`) as the background: its raw bytes, with its own content type - which
+ * bypasses `apiFetch()`, as it always sends JSON. Answers with the updated preferences. */
+export async function uploadAppearanceBackground(file) {
+    const res = await fetch(apiUrl(`${PATH}/background`), {
+        method: "POST",
+        credentials: "include",
+        headers: withCsrfHeader({ "Content-Type": file.type || "application/octet-stream" }),
+        body: file,
+    });
+    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 || "Upload failed.";
+        throw new ApiRequestError(message, res.status, body?.code);
+    }
+    const stored = normalizeAppearance(body);
+    if (!stored) {
+        throw new ApiRequestError("The server did not return the saved appearance.", 502);
+    }
+    return stored;
+}
+/** Removes the stored background image. Answers with the updated preferences when the server sends them, else `undefined`. */
+export async function deleteAppearanceBackground(client) {
+    return normalizeAppearance(await withClient(client, `${PATH}/background`, { method: "DELETE" }));
+}
+/** The URL of the stored background image `version` - what CSS `url()` and `<img src>` use. Immutable per version. */
+export function appearanceBackgroundUrl(version) {
+    return apiUrl(`${PATH}/background/${encodeURIComponent(String(version))}`);
+}
+/**
+ * What a push event says about the appearance: the new preferences for a `create`/`update` of an `AppearancePreferences...` model
+ * (whose `data` normalises), `null` for its `delete` (the user's back to the defaults), and `undefined` for any other event.
+ */
+export function parseAppearanceEvent(event) {
+    if (!/^AppearancePreferences/.test(event.type)) {
+        return undefined;
+    }
+    if (event.action === "delete") {
+        return null;
+    }
+    if (event.action === "update" || event.action === "create") {
+        return normalizeAppearance(event.data);
+    }
+    return undefined;
+}

package/dist/lib/auth/profileApi.d.ts

@@ -0,0 +1,33 @@
+export interface Profile {
+    uid: string;
+    /** URL to the user's avatar image (e.g. gravatar). Absent for most password-registered accounts. */
+    avatar?: string;
+    givenName?: string;
+    familyName?: string;
+}
+/** Fetches the signed-in caller's own profile — `"me"` resolves to the caller's own uid server-side. */
+export declare function getMyProfile(authServerUrl: string): Promise<Profile>;
+/**
+ * One of the caller's own aliases as auth-server's `GET /api/aliases` returns it - only the fields read here.
+ * `type: "name"` is a username (the local part of a mailbox address); `verified` is false until it's confirmed.
+ */
+export interface Alias {
+    alias: string;
+    type: string;
+    verified?: boolean;
+}
+/**
+ * The caller's username - their first verified auth-server alias of type `name` (`GET /api/aliases?type=name`,
+ * which lists only the caller's own). The display-name fallback for an account with no profile name: some
+ * accounts have no profile document at all (`/profiles/me` is a 404 for them), yet every account has a
+ * username. Never rejects - a failed call, an unexpected body or no verified name alias all resolve
+ * `undefined`, since a missing nicety must not surface as an error.
+ */
+export declare function getMyUsername(authServerUrl: string): Promise<string | undefined>;
+/** `"Jane Doe"`, `"Jane"`, `"Doe"`, or `undefined` if neither name field is set. */
+export declare function formatProfileName(profile: Pick<Profile, "givenName" | "familyName"> | undefined): string | undefined;
+/**
+ * A 1-2 letter initials badge, derived from the profile's name, else the first letter of `username` (see
+ * `getMyUsername()`), else the first letter of the given uid.
+ */
+export declare function profileInitials(profile: Pick<Profile, "givenName" | "familyName"> | undefined, uid: string, username?: string): string;

package/dist/lib/auth/profileApi.js

@@ -0,0 +1,52 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrapper over `@rapidrest/auth`'s `BaseProfileRoute`, mounted by auth-server at `/api/profiles`. Used
+ * for the signed-in user's own display name/avatar in the top-right user menu (see `UserMenu.tsx`) — this
+ * service has no local user directory of its own (see `.claude/NOTES.md`), so name/avatar can only ever come
+ * from auth-server.
+ *
+ * Deliberately NOT given the explicit-`ApiClient` `client?` parameter every other converted module in this
+ * package has — see `withClient()`'s doc comment in `util/api.ts`. Both `getMyProfile()` and `getMyUsername()`
+ * already take an explicit `authServerUrl` targeting a *different* origin than this app's own API (auth-server,
+ * not the RapidMX server `ApiClient`/`apiFetch()` talk to) — the same shape as `mailApi.ts`'s `impersonateUser()`/
+ * `stopImpersonating()`, which is why those were left unconverted too. A per-account auth-server session (the
+ * multi-account app's own credentials for *that* origin, not this app's) is a separate future change, out of
+ * scope here.
+ */
+import { authApiFetch } from "../util/api.js";
+/** Fetches the signed-in caller's own profile — `"me"` resolves to the caller's own uid server-side. */
+export function getMyProfile(authServerUrl) {
+    return authApiFetch(authServerUrl, "/profiles/me");
+}
+/**
+ * The caller's username - their first verified auth-server alias of type `name` (`GET /api/aliases?type=name`,
+ * which lists only the caller's own). The display-name fallback for an account with no profile name: some
+ * accounts have no profile document at all (`/profiles/me` is a 404 for them), yet every account has a
+ * username. Never rejects - a failed call, an unexpected body or no verified name alias all resolve
+ * `undefined`, since a missing nicety must not surface as an error.
+ */
+export async function getMyUsername(authServerUrl) {
+    try {
+        const aliases = await authApiFetch(authServerUrl, "/aliases?type=name");
+        return Array.isArray(aliases) ? aliases.find((a) => a?.type === "name" && a.verified === true && !!a.alias)?.alias : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `"Jane Doe"`, `"Jane"`, `"Doe"`, or `undefined` if neither name field is set. */
+export function formatProfileName(profile) {
+    const name = [profile?.givenName, profile?.familyName].filter(Boolean).join(" ").trim();
+    return name || undefined;
+}
+/**
+ * A 1-2 letter initials badge, derived from the profile's name, else the first letter of `username` (see
+ * `getMyUsername()`), else the first letter of the given uid.
+ */
+export function profileInitials(profile, uid, username) {
+    const initials = [profile?.givenName?.[0], profile?.familyName?.[0]].filter(Boolean).join("");
+    return (initials || username?.[0] || uid[0] || "?").toUpperCase();
+}

package/dist/lib/auth/session.d.ts

@@ -0,0 +1,70 @@
+/** An access token's age at which it is refreshed. The token lives an hour; the margin leaves time to retry a failed refresh. */
+export declare const SESSION_REFRESH_AFTER_MS: number;
+/** How often an open page checks whether its token is due. Also what retries a refresh that failed for a transient reason. */
+export declare const SESSION_REFRESH_CHECK_MS: number;
+/** A reload that follows a successful recovery refresh but still finds no session is not repeated within this window. */
+export declare const SESSION_RELOAD_GUARD_MS: number;
+/**
+ * Refreshes the signed-in session through auth-server: exchanges the `refresh` cookie for a new access token and
+ * refresh token, both set as cookies on the response. Rejects with the `ApiRequestError` auth-server answered
+ * (`401`/`403` when the refresh token has expired or was revoked).
+ *
+ * A refresh token is single-use and bound to the session, so two tabs refreshing at once would make the second one look
+ * like a dead session. Refreshes are therefore serialised across tabs (Web Locks, where the browser has them) and each
+ * tab records when the last one happened, so a tab that gets its turn right after another tab refreshed does nothing.
+ *
+ * @param force Refresh even when the last refresh, by this tab or another, was recent.
+ * @returns `true` when a refresh was made, `false` when one was not needed.
+ */
+export declare function refreshSession(authServerUrl: string, force?: boolean): Promise<boolean>;
+/**
+ * Redirects the browser to auth-server's sign-in page when `userUid` is absent, carrying the current URL as
+ * `return_to` so auth-server can send the browser back here afterward. A no-op once `userUid` is present.
+ *
+ * This does not try to recover the session first; `useSessionRefresh()` does, and is what an app frame should call.
+ *
+ * A no-op under an `ApiClientContext.Provider` (see `useSessionRefresh()`'s own doc comment for why) — there is
+ * no `jwt` cookie in that context for `userUid` to ever meaningfully reflect, and redirecting to auth-server's
+ * cookie-based sign-in page would be wrong for a session whose lifecycle a host app's own `ApiClient` manages.
+ */
+export declare function useRedirectIfUnauthenticated(userUid: string | undefined, authServerUrl: string | undefined): void;
+/** Options for `useSessionRefresh()`. */
+export interface SessionRefreshOptions {
+    /**
+     * Do not refresh, and send a page with no session straight to sign-in. For a session whose access token was not
+     * issued from the refresh token in its cookie: an admin viewing as another user holds that user's token beside their
+     * own refresh token, and a refresh would silently swap the admin back in.
+     */
+    paused?: boolean;
+    /**
+     * Runs before the browser leaves for sign-in because a refresh was refused while the page still had a session - the
+     * access token in hand is valid for a while yet, so this is the moment to save work in progress. The caller bounds how
+     * long it takes; a rejection is ignored and never stops the redirect.
+     */
+    beforeRedirect?: () => Promise<unknown>;
+}
+/**
+ * Keeps a page's session alive for as long as auth-server's refresh token is valid, so the user is not sent to sign in
+ * again every time the access token's hour is up:
+ *
+ * - `userUid` unset (the page was rendered without a valid `jwt` cookie - the tab was left open past the token's
+ * lifetime, or reopened later): attempts one silent refresh and reloads so the server renders the page with the new
+ * cookie. If the refresh is refused (the refresh token expired or was revoked, or there was none), or a reload just
+ * made still found no session, redirects to sign-in as `useRedirectIfUnauthenticated()` does.
+ * - `userUid` set: refreshes once the token is `SESSION_REFRESH_AFTER_MS` old (and right away when this browser has no
+ * record of a recent refresh, since the page's token age is unknown), checked every `SESSION_REFRESH_CHECK_MS` and
+ * whenever the tab becomes visible or the network returns, because a sleeping laptop stops timers. A failure that is
+ * not a rejection is simply retried at the next check. A rejection (`401`/`403`: the refresh token expired or was
+ * revoked, so the session cannot be kept) redirects to sign-in with `return_to` after `options.beforeRedirect` has run.
+ *
+ * **A no-op under an `ApiClientContext.Provider`** (see `util/apiClientContext.ts`): everything above assumes a
+ * `jwt`/`refresh` cookie pair this app can renew through auth-server's own `/auth/refresh` - meaningless for a
+ * component whose network calls actually go through an explicit `ApiClient` from `createApiClient()` instead
+ * (e.g. one account of the native, multi-account `tauri-client`), which has no cookie jar for that origin at all
+ * and whose token lifecycle is the host app's own job via a completely different mechanism (its own refresh
+ * flow, keyed to `ApiClient.getAccessToken()`). Detected via `useApiClient()`; when it returns anything other
+ * than `undefined`, this hook does nothing at all - no timer, no listener, no redirect, regardless of `userUid`/
+ * `authServerUrl`/`options`. The default (no `ApiClientContext.Provider` anywhere - every existing browser/SSR/
+ * Electron consumer) is completely unchanged: `useApiClient()` there always returns `undefined`.
+ */
+export declare function useSessionRefresh(userUid: string | undefined, authServerUrl: string | undefined, options?: SessionRefreshOptions): void;