@remit/backend 0.0.1

package/src/handlers/organize.test.ts

@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { OrganizeInput } from "@remit/api-openapi-types";
+import { FilterMatchOperator } from "@remit/domain-enums";
+import { predicateFromInput } from "./organize.js";
+
+const input = (over: Partial<OrganizeInput> = {}): OrganizeInput => ({
+	matchOperator: FilterMatchOperator.And,
+	literalClauses: [],
+	actionLabelId: "None",
+	actionMailboxId: "None",
+	...over,
+});
+
+// A move back-apply is accepted end to end: createOrganizeJob and
+// previewOrganize no longer reject `actionMailboxId` up front (the removed
+// label-only 400). Both endpoints flatten the request into the predicate the
+// job row and the matcher share, so the proof of acceptance is that the move
+// action survives that mapping verbatim — the worker then applies it through
+// the wired placement mover (see service/organize.test.ts).
+describe("predicateFromInput (move back-apply accepted)", () => {
+	it("carries a requested move action through to the predicate", () => {
+		const predicate = predicateFromInput(
+			input({ actionMailboxId: "mbox-target" }),
+		);
+		assert.equal(predicate.actionMailboxId, "mbox-target");
+		assert.equal(predicate.actionLabelId, "None");
+	});
+
+	it("carries a combined move + label action through to the predicate", () => {
+		const predicate = predicateFromInput(
+			input({ actionLabelId: "lbl-1", actionMailboxId: "mbox-target" }),
+		);
+		assert.equal(predicate.actionMailboxId, "mbox-target");
+		assert.equal(predicate.actionLabelId, "lbl-1");
+	});
+
+	it("preserves the None sentinel for an absent action", () => {
+		const predicate = predicateFromInput(input());
+		assert.equal(predicate.actionMailboxId, "None");
+		assert.equal(predicate.actionLabelId, "None");
+	});
+});

package/src/handlers/organize.ts

