@remit/web-client 0.0.1

package/src/lib/search-query.test.ts

@@ -0,0 +1,35 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { normalizeSearchQuery } from "./search-query.js";
+
+describe("normalizeSearchQuery", () => {
+	test("lowercases an ASCII query", () => {
+		assert.equal(normalizeSearchQuery("ALICE"), "alice");
+	});
+
+	test("lowercases a mixed-case query", () => {
+		assert.equal(
+			normalizeSearchQuery("Alice@Example.COM"),
+			"alice@example.com",
+		);
+	});
+
+	test("trims surrounding whitespace", () => {
+		assert.equal(normalizeSearchQuery("   Bob  "), "bob");
+	});
+
+	test("returns an empty string for whitespace-only input", () => {
+		assert.equal(normalizeSearchQuery("   "), "");
+	});
+
+	test("leaves an already-lowercase query unchanged", () => {
+		assert.equal(normalizeSearchQuery("invoice 2026"), "invoice 2026");
+	});
+
+	test("handles non-ASCII letters via locale-aware lowercasing", () => {
+		// `toLocaleLowerCase` folds these where `String.prototype.toLowerCase`
+		// would also work for Latin-1, but we exercise it to lock the contract.
+		assert.equal(normalizeSearchQuery("ÄPPEL"), "äppel");
+		assert.equal(normalizeSearchQuery("STRAẞE"), "straße");
+	});
+});

package/src/lib/search-query.ts

@@ -0,0 +1,11 @@
+// Pre-query normalizer for the mail search bar. We keep the user's typed
+// casing visible in the input and the "results for X" header, but the value
+// sent to the backend (and used as the React Query cache key) is folded to
+// lowercase so equivalent searches collide on the same cache entry and the
+// server-side comparison is case-insensitive.
+//
+// `toLocaleLowerCase` (no locale arg) uses the host locale, which handles
+// Unicode edge cases that ASCII `toLowerCase` mishandles — most notably the
+// Turkish dotless I (`I` → `ı` / `İ` → `i`).
+export const normalizeSearchQuery = (query: string): string =>
+	query.trim().toLocaleLowerCase();

package/src/lib/search-result.test.ts

