@remit/backend 0.0.1

package/src/handlers/filter.ts

@@ -0,0 +1,294 @@
+import type {
+	CreateFilterInput,
+	FilterResponse,
+	UpdateFilterInput,
+} from "@remit/api-openapi-types";
+import type { FilterItem } from "@remit/data-ports";
+import { ClientError } from "@remit/data-ports/errors";
+import { FilterScope } from "@remit/domain-enums";
+import type { AnchorPayload } from "@remit/search-service";
+import type { APIGatewayProxyEvent } from "aws-lambda";
+import { getAccountConfigIdFromEvent } from "../auth.js";
+import { getClient } from "../service/dynamodb.js";
+import { buildFilterAnchor } from "../service/filter.js";
+import type {
+	FilterDetailOperationIds,
+	FilterOperationIds,
+	OperationHandler,
+} from "../types.js";
+import { assertAccountOwnership } from "./account-ownership.js";
+
+/**
+ * Minimal filter-service surface the CRUD handlers need — declared as a `Pick`
+ * so tests can stub it without a live table.
+ */
+export interface FilterCrudDeps {
+	filter: {
+		create(input: {
+			accountConfigId: string;
+			name: string;
+			scope: FilterItem["scope"];
+			expiresAt?: string;
+			ttl?: number;
+			matchOperator: FilterItem["matchOperator"];
+			literalClauses: FilterItem["literalClauses"];
+			actionLabelId: string;
+			actionMailboxId: string;
+			hasAnchor: boolean;
+		}): Promise<FilterItem>;
+		get(accountConfigId: string, filterId: string): Promise<FilterItem>;
+		update(
+			accountConfigId: string,
+			filterId: string,
+			input: Partial<UpdateFilterInput>,
+		): Promise<FilterItem>;
+		delete(accountConfigId: string, filterId: string): Promise<void>;
+		refreshExpiry(item: FilterItem): Promise<FilterItem>;
+		listPageByAccountConfig(
+			accountConfigId: string,
+			options?: { limit?: number; continuationToken?: string },
+		): Promise<{ items: FilterItem[]; continuationToken: string | undefined }>;
+	};
+	filterAnchor: {
+		put(input: {
+			accountConfigId: string;
+			filterId: string;
+			anchorMessageId: string;
+			anchorEmbedding: number[];
+			anchorEmbeddingId: string;
+			anchorSourceText: string;
+		}): Promise<unknown>;
+	};
+	buildAnchor(
+		accountConfigId: string,
+		anchorMessageId: string,
+	): Promise<AnchorPayload | null>;
+}
+
+/**
+ * Epoch-seconds `ttl` derived from `expiresAt`, set only for a `Temporary`
+ * filter (RFC 034 Decision 1.3). A `Standing` filter never carries `ttl` — the
+ * reserved table-wide TTL attribute must stay absent, or the row would be swept
+ * (Decision 1.4).
+ */
+export const deriveFilterTtl = (
+	scope: string,
+	expiresAt: string | undefined,
+): number | undefined => {
+	if (scope !== FilterScope.Temporary || !expiresAt) return undefined;
+	const ms = new Date(expiresAt).getTime();
+	if (Number.isNaN(ms)) {
+		throw new ClientError(`Invalid expiresAt: ${expiresAt}`);
+	}
+	return Math.floor(ms / 1000);
+};
+
+/**
+ * Reduce a PATCH body to the fields a filter update may set (RFC 034). Preserves
+ * absence: a key not present in the body is not present in the patch, so a
+ * name-only rename yields `{ name }` and never touches a predicate/action field
+ * — the service's `changesPredicateOrAction` guard then leaves `ruleChangedAt`
+ * untouched (Decision 3.2). Any field outside this set — most notably a
+ * server-derived `state`/`ruleChangedAt` smuggled into the body — is dropped.
+ */
+export const pickFilterUpdate = (
+	body: Partial<UpdateFilterInput>,
+): Partial<UpdateFilterInput> => {
+	const patch: Partial<UpdateFilterInput> = {};
+	if (Object.hasOwn(body, "name")) patch.name = body.name;
+	if (Object.hasOwn(body, "matchOperator")) {
+		patch.matchOperator = body.matchOperator;
+	}
+	if (Object.hasOwn(body, "literalClauses")) {
+		patch.literalClauses = body.literalClauses;
+	}
+	if (Object.hasOwn(body, "actionLabelId")) {
+		patch.actionLabelId = body.actionLabelId;
+	}
+	if (Object.hasOwn(body, "actionMailboxId")) {
+		patch.actionMailboxId = body.actionMailboxId;
+	}
+	return patch;
+};
+
+const toFilterResponse = (item: FilterItem): FilterResponse => ({
+	filterId: item.filterId,
+	accountConfigId: item.accountConfigId,
+	name: item.name,
+	scope: item.scope,
+	expiresAt: item.expiresAt,
+	state: item.state,
+	hasAnchor: item.hasAnchor,
+	ruleChangedAt: item.ruleChangedAt,
+	matchOperator: item.matchOperator,
+	literalClauses: item.literalClauses,
+	actionLabelId: item.actionLabelId,
+	actionMailboxId: item.actionMailboxId,
+	createdAt: item.createdAt,
+	updatedAt: item.updatedAt,
+});
+
+/**
+ * Create a filter, wiring the semantic anchor when `anchorMessageId` is set
+ * (RFC 034 Decision 2). The anchor is built first, before the row is written,
+ * so `hasAnchor` is set correctly at creation and the sibling `FilterAnchor`
+ * row is written against the new `filterId` — never a second round-trip that
+ * would bump `ruleChangedAt`. A message with no indexed chunks yields no anchor:
+ * the filter is created as purely literal (`hasAnchor: false`) rather than with
+ * an empty anchor.
+ */
+export const createFilterWithAnchor = async (
+	deps: FilterCrudDeps,
+	accountConfigId: string,
+	input: CreateFilterInput,
+): Promise<FilterItem> => {
+	const { anchorMessageId } = input;
+	const anchor = anchorMessageId
+		? await deps.buildAnchor(accountConfigId, anchorMessageId)
+		: null;
+
+	const filter = await deps.filter.create({
+		accountConfigId,
+		name: input.name,
+		scope: input.scope,
+		expiresAt: input.expiresAt,
+		ttl: deriveFilterTtl(input.scope, input.expiresAt),
+		matchOperator: input.matchOperator,
+		literalClauses: input.literalClauses,
+		actionLabelId: input.actionLabelId,
+		actionMailboxId: input.actionMailboxId,
+		hasAnchor: anchor !== null,
+	});
+
+	if (anchor && anchorMessageId) {
+		await deps.filterAnchor.put({
+			accountConfigId,
+			filterId: filter.filterId,
+			anchorMessageId,
+			anchorEmbedding: anchor.anchorEmbedding,
+			anchorEmbeddingId: anchor.anchorEmbeddingId,
+			anchorSourceText: anchor.anchorSourceText,
+		});
+	}
+
+	return filter;
+};
+
+export const FilterOperations: Record<
+	FilterOperationIds,
+	OperationHandler<FilterOperationIds>
+> = {
+	FilterOperations_listFilters: async (context, ...args: unknown[]) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { accountId } = context.request.params as { accountId: string };
+		const { continuationToken } = context.request.query as {
+			continuationToken?: string;
+		};
+
+		const client = await getClient();
+		const account = await client.account.get(accountId);
+		assertAccountOwnership(account, accountConfigId, "read");
+
+		const { filter } = client;
+		const page = await filter.listPageByAccountConfig(accountConfigId, {
+			continuationToken,
+		});
+
+		// Reading the list is one of the touch points that lazily expires a past
+		// Temporary filter (RFC 034 Decision 1.2) — a no-op write for Standing or
+		// not-yet-expired filters.
+		const items = await Promise.all(
+			page.items.map((item) => filter.refreshExpiry(item)),
+		);
+
+		return {
+			items: items.map(toFilterResponse),
+			continuationToken: page.continuationToken,
+		};
+	},
+
+	FilterOperations_createFilter: async (context, ...args: unknown[]) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { accountId } = context.request.params as { accountId: string };
+		const input = context.request.requestBody as CreateFilterInput;
+
+		const client = await getClient();
+		const account = await client.account.get(accountId);
+		assertAccountOwnership(account, accountConfigId, "act");
+
+		const filter = await createFilterWithAnchor(
+			{
+				filter: client.filter,
+				filterAnchor: client.filterAnchor,
+				buildAnchor: buildFilterAnchor,
+			},
+			accountConfigId,
+			input,
+		);
+		return toFilterResponse(filter);
+	},
+};
+
+export const FilterDetailOperations: Record<
+	FilterDetailOperationIds,
+	OperationHandler<FilterDetailOperationIds>
+> = {
+	FilterDetailOperations_getFilter: async (context, ...args: unknown[]) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { accountId, filterId } = context.request.params as {
+			accountId: string;
+			filterId: string;
+		};
+
+		const client = await getClient();
+		const account = await client.account.get(accountId);
+		assertAccountOwnership(account, accountConfigId, "read");
+
+		const { filter } = client;
+		const item = await filter.get(accountConfigId, filterId);
+		const refreshed = await filter.refreshExpiry(item);
+		return toFilterResponse(refreshed);
+	},
+
+	FilterDetailOperations_updateFilter: async (context, ...args: unknown[]) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { accountId, filterId } = context.request.params as {
+			accountId: string;
+			filterId: string;
+		};
+		const body = context.request.requestBody as Partial<UpdateFilterInput>;
+
+		const client = await getClient();
+		const account = await client.account.get(accountId);
+		assertAccountOwnership(account, accountConfigId, "act");
+
+		const { filter } = client;
+		const updated = await filter.update(
+			accountConfigId,
+			filterId,
+			pickFilterUpdate(body),
+		);
+		return toFilterResponse(updated);
+	},
+
+	FilterDetailOperations_deleteFilter: async (context, ...args: unknown[]) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { accountId, filterId } = context.request.params as {
+			accountId: string;
+			filterId: string;
+		};
+
+		const client = await getClient();
+		const account = await client.account.get(accountId);
+		assertAccountOwnership(account, accountConfigId, "act");
+
+		const { filter } = client;
+		await filter.delete(accountConfigId, filterId);
+		return { statusCode: 204 };
+	},
+};