@@ -0,0 +1,196 @@
+import { SendMessageCommand } from "@aws-sdk/client-sqs";
+import type {
+	CreateOrganizeJobResponse,
+	OrganizeInput,
+	OrganizeJobResponse,
+	OrganizePreviewResponse,
+} from "@remit/api-openapi-types";
+import { NotFoundError } from "@remit/data-ports/errors";
+import { logger } from "@remit/logger-lambda";
+import type { APIGatewayProxyEvent } from "aws-lambda";
+import { env } from "expect-env";
+import type { Context } from "openapi-backend";
+import { getAccountConfigIdFromEvent, getSubFromEvent } from "../auth.js";
+import { getClient, type RemitClient } from "../service/dynamodb.js";
+import {
+	buildOrganizeMatchDeps,
+	matchOrganize,
+	ORGANIZE_MATCH_LIMIT,
+	type OrganizePredicate,
+} from "../service/organize.js";
+import { sqsClient } from "../service/sqs.js";
+import type {
+	OperationHandler,
+	OrganizeJobDetailOperationIds,
+	OrganizeOperationIds,
+} from "../types.js";
+import { assertAccountOwnership } from "./account-ownership.js";
+
+const NONE = "None";
+
+/**
+ * How long a finished (or abandoned) job row lingers before the table-wide TTL
+ * reclaims it (RFC 034 Decision 1). A back-apply runs once and needs no standing
+ * lifetime; a week is ample for a client to poll the result.
+ */
+const ORGANIZE_JOB_TTL_SECONDS = 7 * 24 * 60 * 60;
+
+/**
+ * Normalize the request body into the flattened predicate the job row and the
+ * matcher share. `anchorMessageId` collapses to the `"None"` sentinel when
+ * absent, and `similarityThreshold` to the server default — the persisted entity
+ * carries no optional fields (RFC 032).
+ */
+export const predicateFromInput = (
+	input: OrganizeInput,
+): OrganizePredicate => ({
+	anchorMessageId: input.anchorMessageId ?? NONE,
+	matchOperator: input.matchOperator,
+	literalClauses: input.literalClauses,
+	similarityThreshold: input.similarityThreshold ?? 0.75,
+	actionLabelId: input.actionLabelId,
+	actionMailboxId: input.actionMailboxId,
+});
+
+const assertAccount = async (
+	client: RemitClient,
+	accountId: string,
+	accountConfigId: string,
+	mode: "read" | "act",
+): Promise<void> => {
+	const account = await client.account.get(accountId);
+	assertAccountOwnership(account, accountConfigId, mode);
+};
+
+const toOrganizeJobResponse = (
+	job: Awaited<ReturnType<RemitClient["organizeJobRequest"]["get"]>>,
+): OrganizeJobResponse => ({
+	organizeJobId: job.organizeJobId,
+	accountConfigId: job.accountConfigId,
+	userId: job.userId,
+	state: job.state,
+	anchorMessageId: job.anchorMessageId,
+	matchOperator: job.matchOperator,
+	literalClauses: job.literalClauses,
+	similarityThreshold: job.similarityThreshold,
+	actionLabelId: job.actionLabelId,
+	actionMailboxId: job.actionMailboxId,
+	matchedCount: job.matchedCount,
+	appliedCount: job.appliedCount,
+	failedCount: job.failedCount,
+	errorMessage: job.errorMessage,
+	createdAt: job.createdAt,
+	updatedAt: job.updatedAt,
+});
+
+export const OrganizeOperations: Record<
+	OrganizeOperationIds,
+	OperationHandler<OrganizeOperationIds>
+> = {
+	OrganizeOperations_createOrganizeJob: async (
+		context: Context,
+		...args: unknown[]
+	): Promise<CreateOrganizeJobResponse> => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { accountId } = context.request.params as { accountId: string };
+		const input = context.request.requestBody as OrganizeInput;
+
+		const userId = getSubFromEvent(event);
+		if (!userId) {
+			throw new Error(
+				"Missing Cognito `sub`: cannot attribute an organize job to a user",
+			);
+		}
+
+		const client = await getClient();
+		await assertAccount(client, accountId, accountConfigId, "act");
+
+		const predicate = predicateFromInput(input);
+		const ttl = Math.floor(Date.now() / 1000) + ORGANIZE_JOB_TTL_SECONDS;
+
+		const job = await client.organizeJobRequest.create({
+			accountConfigId,
+			userId,
+			anchorMessageId: predicate.anchorMessageId,
+			matchOperator: predicate.matchOperator,
+			literalClauses: predicate.literalClauses,
+			similarityThreshold: predicate.similarityThreshold,
+			actionLabelId: predicate.actionLabelId,
+			actionMailboxId: predicate.actionMailboxId,
+			ttl,
+		});
+
+		await sqsClient.send(
+			new SendMessageCommand({
+				QueueUrl: env.SQS_QUEUE_URL_ACCOUNT_FANOUT,
+				MessageBody: JSON.stringify({
+					type: "OrganizeJob",
+					accountConfigId,
+					organizeJobId: job.organizeJobId,
+				}),
+			}),
+		);
+
+		// biome-ignore lint/plugin/no-logger-info: a back-apply is an audit-grade signal
+		logger.info(
+			{ accountConfigId, organizeJobId: job.organizeJobId },
+			"Organize back-apply job initiated",
+		);
+
+		return {
+			statusCode: 202,
+			organizeJobId: job.organizeJobId,
+			state: job.state,
+		};
+	},
+
+	OrganizeOperations_previewOrganize: async (
+		context: Context,
+		...args: unknown[]
+	): Promise<OrganizePreviewResponse> => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { accountId } = context.request.params as { accountId: string };
+		const input = context.request.requestBody as OrganizeInput;
+
+		const client = await getClient();
+		await assertAccount(client, accountId, accountConfigId, "read");
+
+		const messageIds = await matchOrganize(
+			buildOrganizeMatchDeps(client),
+			accountConfigId,
+			predicateFromInput(input),
+			ORGANIZE_MATCH_LIMIT,
+		);
+
+		return { matchedCount: messageIds.length, messageIds };
+	},
+};
+
+export const OrganizeJobDetailOperations: Record<
+	OrganizeJobDetailOperationIds,
+	OperationHandler<OrganizeJobDetailOperationIds>
+> = {
+	OrganizeJobDetailOperations_getOrganizeJob: async (
+		context: Context,
+		...args: unknown[]
+	): Promise<OrganizeJobResponse> => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { accountId, organizeJobId } = context.request.params as {
+			accountId: string;
+			organizeJobId: string;
+		};
+
+		const client = await getClient();
+		await assertAccount(client, accountId, accountConfigId, "read");
+
+		const job = await client.organizeJobRequest.get(organizeJobId);
+		if (job.accountConfigId !== accountConfigId) {
+			throw new NotFoundError(`Organize job not found: ${organizeJobId}`);
+		}
+
+		return toOrganizeJobResponse(job);
+	},
+};