@@ -0,0 +1,160 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import type {
+	RemitImapSemanticSearchResult,
+	RemitImapThreadMessageResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import {
+	matchedChunkLabel,
+	relatedSearchResults,
+	semanticToSearchResult,
+	threadToSearchResult,
+} from "./search-result.js";
+
+function hit(
+	overrides: Partial<RemitImapSemanticSearchResult> &
+		Pick<RemitImapSemanticSearchResult, "messageId" | "threadId" | "score">,
+): RemitImapSemanticSearchResult {
+	return {
+		matchedChunkType: "body",
+		mailboxIds: [],
+		...overrides,
+	};
+}
+
+describe("semanticToSearchResult", () => {
+	test("maps display fields and converts epoch seconds to ms", () => {
+		const result = semanticToSearchResult(
+			hit({
+				messageId: "m1",
+				threadId: "t1",
+				score: 0.9,
+				fromName: "Stripe",
+				subject: "Invoice ready",
+				sentDate: 1_700_000_000,
+			}),
+		);
+		assert.strictEqual(result.id, "m1");
+		assert.strictEqual(result.sender, "Stripe");
+		assert.strictEqual(result.subject, "Invoice ready");
+		assert.notStrictEqual(result.date, "");
+	});
+
+	test("falls back when denormalized display fields are absent", () => {
+		const result = semanticToSearchResult(
+			hit({ messageId: "m2", threadId: "t2", score: 0.5 }),
+		);
+		assert.strictEqual(result.sender, "Unknown");
+		assert.strictEqual(result.subject, "(No subject)");
+		assert.strictEqual(result.date, "");
+	});
+
+	// The bug: without thread + mailbox the brief could only look the hit up by
+	// messageId in its loaded list, where a related hit isn't found — so it must
+	// carry both so the conversation opens directly.
+	test("carries the thread and first mailbox so the hit opens directly", () => {
+		const result = semanticToSearchResult(
+			hit({
+				messageId: "m3",
+				threadId: "t3",
+				score: 0.7,
+				mailboxIds: ["mb-inbox", "mb-other"],
+			}),
+		);
+		assert.strictEqual(result.threadId, "t3");
+		assert.strictEqual(result.mailboxId, "mb-inbox");
+	});
+
+	test("omits mailboxId when the hit carries no mailbox", () => {
+		const result = semanticToSearchResult(
+			hit({ messageId: "m4", threadId: "t4", score: 0.3, mailboxIds: [] }),
+		);
+		assert.strictEqual(result.threadId, "t4");
+		assert.strictEqual(result.mailboxId, undefined);
+	});
+
+	test("carries the matched-chunk label and score so the row can show why it matched", () => {
+		const result = semanticToSearchResult(
+			hit({
+				messageId: "m5",
+				threadId: "t5",
+				score: 0.42,
+				matchedChunkType: "attachment",
+			}),
+		);
+		assert.strictEqual(result.matchedChunkLabel, "attachment");
+		assert.strictEqual(result.score, 0.42);
+	});
+});
+
+describe("matchedChunkLabel", () => {
+	test("labels every known chunk type", () => {
+		assert.strictEqual(matchedChunkLabel("body"), "body");
+		assert.strictEqual(matchedChunkLabel("subject"), "subject");
+		assert.strictEqual(matchedChunkLabel("sender"), "sender");
+		assert.strictEqual(matchedChunkLabel("recipient"), "recipient");
+		assert.strictEqual(matchedChunkLabel("attachment"), "attachment");
+		assert.strictEqual(matchedChunkLabel("entities"), "entities");
+	});
+});
+
+describe("threadToSearchResult", () => {
+	test("carries thread and mailbox so a literal hit opens directly", () => {
+		const result = threadToSearchResult({
+			messageId: "m1",
+			threadId: "t1",
+			mailboxId: "mb1",
+			subject: "Hi",
+			isRead: true,
+			sentDate: 1_700_000_000_000,
+		} as RemitImapThreadMessageResponse);
+		assert.strictEqual(result.id, "m1");
+		assert.strictEqual(result.threadId, "t1");
+		assert.strictEqual(result.mailboxId, "mb1");
+	});
+});
+
+describe("relatedSearchResults", () => {
+	test("orders by score descending", () => {
+		const results = relatedSearchResults(
+			[
+				hit({ messageId: "m1", threadId: "t1", score: 0.2 }),
+				hit({ messageId: "m2", threadId: "t2", score: 0.9 }),
+				hit({ messageId: "m3", threadId: "t3", score: 0.5 }),
+			],
+			[],
+		);
+		assert.deepStrictEqual(
+			results.map((r) => r.id),
+			["m2", "m3", "m1"],
+		);
+	});
+
+	test("excludes threads already shown under Top matches", () => {
+		const results = relatedSearchResults(
+			[
+				hit({ messageId: "m1", threadId: "shared", score: 0.9 }),
+				hit({ messageId: "m2", threadId: "t2", score: 0.5 }),
+			],
+			["shared"],
+		);
+		assert.deepStrictEqual(
+			results.map((r) => r.id),
+			["m2"],
+		);
+	});
+
+	test("collapses multiple hits in the same thread to one row", () => {
+		const results = relatedSearchResults(
+			[
+				hit({ messageId: "m1", threadId: "t1", score: 0.9 }),
+				hit({ messageId: "m2", threadId: "t1", score: 0.4 }),
+			],
+			[],
+		);
+		assert.deepStrictEqual(
+			results.map((r) => r.id),
+			["m1"],
+		);
+	});
+});

package/src/lib/search-result.ts

@@ -0,0 +1,102 @@
+/**
+ * Map the row shapes the app carries onto the kit `SearchResult` the search
+ * results render. Two feed the literal "Top matches" section (per-mailbox
+ * `RemitImapThreadMessageResponse` and the brief/flagged `ThreadRowData`); the
+ * third (`RemitImapSemanticSearchResult`) feeds the semantic "Related" section.
+ */
+import type {
+	RemitImapSemanticSearchChunkType,
+	RemitImapSemanticSearchResult,
+	RemitImapThreadMessageResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import type { SearchResult, ThreadRowData } from "@remit/ui";
+import { formatEmailDate } from "./format.js";
+
+/**
+ * Plain-language label for the `matched: …` chip, so the user understands why
+ * a "Related" hit matched (#428). Falls back to the raw chunk type for any
+ * value the backend adds later that the client doesn't know about yet.
+ */
+const MATCHED_CHUNK_LABELS: Record<RemitImapSemanticSearchChunkType, string> = {
+	sender: "sender",
+	recipient: "recipient",
+	subject: "subject",
+	attachment: "attachment",
+	body: "body",
+	entities: "entities",
+};
+
+export function matchedChunkLabel(
+	chunkType: RemitImapSemanticSearchChunkType,
+): string {
+	return MATCHED_CHUNK_LABELS[chunkType] ?? chunkType;
+}
+
+export function threadToSearchResult(
+	thread: RemitImapThreadMessageResponse,
+): SearchResult {
+	return {
+		id: thread.messageId,
+		sender: thread.fromName ?? thread.fromEmail ?? "Unknown",
+		subject: thread.subject ?? "(No subject)",
+		snippet: thread.snippet ?? "",
+		date: formatEmailDate(thread.sentDate),
+		unread: !thread.isRead,
+		flagged: thread.hasStars === true,
+		threadId: thread.threadId,
+		mailboxId: thread.mailboxId,
+	};
+}
+
+export function rowToSearchResult(row: ThreadRowData): SearchResult {
+	return {
+		id: row.id,
+		sender: row.fromName,
+		subject: row.subject,
+		snippet: row.snippet,
+		date: row.timeLabel,
+		unread: !row.isRead,
+		flagged: row.starred === true,
+	};
+}
+
+/**
+ * Map a semantic hit onto a `SearchResult`. Display fields are denormalized at
+ * index time and absent for older entries, so each falls back. Read/star state
+ * isn't carried by the semantic index, so the row renders neutral. `sentDate` is
+ * epoch seconds; `formatEmailDate` takes epoch ms.
+ */
+export function semanticToSearchResult(
+	hit: RemitImapSemanticSearchResult,
+): SearchResult {
+	return {
+		id: hit.messageId,
+		sender: hit.fromName ?? "Unknown",
+		subject: hit.subject ?? "(No subject)",
+		snippet: "",
+		date: hit.sentDate != null ? formatEmailDate(hit.sentDate * 1000) : "",
+		threadId: hit.threadId,
+		matchedChunkLabel: matchedChunkLabel(hit.matchedChunkType),
+		score: hit.score,
+		...(hit.mailboxIds[0] != null ? { mailboxId: hit.mailboxIds[0] } : {}),
+	};
+}
+
+/**
+ * Build the semantic "Related" section: order by score (most relevant first),
+ * collapse to one row per thread, and drop any thread already shown under the
+ * literal "Top matches" — literal precedence, so a thread never appears twice.
+ */
+export function relatedSearchResults(
+	hits: RemitImapSemanticSearchResult[],
+	literalThreadIds: Iterable<string>,
+): SearchResult[] {
+	const seenThreadIds = new Set<string>(literalThreadIds);
+	const results: SearchResult[] = [];
+	for (const hit of [...hits].sort((a, b) => b.score - a.score)) {
+		if (seenThreadIds.has(hit.threadId)) continue;
+		seenThreadIds.add(hit.threadId);
+		results.push(semanticToSearchResult(hit));
+	}
+	return results;
+}

package/src/lib/search-schemas.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+
+export const paginationSchema = z.object({
+	page: z.number().int().positive().default(1),
+	limit: z.number().int().min(10).max(100).default(50),
+	cursor: z.string().optional(),
+});
+
+export const mailListSearchSchema = z.object({
+	filter: z.enum(["all", "unread", "starred", "attachments"]).default("all"),
+	sort: z.enum(["date", "sender", "subject"]).default("date"),
+	order: z.enum(["asc", "desc"]).default("desc"),
+
+	...paginationSchema.shape,
+
+	dialog: z.enum(["compose", "move", "delete", "settings"]).optional(),
+
+	selectedThreadId: z.string().optional(),
+	selectedMessageId: z.string().optional(),
+
+	q: z.string().optional(),
+});
+
+export type MailListSearch = z.infer<typeof mailListSearchSchema>;
+
+export const threadViewSearchSchema = z.object({
+	expandedMessageId: z.string().optional(),
+	expandAll: z.boolean().default(false),
+
+	dialog: z.enum(["reply", "reply-all", "forward", "delete"]).optional(),
+	replyToMessageId: z.string().optional(),
+});
+
+export type ThreadViewSearch = z.infer<typeof threadViewSearchSchema>;

package/src/lib/search-token-index.test.ts

@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type {
+	RemitImapAccountResponse,
+	RemitImapMailboxResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import {
+	buildAccountNameIndex,
+	buildMailboxNameIndex,
+} from "./search-token-index.js";
+
+const account = (
+	overrides: Partial<RemitImapAccountResponse> &
+		Pick<RemitImapAccountResponse, "accountId" | "email">,
+): RemitImapAccountResponse =>
+	({
+		accountConfigId: "cfg-1",
+		username: "user",
+		imapHost: "imap.example.com",
+		imapPort: 993,
+		imapTls: true,
+		imapStartTls: false,
+		smtpHost: "smtp.example.com",
+		smtpPort: 587,
+		smtpTls: false,
+		smtpStartTls: true,
+		smtpUsername: "user",
+		isActive: true,
+		createdAt: 1000,
+		updatedAt: 1000,
+		...overrides,
+	}) as RemitImapAccountResponse;
+
+const mailbox = (
+	overrides: Partial<RemitImapMailboxResponse> &
+		Pick<RemitImapMailboxResponse, "mailboxId" | "fullPath">,
+): RemitImapMailboxResponse =>
+	({
+		accountId: "account-1",
+		namespaceType: "personal",
+		namespacePrefix: "",
+		hierarchyDelimiter: "/",
+		messageCount: 0,
+		unseenCount: 0,
+		deletedCount: 0,
+		lastSyncUid: 0,
+		highWaterMarkUid: 0,
+		lastMessageSyncAt: 0,
+		createdAt: 1000,
+		updatedAt: 1000,
+		...overrides,
+	}) as RemitImapMailboxResponse;
+
+describe("buildAccountNameIndex", () => {
+	it("indexes by local-part and full email, lower-cased", () => {
+		const index = buildAccountNameIndex([
+			account({ accountId: "acct-1", email: "Work@Company.com" }),
+		]);
+		assert.equal(index.get("work"), "acct-1");
+		assert.equal(index.get("work@company.com"), "acct-1");
+	});
+
+	it("first account wins a local-part collision", () => {
+		const index = buildAccountNameIndex([
+			account({ accountId: "acct-1", email: "work@company.com" }),
+			account({ accountId: "acct-2", email: "work@other.com" }),
+		]);
+		assert.equal(index.get("work"), "acct-1");
+	});
+
+	it("empty accounts yields an empty index", () => {
+		assert.deepEqual(buildAccountNameIndex([]), new Map());
+	});
+});
+
+describe("buildMailboxNameIndex", () => {
+	it("indexes by full path and last segment, lower-cased", () => {
+		const index = buildMailboxNameIndex([
+			[mailbox({ mailboxId: "mb-1", fullPath: "INBOX/Archive" })],
+		]);
+		assert.equal(index.get("inbox/archive"), "mb-1");
+		assert.equal(index.get("archive"), "mb-1");
+	});
+
+	it("merges mailbox lists across multiple accounts", () => {
+		const index = buildMailboxNameIndex([
+			[mailbox({ mailboxId: "mb-1", fullPath: "Archive" })],
+			[mailbox({ mailboxId: "mb-2", fullPath: "Sent" })],
+		]);
+		assert.equal(index.get("archive"), "mb-1");
+		assert.equal(index.get("sent"), "mb-2");
+	});
+
+	it("first mailbox wins a name collision across accounts", () => {
+		const index = buildMailboxNameIndex([
+			[mailbox({ mailboxId: "mb-1", fullPath: "Archive" })],
+			[mailbox({ mailboxId: "mb-2", fullPath: "Archive" })],
+		]);
+		assert.equal(index.get("archive"), "mb-1");
+	});
+
+	it("skips mailboxes with no fullPath", () => {
+		const index = buildMailboxNameIndex([
+			[mailbox({ mailboxId: "mb-1", fullPath: "" })],
+		]);
+		assert.equal(index.size, 0);
+	});
+
+	it("empty input yields an empty index", () => {
+		assert.deepEqual(buildMailboxNameIndex([]), new Map());
+	});
+});

package/src/lib/search-token-index.ts

@@ -0,0 +1,56 @@
+/**
+ * Builds the name -> id indexes `parseSearchTokens` uses to resolve `in:` and
+ * `account:` tokens (#428 follow-up, see doc/design/flows/06-search.md). Pure
+ * functions over already-loaded data; the caller owns fetching accounts and
+ * mailboxes (`useMailboxNameIndex` fans out the mailbox-list queries).
+ */
+import type {
+	RemitImapAccountResponse,
+	RemitImapMailboxResponse,
+} from "@remit/api-http-client/types.gen.ts";
+
+/**
+ * Account email (and its local-part before `@`) -> accountId, lower-cased.
+ * `account:work` matches an account whose email starts with `work@`, mirroring
+ * the label the nav sidebar and daily brief account chips already show
+ * (`account.email.split("@")[0]`). The first account wins a collision.
+ */
+export function buildAccountNameIndex(
+	accounts: RemitImapAccountResponse[],
+): Map<string, string> {
+	const index = new Map<string, string>();
+	for (const account of accounts) {
+		const email = account.email.toLowerCase();
+		const localPart = email.split("@")[0];
+		if (localPart && !index.has(localPart)) {
+			index.set(localPart, account.accountId);
+		}
+		if (!index.has(email)) index.set(email, account.accountId);
+	}
+	return index;
+}
+
+/**
+ * Mailbox full path (and its last path segment) -> mailboxId, lower-cased, so
+ * `in:archive` matches a mailbox at `INBOX/Archive` as well as one literally
+ * named `Archive`. Takes one mailbox list per account (as returned by the
+ * per-account mailbox-list fan-out) and merges them into one index; the first
+ * mailbox wins a name collision across accounts.
+ */
+export function buildMailboxNameIndex(
+	mailboxesByAccount: RemitImapMailboxResponse[][],
+): Map<string, string> {
+	const index = new Map<string, string>();
+	for (const mailboxes of mailboxesByAccount) {
+		for (const mailbox of mailboxes) {
+			const fullPath = mailbox.fullPath?.toLowerCase();
+			if (!fullPath) continue;
+			const lastSegment = fullPath.split("/").pop();
+			if (!index.has(fullPath)) index.set(fullPath, mailbox.mailboxId);
+			if (lastSegment && !index.has(lastSegment)) {
+				index.set(lastSegment, mailbox.mailboxId);
+			}
+		}
+	}
+	return index;
+}