@rapidmx/web-client 0.21.0 → 0.22.0

package/dist/lib/util/timeZone.js

@@ -0,0 +1,32 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** The time zone a mailbox has when nothing better is known - the server's own default. */
+export 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 function deviceTimeZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || DEFAULT_TIME_ZONE;
+    }
+    catch {
+        return DEFAULT_TIME_ZONE;
+    }
+}
+/**
+ * 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 function timeZoneOptions(...extra) {
+    let zones = [];
+    try {
+        zones = Intl.supportedValuesOf?.("timeZone") ?? [];
+    }
+    catch {
+        zones = [];
+    }
+    return [...new Set([DEFAULT_TIME_ZONE, ...zones, ...extra.filter(Boolean)])].sort((a, b) => a.localeCompare(b));
+}

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

@@ -0,0 +1,12 @@
+/** `"copied"`/`"failed"` are transient - they fall back to `"idle"` after the hook's reset delay. */
+export type CopyStatus = "idle" | "copied" | "failed";
+/** How long "Copied" stays up by default. */
+export declare const COPY_FEEDBACK_MS = 2000;
+/**
+ * Copy-to-clipboard with brief feedback state: `copy(text)` (see `copyTextToClipboard()`) sets `status` to
+ * `"copied"` or `"failed"` and back to `"idle"` after `resetMs`. Safe to unmount mid-copy or mid-feedback.
+ */
+export default function useCopyToClipboard(resetMs?: number): {
+    status: CopyStatus;
+    copy: (text: string) => Promise<boolean>;
+};

package/dist/lib/util/useCopyToClipboard.js

@@ -0,0 +1,34 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useEffect, useRef, useState } from "react";
+import { copyTextToClipboard } from "./clipboard.js";
+/** How long "Copied" stays up by default. */
+export const COPY_FEEDBACK_MS = 2000;
+/**
+ * Copy-to-clipboard with brief feedback state: `copy(text)` (see `copyTextToClipboard()`) sets `status` to
+ * `"copied"` or `"failed"` and back to `"idle"` after `resetMs`. Safe to unmount mid-copy or mid-feedback.
+ */
+export default function useCopyToClipboard(resetMs = COPY_FEEDBACK_MS) {
+    const [status, setStatus] = useState("idle");
+    const timer = useRef(undefined);
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+            clearTimeout(timer.current);
+        };
+    }, []);
+    const copy = useCallback(async (text) => {
+        const copied = await copyTextToClipboard(text);
+        if (mounted.current) {
+            setStatus(copied ? "copied" : "failed");
+            clearTimeout(timer.current);
+            timer.current = setTimeout(() => setStatus("idle"), resetMs);
+        }
+        return copied;
+    }, [resetMs]);
+    return { status, copy };
+}

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

@@ -0,0 +1,10 @@
+/**
+ * `true` below `breakpointPx` (default 768, i.e. Tailwind's `md`). Always `false` during SSR and the
+ * initial client render — corrected in an effect after mount, the same "read real client state once
+ * mounted" convention already used by `MailShell`'s query-param reads — so server-rendered markup and
+ * the first hydrated frame always agree (no hydration-mismatch warning), at the cost of a one-frame
+ * desktop-layout flash for mobile visitors on first load. Prefer plain Tailwind `md:` classes for pure
+ * layout/visibility; reach for this hook only when a component needs to make an actual JS-level
+ * decision (e.g. real navigation vs. local state).
+ */
+export default function useIsMobile(breakpointPx?: number): boolean;

package/dist/lib/util/useIsMobile.js

