@remit/backend 0.0.91 → 0.0.92

package/package.json

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

package/src/handlers/calendar-suggestion.test.ts

@@ -0,0 +1,279 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import type {
+	CalendarSuggestionItem,
+	CreateFilterInput,
+	FilterItem,
+	ICalendarSuggestionRepository,
+	MessageData,
+	ResultList,
+	SettleCalendarSuggestionInput,
+} from "@remit/data-ports";
+import {
+	CalendarInviteMethod,
+	CalendarSuggestionSource,
+	CalendarSuggestionState,
+} from "@remit/domain-enums";
+import {
+	assertSettleable,
+	type MuteSenderDeps,
+	muteSender,
+	settleSuggestion,
+	toCalendarSuggestionResponse,
+} from "./calendar-suggestion.js";
+
+const ACCOUNT_CONFIG_ID = "cfg-1";
+
+const suggestion = (
+	overrides: Partial<CalendarSuggestionItem> = {},
+): CalendarSuggestionItem => ({
+	suggestionId: "sug-1",
+	accountConfigId: ACCOUNT_CONFIG_ID,
+	messageId: "msg-1",
+	bodyPartId: "part-1",
+	icalUid: "invite@example.test",
+	sequence: 0,
+	method: CalendarInviteMethod.Request,
+	source: CalendarSuggestionSource.IcalendarPart,
+	state: CalendarSuggestionState.Pending,
+	summary: "Quarterly review",
+	dtStart: "2026-09-01T10:00:00+02:00",
+	dtEnd: "2026-09-01T11:00:00+02:00",
+	allDay: false,
+	location: "Room 4",
+	organizer: "organizer@example.test",
+	zoneCertainty: "Explicit",
+	icalData: "BEGIN:VCALENDAR\r\nEND:VCALENDAR\r\n",
+	acceptedCalendarObjectId: "",
+	createdAt: 1,
+	updatedAt: 1,
+	...overrides,
+});
+
+const repoOf = (
+	initial: CalendarSuggestionItem,
+): {
+	repo: ICalendarSuggestionRepository;
+	settles: SettleCalendarSuggestionInput[];
+} => {
+	let row = initial;
+	const settles: SettleCalendarSuggestionInput[] = [];
+	const repo = {
+		get: async () => row,
+		settle: async (
+			_accountConfigId: string,
+			_suggestionId: string,
+			input: SettleCalendarSuggestionInput,
+		) => {
+			settles.push(input);
+			row = { ...row, ...input };
+			return row;
+		},
+	} as unknown as ICalendarSuggestionRepository;
+	return { repo, settles };
+};
+
+const muteDepsOf = (
+	from: string | null,
+	existing: FilterItem[] = [],
+): { deps: MuteSenderDeps; created: CreateFilterInput[] } => {
+	const created: CreateFilterInput[] = [];
+	const rules = [...existing];
+	const deps: MuteSenderDeps = {
+		envelope: {
+			getMessageData: async () =>
+				({
+					envelopeAddress: from
+						? [{ addressRole: "from", normalizedEmail: from }]
+						: [{ addressRole: "to", normalizedEmail: "user@example.test" }],
+				}) as unknown as MessageData,
+		},
+		filter: {
+			listByAccountAndState: async () => rules,
+			create: async (input: CreateFilterInput) => {
+				created.push(input);
+				const row = {
+					...input,
+					actionLabelId: input.actionLabelId ?? "None",
+					actionMailboxId: input.actionMailboxId ?? "None",
+				} as unknown as FilterItem;
+				rules.push(row);
+				return row;
+			},
+		},
+	};
+	return { deps, created };
+};
+
+const muteRule = (sender: string): FilterItem =>
+	({
+		filterId: `mute-${sender}`,
+		accountConfigId: ACCOUNT_CONFIG_ID,
+		name: `Muted invitations from ${sender}`,
+		scope: "Standing",
+		state: "Active",
+		matchOperator: "And",
+		literalClauses: [{ field: "From", value: sender }],
+		actionLabelId: "None",
+		actionMailboxId: "None",
+	}) as unknown as FilterItem;
+
+describe("toCalendarSuggestionResponse", () => {
+	test("keeps the raw invitation bytes on the server", async () => {
+		const response = toCalendarSuggestionResponse(suggestion());
+
+		assert.equal("icalData" in response, false);
+		assert.equal(response.summary, "Quarterly review");
+		assert.equal(response.organizer, "organizer@example.test");
+	});
+});
+
+describe("assertSettleable", () => {
+	test("lets a pending card be answered", () => {
+		assertSettleable(suggestion(), CalendarSuggestionState.Accepted);
+	});
+
+	test("refuses to accept an event a revision already retired", () => {
+		assert.throws(
+			() =>
+				assertSettleable(
+					suggestion({ state: CalendarSuggestionState.Superseded }),
+					CalendarSuggestionState.Accepted,
+				),
+			/already superseded/,
+		);
+	});
+
+	test("refuses to decline an event that is already in the calendar", () => {
+		// A resource exists. Declining would say no to a meeting the user's
+		// calendar still shows, which is a lie the API must not tell.
+		assert.throws(
+			() =>
+				assertSettleable(
+					suggestion({ state: CalendarSuggestionState.Accepted }),
+					CalendarSuggestionState.Declined,
+				),
+			/already accepted/,
+		);
+	});
+
+	test("lets a repeat of the same answer through", () => {
+		assertSettleable(
+			suggestion({ state: CalendarSuggestionState.Declined }),
+			CalendarSuggestionState.Declined,
+		);
+	});
+});
+
+describe("settleSuggestion", () => {
+	test("records a decline", async () => {
+		const { repo, settles } = repoOf(suggestion());
+
+		const settled = await settleSuggestion(
+			repo,
+			ACCOUNT_CONFIG_ID,
+			"sug-1",
+			CalendarSuggestionState.Declined,
+		);
+
+		assert.equal(settled.state, CalendarSuggestionState.Declined);
+		assert.deepEqual(settles, [
+			{
+				state: CalendarSuggestionState.Declined,
+				acceptedCalendarObjectId: "",
+			},
+		]);
+	});
+
+	test("writes nothing on a repeated decline", async () => {
+		const { repo, settles } = repoOf(
+			suggestion({ state: CalendarSuggestionState.Declined }),
+		);
+
+		const settled = await settleSuggestion(
+			repo,
+			ACCOUNT_CONFIG_ID,
+			"sug-1",
+			CalendarSuggestionState.Declined,
+		);
+
+		assert.equal(settled.state, CalendarSuggestionState.Declined);
+		assert.deepEqual(settles, []);
+	});
+
+	test("never names a calendar object on a decision that wrote none", async () => {
+		// Dismiss and decline write no resource, so the field that points at one
+		// stays the empty sentinel rather than carrying a stale id.
+		const { repo, settles } = repoOf(suggestion());
+
+		await settleSuggestion(
+			repo,
+			ACCOUNT_CONFIG_ID,
+			"sug-1",
+			CalendarSuggestionState.Dismissed,
+		);
+
+		assert.deepEqual(
+			settles.map((settle) => settle.acceptedCalendarObjectId),
+			[""],
+		);
+	});
+});
+
+describe("muteSender", () => {
+	test("writes a standing rule on the message's sender", async () => {
+		const { deps, created } = muteDepsOf("organizer@example.test");
+
+		await muteSender(deps, ACCOUNT_CONFIG_ID, "msg-1");
+
+		assert.equal(created.length, 1);
+		assert.equal(created[0]?.accountConfigId, ACCOUNT_CONFIG_ID);
+		assert.equal(created[0]?.scope, "Standing");
+		assert.deepEqual(created[0]?.literalClauses, [
+			{ field: "From", value: "organizer@example.test" },
+		]);
+		assert.match(created[0]?.name ?? "", /organizer@example\.test/);
+	});
+
+	test("writes one rule however often the dismiss is retried", async () => {
+		// A retried dismiss is the same instruction repeated. A second identical
+		// rule would only be a second row for the user to find and delete twice.
+		const { deps, created } = muteDepsOf("organizer@example.test");
+
+		await muteSender(deps, ACCOUNT_CONFIG_ID, "msg-1");
+		await muteSender(deps, ACCOUNT_CONFIG_ID, "msg-1");
+		await muteSender(deps, ACCOUNT_CONFIG_ID, "msg-2");
+
+		assert.equal(created.length, 1);
+	});
+
+	test("adds nothing when the sender is already muted from another card", async () => {
+		const { deps, created } = muteDepsOf("organizer@example.test", [
+			muteRule("Organizer@Example.test"),
+		]);
+
+		await muteSender(deps, ACCOUNT_CONFIG_ID, "msg-1");
+
+		assert.deepEqual(created, []);
+	});
+
+	test("still writes a rule when the existing one names a different sender", async () => {
+		const { deps, created } = muteDepsOf("organizer@example.test", [
+			muteRule("someone-else@example.test"),
+		]);
+
+		await muteSender(deps, ACCOUNT_CONFIG_ID, "msg-1");
+
+		assert.equal(created.length, 1);
+	});
+
+	test("refuses to mute a message that names no sender", async () => {
+		const { deps, created } = muteDepsOf(null);
+
+		await assert.rejects(
+			() => muteSender(deps, ACCOUNT_CONFIG_ID, "msg-1"),
+			/nobody to mute/,
+		);
+		assert.deepEqual(created, []);
+	});
+});

