@remit/backend 0.0.36 → 0.0.38

package/package.json

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

package/src/derive/enrichThreadRows.test.ts

@@ -0,0 +1,163 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import type {
+	AddressItem,
+	LabelItem,
+	MessageItem,
+	MessageLabelItem,
+	ThreadMessageItem,
+} from "@remit/data-ports";
+import { type EnrichClient, enrichThreadRows } from "./enrichThreadRows.js";
+
+const threadRow = (
+	threadMessageId: string,
+	messageId: string,
+): ThreadMessageItem =>
+	({
+		threadMessageId,
+		threadId: "th-1",
+		messageId,
+		accountConfigId: "acc-1",
+		mailboxId: "mbx-1",
+		sentDate: 1,
+		isRead: true,
+		hasAttachment: false,
+		hasStars: false,
+		isDeleted: false,
+		createdAt: 1,
+		updatedAt: 1,
+	}) as unknown as ThreadMessageItem;
+
+const buildClient = (
+	messageLabels: MessageLabelItem[],
+	labels: LabelItem[],
+): EnrichClient => ({
+	message: { get: async () => [] as MessageItem[] },
+	address: { getAddress: async () => [] as AddressItem[] },
+	messageLabel: {
+		listByMessageIds: async (messageIds: string[]) =>
+			messageLabels.filter((row) => messageIds.includes(row.messageId)),
+	},
+	label: {
+		listByAccountConfig: async () => labels,
+	},
+});
+
+describe("enrichThreadRows — labels", () => {
+	test("attaches every label applied to a message", async () => {
+		const rows = [threadRow("tm-1", "msg-1")];
+		const messageLabels = [
+			{
+				messageLabelId: "ml-1",
+				messageId: "msg-1",
+				labelId: "lbl-1",
+				accountConfigId: "acc-1",
+				createdAt: 1,
+				updatedAt: 1,
+			},
+			{
+				messageLabelId: "ml-2",
+				messageId: "msg-1",
+				labelId: "lbl-2",
+				accountConfigId: "acc-1",
+				createdAt: 1,
+				updatedAt: 1,
+			},
+		] as unknown as MessageLabelItem[];
+		const labels = [
+			{
+				labelId: "lbl-1",
+				accountConfigId: "acc-1",
+				name: "Receipts",
+				normalizedName: "receipts",
+				color: "Blue",
+				createdAt: 1,
+				updatedAt: 1,
+			},
+			{
+				labelId: "lbl-2",
+				accountConfigId: "acc-1",
+				name: "Travel",
+				normalizedName: "travel",
+				color: "Green",
+				createdAt: 1,
+				updatedAt: 1,
+			},
+		] as unknown as LabelItem[];
+
+		const [result] = await enrichThreadRows(
+			rows,
+			buildClient(messageLabels, labels),
+			"acc-1",
+		);
+
+		assert.deepEqual(result?.labels?.map((l) => l.labelId).sort(), [
+			"lbl-1",
+			"lbl-2",
+		]);
+		assert.deepEqual(
+			result?.labels?.find((l) => l.labelId === "lbl-1"),
+			{ labelId: "lbl-1", name: "Receipts", color: "Blue" },
+		);
+	});
+
+	test("omits labels entirely when the message has none", async () => {
+		const rows = [threadRow("tm-1", "msg-1")];
+		const [result] = await enrichThreadRows(rows, buildClient([], []), "acc-1");
+		assert.equal(result?.labels, undefined);
+	});
+
+	test("skips a MessageLabel row whose Label was deleted out from under it", async () => {
+		const rows = [threadRow("tm-1", "msg-1")];
+		const messageLabels = [
+			{
+				messageLabelId: "ml-1",
+				messageId: "msg-1",
+				labelId: "gone",
+				accountConfigId: "acc-1",
+				createdAt: 1,
+				updatedAt: 1,
+			},
+		] as unknown as MessageLabelItem[];
+
+		const [result] = await enrichThreadRows(
+			rows,
+			buildClient(messageLabels, []),
+			"acc-1",
+		);
+		assert.equal(result?.labels, undefined);
+	});
+
+	test("never cross-wires labels between rows for different messages", async () => {
+		const rows = [threadRow("tm-1", "msg-1"), threadRow("tm-2", "msg-2")];
+		const messageLabels = [
+			{
+				messageLabelId: "ml-1",
+				messageId: "msg-1",
+				labelId: "lbl-1",
+				accountConfigId: "acc-1",
+				createdAt: 1,
+				updatedAt: 1,
+			},
+		] as unknown as MessageLabelItem[];
+		const labels = [
+			{
+				labelId: "lbl-1",
+				accountConfigId: "acc-1",
+				name: "Receipts",
+				normalizedName: "receipts",
+				color: "Blue",
+				createdAt: 1,
+				updatedAt: 1,
+			},
+		] as unknown as LabelItem[];
+
+		const [first, second] = await enrichThreadRows(
+			rows,
+			buildClient(messageLabels, labels),
+			"acc-1",
+		);
+		assert.equal(first?.labels?.length, 1);
+		assert.equal(second?.labels, undefined);
+	});
+});

