@remit/backend 0.0.132 → 0.0.133

package/package.json

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

package/src/handlers/filter.test.ts

@@ -10,6 +10,7 @@ import type {
 	FilterItem,
 } from "@remit/data-ports";
 import {
+	FilterDisabledReason,
 	FilterMatchOperator,
 	FilterScope,
 	FilterState,
@@ -21,6 +22,7 @@ import {
 	pickFilterUpdate,
 	rejectAnchorMutation,
 	resolveFilterScopeExpiry,
+	resolveFilterUpdate,
 } from "./filter.js";
 
 describe("pickFilterUpdate", () => {
@@ -45,7 +47,7 @@ describe("pickFilterUpdate", () => {
 		const raw: Record<string, unknown> = {
 			name: "Receipts",
 			ttl: 123,
-			state: "Expired",
+			disabledReason: "None",
 			hasAnchor: true,
 			ruleChangedAt: 999,
 			filterId: "sneaky",
@@ -55,6 +57,204 @@ describe("pickFilterUpdate", () => {
 	});
 });
 
+describe("resolveFilterUpdate (#1103)", () => {
+	const NOW = Date.parse("2026-09-25T12:00:00Z");
+	const standing = {
+		scope: FilterScope.Standing,
+		expiresAt: undefined,
+		state: FilterState.Active,
+		disabledReason: FilterDisabledReason.None,
+		actionMailboxId: "mbx-invoices",
+	};
+
+	it("carries a state the body names through to the patch", () => {
+		assert.equal(
+			pickFilterUpdate({ state: FilterState.Disabled }).state,
+			FilterState.Disabled,
+		);
+	});
+
+	it("records UserDisabled when the user turns a filter off", () => {
+		assert.deepEqual(
+			resolveFilterUpdate(standing, { state: FilterState.Disabled }, NOW),
+			{
+				state: FilterState.Disabled,
+				disabledReason: FilterDisabledReason.UserDisabled,
+			},
+		);
+	});
+
+	for (const reason of [
+		FilterDisabledReason.UserDisabled,
+		FilterDisabledReason.AwaitingFolder,
+		FilterDisabledReason.FolderCreateFailed,
+		FilterDisabledReason.FolderMissing,
+	]) {
+		it(`clears ${reason} when the user turns the filter back on`, () => {
+			assert.deepEqual(
+				resolveFilterUpdate(
+					{
+						...standing,
+						state: FilterState.Disabled,
+						disabledReason: reason,
+					},
+					{ state: FilterState.Active },
+					NOW,
+				),
+				{
+					state: FilterState.Active,
+					disabledReason: FilterDisabledReason.None,
+				},
+			);
+		});
+	}
+
+	it("keeps a disabled filter disabled, with its reason, through an expiry edit", () => {
+		const resolved = resolveFilterUpdate(
+			{ ...standing, state: FilterState.Disabled },
+			{
+				scope: FilterScope.Temporary,
+				expiresAt: "2027-01-01T00:00:00+00:00",
+			},
+			NOW,
+		);
+		assert.equal(resolved.state, FilterState.Disabled);
+		assert.equal("disabledReason" in resolved, false);
+	});
+
+	for (const reason of [
+		FilterDisabledReason.AwaitingFolder,
+		FilterDisabledReason.FolderCreateFailed,
+	]) {
+		it(`refuses to turn on a ${reason} filter that has no folder`, () => {
+			assert.throws(
+				() =>
+					resolveFilterUpdate(
+						{
+							...standing,
+							state: FilterState.Disabled,
+							disabledReason: reason,
+							actionMailboxId: "None",
+						},
+						{ state: FilterState.Active },
+						NOW,
+					),
+				/pick a folder in the rule/i,
+			);
+		});
+
+		it(`turns on a ${reason} filter once the patch names a folder`, () => {
+			assert.equal(
+				resolveFilterUpdate(
+					{
+						...standing,
+						state: FilterState.Disabled,
+						disabledReason: reason,
+						actionMailboxId: "None",
+					},
+					{ state: FilterState.Active, actionMailboxId: "mbx-picked" },
+					NOW,
+				).state,
+				FilterState.Active,
+			);
+		});
+	}
+
+	const awaiting = {
+		...standing,
+		state: FilterState.Disabled,
+		disabledReason: FilterDisabledReason.AwaitingFolder,
+		actionMailboxId: "None",
+	};
+
+	it("keeps a folderless reason when the user turns an awaiting filter off again", () => {
+		const resolved = resolveFilterUpdate(
+			awaiting,
+			{ state: FilterState.Disabled },
+			NOW,
+		);
+		assert.equal(resolved.state, FilterState.Disabled);
+		assert.equal("disabledReason" in resolved, false);
+		assert.throws(
+			() =>
+				resolveFilterUpdate(
+					{ ...awaiting, state: resolved.state ?? awaiting.state },
+					{ state: FilterState.Active },
+					NOW,
+				),
+			/pick a folder in the rule/i,
+		);
+	});
+
+	it("keeps a lapsed folderless filter off when its date moves forward", () => {
+		const lapsed = {
+			...awaiting,
+			scope: FilterScope.Temporary,
+			expiresAt: "2026-01-01T00:00:00+00:00",
+			disabledReason: FilterDisabledReason.FolderCreateFailed,
+		};
+		const resolved = resolveFilterUpdate(
+			lapsed,
+			{
+				scope: FilterScope.Temporary,
+				expiresAt: "2027-01-01T00:00:00+00:00",
+			},
+			NOW,
+		);
+		assert.equal(resolved.state, FilterState.Disabled);
+		assert.equal("disabledReason" in resolved, false);
+		assert.throws(
+			() =>
+				resolveFilterUpdate(
+					{ ...lapsed, expiresAt: "2027-01-01T00:00:00+00:00" },
+					{ state: FilterState.Active },
+					NOW,
+				),
+			/pick a folder in the rule/i,
+		);
+	});
+
+	it("marks a folderless filter UserDisabled once the user picks a folder", () => {
+		assert.deepEqual(
+			resolveFilterUpdate(awaiting, { actionMailboxId: "mbx-picked" }, NOW),
+			{
+				actionMailboxId: "mbx-picked",
+				disabledReason: FilterDisabledReason.UserDisabled,
+			},
+		);
+	});
+
+	it("refuses Expired as a state the user sets", () => {
+		assert.throws(
+			() => resolveFilterUpdate(standing, { state: FilterState.Expired }, NOW),
+			/expires through its date/,
+		);
+	});
+
+	it("refuses to turn on a temporary filter whose date has passed", () => {
+		assert.throws(
+			() =>
+				resolveFilterUpdate(
+					{
+						...standing,
+						scope: FilterScope.Temporary,
+						expiresAt: "2026-01-01T00:00:00+00:00",
+						state: FilterState.Disabled,
+					},
+					{ state: FilterState.Active },
+					NOW,
+				),
+			/has expired/,
+		);
+	});
+
+	it("leaves a patch that names neither state nor timing untouched", () => {
+		assert.deepEqual(resolveFilterUpdate(standing, { name: "Receipts" }, NOW), {
+			name: "Receipts",
+		});
+	});
+});
+
 describe("rejectAnchorMutation", () => {
 	it("throws a 400 when the body carries anchorMessageId", () => {
 		assert.throws(
@@ -197,6 +397,7 @@ describe("createFilterWithAnchor (#351)", () => {
 		name: baseInput.name,
 		scope: FilterScope.Standing,
 		state: FilterState.Active,
+		disabledReason: "None",
 		hasAnchor: false,
 		ruleChangedAt: 1_700_000_000,
 		actionChangedAt: 1_700_000_000,

package/src/handlers/filter.ts

@@ -12,7 +12,11 @@ import {
 	type UpdateFilterInput,
 } from "@remit/data-ports";
 import { BadRequestError } from "@remit/data-ports/errors";
-import { FilterScope, FilterState } from "@remit/domain-enums";
+import {
+	FilterDisabledReason,
+	FilterScope,
+	FilterState,
+} from "@remit/domain-enums";
 import type { AnchorPayload } from "@remit/search-service";
 import type { APIGatewayProxyEvent } from "aws-lambda";
 import { getAccountConfigIdFromEvent } from "../auth.js";
@@ -76,6 +80,7 @@ export const pickFilterUpdate = (
 	if (Object.hasOwn(body, "actionMailboxId")) {
 		patch.actionMailboxId = body.actionMailboxId;
 	}
+	if (Object.hasOwn(body, "state")) patch.state = body.state;
 	return patch;
 };
 
@@ -164,6 +169,115 @@ export const resolveFilterScopeExpiry = (
 	return { scope, expiresAt, ttl, state };
 };
 
+const hasLapsed = (
+	filter: Pick<FilterItem, "scope" | "expiresAt">,
+	now: number,
+): boolean =>
+	filter.scope === FilterScope.Temporary &&
+	filter.expiresAt !== undefined &&
+	new Date(filter.expiresAt).getTime() <= now;
+
+const FOLDERLESS_REASONS: ReadonlySet<FilterItem["disabledReason"]> = new Set([
+	FilterDisabledReason.AwaitingFolder,
+	FilterDisabledReason.FolderCreateFailed,
+]);
+
+const folderlessRefusal = (
+	reason: FilterItem["disabledReason"],
+): BadRequestError =>
+	new BadRequestError(
+		reason === FilterDisabledReason.AwaitingFolder
+			? "This filter has no folder to move mail into yet. Wait for its folder to be created on the mail server, or pick a folder in the rule, then turn it on."
+			: "The mail server refused to create this filter's folder. Pick a folder in the rule, then turn it on.",
+	);
+
+export const resolveFilterUpdate = (
+	current: Pick<
+		FilterItem,
+		"scope" | "expiresAt" | "state" | "disabledReason" | "actionMailboxId"
+	>,
+	patch: Partial<UpdateFilterInput>,
+	now: number = Date.now(),
+): Partial<UpdateFilterInput> => {
+	if (patch.state === FilterState.Expired) {
+		throw new BadRequestError(
+			"A filter expires through its date, not its state. Set it Active or Disabled, or change its expiry.",
+		);
+	}
+	const folderless =
+		current.state === FilterState.Disabled &&
+		FOLDERLESS_REASONS.has(current.disabledReason);
+	const folder = patch.actionMailboxId ?? current.actionMailboxId;
+	const picked = folderless && folder !== FILTER_NO_ACTION;
+	const pickedReason = picked
+		? { disabledReason: FilterDisabledReason.UserDisabled }
+		: {};
+
+	const touchesTiming =
+		Object.hasOwn(patch, "scope") || Object.hasOwn(patch, "expiresAt");
+	if (!touchesTiming && patch.state === undefined) {
+		return { ...patch, ...pickedReason };
+	}
+
+	const timing = touchesTiming
+		? resolveFilterScopeExpiry(current, patch)
+		: undefined;
+	const lapsed = timing
+		? timing.state === FilterState.Expired
+		: hasLapsed(current, now);
+
+	if (patch.state === FilterState.Active && lapsed) {
+		throw new BadRequestError(
+			"This filter has expired. Move its date forward or make it Standing to turn it back on.",
+		);
+	}
+
+	const wanted = patch.state ?? current.state;
+	const merged = { ...patch, ...timing };
+	if (wanted === FilterState.Disabled) {
+		return {
+			...merged,
+			state: FilterState.Disabled,
+			...(folderless
+				? pickedReason
+				: patch.state === FilterState.Disabled
+					? { disabledReason: FilterDisabledReason.UserDisabled }
+					: {}),
+		};
+	}
+	if (lapsed) {
+		return {
+			...merged,
+			state: FilterState.Expired,
+			disabledReason: FilterDisabledReason.None,
+		};
+	}
+	if (folderless && folder === FILTER_NO_ACTION) {
+		throw folderlessRefusal(current.disabledReason);
+	}
+	return {
+		...merged,
+		state: FilterState.Active,
+		disabledReason: FilterDisabledReason.None,
+	};
+};
+
+const assertEnabledTargetExists = async (
+	client: {
+		mailbox: Pick<IMailboxRepository, "get" | "resolveAccountId">;
+	},
+	accountId: string,
+	actionMailboxId: string,
+): Promise<void> => {
+	if (actionMailboxId === FILTER_NO_ACTION) return;
+	if ((await client.mailbox.resolveAccountId(actionMailboxId)) === null) {
+		throw new BadRequestError(
+			"The folder this filter moves mail into no longer exists. Pick another folder, then turn the filter on.",
+		);
+	}
+	await assertActionMailboxSettled(client, accountId, actionMailboxId);
+};
+
 const toFilterResponse = (item: FilterItem): FilterResponse => ({
 	filterId: item.filterId,
 	accountConfigId: item.accountConfigId,
@@ -171,6 +285,7 @@ const toFilterResponse = (item: FilterItem): FilterResponse => ({
 	scope: item.scope,
 	expiresAt: item.expiresAt,
 	state: item.state,
+	disabledReason: item.disabledReason,
 	hasAnchor: item.hasAnchor,
 	ruleChangedAt: item.ruleChangedAt,
 	actionChangedAt: item.actionChangedAt,
@@ -340,17 +455,18 @@ export const FilterDetailOperations: Record<
 		const { filter } = client;
 		const patch = pickFilterUpdate(body as Partial<UpdateFilterRequestBody>);
 		await assertActionMailboxSettled(client, accountId, patch.actionMailboxId);
-		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 current = await filter.get(accountConfigId, filterId);
+		const resolvedPatch = resolveFilterUpdate(current, patch);
+		if (
+			patch.state === FilterState.Active &&
+			patch.actionMailboxId === undefined
+		) {
+			await assertEnabledTargetExists(
+				client,
+				accountId,
+				current.actionMailboxId,
+			);
+		}
 
 		const updated = await filter.update(
 			accountConfigId,

package/src/service/organize.test.ts

@@ -109,6 +109,7 @@ const filterItem = (over: Partial<FilterItem> = {}): FilterItem => ({
 	name: "other filter",
 	scope: "Standing",
 	state: FilterState.Active,
+	disabledReason: "None",
 	hasAnchor: false,
 	ruleChangedAt: 0,
 	actionChangedAt: 0,