@rapidmx/web-client 0.21.0 → 0.23.0

package/dist/lib/components/overlays/PopoverPortal.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+/**
+ * Renders its children into `document.body` (via a portal), `position: fixed` at a spot computed from
+ * `anchorRef`'s own rect — used by `EmojiPicker`/`GifPicker` so the popup escapes every ancestor's
+ * `overflow-hidden` (the Compose window's own outer frame, and `RichTextEditor`'s bordered wrapper
+ * both clip anything positioned merely `absolute` inside them, however high its `z-index` — clipping
+ * isn't a stacking-order problem `z-index` can override). Prefers opening *below* the anchor (there's
+ * more room in the editor area below the toolbar than above it, where the To/Cc/Subject rows are —
+ * confirmed directly: an earlier `absolute`+`overflow-hidden` version of this rendered the popup
+ * behind those rows), flipping to *above* only if there isn't enough room below.
+ */
+export default function PopoverPortal({ anchorRef, onClose, width, height, children, ...rest }) {
+    const containerRef = useRef(null);
+    const [style, setStyle] = useState(null);
+    // Read through a ref, like `overlayStack.ts`'s `onCloseRef`: callers (EmojiPicker/GifPicker) routinely pass
+    // `onClose` as a fresh inline function every render, and depending on it directly would remove/re-add the
+    // document listener on every parent re-render instead of just once on mount.
+    const onCloseRef = useRef(onClose);
+    onCloseRef.current = onClose;
+    useEffect(() => {
+        const rect = anchorRef.current?.getBoundingClientRect();
+        if (!rect) {
+            return;
+        }
+        const gap = 6;
+        const margin = 8;
+        const spaceBelow = window.innerHeight - rect.bottom;
+        const top = spaceBelow >= height + gap ? rect.bottom + gap : Math.max(margin, rect.top - height - gap);
+        const left = Math.min(Math.max(rect.left, margin), window.innerWidth - width - margin);
+        setStyle({ position: "fixed", top, left, width, height });
+    }, [anchorRef, height, width]);
+    useEffect(() => {
+        function handlePointerDown(e) {
+            const target = e.target;
+            if (containerRef.current?.contains(target) || anchorRef.current?.contains(target)) {
+                return;
+            }
+            onCloseRef.current();
+        }
+        document.addEventListener("pointerdown", handlePointerDown);
+        return () => document.removeEventListener("pointerdown", handlePointerDown);
+    }, [anchorRef]);
+    if (!style) {
+        return null;
+    }
+    return createPortal(_jsx("div", { ref: containerRef, role: "dialog", style: style, className: "z-50 flex flex-col bg-surface border border-border rounded-md shadow-modal overflow-hidden", ...rest, children: children }), document.body);
+}

package/dist/lib/components/overlays/overlayStack.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The shared dialog behavior behind `Modal.tsx` and `Drawer.tsx`: a module-level stack of every open
+ * overlay, so that when overlays nest (a Modal opened from inside a Drawer, a confirm Modal on top of an
+ * edit Modal) only the *topmost* one reacts to Escape and traps Tab — pressing Escape once closes one
+ * layer, not every layer at once.
+ *
+ * One `keydown` listener on `document` is installed while the stack is non-empty and dispatches to the
+ * top entry only. A per-overlay listener that checked "am I on top?" wouldn't be enough: the top
+ * overlay's `onClose` only *schedules* a React state update, so a lower overlay's listener running later
+ * in the same dispatch would still see itself as not-on-top only by luck of ordering.
+ */
+import { RefObject } from "react";
+/**
+ * The nesting depth of the overlay rendering a subtree. Overlays wrap their children in a provider with
+ * the value `useOverlayDialog()` returns, so an overlay rendered inside another's children knows it
+ * belongs above it regardless of effect ordering - see `push()`.
+ */
+export declare const OverlayDepthContext: import("react").Context<number>;
+/**
+ * Wires one open overlay into the stack: on open, remembers the previously focused element and moves
+ * focus into `dialogRef`'s element; while open *and topmost*, Escape calls `onClose` and Tab/Shift+Tab
+ * cycle focus within the dialog; on close/unmount, leaves the stack and restores focus to whatever had it
+ * before opening (when that's still an `HTMLElement`).
+ *
+ * `onClose` is read through a ref: callers routinely pass it as a fresh inline function every render, and
+ * depending on it directly would re-run the effect - re-stealing focus into the dialog - on every parent
+ * re-render (e.g. every keystroke in a field inside the dialog).
+ *
+ * Returns the depth to provide to the overlay's children via `OverlayDepthContext`.
+ */
+export declare function useOverlayDialog(open: boolean, dialogRef: RefObject<HTMLElement | null>, onClose: () => void): number;

