@remit/mailbox-service 0.0.112 → 0.0.113

package/dist/message-category.d.ts

@@ -0,0 +1,51 @@
+import type { IThreadMessageRepository, ThreadMessageItem } from "@remit/data-ports";
+export type MessageCategoryValue = ThreadMessageItem["category"];
+/**
+ * RFC 034 Decision 3.1: `Message.category` is written once and never mutated
+ * after — RFC 030's message-list GSI sort key depends on it never churning.
+ * "Already decided" is any real category, so a message that carries one is
+ * never re-categorized by a re-entrant pass.
+ *
+ * `uncategorized` fails this test whether or not the classifier has run, which
+ * is deliberate: this asks what the row holds, not what was done to it. Whether
+ * the classifier has run is {@link Message.classificationState}, and it is the
+ * skip guard in `BodySyncService.syncBodies` — not this one — that keeps a
+ * declined message from being examined twice.
+ */
+export declare const hasDecidedCategory: (category: MessageCategoryValue | undefined) => boolean;
+export interface MessageCategoryDenormalizeDeps {
+    threadMessageService: Pick<IThreadMessageRepository, "findAllByMessageId" | "update">;
+}
+export interface MessageCategoryDenormalizeInput {
+    category: MessageCategoryValue;
+    snippet?: string;
+    listId?: string;
+}
+/**
+ * Write a message's category (and, when the caller has them, its snippet and
+ * `List-Id`) onto every ThreadMessage row that indexes it. The thread row is
+ * what the message list renders and what the category filter matches, so it
+ * must never disagree with the Message row it mirrors.
+ *
+ * More than one row per messageId is schema-legal but not normally produced,
+ * and this iterates for the same reason `message-move.ts` does (see the model
+ * stated at its `deleteThreadMessagesForMessage`): the key permits it and
+ * nothing enforces otherwise. It is NOT the second mailbox a message appears
+ * in — `deriveMessageId` and `deriveThreadMessageId` are both
+ * mailbox-independent, so INBOX and Archive resolve to one row, and a copy
+ * gets its own messageId. The reachable case is thread-root drift: the same
+ * message re-saved under different `References`, which mints a second
+ * threadId and so a second row. Iterating is therefore hardening against a
+ * legal state, not a repair for one the sync path manufactures, which is why
+ * the tree's other single-row `messageId` lookups are correct as they stand.
+ * `flag-queue.ts` iterates the same list.
+ *
+ * Rows are looked up by messageId, so this does not depend on the RFC822
+ * Message-ID header — a headerless message still gets denormalized, matching
+ * the unconditional Message.category write. The composite set is built per
+ * row, never reused: `mailboxId` and `isRead` can differ between two rows for
+ * one message, and it is passed at all so that a future key-attribute
+ * addition touching the lsi3/lsi4/lsi5/gsi2 sort keys keeps the index rows
+ * consistent.
+ */
+export declare const denormalizeMessageCategory: (deps: MessageCategoryDenormalizeDeps, accountConfigId: string, messageId: string, update: MessageCategoryDenormalizeInput) => Promise<void>;

package/{src/message-category.ts → dist/message-category.js}

@@ -1,12 +1,5 @@
-import type {
-	IThreadMessageRepository,
-	ThreadMessageItem,
-} from "@remit/data-ports";
 import { NotFoundError } from "@remit/data-ports/errors";
 import { MessageCategory } from "@remit/domain-enums";
-
-export type MessageCategoryValue = ThreadMessageItem["category"];
-
 /**
  * RFC 034 Decision 3.1: `Message.category` is written once and never mutated
  * after — RFC 030's message-list GSI sort key depends on it never churning.
@@ -19,37 +12,15 @@ export type MessageCategoryValue = ThreadMessageItem["category"];
  * skip guard in `BodySyncService.syncBodies` — not this one — that keeps a
  * declined message from being examined twice.
  */