package/src/handlers/calendar-suggestion.ts

@@ -0,0 +1,289 @@
+import type { CalendarSuggestionResponse } from "@remit/api-openapi-types";
+import { acceptCalendarSuggestion } from "@remit/calendar-service";
+import {
+	type CalendarSuggestionItem,
+	type ICalendarSuggestionRepository,
+	type IEnvelopeRepository,
+	type IFilterRepository,
+	isSenderMuted,
+} from "@remit/data-ports";
+import { BadRequestError } from "@remit/data-ports/errors";
+import {
+	CalendarSuggestionState,
+	FilterClauseField,
+	FilterMatchOperator,
+	FilterScope,
+	FilterState,
+} from "@remit/domain-enums";
+import type { APIGatewayProxyEvent } from "aws-lambda";
+import { getAccountConfigIdFromEvent } from "../auth.js";
+import { getClient, type RemitClient } from "../service/data-client.js";
+import type {
+	CalendarSuggestionActionOperationIds,
+	CalendarSuggestionOperationIds,
+	MessageCalendarSuggestionOperationIds,
+	OperationHandler,
+} from "../types.js";
+
+/**
+ * The raw invitation bytes stay on the server. A client renders the projected
+ * fields; the bytes exist so accepting can write them into a calendar
+ * unchanged, and shipping them would invite a second, divergent renderer.
+ */
+export const toCalendarSuggestionResponse = (
+	item: CalendarSuggestionItem,
+): CalendarSuggestionResponse => {
+	const { icalData: _icalData, ...response } = item;
+	return response;
+};
+
+/**
+ * The states a person can move a pending card into. `Superseded` is the
+ * producer's alone — a revision retires a card, a person never does — and the
+ * rest are terminal.
+ */
+export const assertSettleable = (
+	suggestion: CalendarSuggestionItem,
+	target: CalendarSuggestionItem["state"],
+): void => {
+	if (suggestion.state === CalendarSuggestionState.Pending) return;
+	if (suggestion.state === target) return;
+	throw new BadRequestError(
+		`This suggestion was already ${suggestion.state.toLowerCase()}, so it can't be ${target.toLowerCase()}.`,
+	);
+};
+
+/**
+ * The mail address the card's event should name as the accepting attendee: the
+ * account the invitation arrived on. Resolved from the message rather than
+ * asked of the client, so an ATTENDEE line can never name an address the user
+ * does not own.
+ */
+const accountEmailForMessage = async (
+	client: RemitClient,
+	messageId: string,
+): Promise<string> => {
+	const message = await client.message.get(messageId);
+	const accountId = await client.mailbox.resolveAccountId(message.mailboxId);
+	if (!accountId) {
+		throw new BadRequestError(
+			"The folder this invitation arrived in is gone, so there is no address to accept as.",
+		);
+	}
+	const account = await client.account.get(accountId);
+	return account.email;
+};
+
+/** What muting a sender needs, so it can be driven without a live table. */
+export interface MuteSenderDeps {
+	envelope: Pick<IEnvelopeRepository, "getMessageData">;
+	filter: Pick<IFilterRepository, "create" | "listByAccountAndState">;
+}
+
+/**
+ * The standing rule `dismiss{muteSender:true}` writes: the user saying they do
+ * not want this sender's invitations offered. It goes through the existing
+ * `Filter` entity rather than a second rules table, so it is visible and
+ * editable beside every other rule the user has, and matches on the message's
+ * From address rather than on the invitation's ORGANIZER — a `PUBLISH` names
+ * no organizer at all, and the sender is who the user is refusing.
+ *
+ * At most one rule per sender. Dismissing the same card twice, or muting a
+ * sender already muted from another card, is the same instruction repeated —
+ * a second identical rule would only be a second row for the settings page to
+ * show and the user to delete twice.
+ */
+export const muteSender = async (
+	deps: MuteSenderDeps,
+	accountConfigId: string,
+	messageId: string,
+): Promise<void> => {
+	const data = await deps.envelope.getMessageData(messageId);
+	const from = data.envelopeAddress.find(
+		(address) => address.addressRole === "from",
+	);
+	if (!from) {
+		throw new BadRequestError(
+			"This message names no sender, so there is nobody to mute.",
+		);
+	}
+	const active = await deps.filter.listByAccountAndState(
+		accountConfigId,
+		FilterState.Active,
+	);
+	if (isSenderMuted(active, from.normalizedEmail)) return;
+	await deps.filter.create({
+		accountConfigId,
+		name: `Muted invitations from ${from.normalizedEmail}`,
+		scope: FilterScope.Standing,
+		matchOperator: FilterMatchOperator.And,
+		literalClauses: [
+			{ field: FilterClauseField.From, value: from.normalizedEmail },
+		],
+	});
+};
+
+/**
+ * Moves a card to a decision. Idempotent by design: a client that retries a
+ * decline gets the same answer rather than a 400, and only a card in a
+ * different terminal state is refused.
+ */
+export const settleSuggestion = async (
+	repo: ICalendarSuggestionRepository,
+	accountConfigId: string,
+	suggestionId: string,
+	state: CalendarSuggestionItem["state"],
+): Promise<CalendarSuggestionItem> => {
+	const suggestion = await repo.get(accountConfigId, suggestionId);
+	assertSettleable(suggestion, state);
+	if (suggestion.state === state) return suggestion;
+	return repo.settle(accountConfigId, suggestionId, {
+		state,
+		acceptedCalendarObjectId: "",
+	});
+};
+
+export const CalendarSuggestionOperations: Record<
+	CalendarSuggestionOperationIds,
+	OperationHandler<CalendarSuggestionOperationIds>
+> = {
+	CalendarSuggestionOperations_listCalendarSuggestions: async (
+		context,
+		...args: unknown[]
+	) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { state, continuationToken } = context.request.query as {
+			state: CalendarSuggestionItem["state"];
+			continuationToken?: string;
+		};
+
+		const client = await getClient();
+		const page = await client.calendarSuggestion.listByState(
+			accountConfigId,
+			state,
+			{ continuationToken },
+		);
+
+		return {
+			items: page.items.map(toCalendarSuggestionResponse),
+			continuationToken: page.continuationToken,
+		};
+	},
+};
+
+export const MessageCalendarSuggestionOperations: Record<
+	MessageCalendarSuggestionOperationIds,
+	OperationHandler<MessageCalendarSuggestionOperationIds>
+> = {
+	MessageCalendarSuggestionOperations_listMessageCalendarSuggestions: async (
+		context,
+		...args: unknown[]
+	) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { messageId } = context.request.params as { messageId: string };
+
+		const client = await getClient();
+		const items = await client.calendarSuggestion.listByMessage(
+			accountConfigId,
+			messageId,
+		);
+
+		return {
+			items: items.map(toCalendarSuggestionResponse),
+			continuationToken: undefined,
+		};
+	},
+};
+
+export const CalendarSuggestionActionOperations: Record<
+	CalendarSuggestionActionOperationIds,
+	OperationHandler<CalendarSuggestionActionOperationIds>
+> = {
+	CalendarSuggestionActionOperations_acceptCalendarSuggestion: async (
+		context,
+		...args: unknown[]
+	) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { suggestionId } = context.request.params as {
+			suggestionId: string;
+		};
+		const { calendarId } = context.request.requestBody as {
+			calendarId: string;
+		};
+
+		const client = await getClient();
+		const suggestion = await client.calendarSuggestion.get(
+			accountConfigId,
+			suggestionId,
+		);
+		assertSettleable(suggestion, CalendarSuggestionState.Accepted);
+
+		// Reads the collection through the caller's own account config, so a
+		// calendarId naming somebody else's collection is a 404 before anything
+		// is written into it.
+		await client.calendarCollection.get(accountConfigId, calendarId);
+
+		const accepted = await acceptCalendarSuggestion(client.calendarUnitOfWork, {
+			accountConfigId,
+			calendarId,
+			suggestion,
+			attendee: await accountEmailForMessage(client, suggestion.messageId),
+		});
+		if (!accepted.ok) {
+			throw new BadRequestError(accepted.error.message);
+		}
+
+		return toCalendarSuggestionResponse(accepted.value.suggestion);
+	},
+
+	CalendarSuggestionActionOperations_declineCalendarSuggestion: async (
+		context,
+		...args: unknown[]
+	) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { suggestionId } = context.request.params as {
+			suggestionId: string;
+		};
+
+		const client = await getClient();
+		const declined = await settleSuggestion(
+			client.calendarSuggestion,
+			accountConfigId,
+			suggestionId,
+			CalendarSuggestionState.Declined,
+		);
+
+		return toCalendarSuggestionResponse(declined);
+	},
+
+	CalendarSuggestionActionOperations_dismissCalendarSuggestion: async (
+		context,
+		...args: unknown[]
+	) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { suggestionId } = context.request.params as {
+			suggestionId: string;
+		};
+		const body = (context.request.requestBody ?? {}) as {
+			muteSender?: boolean;
+		};
+
+		const client = await getClient();
+		const dismissed = await settleSuggestion(
+			client.calendarSuggestion,
+			accountConfigId,
+			suggestionId,
+			CalendarSuggestionState.Dismissed,
+		);
+		if (body.muteSender) {
+			await muteSender(client, accountConfigId, dismissed.messageId);
+		}
+
+		return toCalendarSuggestionResponse(dismissed);
+	},
+};