package/dist/lib/components/overlays/overlayStack.js

@@ -0,0 +1,143 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The shared dialog behavior behind `Modal.tsx` and `Drawer.tsx`: a module-level stack of every open
+ * overlay, so that when overlays nest (a Modal opened from inside a Drawer, a confirm Modal on top of an
+ * edit Modal) only the *topmost* one reacts to Escape and traps Tab — pressing Escape once closes one
+ * layer, not every layer at once.
+ *
+ * One `keydown` listener on `document` is installed while the stack is non-empty and dispatches to the
+ * top entry only. A per-overlay listener that checked "am I on top?" wouldn't be enough: the top
+ * overlay's `onClose` only *schedules* a React state update, so a lower overlay's listener running later
+ * in the same dispatch would still see itself as not-on-top only by luck of ordering.
+ */
+import { createContext, useContext, useEffect, useRef } from "react";
+/**
+ * The nesting depth of the overlay rendering a subtree. Overlays wrap their children in a provider with
+ * the value `useOverlayDialog()` returns, so an overlay rendered inside another's children knows it
+ * belongs above it regardless of effect ordering - see `push()`.
+ */
+export const OverlayDepthContext = createContext(0);
+const stack = [];
+/** Everything natively tabbable - disabled controls, `tabindex="-1"`, and hidden inputs excluded. */
+const TABBABLE_SELECTOR = [
+    "a[href]",
+    "area[href]",
+    "button:not([disabled])",
+    "input:not([disabled]):not([type='hidden'])",
+    "select:not([disabled])",
+    "textarea:not([disabled])",
+    "iframe",
+    "audio[controls]",
+    "video[controls]",
+    "[contenteditable]:not([contenteditable='false'])",
+    "[tabindex]",
+].join(",");
+function tabbableElements(container) {
+    return Array.from(container.querySelectorAll(TABBABLE_SELECTOR)).filter((el) => el.tabIndex >= 0 && !el.hasAttribute("inert") && !el.closest("[hidden]"));
+}
+function handleKeyDown(e) {
+    const top = stack[stack.length - 1];
+    const dialog = top.dialogRef.current;
+    if (e.key === "Escape") {
+        top.onEscape();
+        return;
+    }
+    if (e.key !== "Tab" || !dialog) {
+        return;
+    }
+    const tabbable = tabbableElements(dialog);
+    const active = document.activeElement;
+    if (tabbable.length === 0) {
+        e.preventDefault();
+        dialog.focus();
+        return;
+    }
+    const first = tabbable[0];
+    const last = tabbable[tabbable.length - 1];
+    const outside = !dialog.contains(active);
+    if (e.shiftKey) {
+        if (outside || active === first || active === dialog) {
+            e.preventDefault();
+            last.focus();
+        }
+    }
+    else if (outside || active === last) {
+        e.preventDefault();
+        first.focus();
+    }
+}
+/** Identifies the synchronous burst of effects (one React commit) an entry was pushed in: bumped in a
+ * microtask after the first push of a burst, so every push from the same commit shares one value. */
+let currentCommit = 0;
+let commitBumpScheduled = false;
+function push(entry) {
+    if (stack.length === 0) {
+        document.addEventListener("keydown", handleKeyDown);
+    }
+    if (!commitBumpScheduled) {
+        commitBumpScheduled = true;
+        queueMicrotask(() => {
+            commitBumpScheduled = false;
+            currentCommit++;
+        });
+    }
+    entry.commit = currentCommit;
+    // Normally just an append (the most recently opened overlay is on top). But React runs a child's
+    // effects before its parent's, so when a nested overlay mounts already-open in the same commit as the
+    // overlay containing it, the child is pushed first and would end up *under* its own container - so an
+    // entry goes below deeper entries pushed *in the same commit* (its not-yet-stacked children). A deeper
+    // entry from an earlier commit stays below it: an overlay opened later is on top regardless of depth
+    // (e.g. a top-level confirm opened while a nested Drawer > Modal is already showing).
+    let index = stack.length;
+    while (index > 0 && stack[index - 1].depth > entry.depth && stack[index - 1].commit === entry.commit) {
+        index--;
+    }
+    stack.splice(index, 0, entry);
+}
+function remove(entry) {
+    stack.splice(stack.indexOf(entry), 1);
+    if (stack.length === 0) {
+        document.removeEventListener("keydown", handleKeyDown);
+    }
+}
+/**
+ * Wires one open overlay into the stack: on open, remembers the previously focused element and moves
+ * focus into `dialogRef`'s element; while open *and topmost*, Escape calls `onClose` and Tab/Shift+Tab
+ * cycle focus within the dialog; on close/unmount, leaves the stack and restores focus to whatever had it
+ * before opening (when that's still an `HTMLElement`).
+ *
+ * `onClose` is read through a ref: callers routinely pass it as a fresh inline function every render, and
+ * depending on it directly would re-run the effect - re-stealing focus into the dialog - on every parent
+ * re-render (e.g. every keystroke in a field inside the dialog).
+ *
+ * Returns the depth to provide to the overlay's children via `OverlayDepthContext`.
+ */
+export function useOverlayDialog(open, dialogRef, onClose) {
+    const depth = useContext(OverlayDepthContext);
+    const onCloseRef = useRef(onClose);
+    onCloseRef.current = onClose;
+    useEffect(() => {
+        if (!open)
+            return;
+        // Remember what had focus before the overlay opened so it can be restored on close (e.g. the
+        // "+ Add" button that triggered it), then move focus into the dialog itself.
+        const trigger = document.activeElement;
+        const entry = { dialogRef, onEscape: () => onCloseRef.current(), depth };
+        push(entry);
+        // An overlay that mounted open underneath an already-open nested one (see `push()`) must not
+        // steal focus from the overlay above it.
+        if (stack[stack.length - 1] === entry) {
+            dialogRef.current?.focus();
+        }
+        return () => {
+            remove(entry);
+            if (trigger instanceof HTMLElement) {
+                trigger.focus();
+            }
+        };
+    }, [open]);
+    return depth + 1;
+}