-export const hasDecidedCategory = (
-	category: MessageCategoryValue | undefined,
-): boolean =>
-	category !== undefined && category !== MessageCategory.uncategorized;
-
-export interface MessageCategoryDenormalizeDeps {
-	threadMessageService: Pick<
-		IThreadMessageRepository,
-		"findAllByMessageId" | "update"
-	>;
-}
-
-export interface MessageCategoryDenormalizeInput {
-	category: MessageCategoryValue;
-	snippet?: string;
-	listId?: string;
-}
-
+export const hasDecidedCategory = (category) => category !== undefined && category !== MessageCategory.uncategorized;
 /**
  * A row is skipped only when every field the denormalization would write
  * already matches. `snippet` and `listId` are absent from the update when the
  * message has neither, and an absent field is not a mismatch.
  */
-const alreadyDenormalized = (
-	row: ThreadMessageItem,
-	update: MessageCategoryDenormalizeInput,
-): boolean =>
-	row.category === update.category &&
-	(update.snippet === undefined || row.snippet === update.snippet) &&
-	(update.listId === undefined || row.listId === update.listId);
-
+const alreadyDenormalized = (row, update) => row.category === update.category &&
+    (update.snippet === undefined || row.snippet === update.snippet) &&
+    (update.listId === undefined || row.listId === update.listId);
 /**
  * Write a message's category (and, when the caller has them, its snippet and
  * `List-Id`) onto every ThreadMessage row that indexes it. The thread row is
@@ -77,42 +48,28 @@ const alreadyDenormalized = (
  * addition touching the lsi3/lsi4/lsi5/gsi2 sort keys keeps the index rows
  * consistent.
  */
