@rapidmx/web-client 0.21.0 → 0.23.0

package/dist/lib/mail/mailApi.js

@@ -0,0 +1,602 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s REST surface. Shared by `apps/admin` and (from Phase 3 on)
+ * `apps/www` — there is no separate admin-only endpoint set to isolate: every route here is gated entirely
+ * by the ACL system, so the exact same call returns the caller's own data and what is shared with them - an
+ * administrator's included: no role reads another user's mail. The one exception is the administration scope
+ * (`scope: "admin"` -> `?scope=admin`), which ONLY the admin console passes: mailboxes then come back as
+ * administrative metadata (no keys, settings or content) and every call is audited; an administrator who needs
+ * to see somebody's mail impersonates them (`impersonateUser()`). See `BaseMailboxRoute`'s doc comment in
+ * `@rapidmx/restapi` and this repo's `.claude/NOTES.md`.
+ */
+import { ApiRequestError, apiFetch, apiUrl, authApiFetch, withClient, withCsrfHeader } from "../util/api.js";
+import { buildQuery } from "../util/apiQuery.js";
+import { deviceTimeZone } from "../util/timeZone.js";
+import { bytesToBinaryString } from "../crypto/mime.js";
+/** Whether `mailbox` is one shared with the caller rather than their own: a delegate grant on somebody's mailbox, or a mailbox with no
+ * owner at all (a shared/org mailbox they were granted). */
+export function isSharedWithMe(mailbox) {
+    return mailbox.accessRole ? mailbox.accessRole === "delegate" : !mailbox.ownerUserUid;
+}
+/** The `scope` query parameter of `params`, when set. */
+function scopeQuery(params) {
+    return params.scope ? { scope: params.scope } : {};
+}
+/** The free/busy visibility `mailbox` has: `"domain"` when it says none (a mailbox stored before the setting existed). */
+export function freeBusyVisibilityOf(mailbox) {
+    return mailbox.freeBusyVisibility ?? "domain";
+}
+/** The blocked senders `mailbox` has: none when it says none (a mailbox stored before the list existed, or `null` from an SQL row). */
+export function blockedSendersOf(mailbox) {
+    return mailbox.blockedSenders ?? [];
+}
+/** The safe senders `mailbox` has: none when it says none. */
+export function safeSendersOf(mailbox) {
+    return mailbox.safeSenders ?? [];
+}
+/** Lists the mailboxes the caller owns or has been granted - the same for everyone, an administrator included. With
+ * `scope: "admin"` (admin console only) it lists every mailbox as administrative metadata instead. */
+export function listMailboxes(params = {}, client) {
+    return withClient(client, `/mail/mailboxes?${buildQuery(params, scopeQuery(params))}`);
+}
+/** One mailbox the caller owns or has been granted; with `scope: "admin"` (admin console only), its administrative metadata. */
+export function getMailbox(uid, options = {}, client) {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(uid)}${options.scope ? `?scope=${options.scope}` : ""}`);
+}
+/** Lists bookable resource mailboxes (rooms/equipment) visible to the caller — same ACL scoping as
+ * `listMailboxes()`, just pre-filtered server-side to `isResource: true` so `ResourcePicker` doesn't
+ * need to fetch and filter the caller's entire mailbox list client-side. */
+export function listResourceMailboxes(params = {}, client) {
+    return withClient(client, `/mail/mailboxes?${buildQuery(params, { isResource: "true" })}`);
+}
+export function createMailbox(input, client) {
+    return withClient(client, "/mail/mailboxes", {
+        method: "POST",
+        body: JSON.stringify({ aliasAddresses: [], usedBytes: 0, ...input }),
+    });
+}
+/**
+ * Who a typed principal - a mailbox address, an auth-server username or e-mail alias, or a user uid - is, for an
+ * administrator naming a mailbox's owner (a new mailbox here, or a future reassignment) to confirm before saving.
+ * Rejects with a 404 `ApiRequestError` ("No user found for ...") for nobody. Trusted-role-only
+ * (`BaseMailboxRoute.resolveOwner()` in `@rapidmx/restapi`) - the same exact-match resolution
+ * `resolveMailboxPrincipal()` (`mailboxAccessApi.ts`) uses for sharing.
+ */
+export function resolveMailboxOwner(principal, client) {
+    return withClient(client, `/mail/mailboxes/resolve-owner?principal=${encodeURIComponent(principal)}`);
+}
+/** This server's configured domain list (`mail:domains`) — empty when unconfigured, meaning no
+ * restriction applies and a `primarySmtpAddress` may be on any domain. */
+export function listMailboxDomains(client) {
+    return withClient(client, "/mail/mailboxes/domains");
+}
+/**
+ * Self-service mailbox creation for a user with none yet — see `BaseMailboxRoute.autoProvision()`'s own
+ * doc comment in `@rapidmx/restapi` for the full contract. Call with no `selection` first; if the
+ * result is `needs_selection`, call again with the option the user picked from that list.
+ */
+export function autoProvisionMailbox(selection, client) {
+    return withClient(client, "/mail/mailboxes/auto-provision", {
+        method: "POST",
+        // The device's time zone goes with every call, for the mailbox this may create.
+        body: JSON.stringify({ ...selection, timezone: deviceTimeZone() }),
+    });
+}
+export function updateMailbox(input, client) {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+/**
+ * Deletes a mailbox. Only the mailbox itself goes: its folders and everything in them stay - and the address can't be used for a
+ * new mailbox - until that data is erased. `erase: true` (administrators only; anybody else is refused 403 before anything is
+ * deleted) also files that erasure in the same step, which the server then runs in the background; without it the data is left for
+ * `admin/leftoverMailboxApi.ts` to list and erase later.
+ */
+export function deleteMailbox(uid, version, options = {}, client) {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(uid)}?version=${version}${options.erase ? "&erase=true" : ""}`, { method: "DELETE" });
+}
+/** Lists quarantined mail for a mailbox the caller owns or has been granted; with `scope: "admin"` (admin console only), for any mailbox. */
+export function listQuarantine(mailboxUid, params = {}, client) {
+    return withClient(client, `/mail/quarantine?${buildQuery(params, { mailboxUid, ...scopeQuery(params) })}`);
+}
+/**
+ * Marks a quarantined entry released. This only updates the record's metadata — it does not re-inject the
+ * message into normal delivery (see `@rapidmx/restapi`'s NOTES.md for why that's an explicit non-goal here).
+ */
+export function releaseQuarantineEntry(uid, version, releasedByUserUid, client) {
+    return withClient(client, `/mail/quarantine/${encodeURIComponent(uid)}`, {
+        method: "PUT",
+        body: JSON.stringify({ uid, version, releasedAt: new Date().toISOString(), releasedByUserUid }),
+    });
+}
+/** Lists ingest-queue entries for a mailbox the caller owns or has been granted - useful for diagnosing stuck delivery; with
+ * `scope: "admin"` (admin console only), for any mailbox. */
+export function listIngestQueue(mailboxUid, params = {}, client) {
+    return withClient(client, `/mail/ingest-queue?${buildQuery(params, { mailboxUid, ...scopeQuery(params) })}`);
+}
+/** Fetches a mailbox's own ACL — its `records` are its owner's/delegates' grants (see BaseACLRoute). The server only answers a
+ * caller who holds full access to that mailbox as themselves (never through a trusted role): to list, grant or revoke a mailbox's
+ * members use `listMailboxAccess()`/`setMailboxAccess()`/`removeMailboxAccess()` (`mailboxAccessApi.ts`), which is also the
+ * audited way an administrator shares an ownerless mailbox. */
+export function getMailboxAcl(mailboxUid, client) {
+    return withClient(client, `/acls/${encodeURIComponent(mailboxUid)}`);
+}
+/**
+ * Grants (or replaces, if `userOrRoleId` already has a record) a delegate's access to a mailbox — the
+ * mechanism behind Exchange-style shared mailboxes. Read-modify-write against the ACL's own optimistic
+ * `version`, so concurrent grants can conflict; the caller should retry on a 409/version-mismatch.
+ */
+export async function grantMailboxAccess(mailboxUid, userOrRoleId, actions, client) {
+    const acl = await getMailboxAcl(mailboxUid, client);
+    const records = acl.records.filter((r) => r.userOrRoleId !== userOrRoleId);
+    records.push({ userOrRoleId, actions });
+    return withClient(client, `/acls/${encodeURIComponent(mailboxUid)}`, {
+        method: "PUT",
+        body: JSON.stringify({ uid: mailboxUid, version: acl.version, records }),
+    });
+}
+/** Revokes a delegate's access to a mailbox previously granted via `grantMailboxAccess`. */
+export async function revokeMailboxAccess(mailboxUid, userOrRoleId, client) {
+    const acl = await getMailboxAcl(mailboxUid, client);
+    const records = acl.records.filter((r) => r.userOrRoleId !== userOrRoleId);
+    return withClient(client, `/acls/${encodeURIComponent(mailboxUid)}`, {
+        method: "PUT",
+        body: JSON.stringify({ uid: mailboxUid, version: acl.version, records }),
+    });
+}
+/** Lists a mailbox's folders — visible to its owner, any delegate the mailbox is shared with, or (trusted) anyone. */
+export function listFolders(mailboxUid, client) {
+    return withClient(client, `/mail/folders?${buildQuery({ limit: 200 }, { mailboxUid })}`);
+}
+/** Creates a new folder — e.g. an additional `calendar`-type folder for multi-calendar support. Nothing
+ * about folder creation is type-restricted server-side (see the Phase 4 plan's own note on
+ * `BaseFolderRoute.create()`), so this is just a thin wrapper, not a new backend capability. */
+export function createFolder(input, client) {
+    return withClient(client, "/mail/folders", {
+        method: "POST",
+        body: JSON.stringify({ unreadCount: 0, totalCount: 0, ...input }),
+    });
+}
+export function updateFolder(input, client) {
+    return withClient(client, `/mail/folders/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+/**
+ * The most labels one list request may filter by, matching `@rapidmx/restapi`'s own
+ * `MAX_MESSAGE_LABEL_FILTER_UIDS` — a longer set is refused with a 400, so a label menu offering multiple
+ * selection should stop the user here rather than send it.
+ */
+export const MAX_MESSAGE_LABEL_FILTER = 20;
+/** Only the sort/filter params actually set, so a default list sends the same URL it always did. */
+export function messageListQuery(params) {
+    const query = {};
+    if (params.sortBy) {
+        query.sortBy = params.sortBy;
+    }
+    if (params.sortOrder) {
+        query.sortOrder = params.sortOrder;
+    }
+    if (params.filter) {
+        query.filter = params.filter;
+    }
+    // One comma-separated value, the only form the server parses. An empty selection sends no parameter at all
+    // rather than an empty one, so a filter menu with nothing ticked makes the request it always made.
+    if (params.labelUids?.length) {
+        query.labelUids = params.labelUids.join(",");
+    }
+    return query;
+}
+/**
+ * Lists messages in a folder — newest received first unless `sortBy`/`sortOrder` say otherwise, and unfiltered
+ * unless `filter`/`labelUids` say otherwise. All of them are applied by the *database*, over the whole folder
+ * rather than over the page this call happens to return, so `page`/`limit` stay correct under a filter and a
+ * sort. Ties are broken by `uid`, so a message never appears on two pages or on neither.
+ */
+export function listMessages(folderUid, params = {}, client) {
+    return withClient(client, `/mail/messages?${buildQuery(params, { folderUid, ...messageListQuery(params) })}`);
+}
+export function getMessage(uid, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(uid)}`);
+}
+/**
+ * Attempts to recall a message this mailbox previously sent — only valid for a message currently in
+ * Sent Items (enforced server-side). Asynchronous and best-effort: this composes and relays a control
+ * message to every original recipient, but the actual delete-if-still-unread mutation happens later on
+ * each recipient's own mail system — there is no synchronous "recalled" outcome to report back, and the
+ * only visible effect here is `recallRequestedAt` getting set on the response.
+ */
+export function recallMessage(uid, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(uid)}/recall`, { method: "POST" });
+}
+/**
+ * Moves a message into the mailbox's Archive folder (`FolderType.ARCHIVE`), lazily created on first use
+ * server-side — same pattern as Sent Items/Outbox, no client-side folder-creation step needed. Rejects
+ * (400, surfaced as an `ApiRequestError`) for a message currently in Drafts or Outbox. Idempotent —
+ * archiving an already-archived message is a no-op that still returns the message.
+ */
+export function archiveMessage(uid, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(uid)}/archive`, { method: "POST" });
+}
+/**
+ * Moves a message between the Focused and Other halves of the Inbox — Outlook's "Move to Other" gesture.
+ * With `applyToSender: true` ("Always move to Other"), also upserts a standing `FocusedInboxOverride` for
+ * every future message from the same sender (see `focusedInboxOverridesApi.ts`) in the same round trip.
+ */
+export function classifyMessage(uid, classifyAs, applyToSender = false, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(uid)}/classify`, {
+        method: "POST",
+        body: JSON.stringify({ classifyAs, applyToSender }),
+    });
+}
+/**
+ * Marks a message read/unread in place. `folderUid` must be included even though it isn't changing — every
+ * `Message` update is scoped by its owning folder (see `BaseScopedChildRoute`), and this framework's `PUT`
+ * routes replace the whole record rather than patch individual fields.
+ */
+export function setMessageRead(message, read, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(message.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify({ uid: message.uid, version: message.version, flags: { ...message.flags, read } }),
+    });
+}
+/** Flags/unflags a message in place — Outlook's flag-status toggle, and what `listMessages({ filter:
+ * "flagged" })` and `listFlaggedMessages()` select on. */
+export function setMessageFlagged(message, flagged, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(message.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify({ uid: message.uid, version: message.version, flags: { ...message.flags, flagged } }),
+    });
+}
+/** Moves a message into another folder of the same mailbox — how "Move to", "Archive" (to the Archive folder),
+ * "Report junk" (to Junk) and "Delete" (to Deleted Items) are all expressed. */
+export function moveMessage(message, folderUid, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(message.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify({ uid: message.uid, version: message.version, folderUid }),
+    });
+}
+/**
+ * Reports a message as junk, phishing or not junk - `POST /mail/messages/:uid/report`. The SERVER moves it (`junk` and `phishing` to the mailbox's Junk Email,
+ * `not_junk` to its Inbox; a message already there is not moved), records what was reported, teaches its spam filter (never for an encrypted message) and
+ * writes an audit entry; a caller needs no folder uid and no `version`. Rejects with a 400 for a message in Drafts or Outbox, a 403 without the right to change
+ * the message (or, for `alwaysTrustSender`, without full access to the mailbox), a 404 for an unknown message - and also for a server that predates the route,
+ * where a caller falls back to `moveMessage()`.
+ */
+export function reportMessage(uid, kind, options = {}, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(uid)}/report`, {
+        method: "POST",
+        body: JSON.stringify({ kind, ...(options.alwaysTrustSender ? { alwaysTrustSender: true } : {}) }),
+    });
+}
+/**
+ * The most updates `bulkUpdateMessages()` puts in one request, matching `@rapidmx/restapi`'s own
+ * `MAX_BULK_UPDATE` — a longer list is refused with a 400, so the helper below chunks rather than sending it.
+ */
+export const MAX_BULK_MESSAGE_UPDATE = 100;
+/**
+ * Applies `updates` through `PUT /mail/messages`, the bulk form of the single-message update — one request per
+ * `MAX_BULK_MESSAGE_UPDATE` updates instead of one per message, with every permission, folder and legal-hold
+ * check the single-message path makes.
+ *
+ * Deliberately NOT atomic, on either side of the wire: the server applies each element in order and the first
+ * failure (a stale `version`, a refused move) aborts the rest of *that* request, leaving the elements before it
+ * applied; this helper then stops and rejects rather than sending the remaining chunks. So a caller should
+ * refetch the list after a rejection instead of assuming nothing happened, and should send fresh `version`s -
+ * a bulk action over a stale selection is the common way to hit a 409. For a per-element outcome, call the
+ * single-message functions instead.
+ *
+ * Resolves with every message actually updated, in request order.
+ */
+export async function bulkUpdateMessages(updates, client) {
+    const updated = [];
+    for (let i = 0; i < updates.length; i += MAX_BULK_MESSAGE_UPDATE) {
+        const chunk = updates.slice(i, i + MAX_BULK_MESSAGE_UPDATE);
+        updated.push(...(await withClient(client, "/mail/messages", { method: "PUT", body: JSON.stringify(chunk) })));
+    }
+    return updated;
+}
+/** Marks a whole selection read/unread in one pass — see `bulkUpdateMessages()` for the failure semantics. */
+export function setMessagesRead(messages, read, client) {
+    return bulkUpdateMessages(messages.map((message) => ({ uid: message.uid, version: message.version, flags: { ...message.flags, read } })), client);
+}
+/** Flags/unflags a whole selection in one pass — see `bulkUpdateMessages()`. */
+export function setMessagesFlagged(messages, flagged, client) {
+    return bulkUpdateMessages(messages.map((message) => ({ uid: message.uid, version: message.version, flags: { ...message.flags, flagged } })), client);
+}
+/** Moves a whole selection into `folderUid` — bulk Move, Archive, Report junk and Delete (to Deleted Items)
+ * are all this call with a different target folder. See `bulkUpdateMessages()`. */
+export function moveMessages(messages, folderUid, client) {
+    return bulkUpdateMessages(messages.map((message) => ({ uid: message.uid, version: message.version, folderUid })), client);
+}
+/** Sets the full `labelUids` list on a whole selection — see `setMessageLabels()` and `bulkUpdateMessages()`. */
+export function setMessagesLabels(messages, labelUids, client) {
+    return bulkUpdateMessages(messages.map((message) => ({ uid: message.uid, version: message.version, labelUids })), client);
+}
+/** Sets a message's full `labelUids` list (not an add/remove delta - the caller computes the complete
+ * new set, same convention as `Note`/`Task` label-like fields elsewhere in restapi). Deleting a label
+ * elsewhere already strips it server-side from every message (`labelsApi.ts#deleteLabel()`'s own doc
+ * comment) - this is only for a user explicitly applying/removing labels on one message. */
+export function setMessageLabels(message, labelUids, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(message.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify({ uid: message.uid, version: message.version, labelUids }),
+    });
+}
+/**
+ * Cancels a scheduled send by moving the message out of Outbox into `draftsFolderUid` (the mailbox's Drafts
+ * folder, which the caller resolves). The server clears `scheduledSendTime` itself on any move out of Outbox;
+ * the `null` sent here is accepted and ignored.
+ */
+export function cancelScheduledSend(message, draftsFolderUid, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(message.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify({ uid: message.uid, version: message.version, scheduledSendTime: null, folderUid: draftsFolderUid }),
+    });
+}
+/**
+ * Sets a draft's `requestReceipt` ahead of calling `sendMessage()`, overriding the mailbox's own
+ * `alwaysRequestReceiptInternal`/`External` defaults for this one message — same ordinary-`PUT`-before-
+ * `send()` convention.
+ */
+export function setMessageRequestReceipt(message, requestReceipt, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(message.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify({ uid: message.uid, version: message.version, requestReceipt }),
+    });
+}
+/**
+ * Thrown by `setMessageVerificationSeal()` when restapi answers `409`: the message already carries a different seal the
+ * server won't replace (it replaces one only when the stored seal's generation is older than the vault's current
+ * `masterKeyGeneration` and the request's generation equals the current one). Still an `ApiRequestError` (`status` 409).
+ * A caller writing seals best effort should ignore it.
+ */
+export class VerificationSealConflictError extends ApiRequestError {
+    constructor(message, code) {
+        super(message, 409, code);
+        this.name = "VerificationSealConflictError";
+    }
+}
+/**
+ * Stores a verification seal on a message (`PUT /mail/messages/:id/verification-seal` with
+ * `{ seal, masterKeyGeneration }`), normally `MessageSecurityResult.sealToWrite`'s two fields from
+ * `crypto/messageSecurity.ts`'s `evaluateMessageSecurityWithSeal()`. Resolves with the updated message; storing the
+ * identical seal again succeeds. Rejects with `VerificationSealConflictError` on `409` (a different seal is stored and
+ * isn't replaceable - see that class), and a plain `ApiRequestError` for `400` (an invalid seal or generation) and
+ * `403`/`404`.
+ */
+export async function setMessageVerificationSeal(messageUid, seal, masterKeyGeneration, client) {
+    try {
+        return await withClient(client, `/mail/messages/${encodeURIComponent(messageUid)}/verification-seal`, {
+            method: "PUT",
+            body: JSON.stringify({ seal, masterKeyGeneration }),
+        });
+    }
+    catch (err) {
+        if (err instanceof ApiRequestError && err.status === 409) {
+            throw new VerificationSealConflictError(err.message, err.code);
+        }
+        throw err;
+    }
+}
+/** Sends a delivery/read receipt this mailbox held pending the owner's explicit approval (see
+ * `Message.deliveryReceiptPending`/`readReceiptPending`). */
+export function approveReceipt(uid, type, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(uid)}/receipt/approve`, {
+        method: "POST",
+        body: JSON.stringify({ type }),
+    });
+}
+/** Permanently declines a pending receipt — no later re-prompt for that same event. */
+export function declineReceipt(uid, type, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(uid)}/receipt/decline`, {
+        method: "POST",
+        body: JSON.stringify({ type }),
+    });
+}
+/** Lists the attachments belonging to a single message. */
+export function listAttachments(folderUid, messageUid, client) {
+    return withClient(client, `/mail/attachments?${buildQuery({ limit: 200 }, { folderUid, messageUid })}`);
+}
+/** The URL to download/display an attachment's binary content — not fetched via `apiFetch`, used directly as
+ * a link/image `href`/`src`. Honors `configureApiBaseUrl()` (see `apiUrl()`). */
+export function attachmentContentUrl(uid) {
+    return apiUrl(`/mail/attachments/${encodeURIComponent(uid)}/content`);
+}
+/**
+ * Uploads a file's raw bytes as a new attachment on a not-yet-sent draft. Bypasses `apiFetch` — that helper
+ * always forces `Content-Type: application/json`, which would corrupt binary content; this sends the file's
+ * own bytes/type directly instead, matching `BaseAttachmentRoute.upload`'s expectation of a raw request body.
+ */
+export async function uploadAttachment(messageUid, file) {
+    const params = new URLSearchParams({ messageUid, filename: file.name, mimeType: file.type || "application/octet-stream" });
+    const res = await fetch(apiUrl(`/mail/attachments/upload?${params.toString()}`), {
+        method: "POST",
+        credentials: "include",
+        headers: withCsrfHeader({ "Content-Type": file.type || "application/octet-stream" }),
+        body: file,
+    });
+    const contentType = res.headers.get("content-type") ?? "";
+    const responseBody = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
+    if (!res.ok) {
+        const message = (responseBody && (responseBody.message || responseBody.error)) || res.statusText || "Upload failed.";
+        throw new ApiRequestError(message, res.status, responseBody?.code);
+    }
+    return responseBody;
+}
+/**
+ * Creates a blank draft `Message` in the given folder (normally the mailbox's Drafts folder) to compose into.
+ *
+ * A reply MUST pass `threading` (build it with `buildReplyThreading()` from the message being replied to).
+ * `@rapidmx/restapi` writes those values into the `In-Reply-To`/`References` headers of the MIME it relays and
+ * groups the message into the replied-to message's conversation; a reply created without them is relayed with no
+ * threading headers at all, and every recipient - and the sender's own Sent Items copy - files it as a brand-new
+ * conversation. Nothing else recovers them: this server composes the MIME from the recipients, subject and HTML
+ * passed to `assembleDraft()`, which say nothing about what is being replied to.
+ */
+export function createDraft(mailboxUid, folderUid, threading, client) {
+    return withClient(client, "/mail/messages", {
+        method: "POST",
+        body: JSON.stringify({
+            mailboxUid,
+            folderUid,
+            messageId: `${crypto.randomUUID()}@webmail`,
+            ...(threading?.inReplyTo ? { inReplyTo: threading.inReplyTo } : {}),
+            ...(threading?.references?.length ? { references: threading.references } : {}),
+        }),
+    });
+}
+/** Deletes a message - e.g. an unsent draft that's no longer needed because compose switched to a different
+ * sending mailbox. */
+export function deleteMessage(uid, version, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}
+/**
+ * Permanently deletes one message - `DELETE /mail/messages/:uid?purge=true`, the hard delete: the row and its search
+ * document are gone and it cannot be restored, unlike `deleteMessage()` (a soft delete the server can bring back) or a
+ * move into Deleted Items. Whoever may delete in the message's folder may do this - the mailbox's owner, or a delegate
+ * granted `delete` - there is nothing administrative about it.
+ *
+ * Takes no `version`: one that no longer matches (another device flipped a flag since the list was fetched) would make
+ * the server answer "not found", which is no reason to keep a message the reader has asked to erase. Refused with a
+ * `409` for a message under an active legal hold (the response's message says so) or with a send in flight, and with a
+ * `403` without the `delete` grant. Nothing about the message changes when it is refused, so a caller deleting several
+ * reports each refusal and carries on with the rest.
+ */
+export function purgeMessage(uid, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(uid)}?purge=true`, { method: "DELETE" });
+}
+/**
+ * Permanently deletes every message in a folder in one request - `DELETE /mail/messages?folderUid=` (the collection
+ * `truncate`, always a hard delete). All or nothing: the server checks every message for a legal hold first and refuses
+ * the whole request with a `409` if any is held, and with a `403` unless the caller holds the `truncate` grant on the
+ * mailbox (its owner or a manager - not a delegate who may merely delete). Resolves without saying how many messages
+ * went, so a caller that needs to says so from what it knew. Messages already soft-deleted are not part of it.
+ *
+ * After a refusal, fall back to `purgeMessage()` per message: that removes what may be removed and says which may not.
+ */
+export function emptyFolder(folderUid, client) {
+    return withClient(client, `/mail/messages?${new URLSearchParams({ folderUid }).toString()}`, { method: "DELETE" });
+}
+/**
+ * Assembles a draft's structured compose input (recipients/subject/HTML body, plus whatever attachments have
+ * already been `uploadAttachment()`-ed onto it) into RFC 5322 MIME and stores it as the draft's `bodyBlobKey`
+ * — see `BaseMailComposeRoute` (this app's own compose-assembly glue, since `@rapidmx/restapi`'s `send()`
+ * itself does no MIME composition). Does not send the message.
+ */
+export function assembleDraft(messageUid, input, client) {
+    return withClient(client, `/mail/compose/${encodeURIComponent(messageUid)}/assemble`, {
+        method: "POST",
+        body: JSON.stringify(input),
+    });
+}
+/**
+ * Stores an already-signed/encrypted draft's raw MIME source as its `bodyBlobKey`, completely
+ * unmodified — the E2E counterpart to `assembleDraft()`, for when the message body was built
+ * client-side via `crypto/smimeMessage.ts` rather than from plain HTML. Does not send the message. A
+ * draft assembled this way cannot carry file attachments yet — see `BaseMailComposeRoute.assembleRaw()`'s
+ * own doc comment in `server`.
+ */
+export function assembleDraftRaw(messageUid, input, client) {
+    return withClient(client, `/mail/compose/${encodeURIComponent(messageUid)}/assemble-raw`, {
+        method: "POST",
+        body: JSON.stringify(input),
+    });
+}
+/**
+ * Scans, relays, and moves an already-assembled draft into Sent Items - or, with a future
+ * `scheduledSendTime`, queues it in Outbox for `@rapidmx/restapi`'s `ScheduledSendJob`. A message already in
+ * Outbox or Sent Items is refused (409); move it back to Drafts first.
+ */
+export function sendMessage(messageUid, options, client) {
+    return withClient(client, `/mail/messages/${encodeURIComponent(messageUid)}/send`, {
+        method: "POST",
+        ...(options?.scheduledSendTime ? { body: JSON.stringify({ scheduledSendTime: options.scheduledSendTime }) } : {}),
+    });
+}
+/**
+ * Sends an already-assembled draft *in the background*: `POST /mail/messages/:id/send` with `{ background: true }`. The server
+ * checks the message, moves it into Outbox with a lease and answers `202 { status: "queued", message }` at once - relaying happens
+ * afterwards, and its outcome is published as push events on the mailbox's, Outbox's and Sent Items' channels rather than answered
+ * here. Rejects with the server's own error (validation, permissions: the message was not queued). A server that has no queue
+ * relays first and answers with the message, which resolves as `{ queued: false }` - as does a message class with no send job, which
+ * answers a background send `501`: it is then sent the ordinary, synchronous way.
+ */
+export async function queueMessageSend(messageUid, client) {
+    let result;
+    try {
+        result = await withClient(client, `/mail/messages/${encodeURIComponent(messageUid)}/send`, { method: "POST", body: JSON.stringify({ background: true }) });
+    }
+    catch (err) {
+        if (err instanceof ApiRequestError && err.status === 501) {
+            return { queued: false, message: await sendMessage(messageUid, undefined, client) };
+        }
+        throw err;
+    }
+    const queued = result;
+    if (queued.status === "queued" && queued.message) {
+        return { queued: true, message: queued.message };
+    }
+    return { queued: false, message: result };
+}
+/**
+ * Fetches a message's raw RFC 5322 MIME source — for client-side E2E decrypt/signature-verification
+ * only (`crypto/smimeMessage.ts`), never for display. Bypasses `apiFetch()` (which only ever decodes a
+ * JSON response body): this server-local route (`BaseMessageRawContentRoute.ts` in `server`, mounted
+ * alongside `@rapidmx/restapi`'s own `MessageRoute`) returns `message/rfc822`, not JSON — the one thing
+ * that library's own `GET /:id/content` deliberately never serves (see that route's own doc comment).
+ *
+ * Returns a *binary string* - the response bytes decoded as Latin-1, exactly one character per byte -
+ * rather than `res.text()`'s UTF-8 decoding, which would replace every invalid byte of a non-UTF-8 8bit
+ * part with U+FFFD before its own `charset` is known and break any signature over those bytes. Pass it
+ * straight to `evaluateMessageSecurity()` (see `crypto/mime.ts`'s doc comment on binary strings); it is
+ * not display text.
+ */
+export async function getMessageRawContent(messageUid) {
+    const res = await fetch(apiUrl(`/mail/messages/${encodeURIComponent(messageUid)}/raw`), { credentials: "include" });
+    if (!res.ok) {
+        const contentType = res.headers.get("content-type") ?? "";
+        const body = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
+        const message = (body && (body.message || body.error)) || res.statusText || "Could not load this message's raw content.";
+        throw new ApiRequestError(message, res.status, body?.code);
+    }
+    // Not `new TextDecoder("latin1")`: WHATWG maps that label to windows-1252, which remaps 0x80-0x9F and so
+    // isn't byte-preserving. `bytesToBinaryString()` is an exact byte -> code unit conversion.
+    return bytesToBinaryString(new Uint8Array(await res.arrayBuffer()));
+}
+/**
+ * Trusted-role-only: starts an admin "log in as user" session. In production this calls auth-server
+ * directly (not this app's own API) since only auth-server can mint a token carrying `userUid`'s real
+ * roles/scopes the way its own sign-in flow would — see `@rapidrest/auth`'s `BaseImpersonationRoute` and
+ * this repo's `.claude/NOTES.md`. The browser's `jwt` cookie is swapped for the freshly-minted token, and
+ * the caller's own session is stashed (`jwt_impersonator`) so `stopImpersonating()` can restore it later.
+ * The caller is responsible for navigating to `/` afterward — this call only swaps the cookie, it doesn't
+ * redirect.
+ *
+ * @param impersonationBaseUrl The origin to call — the real auth-server in production, or `""` under
+ * `yarn dev` (see `AdminConsoleRoute`/`wwwRoute`'s `fetchProps`) to instead call this app's own local
+ * dev-only endpoint (`DevImpersonationRoute`), since a real auth-server isn't running locally.
+ */
+export function impersonateUser(impersonationBaseUrl, userUid) {
+    const init = { method: "POST", body: JSON.stringify({ userUid }) };
+    return impersonationBaseUrl
+        ? authApiFetch(impersonationBaseUrl, "/admin/impersonate", init)
+        : apiFetch("/admin/impersonate", init);
+}
+/**
+ * Ends an active impersonation session, restoring the admin's own — a no-op (`restored: false`) if none is
+ * active. POST, not GET: this mutates state (swaps the active `jwt` cookie back), and a state-changing GET
+ * is exploitable via a bare navigation — no form or script required at all — bypassing CSRF defenses
+ * entirely, since they only ever apply to non-safe methods. See `@rapidrest/auth`'s `BaseImpersonationRoute`.
+ */
+export function stopImpersonating(impersonationBaseUrl) {
+    return impersonationBaseUrl
+        ? authApiFetch(impersonationBaseUrl, "/admin/impersonate/stop", { method: "POST" })
+        : apiFetch("/admin/impersonate/stop", { method: "POST" });
+}

package/dist/lib/mail/mailDetailHooks.d.ts

@@ -0,0 +1,10 @@
+import { Attachment, Message } from "./mailApi.js";
+/** Loads a message's attachments (only when it actually has any) — shared by every place a message is read. */
+export declare function useMessageAttachments(message: Message | null): Attachment[];
+/**
+ * Marks a message read the first time it's viewed. `onUpdated` receives the server's updated copy — the
+ * desktop reading pane patches its in-memory message list with it; the mobile detail route (which has no
+ * list to patch) just replaces its own local `message` state. Best-effort: a failed update shouldn't block
+ * reading the message, matching this app's existing `handleSelect` behavior.
+ */
+export declare function useMarkMessageRead(message: Message | null, onUpdated: (updated: Message) => void): void;