@@ -0,0 +1,29 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+/** Matches this app's Tailwind `md` breakpoint, the cutoff used throughout for mobile vs. desktop layout. */
+const DEFAULT_BREAKPOINT_PX = 768;
+/**
+ * `true` below `breakpointPx` (default 768, i.e. Tailwind's `md`). Always `false` during SSR and the
+ * initial client render — corrected in an effect after mount, the same "read real client state once
+ * mounted" convention already used by `MailShell`'s query-param reads — so server-rendered markup and
+ * the first hydrated frame always agree (no hydration-mismatch warning), at the cost of a one-frame
+ * desktop-layout flash for mobile visitors on first load. Prefer plain Tailwind `md:` classes for pure
+ * layout/visibility; reach for this hook only when a component needs to make an actual JS-level
+ * decision (e.g. real navigation vs. local state).
+ */
+export default function useIsMobile(breakpointPx = DEFAULT_BREAKPOINT_PX) {
+    const [isMobile, setIsMobile] = useState(false);
+    useEffect(() => {
+        const mql = window.matchMedia(`(max-width: ${breakpointPx - 1}px)`);
+        setIsMobile(mql.matches);
+        function handleChange(e) {
+            setIsMobile(e.matches);
+        }
+        mql.addEventListener("change", handleChange);
+        return () => mql.removeEventListener("change", handleChange);
+    }, [breakpointPx]);
+    return isMobile;
+}

