@remit/backend 0.0.33 → 0.0.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/backend",
-  "version": "0.0.33",
+  "version": "0.0.35",
   "description": "Remit Mail Inspector API backend",
   "license": "MIT",
   "author": "",

package/scripts/backfill-list-id.ts

@@ -0,0 +1,68 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { logger } from "@remit/logger-lambda";
+import {
+	backfillListIds,
+	type ListIdBackfillCheckpoint,
+	type ListIdBackfillCheckpointStore,
+} from "@remit/mailbox-service";
+import { getClient } from "../src/service/dynamodb.js";
+
+/**
+ * One-time, full-corpus `ThreadMessage.listId` backfill (issue #263). Ships as
+ * an alternate entrypoint baked into the backend image — "the backend image
+ * with a command", the same shape `migrate.mjs` uses — rather than a service
+ * of its own. Unlike `migrate`, it is never wired into a compose one-shot: a
+ * full pass runs once per install, not on every restart. Invoke it by hand:
+ *
+ *   docker compose -f docker-compose.sqlite.yml run --rm backend \
+ *     node backfill-list-id.mjs
+ *
+ * Safe to interrupt: progress is checkpointed to disk after every page and
+ * picked back up on the next run, and every row it touches is read-only
+ * against the stored message, so a rerun after a partial pass is a no-op for
+ * everything already done.
+ */
+
+const CHECKPOINT_PATH =
+	process.env.LIST_ID_BACKFILL_CHECKPOINT_PATH ??
+	"/data/sqlite/list-id-backfill-checkpoint.json";
+
+const fileCheckpointStore: ListIdBackfillCheckpointStore = {
+	load: async () => {
+		if (!existsSync(CHECKPOINT_PATH)) return undefined;
+		const raw = await readFile(CHECKPOINT_PATH, "utf8");
+		return JSON.parse(raw) as ListIdBackfillCheckpoint;
+	},
+	save: async (checkpoint) => {
+		await mkdir(dirname(CHECKPOINT_PATH), { recursive: true });
+		await writeFile(CHECKPOINT_PATH, JSON.stringify(checkpoint));
+	},
+	clear: async () => {
+		await rm(CHECKPOINT_PATH, { force: true });
+	},
+};
+
+const run = async (): Promise<void> => {
+	const client = await getClient();
+
+	const result = await backfillListIds(
+		{
+			accountConfigService: client.accountConfig,
+			threadMessageService: client.threadMessage,
+			messageService: client.message,
+			storageService: client.storage,
+		},
+		{ checkpointStore: fileCheckpointStore, logger },
+	);
+
+	console.log("[backfill-list-id] done", result);
+};
+
+run()
+	.then(() => process.exit(0))
+	.catch((error: unknown) => {
+		console.error("[backfill-list-id] failed", error);
+		process.exit(1);
+	});

package/src/handlers/filter.test.ts

