@rapidmx/web-client 0.20.0 → 0.22.0

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

@@ -0,0 +1,80 @@
+/**
+ * Typed wrapper over `@rapidmx/restapi`'s conversation endpoints (`BaseMessageRoute.conversations()` and
+ * `conversationMessages()`) — the parent rows of a nested, Outlook-style conversation list, and the child rows
+ * one expands into. Conversations are RFC 5322 References/In-Reply-To threads (`Message.conversationId`),
+ * computed fresh on every call — a `ConversationSummary` is never itself persisted.
+ */
+import { ApiClient } from "../util/api.js";
+import { Message, MessageListFilter, Recipient } from "./mailApi.js";
+export interface ConversationSummary {
+    conversationId: string;
+    /** The most recent message's subject line. */
+    subject: string;
+    /** Every message in this conversation, oldest to newest. */
+    messageUids: string[];
+    /** Every folder (deduped) this conversation has a message in — a conversation can span folders,
+     * e.g. an Inbox message and the Sent Items copy of its reply. */
+    folderUids: string[];
+    messageCount: number;
+    unreadCount: number;
+    /** The most recent message's `receivedDate` — what the list is sorted by (newest first). */
+    latestDate: string;
+    /** Every distinct participant (deduped by address) across every message in the conversation. */
+    participants: Recipient[];
+    hasAttachments: boolean;
+    /** `true` if any message in the conversation is flagged. */
+    flagged: boolean;
+    /** The most recent message's `uid` — what a collapsed conversation row stands for, so it can be opened
+     * without expanding the conversation first. */
+    latestMessageUid: string;
+    /** The most recent message's sender. */
+    latestFrom: Recipient;
+    /** The most recent message's `bodyPreview` — the snippet a collapsed row shows. */
+    latestPreview: string;
+    /** The most recent message's folder. */
+    latestFolderUid: string;
+    /** The iTIP `METHOD` of the calendar file the most recent message carries (`Message.meetingMethod`) - `"REQUEST"`, `"REPLY"`,
+     * `"CANCEL"`, `"PUBLISH"`, `"COUNTER"` or `""`. Absent, or `null` from the server's SQL, when it carries none. Lets a collapsed row mark a
+     * meeting request without opening the conversation. */
+    latestMeetingMethod?: string | null;
+    /** What the reader answered that meeting request with (`Message.meetingResponse`). Absent, or `null`, when unanswered. */
+    latestMeetingResponse?: "accepted" | "tentative" | "declined" | null;
+}
+/**
+ * How many of a mailbox's *messages* the server reads, newest first, to build these groups — restapi's
+ * `mail:conversations:scan_limit` default, and also the cap and default for `limit` below. A conversation whose
+ * older messages fall outside that window reports only the part inside it.
+ */
+export declare const CONVERSATION_SCAN_LIMIT = 500;
+export interface ConversationListParams {
+    /** Restricts both the scan and the grouping to one folder — a per-folder conversation view. Without it a
+     * conversation spans every folder in the mailbox. */
+    folderUid?: string;
+    /** The same named filters `listMessages()` takes, applied to the *messages* before they are grouped: so
+     * `unread` yields each conversation's unread messages, and only the conversations that have any. */
+    filter?: MessageListFilter;
+    /** The label filter `listMessages()` takes (`Label.uid`s; a message matching ANY of them), applied at the
+     * same point as `filter` and ANDed with it — so a conversation appears if any of its messages carries any
+     * of these labels, and reports only those messages. At most `MAX_MESSAGE_LABEL_FILTER` of them. */
+    labelUids?: string[];
+    /** Zero-based. */
+    page?: number;
+    /** Capped at `CONVERSATION_SCAN_LIMIT`, which is also the default. */
+    limit?: number;
+}
+/** Lists a mailbox's conversations, newest activity first. Computed mailbox-wide unless `folderUid` narrows
+ * them — folder scope is a filter here, not part of the endpoint. */
+export declare function listConversations(mailboxUid: string, params?: ConversationListParams, client?: ApiClient): Promise<ConversationSummary[]>;
+/** Paging for `listConversationMessages()`. The server defaults `limit` to 100 and caps it at 500. */
+export interface ConversationMessagesParams {
+    page?: number;
+    limit?: number;
+}
+/**
+ * One conversation's messages, oldest first, across every folder in the mailbox — the expanded children of a
+ * conversation row, in one request rather than one per `messageUids` entry.
+ *
+ * `conversationId` is the summary's own `conversationId`, which for a message belonging to no thread is that
+ * message's `uid`; the server resolves either.
+ */
+export declare function listConversationMessages(mailboxUid: string, conversationId: string, params?: ConversationMessagesParams, client?: ApiClient): Promise<Message[]>;

