@remit/backend 0.0.109 → 0.0.110

package/package.json

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

package/src/handlers/sync-progress.test.ts

@@ -9,7 +9,9 @@ import { describe, it } from "node:test";
 import {
 	computeMessagesSynced,
 	deriveMailboxPhase,
+	type MailboxProgressFields,
 	type MailboxSyncFields,
+	toMailboxSyncProgress,
 } from "./sync-progress.js";
 
 // ─── deriveMailboxPhase tests ───────────────────────────────────────────────
@@ -156,3 +158,48 @@ describe("computeMessagesSynced", () => {
 		assert.equal(computeMessagesSynced(mailbox), 50);
 	});
 });
+
+// ─── toMailboxSyncProgress tests ────────────────────────────────────────────
+
+const mailboxRow = (
+	overrides: Partial<MailboxProgressFields> = {},
+): MailboxProgressFields => ({
+	mailboxId: "mb-1",
+	fullPath: "INBOX",
+	lastMessageSyncAt: 1_700_000_000_000,
+	initialSyncCompletedAt: 1_700_000_000_001,
+	messageCount: 10,
+	lastSyncUid: 1,
+	highWaterMarkUid: 100,
+	...overrides,
+});
+
+describe("toMailboxSyncProgress", () => {
+	// Issue #771: the client cannot tell an arrival from a departure by count —
+	// one message in and one out nets to zero. The highest UID only ever moves
+	// up, so the projection has to carry it or the arrival stays invisible.
+	it("carries the mailbox's highest UID", () => {
+		assert.equal(
+			toMailboxSyncProgress(mailboxRow({ highWaterMarkUid: 4321 }))
+				.highWaterMarkUid,
+			4321,
+		);
+	});
+
+	it("reports the sentinel 0 for a mailbox that has never taken a message", () => {
+		assert.equal(
+			toMailboxSyncProgress(mailboxRow({ highWaterMarkUid: 0 }))
+				.highWaterMarkUid,
+			0,
+		);
+	});
+
+	it("projects identity, phase and totals alongside it", () => {
+		const progress = toMailboxSyncProgress(mailboxRow());
+		assert.equal(progress.mailboxId, "mb-1");
+		assert.equal(progress.fullPath, "INBOX");
+		assert.equal(progress.phase, "complete");
+		assert.equal(progress.messagesTotal, 10);
+		assert.equal(progress.lastSyncedAt, 1_700_000_000_000);
+	});
+});

package/src/handlers/sync-progress.ts

@@ -10,6 +10,21 @@ export type MailboxSyncFields = Pick<
 	| "highWaterMarkUid"
 >;
 
+/** A mailbox row, as far as the sync-status projection reads it. */
+export type MailboxProgressFields = MailboxSyncFields &
+	Pick<MailboxItem, "mailboxId" | "fullPath">;
+
+/** The per-mailbox entry `getSyncStatus` returns. */
+export interface MailboxSyncProgress {
+	mailboxId: string;
+	fullPath: string;
+	phase: string;
+	messagesTotal: number;
+	messagesSynced: number;
+	highWaterMarkUid: number;
+	lastSyncedAt: number | undefined;
+}
+
 /**
  * Derive a per-mailbox sync phase from worker-written sync state.
  *
@@ -62,3 +77,23 @@ export const computeMessagesSynced = (mailbox: MailboxSyncFields): number => {
 
 	return Math.min(Math.max(synced, 0), messagesTotal);
 };
+
+/**
+ * Project a mailbox row into its sync-status entry.
+ *
+ * `highWaterMarkUid` is carried through because a total cannot tell an arrival
+ * from a departure: a message landing in the same sync round that another one
+ * leaves nets to zero, and the client's freshness check saw nothing (#771). The
+ * highest UID only ever moves up, so it names the arrival on its own.
+ */
+export const toMailboxSyncProgress = (
+	mailbox: MailboxProgressFields,
+): MailboxSyncProgress => ({
+	mailboxId: mailbox.mailboxId,
+	fullPath: mailbox.fullPath,
+	phase: deriveMailboxPhase(mailbox),
+	messagesTotal: mailbox.messageCount ?? 0,
+	messagesSynced: computeMessagesSynced(mailbox),
+	highWaterMarkUid: mailbox.highWaterMarkUid ?? 0,
+	lastSyncedAt: mailbox.lastMessageSyncAt || undefined,
+});

package/src/handlers/sync.ts

@@ -12,7 +12,7 @@ import { sqsClient } from "../service/sqs.js";
 import { triggerAccountSync } from "../service/trigger-sync.js";
 import type { OperationHandler, SyncOperationIds } from "../types.js";
 import { assertAccountOwnership } from "./account-ownership.js";
-import { computeMessagesSynced, deriveMailboxPhase } from "./sync-progress.js";
+import { toMailboxSyncProgress } from "./sync-progress.js";
 
 interface SyncTriggerDeps {
 	sqsClient: SQSClient;
@@ -114,14 +114,7 @@ export const SyncOperations: Record<
 			mailboxCountTotal: account.mailboxCountTotal,
 			mailboxCountSynced: account.mailboxCountSynced,
 			lastSyncAt: account.lastSyncAt,
-			mailboxes: mailboxes.map((mailbox) => ({
-				mailboxId: mailbox.mailboxId,
-				fullPath: mailbox.fullPath,
-				phase: deriveMailboxPhase(mailbox),
-				messagesTotal: mailbox.messageCount ?? 0,
-				messagesSynced: computeMessagesSynced(mailbox),
-				lastSyncedAt: mailbox.lastMessageSyncAt || undefined,
-			})),
+			mailboxes: mailboxes.map(toMailboxSyncProgress),
 		};
 	},
 };