package/src/handlers/outbox.ts

@@ -0,0 +1,218 @@
+import type {
+	CreateOutboxMessageInput,
+	OutboxMessageResponse,
+	UpdateOutboxMessageInput,
+} from "@remit/api-openapi-types";
+import type { OutboxMessageItem } from "@remit/data-ports";
+import { ForbiddenError } from "@remit/data-ports/errors";
+import type { APIGatewayProxyEvent } from "aws-lambda";
+import type { Context } from "openapi-backend";
+import { getAccountConfigIdFromEvent } from "../auth.js";
+import { getClient } from "../service/dynamodb.js";
+import type {
+	OperationHandler,
+	OutboxDetailOperationIds,
+	OutboxOperationIds,
+} from "../types.js";
+
+const toOutboxMessageResponse = (
+	item: OutboxMessageItem,
+): OutboxMessageResponse => ({
+	outboxMessageId: item.outboxMessageId,
+	accountId: item.accountId,
+	fromAddress: item.fromAddress,
+	fromName: item.fromName,
+	toAddresses: item.toAddresses,
+	ccAddresses: item.ccAddresses ?? [],
+	bccAddresses: item.bccAddresses ?? [],
+	subject: item.subject,
+	textBody: item.textBody,
+	htmlBody: item.htmlBody,
+	inReplyTo: item.inReplyTo,
+	references: item.references ?? [],
+	status: item.status,
+	lastError: item.lastError,
+	sentAt: item.sentAt,
+	createdAt: item.createdAt,
+	updatedAt: item.updatedAt,
+});
+
+export const OutboxOperations: Record<
+	OutboxOperationIds,
+	OperationHandler<OutboxOperationIds>
+> = {
+	OutboxOperations_createOutboxMessage: async (
+		_context: Context,
+		...args: unknown[]
+	): Promise<OutboxMessageResponse> => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const input = JSON.parse(event.body ?? "{}") as CreateOutboxMessageInput;
+
+		const client = await getClient();
+
+		const account = await client.account.get(input.accountId);
+		if (account.accountConfigId !== accountConfigId) {
+			throw new ForbiddenError(
+				`Account ${input.accountId} not in account config`,
+			);
+		}
+
+		const fromAddress = account.email;
+
+		if (input.sendImmediately) {
+			const outbox = await client.outboxQueue.createAndSend({
+				accountId: input.accountId,
+				accountConfigId,
+				fromAddress,
+
+				toAddresses: input.toAddresses,
+				ccAddresses: input.ccAddresses,
+				bccAddresses: input.bccAddresses,
+				subject: input.subject,
+				textBody: input.textBody,
+				htmlBody: input.htmlBody,
+				inReplyTo: input.inReplyTo,
+				references: input.references,
+			});
+			return toOutboxMessageResponse(outbox);
+		}
+
+		const outbox = await client.outboxQueue.createDraft({
+			accountId: input.accountId,
+			accountConfigId,
+			fromAddress,
+
+			toAddresses: input.toAddresses,
+			ccAddresses: input.ccAddresses,
+			bccAddresses: input.bccAddresses,
+			subject: input.subject,
+			textBody: input.textBody,
+			htmlBody: input.htmlBody,
+			inReplyTo: input.inReplyTo,
+			references: input.references,
+		});
+		return toOutboxMessageResponse(outbox);
+	},
+
+	OutboxOperations_listOutboxMessages: async (
+		context: Context,
+		...args: unknown[]
+	) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { continuationToken } = context.request.query as {
+			continuationToken?: string;
+		};
+
+		const client = await getClient();
+
+		const accounts = await client.account.list(accountConfigId);
+		if (accounts.items.length === 0) {
+			return { items: [], continuationToken: null };
+		}
+
+		const accountId = accounts.items[0].accountId;
+		const result = await client.outboxMessage.listByAccount(accountId, {
+			continuationToken,
+		});
+
+		return {
+			items: result.items.map(toOutboxMessageResponse),
+			continuationToken: result.continuationToken,
+		};
+	},
+};
+
+export const OutboxDetailOperations: Record<
+	OutboxDetailOperationIds,
+	OperationHandler<OutboxDetailOperationIds>
+> = {
+	OutboxDetailOperations_getOutboxMessage: async (
+		context: Context,
+		...args: unknown[]
+	): Promise<OutboxMessageResponse> => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { outboxMessageId } = context.request.params as {
+			outboxMessageId: string;
+		};
+
+		const client = await getClient();
+		// Default mode "read": the scoped get refuses a foreign message with
+		// NotFound (404, no existence leak) — no separate check needed.
+		const outbox = await client.outboxMessage.get(
+			accountConfigId,
+			outboxMessageId,
+		);
+		return toOutboxMessageResponse(outbox);
+	},
+
+	OutboxDetailOperations_updateOutboxMessage: async (
+		context: Context,
+		...args: unknown[]
+	): Promise<OutboxMessageResponse> => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { outboxMessageId } = context.request.params as {
+			outboxMessageId: string;
+		};
+		const input = context.request.requestBody as UpdateOutboxMessageInput;
+
+		const client = await getClient();
+		// updateDraft's own scoped get uses mode "act": a foreign message is
+		// denied with Forbidden (403), not feigned as NotFound.
+		const updated = await client.outboxQueue.updateDraft(
+			accountConfigId,
+			outboxMessageId,
+			{
+				toAddresses: input.toAddresses,
+				ccAddresses: input.ccAddresses,
+				bccAddresses: input.bccAddresses,
+				subject: input.subject,
+				textBody: input.textBody,
+				htmlBody: input.htmlBody,
+				inReplyTo: input.inReplyTo,
+				references: input.references,
+			},
+		);
+		return toOutboxMessageResponse(updated);
+	},
+
+	OutboxDetailOperations_deleteOutboxMessage: async (
+		context: Context,
+		...args: unknown[]
+	) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { outboxMessageId } = context.request.params as {
+			outboxMessageId: string;
+		};
+
+		const client = await getClient();
+		// deleteDraft's own scoped get uses mode "act": a foreign message is
+		// denied with Forbidden (403), not feigned as NotFound.
+		await client.outboxQueue.deleteDraft(accountConfigId, outboxMessageId);
+		return { statusCode: 204 };
+	},
+
+	OutboxDetailOperations_sendOutboxMessage: async (
+		context: Context,
+		...args: unknown[]
+	): Promise<OutboxMessageResponse> => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { outboxMessageId } = context.request.params as {
+			outboxMessageId: string;
+		};
+
+		const client = await getClient();
+		// send's own scoped get uses mode "act": a foreign message is denied
+		// with Forbidden (403), not feigned as NotFound.
+		const sent = await client.outboxQueue.send(
+			accountConfigId,
+			outboxMessageId,
+		);
+		return toOutboxMessageResponse(sent);
+	},
+};