package/dist/lib/videoconf/videoMeetingsApi.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Typed wrappers over `@rapidmx/meet-plugin`'s `/mail/video-meetings` REST surface — the owner-side
+ * management endpoints only (create, read, update/cancel). The anonymous `/join/:token` endpoint a guest's
+ * link resolves through is deliberately not wrapped here: it belongs to the meeting UI a guest loads, not to
+ * the authenticated webmail client this library serves.
+ *
+ * A plugin's routes are mounted on the same server, under the same `/api` prefix, as every first-party route,
+ * so there is nothing special about calling one: these go through the same `apiFetch()` (and therefore the
+ * same `jwt` cookie, the same `configureApiBaseUrl()` origin and the same `ApiRequestError` failure shape) as
+ * `calendarApi.ts`'s own calls. Authorization is the plugin's own: every call here is checked against the
+ * meeting's owning mailbox ACL, so a caller who neither owns nor holds a grant on that mailbox gets a 403/404
+ * rather than a meeting. When the plugin isn't installed at all, its routes simply aren't mounted and these
+ * calls fail with a 404 `ApiRequestError` — a caller that offers video conferencing optionally must treat
+ * that as "not available here" rather than as an error worth alarming the user with.
+ *
+ * Response bodies are typed, not runtime-validated, matching this library's convention for a plain typed
+ * `apiFetch<T>()` call (see `crypto/signingProviderApi.ts`'s own note on the same choice).
+ */
+import { ApiClient } from "../util/api.js";
+import { ListParams } from "../util/apiQuery.js";
+export type { ListParams };
+/** Whether a meeting is joinable only by its explicitly invited participants, or by anyone holding its link. */
+export type VideoMeetingVisibility = "private" | "public";
+export type VideoMeetingStatus = "scheduled" | "active" | "ended" | "cancelled";
+/** The owner's view of a meeting. Only the fields a client actually reads are typed — the entity carries more. */
+export interface VideoMeeting {
+    uid: string;
+    mailboxUid: string;
+    title: string;
+    visibility: VideoMeetingVisibility;
+    status: VideoMeetingStatus;
+    /** The `CalendarEvent` this meeting was minted for, when it was minted for one. */
+    calendarEventUid?: string;
+    startTime?: string;
+    endTime?: string;
+    /** ISO 8601 instant the meeting was created - every `BaseEntity` carries one; typed here because
+     * `apps/settings-video-conferencing` (Phase 4) both shows it and uses it to pick a mailbox's "personal room"
+     * (its oldest non-cancelled public meeting - see that app's own doc comment) out of `listVideoMeetings()`'s
+     * results. */
+    dateCreated: string;
+}
+/**
+ * A meeting as fetched by `getVideoMeeting()` or listed by `listVideoMeetings()` — the entity plus whichever join
+ * link(s) `BaseVideoMeetingRoute.withJoinUrls()` recomputes for it from its persisted slug(s). A meeting carries at
+ * most one of the two: `organizerJoinUrl` only for a private meeting that has an `organizerSlug`, `publicJoinUrl`
+ * only for a public one (see `VideoMeeting.visibility`) - never both, and neither at all when the deployment has no
+ * public URL configured for the plugin.
+ */
+export interface VideoMeetingDetail extends VideoMeeting {
+    /** The owner's own working join link for a private meeting. */
+    organizerJoinUrl?: string;
+    /** The single shareable join link for a public meeting - what a host copies out to share their "personal
+     * room" or any other public meeting. */
+    publicJoinUrl?: string;
+}
+/** One person to invite to a private meeting. */
+export interface VideoMeetingInvitee {
+    email: string;
+    displayName?: string;
+}
+/** One invitee as minted by `createVideoMeeting()`, carrying that person's own personal join link. */
+export interface VideoMeetingInviteeJoinInfo extends VideoMeetingInvitee {
+    uid: string;
+    /** Absent when the deployment has no public URL configured for the plugin. */
+    joinUrl?: string;
+}
+export interface CreateVideoMeetingInput {
+    /** The mailbox that owns the meeting — the one whose ACL every later call on it is checked against. */
+    mailboxUid: string;
+    /** Non-empty, at most 200 characters (the server rejects anything else with a 400). */
+    title: string;
+    visibility: VideoMeetingVisibility;
+    /** The `CalendarEvent` this meeting is being minted for, when there is one. */
+    calendarEventUid?: string;
+    startTime?: string;
+    endTime?: string;
+    /** Required, and non-empty, for a `"private"` meeting — the server mints one personal join link per entry
+     * and 400s a private meeting with none. Never send the organizer here: they reach their own meeting
+     * through ownership (and `organizerJoinUrl`), not as a guest. */
+    invitees?: VideoMeetingInvitee[];
+}
+export interface VideoMeetingCreateResult {
+    meeting: VideoMeeting;
+    /** Present for a private meeting — one entry per requested invitee, each with their own join link. */
+    invitees?: VideoMeetingInviteeJoinInfo[];
+    /** Present for a private meeting — the organizer's own join link (see `VideoMeetingDetail`). */
+    organizerJoinUrl?: string;
+    /** Present for a public meeting — the single link everyone joins through. */
+    publicJoinUrl?: string;
+}
+/** `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. */
+/** Creates a meeting owned by `input.mailboxUid`. Requires CREATE on that mailbox. */
+export declare function createVideoMeeting(input: CreateVideoMeetingInput, client?: ApiClient): Promise<VideoMeetingCreateResult>;
+/**
+ * The only changes this route accepts. It deliberately cannot change a meeting's invitees: a private
+ * meeting's invitee list (and therefore its personal join links) is fixed at creation, so a caller whose
+ * invitee list has changed must cancel this meeting and create a new one.
+ */
+export interface UpdateVideoMeetingInput {
+    title?: string;
+    status?: "cancelled";
+}
+/** Renames or cancels a meeting. Requires UPDATE on its owning mailbox. */
+export declare function updateVideoMeeting(uid: string, input: UpdateVideoMeetingInput, client?: ApiClient): Promise<VideoMeeting>;
+/** Fetches one meeting, with the organizer's own join link when it has one. Requires READ on its owning mailbox. */
+export declare function getVideoMeeting(uid: string, client?: ApiClient): Promise<VideoMeetingDetail>;
+/**
+ * Lists every meeting owned by `mailboxUid`, each carrying whichever join link `VideoMeetingDetail` describes for
+ * it. Requires LIST on that mailbox. Added for `apps/settings-video-conferencing` (Phase 4), which needs a
+ * mailbox's whole meeting history to both render its list and find the mailbox's "personal room" (its oldest
+ * non-cancelled public meeting) - `BaseVideoMeetingRoute.find()` already supported this exact query (no
+ * `calendarEventUid` filter), it just had no typed wrapper here yet.
+ */
+export declare function listVideoMeetings(mailboxUid: string, params?: ListParams, client?: ApiClient): Promise<VideoMeetingDetail[]>;

package/dist/lib/videoconf/videoMeetingsApi.js

@@ -0,0 +1,49 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/meet-plugin`'s `/mail/video-meetings` REST surface — the owner-side
+ * management endpoints only (create, read, update/cancel). The anonymous `/join/:token` endpoint a guest's
+ * link resolves through is deliberately not wrapped here: it belongs to the meeting UI a guest loads, not to
+ * the authenticated webmail client this library serves.
+ *
+ * A plugin's routes are mounted on the same server, under the same `/api` prefix, as every first-party route,
+ * so there is nothing special about calling one: these go through the same `apiFetch()` (and therefore the
+ * same `jwt` cookie, the same `configureApiBaseUrl()` origin and the same `ApiRequestError` failure shape) as
+ * `calendarApi.ts`'s own calls. Authorization is the plugin's own: every call here is checked against the
+ * meeting's owning mailbox ACL, so a caller who neither owns nor holds a grant on that mailbox gets a 403/404
+ * rather than a meeting. When the plugin isn't installed at all, its routes simply aren't mounted and these
+ * calls fail with a 404 `ApiRequestError` — a caller that offers video conferencing optionally must treat
+ * that as "not available here" rather than as an error worth alarming the user with.
+ *
+ * Response bodies are typed, not runtime-validated, matching this library's convention for a plain typed
+ * `apiFetch<T>()` call (see `crypto/signingProviderApi.ts`'s own note on the same choice).
+ */
+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. */
+/** Creates a meeting owned by `input.mailboxUid`. Requires CREATE on that mailbox. */
+export function createVideoMeeting(input, client) {
+    return withClient(client, "/mail/video-meetings", { method: "POST", body: JSON.stringify(input) });
+}
+/** Renames or cancels a meeting. Requires UPDATE on its owning mailbox. */
+export function updateVideoMeeting(uid, input, client) {
+    return withClient(client, `/mail/video-meetings/${encodeURIComponent(uid)}`, { method: "PUT", body: JSON.stringify(input) });
+}
+/** Fetches one meeting, with the organizer's own join link when it has one. Requires READ on its owning mailbox. */
+export function getVideoMeeting(uid, client) {
+    return withClient(client, `/mail/video-meetings/${encodeURIComponent(uid)}`);
+}
+/**
+ * Lists every meeting owned by `mailboxUid`, each carrying whichever join link `VideoMeetingDetail` describes for
+ * it. Requires LIST on that mailbox. Added for `apps/settings-video-conferencing` (Phase 4), which needs a
+ * mailbox's whole meeting history to both render its list and find the mailbox's "personal room" (its oldest
+ * non-cancelled public meeting) - `BaseVideoMeetingRoute.find()` already supported this exact query (no
+ * `calendarEventUid` filter), it just had no typed wrapper here yet.
+ */
+export function listVideoMeetings(mailboxUid, params = {}, client) {
+    return withClient(client, `/mail/video-meetings?${buildQuery(params, { mailboxUid })}`);
+}

package/lib/admin/auditLogApi.ts

@@ -0,0 +1,48 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrapper over `@rapidmx/restapi`'s `AuditLogEntry` route (`BaseAuditLogRoute`) — read-only: every
+ * write path (`create`/`update`/`delete`/`truncate`) unconditionally 403s, trusted callers included, so
+ * there is no write function here to mirror `domainsApi.ts`'s CRUD shape. The only writer is restapi's
+ * own server-internal `recordAuditLog()`.
+ */
+
+import { ApiClient, withClient } from "../util/api.js";
+import { ListParams, buildQuery } from "../util/apiQuery.js";
+
+export type { ListParams };
+
+export interface AuditLogEntry {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid?: string;
+    actorUserUid?: string;
+    action: string;
+    targetType: string;
+    targetUid: string;
+    ip?: string;
+    details?: Record<string, unknown>;
+}
+
+export interface AuditLogFilters {
+    mailboxUid?: string;
+    actorUserUid?: string;
+    action?: string;
+    targetType?: string;
+}
+
+/** `client`, given 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), this behaves exactly as before. */
+export function listAuditLog(filters: AuditLogFilters = {}, params: ListParams = {}, client?: ApiClient): Promise<AuditLogEntry[]> {
+    const extra: Record<string, string> = {};
+    if (filters.mailboxUid) extra.mailboxUid = filters.mailboxUid;
+    if (filters.actorUserUid) extra.actorUserUid = filters.actorUserUid;
+    if (filters.action) extra.action = filters.action;
+    if (filters.targetType) extra.targetType = filters.targetType;
+    return withClient(client, `/mail/audit-log?${buildQuery(params, extra)}`);
+}

package/lib/admin/distributionListsApi.ts

@@ -0,0 +1,77 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `DistributionList` CRUD route (`BaseDistributionListRoute`) —
+ * trusted-role-only, no self-service creation or per-list delegated ownership (v1).
+ */
+
+import { ApiClient, withClient } from "../util/api.js";
+import { ListParams, buildQuery } from "../util/apiQuery.js";
+
+export type { ListParams };
+
+export interface DistributionList {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    primarySmtpAddress: string;
+    aliasAddresses?: string[];
+    name: string;
+    description?: string;
+    /** Informational only — v1 has no delegated-ownership enforcement; list management is trusted-role-only. */
+    ownerUserUid?: string;
+    memberAddresses: string[];
+    restrictSenders?: boolean;
+}
+
+/** `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 listDistributionLists(params: ListParams = {}, client?: ApiClient): Promise<DistributionList[]> {
+    return withClient(client, `/mail/distribution-lists?${buildQuery(params)}`);
+}
+
+export function getDistributionList(uid: string, client?: ApiClient): Promise<DistributionList> {
+    return withClient(client, `/mail/distribution-lists/${encodeURIComponent(uid)}`);
+}
+
+export interface CreateDistributionListInput {
+    primarySmtpAddress: string;
+    aliasAddresses?: string[];
+    name: string;
+    description?: string;
+    ownerUserUid?: string;
+    memberAddresses?: string[];
+    restrictSenders?: boolean;
+}
+
+export function createDistributionList(input: CreateDistributionListInput, client?: ApiClient): Promise<DistributionList> {
+    return withClient(client, "/mail/distribution-lists", {
+        method: "POST",
+        body: JSON.stringify({ aliasAddresses: [], memberAddresses: [], ...input }),
+    });
+}
+
+export interface UpdateDistributionListInput {
+    uid: string;
+    version: number;
+    name?: string;
+    description?: string;
+    aliasAddresses?: string[];
+    memberAddresses?: string[];
+    restrictSenders?: boolean;
+}
+
+export function updateDistributionList(input: UpdateDistributionListInput, client?: ApiClient): Promise<DistributionList> {
+    return withClient(client, `/mail/distribution-lists/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+
+export function deleteDistributionList(uid: string, version: number, client?: ApiClient): Promise<void> {
+    return withClient(client, `/mail/distribution-lists/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}

package/lib/admin/domainsApi.ts

@@ -0,0 +1,113 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `Domain` CRUD + verification routes (`BaseDomainRoute`).
+ * Every route here is `@RequiresTrustedRole()` on the backend — admin-only, matching `mailApi.ts`'s other
+ * admin-scoped entities.
+ */
+
+import { ApiClient, withClient } from "../util/api.js";
+import { ListParams, buildQuery } from "../util/apiQuery.js";
+
+export type { ListParams };
+
+export interface Domain {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    name: string;
+    enabled: boolean;
+    verified: boolean;
+    verificationToken: string;
+    verifiedAt?: string;
+    lastCheckedAt?: string;
+    dkimSelector?: string;
+    dkimPublicKey?: string;
+    dmarcPolicy?: "none" | "quarantine" | "reject";
+    dmarcReportEmail?: string;
+    /** When set, this domain is a pure alias of the domain named here - it has no mailboxes of its own; mail
+     * addressed to it is delivered to the matching mailbox on the domain it aliases instead. */
+    aliasOf?: string;
+}
+
+/** `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 listDomains(params: ListParams = {}, client?: ApiClient): Promise<Domain[]> {
+    return withClient(client, `/mail/domains?${buildQuery(params)}`);
+}
+
+export function getDomain(uid: string, client?: ApiClient): Promise<Domain> {
+    return withClient(client, `/mail/domains/${encodeURIComponent(uid)}`);
+}
+
+export interface CreateDomainInput {
+    name: string;
+    enabled?: boolean;
+    dkimSelector?: string;
+    dkimPublicKey?: string;
+    dmarcPolicy?: "none" | "quarantine" | "reject";
+    dmarcReportEmail?: string;
+    aliasOf?: string;
+}
+
+export function createDomain(input: CreateDomainInput, client?: ApiClient): Promise<Domain> {
+    return withClient(client, "/mail/domains", {
+        method: "POST",
+        body: JSON.stringify({ enabled: true, ...input }),
+    });
+}
+
+export interface UpdateDomainInput {
+    uid: string;
+    version: number;
+    enabled?: boolean;
+    dkimSelector?: string;
+    dkimPublicKey?: string;
+    dmarcPolicy?: "none" | "quarantine" | "reject";
+    dmarcReportEmail?: string;
+    aliasOf?: string;
+}
+
+export function updateDomain(input: UpdateDomainInput, client?: ApiClient): Promise<Domain> {
+    return withClient(client, `/mail/domains/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+
+export function deleteDomain(uid: string, version: number, client?: ApiClient): Promise<void> {
+    return withClient(client, `/mail/domains/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}
+
+/** Triggers an immediate DNS ownership check rather than waiting for the next scheduled background pass.
+ * Idempotent on an already-verified domain; a still-unverified result is not an error (only
+ * `lastCheckedAt` advances) — always returns the domain's current state either way. */
+export function verifyDomain(uid: string, client?: ApiClient): Promise<Domain> {
+    return withClient(client, `/mail/domains/${encodeURIComponent(uid)}/verify`, { method: "POST" });
+}
+
+export type DnsRecordType = "ownership" | "mx" | "spf" | "dkim" | "dmarc" | "autodiscover_cname" | "autodiscover_srv";
+
+/** One mail-related DNS record this server recommends for a domain, live-checked against real DNS —
+ * purely diagnostic, never mutates anything (unlike `verifyDomain`). The two `autodiscover_*` types are only
+ * ever present while `@rapidmx/autodiscover-plugin` is active for this deployment. */
+export interface DnsRecordCheck {
+    type: DnsRecordType;
+    recordKind: "TXT" | "MX" | "CNAME" | "SRV";
+    recordName: string;
+    /** `false` when there isn't enough information yet to know what to recommend (no DKIM
+     * selector/key configured, for example) — `recommendedValue`/`found`/`matches` are meaningless then. */
+    configured: boolean;
+    recommendedValue?: string;
+    found: boolean;
+    matches: boolean;
+    actualValue?: string;
+}
+
+export function getDnsSetup(uid: string, client?: ApiClient): Promise<DnsRecordCheck[]> {
+    return withClient(client, `/mail/domains/${encodeURIComponent(uid)}/dns-setup`);
+}

package/lib/admin/escrowAccessRequestsApi.ts

@@ -0,0 +1,110 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `EscrowAccessRequest` route (`BaseEscrowAccessRequestRoute`) —
+ * a bespoke (non-`CRUDRoute`) route: no `update`/`delete`/`count`, and `create()` only ever accepts
+ * `{matterId, mailboxUid}` (everything else is derived server-side). Holder-gated throughout, same as
+ * `mattersApi.ts`. `find()`/`findById()` auto-scope to matters under scopes the caller holds; `approve()`/
+ * `deny()` mutate in place and return the updated request; `material()` is only ever readable once the
+ * request is `approved`/`fulfilled`, and returns still-encrypted `MasterKeyWraps` this server can't
+ * decrypt either — see `EscrowAccessMaterial`'s own doc comment.
+ */
+
+import { ApiClient, withClient } from "../util/api.js";
+import { ListParams, RequestListParams, buildQuery } from "../util/apiQuery.js";
+
+export type { ListParams, RequestListParams };
+
+export interface EscrowAccessRequestApproval {
+    holderUserUid: string;
+    /** ISO 8601 timestamp. */
+    approvedAt: string;
+}
+
+export type EscrowAccessRequestStatus = "pending" | "approved" | "denied" | "fulfilled";
+
+export interface EscrowAccessRequest {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    matterId: string;
+    mailboxUid: string;
+    requestedByUserUid: string;
+    approvals: EscrowAccessRequestApproval[];
+    /** Snapshotted from `EscrowScope.requiredHolders` at creation time — see this type's own restapi doc
+     * comment on why it's never re-read live. */
+    requiredHoldersAtCreation: number;
+    status: EscrowAccessRequestStatus;
+    /** Set the first time `getAccessRequestMaterial()` is successfully called — informational only. */
+    fulfilledAt?: string;
+    deniedByUserUid?: string;
+    deniedAt?: string;
+}
+
+/** Mirrors `@rapidmx/restapi`'s `MasterKeyWrap` — same shape `crypto/keyvaultApi.ts` already defines for
+ * the mailbox-owner side of this feature, duplicated here rather than cross-imported (same convention
+ * every other `*Api.ts` wrapper in this package already follows for overlapping wire shapes). */
+export interface MasterKeyWrap {
+    method: "password" | "passkey" | "recovery" | "escrow";
+    methodId?: string;
+    escrowScopeId?: string;
+    ciphertext: string;
+    nonce: string;
+    salt: string;
+    kdf: string;
+    schemeVersion: number;
+    createdAt: number;
+}
+
+/** The wire shape `getAccessRequestMaterial()` returns — only ever the escrow-method wraps scoped to the
+ * matter's own escrow scope, never `wrappedKeys` or any other unlock method. This app deliberately never
+ * attempts to decrypt these — they're surfaced as-is for the holder to copy into their own offline
+ * tooling, per `specs/end-to-end_encryption.md`'s "this server never holds the scope's private key". */
+export interface EscrowAccessMaterial {
+    masterKeyWraps: MasterKeyWrap[];
+}
+
+/** `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. */
+/** Newest first. Every request belongs to one Matter, so `params.matterId` narrows the list to that
+ * Matter's requests (still only ever within scopes the caller holds). */
+export function listAccessRequests(params: RequestListParams = {}, client?: ApiClient): Promise<EscrowAccessRequest[]> {
+    const { matterId, ...paging } = params;
+    return withClient(client, `/escrow/access-requests?${buildQuery(paging, matterId ? { matterId } : {})}`);
+}
+
+export function getAccessRequest(uid: string, client?: ApiClient): Promise<EscrowAccessRequest> {
+    return withClient(client, `/escrow/access-requests/${encodeURIComponent(uid)}`);
+}
+
+export interface CreateAccessRequestInput {
+    matterId: string;
+    mailboxUid: string;
+}
+
+/** The requester's own creation counts as their first approval — auto-approved immediately if
+ * `EscrowScope.requiredHolders` is `1`. */
+export function createAccessRequest(input: CreateAccessRequestInput, client?: ApiClient): Promise<EscrowAccessRequest> {
+    return withClient(client, "/escrow/access-requests", { method: "POST", body: JSON.stringify(input) });
+}
+
+/** 409s if the request isn't `pending`; 400s if the caller already approved it. */
+export function approveAccessRequest(uid: string, client?: ApiClient): Promise<EscrowAccessRequest> {
+    return withClient(client, `/escrow/access-requests/${encodeURIComponent(uid)}/approve`, { method: "POST" });
+}
+
+/** 409s if the request isn't `pending`. */
+export function denyAccessRequest(uid: string, client?: ApiClient): Promise<EscrowAccessRequest> {
+    return withClient(client, `/escrow/access-requests/${encodeURIComponent(uid)}/deny`, { method: "POST" });
+}
+
+/** 403s ("Dual control threshold not yet met.") unless the request is `approved`/`fulfilled`. Marks the
+ * request `fulfilled` server-side as a side effect of a successful call, and records an
+ * `EscrowAuditAction.MATERIAL_READ` entry — see `escrowAuditLogApi.ts`. */
+export function getAccessRequestMaterial(uid: string, client?: ApiClient): Promise<EscrowAccessMaterial> {
+    return withClient(client, `/escrow/access-requests/${encodeURIComponent(uid)}/material`);
+}