@remit/backend 0.0.8 → 0.0.9

package/package.json

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

package/src/handlers/unified-threads.test.ts

@@ -0,0 +1,172 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import type {
+	AccountItem,
+	AccountSettingItem,
+	MailboxItem,
+} from "@remit/data-ports";
+import {
+	buildInboxMailboxMap,
+	buildListAllThreadsOptions,
+	buildListStarredThreadsOptions,
+	type InboxMapClient,
+} from "./unified-threads.js";
+
+// #44: Flagged filtered client-side over the newest 50 unified-inbox rows, so a
+// star outside that window — or in any folder that is not INBOX — never showed.
+// The starred scope is every non-muted mailbox, served by its own access
+// pattern.
+
+const CONFIG_ID = "cfg-1";
+
+const account = (accountId: string): AccountItem =>
+	({ accountId }) as unknown as AccountItem;
+
+const mailbox = (
+	mailboxId: string,
+	accountId: string,
+	fullPath: string,
+	specialUse?: string[],
+): MailboxItem =>
+	({ mailboxId, accountId, fullPath, specialUse }) as unknown as MailboxItem;
+
+const mutedSetting = (
+	name: "AccountMuted" | "MailboxMuted",
+	targetId: string,
+): AccountSettingItem =>
+	({
+		name: `${name}#${targetId}`,
+		value: { kind: "MutedFlag", value: { value: true, setAt: 0 } },
+	}) as unknown as AccountSettingItem;
+
+const buildClient = (
+	accounts: AccountItem[],
+	mailboxesByAccount: Record<string, MailboxItem[]>,
+	settings: AccountSettingItem[] = [],
+): InboxMapClient =>
+	({
+		account: { listAllByAccountConfig: async () => accounts },
+		mailbox: {
+			listAllByAccount: async (accountId: string) =>
+				mailboxesByAccount[accountId] ?? [],
+		},
+		accountSetting: { listByAccountConfig: async () => settings },
+	}) as unknown as InboxMapClient;
+
+describe("buildInboxMailboxMap", () => {
+	test("separates the INBOX scope from the wider starred scope", async () => {
+		const client = buildClient([account("a1")], {
+			a1: [
+				mailbox("m-inbox", "a1", "INBOX"),
+				mailbox("m-archive", "a1", "Archive", ["Archive"]),
+				mailbox("m-sub", "a1", "INBOX/Receipts"),
+			],
+		});
+
+		const { inboxMailboxIds, starredMailboxIds, mailboxIdToAccountId } =
+			await buildInboxMailboxMap(CONFIG_ID, client);
+
+		assert.deepEqual([...inboxMailboxIds], ["m-inbox"]);
+		assert.deepEqual([...starredMailboxIds].sort(), [
+			"m-archive",
+			"m-inbox",
+			"m-sub",
+		]);
+		// The map must cover every mailbox, or a starred row from Archive could
+		// not resolve its accountId.
+		assert.equal(mailboxIdToAccountId.get("m-archive"), "a1");
+	});
+
+	// A star on mail in Spam or Trash is not something the starred view should
+	// resurface; Gmail's All Mail is a second copy of everything, so including it
+	// renders every starred Gmail message twice.
+	test("the starred scope excludes All Mail, Junk and Trash", async () => {
+		const client = buildClient([account("a1")], {
+			a1: [
+				mailbox("m-inbox", "a1", "INBOX"),
+				mailbox("m-all", "a1", "[Gmail]/All Mail", ["All"]),
+				mailbox("m-junk", "a1", "[Gmail]/Spam", ["Junk"]),
+				mailbox("m-trash", "a1", "[Gmail]/Trash", ["Trash"]),
+				mailbox("m-sent", "a1", "[Gmail]/Sent Mail", ["Sent"]),
+			],
+		});
+
+		const { starredMailboxIds, mailboxIdToAccountId } =
+			await buildInboxMailboxMap(CONFIG_ID, client);
+
+		assert.deepEqual([...starredMailboxIds].sort(), ["m-inbox", "m-sent"]);
+		// Excluded mailboxes still resolve an accountId — the map is the wider set.
+		assert.equal(mailboxIdToAccountId.get("m-trash"), "a1");
+	});
+
+	test("a mailbox carrying several special uses is excluded on any one of them", async () => {
+		const client = buildClient([account("a1")], {
+			a1: [mailbox("m-archive-all", "a1", "Archive", ["Archive", "All"])],
+		});
+
+		const { starredMailboxIds } = await buildInboxMailboxMap(CONFIG_ID, client);
+		assert.equal(starredMailboxIds.size, 0);
+	});
+
+	test("muted mailboxes are excluded from both scopes", async () => {
+		const client = buildClient(
+			[account("a1")],
+			{
+				a1: [
+					mailbox("m-inbox", "a1", "INBOX"),
+					mailbox("m-muted", "a1", "Archive"),
+				],
+			},
+			[mutedSetting("MailboxMuted", "m-muted")],
+		);
+
+		const { inboxMailboxIds, starredMailboxIds } = await buildInboxMailboxMap(
+			CONFIG_ID,
+			client,
+		);
+
+		assert.deepEqual([...inboxMailboxIds], ["m-inbox"]);
+		assert.deepEqual([...starredMailboxIds], ["m-inbox"]);
+	});
+
+	test("a muted account contributes no mailboxes", async () => {
+		const client = buildClient(
+			[account("a1")],
+			{ a1: [mailbox("m-inbox", "a1", "INBOX")] },
+			[mutedSetting("AccountMuted", "a1")],
+		);
+
+		const { starredMailboxIds } = await buildInboxMailboxMap(CONFIG_ID, client);
+		assert.equal(starredMailboxIds.size, 0);
+	});
+});
+
+describe("buildListStarredThreadsOptions", () => {
+	test("scopes to every supplied mailbox, not just the inbox", () => {
+		const options = buildListStarredThreadsOptions(
+			{},
+			new Set(["m-inbox", "m-archive"]),
+		);
+
+		assert.deepEqual([...options.mailboxIds].sort(), ["m-archive", "m-inbox"]);
+		assert.equal(options.order, "desc");
+		assert.equal(options.excludeDeleted, true);
+	});
+
+	test("carries the caller's paging through", () => {
+		const options = buildListStarredThreadsOptions(
+			{ continuationToken: "tok", order: "asc", limit: 10 },
+			new Set(["m-inbox"]),
+		);
+
+		assert.equal(options.continuationToken, "tok");
+		assert.equal(options.order, "asc");
+		assert.equal(options.limit, 10);
+	});
+
+	test("defaults the page size to the unified default", () => {
+		const starred = buildListStarredThreadsOptions({}, new Set(["m-inbox"]));
+		const unified = buildListAllThreadsOptions({}, new Set(["m-inbox"]));
+		assert.equal(starred.limit, unified.limit);
+	});
+});

