@remit/backend 0.0.1

package/src/service/organize.ts

@@ -0,0 +1,354 @@
+import type { FilterItem, OrganizeJobRequestItem } from "@remit/data-ports";
+import {
+	DEFAULT_SEMANTIC_MATCH_THRESHOLD,
+	type FilterMessage,
+	literalClausesMatch,
+	NO_ACTION,
+	PlacementMoveService,
+} from "@remit/mailbox-service";
+import {
+	type AnchorPayload,
+	buildMessageAnchor,
+	type VectorRecord,
+	type VectorStoreService,
+} from "@remit/search-service";
+import {
+	buildEmbeddingServiceFromEnv,
+	buildVectorStoreFromEnv,
+} from "@remit/search-service/from-env";
+import type { RemitClient } from "./dynamodb.js";
+
+/**
+ * Hard cap on both the previewed and the applied set. A back-apply is a
+ * data-heavy corpus pass (remit-data-heavy: frugal): the semantic side is
+ * bounded by the vector query's `topK`, the literal-only side by a paginated
+ * message scan, and the final match set never exceeds this.
+ */
+export const ORGANIZE_MATCH_LIMIT = 500;
+
+/**
+ * How many chunk matches to pull per requested message. A message contributes
+ * several chunk vectors (sender / subject / body / …); over-fetching chunks
+ * keeps enough distinct messages after de-duplication to fill the cap.
+ */
+const VECTOR_CHUNK_FACTOR = 8;
+
+/**
+ * The predicate + action for one back-apply pass — the OrganizeInput fields,
+ * flattened. `anchorMessageId` uses the `"None"` sentinel (never optional) to
+ * mean "purely literal", matching how the job row and the action fields carry
+ * absence (RFC 034 Decision 3.1).
+ */
+export interface OrganizePredicate {
+	anchorMessageId: string;
+	matchOperator: FilterItem["matchOperator"];
+	literalClauses: FilterItem["literalClauses"];
+	similarityThreshold: number;
+	actionLabelId: string;
+	actionMailboxId: string;
+}
+
+/**
+ * The predicate a back-apply job snapshotted onto its row, read back verbatim so
+ * the worker runs exactly what the request asked for.
+ */
+export const predicateFromJob = (
+	job: OrganizeJobRequestItem,
+): OrganizePredicate => ({
+	anchorMessageId: job.anchorMessageId,
+	matchOperator: job.matchOperator,
+	literalClauses: job.literalClauses,
+	similarityThreshold: job.similarityThreshold,
+	actionLabelId: job.actionLabelId,
+	actionMailboxId: job.actionMailboxId,
+});
+
+export interface OrganizeMatchDeps {
+	buildAnchor: (
+		accountConfigId: string,
+		anchorMessageId: string,
+	) => Promise<AnchorPayload | null>;
+	vectorStore: Pick<VectorStoreService, "query" | "getByMessage">;
+	listAccountMessageIds: (
+		accountConfigId: string,
+		limit: number,
+	) => Promise<string[]>;
+}
+
+const hasAnchor = (predicate: OrganizePredicate): boolean =>
+	predicate.anchorMessageId !== NO_ACTION && predicate.anchorMessageId !== "";
+
+/**
+ * Reconstruct the literal-match view of a message from its already-indexed chunk
+ * vectors — no body fetch, no re-embedding (remit-data-heavy: frugal). The
+ * sender chunk carries the from address, the subject/body chunks the text; each
+ * is the same 512-char preview the semantic side is derived from.
+ */
+const filterMessageFromChunks = (
+	records: VectorRecord[],
+): FilterMessage | null => {
+	if (records.length === 0) return null;
+	let subject = "";
+	let fromName = "";
+	let from = "";
+	const textParts: string[] = [];
+	for (const record of records) {
+		const meta = record.metadata;
+		if (meta.subject && !subject) subject = meta.subject;
+		if (meta.fromName && !fromName) fromName = meta.fromName;
+		if (meta.chunkType === "sender" && meta.textPreview && !from) {
+			from = meta.textPreview;
+		}
+		if (
+			(meta.chunkType === "body" || meta.chunkType === "subject") &&
+			meta.textPreview
+		) {
+			textParts.push(meta.textPreview);
+		}
+	}
+	return { from, fromName, subject, text: textParts.join("\n") };
+};
+
+/**
+ * The matcher shared by preview and apply — the previewed set equals the applied
+ * set for the same input. Read-only. Returns the matching message ids, bounded.
+ *
+ * - Semantic anchor: the anchor vector is pooled transiently from the anchor
+ *   message's existing chunk vectors (never a FilterAnchor row), then a k-NN
+ *   query fans out to candidate messages gated on the cosine threshold.
+ * - Literal clauses (RFC 031) refine the candidate set; a purely-literal
+ *   back-apply scans a bounded slice of the corpus instead.
+ * - A predicate with neither an anchor nor a clause matches nothing, mirroring
+ *   the index-time filter matcher.
+ */
+export const matchOrganize = async (
+	deps: OrganizeMatchDeps,
+	accountConfigId: string,
+	predicate: OrganizePredicate,
+	limit: number = ORGANIZE_MATCH_LIMIT,
+): Promise<string[]> => {
+	const anchored = hasAnchor(predicate);
+	const clauses = predicate.literalClauses;
+	if (!anchored && clauses.length === 0) return [];
+
+	let base: string[];
+	if (anchored) {
+		const anchor = await deps.buildAnchor(
+			accountConfigId,
+			predicate.anchorMessageId,
+		);
+		if (!anchor) return [];
+		const threshold =
+			predicate.similarityThreshold ?? DEFAULT_SEMANTIC_MATCH_THRESHOLD;
+		const matches = await deps.vectorStore.query({
+			vector: anchor.anchorEmbedding,
+			topK: limit * VECTOR_CHUNK_FACTOR,
+			filter: { accountConfigId },
+		});
+		const bestScore = new Map<string, number>();
+		for (const match of matches) {
+			const messageId = match.metadata.messageId;
+			const prev = bestScore.get(messageId);
+			if (prev === undefined || match.score > prev) {
+				bestScore.set(messageId, match.score);
+			}
+		}
+		base = [...bestScore.entries()]
+			.filter(([, score]) => score >= threshold)
+			.map(([messageId]) => messageId);
+	} else {
+		base = await deps.listAccountMessageIds(accountConfigId, limit);
+	}
+
+	if (clauses.length === 0) return base.slice(0, limit);
+
+	const matched: string[] = [];
+	for (const messageId of base) {
+		if (matched.length >= limit) break;
+		const records = await deps.vectorStore.getByMessage(messageId);
+		const message = filterMessageFromChunks(records);
+		if (!message) continue;
+		if (literalClausesMatch(clauses, predicate.matchOperator, message)) {
+			matched.push(messageId);
+		}
+	}
+	return matched;
+};
+
+let cachedVectorStore: Pick<
+	VectorStoreService,
+	"query" | "getByMessage"
+> | null = null;
+
+const getVectorStore = (): Pick<
+	VectorStoreService,
+	"query" | "getByMessage"
+> => {
+	if (!cachedVectorStore) {
+		const embedder = buildEmbeddingServiceFromEnv();
+		cachedVectorStore = buildVectorStoreFromEnv(embedder.dimensions);
+	}
+	return cachedVectorStore;
+};
+
+const buildAnchorFromEnv = (): OrganizeMatchDeps["buildAnchor"] => {
+	const embedder = buildEmbeddingServiceFromEnv();
+	const store = buildVectorStoreFromEnv(embedder.dimensions);
+	return (accountConfigId, anchorMessageId) =>
+		buildMessageAnchor(
+			{ store, embedder },
+			{ accountConfigId, anchorMessageId },
+		);
+};
+
+/**
+ * A bounded corpus slice for a purely-literal back-apply: the account's message
+ * ids, gathered mailbox by mailbox and capped. Paginated per mailbox so a large
+ * corpus never loads at once.
+ */
+const listAccountMessageIdsFromClient =
+	(client: RemitClient): OrganizeMatchDeps["listAccountMessageIds"] =>
+	async (accountConfigId, limit) => {
+		const accounts =
+			await client.account.listAllByAccountConfig(accountConfigId);
+		const ids: string[] = [];
+		for (const account of accounts) {
+			const mailboxes = await client.mailbox.listAllByAccount(
+				account.accountId,
+			);
+			for (const mailbox of mailboxes) {
+				let continuationToken: string | undefined;
+				do {
+					const page = await client.message.listByMailbox(mailbox.mailboxId, {
+						limit,
+						continuationToken,
+					});
+					for (const message of page.items) {
+						ids.push(message.messageId);
+						if (ids.length >= limit) return ids;
+					}
+					continuationToken = page.continuationToken;
+				} while (continuationToken);
+			}
+		}
+		return ids;
+	};
+
+/**
+ * The env-wired matcher deps for the running backend/worker. The vector store
+ * and embedder are selected by env, independent of `DATA_BACKEND`.
+ */
+export const buildOrganizeMatchDeps = (
+	client: RemitClient,
+): OrganizeMatchDeps => ({
+	buildAnchor: buildAnchorFromEnv(),
+	vectorStore: getVectorStore(),
+	listAccountMessageIds: listAccountMessageIdsFromClient(client),
+});
+
+/**
+ * The exclusive-move arm of a back-apply, wired exactly like the body-sync
+ * placement mover (`sync-message-body.ts`): the local-first
+ * {@link PlacementMoveService} over the shared message-management queue. A move
+ * commits locally (marker + ThreadMessage + Message row) and enqueues a
+ * `PLACEMENT_MOVE_PUSH` for the reconciler; its marker state engine makes a
+ * redelivered job idempotent (mirrors #1297). Returns `undefined` when no
+ * message-management queue is wired — the same gate body sync uses to keep the
+ * move path off — so a move requested in that environment is counted as failed
+ * rather than silently dropped (see {@link applyOrganize}).
+ */
+export const buildOrganizeMoveService = (
+	client: RemitClient,
+): PlacementMoveService | undefined => {
+	const queueUrl = process.env.SQS_QUEUE_URL_MESSAGE_MGMT;
+	if (!queueUrl) return undefined;
+	return new PlacementMoveService({
+		messageService: client.message,
+		threadMessageService: client.threadMessage,
+		markerService: client.placementMove,
+		sqsQueueUrl: queueUrl,
+	});
+};
+
+export interface ApplyOrganizeDeps {
+	client: RemitClient;
+	moveService?: PlacementMoveService;
+}
+
+export interface ApplyOrganizeResult {
+	applied: number;
+	failed: number;
+}
+
+/**
+ * Apply the back-apply action to every matched message, reusing the index-time
+ * apply plumbing: an idempotent MessageLabel upsert (additive) with
+ * `appliedByFilterId` deliberately ABSENT — this path attributes to no filter,
+ * exactly like a hand-applied label (RFC 034 Decision 3.3) — and an idempotent
+ * folder move (exclusive). One poisoned message never fails the batch; it is
+ * counted as failed and the pass continues.
+ */
+export const applyOrganize = async (
+	deps: ApplyOrganizeDeps,
+	accountConfigId: string,
+	messageIds: readonly string[],
+	predicate: OrganizePredicate,
+): Promise<ApplyOrganizeResult> => {
+	const { client, moveService } = deps;
+	const applyLabel =
+		predicate.actionLabelId !== NO_ACTION && predicate.actionLabelId !== "";
+	const applyMove =
+		predicate.actionMailboxId !== NO_ACTION && predicate.actionMailboxId !== "";
+
+	const applyToMessage = async (messageId: string): Promise<void> => {
+		if (applyLabel) {
+			await client.messageLabel.apply({
+				messageId,
+				labelId: predicate.actionLabelId,
+				accountConfigId,
+			});
+		}
+		if (applyMove) {
+			if (!moveService) {
+				// An exclusive move was requested but this caller wired no move
+				// service. Never silently pretend it applied — surface it as a
+				// failed message so the job's failedCount reflects reality.
+				throw new Error(
+					"Organize move action requested but no move service is wired",
+				);
+			}
+			const message = await client.message.get(messageId);
+			const accountId = await client.mailbox.resolveAccountId(
+				message.mailboxId,
+			);
+			if (!accountId) {
+				throw new Error(
+					`Cannot resolve owning account for mailbox ${message.mailboxId}`,
+				);
+			}
+			await moveService.moveMessage(
+				accountConfigId,
+				messageId,
+				predicate.actionMailboxId,
+				accountId,
+			);
+		}
+	};
+
+	let applied = 0;
+	let failed = 0;
+	for (const messageId of messageIds) {
+		// Per-message isolation: one poisoned message is counted and skipped, the
+		// pass continues. `.catch()` (not a block try/catch) keeps this inside the
+		// no-silent-catch ban.
+		const ok = await applyToMessage(messageId)
+			.then(() => true)
+			.catch(() => false);
+		if (ok) {
+			applied += 1;
+		} else {
+			failed += 1;
+		}
+	}
+	return { applied, failed };
+};