package/dist/lib/mail/conversationsApi.js

@@ -0,0 +1,44 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrapper over `@rapidmx/restapi`'s conversation endpoints (`BaseMessageRoute.conversations()` and
+ * `conversationMessages()`) — the parent rows of a nested, Outlook-style conversation list, and the child rows
+ * one expands into. Conversations are RFC 5322 References/In-Reply-To threads (`Message.conversationId`),
+ * computed fresh on every call — a `ConversationSummary` is never itself persisted.
+ */
+import { withClient } from "../util/api.js";
+/**
+ * How many of a mailbox's *messages* the server reads, newest first, to build these groups — restapi's
+ * `mail:conversations:scan_limit` default, and also the cap and default for `limit` below. A conversation whose
+ * older messages fall outside that window reports only the part inside it.
+ */
+export const CONVERSATION_SCAN_LIMIT = 500;
+/** `?mailboxUid=` plus whichever optional params were actually set, each URL-encoded. */
+function conversationQuery(mailboxUid, params) {
+    const query = new URLSearchParams({ mailboxUid });
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== "") {
+            query.set(key, String(value));
+        }
+    }
+    return query.toString();
+}
+/** Lists a mailbox's conversations, newest activity first. Computed mailbox-wide unless `folderUid` narrows
+ * them — folder scope is a filter here, not part of the endpoint. */
+export function listConversations(mailboxUid, params = {}, client) {
+    const { labelUids, ...rest } = params;
+    // One comma-separated value, as `messageListQuery()` sends it; an empty selection sends no parameter.
+    return withClient(client, `/mail/messages/conversations?${conversationQuery(mailboxUid, { ...rest, labelUids: labelUids?.length ? labelUids.join(",") : undefined })}`);
+}
+/**
+ * One conversation's messages, oldest first, across every folder in the mailbox — the expanded children of a
+ * conversation row, in one request rather than one per `messageUids` entry.
+ *
+ * `conversationId` is the summary's own `conversationId`, which for a message belonging to no thread is that
+ * message's `uid`; the server resolves either.
+ */
+export function listConversationMessages(mailboxUid, conversationId, params = {}, client) {
+    return withClient(client, `/mail/messages/conversations/${encodeURIComponent(conversationId)}?${conversationQuery(mailboxUid, { ...params })}`);
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s GDPR data-portability export (`BaseDataExportRoute`, mounted
+ * at `mail/data-export-requests`). `create()` is both self-service (a mailbox owner exports their own
+ * mail) and admin-mediated (a trusted caller may supply an explicit `mailboxUid`) — an ordinary caller's
+ * own mailbox is always used regardless of what they send, only a trusted caller's supplied `mailboxUid`
+ * is honored. Export runs asynchronously (restapi's own `DataExportJob`, not this client) — `create()`
+ * only stages a `pending` request; poll `getExportRequest()`/`listExportRequests()` for `status` to
+ * become `"ready"` (or `"failed"`) before offering the download.
+ */
+import { ApiClient } from "../util/api.js";
+import { RequestListParams } from "../util/apiQuery.js";
+export type { RequestListParams };
+export type DataExportFormat = "json" | "mbox";
+/** `processing` while a worker is building the export (restapi's `DataExportJob` claims `pending` requests). */
+export type DataExportStatus = "pending" | "processing" | "ready" | "failed";
+export interface DataExportRequest {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    requestedByUserUid: string;
+    format: DataExportFormat;
+    status: DataExportStatus;
+    blobKey?: string;
+    errorMessage?: string;
+    /** How many times the server job has claimed this request into `"processing"` (a stalled claim is reclaimed
+     * back to `"pending"` until the job's max attempts, then marked `"failed"`). */
+    processingAttempts?: number;
+}
+export interface CreateDataExportRequestInput {
+    format: DataExportFormat;
+    /** Only honored when the caller is a trusted admin — an ordinary caller's own mailbox is always
+     * used, regardless of what (if anything) is supplied here. */
+    mailboxUid?: string;
+}
+/** `client`, given by every function below that isn't a plain URL builder, 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 createExportRequest(input: CreateDataExportRequestInput, client?: ApiClient): Promise<DataExportRequest>;
+/** A trusted caller sees every request; anyone else sees only their own (`requestedByUserUid`). Newest
+ * first; `params` pages through them (`limit` capped at 500 server-side). */
+export declare function listExportRequests(params?: RequestListParams, client?: ApiClient): Promise<DataExportRequest[]>;
+export declare function getExportRequest(uid: string, client?: ApiClient): Promise<DataExportRequest>;
+/** A plain URL, not a fetch wrapper — the server streams the export's raw bytes back with its own
+ * `content-disposition: attachment` header, so a caller renders this directly as `<a href={...}>`
+ * (the browser's own native download, no JS fetch/blob needed) — same pattern `mailApi.ts`'s
+ * `attachmentContentUrl()` already establishes. 404s until `status === "ready"`. */
+export declare function exportRequestDownloadUrl(uid: string): string;

package/dist/lib/mail/dataExportApi.js

@@ -0,0 +1,40 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s GDPR data-portability export (`BaseDataExportRoute`, mounted
+ * at `mail/data-export-requests`). `create()` is both self-service (a mailbox owner exports their own
+ * mail) and admin-mediated (a trusted caller may supply an explicit `mailboxUid`) — an ordinary caller's
+ * own mailbox is always used regardless of what they send, only a trusted caller's supplied `mailboxUid`
+ * is honored. Export runs asynchronously (restapi's own `DataExportJob`, not this client) — `create()`
+ * only stages a `pending` request; poll `getExportRequest()`/`listExportRequests()` for `status` to
+ * become `"ready"` (or `"failed"`) before offering the download.
+ */
+import { apiUrl, withClient } from "../util/api.js";
+import { buildRequestListQuery } from "../util/apiQuery.js";
+/** `client`, given by every function below that isn't a plain URL builder, 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 createExportRequest(input, client) {
+    return withClient(client, `/mail/data-export-requests`, {
+        method: "POST",
+        body: JSON.stringify(input),
+    });
+}
+/** A trusted caller sees every request; anyone else sees only their own (`requestedByUserUid`). Newest
+ * first; `params` pages through them (`limit` capped at 500 server-side). */
+export function listExportRequests(params = {}, client) {
+    return withClient(client, `/mail/data-export-requests${buildRequestListQuery(params)}`);
+}
+export function getExportRequest(uid, client) {
+    return withClient(client, `/mail/data-export-requests/${encodeURIComponent(uid)}`);
+}
+/** A plain URL, not a fetch wrapper — the server streams the export's raw bytes back with its own
+ * `content-disposition: attachment` header, so a caller renders this directly as `<a href={...}>`
+ * (the browser's own native download, no JS fetch/blob needed) — same pattern `mailApi.ts`'s
+ * `attachmentContentUrl()` already establishes. 404s until `status === "ready"`. */
+export function exportRequestDownloadUrl(uid) {
+    return apiUrl(`/mail/data-export-requests/${encodeURIComponent(uid)}/download`);
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `BaseDirectoryRoute` - recipient suggestions for compose. `GET
+ * /mail/directory` searches the server's mailboxes (people, shared mailboxes, rooms and equipment) and distribution
+ * lists; `GET /mail/directory/contacts` searches the caller's own contacts. Both match every word of the query against
+ * the start of a name word or of an address, and return only a display name, an address and a kind.
+ */
+import { ApiClient } from "../util/api.js";
+/** What a suggestion names. `"contact"` comes from the caller's contacts, everything else from the server directory. */
+export type RecipientSuggestionKind = "user" | "shared" | "room" | "equipment" | "list" | "contact";
+export interface RecipientSuggestion {
+    displayName: string;
+    address: string;
+    kind: RecipientSuggestionKind;
+}
+/** The shortest trimmed query the server searches for - shorter ones resolve to `[]` without a request. */
+export declare const RECIPIENT_SUGGESTION_MIN_QUERY_LENGTH = 2;
+/** The longest query the server accepts; longer ones are cut to this length. */
+export declare const RECIPIENT_SUGGESTION_MAX_QUERY_LENGTH = 100;
+/** The server's own default and cap for `limit`. */
+export declare const RECIPIENT_SUGGESTION_DEFAULT_LIMIT = 8;
+export declare const RECIPIENT_SUGGESTION_MAX_LIMIT = 20;
+export interface RecipientSuggestionOptions {
+    /** At most this many entries (the server caps it at `RECIPIENT_SUGGESTION_MAX_LIMIT`). */
+    limit?: number;
+    /** Aborts the request, rejecting with the fetch's `AbortError`. */
+    signal?: AbortSignal;
+}
+export interface ContactSuggestionOptions extends RecipientSuggestionOptions {
+    /** Also search this mailbox's contacts (e.g. the shared mailbox being composed from) when the caller may read it.
+     * The caller's own mailboxes are always searched. */
+    mailboxUid?: 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. */
+/** Searches the server directory. Rejects with a 403 `ApiRequestError` for a caller without a mailbox on the server,
+ * and a 429 one when the caller searches too often. */
+export declare function searchDirectory(query: string, options?: RecipientSuggestionOptions, client?: ApiClient): Promise<RecipientSuggestion[]>;
+/** Searches the caller's contacts (every address of a contact whose name matches, or the addresses that match). */
+export declare function searchContactSuggestions(query: string, options?: ContactSuggestionOptions, client?: ApiClient): Promise<RecipientSuggestion[]>;
+/** Contacts first, then directory entries, without repeating an address (compared case-insensitively; the first
+ * occurrence wins), at most `limit`. */
+export declare function mergeRecipientSuggestions(contacts: RecipientSuggestion[], directory: RecipientSuggestion[], limit?: number): RecipientSuggestion[];
+/**
+ * Contacts and directory suggestions for `query`, merged by `mergeRecipientSuggestions()`. Either source failing (a 403
+ * directory for a caller with no mailbox here, a 429, a network error) still returns the other's entries; only when
+ * both fail does this reject, with the contacts error. An aborted `signal` always rejects with the `AbortError`.
+ */
+export declare function fetchRecipientSuggestions(query: string, options?: ContactSuggestionOptions, client?: ApiClient): Promise<RecipientSuggestion[]>;

package/dist/lib/mail/directoryApi.js

@@ -0,0 +1,101 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `BaseDirectoryRoute` - recipient suggestions for compose. `GET
+ * /mail/directory` searches the server's mailboxes (people, shared mailboxes, rooms and equipment) and distribution
+ * lists; `GET /mail/directory/contacts` searches the caller's own contacts. Both match every word of the query against
+ * the start of a name word or of an address, and return only a display name, an address and a kind.
+ */
+import { ApiRequestError, withClient } from "../util/api.js";
+/** The shortest trimmed query the server searches for - shorter ones resolve to `[]` without a request. */
+export const RECIPIENT_SUGGESTION_MIN_QUERY_LENGTH = 2;
+/** The longest query the server accepts; longer ones are cut to this length. */
+export const RECIPIENT_SUGGESTION_MAX_QUERY_LENGTH = 100;
+/** The server's own default and cap for `limit`. */
+export const RECIPIENT_SUGGESTION_DEFAULT_LIMIT = 8;
+export const RECIPIENT_SUGGESTION_MAX_LIMIT = 20;
+/** The trimmed query to send, or `undefined` when it's too short to search. */
+function normalizeQuery(query) {
+    const trimmed = query.trim().slice(0, RECIPIENT_SUGGESTION_MAX_QUERY_LENGTH).trim();
+    return trimmed.length >= RECIPIENT_SUGGESTION_MIN_QUERY_LENGTH ? trimmed : undefined;
+}
+/** Keeps only well-formed entries of a response. */
+function wellFormed(body) {
+    return Array.isArray(body)
+        ? body
+            .filter((entry) => entry && typeof entry.address === "string" && entry.address.length > 0)
+            .map((entry) => ({
+            displayName: typeof entry.displayName === "string" ? entry.displayName : "",
+            address: entry.address,
+            kind: entry.kind,
+        }))
+        : [];
+}
+async function fetchSuggestions(path, query, params, signal, client) {
+    const q = normalizeQuery(query);
+    if (q === undefined) {
+        return [];
+    }
+    const search = new URLSearchParams({ q });
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined) {
+            search.set(key, value);
+        }
+    }
+    return wellFormed(await withClient(client, `${path}?${search.toString()}`, signal ? { signal } : {}));
+}
+/** `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. */
+/** Searches the server directory. Rejects with a 403 `ApiRequestError` for a caller without a mailbox on the server,
+ * and a 429 one when the caller searches too often. */
+export function searchDirectory(query, options = {}, client) {
+    return fetchSuggestions("/mail/directory", query, { limit: options.limit?.toString() }, options.signal, client);
+}
+/** Searches the caller's contacts (every address of a contact whose name matches, or the addresses that match). */
+export function searchContactSuggestions(query, options = {}, client) {
+    return fetchSuggestions("/mail/directory/contacts", query, { limit: options.limit?.toString(), mailboxUid: options.mailboxUid }, options.signal, client);
+}
+/** Contacts first, then directory entries, without repeating an address (compared case-insensitively; the first
+ * occurrence wins), at most `limit`. */
+export function mergeRecipientSuggestions(contacts, directory, limit = RECIPIENT_SUGGESTION_DEFAULT_LIMIT) {
+    const seen = new Set();
+    const result = [];
+    for (const entry of [...contacts, ...directory]) {
+        const key = entry.address.trim().toLowerCase();
+        if (result.length >= limit) {
+            break;
+        }
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(entry);
+        }
+    }
+    return result;
+}
+function isAbort(error) {
+    return error?.name === "AbortError";
+}
+/**
+ * Contacts and directory suggestions for `query`, merged by `mergeRecipientSuggestions()`. Either source failing (a 403
+ * directory for a caller with no mailbox here, a 429, a network error) still returns the other's entries; only when
+ * both fail does this reject, with the contacts error. An aborted `signal` always rejects with the `AbortError`.
+ */
+export async function fetchRecipientSuggestions(query, options = {}, client) {
+    const limit = options.limit ?? RECIPIENT_SUGGESTION_DEFAULT_LIMIT;
+    const [contacts, directory] = await Promise.allSettled([
+        searchContactSuggestions(query, { ...options, limit }, client),
+        searchDirectory(query, { limit, signal: options.signal }, client),
+    ]);
+    for (const outcome of [contacts, directory]) {
+        if (outcome.status === "rejected" && isAbort(outcome.reason)) {
+            throw outcome.reason;
+        }
+    }
+    if (contacts.status === "rejected" && directory.status === "rejected") {
+        throw contacts.reason instanceof Error ? contacts.reason : new ApiRequestError("Suggestions couldn't be loaded.", 0);
+    }
+    return mergeRecipientSuggestions(contacts.status === "fulfilled" ? contacts.value : [], directory.status === "fulfilled" ? directory.value : [], limit);
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s GDPR Article 17 ("right to erasure") request
+ * (`BaseDataSubjectErasureRequestRoute`, mounted at `mail/erasure-requests`). Unlike
+ * `dataExportApi.ts`/`mailboxImportApi.ts`, `create()` is self-service only — there is no
+ * admin-on-behalf-of path, and no `mailboxUid` parameter to override; it is always the caller's own
+ * mailbox. `approve()`/`deny()` are trusted-admin-only server-side. The actual destructive cascade is
+ * asynchronous (restapi's own `ErasureExecutionJob`, not this client) and irreversible once it runs — an
+ * approved request 409s during approval, and is retried indefinitely (never failed) by the job itself,
+ * while the target mailbox is a custodian on an active legal hold.
+ */
+import { ApiClient } from "../util/api.js";
+import { RequestListParams } from "../util/apiQuery.js";
+export type { RequestListParams };
+export type DataSubjectErasureStatus = "pending" | "approved" | "in_progress" | "denied" | "completed";
+export interface DataSubjectErasureRequest {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    requestedByUserUid: string;
+    status: DataSubjectErasureStatus;
+    reviewedByUserUid?: string;
+    /** Only ever set by `denyErasureRequest()` — never required or meaningful for an approval. */
+    reason?: string;
+    /** Set once `status === "completed"` — a single aggregate count, not a per-row manifest. */
+    purgedCount?: number;
+    /** Set when an administrator filed this request for the data a deleted mailbox left behind (see `admin/leftoverMailboxApi.ts`) - it
+     * was approved when filed, and never removes a mailbox. */
+    leftoverOnly?: 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. */
+/** Always the caller's own mailbox — 409s if a `pending` request for it already exists. */
+export declare function createErasureRequest(client?: ApiClient): Promise<DataSubjectErasureRequest>;
+/** A trusted caller sees every request; anyone else sees only their own (`requestedByUserUid`). Newest
+ * first; `params` pages through them (`limit` capped at 500 server-side). */
+export declare function listErasureRequests(params?: RequestListParams, client?: ApiClient): Promise<DataSubjectErasureRequest[]>;
+export declare function getErasureRequest(uid: string, client?: ApiClient): Promise<DataSubjectErasureRequest>;
+/** 409s if the mailbox is a custodian on an active legal hold, naming the blocking Matter uid(s) in the
+ * error message — surface this as-is, the same "server's own message wins" convention used everywhere
+ * else in this codebase for a destructive-action error. */
+export declare function approveErasureRequest(uid: string, client?: ApiClient): Promise<DataSubjectErasureRequest>;
+export declare function denyErasureRequest(uid: string, reason: string, client?: ApiClient): Promise<DataSubjectErasureRequest>;

package/dist/lib/mail/erasureRequestApi.js

@@ -0,0 +1,43 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s GDPR Article 17 ("right to erasure") request
+ * (`BaseDataSubjectErasureRequestRoute`, mounted at `mail/erasure-requests`). Unlike
+ * `dataExportApi.ts`/`mailboxImportApi.ts`, `create()` is self-service only — there is no
+ * admin-on-behalf-of path, and no `mailboxUid` parameter to override; it is always the caller's own
+ * mailbox. `approve()`/`deny()` are trusted-admin-only server-side. The actual destructive cascade is
+ * asynchronous (restapi's own `ErasureExecutionJob`, not this client) and irreversible once it runs — an
+ * approved request 409s during approval, and is retried indefinitely (never failed) by the job itself,
+ * while the target mailbox is a custodian on an active legal hold.
+ */
+import { withClient } from "../util/api.js";
+import { buildRequestListQuery } 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. */
+/** Always the caller's own mailbox — 409s if a `pending` request for it already exists. */
+export function createErasureRequest(client) {
+    return withClient(client, `/mail/erasure-requests`, { method: "POST" });
+}
+/** A trusted caller sees every request; anyone else sees only their own (`requestedByUserUid`). Newest
+ * first; `params` pages through them (`limit` capped at 500 server-side). */
+export function listErasureRequests(params = {}, client) {
+    return withClient(client, `/mail/erasure-requests${buildRequestListQuery(params)}`);
+}
+export function getErasureRequest(uid, client) {
+    return withClient(client, `/mail/erasure-requests/${encodeURIComponent(uid)}`);
+}
+/** 409s if the mailbox is a custodian on an active legal hold, naming the blocking Matter uid(s) in the
+ * error message — surface this as-is, the same "server's own message wins" convention used everywhere
+ * else in this codebase for a destructive-action error. */
+export function approveErasureRequest(uid, client) {
+    return withClient(client, `/mail/erasure-requests/${encodeURIComponent(uid)}/approve`, { method: "POST" });
+}
+export function denyErasureRequest(uid, reason, client) {
+    return withClient(client, `/mail/erasure-requests/${encodeURIComponent(uid)}/deny`, {
+        method: "POST",
+        body: JSON.stringify({ reason }),
+    });
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Backs Tasks' "Flagged email" smart-list (an Outlook To-Do concept: flagged *Messages*, not Tasks,
+ * surfaced into the Tasks app).
+ *
+ * The server now does the filtering: `listMessages({ filter: "flagged" })` is an indexed database predicate on
+ * the denormalized `Message.flagged` mirror (`flags` itself is one JSON column, which is why this used to read
+ * every message in the mailbox and filter in the browser). What is still client-side is the fan-out: a message
+ * list is folder-scoped, and "every flagged message in this mailbox" spans every mail folder, so this still
+ * makes one paged call per folder and merges the results. The client-side `flags.flagged` check below is kept
+ * as a cheap guard for a row written before the mirror existed, not as the filter.
+ */
+import { Message } from "./mailApi.js";
+import { ApiClient } from "../util/api.js";
+/** Hard cap on pages read per folder (50,000 messages) - guards against paging forever should a server
+ * ignore `page` and keep returning full pages. */
+export declare const FLAGGED_MAX_PAGES_PER_FOLDER = 100;
+/** How many folders are paged through at once, bounding the request burst on a mailbox with many folders. */
+export declare const FLAGGED_FOLDER_CONCURRENCY = 4;
+/** Lists every flagged message across all of a mailbox's mail folders (not just Inbox), newest first, each
+ * message at most once. `client`, when given, is threaded through to every underlying `listFolders()`/
+ * `listMessages()` call (see `useApiClient()`'s own doc comment) - omitted, this behaves exactly as before. */
+export declare function listFlaggedMessages(mailboxUid: string, client?: ApiClient): Promise<Message[]>;

package/dist/lib/mail/flaggedMessages.js

@@ -0,0 +1,73 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Backs Tasks' "Flagged email" smart-list (an Outlook To-Do concept: flagged *Messages*, not Tasks,
+ * surfaced into the Tasks app).
+ *
+ * The server now does the filtering: `listMessages({ filter: "flagged" })` is an indexed database predicate on
+ * the denormalized `Message.flagged` mirror (`flags` itself is one JSON column, which is why this used to read
+ * every message in the mailbox and filter in the browser). What is still client-side is the fan-out: a message
+ * list is folder-scoped, and "every flagged message in this mailbox" spans every mail folder, so this still
+ * makes one paged call per folder and merges the results. The client-side `flags.flagged` check below is kept
+ * as a cheap guard for a row written before the mirror existed, not as the filter.
+ */
+import { listFolders, listMessages } from "./mailApi.js";
+/** Folder types that actually hold `Message` records — mirrors `MailShell.tsx`'s own `MAIL_FOLDER_TYPES`
+ * allowlist (kept as a separate local copy rather than a shared export, since the two call sites have no
+ * other coupling and this list is small/stable). */
+const MAIL_FOLDER_TYPES = new Set(["inbox", "drafts", "outbox", "sent_items", "junk", "deleted_items", "archive", "user"]);
+/** The server's own per-request `limit` cap - a page shorter than this is the folder's last one. */
+const PAGE_SIZE = 500;
+/** Hard cap on pages read per folder (50,000 messages) - guards against paging forever should a server
+ * ignore `page` and keep returning full pages. */
+export const FLAGGED_MAX_PAGES_PER_FOLDER = 100;
+/** How many folders are paged through at once, bounding the request burst on a mailbox with many folders. */
+export const FLAGGED_FOLDER_CONCURRENCY = 4;
+/** Every flagged message in one folder, paging through `listMessages()` until a short page. Only flagged
+ * messages are kept (a large folder's unflagged pages are dropped as they arrive). Stops early at
+ * `FLAGGED_MAX_PAGES_PER_FOLDER`, or when a full page brings no message not already seen (a server
+ * ignoring `page` and returning the same page again). */
+async function listFlaggedInFolder(folderUid, seen, client) {
+    const flagged = [];
+    const seenInFolder = new Set();
+    for (let page = 0; page < FLAGGED_MAX_PAGES_PER_FOLDER; page += 1) {
+        const batch = await listMessages(folderUid, { limit: PAGE_SIZE, page, filter: "flagged" }, client);
+        let fresh = 0;
+        for (const message of batch) {
+            if (seenInFolder.has(message.uid)) {
+                continue;
+            }
+            seenInFolder.add(message.uid);
+            fresh += 1;
+            // Deduplicated across folders too: a message moved mid-listing can appear in two folders' pages.
+            if (message.flags.flagged && !seen.has(message.uid)) {
+                seen.add(message.uid);
+                flagged.push(message);
+            }
+        }
+        if (batch.length < PAGE_SIZE || fresh === 0) {
+            break;
+        }
+    }
+    return flagged;
+}
+/** Lists every flagged message across all of a mailbox's mail folders (not just Inbox), newest first, each
+ * message at most once. `client`, when given, is threaded through to every underlying `listFolders()`/
+ * `listMessages()` call (see `useApiClient()`'s own doc comment) - omitted, this behaves exactly as before. */
+export async function listFlaggedMessages(mailboxUid, client) {
+    const folders = await listFolders(mailboxUid, client);
+    const mailFolders = folders.filter((f) => MAIL_FOLDER_TYPES.has(f.type));
+    const seen = new Set();
+    const perFolder = [];
+    let next = 0;
+    async function worker() {
+        while (next < mailFolders.length) {
+            const index = next++;
+            perFolder[index] = await listFlaggedInFolder(mailFolders[index].uid, seen, client);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(FLAGGED_FOLDER_CONCURRENCY, mailFolders.length) }, () => worker()));
+    return perFolder.flat().sort((a, b) => new Date(b.receivedDate).getTime() - new Date(a.receivedDate).getTime());
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `FocusedInboxOverride` CRUD route (`BaseScopedChildRoute`,
+ * `scopeProperty: "mailboxUid"`) — the standing "always classify mail from this sender as Focused/Other"
+ * rules `BaseMessageRoute.classify()` (see `classifyMessage()` in `mailApi.ts`) upserts when a caller sets
+ * `applyToSender: true`. This file lets a Settings page list/remove those rules directly, and add one by
+ * hand without first receiving a matching message.
+ */
+import { ApiClient } from "../util/api.js";
+import { ListParams } from "../util/apiQuery.js";
+import { MessageClassification } from "./mailApi.js";
+export type { ListParams };
+export interface FocusedInboxOverride {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    senderAddress: string;
+    classifyAs: MessageClassification;
+}
+/** `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 listFocusedInboxOverrides(mailboxUid: string, params?: ListParams, client?: ApiClient): Promise<FocusedInboxOverride[]>;
+export interface CreateFocusedInboxOverrideInput {
+    mailboxUid: string;
+    senderAddress: string;
+    classifyAs: MessageClassification;
+}
+export declare function createFocusedInboxOverride(input: CreateFocusedInboxOverrideInput, client?: ApiClient): Promise<FocusedInboxOverride>;
+export interface UpdateFocusedInboxOverrideInput {
+    uid: string;
+    version: number;
+    classifyAs: MessageClassification;
+}
+export declare function updateFocusedInboxOverride(input: UpdateFocusedInboxOverrideInput, client?: ApiClient): Promise<FocusedInboxOverride>;
+export declare function deleteFocusedInboxOverride(uid: string, version: number, client?: ApiClient): Promise<void>;

package/dist/lib/mail/focusedInboxOverridesApi.js

@@ -0,0 +1,34 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `FocusedInboxOverride` CRUD route (`BaseScopedChildRoute`,
+ * `scopeProperty: "mailboxUid"`) — the standing "always classify mail from this sender as Focused/Other"
+ * rules `BaseMessageRoute.classify()` (see `classifyMessage()` in `mailApi.ts`) upserts when a caller sets
+ * `applyToSender: true`. This file lets a Settings page list/remove those rules directly, and add one by
+ * hand without first receiving a matching message.
+ */
+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 listFocusedInboxOverrides(mailboxUid, params = {}, client) {
+    return withClient(client, `/mail/focused-inbox-overrides?${buildQuery(params, { mailboxUid })}`);
+}
+export function createFocusedInboxOverride(input, client) {
+    return withClient(client, "/mail/focused-inbox-overrides", {
+        method: "POST",
+        body: JSON.stringify(input),
+    });
+}
+export function updateFocusedInboxOverride(input, client) {
+    return withClient(client, `/mail/focused-inbox-overrides/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+export function deleteFocusedInboxOverride(uid, version, client) {
+    return withClient(client, `/mail/focused-inbox-overrides/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}