@rapidmx/web-client 0.21.0 → 0.23.0

package/dist/lib/mail/sendFailure.js

@@ -0,0 +1,86 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ApiRequestError } from "../util/api.js";
+/** Keys of an error body that are the message and its bookkeeping, not details. */
+const ENVELOPE_KEYS = new Set(["message", "error", "code", "status", "statusCode", "name", "stack"]);
+/** The most lines, and the longest line, one failure is reduced to - a transport can put a whole SMTP transcript in a field. */
+const MAX_LINES = 50;
+const MAX_LINE_LENGTH = 500;
+function clip(text) {
+    return text.length > MAX_LINE_LENGTH ? `${text.slice(0, MAX_LINE_LENGTH)}...` : text;
+}
+function scalar(value) {
+    if (value === null || value === undefined) {
+        return "";
+    }
+    return typeof value === "object" ? JSON.stringify(value) : String(value);
+}
+/** An object as `key=value key=value` - one recipient's result on one line. */
+function pairs(item) {
+    return Object.entries(item)
+        .filter(([, value]) => value !== undefined && value !== null && value !== "")
+        .map(([key, value]) => `${key}=${scalar(value)}`)
+        .join(" ");
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function itemLines(label, items) {
+    return items.map((item, index) => {
+        const text = isRecord(item) ? pairs(item) : scalar(item);
+        return `${label} ${index + 1}: ${text}`;
+    });
+}
+/** The lines of one details object: each scalar as `key: value`, each list as one `key N: ...` line per entry, a nested
+ * object as its `key=value` pairs. */
+function objectLines(details) {
+    const lines = [];
+    for (const [key, value] of Object.entries(details)) {
+        if (ENVELOPE_KEYS.has(key) || value === undefined || value === null || value === "") {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            lines.push(...itemLines(key, value));
+        }
+        else if (isRecord(value)) {
+            lines.push(`${key}: ${pairs(value)}`);
+        }
+        else {
+            lines.push(`${key}: ${scalar(value)}`);
+        }
+    }
+    return lines;
+}
+/**
+ * Turns whatever a failed send threw into something a compose window can show. `message` is the server's own
+ * (the error's message, else `fallback`); `lines` are the structured `details` the send endpoint adds to its error body
+ * - typically per-recipient SMTP codes, enhanced status codes, the remote server's response text and any transport
+ * error. That shape is not fixed, so this reads it defensively: the body's `details` (an object or a list), or, without
+ * one, whatever else the body carries besides its message and code. Nothing is assumed, nothing throws, and a response
+ * with no details gives no lines - the caller then shows the message alone.
+ */
+export function describeSendFailure(err, fallback) {
+    if (!(err instanceof ApiRequestError)) {
+        return { message: fallback, lines: [] };
+    }
+    const body = err.details;
+    let lines = [];
+    if (isRecord(body)) {
+        const details = body.details;
+        if (Array.isArray(details)) {
+            lines = itemLines("detail", details);
+        }
+        else if (isRecord(details)) {
+            lines = objectLines(details);
+        }
+        else if (details !== undefined && details !== null && details !== "") {
+            lines = [`details: ${scalar(details)}`];
+        }
+        else {
+            lines = objectLines(body);
+        }
+    }
+    return { message: err.message, lines: lines.slice(0, MAX_LINES).map(clip) };
+}

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

@@ -0,0 +1,69 @@
+/**
+ * A mailbox's Blocked Senders and Safe Senders lists (`Mailbox.blockedSenders`, `Mailbox.safeSenders`) - typed wrappers over
+ * `@rapidmx/restapi`'s `POST/DELETE /mail/mailboxes/:id/blocked-senders[/:entry]` and `.../safe-senders[/:entry]`, and the entry
+ * normalizer that mirrors the server's, so a form can say what is wrong with what was typed before sending it.
+ *
+ * An entry is a plain lowercase address (`user@example.com`) or a domain (`@example.com` - that exact domain, not its subdomains). Adding
+ * an entry to one list takes it off the other. Both lists are owner-level settings: every call needs FULL access to the mailbox (a 403
+ * otherwise), which the mailbox's owner and a "manager" delegate have.
+ */
+import { ApiClient } from "../util/api.js";
+/** The most entries one list may hold (a 400 past it). */
+export declare const MAX_SENDER_LIST_ENTRIES = 1000;
+/** The longest an entry may be, in characters (RFC 5321's forward-path limit). */
+export declare const MAX_SENDER_ENTRY_LENGTH = 254;
+/** Which list. */
+export type SenderListKind = "blocked" | "safe";
+/** What a change to a list answers: the entry as the server stored it, whether anything changed (`false` for an entry already there, or an absent one
+ * removed), and both lists as they now are. */
+export interface SenderListsChange {
+    entry: string;
+    changed: boolean;
+    blockedSenders: string[];
+    safeSenders: string[];
+}
+/**
+ * `value` as the canonical entry the server stores, or `undefined` when the server would refuse it (a 400): trimmed and lowercased, a plain address
+ * stays `user@example.com`, and a domain - typed `@example.com` or `example.com` - becomes `@example.com`, so the two spellings are one entry.
+ */
+export declare function normalizeSenderEntry(value: string): string | undefined;
+/** What `checkSenderEntry()` decided about what was typed. */
+export type SenderEntryCheck = {
+    ok: true;
+    entry: string;
+    kind: "address" | "domain";
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Checks what a person typed into an "add a sender" field: `{ ok: true, entry, kind }` with the canonical entry (`normalizeSenderEntry()`), or
+ * `{ ok: false, message }` with a sentence that says what is wrong - nothing typed, too long, a name with the address in angle brackets, more than one address, a
+ * domain with a single label, a non-ASCII domain - fit to show under the field.
+ */
+export declare function checkSenderEntry(value: string): SenderEntryCheck;
+/** The domain of `address` (after its last `@`), lowercased; `undefined` when it has none. */
+export declare function senderDomainOf(address: string): string | undefined;
+/** Whether `entry` (`user@example.com` or `@example.com`) names `address` - compared case-insensitively; a domain entry names that exact domain, not its subdomains. */
+export declare function senderEntryMatches(entry: string, address: string): boolean;
+/** The entry of `list` that names `address` (the address itself, or its domain), if any - the one a "blocked" or "safe" badge would come from. */
+export declare function senderListEntryFor(list: readonly string[] | null | undefined, address: string): string | undefined;
+/** `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. */
+/**
+ * Adds an address or domain to the mailbox's Blocked Senders (`POST .../blocked-senders`) and takes it off its Safe Senders. Mail from it goes to Junk Email
+ * from then on. `entry` is normalized by the server, so `Example.com` is `@example.com`; use `checkSenderEntry()` first to tell the person what is wrong.
+ * Adding an entry already there changes nothing (`changed: false`). Rejects with a 400 for an invalid entry or a full list, a 403 without full access to the
+ * mailbox, and a 404 for a mailbox the caller cannot read - or a server without the lists.
+ */
+export declare function addBlockedSender(mailboxUid: string, entry: string, client?: ApiClient): Promise<SenderListsChange>;
+/** Takes an address or domain off the mailbox's Blocked Senders (`DELETE .../blocked-senders/:entry`, the entry URL-encoded, `@` included). Removing an absent entry
+ * succeeds with `changed: false`. */
+export declare function removeBlockedSender(mailboxUid: string, entry: string, client?: ApiClient): Promise<SenderListsChange>;
+/** Adds an address or domain to the mailbox's Safe Senders (`POST .../safe-senders`) and takes it off its Blocked Senders. Authenticated mail from it (a passing DKIM signature
+ * aligned with its From domain) is then not sent to Junk Email for the spam filter's verdict; mail that fails authentication, carries a virus or is quarantined
+ * by policy still is. Errors as `addBlockedSender()`. */
+export declare function addSafeSender(mailboxUid: string, entry: string, client?: ApiClient): Promise<SenderListsChange>;
+/** Takes an address or domain off the mailbox's Safe Senders (`DELETE .../safe-senders/:entry`). Removing an absent entry succeeds with `changed: false`. */
+export declare function removeSafeSender(mailboxUid: string, entry: string, client?: ApiClient): Promise<SenderListsChange>;

package/dist/lib/mail/senderListsApi.js

@@ -0,0 +1,126 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * A mailbox's Blocked Senders and Safe Senders lists (`Mailbox.blockedSenders`, `Mailbox.safeSenders`) - typed wrappers over
+ * `@rapidmx/restapi`'s `POST/DELETE /mail/mailboxes/:id/blocked-senders[/:entry]` and `.../safe-senders[/:entry]`, and the entry
+ * normalizer that mirrors the server's, so a form can say what is wrong with what was typed before sending it.
+ *
+ * An entry is a plain lowercase address (`user@example.com`) or a domain (`@example.com` - that exact domain, not its subdomains). Adding
+ * an entry to one list takes it off the other. Both lists are owner-level settings: every call needs FULL access to the mailbox (a 403
+ * otherwise), which the mailbox's owner and a "manager" delegate have.
+ */
+import { withClient } from "../util/api.js";
+/** The most entries one list may hold (a 400 past it). */
+export const MAX_SENDER_LIST_ENTRIES = 1000;
+/** The longest an entry may be, in characters (RFC 5321's forward-path limit). */
+export const MAX_SENDER_ENTRY_LENGTH = 254;
+/** A DNS host name of at least two labels: letters, digits and inner hyphens, each label at most 63 characters, the whole at most 253. Lowercase input. */
+const DOMAIN_PATTERN = /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/;
+/** One plain address: no display name, angle brackets, group, comment, list, quoting or whitespace. */
+const PLAIN_ADDRESS_PATTERN = /^[^\s()<>@,;:\\"[\]]+@[^\s()<>@,;:\\"[\]]+$/;
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARACTER = /[\u0000-\u001F\u007F]/;
+function parseDomain(value) {
+    const trimmed = value.trim().toLowerCase();
+    const domain = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
+    return domain.length <= MAX_SENDER_ENTRY_LENGTH && DOMAIN_PATTERN.test(domain) ? domain : undefined;
+}
+function parseAddress(value) {
+    const address = value.trim().toLowerCase();
+    return address.length <= MAX_SENDER_ENTRY_LENGTH && !CONTROL_CHARACTER.test(address) && PLAIN_ADDRESS_PATTERN.test(address) ? address : undefined;
+}
+/**
+ * `value` as the canonical entry the server stores, or `undefined` when the server would refuse it (a 400): trimmed and lowercased, a plain address
+ * stays `user@example.com`, and a domain - typed `@example.com` or `example.com` - becomes `@example.com`, so the two spellings are one entry.
+ */
+export function normalizeSenderEntry(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith("@") || !trimmed.includes("@")) {
+        const domain = parseDomain(trimmed);
+        return domain === undefined ? undefined : `@${domain}`;
+    }
+    return parseAddress(trimmed);
+}
+/**
+ * Checks what a person typed into an "add a sender" field: `{ ok: true, entry, kind }` with the canonical entry (`normalizeSenderEntry()`), or
+ * `{ ok: false, message }` with a sentence that says what is wrong - nothing typed, too long, a name with the address in angle brackets, more than one address, a
+ * domain with a single label, a non-ASCII domain - fit to show under the field.
+ */
+export function checkSenderEntry(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return { ok: false, message: "Type an email address (name@example.com) or a domain (example.com)." };
+    }
+    if (trimmed.length > MAX_SENDER_ENTRY_LENGTH) {
+        return { ok: false, message: `That is longer than ${MAX_SENDER_ENTRY_LENGTH} characters.` };
+    }
+    const entry = normalizeSenderEntry(trimmed);
+    if (entry !== undefined) {
+        return { ok: true, entry, kind: entry.startsWith("@") ? "domain" : "address" };
+    }
+    if (/[<>]/.test(trimmed)) {
+        return { ok: false, message: "Type only the address, without a name or angle brackets: name@example.com." };
+    }
+    if (/[,;\s]/.test(trimmed)) {
+        return { ok: false, message: "Add one address or domain at a time, with no spaces or commas." };
+    }
+    if (trimmed.startsWith("@") || !trimmed.includes("@")) {
+        if (/[\u0080-￿]/.test(trimmed)) {
+            return { ok: false, message: "Use the ASCII (punycode) form of an international domain name, such as xn--bcher-kva.example." };
+        }
+        return { ok: false, message: "That is not a domain. Type one such as example.com, with at least two parts and only letters, digits and hyphens." };
+    }
+    return { ok: false, message: "That is not an email address. Type one such as name@example.com, or a domain such as example.com." };
+}
+/** The domain of `address` (after its last `@`), lowercased; `undefined` when it has none. */
+export function senderDomainOf(address) {
+    const at = address.lastIndexOf("@");
+    return at >= 0 && at < address.length - 1 ? address.slice(at + 1).trim().toLowerCase() : undefined;
+}
+/** Whether `entry` (`user@example.com` or `@example.com`) names `address` - compared case-insensitively; a domain entry names that exact domain, not its subdomains. */
+export function senderEntryMatches(entry, address) {
+    const lower = address.trim().toLowerCase();
+    return entry.startsWith("@") ? senderDomainOf(lower) === entry.slice(1).toLowerCase() : lower === entry.toLowerCase();
+}
+/** The entry of `list` that names `address` (the address itself, or its domain), if any - the one a "blocked" or "safe" badge would come from. */
+export function senderListEntryFor(list, address) {
+    return (list ?? []).find((entry) => senderEntryMatches(entry, address));
+}
+function listPath(mailboxUid, list) {
+    return `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/${list === "blocked" ? "blocked-senders" : "safe-senders"}`;
+}
+function add(mailboxUid, list, entry, client) {
+    return withClient(client, listPath(mailboxUid, list), { method: "POST", body: JSON.stringify({ entry }) });
+}
+function remove(mailboxUid, list, entry, client) {
+    return withClient(client, `${listPath(mailboxUid, list)}/${encodeURIComponent(entry)}`, { method: "DELETE" });
+}
+/** `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. */
+/**
+ * Adds an address or domain to the mailbox's Blocked Senders (`POST .../blocked-senders`) and takes it off its Safe Senders. Mail from it goes to Junk Email
+ * from then on. `entry` is normalized by the server, so `Example.com` is `@example.com`; use `checkSenderEntry()` first to tell the person what is wrong.
+ * Adding an entry already there changes nothing (`changed: false`). Rejects with a 400 for an invalid entry or a full list, a 403 without full access to the
+ * mailbox, and a 404 for a mailbox the caller cannot read - or a server without the lists.
+ */
+export function addBlockedSender(mailboxUid, entry, client) {
+    return add(mailboxUid, "blocked", entry, client);
+}
+/** Takes an address or domain off the mailbox's Blocked Senders (`DELETE .../blocked-senders/:entry`, the entry URL-encoded, `@` included). Removing an absent entry
+ * succeeds with `changed: false`. */
+export function removeBlockedSender(mailboxUid, entry, client) {
+    return remove(mailboxUid, "blocked", entry, client);
+}
+/** Adds an address or domain to the mailbox's Safe Senders (`POST .../safe-senders`) and takes it off its Blocked Senders. Authenticated mail from it (a passing DKIM signature
+ * aligned with its From domain) is then not sent to Junk Email for the spam filter's verdict; mail that fails authentication, carries a virus or is quarantined
+ * by policy still is. Errors as `addBlockedSender()`. */
+export function addSafeSender(mailboxUid, entry, client) {
+    return add(mailboxUid, "safe", entry, client);
+}
+/** Takes an address or domain off the mailbox's Safe Senders (`DELETE .../safe-senders/:entry`). Removing an absent entry succeeds with `changed: false`. */
+export function removeSafeSender(mailboxUid, entry, client) {
+    return remove(mailboxUid, "safe", entry, client);
+}