package/src/service/semantic-capability.test.ts

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import {
+	_resetSemanticCapabilityForTest,
+	isSemanticSearchUnavailable,
+	noteSemanticCapabilityAbsence,
+} from "./semantic-capability.js";
+
+const moduleNotFound = (): Error => {
+	const error = new Error(
+		"Cannot find package '@huggingface/transformers' imported from /app/server.mjs",
+	);
+	(error as Error & { code: string }).code = "ERR_MODULE_NOT_FOUND";
+	return error;
+};
+
+describe("noteSemanticCapabilityAbsence", () => {
+	const ORIGINAL = process.env.DATA_BACKEND;
+	beforeEach(() => {
+		_resetSemanticCapabilityForTest();
+	});
+	afterEach(() => {
+		if (ORIGINAL === undefined) delete process.env.DATA_BACKEND;
+		else process.env.DATA_BACKEND = ORIGINAL;
+		_resetSemanticCapabilityForTest();
+	});
+
+	it("absorbs a missing-module failure on the self-host SQL backends and remembers it", () => {
+		for (const backend of ["sqlite", "postgres"]) {
+			_resetSemanticCapabilityForTest();
+			process.env.DATA_BACKEND = backend;
+			assert.equal(isSemanticSearchUnavailable(), false);
+			assert.equal(noteSemanticCapabilityAbsence(moduleNotFound()), true);
+			assert.equal(isSemanticSearchUnavailable(), true);
+		}
+	});
+
+	it("absorbs a dlopen failure (musl loading a glibc extension)", () => {
+		process.env.DATA_BACKEND = "sqlite";
+		const error = new Error(
+			"Error loading shared library ld-linux-x86-64.so.2: No such file or directory",
+		);
+		(error as Error & { code: string }).code = "ERR_DLOPEN_FAILED";
+		assert.equal(noteSemanticCapabilityAbsence(error), true);
+	});
+
+	it("rethrows genuine query errors on the self-host SQL backends", () => {
+		process.env.DATA_BACKEND = "sqlite";
+		assert.equal(
+			noteSemanticCapabilityAbsence(new Error("SQLITE_BUSY")),
+			false,
+		);
+		assert.equal(isSemanticSearchUnavailable(), false);
+		assert.equal(noteSemanticCapabilityAbsence(undefined), false);
+	});
+
+	it("never engages on the AWS DynamoDB path — a missing module there is a broken deploy", () => {
+		delete process.env.DATA_BACKEND;
+		assert.equal(noteSemanticCapabilityAbsence(moduleNotFound()), false);
+		process.env.DATA_BACKEND = "dynamodb";
+		assert.equal(noteSemanticCapabilityAbsence(moduleNotFound()), false);
+		assert.equal(isSemanticSearchUnavailable(), false);
+	});
+});