@@ -0,0 +1,165 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { UpdateFilterInput } from "@remit/data-ports";
+import { FilterScope, FilterState } from "@remit/domain-enums";
+import {
+	pickFilterUpdate,
+	rejectAnchorMutation,
+	resolveFilterScopeExpiry,
+} from "./filter.js";
+
+describe("pickFilterUpdate", () => {
+	it("carries scope and expiresAt through, alongside the predicate/action fields", () => {
+		const patch = pickFilterUpdate({
+			scope: FilterScope.Temporary,
+			expiresAt: "2027-01-01T00:00:00+00:00",
+			matchOperator: "Or",
+		});
+		assert.equal(patch.scope, FilterScope.Temporary);
+		assert.equal(patch.expiresAt, "2027-01-01T00:00:00+00:00");
+		assert.equal(patch.matchOperator, "Or");
+	});
+
+	it("leaves scope/expiresAt absent when the body doesn't touch them", () => {
+		const patch = pickFilterUpdate({ name: "Receipts" });
+		assert.equal("scope" in patch, false);
+		assert.equal("expiresAt" in patch, false);
+	});
+
+	it("drops any server-derived field smuggled into the body", () => {
+		const raw: Record<string, unknown> = {
+			name: "Receipts",
+			ttl: 123,
+			state: "Expired",
+			hasAnchor: true,
+			ruleChangedAt: 999,
+			filterId: "sneaky",
+		};
+		const patch = pickFilterUpdate(raw as Partial<UpdateFilterInput>);
+		assert.deepEqual(patch, { name: "Receipts" });
+	});
+});
+
+describe("rejectAnchorMutation", () => {
+	it("throws a 400 when the body carries anchorMessageId", () => {
+		assert.throws(
+			() => rejectAnchorMutation({ anchorMessageId: "msg-1" }),
+			(error: unknown) => {
+				assert.equal((error as { statusCode?: number }).statusCode, 400);
+				assert.match(
+					(error as Error).message,
+					/anchor can't change after creation/,
+				);
+				return true;
+			},
+		);
+	});
+
+	it("does not throw for an ordinary predicate/action/scope patch", () => {
+		assert.doesNotThrow(() =>
+			rejectAnchorMutation({
+				name: "Receipts",
+				scope: "Temporary",
+				expiresAt: "2027-01-01T00:00:00+00:00",
+			}),
+		);
+	});
+});
+
+describe("resolveFilterScopeExpiry (reader #266)", () => {
+	it("moves Standing to Temporary given a future expiresAt", () => {
+		const resolved = resolveFilterScopeExpiry(
+			{ scope: FilterScope.Standing, expiresAt: undefined },
+			{ scope: FilterScope.Temporary, expiresAt: "2099-01-01T00:00:00+00:00" },
+		);
+		assert.equal(resolved.scope, FilterScope.Temporary);
+		assert.equal(resolved.expiresAt, "2099-01-01T00:00:00+00:00");
+		assert.equal(resolved.state, FilterState.Active);
+		assert.ok(resolved.ttl && resolved.ttl > 0);
+	});
+
+	it("rejects moving to Temporary without an expiresAt", () => {
+		assert.throws(
+			() =>
+				resolveFilterScopeExpiry(
+					{ scope: FilterScope.Standing, expiresAt: undefined },
+					{ scope: FilterScope.Temporary },
+				),
+			(error: unknown) => {
+				assert.equal((error as { statusCode?: number }).statusCode, 400);
+				assert.match((error as Error).message, /needs expiresAt/);
+				return true;
+			},
+		);
+	});
+
+	it("rejects an expiresAt patch that isn't paired with a Temporary scope", () => {
+		assert.throws(
+			() =>
+				resolveFilterScopeExpiry(
+					{ scope: FilterScope.Standing, expiresAt: undefined },
+					{ expiresAt: "2099-01-01T00:00:00+00:00" },
+				),
+			(error: unknown) => {
+				assert.equal((error as { statusCode?: number }).statusCode, 400);
+				assert.match((error as Error).message, /only applies to a Temporary/);
+				return true;
+			},
+		);
+	});
+
+	it("clears expiresAt/ttl and reports Active when moving Temporary to Standing", () => {
+		const resolved = resolveFilterScopeExpiry(
+			{ scope: FilterScope.Temporary, expiresAt: "2020-01-01T00:00:00+00:00" },
+			{ scope: FilterScope.Standing },
+		);
+		assert.equal(resolved.scope, FilterScope.Standing);
+		assert.equal(resolved.expiresAt, undefined);
+		assert.equal(resolved.ttl, undefined);
+		assert.equal(resolved.state, FilterState.Active);
+	});
+
+	it("recomputes ttl for an expiresAt-only change on an already-Temporary filter", () => {
+		const resolved = resolveFilterScopeExpiry(
+			{ scope: FilterScope.Temporary, expiresAt: "2026-08-01T00:00:00+00:00" },
+			{ expiresAt: "2099-06-01T00:00:00+00:00" },
+		);
+		assert.equal(resolved.scope, FilterScope.Temporary);
+		assert.equal(resolved.expiresAt, "2099-06-01T00:00:00+00:00");
+		assert.equal(
+			resolved.ttl,
+			Math.floor(new Date("2099-06-01T00:00:00+00:00").getTime() / 1000),
+		);
+		assert.equal(resolved.state, FilterState.Active);
+	});
+
+	it("reactivates a lapsed filter extended into the future", () => {
+		const resolved = resolveFilterScopeExpiry(
+			{ scope: FilterScope.Temporary, expiresAt: "2020-01-01T00:00:00+00:00" },
+			{ expiresAt: "2099-01-01T00:00:00+00:00" },
+		);
+		assert.equal(resolved.state, FilterState.Active);
+	});
+
+	it("reads Expired immediately when the new expiresAt is already in the past", () => {
+		const resolved = resolveFilterScopeExpiry(
+			{ scope: FilterScope.Temporary, expiresAt: "2099-01-01T00:00:00+00:00" },
+			{ expiresAt: "2020-01-01T00:00:00+00:00" },
+		);
+		assert.equal(resolved.state, FilterState.Expired);
+	});
+
+	it("rejects an unparseable expiresAt", () => {
+		assert.throws(
+			() =>
+				resolveFilterScopeExpiry(
+					{ scope: FilterScope.Standing, expiresAt: undefined },
+					{ scope: FilterScope.Temporary, expiresAt: "not-a-date" },
+				),
+			(error: unknown) => {
+				assert.equal((error as { statusCode?: number }).statusCode, 400);
+				return true;
+			},
+		);
+	});
+});

