@remit/backend 0.0.1

package/src/handlers/thread.ts

@@ -0,0 +1,361 @@
+import type {
+	MessageCategory,
+	SenderTrust,
+	ThreadSearchResponse,
+} from "@remit/api-openapi-types";
+import type { ResultList, ThreadMessageItem } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
+import type { APIGatewayProxyEvent } from "aws-lambda";
+import type { Context } from "openapi-backend";
+import { getAccountConfigIdFromEvent } from "../auth.js";
+import {
+	type EnrichClient,
+	enrichThreadRows,
+} from "../derive/enrichThreadRows.js";
+import {
+	filterByOffRowCriteria,
+	hasOffRowCriteria,
+} from "../derive/filterThreadCriteria.js";
+import { getClient } from "../service/dynamodb.js";
+import type {
+	OperationHandler,
+	ThreadDetailOperationIds,
+	ThreadOperationIds,
+} from "../types.js";
+
+const DEFAULT_THREADS_PAGE_SIZE = 50;
+
+// Project to fields used by ListThreadsResponse — keep in sync with handler mapping.
+// Includes ThreadMessage table key fields (accountConfigId, threadMessageId) and
+// the lsi2 index components (mailboxId, sentDate) so ElectroDB can materialize
+// entities and pagination cursors from projected reads. accountConfigId +
+// fromEmail are required at read time to derive the From Address row for
+// senderTrust enrichment (see enrichThreadRows).
+const THREAD_LIST_ATTRIBUTES: ReadonlyArray<keyof ThreadMessageItem> = [
+	"threadMessageId",
+	"threadId",
+	"messageId",
+	"accountConfigId",
+	"mailboxId",
+	"fromEmail",
+	"fromName",
+	"subject",
+	"sentDate",
+	"isRead",
+	"hasAttachment",
+	"star",
+	"hasStars",
+	"isDeleted",
+	"snippet",
+	"createdAt",
+	"updatedAt",
+];
+
+/**
+ * Build the `listByMailbox` options for the thread list handler.
+ *
+ * Exposed as a pure helper so the `excludeDeleted: true` default — which is
+ * the entire point of the #212 fix on the handler side — is testable without
+ * standing up DynamoDB. The defaults must stay opt-out from the user (a
+ * future Trash / All-Mail view can flip the flag) and opt-in at the
+ * service layer.
+ */
+export const buildListThreadsOptions = (query: {
+	continuationToken?: string;
+	order?: "asc" | "desc";
+}) => ({
+	order: query.order ?? ("desc" as const),
+	continuationToken: query.continuationToken,
+	limit: DEFAULT_THREADS_PAGE_SIZE,
+	attributes: [...THREAD_LIST_ATTRIBUTES],
+	excludeDeleted: true,
+});
+
+/**
+ * Build the `searchByMailboxWindow` options for the thread search handler.
+ * Same #212 `excludeDeleted` default as `buildListThreadsOptions`. The caller's
+ * `limit` is forwarded raw and clamped server-side (THREAD_SEARCH_MAX_LIMIT).
+ */
+export const buildSearchThreadsOptions = (query: {
+	continuationToken?: string;
+	order?: "asc" | "desc";
+	limit?: number;
+}) => ({
+	order: query.order ?? ("desc" as const),
+	continuationToken: query.continuationToken,
+	limit: query.limit,
+	attributes: [...THREAD_LIST_ATTRIBUTES],
+	excludeDeleted: true,
+});
+
+const toArray = <T>(value: T | T[] | undefined): T[] | undefined => {
+	if (value === undefined) return undefined;
+	return Array.isArray(value) ? value : [value];
+};
+
+type WindowOptions = {
+	order?: "asc" | "desc";
+	limit?: number;
+	continuationToken?: string;
+	attributes?: Array<keyof ThreadMessageItem>;
+	excludeDeleted?: boolean;
+};
+
+type ThreadSearch = {
+	query?: string;
+	subject?: string;
+	from?: string;
+	unread?: boolean;
+	starred?: boolean;
+	attachments?: boolean;
+};
+
+/**
+ * Minimal client surface `executeThreadSearch` needs. Declared structurally
+ * (like `EnrichClient`) so the orchestration — index/window read, count, and
+ * the off-row enrich/filter — is testable with an in-memory fake.
+ */
+export interface ThreadSearchClient extends EnrichClient {
+	threadMessage: {
+		searchByMailboxWindow(
+			accountConfigId: string,
+			mailboxId: string,
+			search: ThreadSearch,
+			options?: WindowOptions,
+		): Promise<ResultList<ThreadMessageItem>>;
+		countByMailbox(
+			accountConfigId: string,
+			mailboxId: string,
+			search: ThreadSearch,
+			options?: {
+				limit?: number;
+				excludeDeleted?: boolean;
+				order?: "asc" | "desc";
+			},
+		): Promise<number>;
+	};
+}
+
+export type ThreadSearchParams = {
+	continuationToken?: string;
+	order?: "asc" | "desc";
+	query?: string;
+	subject?: string;
+	from?: string;
+	unread?: boolean;
+	starred?: boolean;
+	attachments?: boolean;
+	senderTrust?: SenderTrust[];
+	category?: MessageCategory[];
+	dkimMismatch?: boolean;
+	count?: boolean;
+	results?: boolean;
+	limit?: number;
+};
+
+/**
+ * Run a per-mailbox thread search: select the index/window read, optionally
+ * count, and resolve off-row criteria by enriching+filtering the window. The
+ * `results` toggle omits `items` (count-only) and `count` adds the match count.
+ * Off-row criteria force a window read+enrich even in count-only mode, since no
+ * Select:COUNT can see fields that aren't on the row.
+ */
+export const executeThreadSearch = async (
+	client: ThreadSearchClient,
+	accountConfigId: string,
+	mailboxId: string,
+	params: ThreadSearchParams,
+): Promise<ThreadSearchResponse> => {
+	const search = {
+		query: params.query,
+		subject: params.subject,
+		from: params.from,
+		unread: params.unread,
+		starred: params.starred,
+		attachments: params.attachments,
+	};
+	const offRow = {
+		senderTrust: params.senderTrust,
+		category: params.category,
+		dkimMismatch: params.dkimMismatch,
+	};
+	const wantCount = params.count === true;
+	const wantResults = params.results !== false;
+	const options = buildSearchThreadsOptions({
+		continuationToken: params.continuationToken,
+		order: params.order,
+		limit: params.limit,
+	});
+
+	if (hasOffRowCriteria(offRow)) {
+		const window = await client.threadMessage.searchByMailboxWindow(
+			accountConfigId,
+			mailboxId,
+			search,
+			options,
+		);
+		const enriched = await enrichThreadRows(
+			window.items,
+			client,
+			accountConfigId,
+		);
+		const filtered = filterByOffRowCriteria(enriched, offRow);
+		return {
+			...(wantResults
+				? { items: filtered, continuationToken: window.continuationToken }
+				: {}),
+			...(wantCount ? { count: filtered.length } : {}),
+		};
+	}
+
+	const response: ThreadSearchResponse = {};
+
+	if (wantResults) {
+		const window = await client.threadMessage.searchByMailboxWindow(
+			accountConfigId,
+			mailboxId,
+			search,
+			options,
+		);
+		response.items = await enrichThreadRows(
+			window.items,
+			client,
+			accountConfigId,
+		);
+		response.continuationToken = window.continuationToken;
+		// The window read already yielded the exact match set, so the count is
+		// its length — no separate Select:COUNT, and count == items.length by
+		// construction.
+		if (wantCount) response.count = response.items.length;
+		return response;
+	}
+
+	if (wantCount) {
+		response.count = await client.threadMessage.countByMailbox(
+			accountConfigId,
+			mailboxId,
+			search,
+			{ limit: params.limit, excludeDeleted: true, order: params.order },
+		);
+	}
+
+	return response;
+};
+
+/**
+ * Build the `listByThread` options for the thread-messages handler. Same
+ * #212 default as the listing handlers — a soft-deleted message inside a
+ * conversation should not surface in the conversation pane either.
+ */
+export const buildListThreadMessagesOptions = (query: {
+	order?: "asc" | "desc";
+	mailboxId?: string;
+}) => ({
+	order: query.order ?? ("desc" as const),
+	mailboxId: query.mailboxId,
+	excludeDeleted: true,
+});
+
+export const ThreadOperations: Record<
+	ThreadOperationIds,
+	OperationHandler<ThreadOperationIds>
+> = {
+	ThreadOperations_listThreads: async (
+		context: Context,
+		...args: unknown[]
+	) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { mailboxId } = context.request.params as { mailboxId: string };
+		const { continuationToken, order } = context.request.query as {
+			continuationToken?: string;
+			order?: "asc" | "desc";
+		};
+
+		const client = await getClient();
+		const result = await client.threadMessage.listByMailbox(
+			accountConfigId,
+			mailboxId,
+			buildListThreadsOptions({ continuationToken, order }),
+		);
+
+		const items = await enrichThreadRows(result.items, client, accountConfigId);
+
+		return {
+			items,
+			continuationToken: result.continuationToken,
+		};
+	},
+
+	ThreadOperations_searchThreads: async (
+		context: Context,
+		...args: unknown[]
+	) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { mailboxId } = context.request.params as { mailboxId: string };
+		const raw = context.request.query as {
+			continuationToken?: string;
+			order?: "asc" | "desc";
+			query?: string;
+			subject?: string;
+			from?: string;
+			unread?: boolean;
+			starred?: boolean;
+			attachments?: boolean;
+			senderTrust?: SenderTrust | SenderTrust[];
+			category?: MessageCategory | MessageCategory[];
+			dkimMismatch?: boolean;
+			count?: boolean;
+			results?: boolean;
+			limit?: number;
+		};
+
+		return executeThreadSearch(await getClient(), accountConfigId, mailboxId, {
+			...raw,
+			senderTrust: toArray(raw.senderTrust),
+			category: toArray(raw.category),
+		});
+	},
+};
+
+export const ThreadDetailOperations: Record<
+	ThreadDetailOperationIds,
+	OperationHandler<ThreadDetailOperationIds>
+> = {
+	ThreadDetailOperations_listThreadMessages: async (
+		context,
+		...args: unknown[]
+	) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { threadId } = context.request.params as { threadId: string };
+		const { order, mailboxId } = context.request.query as {
+			order?: "asc" | "desc";
+			mailboxId?: string;
+		};
+
+		const client = await getClient();
+		const result = await client.threadMessage.listByThread(
+			threadId,
+			accountConfigId,
+			buildListThreadMessagesOptions({ order, mailboxId }),
+		);
+
+		// Defense-in-depth: the query is already scoped to accountConfigId; assert
+		// no foreign row slips into the response. `read`-class → 404, no existence
+		// leak, consistent with the mailbox/message guards.
+		for (const row of result.items) {
+			if (row.accountConfigId !== accountConfigId) {
+				throw new NotFoundError(`Thread not found: ${threadId}`);
+			}
+		}
+
+		const items = await enrichThreadRows(result.items, client, accountConfigId);
+
+		return {
+			items,
+			continuationToken: result.continuationToken,
+		};
+	},
+};