package/src/service/semantic-capability.ts

@@ -0,0 +1,62 @@
+import { logger } from "@remit/logger-lambda";
+import { isSelfHostSqlBackend } from "../data-backend.js";
+
+/**
+ * Semantic-search capability gate for the self-host compose profiles.
+ *
+ * The backend container image ships neither `@huggingface/transformers` (query
+ * embedding) nor `sqlite-vec` (the vector store's loadable extension, glibc-only
+ * on top of that — see npm-scripts/docker-bundle.mjs and deploy/vps/README.md).
+ * Both are reached lazily through `runtimeImport`, so the first semantic query —
+ * not startup — hits ERR_MODULE_NOT_FOUND. Without this gate every search the
+ * web client issues fires a `/search/semantic` request that 500s (the client
+ * fetches semantic hits alongside every literal search), retried by the client
+ * on top.
+ *
+ * When the pipeline is genuinely absent, empty hits are the truthful answer:
+ * the FTS/literal engine is the primary search surface on these profiles and is
+ * unaffected. The absence is remembered so subsequent requests short-circuit.
+ *
+ * Scoped to the self-host SQL backends: on AWS the pipeline (Bedrock +
+ * S3 Vectors) is bundled, so a module-resolution failure there is a broken
+ * deploy and must keep failing loud. Falling back to the FTS engine here
+ * instead was considered and rejected — it would fabricate relevance scores and
+ * matched-chunk labels for the "Related" UI, and cannot serve the cross-account
+ * queries the daily brief issues.
+ */
+
+const CAPABILITY_ABSENCE_CODES = new Set([
+	"ERR_MODULE_NOT_FOUND",
+	"MODULE_NOT_FOUND",
+	"ERR_DLOPEN_FAILED",
+]);
+
+let semanticUnavailable = false;
+
+/** Test-only reset for the memoized absence. */
+export const _resetSemanticCapabilityForTest = (): void => {
+	semanticUnavailable = false;
+};
+
+export const isSemanticSearchUnavailable = (): boolean => semanticUnavailable;
+
+/**
+ * Classify a semantic-search failure. Returns true — and remembers the
+ * absence — when it is the missing-module/extension shape on a self-host SQL
+ * backend; any other error is the caller's to rethrow.
+ */
+export const noteSemanticCapabilityAbsence = (error: unknown): boolean => {
+	if (!isSelfHostSqlBackend()) return false;
+	const code = (error as { code?: unknown } | null)?.code;
+	if (typeof code !== "string" || !CAPABILITY_ABSENCE_CODES.has(code)) {
+		return false;
+	}
+	if (!semanticUnavailable) {
+		logger.warn(
+			{ error: error instanceof Error ? error.message : String(error) },
+			"Semantic search pipeline unavailable in this deployment — serving empty semantic results (see deploy/vps/README.md)",
+		);
+	}
+	semanticUnavailable = true;
+	return true;
+};