package/dist/lib/components/pickers/MiniDatePicker.d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+export interface MiniDatePickerProps {
+    /** The main view's current date — determines both the month shown and which day is highlighted. */
+    selected: Date;
+    onSelect: (date: Date) => void;
+}
+/** A compact month-grid date picker for the Calendar sidebar, reusing `MonthView`'s own grid-generation
+ * approach (`date-fns`'s `startOfWeek`/`endOfWeek`/`eachDayOfInterval`, Monday-start) rather than
+ * re-deriving it — this component just renders that same grid far smaller and without any event data.
+ * Its own displayed month tracks `selected` (so navigating the main view keeps this in sync) but can
+ * also be paged independently via the arrows without moving the main view until a day is actually
+ * clicked. */
+export default function MiniDatePicker({ selected, onSelect }: MiniDatePickerProps): React.JSX.Element;

package/dist/lib/components/pickers/MiniDatePicker.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useState } from "react";
+import { addMonths, eachDayOfInterval, endOfMonth, endOfWeek, format, isSameDay, isSameMonth, isToday, startOfMonth, startOfWeek } from "date-fns";
+const WEEKDAY_LABELS = ["M", "T", "W", "T", "F", "S", "S"];
+/** A compact month-grid date picker for the Calendar sidebar, reusing `MonthView`'s own grid-generation
+ * approach (`date-fns`'s `startOfWeek`/`endOfWeek`/`eachDayOfInterval`, Monday-start) rather than
+ * re-deriving it — this component just renders that same grid far smaller and without any event data.
+ * Its own displayed month tracks `selected` (so navigating the main view keeps this in sync) but can
+ * also be paged independently via the arrows without moving the main view until a day is actually
+ * clicked. */
+export default function MiniDatePicker({ selected, onSelect }) {
+    const [shownMonth, setShownMonth] = useState(() => startOfMonth(selected));
+    // Tracks the last `selected` month this picker synced to, in the standard React
+    // "adjust state during render" shape — resyncs `shownMonth` whenever the caller's selected date
+    // moves to a different month (e.g. via the main view's own Previous/Next/Today controls), but
+    // otherwise leaves it alone so paging this picker's own arrows isn't immediately undone.
+    const [trackedSelectedMonth, setTrackedSelectedMonth] = useState(() => startOfMonth(selected));
+    if (!isSameMonth(trackedSelectedMonth, selected)) {
+        setTrackedSelectedMonth(startOfMonth(selected));
+        setShownMonth(startOfMonth(selected));
+    }
+    const gridStart = startOfWeek(startOfMonth(shownMonth), { weekStartsOn: 1 });
+    const gridEnd = endOfWeek(endOfMonth(shownMonth), { weekStartsOn: 1 });
+    const days = eachDayOfInterval({ start: gridStart, end: gridEnd });
+    return (_jsxs("nav", { "aria-label": "Mini calendar", className: "p-2", children: [_jsxs("div", { className: "flex items-center justify-between mb-1.5", children: [_jsx("button", { type: "button", "aria-label": "Previous month", onClick: () => setShownMonth((m) => addMonths(m, -1)), className: "w-6 h-6 text-xs rounded-sm hover:bg-surface-alt", children: "\u2039" }), _jsx("span", { className: "text-xs font-semibold", children: format(shownMonth, "MMMM yyyy") }), _jsx("button", { type: "button", "aria-label": "Next month", onClick: () => setShownMonth((m) => addMonths(m, 1)), className: "w-6 h-6 text-xs rounded-sm hover:bg-surface-alt", children: "\u203A" })] }), _jsxs("div", { className: "grid grid-cols-7 gap-0.5", children: [WEEKDAY_LABELS.map((label, i) => (_jsx("div", { className: "text-[10px] text-text-muted text-center", children: label }, i))), days.map((day) => (_jsx("button", { type: "button", onClick: () => {
+                            onSelect(day);
+                            setShownMonth(startOfMonth(day));
+                        }, className: [
+                            "text-[11px] w-6 h-6 rounded-full flex items-center justify-center mx-auto",
+                            isSameDay(day, selected)
+                                ? "bg-primary text-white"
+                                : isToday(day)
+                                    ? "text-primary-dark font-semibold"
+                                    : isSameMonth(day, shownMonth)
+                                        ? "text-text hover:bg-surface-alt"
+                                        : "text-text-muted/50 hover:bg-surface-alt",
+                        ].join(" "), children: format(day, "d") }, day.toISOString())))] })] }));
+}

