@remit/mailbox-service 0.0.7 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/mailbox-service",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/attribute-mapper.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert";
 import { describe, it } from "node:test";
-import { MailboxSpecialUse } from "@remit/domain-enums";
+import { MailboxAttribute, MailboxSpecialUse } from "@remit/domain-enums";
 import {
 	hasChildren,
 	isNoSelect,
@@ -50,7 +50,33 @@ describe("parseImapAttributes special-use", () => {
 	it("separates standard attributes from special-use", () => {
 		const parsed = parseImapAttributes(["\\HasChildren", "\\Sent"]);
 		assert.deepStrictEqual(parsed.specialUse, [MailboxSpecialUse.Sent]);
-		assert.deepStrictEqual(parsed.attributes, ["HasChildren"]);
+		assert.deepStrictEqual(parsed.attributes, ["\\HasChildren"]);
+	});
+
+	it("keeps standard attributes in the RFC 9051 backslash-prefixed form", () => {
+		const parsed = parseImapAttributes([
+			"\\NonExistent",
+			"\\Noinferiors",
+			"\\Noselect",
+			"\\HasChildren",
+			"\\HasNoChildren",
+			"\\Marked",
+			"\\Unmarked",
+			"\\Subscribed",
+			"\\Remote",
+		]);
+		assert.deepStrictEqual(parsed.attributes, [
+			"\\NonExistent",
+			"\\Noinferiors",
+			"\\Noselect",
+			"\\HasChildren",
+			"\\HasNoChildren",
+			"\\Marked",
+			"\\Unmarked",
+			"\\Subscribed",
+			"\\Remote",
+		]);
+		assert.deepStrictEqual(parsed.attributes, Object.values(MailboxAttribute));
 	});
 
 	it("collects unknown attributes without dropping them", () => {

package/src/attribute-mapper.ts

@@ -11,8 +11,9 @@ type MailboxSpecialUseValue =
 	(typeof MailboxSpecialUse)[keyof typeof MailboxSpecialUse];
 
 /**
- * Map from IMAP attribute strings to MailboxAttribute enum values
- * IMAP attributes have backslash prefix, our enum values don't
+ * Map from IMAP attribute strings to MailboxAttribute enum values.
+ * MailboxAttribute keeps the RFC 9051 backslash prefix; MailboxSpecialUse
+ * below is a canonical bare designation, so only that map strips it.
  */
 const ATTRIBUTE_MAP: Record<string, MailboxAttributeValue> = {
 	"\\NonExistent": MailboxAttribute.NonExistent,

package/src/flag-queue-stars.test.ts

@@ -0,0 +1,171 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import type {
+	IMessageFlagRepository,
+	IMessageRepository,
+	IThreadMessageRepository,
+	MessageItem,
+	ThreadMessageItem,
+	UpdateThreadMessageInput,
+} from "@remit/data-ports";
+import { MessageSystemFlag } from "@remit/domain-enums";
+import type { FlagPushService } from "./flag-push.js";
+import { FlagQueueService } from "./flag-queue.js";
+
+// #44: `hasStars` is the boolean of record and `star` its presentation colour.
+// The UI's star toggle sends only `isStarred`, so a star that left `star` at
+// the `none` sentinel disagreed with `hasStars` and every read site that
+// consulted the colour rejected the row. The colour now follows the boolean.
+
+const ACCOUNT_CONFIG_ID = "cfg-1";
+const ACCOUNT_ID = "acct-1";
+const MESSAGE_ID = "msg-1";
+const MAILBOX_ID = "mbx-1";
+const THREAD_MESSAGE_ID = "tm-1";
+
+const threadMessage = {
+	threadMessageId: THREAD_MESSAGE_ID,
+	accountConfigId: ACCOUNT_CONFIG_ID,
+	mailboxId: MAILBOX_ID,
+	sentDate: 1,
+	isRead: false,
+	isDeleted: false,
+	hasStars: false,
+	hasAttachment: false,
+} as unknown as ThreadMessageItem;
+
+const buildService = ({
+	alreadyFlagged = false,
+}: {
+	alreadyFlagged?: boolean;
+} = {}): {
+	service: FlagQueueService;
+	updates: UpdateThreadMessageInput[];
+	flips: Array<{ flagName: string; operation: string }>;
+} => {
+	const updates: UpdateThreadMessageInput[] = [];
+	const flips: Array<{ flagName: string; operation: string }> = [];
+
+	const messageService = {
+		get: async () => ({ mailboxId: MAILBOX_ID }) as unknown as MessageItem,
+	} as unknown as IMessageRepository;
+
+	const messageFlagService = {
+		hasFlag: async (_messageId: string, flagName: string) =>
+			flagName === MessageSystemFlag.Flagged ? alreadyFlagged : false,
+		addFlag: async () => {},
+		removeFlag: async () => {},
+	} as unknown as IMessageFlagRepository;
+
+	const threadMessageService = {
+		findAllByMessageId: async () => [threadMessage],
+		update: async (
+			_accountConfigId: string,
+			_threadMessageId: string,
+			input: UpdateThreadMessageInput,
+		) => {
+			updates.push(input);
+			return threadMessage;
+		},
+	} as unknown as IThreadMessageRepository;
+
+	const flagPushService = {
+		flip: async (event: { flagName: string; operation: string }) => {
+			flips.push({ flagName: event.flagName, operation: event.operation });
+		},
+	} as unknown as FlagPushService;
+
+	const service = new FlagQueueService({
+		messageFlagService,
+		messageService,
+		threadMessageService,
+		flagPushService,
+	});
+
+	return { service, updates, flips };
+};
+
+describe("updateFlags keeps hasStars and the star colour in step", () => {
+	test("starring without a colour sets both the boolean and a visible colour", async () => {
+		const { service, updates } = buildService();
+
+		await service.updateFlags(ACCOUNT_CONFIG_ID, MESSAGE_ID, ACCOUNT_ID, {
+			isStarred: true,
+		});
+
+		assert.deepEqual(updates, [{ hasStars: true, star: "yellow" }]);
+	});
+
+	test("unstarring clears the colour back to the none sentinel", async () => {
+		const { service, updates } = buildService({ alreadyFlagged: true });
+
+		await service.updateFlags(ACCOUNT_CONFIG_ID, MESSAGE_ID, ACCOUNT_ID, {
+			isStarred: false,
+		});
+
+		assert.deepEqual(updates, [{ hasStars: false, star: "none" }]);
+	});
+
+	test("an explicit colour wins over the default", async () => {
+		const { service, updates } = buildService();
+
+		await service.updateFlags(ACCOUNT_CONFIG_ID, MESSAGE_ID, ACCOUNT_ID, {
+			isStarred: true,
+			starColor: "red",
+		});
+
+		assert.deepEqual(updates, [{ hasStars: true, star: "red" }]);
+	});
+
+	// A colour-only request is legal on the wire. Before, it wrote the colour
+	// and left `hasStars` alone, so a coloured-but-unstarred row rendered
+	// unstarred, stayed out of Starred, and never pushed \Flagged.
+	test("a colour alone stars the message and pushes the flag", async () => {
+		const { service, updates, flips } = buildService();
+
+		await service.updateFlags(ACCOUNT_CONFIG_ID, MESSAGE_ID, ACCOUNT_ID, {
+			starColor: "blue",
+		});
+
+		assert.deepEqual(updates, [{ hasStars: true, star: "blue" }]);
+		assert.deepEqual(flips, [
+			{ flagName: MessageSystemFlag.Flagged, operation: "add" },
+		]);
+	});
+
+	test("the none colour unstars the message", async () => {
+		const { service, updates, flips } = buildService({ alreadyFlagged: true });
+
+		await service.updateFlags(ACCOUNT_CONFIG_ID, MESSAGE_ID, ACCOUNT_ID, {
+			starColor: "none",
+		});
+
+		assert.deepEqual(updates, [{ hasStars: false, star: "none" }]);
+		assert.deepEqual(flips, [
+			{ flagName: MessageSystemFlag.Flagged, operation: "remove" },
+		]);
+	});
+
+	test("isStarred decides the boolean when both fields are sent", async () => {
+		const { service, updates } = buildService();
+
+		await service.updateFlags(ACCOUNT_CONFIG_ID, MESSAGE_ID, ACCOUNT_ID, {
+			isStarred: true,
+			starColor: "none",
+		});
+
+		assert.deepEqual(updates, [{ hasStars: true, star: "none" }]);
+	});
+
+	test("starring pushes the Flagged keyword", async () => {
+		const { service, flips } = buildService();
+
+		await service.updateFlags(ACCOUNT_CONFIG_ID, MESSAGE_ID, ACCOUNT_ID, {
+			isStarred: true,
+		});
+
+		assert.deepEqual(flips, [
+			{ flagName: MessageSystemFlag.Flagged, operation: "add" },
+		]);
+	});
+});

package/src/flag-queue.ts

@@ -4,7 +4,7 @@ import type {
 	IThreadMessageRepository,
 } from "@remit/data-ports";
 import { NotFoundError } from "@remit/data-ports/errors";
-import { MessageSystemFlag, type StarColor } from "@remit/domain-enums";
+import { MessageSystemFlag, StarColor } from "@remit/domain-enums";
 import type { FlagPushOperationValue, FlagPushService } from "./flag-push.js";
 
 /**
@@ -452,32 +452,41 @@ export class FlagQueueService {
 			}
 		}
 
-		// Handle isStarred -> \Flagged flag and ThreadMessage.hasStars/star
+		// `hasStars` is the boolean of record (the byStarred index sort key) and
+		// the server-side \Flagged keyword; `star` is its presentation colour,
+		// whose absent state is the None sentinel. The two must never disagree,
+		// whichever field the caller sent:
+		//
+		//   isStarred alone  → colour follows the boolean (standard colour on,
+		//                      None off)
+		//   starColor alone  → boolean follows the colour, so `none` unstars and
+		//                      any real colour stars
+		//   both             → isStarred decides the boolean, starColor the colour
+		//
+		// The \Flagged push follows the resulting boolean in every case, so a
+		// colour-only request still reaches the server. `flipFlag` no-ops when the
+		// flag already holds the desired state.
 		if (input.isStarred !== undefined || input.starColor !== undefined) {
-			if (input.isStarred !== undefined) {
-				await this.flipFlag(
-					accountId,
-					accountConfigId,
-					messageId,
-					message.mailboxId,
-					MessageSystemFlag.Flagged,
-					input.isStarred ? "add" : "remove",
-				);
-			}
+			const starred =
+				input.isStarred ??
+				(input.starColor ?? StarColor.None) !== StarColor.None;
+			const color =
+				input.starColor ?? (starred ? StarColor.Yellow : StarColor.None);
 
-			// Update ThreadMessage hasStars and star color for ALL instances
-			const starUpdates: { hasStars?: boolean; star?: StarColorValue } = {};
-			if (input.isStarred !== undefined) {
-				starUpdates.hasStars = input.isStarred;
-			}
-			if (input.starColor !== undefined) {
-				starUpdates.star = input.starColor;
-			}
-			await this.updateThreadMessageStars(
+			await this.flipFlag(
+				accountId,
 				accountConfigId,
 				messageId,
-				starUpdates,
+				message.mailboxId,
+				MessageSystemFlag.Flagged,
+				starred ? "add" : "remove",
 			);
+
+			// Update ThreadMessage hasStars and star color for ALL instances
+			await this.updateThreadMessageStars(accountConfigId, messageId, {
+				hasStars: starred,
+				star: color,
+			});
 		}
 
 		// Return current state

package/src/message-sync-flags.test.ts

@@ -0,0 +1,131 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import type {
+	CreateThreadMessageInput,
+	IAddressRepository,
+	IEnvelopeRepository,
+	IMailboxRepository,
+	IMessageRepository,
+	IThreadMessageRepository,
+	ThreadMessageItem,
+} from "@remit/data-ports";
+import type { ManagedConnectionFactory } from "./connection-factory.js";
+import { MessageSyncService } from "./message-sync.js";
+import type { ImapEnvelope } from "./types.js";
+
+// #44: initial sync hardcoded `hasStars: false` on row create, so mail flagged
+// in another client arrived unstarred and never appeared in Flagged. The
+// server's \Flagged keyword is the star; these cover the mapping on create.
+
+const ACCOUNT_ID = "acct-1";
+const ACCOUNT_CONFIG_ID = "cfg-1";
+const MAILBOX_ID = "mbx-1";
+const MESSAGE_ID = "msg-1";
+
+const envelope: ImapEnvelope = {
+	date: new Date(0).toISOString(),
+	messageId: "<root@example.com>",
+	subject: "Subject",
+	from: [{ name: "Sender", mailbox: "sender", host: "example.com" }],
+	sender: [],
+	replyTo: [],
+	to: [],
+	cc: [],
+	bcc: [],
+	inReplyTo: "",
+};
+
+/**
+ * Capture the ThreadMessage create input the sync path builds. Only `create` is
+ * exercised; the rest of the port is unreachable from this code path.
+ */
+const captureCreate = (): {
+	repo: IThreadMessageRepository;
+	inputs: CreateThreadMessageInput[];
+} => {
+	const inputs: CreateThreadMessageInput[] = [];
+	const repo = {
+		create: async (input: CreateThreadMessageInput) => {
+			inputs.push(input);
+			return input as unknown as ThreadMessageItem;
+		},
+	} as unknown as IThreadMessageRepository;
+	return { repo, inputs };
+};
+
+const stub = <T>(): T => ({}) as T;
+
+/**
+ * `createThreadForMessage` is private to the service — it is only ever reached
+ * through a live IMAP fetch. Reach it directly so the flag mapping is covered
+ * without standing up a server.
+ */
+type CreateThreadForMessage = (
+	threadMessageService: IThreadMessageRepository,
+	messageId: string,
+	mailboxId: string,
+	accountId: string,
+	accountConfigId: string,
+	uid: number,
+	internalDate: number,
+	sentDate: number,
+	envelope: ImapEnvelope,
+	flags: string[],
+	references?: string[],
+	hasAttachment?: boolean,
+) => Promise<void>;
+
+const createThreadWithFlags = async (
+	flags: string[],
+): Promise<CreateThreadMessageInput> => {
+	const service = new MessageSyncService(
+		stub<ManagedConnectionFactory>(),
+		stub<IMailboxRepository>(),
+		stub<IMessageRepository>(),
+		stub<IEnvelopeRepository>(),
+		stub<IAddressRepository>(),
+		stub<IThreadMessageRepository>(),
+	);
+	const { repo, inputs } = captureCreate();
+	const now = Date.now();
+
+	await (
+		service as unknown as { createThreadForMessage: CreateThreadForMessage }
+	).createThreadForMessage(
+		repo,
+		MESSAGE_ID,
+		MAILBOX_ID,
+		ACCOUNT_ID,
+		ACCOUNT_CONFIG_ID,
+		42,
+		now,
+		now,
+		envelope,
+		flags,
+	);
+
+	assert.equal(inputs.length, 1);
+	const [input] = inputs;
+	assert.ok(input);
+	return input;
+};
+
+describe("message sync maps IMAP flags onto the created ThreadMessage", () => {
+	test("a message carrying \\Flagged is created starred", async () => {
+		const input = await createThreadWithFlags(["\\Flagged"]);
+		assert.equal(input.hasStars, true);
+		assert.equal(input.star, "yellow");
+	});
+
+	test("a message without \\Flagged is created unstarred", async () => {
+		const input = await createThreadWithFlags(["\\Seen"]);
+		assert.equal(input.hasStars, false);
+		assert.equal(input.star, "none");
+	});
+
+	test("\\Flagged and \\Seen are mapped independently", async () => {
+		const input = await createThreadWithFlags(["\\Seen", "\\Flagged"]);
+		assert.equal(input.isRead, true);
+		assert.equal(input.hasStars, true);
+	});
+});

package/src/message-sync.ts

@@ -17,7 +17,11 @@ import {
 	deriveThreadId,
 	isValidMessageId,
 } from "@remit/data-ports/id";
-import { AddressRole, MailboxCursorState } from "@remit/domain-enums";
+import {
+	AddressRole,
+	MailboxCursorState,
+	StarColor,
+} from "@remit/domain-enums";
 import pMap from "p-map";
 import type { ManagedConnectionFactory } from "./connection-factory.js";
 import { guardMailboxCursor, isCursorRebuildNeeded } from "./mailbox-cursor.js";
@@ -935,6 +939,13 @@ export class MessageSyncService {
 		// Check if message is read based on IMAP flags
 		const isRead = flags.includes("\\Seen");
 
+		// The server's \Flagged keyword is the star. Mail flagged in another
+		// client must arrive starred, so carry it through on create rather than
+		// defaulting every row to unstarred. Compared as a literal for the same
+		// reason \Seen is above: the generated MessageSystemFlag members drop the
+		// leading backslash, so they do not match a wire flag.
+		const hasStars = flags.includes("\\Flagged");
+
 		// Extract sender info. When the server could not parse the From address,
 		// omit fromEmail rather than persist a fabricated string — a display name
 		// may still be present and useful, so keep it.
@@ -967,7 +978,8 @@ export class MessageSyncService {
 				isRead,
 				isDeleted: false,
 				hasAttachment,
-				hasStars: false,
+				hasStars,
+				star: hasStars ? StarColor.Yellow : StarColor.None,
 			})
 			.catch((error: unknown) => {
 				// Ignore conflict errors (idempotent create)

package/src/system-flag-wire-format.test.ts

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	MailboxAttribute,
+	MessageKeywordFlag,
+	MessageSystemFlag,
+} from "@remit/domain-enums";
+
+/**
+ * RFC 9051 §2.3.2 system flags and §7.3.1 mailbox attributes are
+ * backslash-prefixed on the wire, and these enum values reach an IMAP server
+ * verbatim: `handleFlagPush` passes a marker's `flagName` straight to
+ * `ImapFlowConnection.addFlags`/`removeFlags`. A value that has lost its
+ * backslash is still a legal STORE argument — the server takes it as a custom
+ * keyword — so the push silently sets the wrong thing rather than failing.
+ *
+ * These enums are generated, and the emitter writes their values into
+ * JavaScript source where an unescaped `\S` collapses to `S` (issue #64).
+ * Pin the exact bytes so a regression fails here instead of on a real
+ * mailbox.
+ */
+const SYSTEM_FLAG_WIRE_FORMAT = {
+	Seen: "\\Seen",
+	Answered: "\\Answered",
+	Flagged: "\\Flagged",
+	Deleted: "\\Deleted",
+	Draft: "\\Draft",
+} as const;
+
+const MAILBOX_ATTRIBUTE_WIRE_FORMAT = {
+	NonExistent: "\\NonExistent",
+	NoInferiors: "\\Noinferiors",
+	NoSelect: "\\Noselect",
+	HasChildren: "\\HasChildren",
+	HasNoChildren: "\\HasNoChildren",
+	Marked: "\\Marked",
+	Unmarked: "\\Unmarked",
+	Subscribed: "\\Subscribed",
+	Remote: "\\Remote",
+} as const;
+
+describe("IMAP system flag wire format (issue #64)", () => {
+	it("carries the RFC 9051 backslash prefix on every member", () => {
+		assert.deepEqual({ ...MessageSystemFlag }, { ...SYSTEM_FLAG_WIRE_FORMAT });
+	});
+
+	for (const [name, wireValue] of Object.entries(SYSTEM_FLAG_WIRE_FORMAT)) {
+		it(`${name} is one backslash followed by the flag name`, () => {
+			assert.equal(wireValue.charCodeAt(0), 0x5c);
+			assert.equal(wireValue.slice(1), name);
+			assert.equal(wireValue.length, name.length + 1);
+		});
+	}
+
+	it("leaves keyword flags unprefixed", () => {
+		for (const wireValue of Object.values(MessageKeywordFlag)) {
+			assert.equal(wireValue.startsWith("\\"), false);
+			assert.equal(wireValue.startsWith("$"), true);
+		}
+	});
+});
+
+describe("IMAP mailbox attribute wire format (issue #64)", () => {
+	it("carries the RFC 9051 backslash prefix on every member", () => {
+		assert.deepEqual(
+			{ ...MailboxAttribute },
+			{ ...MAILBOX_ATTRIBUTE_WIRE_FORMAT },
+		);
+	});
+
+	it("prefixes every value with exactly one backslash", () => {
+		for (const wireValue of Object.values(MailboxAttribute)) {
+			assert.equal(wireValue.charCodeAt(0), 0x5c);
+			assert.equal(wireValue.charCodeAt(1) === 0x5c, false);
+		}
+	});
+});