package/src/handlers/search.test.ts

@@ -0,0 +1,182 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { SemanticSearchResult } from "@remit/api-openapi-types";
+import type {
+	SearchParams,
+	SearchResult,
+	SearchService,
+} from "@remit/search-service";
+
+interface CapturedSearch {
+	calls: SearchParams[];
+}
+
+const buildFakeSearch = (
+	results: SearchResult[],
+): { service: SearchService; captured: CapturedSearch } => {
+	const captured: CapturedSearch = { calls: [] };
+	const service: SearchService = {
+		index: async () => {},
+		prepareVectors: async () => [],
+		upsertVectors: async () => ({ upserted: 0, skipped: 0 }),
+		indexIncremental: async () => ({ upserted: 0, skipped: 0 }),
+		delete: async () => {},
+		search: async (params) => {
+			captured.calls.push(params);
+			return results;
+		},
+	};
+	return { service, captured };
+};
+
+const toResponse = (item: SearchResult): SemanticSearchResult => {
+	const result: SemanticSearchResult = {
+		messageId: item.messageId,
+		threadId: item.threadId,
+		score: item.score,
+		matchedChunkType: item.matchedChunkType,
+		mailboxIds: item.mailboxIds,
+		sentDate: item.sentDate,
+	};
+	if (item.fromName !== undefined) {
+		result.fromName = item.fromName ?? undefined;
+	}
+	if (item.subject !== undefined) {
+		result.subject = item.subject;
+	}
+	if (item.category !== undefined) {
+		result.category = item.category;
+	}
+	return result;
+};
+
+describe("SemanticSearch handler response mapping", () => {
+	it("maps SearchResult into SemanticSearchResult preserving all fields", () => {
+		const item: SearchResult = {
+			messageId: "msg-alice",
+			threadId: "thread-a",
+			score: 0.87,
+			matchedChunkType: "sender",
+			mailboxIds: ["mb-inbox", "mb-archive"],
+			sentDate: 1_700_000_000,
+		};
+		const out = toResponse(item);
+		assert.equal(out.messageId, "msg-alice");
+		assert.equal(out.threadId, "thread-a");
+		assert.equal(out.score, 0.87);
+		assert.equal(out.matchedChunkType, "sender");
+		assert.deepEqual(out.mailboxIds, ["mb-inbox", "mb-archive"]);
+		assert.equal(out.sentDate, 1_700_000_000);
+	});
+
+	it("includes fromName and subject when present in SearchResult", () => {
+		const item: SearchResult = {
+			messageId: "msg-bob",
+			threadId: "thread-b",
+			score: 0.72,
+			matchedChunkType: "body",
+			mailboxIds: ["mb-inbox"],
+			sentDate: 1_700_001_000,
+			fromName: "Bob Smith",
+			subject: "Weekly sync",
+		};
+		const out = toResponse(item);
+		assert.equal(out.fromName, "Bob Smith");
+		assert.equal(out.subject, "Weekly sync");
+		assert.equal(out.sentDate, 1_700_001_000);
+	});
+
+	it("echoes category back when present in SearchResult", () => {
+		const item: SearchResult = {
+			messageId: "msg-news",
+			threadId: "thread-news",
+			score: 0.81,
+			matchedChunkType: "body",
+			mailboxIds: ["mb-inbox"],
+			sentDate: 1_700_003_000,
+			category: "newsletter",
+		};
+		const out = toResponse(item);
+		assert.equal(out.category, "newsletter");
+	});
+
+	it("omits category when absent (pre-enrichment vectors)", () => {
+		const item: SearchResult = {
+			messageId: "msg-legacy",
+			threadId: "thread-legacy",
+			score: 0.4,
+			matchedChunkType: "body",
+			mailboxIds: ["mb-archive"],
+			sentDate: 1_600_000_000,
+		};
+		const out = toResponse(item);
+		assert.equal(out.category, undefined);
+	});
+
+	it("omits fromName when it is null (sender has no display name)", () => {
+		const item: SearchResult = {
+			messageId: "msg-carol",
+			threadId: "thread-c",
+			score: 0.6,
+			matchedChunkType: "sender",
+			mailboxIds: ["mb-inbox"],
+			sentDate: 1_700_002_000,
+			fromName: null,
+			subject: "No-name sender",
+		};
+		const out = toResponse(item);
+		assert.equal(out.fromName, undefined);
+		assert.equal(out.subject, "No-name sender");
+	});
+
+	it("omits fromName and subject when absent (pre-enrichment vectors)", () => {
+		const item: SearchResult = {
+			messageId: "msg-legacy",
+			threadId: "thread-legacy",
+			score: 0.5,
+			matchedChunkType: "body",
+			mailboxIds: ["mb-archive"],
+			sentDate: 1_600_000_000,
+		};
+		const out = toResponse(item);
+		assert.equal(out.fromName, undefined);
+		assert.equal(out.subject, undefined);
+		assert.equal(out.sentDate, 1_600_000_000);
+	});
+});
+
+describe("SemanticSearch handler search invocation", () => {
+	it("forwards filters from the request to the search service", async () => {
+		const { service, captured } = buildFakeSearch([
+			{
+				messageId: "msg-bob",
+				threadId: "thread-b",
+				score: 0.5,
+				matchedChunkType: "body",
+				mailboxIds: ["mb-inbox"],
+				sentDate: 1_700_000_000,
+			},
+		]);
+
+		const results = await service.search({
+			query: "alice",
+			accountConfigId: "acct-1",
+			mailboxId: "mb-inbox",
+			sentDateRange: { from: 100, to: 200 },
+			hasAttachment: true,
+			category: "newsletter",
+			limit: 10,
+		});
+
+		assert.equal(results.length, 1);
+		assert.equal(captured.calls.length, 1);
+		const call = captured.calls[0];
+		assert.equal(call.query, "alice");
+		assert.equal(call.accountConfigId, "acct-1");
+		assert.equal(call.mailboxId, "mb-inbox");
+		assert.deepEqual(call.sentDateRange, { from: 100, to: 200 });
+		assert.equal(call.hasAttachment, true);
+		assert.equal(call.category, "newsletter");
+		assert.equal(call.limit, 10);
+	});
+});