package/src/derive/enrichThreadRows.ts

@@ -1,7 +1,9 @@
 import type { ThreadMessageResponse } from "@remit/api-openapi-types";
 import type {
 	AddressItem,
+	LabelItem,
 	MessageItem,
+	MessageLabelItem,
 	ThreadMessageItem,
 } from "@remit/data-ports";
 import { deriveAddressId } from "@remit/data-ports/id";
@@ -24,6 +26,12 @@ export interface EnrichClient {
 			addressIds: string[],
 		): Promise<AddressItem[]>;
 	};
+	messageLabel: {
+		listByMessageIds(messageIds: string[]): Promise<MessageLabelItem[]>;
+	};
+	label: {
+		listByAccountConfig(accountConfigId: string): Promise<LabelItem[]>;
+	};
 }
 
 const toResponse = (item: ThreadMessageItem): ThreadMessageResponse => ({
@@ -102,23 +110,54 @@ export const planBatchFetch = (rows: ThreadMessageItem[]): BatchPlan => {
  * Message with no stored category coalesces to `uncategorized` (RFC 032 Tier 2).
  * `senderTrust` defaults to `"unknown"`. `autoMoved` is omitted whenever the
  * move isn't a real, in-effect auto-move (or the Message row is absent).
+ *
+ * Not annotated `Promise<ThreadMessageResponse[]>`: `labels` is a new field on
+ * it in this same PR, and that package publishes separately from this repo —
+ * an explicit annotation here would contextually type the literal below
+ * against the currently-*published* shape (which lacks `labels`) and fail
+ * `check-consumer-typecheck`/`release:dry-run`. Callers assign the (wider,
+ * inferred) result into an already-typed `ThreadMessageResponse[]` property,
+ * which is a plain assignability check, not an excess-property one.
  */
 export const enrichThreadRows = async (
 	rows: ThreadMessageItem[],
 	client: EnrichClient,
 	accountConfigId: string,
-): Promise<ThreadMessageResponse[]> => {
+) => {
 	if (rows.length === 0) return [];
 
 	const plan = planBatchFetch(rows);
 
-	const [messages, addresses] = await Promise.all([
+	const [messages, addresses, messageLabels, labels] = await Promise.all([
 		plan.messageIds.length ? client.message.get(plan.messageIds) : [],
 		plan.addressIds.length
 			? client.address.getAddress(accountConfigId, plan.addressIds)
 			: [],
+		client.messageLabel.listByMessageIds(plan.messageIds),
+		client.label.listByAccountConfig(accountConfigId),
 	]);
 
+	const labelById = new Map(labels.map((label) => [label.labelId, label]));
+	const labelsByMessageId = new Map<
+		string,
+		{ labelId: string; name: string; color: LabelItem["color"] }[]
+	>();
+	for (const messageLabel of messageLabels) {
+		const label = labelById.get(messageLabel.labelId);
+		if (!label) continue;
+		const entry = {
+			labelId: label.labelId,
+			name: label.name,
+			color: label.color,
+		};
+		const existing = labelsByMessageId.get(messageLabel.messageId);
+		if (existing) {
+			existing.push(entry);
+		} else {
+			labelsByMessageId.set(messageLabel.messageId, [entry]);
+		}
+	}
+
 	const categoryByMessageId = new Map(
 		messages.map((m) => [
 			m.messageId,
@@ -144,11 +183,13 @@ export const enrichThreadRows = async (
 		const senderTrust = addressId
 			? (trustByAddressId.get(addressId) ?? SenderTrust.Unknown)
 			: SenderTrust.Unknown;
+		const labels = labelsByMessageId.get(row.messageId);
 		return {
 			...base,
 			...(category !== undefined ? { category } : {}),
 			...(authenticity !== undefined ? { authenticity } : {}),
 			...(autoMoved !== undefined ? { autoMoved } : {}),
+			...(labels !== undefined ? { labels } : {}),
 			senderTrust,
 		};
 	});

package/src/handlers/filter.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import type { UpdateFilterInput } from "@remit/data-ports";
+import type { UpdateFilterInput as UpdateFilterRequestBody } from "@remit/api-openapi-types";
 import { FilterScope, FilterState } from "@remit/domain-enums";
 import {
 	pickFilterUpdate,
@@ -35,7 +35,7 @@ describe("pickFilterUpdate", () => {
 			ruleChangedAt: 999,
 			filterId: "sneaky",
 		};
-		const patch = pickFilterUpdate(raw as Partial<UpdateFilterInput>);
+		const patch = pickFilterUpdate(raw as Partial<UpdateFilterRequestBody>);
 		assert.deepEqual(patch, { name: "Receipts" });
 	});
 });

package/src/handlers/filter.ts

@@ -1,6 +1,7 @@
 import type {
 	CreateFilterInput,
 	FilterResponse,
+	UpdateFilterInput as UpdateFilterRequestBody,
 } from "@remit/api-openapi-types";
 import type { FilterItem, UpdateFilterInput } from "@remit/data-ports";
 import { BadRequestError } from "@remit/data-ports/errors";
@@ -93,19 +94,9 @@ export const deriveFilterTtl = (
  * 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>,
+	body: Partial<UpdateFilterRequestBody>,
 ): Partial<UpdateFilterInput> => {
 	const patch: Partial<UpdateFilterInput> = {};
 	if (Object.hasOwn(body, "name")) patch.name = body.name;
@@ -368,7 +359,7 @@ export const FilterDetailOperations: Record<
 		assertAccountOwnership(account, accountConfigId, "act");
 
 		const { filter } = client;
-		const patch = pickFilterUpdate(body as Partial<UpdateFilterInput>);
+		const patch = pickFilterUpdate(body as Partial<UpdateFilterRequestBody>);
 		const touchesScopeOrExpiry =
 			Object.hasOwn(patch, "scope") || Object.hasOwn(patch, "expiresAt");
 		const resolvedPatch: Partial<UpdateFilterInput> = touchesScopeOrExpiry

package/src/handlers/index.ts

@@ -5,6 +5,7 @@ import { AddressDetailOperations, AddressOperations } from "./address.js";
 import { ConfigOperations } from "./config.js";
 import { FilterDetailOperations, FilterOperations } from "./filter.js";
 import { FolderRoleOperations } from "./folder-role.js";
+import { LabelDetailOperations, LabelOperations } from "./label.js";
 import {
 	MailboxDetailOperations,
 	MailboxOperations,
@@ -33,6 +34,8 @@ export const handlers: Record<OperationIds, OperationHandler<any>> = {
 	...FolderRoleOperations,
 	...FilterOperations,
 	...FilterDetailOperations,
+	...LabelOperations,
+	...LabelDetailOperations,
 	...OrganizeOperations,
 	...OrganizeJobDetailOperations,
 	...TrashOperations,

package/src/handlers/label.test.ts

@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import type { FilterItem, LabelItem } from "@remit/data-ports";
+import {
+	deleteLabelWithCascade,
+	findFiltersForLabel,
+	type LabelCrudDeps,
+} from "./label.js";
+
+const filter = (filterId: string, actionLabelId: string): FilterItem =>
+	({ filterId, actionLabelId }) as unknown as FilterItem;
+
+const label = (labelId: string): LabelItem =>
+	({
+		labelId,
+		accountConfigId: "acc-1",
+		name: "x",
+		color: "Default",
+	}) as LabelItem;
+
+const buildDeps = (filters: FilterItem[]) => {
+	const deletedFilterIds: string[] = [];
+	const removedLabelIds: string[] = [];
+	const deletedLabelIds: string[] = [];
+
+	const deps: LabelCrudDeps = {
+		label: {
+			create: async () => label("unused"),
+			get: async (_accountConfigId: string, labelId: string) => label(labelId),
+			update: async (_accountConfigId: string, labelId: string) =>
+				label(labelId),
+			delete: async (_accountConfigId: string, labelId: string) => {
+				deletedLabelIds.push(labelId);
+			},
+			listPageByAccountConfig: async () => ({
+				items: [],
+				continuationToken: undefined,
+			}),
+		},
+		filter: {
+			listByAccountConfig: async () => filters,
+			delete: async (_accountConfigId: string, filterId: string) => {
+				deletedFilterIds.push(filterId);
+			},
+		},
+		messageLabel: {
+			removeAllByLabelId: async (_accountConfigId: string, labelId: string) => {
+				removedLabelIds.push(labelId);
+			},
+		},
+	};
+
+	return { deps, deletedFilterIds, removedLabelIds, deletedLabelIds };
+};
+
+describe("findFiltersForLabel", () => {
+	test("returns only the filters whose actionLabelId matches", async () => {
+		const filters = [
+			filter("f1", "label-1"),
+			filter("f2", "label-2"),
+			filter("f3", "label-1"),
+		];
+		const { deps } = buildDeps(filters);
+
+		const found = await findFiltersForLabel(deps, "acc-1", "label-1");
+		assert.deepEqual(found.map((f) => f.filterId).sort(), ["f1", "f3"]);
+	});
+
+	test("returns an empty list when no filter uses the label", async () => {
+		const { deps } = buildDeps([filter("f1", "label-2")]);
+		const found = await findFiltersForLabel(deps, "acc-1", "label-1");
+		assert.deepEqual(found, []);
+	});
+});
+
+describe("deleteLabelWithCascade", () => {
+	test("deletes every filter referencing the label, clears applied messages, then deletes the label", async () => {
+		const filters = [
+			filter("f1", "label-1"),
+			filter("f2", "label-2"),
+			filter("f3", "label-1"),
+		];
+		const { deps, deletedFilterIds, removedLabelIds, deletedLabelIds } =
+			buildDeps(filters);
+
+		await deleteLabelWithCascade(deps, "acc-1", "label-1");
+
+		assert.deepEqual(deletedFilterIds.sort(), ["f1", "f3"]);
+		assert.deepEqual(removedLabelIds, ["label-1"]);
+		assert.deepEqual(deletedLabelIds, ["label-1"]);
+	});
+
+	test("never touches a filter that references a different label", async () => {
+		const filters = [filter("f1", "label-2")];
+		const { deps, deletedFilterIds } = buildDeps(filters);
+
+		await deleteLabelWithCascade(deps, "acc-1", "label-1");
+
+		assert.deepEqual(deletedFilterIds, []);
+	});
+
+	test("is a no-op on the filter/messageLabel side when nothing references the label", async () => {
+		const { deps, deletedFilterIds, removedLabelIds, deletedLabelIds } =
+			buildDeps([]);
+
+		await deleteLabelWithCascade(deps, "acc-1", "label-1");
+
+		assert.deepEqual(deletedFilterIds, []);
+		assert.deepEqual(removedLabelIds, ["label-1"]);
+		assert.deepEqual(deletedLabelIds, ["label-1"]);
+	});
+});

package/src/handlers/label.ts

@@ -0,0 +1,210 @@
+import type {
+	CreateLabelInput as CreateLabelRequestBody,
+	LabelResponse,
+	UpdateLabelInput as UpdateLabelRequestBody,
+} from "@remit/api-openapi-types";
+import type {
+	CreateLabelInput,
+	FilterItem,
+	LabelItem,
+	UpdateLabelInput,
+} from "@remit/data-ports";
+import type { APIGatewayProxyEvent } from "aws-lambda";
+import { getAccountConfigIdFromEvent } from "../auth.js";
+import { getClient } from "../service/dynamodb.js";
+import type {
+	LabelDetailOperationIds,
+	LabelOperationIds,
+	OperationHandler,
+} from "../types.js";
+import { assertAccountOwnership } from "./account-ownership.js";
+
+/**
+ * Minimal label-service surface the CRUD handlers need — declared as a `Pick`
+ * so tests can stub it without a live table.
+ */
+export interface LabelCrudDeps {
+	label: {
+		create(input: CreateLabelInput): Promise<LabelItem>;
+		get(accountConfigId: string, labelId: string): Promise<LabelItem>;
+		update(
+			accountConfigId: string,
+			labelId: string,
+			input: UpdateLabelInput,
+		): Promise<LabelItem>;
+		delete(accountConfigId: string, labelId: string): Promise<void>;
+		listPageByAccountConfig(
+			accountConfigId: string,
+			options?: { limit?: number; continuationToken?: string },
+		): Promise<{ items: LabelItem[]; continuationToken: string | undefined }>;
+	};
+	filter: {
+		listByAccountConfig(accountConfigId: string): Promise<FilterItem[]>;
+		delete(accountConfigId: string, filterId: string): Promise<void>;
+	};
+	messageLabel: {
+		removeAllByLabelId(accountConfigId: string, labelId: string): Promise<void>;
+	};
+}
+
+/**
+ * Every filter in the account whose action applies this label (issue #26). The
+ * count backs `LabelResponse.filterCount`; the list backs the cascade delete.
+ */
+export const findFiltersForLabel = async (
+	deps: Pick<LabelCrudDeps, "filter">,
+	accountConfigId: string,
+	labelId: string,
+): Promise<FilterItem[]> => {
+	const filters = await deps.filter.listByAccountConfig(accountConfigId);
+	return filters.filter((filter) => filter.actionLabelId === labelId);
+};
+
+/**
+ * `filterCount` is computed here, not stored (issue #26) — every other field
+ * comes straight off the `LabelItem` row.
+ */
+const toLabelResponse = (
+	item: LabelItem,
+	filterCount: number,
+): LabelResponse => ({
+	labelId: item.labelId,
+	accountConfigId: item.accountConfigId,
+	name: item.name,
+	color: item.color,
+	filterCount,
+	createdAt: item.createdAt,
+	updatedAt: item.updatedAt,
+});
+
+/**
+ * Delete a label and cascade in both directions (issue #26): every filter
+ * whose `actionLabelId` is this label is deleted outright — never left
+ * dangling, never blocking the delete — and every `MessageLabel` row for it is
+ * removed. The label row itself is deleted last so a failure mid-cascade never
+ * leaves the label gone while its filters or applied-to-messages still exist.
+ */
+export const deleteLabelWithCascade = async (
+	deps: LabelCrudDeps,
+	accountConfigId: string,
+	labelId: string,
+): Promise<void> => {
+	const filters = await findFiltersForLabel(deps, accountConfigId, labelId);
+	for (const filter of filters) {
+		await deps.filter.delete(accountConfigId, filter.filterId);
+	}
+	await deps.messageLabel.removeAllByLabelId(accountConfigId, labelId);
+	await deps.label.delete(accountConfigId, labelId);
+};
+
+export const LabelOperations: Record<
+	LabelOperationIds,
+	OperationHandler<LabelOperationIds>
+> = {
+	LabelOperations_listLabels: async (context, ...args: unknown[]) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { accountId } = context.request.params as { accountId: string };
+		const { continuationToken } = context.request.query as {
+			continuationToken?: string;
+		};
+
+		const client = await getClient();
+		const account = await client.account.get(accountId);
+		assertAccountOwnership(account, accountConfigId, "read");
+
+		const page = await client.label.listPageByAccountConfig(accountConfigId, {
+			continuationToken,
+		});
+		const filters = await client.filter.listByAccountConfig(accountConfigId);
+		const filterCountByLabelId = new Map<string, number>();
+		for (const filter of filters) {
+			const labelId = filter.actionLabelId;
+			filterCountByLabelId.set(
+				labelId,
+				(filterCountByLabelId.get(labelId) ?? 0) + 1,
+			);
+		}
+
+		return {
+			items: page.items.map((item) =>
+				toLabelResponse(item, filterCountByLabelId.get(item.labelId) ?? 0),
+			),
+			continuationToken: page.continuationToken,
+		};
+	},
+
+	LabelOperations_createLabel: async (context, ...args: unknown[]) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { accountId } = context.request.params as { accountId: string };
+		const input = context.request.requestBody as CreateLabelRequestBody;
+
+		const client = await getClient();
+		const account = await client.account.get(accountId);
+		assertAccountOwnership(account, accountConfigId, "act");
+
+		const label = await client.label.create({
+			accountConfigId,
+			name: input.name,
+			color: input.color,
+		});
+		return toLabelResponse(label, 0);
+	},
+};
+
+export const LabelDetailOperations: Record<
+	LabelDetailOperationIds,
+	OperationHandler<LabelDetailOperationIds>
+> = {
+	LabelDetailOperations_getLabel: async (context, ...args: unknown[]) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { accountId, labelId } = context.request.params as {
+			accountId: string;
+			labelId: string;
+		};
+
+		const client = await getClient();
+		const account = await client.account.get(accountId);
+		assertAccountOwnership(account, accountConfigId, "read");
+
+		const label = await client.label.get(accountConfigId, labelId);
+		const filters = await findFiltersForLabel(client, accountConfigId, labelId);
+		return toLabelResponse(label, filters.length);
+	},
+
+	LabelDetailOperations_updateLabel: async (context, ...args: unknown[]) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { accountId, labelId } = context.request.params as {
+			accountId: string;
+			labelId: string;
+		};
+		const body = context.request.requestBody as Partial<UpdateLabelRequestBody>;
+
+		const client = await getClient();
+		const account = await client.account.get(accountId);
+		assertAccountOwnership(account, accountConfigId, "act");
+
+		const updated = await client.label.update(accountConfigId, labelId, body);
+		const filters = await findFiltersForLabel(client, accountConfigId, labelId);
+		return toLabelResponse(updated, filters.length);
+	},
+
+	LabelDetailOperations_deleteLabel: async (context, ...args: unknown[]) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { accountId, labelId } = context.request.params as {
+			accountId: string;
+			labelId: string;
+		};
+
+		const client = await getClient();
+		const account = await client.account.get(accountId);
+		assertAccountOwnership(account, accountConfigId, "act");
+
+		await deleteLabelWithCascade(client, accountConfigId, labelId);
+		return { statusCode: 204 };
+	},
+};

package/src/handlers/message.ts

@@ -2,7 +2,6 @@ import type {
 	BodyPartResponse,
 	EnvelopeAddressResponse,
 	EnvelopeResponse,
-	MessageSummaryResponse,
 } from "@remit/api-openapi-types";
 import type { MailboxItem } from "@remit/data-ports";
 import {
@@ -351,7 +350,26 @@ export const MessageOperations: Record<
 		const envelope = description.envelope[0];
 
 		const autoMoved = deriveAutoMoved(message);
-		const messageSummary: MessageSummaryResponse = {
+
+		// Labels applied to this message (issue #26) — filter-, organize-, and
+		// manually-applied alike. A message rarely carries more than a handful, so
+		// a `get` per label id (not a batch fetch) is the whole cost.
+		const messageLabelRows = await client.messageLabel.listByMessageId(
+			message.messageId,
+		);
+		const labels = await Promise.all(
+			messageLabelRows.map(async (row) => {
+				const label = await client.label.get(accountConfigId, row.labelId);
+				return { labelId: label.labelId, name: label.name, color: label.color };
+			}),
+		);
+
+		// Not typed against the generated `MessageSummaryResponse`: `labels` is a
+		// new field on it in this same PR, and that package publishes separately
+		// from this repo — a local-codegen-only field would fail
+		// `check-consumer-typecheck`/`release:dry-run`, which resolve generated
+		// `@remit/*` packages off the registry, not the local `build/` output.
+		const messageSummary = {
 			messageId: message.messageId,
 			mailboxId: message.mailboxId,
 			uid: message.uid,
@@ -360,6 +378,7 @@ export const MessageOperations: Record<
 			messageIdHeader: message.messageIdHeader,
 			authenticity: message.authenticity,
 			...(autoMoved ? { autoMoved } : {}),
+			...(labels.length > 0 ? { labels } : {}),
 		};
 
 		// Batch-fetch the resolved Address rows so each EnvelopeAddressResponse can
@@ -883,4 +902,49 @@ export const MessageBulkOperations: Record<
 			failureCount: 0,
 		};
 	},
+
+	MessageBulkOperations_updateMessageLabels: async (
+		context,
+		...args: unknown[]
+	) => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const { messageIds, labelId, action } = context.request.requestBody as {
+			messageIds: string[];
+			labelId: string;
+			action: "Apply" | "Remove";
+		};
+
+		if (messageIds.length === 0) {
+			return { successCount: 0, failureCount: 0 };
+		}
+
+		const client = await getClient();
+		await assertMessagesOwned(client, messageIds, accountConfigId, "act");
+
+		// Scoped by accountConfigId (RFC 030) — a foreign labelId 404s here rather
+		// than silently applying to messages under someone else's label.
+		await client.label.get(accountConfigId, labelId);
+
+		// `appliedByFilterId` stays absent — this is the manual "just these" scope
+		// (RFC 034 Decision 3.3), never filter-attributed.
+		if (action === "Apply") {
+			for (const messageId of messageIds) {
+				await client.messageLabel.apply({
+					accountConfigId,
+					messageId,
+					labelId,
+				});
+			}
+		} else {
+			for (const messageId of messageIds) {
+				await client.messageLabel.remove(messageId, labelId);
+			}
+		}
+
+		return {
+			successCount: messageIds.length,
+			failureCount: 0,
+		};
+	},
 };

package/src/service/filter.ts

@@ -28,10 +28,7 @@ const build = (): BuildFilterAnchor => {
 	const embedder = buildEmbeddingServiceFromEnv();
 	const store = buildVectorStoreFromEnv(embedder.dimensions);
 	return (accountConfigId, anchorMessageId) =>
-		buildMessageAnchor(
-			{ store, embedder },
-			{ accountConfigId, anchorMessageId },
-		);
+		buildMessageAnchor({ store }, { accountConfigId, anchorMessageId });
 };
 
 export const buildFilterAnchor: BuildFilterAnchor = (

package/src/service/organize.ts

@@ -341,10 +341,7 @@ const buildSemanticFromEnv = (): OrganizeSemanticDeps => {
 	const store = buildVectorStoreFromEnv(embedder.dimensions);
 	cachedSemantic = {
 		buildAnchor: (accountConfigId, anchorMessageId) =>
-			buildMessageAnchor(
-				{ store, embedder },
-				{ accountConfigId, anchorMessageId },
-			),
+			buildMessageAnchor({ store }, { accountConfigId, anchorMessageId }),
 		vectorStore: store,
 	};
 	return cachedSemantic;

package/src/types.ts

@@ -31,6 +31,11 @@ export type OperationIds =
 	| "FilterDetailOperations_getFilter"
 	| "FilterDetailOperations_updateFilter"
 	| "FilterDetailOperations_deleteFilter"
+	| "LabelOperations_listLabels"
+	| "LabelOperations_createLabel"
+	| "LabelDetailOperations_getLabel"
+	| "LabelDetailOperations_updateLabel"
+	| "LabelDetailOperations_deleteLabel"
 	| "OrganizeOperations_createOrganizeJob"
 	| "OrganizeOperations_previewOrganize"
 	| "OrganizeJobDetailOperations_getOrganizeJob"
@@ -48,6 +53,7 @@ export type OperationIds =
 	| "MessageBulkOperations_moveMessages"
 	| "MessageBulkOperations_updateFlags"
 	| "MessageBulkOperations_copyMessages"
+	| "MessageBulkOperations_updateMessageLabels"
 	| "TrashOperations_emptyTrash"
 	| "OutboxOperations_createOutboxMessage"
 	| "OutboxOperations_listOutboxMessages"
@@ -96,6 +102,13 @@ export type FilterDetailOperationIds = MatchPrefix<
 	OperationIds
 >;
 
+export type LabelOperationIds = MatchPrefix<"LabelOperations_", OperationIds>;
+
+export type LabelDetailOperationIds = MatchPrefix<
+	"LabelDetailOperations_",
+	OperationIds
+>;
+
 export type OrganizeOperationIds = MatchPrefix<
 	"OrganizeOperations_",
 	OperationIds