package/dist/lib/search/queryGrammar.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Parses `specs/search.md` §14's light operator syntax (`from:`, `to:`, `cc:`, `subject:`,
+ * `has:attachment`, `before:`, `after:`, `in:`, `is:`, `label:`, `type:`) out of a raw search box
+ * string, once, client-side — per the spec's own requirement that parsing happen in exactly one place
+ * so every tier (server Tier 1 today; a future local Tier 2/3) interprets the grammar identically.
+ *
+ * Only the *operator* tokens are extracted. Everything else — plain words, quoted phrases, a leading
+ * `-` negating a term — is left untouched in the returned `text` remainder, because each provider's own
+ * free-text engine already understands that syntax natively (`specs/search.md` §14's own "Provider
+ * Implementation": Postgres's `websearch_to_tsquery` handles quoted phrases, `OR`, and `-` negation
+ * safely on untrusted input). Rewriting that ourselves would just be a worse reimplementation of what
+ * the provider already does correctly.
+ *
+ * An operator token is only recognized when it starts at a word boundary (start of string, or after
+ * whitespace) — `-from:bob` therefore is NOT parsed as a negated operator (the operator fields
+ * `BaseSearchRoute` accepts are single-value/AND-only with no negated form) and is left in `text`
+ * verbatim, and a deliberately-quoted phrase like `"from:bob"` is never mistaken for the operator
+ * either, since the match requires an *unquoted* key immediately followed by `:`.
+ */
+import { SearchEntityType } from "./searchApi.js";
+export interface ParsedSearchQuery {
+    /** The remaining free-text portion — quotes, `-` negation, and `OR` preserved verbatim for each
+     * provider's own free-text engine to interpret. Never rewritten by this parser beyond removing the
+     * operator tokens themselves and collapsing the whitespace that leaves behind. */
+    text: string;
+    /** `from:` — sender address or display name. */
+    from?: string;
+    /** `to:` — a recipient address. */
+    to?: string;
+    /** `cc:` — a recipient address. */
+    cc?: string;
+    /** `subject:` — restricts matching to the subject/title field. */
+    subject?: string;
+    /** `has:attachment` */
+    hasAttachment?: boolean;
+    /** `before:` — parsed via `new Date()`; an unparseable value is left in `text` rather than dropped. */
+    before?: Date;
+    /** `after:` — see `before`. */
+    after?: Date;
+    /** `in:` — folder or calendar uid. */
+    folderUid?: string;
+    /** `is:` — one or more flag/state strings (`is:read`, repeated `is:` tokens, or a single
+     * comma-separated `is:read,flagged` token all accumulate into this array). */
+    flags?: string[];
+    /** `label:` — one or more `Label.uid`s. Same repeat/comma-separation rules as `flags`. */
+    labels?: string[];
+    /** `type:` — maps to `SearchQuery.entityTypes`. An unrecognized type token is dropped rather than
+     * forwarded, since the server has no representation for anything outside `SearchEntityType`. */
+    entityTypes?: SearchEntityType[];
+}
+export declare function parseSearchQuery(raw: string): ParsedSearchQuery;

