@remit/backend 0.0.143 → 0.0.145

package/{src/derive/contentSignature.ts → dist/src/derive/contentSignature.js}

@@ -1,10 +1,4 @@
-import {
-	type SignedPathFailure,
-	signStoragePath,
-	verifyStoragePath,
-} from "@remit/storage-service/signed-path";
-import { usesBetterAuthJwt } from "../data-backend.js";
-
+import { signStoragePath, verifyStoragePath, } from "@remit/storage-service/signed-path";
 /**
  * Signed-URL scheme for `/content/*` on the self-host stack.
  *
@@ -29,9 +23,7 @@ import { usesBetterAuthJwt } from "../data-backend.js";
  * write side (an attachment upload URL) under a different derivation label. This
  * module is the read side's label, TTL and public shape.
  */
-
 const KEY_DERIVATION_LABEL = "remit-content-url-signing-v1";
-
 /**
  * Default validity window for a signed content URL. Long enough to cover a
  * viewing session (react-query caches describeMessage for 30 min and inline
@@ -39,84 +31,38 @@ const KEY_DERIVATION_LABEL = "remit-content-url-signing-v1";
  * leaks.
  */
 export const CONTENT_URL_TTL_SECONDS = 3600;
-
-export interface ContentSignature {
-	exp: number;
-	sig: string;
-}
-
-/**
- * A function that signs a decoded, account-scoped storage path and returns the
- * `exp`/`sig` query params to append to its content URL.
- */
-export type ContentSigner = (relativePath: string) => ContentSignature;
-
-export const createContentSigner = (
-	masterSecret: string,
-	ttlSeconds: number = CONTENT_URL_TTL_SECONDS,
-): ContentSigner => {
-	return (relativePath) => {
-		const exp = Math.floor(Date.now() / 1000) + ttlSeconds;
-		return {
-			exp,
-			sig: signStoragePath(masterSecret, KEY_DERIVATION_LABEL, relativePath, [
-				exp,
-			]),
-		};
-	};
+export const createContentSigner = (masterSecret, ttlSeconds = CONTENT_URL_TTL_SECONDS) => {
+    return (relativePath) => {
+        const exp = Math.floor(Date.now() / 1000) + ttlSeconds;
+        return {
+            exp,
+            sig: signStoragePath(masterSecret, KEY_DERIVATION_LABEL, relativePath, [
+                exp,
+            ]),
+        };
+    };
 };
-
 /**
  * Build the content-URL signer for the current environment, or `undefined` when
  * signing does not apply. Signing is enforced on the self-host SQL backend,
  * which serves `/content/*` straight from the backend container; on AWS the
  * Lambda@Edge JWT verifier guards `/content/*` and the URL stays unsigned so
- * CloudFront/S3 behaviour is unchanged. Throws on the self-host backend when the
- * master secret is missing, so a misconfigured deploy fails loud rather than
- * shipping unsigned (unauthenticated) content URLs.
+ * CloudFront/S3 behaviour is unchanged.
  */
-export const getContentSigner = (): ContentSigner | undefined => {
-	if (!usesBetterAuthJwt()) return undefined;
-	const secret = process.env.BETTER_AUTH_SECRET;
-	if (!secret || secret.length === 0) {
-		throw new Error(
-			"the self-host SQL backend requires BETTER_AUTH_SECRET to sign content URLs",
-		);
-	}
-	return createContentSigner(secret);
-};
-
-export type ContentSignatureFailure = SignedPathFailure;
-
-export type ContentSignatureResult =
-	| { valid: true }
-	| { valid: false; reason: ContentSignatureFailure };
-
+export const getContentSigner = (config) => config.auth.mode === "BetterAuthJwt"
+    ? createContentSigner(config.auth.contentSigningSecret)
+    : undefined;
 /**
  * Verify a signed content request. Recomputes the HMAC over the requested path
  * and the supplied expiry and constant-time compares it against the presented
  * signature. Pure so the decision can be unit-tested without a live server.
  */
-export const verifyContentSignature = (
-	relativePath: string,
-	expRaw: string | undefined,
-	sig: string | undefined,
-	masterSecret: string,
-	nowSeconds: number,
-): ContentSignatureResult => {
-	if (!expRaw || !sig) return { valid: false, reason: "missing" };
-
-	const exp = Number(expRaw);
-	if (!Number.isInteger(exp) || exp <= 0) {
-		return { valid: false, reason: "malformed" };
-	}
-
-	return verifyStoragePath(
-		masterSecret,
-		KEY_DERIVATION_LABEL,
-		relativePath,
-		[exp],
-		sig,
-		nowSeconds,
-	);
+export const verifyContentSignature = (relativePath, expRaw, sig, masterSecret, nowSeconds) => {
+    if (!expRaw || !sig)
+        return { valid: false, reason: "missing" };
+    const exp = Number(expRaw);
+    if (!Number.isInteger(exp) || exp <= 0) {
+        return { valid: false, reason: "malformed" };
+    }
+    return verifyStoragePath(masterSecret, KEY_DERIVATION_LABEL, relativePath, [exp], sig, nowSeconds);
 };

package/dist/src/derive/contentUrl.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Build the public CloudFront URL that fetches a single body part for a
+ * message. The path layout is what the Lambda@Edge JWT verifier expects
+ * (PR 1 of #224): `/content/accounts/{accountConfigId}/{accountId}/messages/
+ * {messageId}/parts/{partPath}`.
+ *
+ * The function is intentionally pure — domain comes from configuration so
+ * tests can pin the output without env vars. `partPath` is passed through
+ * `encodeURIComponent` because IMAP section paths are dot-separated digits
+ * (e.g. `1`, `1.2`, `2.1.3`) but a defensive encode keeps the builder safe
+ * if the path ever carries unexpected characters.
+ */
+import type { ContentSigner } from "./contentSignature.js";
+export interface BuildContentUrlInput {
+    domain: string;
+    accountConfigId: string;
+    accountId: string;
+    messageId: string;
+    partPath: string;
+    /**
+     * When present (self-host stack), append an `exp`/`sig` signature scoped to
+     * this account's storage path. Absent on AWS, where Lambda@Edge guards the
+     * URL and the path stays unsigned. See `contentSignature.ts`.
+     */
+    sign?: ContentSigner;
+}
+export interface BuildStorageContentUrlInput {
+    domain: string;
+    storageKey: string;
+    sign?: ContentSigner;
+}
+export declare const buildStorageContentUrl: (input: BuildStorageContentUrlInput) => string;
+export declare const buildContentUrl: (input: BuildContentUrlInput) => string;

package/dist/src/derive/contentUrl.js

@@ -0,0 +1,27 @@
+export const buildStorageContentUrl = (input) => {
+    const { domain, storageKey, sign } = input;
+    const normalizedDomain = domain.replace(/\/+$/, "");
+    const base = normalizedDomain.startsWith("http")
+        ? normalizedDomain
+        : `https://${normalizedDomain}`;
+    // The signed message is the decoded, account-scoped storage path — the same
+    // value the `/content` route recomputes from `req.path`. Keep it in lockstep
+    // with the verifier's `req.path.replace(/^\/content\//, "")`.
+    const safeKey = storageKey
+        .split("/")
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+    const url = `${base}/content/${safeKey}`;
+    if (!sign)
+        return url;
+    const { exp, sig } = sign(storageKey);
+    return `${url}?exp=${exp}&sig=${encodeURIComponent(sig)}`;
+};
+export const buildContentUrl = (input) => {
+    const { domain, accountConfigId, accountId, messageId, partPath, sign } = input;
+    return buildStorageContentUrl({
+        domain,
+        storageKey: `accounts/${accountConfigId}/${accountId}/messages/${messageId}/parts/${partPath}`,
+        sign,
+    });
+};

package/{src/derive/deriveMuted.ts → dist/src/derive/deriveMuted.d.ts}

@@ -1,10 +1,8 @@
 import type { AddressFlags } from "@remit/api-openapi-types";
-
 /**
  * Derive whether the From address is muted from an Address's flags map.
  *
  * Pure function, no I/O. Frontend never derives this — single source of
  * truth for filtering the daily brief.
  */
-export const deriveMuted = (flags: AddressFlags | undefined): boolean =>
-	flags?.muted?.value === true;
+export declare const deriveMuted: (flags: AddressFlags | undefined) => boolean;

package/dist/src/derive/deriveMuted.js

@@ -0,0 +1,7 @@
+/**
+ * Derive whether the From address is muted from an Address's flags map.
+ *
+ * Pure function, no I/O. Frontend never derives this — single source of
+ * truth for filtering the daily brief.
+ */
+export const deriveMuted = (flags) => flags?.muted?.value === true;

package/dist/src/derive/enrichThreadRows.d.ts

@@ -0,0 +1,118 @@
+import type { AddressItem, LabelItem, MessageItem, MessageLabelItem, ThreadMessageItem } from "@remit/data-ports";
+/**
+ * Subset of the ElectroDB client surface used for batch enrichment. Declared
+ * structurally so unit tests can pass an in-memory fake without standing up
+ * DynamoDB.
+ */
+export interface EnrichClient {
+    message: {
+        get(messageIds: string[]): Promise<MessageItem[]>;
+    };
+    address: {
+        getAddress(accountConfigId: string, addressIds: string[]): Promise<AddressItem[]>;
+    };
+    messageLabel: {
+        listByMessageIds(messageIds: string[]): Promise<MessageLabelItem[]>;
+    };
+    label: {
+        listByAccountConfig(accountConfigId: string): Promise<LabelItem[]>;
+    };
+}
+/**
+ * Plan the unique batch-fetch keys for a page of ThreadMessage rows.
+ *
+ * Splitting this out keeps the dedup logic testable without DynamoDB and
+ * documents the contract: a page of N rows produces at most one BatchGet
+ * for messages and one for addresses, no matter how many rows share the
+ * same messageId / sender.
+ *
+ * `addressId` is derived deterministically from `(accountConfigId, fromEmail)`
+ * via `deriveAddressId`, mirroring the write path in
+ * `body-sync.ts`. Rows without a `fromEmail` (rare; sentinel/system rows)
+ * contribute no addressId and fall back to `senderTrust: "unknown"`.
+ */
+export interface BatchPlan {
+    messageIds: string[];
+    addressIds: string[];
+    addressIdByRow: Map<string, string>;
+}
+export declare const planBatchFetch: (rows: ThreadMessageItem[]) => BatchPlan;
+/**
+ * Enrich a page of ThreadMessage rows with `senderTrust` and `muted` (both
+ * derived from the From Address's flags map), `authenticity`, `autoMoved` and
+ * `spamReport`, and the `status`/`syncStatus` pair an IMAP mutation leaves
+ * behind together with the mutation an abandoned one names (all projected
+ * straight from the Message row — no ThreadMessage
+ * column of their own, see `deriveAutoMoved`). `toResponse` seeds that pair
+ * with the ordinary inbound values, which the projection then overwrites; a
+ * ThreadMessage row whose Message row is missing from the batch is broken in a
+ * way this read path cannot report, and claiming a mutation it has no evidence
+ * of would be worse.
+ *
+ * `category` is not enriched: it is denormalized onto the ThreadMessage row
+ * (shared with `Message.category`'s write-once value, see body-sync.ts) and
+ * carried straight through by `toResponse`, so the value a client renders is
+ * the value the category filter matched.
+ *
+ * Two BatchGetItem calls per page, regardless of page size — see
+ * `planBatchFetch` for the dedup contract.
+ *
+ * Missing rows fall back gracefully: `senderTrust` defaults to `"unknown"`,
+ * `muted` defaults to `false`, and `authenticity` / `autoMoved` are omitted
+ * whenever the Message row is absent or the move isn't a real, in-effect
+ * auto-move.
+ *
+ * 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 declare const enrichThreadRows: (rows: ThreadMessageItem[], client: EnrichClient, accountConfigId: string) => Promise<{
+    senderTrust: import("./senderTrust.js").SenderTrustValue;
+    muted: boolean;
+    spamReport?: {
+        reportedAt: number;
+    } | undefined;
+    labels?: {
+        labelId: string;
+        name: string;
+        color: LabelItem["color"];
+    }[] | undefined;
+    autoMoved?: import("@remit/api-openapi-types").Components.Schemas.AutoMovedInfo;
+    authenticity?: {
+        fromDomain: string;
+        dkimMismatch: boolean;
+        dkimDomain?: string | undefined;
+        displayNameCorrespondence?: "Corresponds" | "Lookalike" | "ForeignAddress" | "Unrelated" | "NoClaim" | undefined;
+        offDomainLinkDomains?: string[] | undefined;
+        signerDomain?: string | undefined;
+        envelopeDomain?: string | undefined;
+        signerMessageCount?: number | undefined;
+        signerFirstSeenAt?: number | undefined;
+    } | undefined;
+    status: import("@remit/api-openapi-types").Components.Schemas.MessageStatus;
+    syncStatus: import("@remit/api-openapi-types").Components.Schemas.MessageSyncStatus;
+    abandonedMutation: import("@remit/api-openapi-types").Components.Schemas.MessageMutation;
+    threadMessageId: import("@remit/api-openapi-types").Components.Schemas.UUID;
+    threadId: import("@remit/api-openapi-types").Components.Schemas.UUID;
+    messageId: import("@remit/api-openapi-types").Components.Schemas.UUID;
+    accountConfigId: import("@remit/api-openapi-types").Components.Schemas.UUID;
+    mailboxId: import("@remit/api-openapi-types").Components.Schemas.UUID;
+    fromEmail?: string;
+    fromName?: string;
+    subject?: string;
+    sentDate: number;
+    isRead: boolean;
+    hasAttachment: boolean;
+    star: import("@remit/api-openapi-types").Components.Schemas.StarColor;
+    hasStars: boolean;
+    isDeleted: boolean;
+    snippet?: import("@remit/api-openapi-types").Components.Schemas.String256;
+    createdAt: number;
+    updatedAt: number;
+    category: import("@remit/api-openapi-types").Components.Schemas.MessageCategory;
+    accountId?: import("@remit/api-openapi-types").Components.Schemas.UUID;
+}[]>;

package/dist/src/derive/enrichThreadRows.js

@@ -0,0 +1,151 @@
+import { deriveAddressId } from "@remit/data-ports/id";
+import { MessageMutation, MessageStatus, MessageSyncStatus, SenderTrust, StarColor, } from "@remit/domain-enums";
+import { deriveAutoMoved } from "./autoMoved.js";
+import { deriveMuted } from "./deriveMuted.js";
+import { deriveSenderTrust } from "./senderTrust.js";
+const toResponse = (item) => ({
+    threadMessageId: item.threadMessageId,
+    threadId: item.threadId,
+    messageId: item.messageId,
+    accountConfigId: item.accountConfigId,
+    mailboxId: item.mailboxId,
+    fromEmail: item.fromEmail,
+    fromName: item.fromName,
+    subject: item.subject,
+    sentDate: item.sentDate,
+    isRead: item.isRead,
+    hasAttachment: item.hasAttachment,
+    star: item.star ?? StarColor.None,
+    hasStars: item.hasStars,
+    isDeleted: item.isDeleted,
+    snippet: item.snippet,
+    category: item.category,
+    createdAt: item.createdAt,
+    updatedAt: item.updatedAt,
+    senderTrust: SenderTrust.Unknown,
+    muted: false,
+    status: MessageStatus.active,
+    syncStatus: MessageSyncStatus.pending,
+    abandonedMutation: MessageMutation.none,
+});
+export const planBatchFetch = (rows) => {
+    const messageIds = new Set();
+    const addressIds = new Set();
+    const addressIdByRow = new Map();
+    for (const row of rows) {
+        messageIds.add(row.messageId);
+        if (!row.fromEmail)
+            continue;
+        const addressId = deriveAddressId(row.accountConfigId, row.fromEmail);
+        addressIds.add(addressId);
+        addressIdByRow.set(row.threadMessageId, addressId);
+    }
+    return {
+        messageIds: [...messageIds],
+        addressIds: [...addressIds],
+        addressIdByRow,
+    };
+};
+/**
+ * Enrich a page of ThreadMessage rows with `senderTrust` and `muted` (both
+ * derived from the From Address's flags map), `authenticity`, `autoMoved` and
+ * `spamReport`, and the `status`/`syncStatus` pair an IMAP mutation leaves
+ * behind together with the mutation an abandoned one names (all projected
+ * straight from the Message row — no ThreadMessage
+ * column of their own, see `deriveAutoMoved`). `toResponse` seeds that pair
+ * with the ordinary inbound values, which the projection then overwrites; a
+ * ThreadMessage row whose Message row is missing from the batch is broken in a
+ * way this read path cannot report, and claiming a mutation it has no evidence
+ * of would be worse.
+ *
+ * `category` is not enriched: it is denormalized onto the ThreadMessage row
+ * (shared with `Message.category`'s write-once value, see body-sync.ts) and
+ * carried straight through by `toResponse`, so the value a client renders is
+ * the value the category filter matched.
+ *
+ * Two BatchGetItem calls per page, regardless of page size — see
+ * `planBatchFetch` for the dedup contract.
+ *
+ * Missing rows fall back gracefully: `senderTrust` defaults to `"unknown"`,
+ * `muted` defaults to `false`, and `authenticity` / `autoMoved` are omitted
+ * whenever the Message row is absent or the move isn't a real, in-effect
+ * auto-move.
+ *
+ * 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, client, accountConfigId) => {
+    if (rows.length === 0)
+        return [];
+    const plan = planBatchFetch(rows);
+    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();
+    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 authenticityByMessageId = new Map(messages.map((m) => [m.messageId, m.authenticity]));
+    const autoMovedByMessageId = new Map(messages.map((m) => [m.messageId, deriveAutoMoved(m)]));
+    const spamReportByMessageId = new Map(messages.map((m) => [m.messageId, m.spamReport]));
+    const settlementByMessageId = new Map(messages.map((m) => [
+        m.messageId,
+        {
+            status: m.status,
+            syncStatus: m.syncStatus,
+            abandonedMutation: m.abandonedMutation,
+        },
+    ]));
+    const trustByAddressId = new Map(addresses.map((a) => [a.addressId, deriveSenderTrust(a.flags)]));
+    const mutedByAddressId = new Map(addresses.map((a) => [a.addressId, deriveMuted(a.flags)]));
+    return rows.map((row) => {
+        const base = toResponse(row);
+        const authenticity = authenticityByMessageId.get(row.messageId);
+        const autoMoved = autoMovedByMessageId.get(row.messageId);
+        const spamReport = spamReportByMessageId.get(row.messageId);
+        const addressId = plan.addressIdByRow.get(row.threadMessageId);
+        const senderTrust = addressId
+            ? (trustByAddressId.get(addressId) ?? SenderTrust.Unknown)
+            : SenderTrust.Unknown;
+        const muted = addressId
+            ? (mutedByAddressId.get(addressId) ?? false)
+            : false;
+        const labels = labelsByMessageId.get(row.messageId);
+        const settlement = settlementByMessageId.get(row.messageId);
+        return {
+            ...base,
+            ...(settlement ?? {}),
+            ...(authenticity !== undefined ? { authenticity } : {}),
+            ...(autoMoved !== undefined ? { autoMoved } : {}),
+            ...(labels !== undefined ? { labels } : {}),
+            ...(spamReport !== undefined ? { spamReport } : {}),
+            senderTrust,
+            muted,
+        };
+    });
+};

package/dist/src/derive/filterThreadCriteria.d.ts

@@ -0,0 +1,23 @@
+import type { SenderTrust, ThreadMessageResponse } from "@remit/api-openapi-types";
+/**
+ * Off-row search criteria — fields that live on the underlying Message/Address,
+ * not on the ThreadMessage row. They are resolved by enriching the windowed
+ * rows (see enrichThreadRows) and filtering in app code, because no index or
+ * FilterExpression can serve them.
+ *
+ * `senderTrust` derives from AddressItem.flags and `dkimMismatch` from
+ * MessageItem.authenticity. `category` is not one of these: it is denormalized
+ * onto the ThreadMessage row and filtered in SQL, inside the window.
+ */
+export interface OffRowCriteria {
+    senderTrust?: SenderTrust[];
+    dkimMismatch?: boolean;
+}
+export declare const hasOffRowCriteria: (criteria: OffRowCriteria) => boolean;
+/**
+ * Filter enriched rows by the off-row criteria. Each active criterion is an
+ * any-of set (AND across criteria, OR within a set). A row with no
+ * `authenticity` signal never matches a `dkimMismatch` filter (absence means no
+ * signal, not a verdict).
+ */
+export declare const filterByOffRowCriteria: (rows: ThreadMessageResponse[], criteria: OffRowCriteria) => ThreadMessageResponse[];

package/dist/src/derive/filterThreadCriteria.js

@@ -0,0 +1,24 @@
+export const hasOffRowCriteria = (criteria) => Boolean(criteria.senderTrust?.length) || criteria.dkimMismatch !== undefined;
+/**
+ * Filter enriched rows by the off-row criteria. Each active criterion is an
+ * any-of set (AND across criteria, OR within a set). A row with no
+ * `authenticity` signal never matches a `dkimMismatch` filter (absence means no
+ * signal, not a verdict).
+ */
+export const filterByOffRowCriteria = (rows, criteria) => {
+    if (!hasOffRowCriteria(criteria))
+        return rows;
+    const trustSet = criteria.senderTrust?.length
+        ? new Set(criteria.senderTrust)
+        : undefined;
+    const { dkimMismatch } = criteria;
+    return rows.filter((row) => {
+        if (trustSet && !trustSet.has(row.senderTrust))
+            return false;
+        if (dkimMismatch !== undefined &&
+            row.authenticity?.dkimMismatch !== dkimMismatch) {
+            return false;
+        }
+        return true;
+    });
+};

package/{src/derive/pendingMoveCounts.ts → dist/src/derive/pendingMoveCounts.d.ts}

@@ -1,15 +1,13 @@
 import type { MailboxItem } from "@remit/data-ports";
-
 /**
  * The subset of a pending placement-move marker (issue #1271) this
  * derivation needs — decoupled from the concrete marker type so it stays a
  * pure function over plain data.
  */
 export interface PendingPlacementMove {
-	sourceMailboxId: string;
-	destinationMailboxId: string;
+    sourceMailboxId: string;
+    destinationMailboxId: string;
 }
-
 /**
  * The subset of a pending flag-push marker (issue #1273) this derivation
  * needs. Only `\Seen` markers are meaningful here — `mailboxId` is the
@@ -17,10 +15,9 @@ export interface PendingPlacementMove {
  * `applyPendingMoveCountPrediction` already tolerates for placement moves.
  */
 export interface PendingUnseenFlagPush {
-	mailboxId: string;
-	operation: "add" | "remove";
+    mailboxId: string;
+    operation: "add" | "remove";
 }
-
 /**
  * Adjusts `messageCount` and `unseenCount` on a set of mailboxes to reflect
  * every pending placement move (issue #1271) and pending `\Seen` flag push
@@ -42,49 +39,4 @@ export interface PendingUnseenFlagPush {
  * Pure: takes the mailboxes and the pending markers as plain input, returns a
  * new array. Never mutates its arguments.
  */
-export const applyPendingMoveCountPrediction = (
-	mailboxes: readonly MailboxItem[],
-	pendingMoves: readonly PendingPlacementMove[],
-	pendingUnseenFlagPushes: readonly PendingUnseenFlagPush[] = [],
-): MailboxItem[] => {
-	if (pendingMoves.length === 0 && pendingUnseenFlagPushes.length === 0) {
-		return [...mailboxes];
-	}
-
-	const messageCountDelta = new Map<string, number>();
-	for (const move of pendingMoves) {
-		if (move.sourceMailboxId === move.destinationMailboxId) continue;
-		messageCountDelta.set(
-			move.sourceMailboxId,
-			(messageCountDelta.get(move.sourceMailboxId) ?? 0) - 1,
-		);
-		messageCountDelta.set(
-			move.destinationMailboxId,
-			(messageCountDelta.get(move.destinationMailboxId) ?? 0) + 1,
-		);
-	}
-
-	const unseenCountDelta = new Map<string, number>();
-	for (const push of pendingUnseenFlagPushes) {
-		const adjustment = push.operation === "add" ? -1 : 1;
-		unseenCountDelta.set(
-			push.mailboxId,
-			(unseenCountDelta.get(push.mailboxId) ?? 0) + adjustment,
-		);
-	}
-
-	return mailboxes.map((mailbox) => {
-		const messageAdjustment = messageCountDelta.get(mailbox.mailboxId);
-		const unseenAdjustment = unseenCountDelta.get(mailbox.mailboxId);
-		if (!messageAdjustment && !unseenAdjustment) return mailbox;
-		return {
-			...mailbox,
-			messageCount: messageAdjustment
-				? Math.max(0, mailbox.messageCount + messageAdjustment)
-				: mailbox.messageCount,
-			unseenCount: unseenAdjustment
-				? Math.max(0, mailbox.unseenCount + unseenAdjustment)
-				: mailbox.unseenCount,
-		};
-	});
-};
+export declare const applyPendingMoveCountPrediction: (mailboxes: readonly MailboxItem[], pendingMoves: readonly PendingPlacementMove[], pendingUnseenFlagPushes?: readonly PendingUnseenFlagPush[]) => MailboxItem[];

package/dist/src/derive/pendingMoveCounts.js

@@ -0,0 +1,53 @@
+/**
+ * Adjusts `messageCount` and `unseenCount` on a set of mailboxes to reflect
+ * every pending placement move (issue #1271) and pending `\Seen` flag push
+ * (issue #1273): a prediction applied at READ TIME, never written back to
+ * storage (epic #1281 invariant 4). Stored counts are refreshed only by
+ * mailbox-sync re-reading IMAP.
+ *
+ * - A pending move has already relocated the message locally
+ *   (`ThreadMessage.mailboxId`), so its destination folder's live listing
+ *   outnumbers the stored `messageCount` by one until the marker confirms
+ *   and a resync catches up.
+ * - A pending `\Seen` push has already flipped `ThreadMessage.isRead`
+ *   locally: `add` (marked read) means the stored `unseenCount` is one HIGH
+ *   until the push confirms; `remove` (marked unread) means it is one LOW.
+ *   Only `\Seen` markers carry read/unread state — a pending `\Flagged`
+ *   (star) marker never adjusts either count, same reasoning the placement
+ *   move prediction already applies to its own scope.
+ *
+ * Pure: takes the mailboxes and the pending markers as plain input, returns a
+ * new array. Never mutates its arguments.
+ */
+export const applyPendingMoveCountPrediction = (mailboxes, pendingMoves, pendingUnseenFlagPushes = []) => {
+    if (pendingMoves.length === 0 && pendingUnseenFlagPushes.length === 0) {
+        return [...mailboxes];
+    }
+    const messageCountDelta = new Map();
+    for (const move of pendingMoves) {
+        if (move.sourceMailboxId === move.destinationMailboxId)
+            continue;
+        messageCountDelta.set(move.sourceMailboxId, (messageCountDelta.get(move.sourceMailboxId) ?? 0) - 1);
+        messageCountDelta.set(move.destinationMailboxId, (messageCountDelta.get(move.destinationMailboxId) ?? 0) + 1);
+    }
+    const unseenCountDelta = new Map();
+    for (const push of pendingUnseenFlagPushes) {
+        const adjustment = push.operation === "add" ? -1 : 1;
+        unseenCountDelta.set(push.mailboxId, (unseenCountDelta.get(push.mailboxId) ?? 0) + adjustment);
+    }
+    return mailboxes.map((mailbox) => {
+        const messageAdjustment = messageCountDelta.get(mailbox.mailboxId);
+        const unseenAdjustment = unseenCountDelta.get(mailbox.mailboxId);
+        if (!messageAdjustment && !unseenAdjustment)
+            return mailbox;
+        return {
+            ...mailbox,
+            messageCount: messageAdjustment
+                ? Math.max(0, mailbox.messageCount + messageAdjustment)
+                : mailbox.messageCount,
+            unseenCount: unseenAdjustment
+                ? Math.max(0, mailbox.unseenCount + unseenAdjustment)
+                : mailbox.unseenCount,
+        };
+    });
+};