@rapidmx/web-client 0.21.0 → 0.22.0

package/dist/lib/mail/mailDetailHooks.js

@@ -0,0 +1,53 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { listAttachments, setMessageRead } from "./mailApi.js";
+/** Loads a message's attachments (only when it actually has any) — shared by every place a message is read. */
+export function useMessageAttachments(message) {
+    const [attachments, setAttachments] = useState([]);
+    useEffect(() => {
+        if (!message || !message.hasAttachments) {
+            setAttachments([]);
+            return;
+        }
+        listAttachments(message.folderUid, message.uid)
+            .then(setAttachments)
+            .catch(() => setAttachments([]));
+        // Only the fields the fetch actually depends on — not the whole `message` object, which gets a new
+        // reference on every metadata-only patch (e.g. `useMarkMessageRead`'s `onUpdated(updated)`, or a
+        // star/flag/label change wired to the same state) and would otherwise trigger a needless re-fetch.
+        // `folderUid` IS included: `moveMessage()`/`archiveMessage()` change it while preserving uid/hasAttachments
+        // (the same "new object reference, same uid" shape as a metadata-only patch), and dropping it would leave
+        // a stale fetch pointed at the message's old folder after a move — folder changes are rare enough that
+        // including it doesn't reintroduce the over-fetching this dependency array was narrowed to avoid.
+    }, [message?.uid, message?.hasAttachments, message?.folderUid]);
+    return attachments;
+}
+/**
+ * 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 function useMarkMessageRead(message, onUpdated) {
+    useEffect(() => {
+        if (!message || message.flags.read) {
+            return;
+        }
+        let cancelled = false;
+        setMessageRead(message, true)
+            .then((updated) => {
+            if (!cancelled) {
+                onUpdated(updated);
+            }
+        })
+            .catch(() => {
+            // Best-effort — see doc comment above.
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [message]);
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `MailFilterRule` CRUD route (`BaseScopedChildRoute`,
+ * `scopeProperty: "mailboxUid"`) — mailbox-scoped (unlike `TransportRule`, which is trusted-role-only
+ * and org-wide): every list/create call must carry `mailboxUid`, checked against that mailbox's own
+ * ACL, same pattern as `Message`/`Task`/`Note`/`Contact`. Evaluated by `ScanQueueJob` immediately after
+ * a message is verdicted "deliver" and before it's filed into the mailbox's Inbox — a live, enforced
+ * feature, not a data-model-only stub.
+ */
+import { ApiClient } from "../util/api.js";
+import { ListParams } from "../util/apiQuery.js";
+import { MessageImportance } from "./mailApi.js";
+export type { ListParams };
+export type MailFilterActionType = "move_to_folder" | "copy_to_folder" | "delete" | "mark_as_read" | "forward" | "apply_label";
+export interface MailFilterAction {
+    type: MailFilterActionType;
+    /** Required for `move_to_folder`/`copy_to_folder`. */
+    folderUid?: string;
+    /** Required for `forward`. */
+    forwardTo?: string;
+    /** The `Label.uid` to apply (`labelsApi.ts`). Required for `apply_label`. */
+    labelUid?: string;
+}
+export interface MailFilterConditions {
+    /** Substrings of the From header, case-insensitive: `ann@x.com` also matches `joann@x.com`. Use `fromEquals` to name one sender exactly. */
+    fromContains?: string[];
+    /** Plain addresses, matched exactly and case-insensitively against the From header's address OR the envelope sender (`ann@x.com` does not match `joann@x.com`).
+     * At most 100. A server before this condition ignores it, so the rule would match every message. */
+    fromEquals?: string[];
+    /** Domains (`x.com`, no `@`), matched exactly against the domain of the From header's address or of the envelope sender (`x.com` is not `mail.x.com`). At most 100. */
+    fromDomainEquals?: string[];
+    subjectContains?: string[];
+    bodyContains?: string[];
+    toCcContains?: string[];
+    hasAttachment?: boolean;
+    importance?: MessageImportance;
+}
+export interface MailFilterRule {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    name: string;
+    enabled: boolean;
+    sequence: number;
+    stopProcessingRules: boolean;
+    conditions: MailFilterConditions;
+    actions: MailFilterAction[];
+}
+/** `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 listMailFilterRules(mailboxUid: string, params?: ListParams, client?: ApiClient): Promise<MailFilterRule[]>;
+export declare function getMailFilterRule(uid: string, client?: ApiClient): Promise<MailFilterRule>;
+export interface CreateMailFilterRuleInput {
+    mailboxUid: string;
+    name: string;
+    enabled?: boolean;
+    sequence?: number;
+    stopProcessingRules?: boolean;
+    conditions?: MailFilterConditions;
+    actions?: MailFilterAction[];
+}
+export declare function createMailFilterRule(input: CreateMailFilterRuleInput, client?: ApiClient): Promise<MailFilterRule>;
+export interface UpdateMailFilterRuleInput {
+    uid: string;
+    version: number;
+    name?: string;
+    enabled?: boolean;
+    sequence?: number;
+    stopProcessingRules?: boolean;
+    conditions?: MailFilterConditions;
+    actions?: MailFilterAction[];
+}
+export declare function updateMailFilterRule(input: UpdateMailFilterRuleInput, client?: ApiClient): Promise<MailFilterRule>;
+export declare function deleteMailFilterRule(uid: string, version: number, client?: ApiClient): Promise<void>;

package/dist/lib/mail/mailFilterRulesApi.js

@@ -0,0 +1,45 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `MailFilterRule` CRUD route (`BaseScopedChildRoute`,
+ * `scopeProperty: "mailboxUid"`) — mailbox-scoped (unlike `TransportRule`, which is trusted-role-only
+ * and org-wide): every list/create call must carry `mailboxUid`, checked against that mailbox's own
+ * ACL, same pattern as `Message`/`Task`/`Note`/`Contact`. Evaluated by `ScanQueueJob` immediately after
+ * a message is verdicted "deliver" and before it's filed into the mailbox's Inbox — a live, enforced
+ * feature, not a data-model-only stub.
+ */
+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 listMailFilterRules(mailboxUid, params = {}, client) {
+    return withClient(client, `/mail/mail-filter-rules?${buildQuery(params, { mailboxUid })}`);
+}
+export function getMailFilterRule(uid, client) {
+    return withClient(client, `/mail/mail-filter-rules/${encodeURIComponent(uid)}`);
+}
+export function createMailFilterRule(input, client) {
+    return withClient(client, "/mail/mail-filter-rules", {
+        method: "POST",
+        body: JSON.stringify({
+            enabled: true,
+            sequence: 0,
+            stopProcessingRules: false,
+            conditions: {},
+            actions: [],
+            ...input,
+        }),
+    });
+}
+export function updateMailFilterRule(input, client) {
+    return withClient(client, `/mail/mail-filter-rules/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+export function deleteMailFilterRule(uid, version, client) {
+    return withClient(client, `/mail/mail-filter-rules/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `MailSignature` CRUD route (`BaseScopedChildRoute`,
+ * `scopeProperty: "mailboxUid"`) — mailbox-scoped, same pattern as `mailFilterRulesApi.ts`. Composition
+ * is entirely this app's own job: restapi never assembles a signature into a message body itself (see
+ * its own `resolveDefaultSignature()` doc comment) — `ComposeWindow.tsx` is what actually inserts a
+ * resolved signature's `contentHtml` into a new draft.
+ */
+import { ApiClient } from "../util/api.js";
+import { ListParams } from "../util/apiQuery.js";
+export type { ListParams };
+export interface MailSignature {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    name: string;
+    contentHtml: string;
+    /** At most one signature per mailbox should have this `true` — enforced by convention (the caller
+     * toggles any previous default off itself), not by a database constraint. Applied to a fresh,
+     * non-reply/forward compose. */
+    isDefaultForNewMessages: boolean;
+    /** Same single-default convention as `isDefaultForNewMessages`, applied to replies/forwards
+     * instead — mirrors Outlook Web Access's separate "Replies/forwards" signature selector. */
+    isDefaultForReplyForward: 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 declare function listMailSignatures(mailboxUid: string, params?: ListParams, client?: ApiClient): Promise<MailSignature[]>;
+export declare function getMailSignature(uid: string, client?: ApiClient): Promise<MailSignature>;
+export interface CreateMailSignatureInput {
+    mailboxUid: string;
+    name: string;
+    contentHtml?: string;
+    isDefaultForNewMessages?: boolean;
+    isDefaultForReplyForward?: boolean;
+}
+export declare function createMailSignature(input: CreateMailSignatureInput, client?: ApiClient): Promise<MailSignature>;
+export interface UpdateMailSignatureInput {
+    uid: string;
+    version: number;
+    name?: string;
+    contentHtml?: string;
+    isDefaultForNewMessages?: boolean;
+    isDefaultForReplyForward?: boolean;
+}
+export declare function updateMailSignature(input: UpdateMailSignatureInput, client?: ApiClient): Promise<MailSignature>;
+export declare function deleteMailSignature(uid: string, version: number, client?: ApiClient): Promise<void>;

package/dist/lib/mail/mailSignaturesApi.js

@@ -0,0 +1,42 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `MailSignature` CRUD route (`BaseScopedChildRoute`,
+ * `scopeProperty: "mailboxUid"`) — mailbox-scoped, same pattern as `mailFilterRulesApi.ts`. Composition
+ * is entirely this app's own job: restapi never assembles a signature into a message body itself (see
+ * its own `resolveDefaultSignature()` doc comment) — `ComposeWindow.tsx` is what actually inserts a
+ * resolved signature's `contentHtml` into a new draft.
+ */
+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 listMailSignatures(mailboxUid, params = {}, client) {
+    return withClient(client, `/mail/mail-signatures?${buildQuery(params, { mailboxUid })}`);
+}
+export function getMailSignature(uid, client) {
+    return withClient(client, `/mail/mail-signatures/${encodeURIComponent(uid)}`);
+}
+export function createMailSignature(input, client) {
+    return withClient(client, "/mail/mail-signatures", {
+        method: "POST",
+        body: JSON.stringify({
+            contentHtml: "",
+            isDefaultForNewMessages: false,
+            isDefaultForReplyForward: false,
+            ...input,
+        }),
+    });
+}
+export function updateMailSignature(input, client) {
+    return withClient(client, `/mail/mail-signatures/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+export function deleteMailSignature(uid, version, client) {
+    return withClient(client, `/mail/mail-signatures/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}

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

@@ -0,0 +1,74 @@
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `BaseMailboxAccessRoute` (`GET/PUT/DELETE /mail/mailboxes/:id/
+ * access[/:userOrRoleId]`, `GET /mail/mailboxes/lookup-by-email`) - a friendlier, purpose-built layer over
+ * mailbox delegate access than this package's own `getMailboxAcl()`/`grantMailboxAccess()`/
+ * `revokeMailboxAccess()` (`mailApi.ts`), which stay as-is for their one existing caller (the admin-only
+ * `ShareAccessCard`). Those wrap the fully generic `BaseACLRoute` directly (raw `ACLRecord.actions[]`,
+ * requires the caller hold literal `ACLAction.FULL`); this module's routes are gated at plain `"update"`
+ * and speak a simple 2-tier `"viewer"`/`"manager"` vocabulary instead, so a non-admin mailbox owner or
+ * delegate can use them too.
+ */
+import { ApiClient } from "../util/api.js";
+/** A role that can be granted. */
+export type MailboxAccessRole = "viewer" | "manager";
+/** A member's role as listed: `"custom"` for any other set of actions granted outside this API, which can't be set
+ * here - see `actions` for what it allows. */
+export type MailboxAccessMemberRole = MailboxAccessRole | "custom";
+export interface MailboxAccessMember {
+    userOrRoleId: string;
+    role: MailboxAccessMemberRole;
+    /** The ACL actions the member holds. */
+    actions?: string[];
+    /** `userOrRoleId` is not a user uid (a username or address typed in free text, say): a person's token carries a uid, never
+     * that string, so the entry almost certainly grants nothing to anyone. Replace it with the user it was meant for. */
+    noEffect?: boolean;
+}
+/** The person a typed principal - a mailbox address, an auth-server username or e-mail alias, or a user uid - resolved to. */
+export interface ResolvedPrincipal {
+    /** The user uid every grant is stored against. */
+    userUid: string;
+    /** Known when the person owns a mailbox on this server. */
+    displayName?: string;
+    address?: 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. */
+/** Who a typed principal is, without granting anything - rejects with a 404 `ApiRequestError` ("No user found for ...") for nobody. */
+export declare function resolveMailboxPrincipal(mailboxUid: string, principal: string, client?: ApiClient): Promise<ResolvedPrincipal>;
+export interface MailboxOwnerLookup {
+    userUid: string;
+    displayName: string;
+}
+/** Lists a mailbox's delegate members (excludes the owner's own implicit grant) - rejects with a 403
+ * `ApiRequestError` if the caller doesn't hold at least `"update"` on the mailbox (an administrator, trusted + elevated, may
+ * list any mailbox's members through the audited administration path). */
+export declare function listMailboxAccess(mailboxUid: string, client?: ApiClient): Promise<MailboxAccessMember[]>;
+/** Grants (or, if already a member, updates the role of) a delegate's access to a mailbox. `userOrRoleId` names the PERSON - a user
+ * uid, or anything the server resolves to one (a mailbox address, an auth-server username or e-mail alias): only the resolved uid is
+ * stored, and a name that resolves to nobody rejects with a 400 `ApiRequestError` ("No user found for ..."). */
+export declare function setMailboxAccess(mailboxUid: string, userOrRoleId: string, role: MailboxAccessRole, client?: ApiClient): Promise<MailboxAccessMember>;
+/** What the signed-in caller may do in a mailbox, as the server's ACLs evaluate it: their own and delegate access - a
+ * trusted role adds nothing, so an administrator with no grant on a mailbox gets `false` throughout. */
+export interface MyMailboxAccess {
+    canRead: boolean;
+    /** Create items in the mailbox: drafts, events, contacts, to-dos. */
+    canCreate: boolean;
+    canUpdate: boolean;
+    canDelete: boolean;
+    /** Manage who else has access. */
+    canManage: boolean;
+}
+/** The signed-in caller's own access to a mailbox. */
+export declare function getMyMailboxAccess(mailboxUid: string, client?: ApiClient): Promise<MyMailboxAccess>;
+/** Revokes a delegate's access to a mailbox - never rejects for a `userOrRoleId` that wasn't a member. */
+export declare function removeMailboxAccess(mailboxUid: string, userOrRoleId: string, client?: ApiClient): Promise<void>;
+/**
+ * Resolves an email address to the person who owns the mailbox at that address, for a "share this
+ * mailbox with someone" UI to grant access by uid after the caller types an email - there is no separate
+ * user/identity directory anywhere in this platform (see `BaseMailboxAccessRoute`'s own doc comment), so
+ * this only ever matches an existing `Mailbox`'s own address. Resolves to `null` (not a thrown error) for
+ * an address with no matching mailbox, or one that only matches a shared (ownerless) mailbox - both are
+ * "no person found," a normal, expected outcome, not a failure.
+ */
+export declare function lookupMailboxOwnerByEmail(email: string, client?: ApiClient): Promise<MailboxOwnerLookup | null>;

package/dist/lib/mail/mailboxAccessApi.js

@@ -0,0 +1,56 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `BaseMailboxAccessRoute` (`GET/PUT/DELETE /mail/mailboxes/:id/
+ * access[/:userOrRoleId]`, `GET /mail/mailboxes/lookup-by-email`) - a friendlier, purpose-built layer over
+ * mailbox delegate access than this package's own `getMailboxAcl()`/`grantMailboxAccess()`/
+ * `revokeMailboxAccess()` (`mailApi.ts`), which stay as-is for their one existing caller (the admin-only
+ * `ShareAccessCard`). Those wrap the fully generic `BaseACLRoute` directly (raw `ACLRecord.actions[]`,
+ * requires the caller hold literal `ACLAction.FULL`); this module's routes are gated at plain `"update"`
+ * and speak a simple 2-tier `"viewer"`/`"manager"` vocabulary instead, so a non-admin mailbox owner or
+ * delegate can use them too.
+ */
+import { withClient } from "../util/api.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. */
+/** Who a typed principal is, without granting anything - rejects with a 404 `ApiRequestError` ("No user found for ...") for nobody. */
+export function resolveMailboxPrincipal(mailboxUid, principal, client) {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/access/resolve?principal=${encodeURIComponent(principal)}`);
+}
+/** Lists a mailbox's delegate members (excludes the owner's own implicit grant) - rejects with a 403
+ * `ApiRequestError` if the caller doesn't hold at least `"update"` on the mailbox (an administrator, trusted + elevated, may
+ * list any mailbox's members through the audited administration path). */
+export function listMailboxAccess(mailboxUid, client) {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/access`);
+}
+/** Grants (or, if already a member, updates the role of) a delegate's access to a mailbox. `userOrRoleId` names the PERSON - a user
+ * uid, or anything the server resolves to one (a mailbox address, an auth-server username or e-mail alias): only the resolved uid is
+ * stored, and a name that resolves to nobody rejects with a 400 `ApiRequestError` ("No user found for ..."). */
+export function setMailboxAccess(mailboxUid, userOrRoleId, role, client) {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/access/${encodeURIComponent(userOrRoleId)}`, {
+        method: "PUT",
+        body: JSON.stringify({ role }),
+    });
+}
+/** The signed-in caller's own access to a mailbox. */
+export function getMyMailboxAccess(mailboxUid, client) {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/access/me`);
+}
+/** Revokes a delegate's access to a mailbox - never rejects for a `userOrRoleId` that wasn't a member. */
+export function removeMailboxAccess(mailboxUid, userOrRoleId, client) {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/access/${encodeURIComponent(userOrRoleId)}`, { method: "DELETE" });
+}
+/**
+ * Resolves an email address to the person who owns the mailbox at that address, for a "share this
+ * mailbox with someone" UI to grant access by uid after the caller types an email - there is no separate
+ * user/identity directory anywhere in this platform (see `BaseMailboxAccessRoute`'s own doc comment), so
+ * this only ever matches an existing `Mailbox`'s own address. Resolves to `null` (not a thrown error) for
+ * an address with no matching mailbox, or one that only matches a shared (ownerless) mailbox - both are
+ * "no person found," a normal, expected outcome, not a failure.
+ */
+export function lookupMailboxOwnerByEmail(email, client) {
+    return withClient(client, `/mail/mailboxes/lookup-by-email?email=${encodeURIComponent(email)}`);
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s GDPR data-portability import (`BaseMailboxImportRoute`,
+ * mounted at `mail/mailbox-import-requests`) — the counterpart to `dataExportApi.ts`. Import runs
+ * asynchronously (restapi's own `MailboxImportJob`, not this client) — `uploadMailboxImport()` only
+ * stages the upload and returns the `pending` request; poll `getImportRequest()`/`listImportRequests()`
+ * for `status` to become `"completed"` (with `importedCount`/`failedCount`) or `"failed"`.
+ */
+import { ApiClient } from "../util/api.js";
+import { RequestListParams } from "../util/apiQuery.js";
+export type { RequestListParams };
+export type MailboxImportFormat = "mbox" | "pst";
+export type MailboxImportStatus = "pending" | "processing" | "completed" | "failed";
+export interface MailboxImportRequest {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    requestedByUserUid: string;
+    targetFolderUid: string;
+    format: MailboxImportFormat;
+    sourceBlobKey: string;
+    status: MailboxImportStatus;
+    importedCount?: number;
+    failedCount?: number;
+    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 UploadMailboxImportInput {
+    format: MailboxImportFormat;
+    targetFolderUid: string;
+    /** 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;
+}
+/**
+ * Uploads `file`'s raw bytes as a new mailbox-import request. Bypasses `apiFetch` — that helper always
+ * forces `Content-Type: application/json`, which would corrupt binary content; this sends the file's own
+ * bytes directly instead, matching `BaseMailboxImportRoute.create()`'s expectation of a raw request body
+ * with `format`/`targetFolderUid`/`mailboxUid` as query-string parameters, not a JSON body — the same
+ * shape `mailApi.ts`'s `uploadAttachment()` already establishes for a raw-bytes upload.
+ */
+export declare function uploadMailboxImport(file: File, input: UploadMailboxImportInput): Promise<MailboxImportRequest>;
+/** `client`, given by every function below that isn't a raw-bytes upload, is an explicit `ApiClient` from
+ * `createApiClient()` (e.g. one account of a multi-account app) to call instead of the default global
+ * `apiFetch()` - see `withClient()`'s own doc comment in `util/api.ts`. Omitted (the default), every
+ * function here behaves exactly as before. */
+/** 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 listImportRequests(params?: RequestListParams, client?: ApiClient): Promise<MailboxImportRequest[]>;
+export declare function getImportRequest(uid: string, client?: ApiClient): Promise<MailboxImportRequest>;

package/dist/lib/mail/mailboxImportApi.js

@@ -0,0 +1,51 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s GDPR data-portability import (`BaseMailboxImportRoute`,
+ * mounted at `mail/mailbox-import-requests`) — the counterpart to `dataExportApi.ts`. Import runs
+ * asynchronously (restapi's own `MailboxImportJob`, not this client) — `uploadMailboxImport()` only
+ * stages the upload and returns the `pending` request; poll `getImportRequest()`/`listImportRequests()`
+ * for `status` to become `"completed"` (with `importedCount`/`failedCount`) or `"failed"`.
+ */
+import { ApiRequestError, apiUrl, withClient, withCsrfHeader } from "../util/api.js";
+import { buildRequestListQuery } from "../util/apiQuery.js";
+/**
+ * Uploads `file`'s raw bytes as a new mailbox-import request. Bypasses `apiFetch` — that helper always
+ * forces `Content-Type: application/json`, which would corrupt binary content; this sends the file's own
+ * bytes directly instead, matching `BaseMailboxImportRoute.create()`'s expectation of a raw request body
+ * with `format`/`targetFolderUid`/`mailboxUid` as query-string parameters, not a JSON body — the same
+ * shape `mailApi.ts`'s `uploadAttachment()` already establishes for a raw-bytes upload.
+ */
+export async function uploadMailboxImport(file, input) {
+    const params = new URLSearchParams({ format: input.format, targetFolderUid: input.targetFolderUid });
+    if (input.mailboxUid) {
+        params.set("mailboxUid", input.mailboxUid);
+    }
+    const res = await fetch(apiUrl(`/mail/mailbox-import-requests?${params.toString()}`), {
+        method: "POST",
+        credentials: "include",
+        headers: withCsrfHeader({ "Content-Type": input.format === "pst" ? "application/vnd.ms-outlook" : "application/mbox" }),
+        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;
+}
+/** `client`, given by every function below that isn't a raw-bytes upload, is an explicit `ApiClient` from
+ * `createApiClient()` (e.g. one account of a multi-account app) to call instead of the default global
+ * `apiFetch()` - see `withClient()`'s own doc comment in `util/api.ts`. Omitted (the default), every
+ * function here behaves exactly as before. */
+/** 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 listImportRequests(params = {}, client) {
+    return withClient(client, `/mail/mailbox-import-requests${buildRequestListQuery(params)}`);
+}
+export function getImportRequest(uid, client) {
+    return withClient(client, `/mail/mailbox-import-requests/${encodeURIComponent(uid)}`);
+}

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

@@ -0,0 +1,16 @@
+/** Decodes CSS escapes first (so an escaped `u\72l(` can't hide from the checks below), then drops every
+ * `@import` and neutralizes every `url()`/`image-set()` reference that isn't a `data:`/`cid:` URI. */
+export declare function stripRemoteCssUrls(css: string): string;
+/**
+ * Sanitizes a message body for display (a sandboxed `srcDoc`, behind its own CSP): DOMPurify's defaults plus the
+ * remote-resource stripping above, and no `<link>`, `<meta>` or `<base>`. Returns `""` when there is no DOM to
+ * sanitize with - never the unsanitized input.
+ */
+export declare function sanitizeMessageBodyHtml(html: string): string;
+/**
+ * Sanitizes message HTML for quoting into a compose body: the display policy (`sanitizeMessageBodyHtml()`), without
+ * the tags in `QUOTE_FORBIDDEN_TAGS`, and without any image that isn't embedded as a `data:` URI - a `cid:` image
+ * refers to a part of the original message the reply doesn't carry. Returns `""` when there is no DOM to sanitize
+ * with.
+ */
+export declare function sanitizeQuotedHtml(html: string): string;