package/src/handlers/folder-role-appointments.test.ts

@@ -0,0 +1,250 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { AccountSettingItem } from "@remit/data-ports";
+import { CanonicalMailboxRole, MailboxSpecialUse } from "@remit/domain-enums";
+import {
+	CANONICAL_ROLES,
+	type FolderCandidate,
+	findFolderForRole,
+	groupFolderAppointmentsByAccount,
+	loadFolderAppointmentsForAccount,
+	resolveFolderAppointments,
+	writeFolderRoleAppointment,
+} from "./folder-role-appointments.js";
+
+const setting = (name: string, value: string): AccountSettingItem =>
+	({
+		accountSettingId: `s-${name}`,
+		accountConfigId: "cfg-1",
+		name,
+		value: { kind: "String", value },
+		createdAt: 0,
+		updatedAt: 0,
+	}) as AccountSettingItem;
+
+describe("CANONICAL_ROLES", () => {
+	it("carries every RFC 032 anchor role, Custom excluded", () => {
+		assert.deepEqual(
+			[...CANONICAL_ROLES].sort(),
+			[
+				CanonicalMailboxRole.Inbox,
+				CanonicalMailboxRole.Drafts,
+				CanonicalMailboxRole.Sent,
+				CanonicalMailboxRole.Archive,
+				CanonicalMailboxRole.Junk,
+				CanonicalMailboxRole.Trash,
+				CanonicalMailboxRole.All,
+				CanonicalMailboxRole.Flagged,
+			].sort(),
+		);
+	});
+});
+
+describe("findFolderForRole", () => {
+	const folders: FolderCandidate[] = [
+		{ mailboxId: "mb-inbox", fullPath: "INBOX" },
+		{
+			mailboxId: "mb-drafts-empty",
+			fullPath: "INBOX/Drafts",
+			specialUse: [MailboxSpecialUse.Drafts],
+		},
+		{ mailboxId: "mb-concepten", fullPath: "INBOX/Concepten" },
+		{ mailboxId: "mb-sent", fullPath: "INBOX/Sent" },
+		{ mailboxId: "mb-sent-messages", fullPath: "INBOX/Sent Messages" },
+		{ mailboxId: "mb-news", fullPath: "INBOX/Nieuwsbrieven" },
+	];
+
+	it("matches the reserved INBOX name for Inbox", () => {
+		assert.equal(
+			findFolderForRole(CanonicalMailboxRole.Inbox, folders),
+			"mb-inbox",
+		);
+	});
+
+	it("prefers the SPECIAL-USE flag over a name hint", () => {
+		assert.equal(
+			findFolderForRole(CanonicalMailboxRole.Drafts, folders),
+			"mb-drafts-empty",
+		);
+	});
+
+	it("falls back to a weak name hint when no flag is present", () => {
+		assert.equal(
+			findFolderForRole(CanonicalMailboxRole.Sent, folders),
+			"mb-sent",
+		);
+	});
+
+	it("returns null when nothing matches", () => {
+		assert.equal(findFolderForRole(CanonicalMailboxRole.Junk, folders), null);
+	});
+
+	it("never matches a plain user folder", () => {
+		assert.equal(
+			findFolderForRole(CanonicalMailboxRole.Archive, folders),
+			null,
+		);
+	});
+});
+
+describe("resolveFolderAppointments", () => {
+	const folders: FolderCandidate[] = [
+		{ mailboxId: "mb-inbox", fullPath: "INBOX" },
+		{ mailboxId: "mb-concepten", fullPath: "INBOX/Concepten" },
+		{
+			mailboxId: "mb-spam",
+			fullPath: "INBOX/Spam",
+			specialUse: [MailboxSpecialUse.Junk],
+		},
+	];
+
+	it("carries one entry per canonical role, even when unfilled", () => {
+		const result = resolveFolderAppointments(new Map(), folders);
+		assert.deepEqual(
+			result.map((r) => r.role).sort(),
+			[...CANONICAL_ROLES].sort(),
+		);
+	});
+
+	it("prefers the persisted appointment over a fresh proposal", () => {
+		const persisted = new Map([[CanonicalMailboxRole.Drafts, "mb-concepten"]]);
+		const result = resolveFolderAppointments(persisted, folders);
+		const drafts = result.find((r) => r.role === CanonicalMailboxRole.Drafts);
+		assert.equal(drafts?.mailboxId, "mb-concepten");
+	});
+
+	it("re-proposes when the persisted mailbox no longer exists", () => {
+		const persisted = new Map([
+			[CanonicalMailboxRole.Junk, "mb-deleted-long-ago"],
+		]);
+		const result = resolveFolderAppointments(persisted, folders);
+		const junk = result.find((r) => r.role === CanonicalMailboxRole.Junk);
+		assert.equal(junk?.mailboxId, "mb-spam");
+	});
+
+	it("leaves a role unfilled when nothing persisted or proposed matches", () => {
+		const result = resolveFolderAppointments(new Map(), folders);
+		const archive = result.find((r) => r.role === CanonicalMailboxRole.Archive);
+		assert.equal(archive?.mailboxId, undefined);
+	});
+});
+
+describe("groupFolderAppointmentsByAccount", () => {
+	it("groups by accountId then role from the composite setting name", () => {
+		const settings = [
+			setting(
+				`FolderRoleAppointment#acc-1#${CanonicalMailboxRole.Drafts}`,
+				"mb-1",
+			),
+			setting(
+				`FolderRoleAppointment#acc-1#${CanonicalMailboxRole.Sent}`,
+				"mb-2",
+			),
+			setting(
+				`FolderRoleAppointment#acc-2#${CanonicalMailboxRole.Inbox}`,
+				"mb-3",
+			),
+			setting("AccountDisplayName#acc-1", "Alice"),
+		];
+		const grouped = groupFolderAppointmentsByAccount(settings);
+		assert.deepEqual(Object.fromEntries(grouped.get("acc-1") ?? []), {
+			[CanonicalMailboxRole.Drafts]: "mb-1",
+			[CanonicalMailboxRole.Sent]: "mb-2",
+		});
+		assert.deepEqual(Object.fromEntries(grouped.get("acc-2") ?? []), {
+			[CanonicalMailboxRole.Inbox]: "mb-3",
+		});
+	});
+
+	it("ignores a leftover MailboxRole#<mailboxId> row instead of throwing", () => {
+		// The #963/#964 backfill wrote `MailboxRole#<mailboxId>` rows that are no
+		// longer written but still persist in production. `FolderRoleAppointment`
+		// superseded `MailboxRole` (RFC 032 exclusive-folder-appointment, #976);
+		// a leftover row alongside real appointments must not make GET /config
+		// throw — it is simply not a folder-role appointment and gets skipped.
+		const settings = [
+			setting(
+				`FolderRoleAppointment#acc-1#${CanonicalMailboxRole.Drafts}`,
+				"mb-1",
+			),
+			setting("MailboxRole#mb-legacy", "custom"),
+		];
+		const grouped = groupFolderAppointmentsByAccount(settings);
+		assert.deepEqual(Object.fromEntries(grouped.get("acc-1") ?? []), {
+			[CanonicalMailboxRole.Drafts]: "mb-1",
+		});
+	});
+});
+
+describe("loadFolderAppointmentsForAccount", () => {
+	it("reads each role's row and collects only the ones that exist", async () => {
+		const stored = new Map<string, string>([
+			[`FolderRoleAppointment#acc-1#${CanonicalMailboxRole.Sent}`, "mb-sent"],
+		]);
+		const accountSetting = {
+			get: async (_accountConfigId: string, name: string) => {
+				const value = stored.get(name);
+				return value ? setting(name, value) : null;
+			},
+		};
+		const roles = await loadFolderAppointmentsForAccount(
+			accountSetting,
+			"cfg-1",
+			"acc-1",
+		);
+		assert.deepEqual(Object.fromEntries(roles), {
+			[CanonicalMailboxRole.Sent]: "mb-sent",
+		});
+	});
+});
+
+describe("writeFolderRoleAppointment", () => {
+	it("upserts a String-valued row for a value", async () => {
+		const calls: unknown[] = [];
+		const accountSetting = {
+			upsert: async (input: unknown) => {
+				calls.push(input);
+				return input as never;
+			},
+			delete: async () => {
+				throw new Error("should not delete");
+			},
+		};
+		await writeFolderRoleAppointment(
+			accountSetting,
+			"cfg-1",
+			"acc-1",
+			CanonicalMailboxRole.Archive,
+			"mb-archive",
+		);
+		assert.deepEqual(calls, [
+			{
+				accountConfigId: "cfg-1",
+				name: `FolderRoleAppointment#acc-1#${CanonicalMailboxRole.Archive}`,
+				value: { kind: "String", value: "mb-archive" },
+			},
+		]);
+	});
+
+	it("deletes the row when mailboxId is null (clear)", async () => {
+		const calls: unknown[][] = [];
+		const accountSetting = {
+			upsert: async () => {
+				throw new Error("should not upsert");
+			},
+			delete: async (accountConfigId: string, name: string) => {
+				calls.push([accountConfigId, name]);
+			},
+		};
+		await writeFolderRoleAppointment(
+			accountSetting,
+			"cfg-1",
+			"acc-1",
+			CanonicalMailboxRole.Archive,
+			null,
+		);
+		assert.deepEqual(calls, [
+			["cfg-1", `FolderRoleAppointment#acc-1#${CanonicalMailboxRole.Archive}`],
+		]);
+	});
+});