@rapidmx/web-client 0.21.0 → 0.22.0

package/lib/mail/senderListsApi.ts

@@ -0,0 +1,161 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { ApiClient, 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;
+
+/** 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[];
+}
+
+/** 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: string): string | undefined {
+    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: string): string | undefined {
+    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: string): string | undefined {
+    const trimmed = value.trim();
+    if (trimmed.startsWith("@") || !trimmed.includes("@")) {
+        const domain = parseDomain(trimmed);
+        return domain === undefined ? undefined : `@${domain}`;
+    }
+    return parseAddress(trimmed);
+}
+
+/** 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 function checkSenderEntry(value: string): SenderEntryCheck {
+    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: string): string | undefined {
+    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: string, address: string): boolean {
+    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: readonly string[] | null | undefined, address: string): string | undefined {
+    return (list ?? []).find((entry) => senderEntryMatches(entry, address));
+}
+
+function listPath(mailboxUid: string, list: SenderListKind): string {
+    return `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/${list === "blocked" ? "blocked-senders" : "safe-senders"}`;
+}
+
+function add(mailboxUid: string, list: SenderListKind, entry: string, client?: ApiClient): Promise<SenderListsChange> {
+    return withClient(client, listPath(mailboxUid, list), { method: "POST", body: JSON.stringify({ entry }) });
+}
+
+function remove(mailboxUid: string, list: SenderListKind, entry: string, client?: ApiClient): Promise<SenderListsChange> {
+    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: string, entry: string, client?: ApiClient): Promise<SenderListsChange> {
+    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: string, entry: string, client?: ApiClient): Promise<SenderListsChange> {
+    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: string, entry: string, client?: ApiClient): Promise<SenderListsChange> {
+    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: string, entry: string, client?: ApiClient): Promise<SenderListsChange> {
+    return remove(mailboxUid, "safe", entry, client);
+}

package/lib/search/queryGrammar.ts

@@ -0,0 +1,179 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * 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[];
+}
+
+const VALID_ENTITY_TYPES: ReadonlySet<string> = new Set<SearchEntityType>(["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: string, key: string): { value?: string; rest: string } {
+    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: string, key: string): { values: string[]; rest: string } {
+    const values: string[] = [];
+    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: string): { found: boolean; rest: string } {
+    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: number, month: number, day: number): Date {
+    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: string, key: string): { date?: Date; rest: string } {
+    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: string): ParsedSearchQuery {
+    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): t is SearchEntityType => 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/lib/search/searchApi.ts

@@ -0,0 +1,199 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { ApiClient, withClient } 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 function buildSearchParams(text: string, params: SearchParams): URLSearchParams {
+    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: string, params: SearchParams = {}, client?: ApiClient): Promise<SearchResultPage> {
+    return withClient(client, `/mail/search?${buildSearchParams(text, params).toString()}`);
+}
+
+/**
+ * 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;
+}
+
+function buildCandidateParams(params: CandidateParams): URLSearchParams {
+    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: CandidateParams = {}, client?: ApiClient): Promise<CandidateResultPage> {
+    return withClient(client, `/mail/search/candidates?${buildCandidateParams(params).toString()}`);
+}

package/lib/search/searchScoring.ts

@@ -0,0 +1,46 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Client-side re-scoring per `specs/search.md` §7 "Ranking and Merge": scores from different search
+ * sources are not comparable — a Postgres `ts_rank`, an OpenSearch `_score`, and a future local FTS5
+ * `bm25()` value occupy different, provider-specific ranges. The spec requires normalizing every
+ * source's scores into one shared space rather than interleaving raw values.
+ *
+ * This pass only has one source (Tier 1 - the server), so there is nothing to *merge* yet - the real
+ * cross-tier merge (§7's full ranking pass, §8's composite pagination cursor) is Tier 2/3 work,
+ * deliberately out of scope for this pass. What's implemented here is the normalization step itself,
+ * written generically (one page's raw scores in, normalized scores out) so a future per-source call
+ * into the same function is all cross-tier merging needs to add - not a second implementation of
+ * normalization.
+ */
+
+/** The spec's own field-weight table (§7), exported for reuse by whichever component eventually
+ * computes a *local* (Tier 2) score from decrypted content - the same weights must produce ranking
+ * that matches today's server-side behavior. */
+export const SEARCH_FIELD_WEIGHTS = {
+    subject: 3,
+    participants: 2,
+    body: 1,
+    attachmentText: 1,
+} as const;
+
+/**
+ * Normalizes one page's raw provider scores into `[0, 1]`, preserving relative order, so a caller never
+ * has to reason about a specific provider's raw score range. `0` for every result when every score in
+ * the page is equal (including the degenerate single-result and all-zero cases) - there is no relative
+ * ordering information to preserve in that case, and `0` is a safer default than an arbitrary `1`.
+ */
+export function normalizeServerScores<T extends { score: number }>(results: readonly T[]): { result: T; normalizedScore: number }[] {
+    if (results.length === 0) {
+        return [];
+    }
+    const maxScore = Math.max(...results.map((r) => r.score));
+    const minScore = Math.min(...results.map((r) => r.score));
+    const range = maxScore - minScore;
+    return results.map((result) => ({
+        result,
+        normalizedScore: range === 0 ? 0 : (result.score - minScore) / range,
+    }));
+}