-export const denormalizeMessageCategory = async (
-	deps: MessageCategoryDenormalizeDeps,
-	accountConfigId: string,
-	messageId: string,
-	update: MessageCategoryDenormalizeInput,
-): Promise<void> => {
-	const rows = await deps.threadMessageService.findAllByMessageId(
-		accountConfigId,
-		messageId,
-	);
-	if (rows.length === 0) {
-		throw new NotFoundError(`ThreadMessage not found for message ${messageId}`);
-	}
-
-	const written = {
-		category: update.category,
-		...(update.snippet ? { snippet: update.snippet } : {}),
-		...(update.listId ? { listId: update.listId } : {}),
-	};
-
-	for (const row of rows) {
-		if (alreadyDenormalized(row, written)) continue;
-		await deps.threadMessageService.update(
-			accountConfigId,
-			row.threadMessageId,
-			written,
-			{
-				composites: {
-					sentDate: row.sentDate,
-					mailboxId: row.mailboxId,
-					isRead: row.isRead,
-					isDeleted: row.isDeleted,
-					hasStars: row.hasStars,
-					hasAttachment: row.hasAttachment,
-				},
-			},
-		);
-	}
+export const denormalizeMessageCategory = async (deps, accountConfigId, messageId, update) => {
+    const rows = await deps.threadMessageService.findAllByMessageId(accountConfigId, messageId);
+    if (rows.length === 0) {
+        throw new NotFoundError(`ThreadMessage not found for message ${messageId}`);
+    }
+    const written = {
+        category: update.category,
+        ...(update.snippet ? { snippet: update.snippet } : {}),
+        ...(update.listId ? { listId: update.listId } : {}),
+    };
+    for (const row of rows) {
+        if (alreadyDenormalized(row, written))
+            continue;
+        await deps.threadMessageService.update(accountConfigId, row.threadMessageId, written, {
+            composites: {
+                sentDate: row.sentDate,
+                mailboxId: row.mailboxId,
+                isRead: row.isRead,
+                isDeleted: row.isDeleted,
+                hasStars: row.hasStars,
+                hasAttachment: row.hasAttachment,
+            },
+        });
+    }
 };

package/dist/message-move.d.ts

@@ -0,0 +1,285 @@
+import { type FifoQueueProducer, type IAddressRepository, type IMailboxRepository, type IMailboxSpecialUseRepository, type IMessageRepository, type IThreadMessageRepository } from "@remit/data-ports";
+import { FolderRoleUnresolvedError } from "@remit/data-ports/errors";
+import { type RoleResolution, type TrashAssuranceLevel } from "@remit/data-ports/folder-role";
+import { MUTATION_EVENT_SCHEMA_VERSION } from "@remit/data-ports/mutation-events";
+/**
+ * What a delete batch did not claim. A row whose placement changed between the
+ * read that decided this delete and the mark that recorded it belongs to
+ * whoever changed it (docs/architecture/imap-mutations.md R3), so this delete
+ * leaves it alone — and says which, because the client removed it optimistically
+ * and a row that reappears unexplained is a failure the user cannot act on.
+ */
+export interface DeleteMessagesOutcome {
+    refusedMessageIds: string[];
+}
+/**
+ * Event types for message move/delete operations.
+ * These match the worker event types in remit-imap-worker/events.ts.
+ */
+export interface MessageDeleteEvent {
+    type: "MESSAGE_DELETE";
+    schemaVersion: typeof MUTATION_EVENT_SCHEMA_VERSION;
+    eventId: string;
+    timestamp: number;
+    accountId: string;
+    messageId: string;
+    mailboxId: string;
+    mailboxPath: string;
+    uid: number;
+    operation: "move_to_trash" | "permanent_delete";
+    destinationMailboxId?: string;
+    destinationMailboxPath?: string;
+}
+export interface MessageMoveEvent {
+    type: "MESSAGE_MOVE";
+    eventId: string;
+    timestamp: number;
+    accountId: string;
+    messageId: string;
+    sourceMailboxId: string;
+    sourceMailboxPath: string;
+    destinationMailboxId: string;
+    destinationMailboxPath: string;
+    uid: number;
+}
+export interface EmptyTrashEvent {
+    type: "EMPTY_TRASH";
+    schemaVersion: typeof MUTATION_EVENT_SCHEMA_VERSION;
+    eventId: string;
+    timestamp: number;
+    accountId: string;
+    trashMailboxId: string;
+    trashMailboxPath: string;
+    /** The folder's UIDVALIDITY at consent time; the worker re-checks it. */
+    trashUidValidity: number;
+}
+export interface MessageCopyEvent {
+    type: "MESSAGE_COPY";
+    eventId: string;
+    timestamp: number;
+    accountId: string;
+    sourceMessageId: string;
+    newMessageId: string;
+    sourceMailboxId: string;
+    sourceMailboxPath: string;
+    destinationMailboxId: string;
+    destinationMailboxPath: string;
+    uid: number;
+}
+export type MessageMoveQueueEvent = MessageDeleteEvent | MessageMoveEvent | EmptyTrashEvent | MessageCopyEvent;
+/**
+ * Logger interface
+ */
+export interface MessageMoveLogger {
+    info(obj: Record<string, unknown>, msg: string): void;
+    error(obj: Record<string, unknown>, msg: string): void;
+    warn?(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * Configuration for MessageMoveService
+ */
+export interface MessageMoveConfig {
+    messageService: IMessageRepository;
+    mailboxService: IMailboxRepository;
+    mailboxSpecialUseService: IMailboxSpecialUseRepository;
+    threadMessageService: IThreadMessageRepository;
+    addressService: IAddressRepository;
+    queue: FifoQueueProducer<MessageMoveQueueEvent>;
+    logger?: MessageMoveLogger;
+    moveSettleTimeoutMs?: number;
+    moveSettlePollMs?: number;
+}
+/**
+ * The account resolves no Trash folder, so a move-to-Trash delete has nowhere
+ * to put the mail and an Empty Trash has nothing it may empty. A designed,
+ * user-facing outcome carrying its own text and a 409 the backend returns
+ * verbatim: the absence of a Trash folder is a blocker the user resolves by
+ * appointing one, never a licence to expunge.
+ */
+export declare class NoTrashMailboxError extends FolderRoleUnresolvedError {
+    name: string;
+    constructor(accountId: string);
+}
+/**
+ * The folder the user appointed as Trash is gone from the server. Distinct from
+ * having no Trash at all: there is a decision on file, and the repair is to
+ * point it at a folder that exists — not to let reader pick one instead.
+ */
+export declare class StaleTrashAppointmentError extends FolderRoleUnresolvedError {
+    name: string;
+    constructor(accountId: string);
+}
+/**
+ * A folder resolves as Trash by its name alone. Enough to move mail into,
+ * never enough to expunge — raised by Empty Trash and by a delete that would
+ * expunge a message already sitting in that folder.
+ */
+export declare class UnconfirmedTrashMailboxError extends FolderRoleUnresolvedError {
+    name: string;
+    constructor(accountId: string);
+}
+/**
+ * The Trash folder a verb may act on at the assurance it demands, or the coded
+ * refusal naming which of the three reasons stopped it. Every Trash gate goes
+ * through here — the delete and the expunge — so no two of them can tell a
+ * user different things about the same account.
+ */
+export declare const requireTrashMailbox: <T>(resolution: RoleResolution<T>, level: TrashAssuranceLevel, accountId: string) => T;
+/**
+ * Options for delete operations
+ */
+export interface DeleteOptions {
+    /** Move to Trash instead of permanent delete. Default: true */
+    toTrash?: boolean;
+    /** Permanently delete even if in Trash. Default: false */
+    permanent?: boolean;
+}
+/**
+ * Service for moving, copying, and deleting messages.
+ *
+ * Implements optimistic local-first pattern:
+ * 1. Updates local state immediately (Message + ThreadMessage)
+ * 2. Enqueues event to SQS for worker to sync to IMAP
+ *
+ * Following RFC 016 for message deletion and moving.
+ */
+export declare class MessageMoveService {
+    private messageService;
+    private mailboxService;
+    private mailboxSpecialUseService;
+    private threadMessageService;
+    private addressService;
+    private queue;
+    private log;
+    private moveSettleTimeoutMs;
+    private moveSettlePollMs;
+    constructor(config: MessageMoveConfig);
+    /**
+     * Delete a message. By default moves to Trash.
+     *
+     * @param messageId - Message to delete
+     * @param accountId - Account ID
+     * @param options - Delete options (toTrash, permanent)
+     */
+    deleteMessage: (accountConfigId: string, messageId: string, accountId: string, options?: DeleteOptions) => Promise<DeleteMessagesOutcome>;
+    /**
+     * Delete multiple messages using batch operations.
+     * By default moves to Trash, unless permanent is specified or already in Trash.
+     *
+     * @param messageIds - Messages to delete
+     * @param accountId - Account ID
+     * @param options - Delete options (toTrash, permanent)
+     */
+    deleteMessages: (accountConfigId: string, messageIds: string[], accountId: string, options?: DeleteOptions) => Promise<DeleteMessagesOutcome>;
+    /**
+     * Move a message to another mailbox.
+     *
+     * Waits, never reconciles (imap-mutations R2): the folder and uid go to the
+     * server as one pair, and once the worker has moved the destination's own
+     * message at that uid there is no reference left to repair. The person is
+     * looking at the result, so blocking for the sub-second a move takes is the
+     * cheap half; on timeout the move refuses ahead of any local write.
+     *
+     * @param messageId - Message to move
+     * @param destinationMailboxId - Destination mailbox ID
+     * @param accountId - Account ID
+     */
+    moveMessage: (accountConfigId: string, messageId: string, destinationMailboxId: string, accountId: string) => Promise<void>;
+    private moveSettledMessage;
+    /**
+     * Move multiple messages to another mailbox.
+     *
+     * @param messageIds - Messages to move
+     * @param destinationMailboxId - Destination mailbox ID
+     * @param accountId - Account ID
+     */
+    moveMessages: (accountConfigId: string, messageIds: string[], destinationMailboxId: string, accountId: string) => Promise<void>;
+    /**
+     * Copy a message to another mailbox.
+     * Creates a new message record locally and enqueues IMAP COPY.
+     *
+     * @param messageId - Message to copy
+     * @param destinationMailboxId - Destination mailbox ID
+     * @param accountId - Account ID
+     * @returns The new message ID for the copy
+     */
+    copyMessage: (accountConfigId: string, messageId: string, destinationMailboxId: string, accountId: string) => Promise<string>;
+    private copySettledMessage;
+    /**
+     * Copy multiple messages to another mailbox.
+     *
+     * @param messageIds - Messages to copy
+     * @param destinationMailboxId - Destination mailbox ID
+     * @param accountId - Account ID
+     * @returns Array of new message IDs for the copies
+     */
+    copyMessages: (accountConfigId: string, messageIds: string[], destinationMailboxId: string, accountId: string) => Promise<string[]>;
+    /**
+     * Restore a message from Trash to its original mailbox.
+     *
+     * @param messageId - Message to restore
+     * @param accountId - Account ID
+     */
+    restoreMessage: (accountConfigId: string, messageId: string, accountId: string) => Promise<void>;
+    /**
+     * Empty the Trash mailbox: an EXPUNGE of everything in it, with no undo.
+     *
+     * Demands confirmed evidence: the folder the user appointed or the one the
+     * server flagged \Trash — never one that merely reads like a trash folder,
+     * and never the fallback behind an appointment that went missing. A user
+     * with an ordinary folder called `Deleted` would otherwise lose its contents
+     * permanently. Each of the three ways that evidence can be absent refuses
+     * under its own reason, so the surface can name the remedy instead of
+     * offering a silent no-op.
+     *
+     * Reports the rows it marked, read once here, so the number the caller shows
+     * a user is the number this operation acted on. Pressed twice before the
+     * worker runs it re-marks the same rows and reports the same number: the
+     * folder really does still hold them, and the second expunge finds nothing
+     * to do.
+     */
+    emptyTrash: (accountConfigId: string, accountId: string) => Promise<{
+        deletedCount: number;
+    }>;
+    private refusePlacement;
+    private settledPlacement;
+    /**
+     * Settle a whole batch before any of it is acted on, so one unsettled row
+     * refuses the batch whole rather than leaving part of it expunged, and the
+     * batch's total wait is one row's ceiling rather than the sum across it.
+     */
+    private settledPlacements;
+    /**
+     * Update ThreadMessage for move operations.
+     * Updates mailboxId and optionally isDeleted.
+     */
+    private updateThreadMessageForMove;
+    /**
+     * Delete every ThreadMessage row that points at this messageId.
+     *
+     * A row is keyed by (threadId, messageId), so this is one row in practice —
+     * a message filed in several folders keeps a single row, because its
+     * messageId is derived from the Message-ID header and not from the mailbox.
+     * The query stays a list because the key permits more than one thread per
+     * message and nothing enforces otherwise.
+     *
+     * Deleting up-front in the permanent-delete optimistic step prevents stale
+     * rows from leaking into mailbox listings while IMAP catches up (#212).
+     */
+    private deleteThreadMessagesForMessage;
+    /**
+     * Update ThreadMessage.isDeleted flag only.
+     */
+    private updateThreadMessageDeleted;
+    /**
+     * Enqueue a message move/delete event, grouped by accountId so events for
+     * different accounts can be processed in parallel.
+     */
+    private enqueueEvent;
+    /**
+     * Enqueue multiple events in batches of at most {@link QUEUE_BATCH_LIMIT}.
+     */
+    private enqueueEventsBatch;
+    private sendEventsBatch;
+    private handBackUnsentMove;
+}