package/src/service/sqs.ts

@@ -0,0 +1,4 @@
+import { createQueueProducer } from "@remit/sqs-client/producer";
+import { env } from "expect-env";
+
+export const sqsClient = createQueueProducer({ queueUrl: env.SQS_QUEUE_URL });

package/src/service/trigger-sync.test.ts

@@ -0,0 +1,211 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { SendMessageCommand, type SQSClient } from "@aws-sdk/client-sqs";
+import {
+	buildManualSyncDedupId,
+	buildScheduledSyncDedupId,
+	buildSyncMailboxesCommand,
+	triggerAccountSync,
+} from "./trigger-sync.js";
+
+const FIFO_QUEUE_URL =
+	"https://sqs.eu-west-1.amazonaws.com/123456789012/remit-dev-mailboxes.fifo";
+const STANDARD_QUEUE_URL =
+	"http://localhost:9324/000000000000/remit-dev-mailboxes";
+
+const parseBody = (cmd: SendMessageCommand): Record<string, unknown> => {
+	const body = cmd.input.MessageBody ?? "{}";
+	return JSON.parse(body) as Record<string, unknown>;
+};
+
+describe("buildSyncMailboxesCommand", () => {
+	it("sets MessageGroupId to accountId for FIFO queues", () => {
+		const cmd = buildSyncMailboxesCommand({
+			sqsClient: {} as SQSClient,
+			queueUrl: FIFO_QUEUE_URL,
+			accountId: "account-abc",
+		});
+
+		assert.equal(cmd.input.MessageGroupId, "account-abc");
+	});
+
+	it("defaults MessageDeduplicationId to the time-bucketed manual dedup id for FIFO queues", () => {
+		const cmd = buildSyncMailboxesCommand({
+			sqsClient: {} as SQSClient,
+			queueUrl: FIFO_QUEUE_URL,
+			accountId: "account-abc",
+		});
+
+		assert.ok(
+			cmd.input.MessageDeduplicationId?.startsWith(
+				"SYNC_MAILBOXES:manual:account-abc:",
+			),
+		);
+	});
+
+	it("does not set FIFO params for standard queues", () => {
+		const cmd = buildSyncMailboxesCommand({
+			sqsClient: {} as SQSClient,
+			queueUrl: STANDARD_QUEUE_URL,
+			accountId: "account-abc",
+		});
+
+		assert.equal(cmd.input.MessageGroupId, undefined);
+		assert.equal(cmd.input.MessageDeduplicationId, undefined);
+	});
+
+	it("builds a SYNC_MAILBOXES event body with accountId and eventId", () => {
+		const cmd = buildSyncMailboxesCommand({
+			sqsClient: {} as SQSClient,
+			queueUrl: FIFO_QUEUE_URL,
+			accountId: "account-abc",
+		});
+
+		const event = parseBody(cmd);
+		assert.equal(event.type, "SYNC_MAILBOXES");
+		assert.equal(event.accountId, "account-abc");
+		assert.equal(typeof event.eventId, "string");
+		assert.equal(typeof event.timestamp, "number");
+	});
+
+	it("targets the configured queue url", () => {
+		const cmd = buildSyncMailboxesCommand({
+			sqsClient: {} as SQSClient,
+			queueUrl: FIFO_QUEUE_URL,
+			accountId: "account-abc",
+		});
+
+		assert.equal(cmd.input.QueueUrl, FIFO_QUEUE_URL);
+	});
+
+	it("uses the caller-supplied dedupId instead of the manual default", () => {
+		const cmd = buildSyncMailboxesCommand({
+			sqsClient: {} as SQSClient,
+			queueUrl: FIFO_QUEUE_URL,
+			accountId: "account-abc",
+			dedupId: "SYNC_MAILBOXES:scheduled:account-abc:12345",
+		});
+
+		assert.equal(
+			cmd.input.MessageDeduplicationId,
+			"SYNC_MAILBOXES:scheduled:account-abc:12345",
+		);
+	});
+});
+
+describe("buildManualSyncDedupId", () => {
+	const SIXTY_SECONDS_MS = 60 * 1000;
+
+	it("is stable within the same time bucket (dedupes a rapid double-tap)", () => {
+		const bucketStart = 10 * SIXTY_SECONDS_MS;
+
+		const first = buildManualSyncDedupId("account-abc", bucketStart);
+		const second = buildManualSyncDedupId("account-abc", bucketStart + 1_000);
+
+		assert.equal(first, second);
+	});
+
+	it("changes across a bucket boundary (never dedupes two polls a minute apart)", () => {
+		const bucketStart = 10 * SIXTY_SECONDS_MS;
+
+		const thisTrigger = buildManualSyncDedupId("account-abc", bucketStart);
+		const nextTrigger = buildManualSyncDedupId(
+			"account-abc",
+			bucketStart + SIXTY_SECONDS_MS,
+		);
+
+		assert.notEqual(thisTrigger, nextTrigger);
+	});
+
+	it("never collides with the scheduler's dedup namespace", () => {
+		const now = 10 * SIXTY_SECONDS_MS;
+		const manual = buildManualSyncDedupId("account-abc", now);
+		const scheduled = buildScheduledSyncDedupId(
+			"account-abc",
+			now,
+			SIXTY_SECONDS_MS,
+		);
+
+		assert.notEqual(manual, scheduled);
+	});
+});
+
+describe("buildScheduledSyncDedupId", () => {
+	const FIVE_MINUTES_MS = 5 * 60 * 1000;
+
+	it("is stable within the same time bucket (dedupes a retried tick)", () => {
+		const bucketStart = 10 * FIVE_MINUTES_MS;
+
+		const first = buildScheduledSyncDedupId(
+			"account-abc",
+			bucketStart,
+			FIVE_MINUTES_MS,
+		);
+		const second = buildScheduledSyncDedupId(
+			"account-abc",
+			bucketStart + 1_000,
+			FIVE_MINUTES_MS,
+		);
+
+		assert.equal(first, second);
+	});
+
+	it("changes across a bucket boundary (never dedupes two ticks apart)", () => {
+		const bucketStart = 10 * FIVE_MINUTES_MS;
+
+		const thisTick = buildScheduledSyncDedupId(
+			"account-abc",
+			bucketStart,
+			FIVE_MINUTES_MS,
+		);
+		const nextTick = buildScheduledSyncDedupId(
+			"account-abc",
+			bucketStart + FIVE_MINUTES_MS,
+			FIVE_MINUTES_MS,
+		);
+
+		assert.notEqual(thisTick, nextTick);
+	});
+});
+
+describe("triggerAccountSync", () => {
+	it("sends a SendMessageCommand to the client", async () => {
+		const sent: SendMessageCommand[] = [];
+		const sqsClient = {
+			send: async (cmd: SendMessageCommand) => {
+				sent.push(cmd);
+				return {};
+			},
+		} as unknown as SQSClient;
+
+		const result = await triggerAccountSync({
+			sqsClient,
+			queueUrl: FIFO_QUEUE_URL,
+			accountId: "account-xyz",
+		});
+
+		assert.equal(sent.length, 1);
+		const cmd = sent[0];
+		if (!cmd) throw new Error("expected command");
+		assert.ok(cmd instanceof SendMessageCommand);
+		assert.equal(cmd.input.MessageGroupId, "account-xyz");
+		assert.equal(typeof result.eventId, "string");
+	});
+
+	it("propagates SQS send errors to the caller", async () => {
+		const sqsClient = {
+			send: async () => {
+				throw new Error("MissingRequiredParameterException");
+			},
+		} as unknown as SQSClient;
+
+		await assert.rejects(
+			triggerAccountSync({
+				sqsClient,
+				queueUrl: FIFO_QUEUE_URL,
+				accountId: "account-xyz",
+			}),
+			/MissingRequiredParameterException/,
+		);
+	});
+});