package/dist/lib/search/queryGrammar.js

@@ -0,0 +1,111 @@
+const VALID_ENTITY_TYPES = new Set(["message", "contact", "calendarEvent", "note", "task"]);
+/** Finds and removes the first `key:value`/`key:"quoted value"` occurrence of `key` in `input`, where
+ * `value` is either a quoted phrase or a run of non-whitespace characters. Returns `undefined` for
+ * `value` (and `input` unchanged as `rest`) when no such token exists. The matched span is replaced by
+ * the single whitespace character that preceded it (or removed entirely at start-of-string), so
+ * `removeRange` never joins two words together — final whitespace collapsing happens once, in
+ * `parseSearchQuery()` itself, after every extraction has run. */
+function extractFirst(input, key) {
+    const pattern = new RegExp(`(^|\\s)${key}:(?:"([^"]*)"|(\\S+))`, "i");
+    const match = pattern.exec(input);
+    if (!match) {
+        return { rest: input };
+    }
+    const value = match[2] ?? match[3] ?? "";
+    const rest = input.slice(0, match.index) + match[1] + input.slice(match.index + match[0].length);
+    return { value, rest };
+}
+/** Repeatedly applies `extractFirst()` for `key` until no more occurrences remain, splitting any
+ * comma-separated value into individual entries — so `is:read is:flagged` and `is:read,flagged` both
+ * produce `["read", "flagged"]`. */
+function extractAll(input, key) {
+    const values = [];
+    let rest = input;
+    for (;;) {
+        const result = extractFirst(rest, key);
+        if (result.value === undefined) {
+            return { values, rest };
+        }
+        rest = result.rest;
+        for (const part of result.value.split(",")) {
+            const trimmed = part.trim();
+            if (trimmed) {
+                values.push(trimmed);
+            }
+        }
+    }
+}
+/** Removes the exact literal token `has:attachment` (case-insensitively), the one compound keyword the
+ * spec defines for this operator — there is no `has:<other value>` form. */
+function extractHasAttachment(input) {
+    const pattern = /(^|\s)has:attachment\b/i;
+    const match = pattern.exec(input);
+    if (!match) {
+        return { found: false, rest: input };
+    }
+    return { found: true, rest: input.slice(0, match.index) + match[1] + input.slice(match.index + match[0].length) };
+}
+/** Local midnight on `year`-`month`-`day`, or an Invalid Date when that calendar date doesn't exist
+ * (e.g. `2026-02-30`, which the `Date` constructor would otherwise silently roll over into March). */
+function localDate(year, month, day) {
+    const date = new Date(year, month - 1, day);
+    date.setFullYear(year);
+    return date.getMonth() === month - 1 && date.getDate() === day ? date : new Date(Number.NaN);
+}
+function extractDate(input, key) {
+    const { value, rest } = extractFirst(input, key);
+    if (value === undefined) {
+        return { rest: input };
+    }
+    // A date-only `yyyy-MM-dd` value means local midnight on that day (what a user typing `before:2026-01-02`
+    // means) — `new Date("2026-01-02")` alone would parse it as UTC midnight per the ECMAScript spec.
+    // Anything else (a full ISO date-time, with or without an offset) is left to `new Date()` as-is.
+    const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    const date = dateOnly ? localDate(Number(dateOnly[1]), Number(dateOnly[2]), Number(dateOnly[3])) : new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        // Unparseable — leave the whole token in the free-text remainder rather than silently dropping
+        // it, mirroring BaseSearchRoute's own parseDateParam() leniency (invalid date -> undefined).
+        return { rest: input };
+    }
+    return { date, rest };
+}
+export function parseSearchQuery(raw) {
+    let rest = raw;
+    const from = extractFirst(rest, "from");
+    rest = from.rest;
+    const to = extractFirst(rest, "to");
+    rest = to.rest;
+    const cc = extractFirst(rest, "cc");
+    rest = cc.rest;
+    const subject = extractFirst(rest, "subject");
+    rest = subject.rest;
+    const folder = extractFirst(rest, "in");
+    rest = folder.rest;
+    const hasAttachment = extractHasAttachment(rest);
+    rest = hasAttachment.rest;
+    const before = extractDate(rest, "before");
+    rest = before.rest;
+    const after = extractDate(rest, "after");
+    rest = after.rest;
+    const flags = extractAll(rest, "is");
+    rest = flags.rest;
+    const labels = extractAll(rest, "label");
+    rest = labels.rest;
+    const types = extractAll(rest, "type");
+    rest = types.rest;
+    const entityTypes = types.values.filter((t) => VALID_ENTITY_TYPES.has(t));
+    return {
+        text: rest.replace(/\s+/g, " ").trim(),
+        from: from.value,
+        to: to.value,
+        cc: cc.value,
+        subject: subject.value,
+        hasAttachment: hasAttachment.found ? true : undefined,
+        before: before.date,
+        after: after.date,
+        folderUid: folder.value,
+        flags: flags.values.length > 0 ? flags.values : undefined,
+        labels: labels.values.length > 0 ? labels.values : undefined,
+        entityTypes: entityTypes.length > 0 ? entityTypes : undefined,
+    };
+}