package/src/handlers/filter.ts

@@ -1,11 +1,10 @@
 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 { FilterItem, UpdateFilterInput } from "@remit/data-ports";
+import { BadRequestError } from "@remit/data-ports/errors";
+import { FilterScope, FilterState } from "@remit/domain-enums";
 import type { AnchorPayload } from "@remit/search-service";
 import type { APIGatewayProxyEvent } from "aws-lambda";
 import { getAccountConfigIdFromEvent } from "../auth.js";
@@ -40,7 +39,7 @@ export interface FilterCrudDeps {
 		update(
 			accountConfigId: string,
 			filterId: string,
-			input: Partial<UpdateFilterInput>,
+			input: UpdateFilterInput,
 		): Promise<FilterItem>;
 		delete(accountConfigId: string, filterId: string): Promise<void>;
 		refreshExpiry(item: FilterItem): Promise<FilterItem>;
@@ -78,24 +77,40 @@ export const deriveFilterTtl = (
 	if (scope !== FilterScope.Temporary || !expiresAt) return undefined;
 	const ms = new Date(expiresAt).getTime();
 	if (Number.isNaN(ms)) {
-		throw new ClientError(`Invalid expiresAt: ${expiresAt}`);
+		throw new BadRequestError(`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.
+ * Reduce a PATCH body to the fields a filter update may set (RFC 034, reader
+ * #266). 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/scope/expiresAt field — the service's
+ * `changesRuleAssertion` guard then leaves `ruleChangedAt` untouched (Decision
+ * 3.2). Any field outside this set — most notably a server-derived
+ * `state`/`ttl`/`hasAnchor`/`ruleChangedAt` smuggled into the body — is
+ * dropped. `scope`/`expiresAt` land here as the caller sent them; a patch that
+ * touches either still needs `resolveFilterScopeExpiry` to merge them against
+ * the stored row and derive `ttl`/`state` before this reaches the repo.
+ *
+ * Typed against the internal `@remit/data-ports` `UpdateFilterInput`, not the
+ * generated `@remit/api-openapi-types` one: that package publishes separately
+ * from this repo, so a PR that both widens the TypeSpec model and reads the
+ * new field in the same change would typecheck in-tree (fresh local codegen)
+ * but fail `check-consumer-typecheck`/`release:dry-run`, which resolve
+ * generated `@remit/*` packages off the registry, not the local `build/`
+ * output. The data-ports shape carries every field this reads regardless —
+ * it derives from the full `Filter` row, which has never gated `scope` or
+ * `expiresAt` behind an API-visibility distinction.
  */
 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, "scope")) patch.scope = body.scope;
+	if (Object.hasOwn(body, "expiresAt")) patch.expiresAt = body.expiresAt;
 	if (Object.hasOwn(body, "matchOperator")) {
 		patch.matchOperator = body.matchOperator;
 	}
@@ -111,6 +126,91 @@ export const pickFilterUpdate = (
 	return patch;
 };
 
+/**
+ * A filter's semantic anchor is set once, from `anchorMessageId`, only on
+ * `CreateFilterInput` (RFC 034 Decision 2) — the generated `UpdateFilterInput`
+ * carries no anchor field at all, so a well-behaved client cannot express this.
+ * This only catches a caller handing the raw PATCH body an anchor field
+ * anyway, and rejects it loudly rather than silently dropping it (reader
+ * #266): repointing an anchor would silently change what a saved filter
+ * matches with nothing visible changing, and that deserves a new filter
+ * instead — scope and expiry cover the rest of what changed here.
+ */
+const ANCHOR_MUTATION_FIELDS = ["anchorMessageId"] as const;
+
+export const rejectAnchorMutation = (body: Record<string, unknown>): void => {
+	const attempted = ANCHOR_MUTATION_FIELDS.find((field) =>
+		Object.hasOwn(body, field),
+	);
+	if (!attempted) return;
+	throw new BadRequestError(
+		"A filter's semantic anchor can't change after creation — create a new filter instead.",
+	);
+};
+
+export interface ResolvedScopeExpiry {
+	scope: FilterItem["scope"];
+	expiresAt?: string;
+	ttl?: number;
+	state: FilterItem["state"];
+}
+
+/**
+ * Merge a PATCH body's `scope`/`expiresAt` against the filter's stored values
+ * and resolve the full set the row must land on (reader #266). Only called
+ * when the patch touches `scope` or `expiresAt` — one that touches neither
+ * leaves both, and `ttl`/`state`, untouched exactly as before this ticket.
+ *
+ * A `Temporary` result always carries a defined `expiresAt` — moving to
+ * `Temporary` without one is rejected, matching the Filter model's invariant
+ * that a Temporary filter always has an expiry (RFC 034 Decision 1.1). Moving
+ * to `Standing` clears `expiresAt`/`ttl`, matching the model's invariant that
+ * both stay absent outside `Temporary` (RFC 034 Decision 1.4) — the reserved
+ * `ttl` attribute must never linger once a filter is no longer temporary.
+ *
+ * `state` is recomputed the same comparison `refreshExpiry` runs, so a filter
+ * extended past a lapsed `expiresAt` (or switched to `Standing`) reads Active
+ * immediately — the index-time worker's `byAccountAndState` query needs that
+ * now, not on whatever read happens to touch the row next.
+ */
+export const resolveFilterScopeExpiry = (
+	current: Pick<FilterItem, "scope" | "expiresAt">,
+	patch: Partial<UpdateFilterInput>,
+): ResolvedScopeExpiry => {
+	const scope = patch.scope ?? current.scope;
+
+	if (scope !== FilterScope.Temporary) {
+		if (Object.hasOwn(patch, "expiresAt") && patch.expiresAt) {
+			throw new BadRequestError(
+				"expiresAt only applies to a Temporary filter — switch scope to Temporary to set one.",
+			);
+		}
+		return {
+			scope,
+			expiresAt: undefined,
+			ttl: undefined,
+			state: FilterState.Active,
+		};
+	}
+
+	const expiresAt = Object.hasOwn(patch, "expiresAt")
+		? patch.expiresAt
+		: current.expiresAt;
+	if (!expiresAt) {
+		throw new BadRequestError(
+			"A Temporary filter needs expiresAt — pick a date, or switch scope to Standing.",
+		);
+	}
+
+	const ttl = deriveFilterTtl(scope, expiresAt);
+	const state =
+		new Date(expiresAt).getTime() > Date.now()
+			? FilterState.Active
+			: FilterState.Expired;
+
+	return { scope, expiresAt, ttl, state };
+};
+
 const toFilterResponse = (item: FilterItem): FilterResponse => ({
 	filterId: item.filterId,
 	accountConfigId: item.accountConfigId,
@@ -260,17 +360,31 @@ export const FilterDetailOperations: Record<
 			accountId: string;
 			filterId: string;
 		};
-		const body = context.request.requestBody as Partial<UpdateFilterInput>;
+		const body = context.request.requestBody as Record<string, unknown>;
+		rejectAnchorMutation(body);
 
 		const client = await getClient();
 		const account = await client.account.get(accountId);
 		assertAccountOwnership(account, accountConfigId, "act");
 
 		const { filter } = client;
+		const patch = pickFilterUpdate(body as Partial<UpdateFilterInput>);
+		const touchesScopeOrExpiry =
+			Object.hasOwn(patch, "scope") || Object.hasOwn(patch, "expiresAt");
+		const resolvedPatch: Partial<UpdateFilterInput> = touchesScopeOrExpiry
+			? {
+					...patch,
+					...resolveFilterScopeExpiry(
+						await filter.get(accountConfigId, filterId),
+						patch,
+					),
+				}
+			: patch;
+
 		const updated = await filter.update(
 			accountConfigId,
 			filterId,
-			pickFilterUpdate(body),
+			resolvedPatch,
 		);
 		return toFilterResponse(updated);
 	},

package/tsconfig.json

@@ -3,5 +3,5 @@
 	"compilerOptions": {
 		"outDir": "dist"
 	},
-	"include": ["src/**/*.ts", "dev-server/**/*.ts"]
+	"include": ["src/**/*.ts", "dev-server/**/*.ts", "scripts/**/*.ts"]
 }