package/src/handlers/unified-threads.ts

@@ -3,6 +3,7 @@ import type {
 	IAccountSettingRepository,
 	MailboxItem,
 } from "@remit/data-ports";
+import { MailboxSpecialUse } from "@remit/domain-enums";
 import type { APIGatewayProxyEvent } from "aws-lambda";
 import type { Context } from "openapi-backend";
 import pMap from "p-map";
@@ -34,8 +35,34 @@ export interface InboxMapClient {
 }
 
 /**
- * Build a mailboxId→accountId map for all non-muted INBOX mailboxes across
- * all non-muted accounts of a given accountConfigId.
+ * Special-use folders a star never surfaces from.
+ *
+ * `Junk` and `Trash` match what Gmail and Fastmail do — a star on mail the user
+ * already threw away or that was classed as spam is not something the starred
+ * view should resurface. `All` is Gmail's All Mail: a second copy of everything
+ * already reachable through its own folder, and because a message's identity
+ * includes its mailbox, the copy is a distinct row carrying the same
+ * server-side \Flagged. Including it would render every starred Gmail message
+ * twice.
+ */
+const STARRED_EXCLUDED_SPECIAL_USE: readonly string[] = [
+	MailboxSpecialUse.All,
+	MailboxSpecialUse.Junk,
+	MailboxSpecialUse.Trash,
+];
+
+const isExcludedFromStarred = (mailbox: MailboxItem): boolean =>
+	mailbox.specialUse?.some((use) =>
+		STARRED_EXCLUDED_SPECIAL_USE.includes(use),
+	) === true;
+
+/**
+ * Build the read scope for the unified listing: a mailboxId→accountId map over
+ * every non-muted mailbox of every non-muted account in a given
+ * accountConfigId, plus two id sets — `inboxMailboxIds` (top-level INBOX only,
+ * the unified inbox scope) and `starredMailboxIds` (every folder a star may
+ * surface from, see `STARRED_EXCLUDED_SPECIAL_USE`). The map covers all
+ * mailboxes, excluded ones included, so any row still resolves its accountId.
  *
  * INBOX is identified by exact match `fullPath.toUpperCase() === "INBOX"` —
  * MailboxSpecialUse has no Inbox value per RFC 6154. This is the same rule
@@ -67,6 +94,7 @@ export const buildInboxMailboxMap = async (
 ): Promise<{
 	mailboxIdToAccountId: Map<string, string>;
 	inboxMailboxIds: Set<string>;
+	starredMailboxIds: Set<string>;
 }> => {
 	const [accounts, settings] = await Promise.all([
 		client.account.listAllByAccountConfig(accountConfigId),
@@ -94,21 +122,23 @@ export const buildInboxMailboxMap = async (
 
 	const mailboxIdToAccountId = new Map<string, string>();
 	const inboxMailboxIds = new Set<string>();
+	const starredMailboxIds = new Set<string>();
 
-	const inboxes = mailboxLists
+	const activeMailboxes = mailboxLists
 		.flat()
-		.filter(
-			(mailbox) =>
-				!isMailboxMuted(mailbox.mailboxId) &&
-				mailbox.fullPath.toUpperCase() === "INBOX",
-		);
+		.filter((mailbox) => !isMailboxMuted(mailbox.mailboxId));
 
-	for (const mailbox of inboxes) {
+	for (const mailbox of activeMailboxes) {
 		mailboxIdToAccountId.set(mailbox.mailboxId, mailbox.accountId);
-		inboxMailboxIds.add(mailbox.mailboxId);
+		if (!isExcludedFromStarred(mailbox)) {
+			starredMailboxIds.add(mailbox.mailboxId);
+		}
+		if (mailbox.fullPath.toUpperCase() === "INBOX") {
+			inboxMailboxIds.add(mailbox.mailboxId);
+		}
 	}
 
-	return { mailboxIdToAccountId, inboxMailboxIds };
+	return { mailboxIdToAccountId, inboxMailboxIds, starredMailboxIds };
 };
 
 /**
@@ -134,6 +164,28 @@ export const buildListAllThreadsOptions = (
 	excludeDeleted: true,
 });
 
+/**
+ * Build listByStarred options for the starred (`starred=true`) listing.
+ *
+ * A star marks the mail, not its placement, so the INBOX narrowing does not
+ * apply: the scope is every non-muted mailbox except the ones a star never
+ * surfaces from. Same defaults as the unified listing otherwise.
+ */
+export const buildListStarredThreadsOptions = (
+	query: {
+		continuationToken?: string;
+		order?: "asc" | "desc";
+		limit?: number;
+	},
+	starredMailboxIds: Set<string>,
+) => ({
+	order: query.order ?? ("desc" as const),
+	continuationToken: query.continuationToken,
+	limit: query.limit ?? DEFAULT_UNIFIED_THREADS_PAGE_SIZE,
+	mailboxIds: starredMailboxIds,
+	excludeDeleted: true,
+});
+
 /**
  * Attach accountId to each enriched ThreadMessageResponse row using the
  * mailboxId→accountId map built from inbox discovery. Same read-time-attach
@@ -158,28 +210,40 @@ export const UnifiedThreadOperations: Record<
 	) => {
 		const event = args[0] as APIGatewayProxyEvent;
 		const accountConfigId = getAccountConfigIdFromEvent(event);
-		const { continuationToken, order, limit } = context.request.query as {
+		const { continuationToken, order, limit, starred } = context.request
+			.query as {
 			continuationToken?: string;
 			order?: "asc" | "desc";
 			limit?: number;
+			starred?: boolean | string;
 		};
+		const starredOnly = starred === true || starred === "true";
 
 		const client = await getClient();
 
-		const { mailboxIdToAccountId, inboxMailboxIds } =
+		const { mailboxIdToAccountId, inboxMailboxIds, starredMailboxIds } =
 			await buildInboxMailboxMap(accountConfigId, client);
 
-		if (inboxMailboxIds.size === 0) {
+		const scope = starredOnly ? starredMailboxIds : inboxMailboxIds;
+		if (scope.size === 0) {
 			return { items: [], continuationToken: undefined };
 		}
 
-		const result = await client.threadMessage.listByDate(
-			accountConfigId,
-			buildListAllThreadsOptions(
-				{ continuationToken, order, limit },
-				inboxMailboxIds,
-			),
-		);
+		const result = starredOnly
+			? await client.threadMessage.listByStarred(
+					accountConfigId,
+					buildListStarredThreadsOptions(
+						{ continuationToken, order, limit },
+						starredMailboxIds,
+					),
+				)
+			: await client.threadMessage.listByDate(
+					accountConfigId,
+					buildListAllThreadsOptions(
+						{ continuationToken, order, limit },
+						inboxMailboxIds,
+					),
+				);
 
 		const enriched = await enrichThreadRows(
 			result.items,