package/src/handlers/calendar.test.ts

@@ -5,24 +5,32 @@ import type {
 	CalendarEventIndexItem,
 	CalendarObjectItem,
 	CalendarOccurrenceInput,
+	CalendarSuggestionItem,
+	CalendarUnitOfWorkRepositories,
 	CreateCalendarCollectionInput,
 	ICalendarCollectionRepository,
 	ICalendarEventIndexRepository,
 	ICalendarObjectRepository,
+	ICalendarSuggestionRepository,
 	ICalendarUnitOfWork,
 	PutCalendarObjectInput,
+	PutCalendarSuggestionInput,
+	ResultList,
+	SettleCalendarSuggestionInput,
 	UpdateCalendarCollectionInput,
 } from "@remit/data-ports";
 import { NotFoundError } from "@remit/data-ports/errors";
 import {
 	deriveCalendarId,
 	deriveCalendarObjectId,
+	deriveCalendarSuggestionId,
 	normalizeCalendarUrlSegment,
 } from "@remit/data-ports/id";
 import {
 	CalendarColor,
 	CalendarComponentSet,
 	CalendarSource,
+	CalendarSuggestionState,
 	RecurrenceScope,
 } from "@remit/domain-enums";
 import {
@@ -58,6 +66,107 @@ class CalendarState {
 	readonly collections = new Map<string, CalendarCollectionItem>();
 	readonly objects = new Map<string, CalendarObjectItem>();
 	readonly occurrences = new Map<string, CalendarEventIndexItem[]>();
+	readonly suggestions = new Map<string, CalendarSuggestionItem>();
+}
+
+/**
+ * Suggestions are bound to the same unit of work so accepting a card and
+ * writing its resource commit together (issue #1033). Nothing in this file
+ * exercises them; they are here so the store answers the whole port.
+ */
+class MemorySuggestions implements ICalendarSuggestionRepository {
+	constructor(private state: CalendarState) {}
+
+	async put(
+		input: PutCalendarSuggestionInput,
+	): Promise<CalendarSuggestionItem> {
+		const suggestionId = deriveCalendarSuggestionId(
+			input.messageId,
+			input.bodyPartId,
+			input.icalUid,
+		);
+		const existing = this.state.suggestions.get(suggestionId);
+		const now = Date.now();
+		const suggestion: CalendarSuggestionItem = {
+			...input,
+			suggestionId,
+			state: existing?.state ?? CalendarSuggestionState.Pending,
+			acceptedCalendarObjectId: existing?.acceptedCalendarObjectId ?? "",
+			createdAt: existing?.createdAt ?? now,
+			updatedAt: now,
+		};
+		this.state.suggestions.set(suggestionId, suggestion);
+		return suggestion;
+	}
+
+	async get(
+		accountConfigId: string,
+		suggestionId: string,
+	): Promise<CalendarSuggestionItem> {
+		const suggestion = this.state.suggestions.get(suggestionId);
+		if (!suggestion || suggestion.accountConfigId !== accountConfigId) {
+			throw new NotFoundError(`Calendar suggestion not found: ${suggestionId}`);
+		}
+		return suggestion;
+	}
+
+	async listByMessage(
+		accountConfigId: string,
+		messageId: string,
+	): Promise<CalendarSuggestionItem[]> {
+		return [...this.state.suggestions.values()].filter(
+			(suggestion) =>
+				suggestion.accountConfigId === accountConfigId &&
+				suggestion.messageId === messageId,
+		);
+	}
+
+	async listByState(
+		accountConfigId: string,
+		state: CalendarSuggestionItem["state"],
+	): Promise<ResultList<CalendarSuggestionItem>> {
+		return {
+			items: [...this.state.suggestions.values()].filter(
+				(suggestion) =>
+					suggestion.accountConfigId === accountConfigId &&
+					suggestion.state === state,
+			),
+			continuationToken: undefined,
+		};
+	}
+
+	async settle(
+		accountConfigId: string,
+		suggestionId: string,
+		input: SettleCalendarSuggestionInput,
+	): Promise<CalendarSuggestionItem> {
+		const suggestion = await this.get(accountConfigId, suggestionId);
+		const settled = { ...suggestion, ...input, updatedAt: Date.now() };
+		this.state.suggestions.set(suggestionId, settled);
+		return settled;
+	}
+
+	async supersedeIfPending(
+		accountConfigId: string,
+		suggestionId: string,
+	): Promise<CalendarSuggestionItem | null> {
+		const suggestion = this.state.suggestions.get(suggestionId);
+		if (
+			!suggestion ||
+			suggestion.accountConfigId !== accountConfigId ||
+			suggestion.state !== CalendarSuggestionState.Pending
+		) {
+			return null;
+		}
+		const retired = {
+			...suggestion,
+			state: CalendarSuggestionState.Superseded,
+			acceptedCalendarObjectId: "",
+			updatedAt: Date.now(),
+		};
+		this.state.suggestions.set(suggestionId, retired);
+		return retired;
+	}
 }
 
 class MemoryCollections implements ICalendarCollectionRepository {
@@ -307,6 +416,7 @@ class InMemoryCalendarStore implements ICalendarUnitOfWork {
 	readonly calendarCollection = new MemoryCollections(this.state);
 	readonly calendarObject = new MemoryObjects(this.state);
 	readonly calendarEventIndex = new MemoryOccurrences(this.state);
+	readonly calendarSuggestion = new MemorySuggestions(this.state);
 
 	get collections(): Map<string, CalendarCollectionItem> {
 		return this.state.collections;
@@ -323,11 +433,7 @@ class InMemoryCalendarStore implements ICalendarUnitOfWork {
 	// No isolation to model: the tests that care about atomicity run against
 	// sqlite, where the transaction is real.
 	transaction<T>(
-		fn: (repos: {
-			calendarCollection: ICalendarCollectionRepository;
-			calendarObject: ICalendarObjectRepository;
-			calendarEventIndex: ICalendarEventIndexRepository;
-		}) => Promise<T>,
+		fn: (repos: CalendarUnitOfWorkRepositories) => Promise<T>,
 	): Promise<T> {
 		return fn(this);
 	}

package/src/handlers/index.ts

@@ -8,6 +8,11 @@ import {
 	CalendarEventOperations,
 	CalendarFreeBusyOperations,
 } from "./calendar-event.js";
+import {
+	CalendarSuggestionActionOperations,
+	CalendarSuggestionOperations,
+	MessageCalendarSuggestionOperations,
+} from "./calendar-suggestion.js";
 import { ConfigOperations } from "./config.js";
 import { FilterDetailOperations, FilterOperations } from "./filter.js";
 import { FolderRoleOperations } from "./folder-role.js";
@@ -66,4 +71,7 @@ export const handlers: Record<OperationIds, OperationHandler<any>> = {
 	...AddressOperations,
 	...AddressDetailOperations,
 	...SemanticSearchOperations,
+	...CalendarSuggestionOperations,
+	...MessageCalendarSuggestionOperations,
+	...CalendarSuggestionActionOperations,
 };

package/src/service/compose-sqlite.ts

@@ -7,6 +7,7 @@ import {
 	CalendarCollectionRepo,
 	CalendarEventIndexRepo,
 	CalendarObjectRepo,
+	CalendarSuggestionRepo,
 	ConfigImportRepo,
 	createSqliteDatabase,
 	DrizzleCalendarUnitOfWork,
@@ -85,6 +86,7 @@ export const buildSqliteClient = async (): Promise<RemitClient> => {
 		calendarCollection: new CalendarCollectionRepo(genericDb),
 		calendarObject: new CalendarObjectRepo(genericDb),
 		calendarEventIndex: new CalendarEventIndexRepo(genericDb),
+		calendarSuggestion: new CalendarSuggestionRepo(genericDb),
 		calendarUnitOfWork: new DrizzleCalendarUnitOfWork(genericDb),
 		unitOfWork: new DrizzleUnitOfWork(messageDataDb),
 		writeSet: (run) => runInTransaction(genericDb, () => run()),

package/src/service/create-remit-client.ts

@@ -7,6 +7,7 @@ import type {
 	ICalendarCollectionRepository,
 	ICalendarEventIndexRepository,
 	ICalendarObjectRepository,
+	ICalendarSuggestionRepository,
 	ICalendarUnitOfWork,
 	IConfigImportRepository,
 	IEnvelopeRepository,
@@ -119,15 +120,17 @@ export interface RemitClient {
 	// body-sync, which is its only writer.
 	senderSignerStanding: ISenderSignerStandingRepository;
 
-	// The calendar store (issue #15). Every write goes through
-	// `calendarUnitOfWork`: the object, its occurrence rows and the collection's
-	// sequence bump are one fact, and the three repositories beside it are the
-	// read side. A backend that cannot supply them cannot serve the calendar at
-	// all, so they are part of the client rather than something each handler
-	// checks for.
+	// The calendar store (issue #15) and the cards a message offers into it
+	// (issue #1033). Every write goes through `calendarUnitOfWork`: the object,
+	// its occurrence rows, the collection's sequence bump and — when the write
+	// came from accepting a suggestion — that suggestion's own state are one
+	// fact, and the repositories beside it are the read side. A backend that
+	// cannot supply them cannot serve the calendar at all, so they are part of
+	// the client rather than something each handler checks for.
 	calendarCollection: ICalendarCollectionRepository;
 	calendarObject: ICalendarObjectRepository;
 	calendarEventIndex: ICalendarEventIndexRepository;
+	calendarSuggestion: ICalendarSuggestionRepository;
 	calendarUnitOfWork: ICalendarUnitOfWork;
 
 	// Atomic write set for a message save. Present on the relational backend (real
@@ -222,6 +225,7 @@ export interface RemitClientRepositories {
 	calendarCollection: ICalendarCollectionRepository;
 	calendarObject: ICalendarObjectRepository;
 	calendarEventIndex: ICalendarEventIndexRepository;
+	calendarSuggestion: ICalendarSuggestionRepository;
 	calendarUnitOfWork: ICalendarUnitOfWork;
 	unitOfWork?: IUnitOfWork;
 	writeSet?: <T>(run: () => Promise<T>) => Promise<T>;
@@ -425,6 +429,15 @@ export const createRemitClient = (deps: RemitClientDeps): RemitClient => {
 		filterConfig,
 		undefined,
 		{ flagQueueService },
+		// The read-path backfill materializes a body the sync path never got to,
+		// so it is a message's first sight as much as the sync pass is — and an
+		// invitation the user opens before background sync must still get its
+		// card (issue #1033, the same argument as the filter wiring above).
+		{
+			calendarSuggestionService: repositories.calendarSuggestion,
+			calendarUnitOfWork: repositories.calendarUnitOfWork,
+			filterService: repositories.filter,
+		},
 	);
 
 	return {
@@ -453,6 +466,7 @@ export const createRemitClient = (deps: RemitClientDeps): RemitClient => {
 		calendarCollection: repositories.calendarCollection,
 		calendarObject: repositories.calendarObject,
 		calendarEventIndex: repositories.calendarEventIndex,
+		calendarSuggestion: repositories.calendarSuggestion,
 		calendarUnitOfWork: repositories.calendarUnitOfWork,
 		unitOfWork: repositories.unitOfWork,
 		writeSet: repositories.writeSet,

package/src/types.ts

@@ -79,7 +79,12 @@ export type OperationIds =
 	| "OutboxDetailOperations_mintOutboxAttachment"
 	| "OutboxAttachmentOperations_completeOutboxAttachment"
 	| "AddressOperations_searchAddresses"
-	| "AddressDetailOperations_updateAddress";
+	| "AddressDetailOperations_updateAddress"
+	| "CalendarSuggestionOperations_listCalendarSuggestions"
+	| "MessageCalendarSuggestionOperations_listMessageCalendarSuggestions"
+	| "CalendarSuggestionActionOperations_acceptCalendarSuggestion"
+	| "CalendarSuggestionActionOperations_declineCalendarSuggestion"
+	| "CalendarSuggestionActionOperations_dismissCalendarSuggestion";
 
 export type MeOperationIds = MatchPrefix<"MeOperations_", OperationIds>;
 
@@ -219,6 +224,21 @@ export type MicrosoftOAuthOperationIds = MatchPrefix<
 	OperationIds
 >;
 
+export type CalendarSuggestionOperationIds = MatchPrefix<
+	"CalendarSuggestionOperations_",
+	OperationIds
+>;
+
+export type MessageCalendarSuggestionOperationIds = MatchPrefix<
+	"MessageCalendarSuggestionOperations_",
+	OperationIds
+>;
+
+export type CalendarSuggestionActionOperationIds = MatchPrefix<
+	"CalendarSuggestionActionOperations_",
+	OperationIds
+>;
+
 // biome-ignore lint/suspicious/noExplicitAny: handler responses vary by operation
 type HandlerResponse = Record<string, any>;
 export type OperationHandler<_T extends OperationIds = OperationIds> = (