package/dist/lib/contacts/contactsApi.d.ts

@@ -0,0 +1,174 @@
+/** Typed wrappers over `@rapidmx/restapi`'s `/mail/contacts` REST surface — see `mailApi.ts`'s own header
+ * comment for the shared ACL/authorization model every wrapper file here follows. */
+import { ApiClient } from "../util/api.js";
+import { ListParams } from "../util/apiQuery.js";
+import { type EncryptionPreference, type KeyConflict, type PreviousKey, type PublicKey, type RejectedKey } from "../crypto/keyvaultApi.js";
+export type ContactAddressKind = "home" | "work" | "other";
+export interface ContactEmail {
+    address: string;
+    type: ContactAddressKind;
+}
+export interface ContactPhone {
+    phoneNumber: string;
+    type: ContactAddressKind;
+}
+export interface ContactPostalAddress {
+    street?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    country?: string;
+    type: ContactAddressKind;
+}
+export interface Contact {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    folderUid: string;
+    /** The `ContactList` (group) this contact belongs to, if any. */
+    contactListUid?: string;
+    displayName: string;
+    givenName?: string;
+    surname?: string;
+    emails: ContactEmail[];
+    phones: ContactPhone[];
+    addresses: ContactPostalAddress[];
+    company?: string;
+    jobTitle?: string;
+    notes?: string;
+    photoBlobKey?: string;
+    sourceUid?: string;
+    /** Whether the caller has starred/favorited this contact. Absent is equivalent to `false`. */
+    favorite?: boolean;
+    /** Free-form category labels (Outlook-style colored categories) applied to this contact, if any. */
+    categories?: string[];
+    /** Present (and `true`) only when fetched via `listDeletedContacts()` — a soft-deleted `RecoverableBaseEntity`
+     * record still exists server-side so it can be restored, per `@rapidmx/restapi`'s own soft-delete model. */
+    deleted?: boolean;
+    /** This contact's known encryption preference, per `specs/end-to-end_encryption.md` — discovered
+     * via `crypto/keyvaultApi.ts`'s `lookupKeys()` at compose time, never fetched on message receipt
+     * (that would leak read timing to the sender's server). */
+    encryptPreference?: EncryptionPreference;
+    /** This contact's pinned public keys. Trust is TOFU (trust-on-first-use) — see `keyConflicts` for what
+     * happens when a newly observed key differs from one of these. */
+    keys?: PublicKey[];
+    /** Observed keys that conflict with the currently pinned key of the same `useType`, at most one per `useType` —
+     * each blocks silent acceptance until the user resolves it (`keyvaultApi.ts`'s `resolveKeyConflict()`, the spec's
+     * Key Conflict Handling). The pinned `keys` are retained unchanged while a conflict is set. */
+    keyConflicts?: KeyConflict[];
+    /** Keys that were pinned before and replaced (by the user accepting a conflict, or by restapi's automatic
+     * same-issuer renewal of an expired or revoked key), newest first, at most 5 per `useType`. Signing keys here
+     * still count as trusted signers — see `signingKeyFingerprints()`. */
+    previousKeys?: PreviousKey[];
+    /** Keys the user rejected when resolving a conflict. */
+    rejectedKeys?: RejectedKey[];
+}
+/** Lists a folder's contacts, alphabetically by display name. Never includes soft-deleted contacts — see
+ * `listDeletedContacts()` for those. */
+export declare function listContacts(folderUid: string, params?: ListParams, client?: ApiClient): Promise<Contact[]>;
+/** The trusted signing-key fingerprints of every contact in `contacts` with an email equal (case-insensitively) to
+ * `address`: each contact's pinned `keys` and its `previousKeys`, so mail signed before a key rotation still verifies -
+ * see `keyvaultApi.ts`'s `signingKeyFingerprints()` for the rules (expired and superseded keys kept, compromised or reasonless revoked keys excluded). De-duplicated;
+ * `[]` when no contact matches or none has a trusted signing key. */
+export declare function pinnedSigningFingerprintsFor(contacts: Contact[], address: string): string[];
+/** Page size and page cap for `fetchPinnedSigningFingerprints()` and `fetchSignerKeyState()` (500 is restapi's own
+ * `limit` cap). */
+export declare const PINNED_FINGERPRINT_PAGE_SIZE = 500;
+export declare const PINNED_FINGERPRINT_MAX_PAGES = 20;
+/**
+ * Fetches the trusted signing-key fingerprints (pinned and previous - see `pinnedSigningFingerprintsFor()`) for a
+ * message sender's `address` from the contacts in `folderUids` (the reader's contacts folders), for
+ * `evaluateMessageSecurity()`'s `pinnedSignerFingerprints`. Reads only what is already stored on the reader's own
+ * contacts - never triggers a Discovery lookup, which must not happen on message receipt (it would leak read timing to
+ * the sender's server). Pages through each folder (`PINNED_FINGERPRINT_PAGE_SIZE`, at most
+ * `PINNED_FINGERPRINT_MAX_PAGES` pages per folder). A caller rendering many messages should cache the contact list and
+ * use `pinnedSigningFingerprintsFor()` instead.
+ */
+export declare function fetchPinnedSigningFingerprints(folderUids: string[], address: string, client?: ApiClient): Promise<string[]>;
+/** A sender's stored signing-key state, for a key-changed comparison - see `signerKeyStateFor()`. */
+export interface SignerKeyState {
+    /** The currently pinned signing keys (every `useType: "sign"` key, revoked and expired ones included, so a UI can
+     * show their dates and status), de-duplicated by fingerprint. */
+    pinned: PublicKey[];
+    /** Previously pinned signing keys, newest `replacedAt` first, de-duplicated by fingerprint. */
+    previous: PreviousKey[];
+    /** The first unresolved signing-key conflict found, if any. */
+    conflict?: KeyConflict;
+}
+/** The signing-key state of every contact in `contacts` with an email equal (case-insensitively) to `address`, merged -
+ * what a UI needs to compare a `signer_key_changed` message's certificate with the pinned and previous keys (their
+ * fingerprints and `notBefore`/`notAfter`/`revokedAt`/`replacedAt` dates) before calling `resolveKeyConflict()`. Empty
+ * `pinned`/`previous` and no `conflict` when no contact matches. */
+export declare function signerKeyStateFor(contacts: Contact[], address: string): SignerKeyState;
+/** Fetches `signerKeyStateFor()` for `address` from the contacts in `folderUids`, paging exactly like
+ * `fetchPinnedSigningFingerprints()`. Reads only stored contacts - never triggers a Discovery lookup. */
+export declare function fetchSignerKeyState(folderUids: string[], address: string, client?: ApiClient): Promise<SignerKeyState>;
+/**
+ * Lists a folder's soft-deleted contacts
+ (for an Outlook-style "Deleted" view) — `deleted` is an ordinary
+ * queryable field on `Contact` (a `RecoverableBaseEntity`), so this is the same `find()` the plain listing
+ * above uses, just constrained to `deleted: true` instead of the framework's own default of excluding them.
+ *
+ * Read-only for now — deliberately no `restoreContact()`: `@rapidmx/restapi`'s generic
+ * `BaseScopedChildRoute.update()` looks the target record up via a plain `findOne()` with no
+ * `includeDeleted` option, so it 404s on an already-deleted record before ever reaching the point where
+ * setting `deleted: false` would matter. Restoring would need a real fix in `@rapidmx/restapi` itself
+ * (passing `includeDeleted: true` into that lookup) — out of scope for this pass; the "Deleted" view here
+ * is browse-only until that lands.
+ */
+export declare function listDeletedContacts(folderUid: string, params?: ListParams, client?: ApiClient): Promise<Contact[]>;
+export declare function getContact(uid: string, client?: ApiClient): Promise<Contact>;
+export interface ContactInput {
+    mailboxUid: string;
+    folderUid: string;
+    contactListUid?: string;
+    displayName: string;
+    givenName?: string;
+    surname?: string;
+    emails?: ContactEmail[];
+    phones?: ContactPhone[];
+    addresses?: ContactPostalAddress[];
+    company?: string;
+    jobTitle?: string;
+    notes?: string;
+    favorite?: boolean;
+    categories?: string[];
+}
+export declare function createContact(input: ContactInput, client?: ApiClient): Promise<Contact>;
+export interface UpdateContactInput extends ContactInput {
+    uid: string;
+    version: number;
+}
+/** A minimal contact update: only `uid`/`version` are required, every other field is sent only if
+ * present. The server merges just the fields in the body and rejects server-managed ones
+ * (`dateCreated`/`dateModified`/etc.), so prefer sending only what actually changed over a whole
+ * fetched `Contact`. An `UpdateContactInput` is also a valid `ContactPatch`. */
+export type ContactPatch = Partial<Contact> & Pick<Contact, "uid" | "version">;
+export declare function updateContact(patch: ContactPatch, client?: ApiClient): Promise<Contact>;
+/** Thin `updateContact()` wrapper for toggling favorite/star status — same pattern as `mailApi.ts`'s
+ * `setMessageRead()`/`tasksApi.ts`'s `setTaskCompleted()`. Sends only `uid`/`version`/`favorite`, never
+ * the rest of `contact` (the server rejects its managed fields). */
+export declare function setContactFavorite(contact: Contact, favorite: boolean, client?: ApiClient): Promise<Contact>;
+export declare function deleteContact(uid: string, version: number, client?: ApiClient): Promise<void>;
+export interface ContactList {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    name: string;
+}
+/** Lists a mailbox's contact lists (Outlook-style "Your contact lists"), alphabetically by name. */
+export declare function listContactLists(mailboxUid: string, params?: ListParams, client?: ApiClient): Promise<ContactList[]>;
+export declare function createContactList(input: {
+    mailboxUid: string;
+    name: string;
+}, client?: ApiClient): Promise<ContactList>;
+export declare function updateContactList(input: {
+    uid: string;
+    version: number;
+    name: string;
+}, client?: ApiClient): Promise<ContactList>;
+export declare function deleteContactList(uid: string, version: number, client?: ApiClient): Promise<void>;