package/dist/lib/search/searchApi.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Client wrapper for `@rapidmx/restapi`'s `BaseSearchRoute` (mounted at `/mail/search` — see
+ * `src/mongo/routes/SearchRoute.ts`/`src/sql/routes/SearchRoute.ts`), the full-text search endpoint across
+ * a mailbox's messages/contacts/calendar events/notes/tasks. Scoped server-side to the caller's own mailbox
+ * unless an optional `mailboxUid` (one the caller can access, e.g. the currently open shared mailbox) is
+ * passed.
+ *
+ * The structured filter params below mirror `specs/search.md` §14's operator grammar
+ * (`from:`/`to:`/`cc:`/`subject:`/`has:attachment`/`before:`/`after:`/`in:`/`is:`/`label:`), already parsed
+ * out of raw query text by `queryGrammar.ts`'s `parseSearchQuery()` — this module only ever sends the
+ * already-structured result, matching `BaseSearchRoute`'s own query-param names exactly
+ * (`from`/`to`/`cc`/`subject`/`hasAttachment`/`before`/`after`/`in`/`is`/`label`).
+ */
+import { ApiClient } from "../util/api.js";
+export type SearchEntityType = "message" | "contact" | "calendarEvent" | "note" | "task";
+/** Which tier produced a result. Only `"server"` is possible until Tier 2 (local index) and Tier 3
+ * (server-assisted narrowing) exist — kept as its own type now so a future client-side tier doesn't need
+ * a breaking change to `SearchResult`. */
+export type SearchResultSource = "server" | "local" | "candidate";
+export interface SearchResult {
+    entityType: SearchEntityType;
+    entityUid: string;
+    score: number;
+    /** A short, provider-generated snippet highlighting the matched text, if supported. */
+    snippet?: string;
+    /** True when `score` is derived from server-visible metadata only (participants/date, not content —
+     * always the case for an encrypted message) and is therefore not comparable to a result scored from
+     * full content. See `searchScoring.ts` for how this is handled once mixed-source merging exists. */
+    metadataOnly?: boolean;
+    /** Which tier produced this result. Always `"server"` from this function today. */
+    source?: SearchResultSource;
+}
+export interface SearchResultPage {
+    results: SearchResult[];
+    /** Opaque cursor to pass back as `cursor` to retrieve the next page, if more results exist. */
+    nextCursor?: string;
+}
+export interface SearchParams {
+    types?: SearchEntityType[];
+    cursor?: string;
+    limit?: number;
+    /** `from:` — sender address. */
+    from?: string;
+    /** `to:` — a recipient address in the `To` line. */
+    to?: string;
+    /** `cc:` — a recipient address in the `Cc` line. */
+    cc?: string;
+    /** `subject:` — restricts matching to the subject/title field only. May be combined with free text. */
+    subject?: string;
+    /** `has:attachment` */
+    hasAttachment?: boolean;
+    /** `before:` */
+    before?: Date;
+    /** `after:` */
+    after?: Date;
+    /** `in:` — folder or calendar uid. */
+    folderUid?: string;
+    /** `is:` — one or more flag/state strings, matched as an AND (all must be present). */
+    flags?: string[];
+    /** `label:` — one or more `Label.uid`s, matched as an AND (all must be present). */
+    labels?: string[];
+    /** Which of the caller's accessible mailboxes to search (e.g. the one currently open). Omitted, the
+     * server falls back to the caller's own mailbox; access to a supplied one is checked server-side. */
+    mailboxUid?: string;
+}
+/** Exported so `admin/matterSearchApi.ts` can build the identical query-param set against a different
+ * base path (`escrow/matter-search`, plus its own required `matterId`) — `BaseMatterSearchRoute` reuses
+ * this exact same query-param grammar verbatim, per its own doc comment. */
+export declare function buildSearchParams(text: string, params: SearchParams): URLSearchParams;
+export declare function search(text: string, params?: SearchParams, client?: ApiClient): Promise<SearchResultPage>;
+/**
+ * Requests a Tier 3 candidate set (`specs/search.md` §6/§12) — identifiers only, ranked purely on
+ * server-visible metadata, never on `subject`/`body`/`attachmentText`. Not called anywhere yet (Tier 3 is
+ * a separate, not-yet-built follow-on to this pass) — added now so that work doesn't need to revisit this
+ * file's shape, since the underlying route (`BaseSearchRoute.candidates()`) is already shipped.
+ */
+export interface CandidateParams {
+    types?: SearchEntityType[];
+    /** Participant terms extracted from the query text, matched against server-visible envelope data
+     * (`from`/`to`/`cc`/`participants`). */
+    participants?: string[];
+    before?: Date;
+    after?: Date;
+    folderUid?: string;
+    flags?: string[];
+    labels?: string[];
+    limit?: number;
+    cursor?: string;
+    /** Same as `SearchParams.mailboxUid`. */
+    mailboxUid?: string;
+}
+export interface CandidateResult {
+    entityType: SearchEntityType;
+    entityUid: string;
+}
+export interface CandidateResultPage {
+    candidates: CandidateResult[];
+    nextCursor?: string;
+}
+export declare function candidates(params?: CandidateParams, client?: ApiClient): Promise<CandidateResultPage>;