package/src/handlers/unified-threads.ts

@@ -0,0 +1,196 @@
+import type {
+	AccountItem,
+	IAccountSettingRepository,
+	MailboxItem,
+} from "@remit/data-ports";
+import type { APIGatewayProxyEvent } from "aws-lambda";
+import type { Context } from "openapi-backend";
+import pMap from "p-map";
+import { getAccountConfigIdFromEvent } from "../auth.js";
+import { enrichThreadRows } from "../derive/enrichThreadRows.js";
+import { getClient } from "../service/dynamodb.js";
+import type { OperationHandler, UnifiedThreadOperationIds } from "../types.js";
+import {
+	groupAccountOverrides,
+	groupMailboxOverrides,
+} from "./account-overrides.js";
+
+const DEFAULT_UNIFIED_THREADS_PAGE_SIZE = 50;
+const MAILBOX_LIST_CONCURRENCY = 5;
+
+/**
+ * Minimal client surface for inbox discovery. Structurally satisfied by
+ * RemitClient; narrowed so unit tests can pass an in-memory fake without
+ * standing up DynamoDB.
+ */
+export interface InboxMapClient {
+	account: {
+		listAllByAccountConfig(accountConfigId: string): Promise<AccountItem[]>;
+	};
+	mailbox: {
+		listAllByAccount(accountId: string): Promise<MailboxItem[]>;
+	};
+	accountSetting: Pick<IAccountSettingRepository, "listByAccountConfig">;
+}
+
+/**
+ * Build a mailboxId→accountId map for all non-muted INBOX mailboxes across
+ * all non-muted accounts of a given accountConfigId.
+ *
+ * INBOX is identified by exact match `fullPath.toUpperCase() === "INBOX"` —
+ * MailboxSpecialUse has no Inbox value per RFC 6154. This is the same rule
+ * sync-mailboxes.ts uses for INBOX-first sync ordering. By design this matches
+ * only the top-level INBOX per account: namespaced sub-paths (`INBOX/Receipts`)
+ * and non-English server primaries are excluded from the unified view, so the
+ * product contract is "unified inbox = each account's primary INBOX, not
+ * sub-folders" — consistent with sync-mailboxes.
+ *
+ * Muted accounts and muted mailboxes are excluded so the unified thread
+ * listing respects the mute flags from #437 (#433). The mute flags now live in
+ * per-target AccountSetting rows (RFC 032), loaded once for the whole config and
+ * keyed by accountId/mailboxId; a target counts as muted only when its MutedFlag
+ * exists AND `value === true`.
+ *
+ * NOTE (read cost / mute drift): this fan-out (one listAllByAccountConfig + N
+ * per-account mailbox listings) runs on *every* page request and is not cached
+ * across a pagination session. Acceptable for v1 — mailbox lists are small —
+ * but it means the inbox/mute filter set is rebuilt per page from live state,
+ * so muting/unmuting a mailbox mid-pagination changes which rows match on
+ * subsequent pages (the cursor is an opaque byDate position; mute changes take
+ * effect on the next page, never retroactively). Memoizing the map within a
+ * session (or threading it through the continuationToken) is a natural
+ * follow-up — tracked alongside the stored-isInbox index work in issue #443.
+ */
+export const buildInboxMailboxMap = async (
+	accountConfigId: string,
+	client: InboxMapClient,
+): Promise<{
+	mailboxIdToAccountId: Map<string, string>;
+	inboxMailboxIds: Set<string>;
+}> => {
+	const [accounts, settings] = await Promise.all([
+		client.account.listAllByAccountConfig(accountConfigId),
+		client.accountSetting.listByAccountConfig(accountConfigId),
+	]);
+
+	// Mute flags live in per-target AccountSetting rows (RFC 032). A target is
+	// muted only when its MutedFlag exists and `value === true`.
+	const accountOverrides = groupAccountOverrides(settings);
+	const mailboxOverrides = groupMailboxOverrides(settings);
+	const isAccountMuted = (accountId: string): boolean =>
+		accountOverrides.get(accountId)?.muted?.value === true;
+	const isMailboxMuted = (mailboxId: string): boolean =>
+		mailboxOverrides.get(mailboxId)?.muted?.value === true;
+
+	const activeAccounts = accounts.filter(
+		(account) => !isAccountMuted(account.accountId),
+	);
+
+	const mailboxLists = await pMap(
+		activeAccounts,
+		(account) => client.mailbox.listAllByAccount(account.accountId),
+		{ concurrency: MAILBOX_LIST_CONCURRENCY },
+	);
+
+	const mailboxIdToAccountId = new Map<string, string>();
+	const inboxMailboxIds = new Set<string>();
+
+	const inboxes = mailboxLists
+		.flat()
+		.filter(
+			(mailbox) =>
+				!isMailboxMuted(mailbox.mailboxId) &&
+				mailbox.fullPath.toUpperCase() === "INBOX",
+		);
+
+	for (const mailbox of inboxes) {
+		mailboxIdToAccountId.set(mailbox.mailboxId, mailbox.accountId);
+		inboxMailboxIds.add(mailbox.mailboxId);
+	}
+
+	return { mailboxIdToAccountId, inboxMailboxIds };
+};
+
+/**
+ * Build listByDate options for the unified thread listing.
+ *
+ * Exposed as a pure helper (same pattern as `buildListThreadsOptions` in
+ * thread.ts) so the defaults — `order: "desc"`, default page size, and the
+ * non-negotiable `excludeDeleted: true` (#212) — are testable without
+ * standing up DynamoDB.
+ */
+export const buildListAllThreadsOptions = (
+	query: {
+		continuationToken?: string;
+		order?: "asc" | "desc";
+		limit?: number;
+	},
+	inboxMailboxIds: Set<string>,
+) => ({
+	order: query.order ?? ("desc" as const),
+	continuationToken: query.continuationToken,
+	limit: query.limit ?? DEFAULT_UNIFIED_THREADS_PAGE_SIZE,
+	inboxMailboxIds,
+	excludeDeleted: true,
+});
+
+/**
+ * Attach accountId to each enriched ThreadMessageResponse row using the
+ * mailboxId→accountId map built from inbox discovery. Same read-time-attach
+ * pattern as senderTrust/category in enrichThreadRows.
+ */
+export const attachAccountIds = (
+	rows: Awaited<ReturnType<typeof enrichThreadRows>>,
+	mailboxIdToAccountId: Map<string, string>,
+): typeof rows =>
+	rows.map((row) => ({
+		...row,
+		accountId: mailboxIdToAccountId.get(row.mailboxId),
+	}));
+
+export const UnifiedThreadOperations: Record<
+	UnifiedThreadOperationIds,
+	OperationHandler<UnifiedThreadOperationIds>
+> = {
+	UnifiedThreadOperations_listAllThreads: async (
+		context: Context,
+		...args: unknown[]
+	) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { continuationToken, order, limit } = context.request.query as {
+			continuationToken?: string;
+			order?: "asc" | "desc";
+			limit?: number;
+		};
+
+		const client = await getClient();
+
+		const { mailboxIdToAccountId, inboxMailboxIds } =
+			await buildInboxMailboxMap(accountConfigId, client);
+
+		if (inboxMailboxIds.size === 0) {
+			return { items: [], continuationToken: undefined };
+		}
+
+		const result = await client.threadMessage.listByDate(
+			accountConfigId,
+			buildListAllThreadsOptions(
+				{ continuationToken, order, limit },
+				inboxMailboxIds,
+			),
+		);
+
+		const enriched = await enrichThreadRows(
+			result.items,
+			client,
+			accountConfigId,
+		);
+		const items = attachAccountIds(enriched, mailboxIdToAccountId);
+
+		return {
+			items,
+			continuationToken: result.continuationToken,
+		};
+	},
+};

package/src/handlers/vip-suggestions.ts

@@ -0,0 +1,21 @@
+import type { VipSuggestionEntry } from "@remit/api-openapi-types";
+import type { AddressItem } from "@remit/data-ports";
+
+/**
+ * Map an Address row to the wire-format `VipSuggestionEntry` returned by
+ * `GET /me/vip-suggestions` (issue #234). Absent counters are normalised to
+ * zero so the UI can render `12 received · 4 sent · 2 replies` without a
+ * `?? 0` fallback at every render site.
+ */
+export const toVipSuggestionEntry = (
+	item: AddressItem,
+): VipSuggestionEntry => ({
+	addressId: item.addressId,
+	displayName: item.displayName,
+	normalizedEmail: item.normalizedEmail,
+	inboundCount: item.inboundCount ?? 0,
+	outboundCount: item.outboundCount ?? 0,
+	replyCount: item.replyCount ?? 0,
+	lastInboundAt: item.lastInboundAt,
+	lastReplyAt: item.lastReplyAt,
+});