package/dist/lib/contacts/contactsApi.js

@@ -0,0 +1,139 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** Typed wrappers over `@rapidmx/restapi`'s `/mail/contacts` REST surface — see `mailApi.ts`'s own header
+ * comment for the shared ACL/authorization model every wrapper file here follows. */
+import { withClient } from "../util/api.js";
+import { buildQuery } from "../util/apiQuery.js";
+import { signingKeyFingerprints, } from "../crypto/keyvaultApi.js";
+/** Lists a folder's contacts, alphabetically by display name. Never includes soft-deleted contacts — see
+ * `listDeletedContacts()` for those. */
+export function listContacts(folderUid, params = {}, client) {
+    return withClient(client, `/mail/contacts?${buildQuery(params, { folderUid, sort: JSON.stringify({ displayName: "ASC" }) })}`);
+}
+function contactsMatching(contacts, address) {
+    const wanted = address.trim().toLowerCase();
+    return contacts.filter((contact) => contact.emails.some((email) => email.address.trim().toLowerCase() === wanted));
+}
+/** The trusted signing-key fingerprints of every contact in `contacts` with an email equal (case-insensitively) to
+ * `address`: each contact's pinned `keys` and its `previousKeys`, so mail signed before a key rotation still verifies -
+ * see `keyvaultApi.ts`'s `signingKeyFingerprints()` for the rules (expired and superseded keys kept, compromised or reasonless revoked keys excluded). De-duplicated;
+ * `[]` when no contact matches or none has a trusted signing key. */
+export function pinnedSigningFingerprintsFor(contacts, address) {
+    return [...new Set(contactsMatching(contacts, address).flatMap((contact) => signingKeyFingerprints(contact.keys, contact.previousKeys)))];
+}
+/** Page size and page cap for `fetchPinnedSigningFingerprints()` and `fetchSignerKeyState()` (500 is restapi's own
+ * `limit` cap). */
+export const PINNED_FINGERPRINT_PAGE_SIZE = 500;
+export const PINNED_FINGERPRINT_MAX_PAGES = 20;
+/** Every contact in `folderUids`, paged (`PINNED_FINGERPRINT_PAGE_SIZE`, at most `PINNED_FINGERPRINT_MAX_PAGES` pages
+ * per folder). A plain contacts read - never a Discovery lookup. */
+async function listContactsInFolders(folderUids, client) {
+    const contacts = [];
+    for (const folderUid of folderUids) {
+        for (let page = 0; page < PINNED_FINGERPRINT_MAX_PAGES; page++) {
+            const batch = await listContacts(folderUid, { limit: PINNED_FINGERPRINT_PAGE_SIZE, page }, client);
+            contacts.push(...batch);
+            if (batch.length < PINNED_FINGERPRINT_PAGE_SIZE) {
+                break;
+            }
+        }
+    }
+    return contacts;
+}
+/**
+ * Fetches the trusted signing-key fingerprints (pinned and previous - see `pinnedSigningFingerprintsFor()`) for a
+ * message sender's `address` from the contacts in `folderUids` (the reader's contacts folders), for
+ * `evaluateMessageSecurity()`'s `pinnedSignerFingerprints`. Reads only what is already stored on the reader's own
+ * contacts - never triggers a Discovery lookup, which must not happen on message receipt (it would leak read timing to
+ * the sender's server). Pages through each folder (`PINNED_FINGERPRINT_PAGE_SIZE`, at most
+ * `PINNED_FINGERPRINT_MAX_PAGES` pages per folder). A caller rendering many messages should cache the contact list and
+ * use `pinnedSigningFingerprintsFor()` instead.
+ */
+export async function fetchPinnedSigningFingerprints(folderUids, address, client) {
+    return pinnedSigningFingerprintsFor(await listContactsInFolders(folderUids, client), address);
+}
+function uniqueByFingerprint(keys) {
+    const seen = new Set();
+    return keys.filter((key) => {
+        const fingerprint = key.fingerprint.toLowerCase();
+        if (seen.has(fingerprint)) {
+            return false;
+        }
+        seen.add(fingerprint);
+        return true;
+    });
+}
+/** The signing-key state of every contact in `contacts` with an email equal (case-insensitively) to `address`, merged -
+ * what a UI needs to compare a `signer_key_changed` message's certificate with the pinned and previous keys (their
+ * fingerprints and `notBefore`/`notAfter`/`revokedAt`/`replacedAt` dates) before calling `resolveKeyConflict()`. Empty
+ * `pinned`/`previous` and no `conflict` when no contact matches. */
+export function signerKeyStateFor(contacts, address) {
+    const matching = contactsMatching(contacts, address);
+    const pinned = uniqueByFingerprint(matching.flatMap((contact) => (contact.keys ?? []).filter((key) => key.useType === "sign")));
+    const previous = uniqueByFingerprint(matching.flatMap((contact) => (contact.previousKeys ?? []).filter((key) => key.useType === "sign")).sort((a, b) => b.replacedAt - a.replacedAt));
+    const conflict = matching.flatMap((contact) => contact.keyConflicts ?? []).find((entry) => entry.useType === "sign");
+    return { pinned, previous, ...(conflict ? { conflict } : {}) };
+}
+/** Fetches `signerKeyStateFor()` for `address` from the contacts in `folderUids`, paging exactly like
+ * `fetchPinnedSigningFingerprints()`. Reads only stored contacts - never triggers a Discovery lookup. */
+export async function fetchSignerKeyState(folderUids, address, client) {
+    return signerKeyStateFor(await listContactsInFolders(folderUids, client), address);
+}
+/**
+ * Lists a folder's soft-deleted contacts
+ (for an Outlook-style "Deleted" view) — `deleted` is an ordinary
+ * queryable field on `Contact` (a `RecoverableBaseEntity`), so this is the same `find()` the plain listing
+ * above uses, just constrained to `deleted: true` instead of the framework's own default of excluding them.
+ *
+ * Read-only for now — deliberately no `restoreContact()`: `@rapidmx/restapi`'s generic
+ * `BaseScopedChildRoute.update()` looks the target record up via a plain `findOne()` with no
+ * `includeDeleted` option, so it 404s on an already-deleted record before ever reaching the point where
+ * setting `deleted: false` would matter. Restoring would need a real fix in `@rapidmx/restapi` itself
+ * (passing `includeDeleted: true` into that lookup) — out of scope for this pass; the "Deleted" view here
+ * is browse-only until that lands.
+ */
+export function listDeletedContacts(folderUid, params = {}, client) {
+    return withClient(client, `/mail/contacts?${buildQuery(params, { folderUid, deleted: "true", sort: JSON.stringify({ displayName: "ASC" }) })}`);
+}
+export function getContact(uid, client) {
+    return withClient(client, `/mail/contacts/${encodeURIComponent(uid)}`);
+}
+export function createContact(input, client) {
+    return withClient(client, "/mail/contacts", {
+        method: "POST",
+        body: JSON.stringify({ emails: [], phones: [], addresses: [], ...input }),
+    });
+}
+export function updateContact(patch, client) {
+    return withClient(client, `/mail/contacts/${encodeURIComponent(patch.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(patch),
+    });
+}
+/** Thin `updateContact()` wrapper for toggling favorite/star status — same pattern as `mailApi.ts`'s
+ * `setMessageRead()`/`tasksApi.ts`'s `setTaskCompleted()`. Sends only `uid`/`version`/`favorite`, never
+ * the rest of `contact` (the server rejects its managed fields). */
+export function setContactFavorite(contact, favorite, client) {
+    return updateContact({ uid: contact.uid, version: contact.version, favorite }, client);
+}
+export function deleteContact(uid, version, client) {
+    return withClient(client, `/mail/contacts/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}
+/** Lists a mailbox's contact lists (Outlook-style "Your contact lists"), alphabetically by name. */
+export function listContactLists(mailboxUid, params = {}, client) {
+    return withClient(client, `/mail/contact-lists?${buildQuery(params, { mailboxUid, sort: JSON.stringify({ name: "ASC" }) })}`);
+}
+export function createContactList(input, client) {
+    return withClient(client, "/mail/contact-lists", { method: "POST", body: JSON.stringify(input) });
+}
+export function updateContactList(input, client) {
+    return withClient(client, `/mail/contact-lists/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+export function deleteContactList(uid, version, client) {
+    return withClient(client, `/mail/contact-lists/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}

package/dist/lib/contacts/vcard.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Pure client-side vCard 3.0 generate/parse — `@rapidmx/restapi` has no vCard import/export support of its
+ * own, and Outlook's Contacts UI treats this as a purely local file-format concern (a `.vcf` file never
+ * touches the server as anything but ordinary `Contact` field values), so there's nothing to add there.
+ */
+import type { Contact, ContactInput } from "./contactsApi.js";
+/** Builds a single vCard 3.0 record for one contact. */
+export declare function contactToVCard(contact: Contact): string;
+/** Builds a single `.vcf` file's text content from multiple contacts (one `BEGIN:VCARD`/`END:VCARD` block
+ * per contact — the standard way multiple vCards share one file). */
+export declare function contactsToVCardFile(contacts: Contact[]): string;
+/** A parsed vCard's fields, shaped as a partial `ContactInput` missing only the `mailboxUid`/`folderUid`
+ * scope (the caller supplies those, since they're not part of the vCard format itself). */
+export type ParsedVCardContact = Omit<ContactInput, "mailboxUid" | "folderUid">;
+/**
+ * Parses one or more vCard 2.1/3.0/4.0 records from a `.vcf` file's text content. Deliberately tolerant of
+ * fields this app doesn't model (PHOTO, BDAY, etc. — silently ignored) and of the `TYPE=` parameter being
+ * absent (defaults to "other") — real-world exported vCards vary a lot in exactly which optional parameters
+ * they include. Folded lines (a line break followed by a space or tab) are unfolded first; property group
+ * prefixes (`item1.EMAIL`, as Apple Contacts writes) are ignored; `TYPE` values are normalized (see
+ * `normalizeType()`); structured values are split on unescaped `;` only.
+ */
+export declare function parseVCards(text: string): ParsedVCardContact[];