package/dist/lib/search/searchApi.js

@@ -0,0 +1,107 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Client wrapper for `@rapidmx/restapi`'s `BaseSearchRoute` (mounted at `/mail/search` — see
+ * `src/mongo/routes/SearchRoute.ts`/`src/sql/routes/SearchRoute.ts`), the full-text search endpoint across
+ * a mailbox's messages/contacts/calendar events/notes/tasks. Scoped server-side to the caller's own mailbox
+ * unless an optional `mailboxUid` (one the caller can access, e.g. the currently open shared mailbox) is
+ * passed.
+ *
+ * The structured filter params below mirror `specs/search.md` §14's operator grammar
+ * (`from:`/`to:`/`cc:`/`subject:`/`has:attachment`/`before:`/`after:`/`in:`/`is:`/`label:`), already parsed
+ * out of raw query text by `queryGrammar.ts`'s `parseSearchQuery()` — this module only ever sends the
+ * already-structured result, matching `BaseSearchRoute`'s own query-param names exactly
+ * (`from`/`to`/`cc`/`subject`/`hasAttachment`/`before`/`after`/`in`/`is`/`label`).
+ */
+import { withClient } from "../util/api.js";
+/** Exported so `admin/matterSearchApi.ts` can build the identical query-param set against a different
+ * base path (`escrow/matter-search`, plus its own required `matterId`) — `BaseMatterSearchRoute` reuses
+ * this exact same query-param grammar verbatim, per its own doc comment. */
+export function buildSearchParams(text, params) {
+    const query = new URLSearchParams({ q: text });
+    if (params.types?.length) {
+        query.set("types", params.types.join(","));
+    }
+    if (params.cursor) {
+        query.set("cursor", params.cursor);
+    }
+    if (params.limit) {
+        query.set("limit", String(params.limit));
+    }
+    if (params.from) {
+        query.set("from", params.from);
+    }
+    if (params.to) {
+        query.set("to", params.to);
+    }
+    if (params.cc) {
+        query.set("cc", params.cc);
+    }
+    if (params.subject) {
+        query.set("subject", params.subject);
+    }
+    if (params.hasAttachment !== undefined) {
+        query.set("hasAttachment", String(params.hasAttachment));
+    }
+    if (params.before) {
+        query.set("before", params.before.toISOString());
+    }
+    if (params.after) {
+        query.set("after", params.after.toISOString());
+    }
+    if (params.folderUid) {
+        query.set("in", params.folderUid);
+    }
+    if (params.flags?.length) {
+        query.set("is", params.flags.join(","));
+    }
+    if (params.labels?.length) {
+        query.set("label", params.labels.join(","));
+    }
+    if (params.mailboxUid) {
+        query.set("mailboxUid", params.mailboxUid);
+    }
+    return query;
+}
+export function search(text, params = {}, client) {
+    return withClient(client, `/mail/search?${buildSearchParams(text, params).toString()}`);
+}
+function buildCandidateParams(params) {
+    const query = new URLSearchParams();
+    if (params.types?.length) {
+        query.set("types", params.types.join(","));
+    }
+    if (params.participants?.length) {
+        query.set("participants", params.participants.join(","));
+    }
+    if (params.before) {
+        query.set("before", params.before.toISOString());
+    }
+    if (params.after) {
+        query.set("after", params.after.toISOString());
+    }
+    if (params.folderUid) {
+        query.set("in", params.folderUid);
+    }
+    if (params.flags?.length) {
+        query.set("is", params.flags.join(","));
+    }
+    if (params.labels?.length) {
+        query.set("label", params.labels.join(","));
+    }
+    if (params.cursor) {
+        query.set("cursor", params.cursor);
+    }
+    if (params.limit) {
+        query.set("limit", String(params.limit));
+    }
+    if (params.mailboxUid) {
+        query.set("mailboxUid", params.mailboxUid);
+    }
+    return query;
+}
+export function candidates(params = {}, client) {
+    return withClient(client, `/mail/search/candidates?${buildCandidateParams(params).toString()}`);
+}