@remit/mailbox-service 0.0.111 → 0.0.113

package/{src/mailbox-presence.ts → dist/mailbox-presence.js}

@@ -1,9 +1,5 @@
-import type { IMailboxRepository, MailboxItem } from "@remit/data-ports";
 import { MailboxSyncStatus } from "@remit/domain-enums";
-
-export const isNotFoundError = (error: unknown): boolean =>
-	error instanceof Error && error.name === "NotFoundError";
-
+export const isNotFoundError = (error) => error instanceof Error && error.name === "NotFoundError";
 /**
  * Every state a mailbox row can carry, for a transition whose caller decided
  * against none of them.
@@ -18,12 +14,11 @@ export const isNotFoundError = (error: unknown): boolean =>
  * recorded target for the settle.
  */
 export const EVERY_MAILBOX_STATE = [
-	MailboxSyncStatus.synced,
-	MailboxSyncStatus.pending,
-	MailboxSyncStatus.failed,
-	MailboxSyncStatus.deleting,
-] as const;
-
+    MailboxSyncStatus.synced,
+    MailboxSyncStatus.pending,
+    MailboxSyncStatus.failed,
+    MailboxSyncStatus.deleting,
+];
 /**
  * Whether a folder mutation is in flight, so nothing else may touch the folder
  * over IMAP.
@@ -57,24 +52,18 @@ export const EVERY_MAILBOX_STATE = [
  * Mailbox management is judged differently — it is what establishes and removes
  * the folder, so it terminates on a not-found row alone.
  */
-export const isFolderMutationInFlight = (
-	mailbox: Pick<MailboxItem, "syncStatus">,
-): boolean =>
-	mailbox.syncStatus === MailboxSyncStatus.pending ||
-	mailbox.syncStatus === MailboxSyncStatus.deleting;
-
+export const isFolderMutationInFlight = (mailbox) => mailbox.syncStatus === MailboxSyncStatus.pending ||
+    mailbox.syncStatus === MailboxSyncStatus.deleting;
 /** {@link isFolderMutationInFlight} for a mailbox that has to be read first, an absent row included. */
-export const isMailboxMutationInFlight = async (
-	mailboxService: Pick<IMailboxRepository, "get">,
-	accountId: string,
-	mailboxId: string,
-): Promise<boolean> => {
-	const mailbox = await mailboxService
-		.get(accountId, mailboxId)
-		.catch((error: unknown) => {
-			if (isNotFoundError(error)) return undefined;
-			throw error;
-		});
-	if (!mailbox) return true;
-	return isFolderMutationInFlight(mailbox);
+export const isMailboxMutationInFlight = async (mailboxService, accountId, mailboxId) => {
+    const mailbox = await mailboxService
+        .get(accountId, mailboxId)
+        .catch((error) => {
+        if (isNotFoundError(error))
+            return undefined;
+        throw error;
+    });
+    if (!mailbox)
+        return true;
+    return isFolderMutationInFlight(mailbox);
 };

package/dist/mailbox-queue.d.ts

@@ -0,0 +1,126 @@
+import type { CreateMailboxInput, CreateMailboxResult, FifoQueueProducer, IMailboxRepository, MailboxItem } from "@remit/data-ports";
+/**
+ * MAILBOX_CREATE event structure (matches remit-imap-worker/events.ts)
+ */
+export interface MailboxCreateEvent {
+    type: "MAILBOX_CREATE";
+    eventId: string;
+    timestamp: number;
+    accountId: string;
+    mailboxId: string;
+    path: string;
+    subscribe?: boolean;
+}
+/**
+ * MAILBOX_RENAME event structure (matches remit-imap-worker/events.ts)
+ */
+export interface MailboxRenameEvent {
+    type: "MAILBOX_RENAME";
+    eventId: string;
+    timestamp: number;
+    accountId: string;
+    mailboxId: string;
+    oldPath: string;
+    newPath: string;
+}
+/**
+ * MAILBOX_DELETE event structure (matches remit-imap-worker/events.ts)
+ */
+export interface MailboxDeleteEvent {
+    type: "MAILBOX_DELETE";
+    eventId: string;
+    timestamp: number;
+    accountId: string;
+    mailboxId: string;
+    path: string;
+}
+export type MailboxManagementEvent = MailboxCreateEvent | MailboxRenameEvent | MailboxDeleteEvent;
+/**
+ * Logger interface
+ */
+export interface MailboxQueueLogger {
+    info(obj: Record<string, unknown>, msg: string): void;
+    error(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * Input for creating a mailbox via the queue service
+ */
+export type CreateMailboxQueueInput = Omit<CreateMailboxInput, "syncStatus">;
+/**
+ * Configuration for MailboxQueueService
+ */
+export interface MailboxQueueConfig {
+    mailboxService: IMailboxRepository;
+    queue: FifoQueueProducer<MailboxManagementEvent>;
+    logger?: MailboxQueueLogger;
+}
+/**
+ * Service for mailbox management with automatic IMAP sync queueing.
+ *
+ * Implements optimistic local-first pattern:
+ * 1. Updates local state immediately
+ * 2. Enqueues mailbox management event to SQS for worker to sync to IMAP
+ *
+ * This follows the same pattern as FlagQueueService (RFC 014).
+ */
+export declare class MailboxQueueService {
+    private mailboxService;
+    private queue;
+    private log;
+    constructor(config: MailboxQueueConfig);
+    /**
+     * Create a new mailbox.
+     * Updates local state (with syncStatus=pending) and enqueues IMAP CREATE.
+     *
+     * @param input - The mailbox creation input (without syncStatus)
+     * @param accountId - The account ID for the IMAP sync event
+     * @param subscribe - Whether to subscribe to the mailbox after creation
+     * @returns The created mailbox, or `PathTaken` when the account already has a folder at that path
+     */
+    createMailbox: (input: CreateMailboxQueueInput, accountId: string, subscribe?: boolean) => Promise<CreateMailboxResult>;
+    /**
+     * Record a rename intent over the folder and every descendant, then enqueue
+     * IMAP RENAME.
+     *
+     * The target is recorded, not the path (D2): every row keeps the `fullPath`
+     * the server holds and takes its own rewritten target in `pendingPath`, so a
+     * rename that never lands needs no unwinding — dropping `pendingPath` is the
+     * whole revert — and nothing that resolves a folder path from a row can
+     * resolve one the server does not have.
+     *
+     * @param mailboxId - The mailbox to rename
+     * @param newPath - The path the rename is aiming at
+     * @param accountId - The account ID for the IMAP sync event
+     * @returns The folder that was named, carrying its recorded target
+     */
+    renameMailbox: (mailboxId: string, newPath: string, accountId: string) => Promise<MailboxItem>;
+    /**
+     * The route out of a failed rename or a failed delete that keeps the folder
+     * as it is (T10, T11): the recorded target is dropped and the row settles
+     * back to `synced`. Nothing is enqueued — `fullPath` was never written, so
+     * the server has nothing to undo.
+     *
+     * Reached without new API surface, from a PATCH whose `fullPath` equals the
+     * row's confirmed one. From `synced` it is a no-op; from a state with a
+     * mutation in flight it is a 409, because dismissing an intent that is still
+     * running would leave the settle with no row to write.
+     */
+    dismissMailboxIntent: (mailboxId: string, accountId: string) => Promise<MailboxItem>;
+    /**
+     * Record a delete intent (T7) and enqueue IMAP DELETE.
+     *
+     * The row stays at `deleting` and stays visible until the worker confirms the
+     * server delete and removes it with the folder's mail (D8, D11). The enqueue
+     * happens only after the transition wins, and an enqueue failure stays thrown
+     * — a 500 to the caller, loud — rather than being swallowed or rolled back.
+     *
+     * @param mailboxId - The mailbox to delete
+     * @param accountId - The account ID for the IMAP sync event
+     */
+    deleteMailbox: (mailboxId: string, accountId: string) => Promise<void>;
+    /**
+     * Enqueue a mailbox management event, ordered per account so events for
+     * different accounts can be processed in parallel.
+     */
+    private enqueueEvent;
+}

package/dist/mailbox-queue.js

@@ -0,0 +1,214 @@
+import { randomUUID } from "node:crypto";
+import { NotFoundError } from "@remit/data-ports/errors";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import { INTENT_RECORDABLE_FROM, recordedByRename, refuseContestedIntent, } from "./mailbox-intent.js";
+const noopLogger = {
+    info: () => { },
+    error: () => { },
+};
+/**
+ * Service for mailbox management with automatic IMAP sync queueing.
+ *
+ * Implements optimistic local-first pattern:
+ * 1. Updates local state immediately
+ * 2. Enqueues mailbox management event to SQS for worker to sync to IMAP
+ *
+ * This follows the same pattern as FlagQueueService (RFC 014).
+ */
+export class MailboxQueueService {
+    mailboxService;
+    queue;
+    log;
+    constructor(config) {
+        this.mailboxService = config.mailboxService;
+        this.queue = config.queue;
+        this.log = config.logger ?? noopLogger;
+    }
+    /**
+     * Create a new mailbox.
+     * Updates local state (with syncStatus=pending) and enqueues IMAP CREATE.
+     *
+     * @param input - The mailbox creation input (without syncStatus)
+     * @param accountId - The account ID for the IMAP sync event
+     * @param subscribe - Whether to subscribe to the mailbox after creation
+     * @returns The created mailbox, or `PathTaken` when the account already has a folder at that path
+     */
+    createMailbox = async (input, accountId, subscribe) => {
+        const created = await this.mailboxService.create({
+            ...input,
+            syncStatus: MailboxSyncStatus.pending,
+        });
+        if (created.outcome === "PathTaken")
+            return created;
+        const { mailbox } = created;
+        this.log.info({ mailboxId: mailbox.mailboxId, path: mailbox.fullPath }, "Created mailbox (local)");
+        // Enqueue IMAP sync
+        await this.enqueueEvent({
+            type: "MAILBOX_CREATE",
+            eventId: randomUUID(),
+            timestamp: Date.now(),
+            accountId,
+            mailboxId: mailbox.mailboxId,
+            path: mailbox.fullPath,
+            subscribe,
+        });
+        return created;
+    };
+    /**
+     * Record a rename intent over the folder and every descendant, then enqueue
+     * IMAP RENAME.
+     *
+     * The target is recorded, not the path (D2): every row keeps the `fullPath`
+     * the server holds and takes its own rewritten target in `pendingPath`, so a
+     * rename that never lands needs no unwinding — dropping `pendingPath` is the
+     * whole revert — and nothing that resolves a folder path from a row can
+     * resolve one the server does not have.
+     *
+     * @param mailboxId - The mailbox to rename
+     * @param newPath - The path the rename is aiming at
+     * @param accountId - The account ID for the IMAP sync event
+     * @returns The folder that was named, carrying its recorded target
+     */
+    renameMailbox = async (mailboxId, newPath, accountId) => {
+        // Get current mailbox to capture old path
+        const mailbox = await this.mailboxService.get(accountId, mailboxId);
+        const oldPath = mailbox.fullPath;
+        // One intent over the folder and every descendant, in one batch:
+        // IMAP RENAME moves the subtree in one command, so a partially recorded
+        // rename is the state that produced today's phantom rows (D6). A
+        // descendant already mid-mutation refuses the whole rename.
+        const written = await this.mailboxService.transitionSubtree(accountId, mailboxId, {
+            from: INTENT_RECORDABLE_FROM,
+            to: MailboxSyncStatus.pending,
+            newPath,
+        });
+        if (!written) {
+            return refuseContestedIntent(this.mailboxService, accountId, mailboxId, "subtree");
+        }
+        const updated = written.find((row) => row.mailboxId === mailboxId);
+        if (!updated)
+            throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
+        this.log.info({
+            accountId,
+            mailboxId,
+            intent: "rename",
+            from: mailbox.syncStatus,
+            to: MailboxSyncStatus.pending,
+            oldPath,
+            newPath,
+            subtreeSize: written.length,
+        }, "Recorded rename intent");
+        // Enqueue IMAP sync
+        await this.enqueueEvent({
+            type: "MAILBOX_RENAME",
+            eventId: randomUUID(),
+            timestamp: Date.now(),
+            accountId,
+            mailboxId,
+            oldPath,
+            newPath,
+        });
+        return updated;
+    };
+    /**
+     * The route out of a failed rename or a failed delete that keeps the folder
+     * as it is (T10, T11): the recorded target is dropped and the row settles
+     * back to `synced`. Nothing is enqueued — `fullPath` was never written, so
+     * the server has nothing to undo.
+     *
+     * Reached without new API surface, from a PATCH whose `fullPath` equals the
+     * row's confirmed one. From `synced` it is a no-op; from a state with a
+     * mutation in flight it is a 409, because dismissing an intent that is still
+     * running would leave the settle with no row to write.
+     */
+    dismissMailboxIntent = async (mailboxId, accountId) => {
+        const current = await this.mailboxService.get(accountId, mailboxId);
+        if (current.syncStatus === MailboxSyncStatus.synced)
+            return current;
+        if (current.syncStatus !== MailboxSyncStatus.failed) {
+            return refuseContestedIntent(this.mailboxService, accountId, mailboxId, "folder");
+        }
+        // A failed rename was recorded over a subtree, so it is dismissed over the
+        // same one. A failed delete carries no target and was recorded on the
+        // folder alone, so there is nothing else to clear.
+        const target = current.pendingPath;
+        const alsoRecorded = target === undefined
+            ? []
+            : (await this.mailboxService.findBySyncStatus(accountId, MailboxSyncStatus.failed)).filter((row) => row.mailboxId !== mailboxId &&
+                recordedByRename(row, current.fullPath, target, current.hierarchyDelimiter));
+        let dismissed;
+        // The named folder first, so a caller always gets back the row it asked
+        // about. Each write carries its own predicate, so a row somebody else
+        // moved between the read and the write is skipped, not overwritten (D3).
+        for (const row of [current, ...alsoRecorded]) {
+            const written = await this.mailboxService.transition(accountId, row.mailboxId, {
+                from: [MailboxSyncStatus.failed],
+                wherePendingPath: row.pendingPath ?? null,
+                to: MailboxSyncStatus.synced,
+            });
+            if (row.mailboxId === mailboxId)
+                dismissed = written ?? undefined;
+            this.log.info({
+                accountId,
+                mailboxId: row.mailboxId,
+                intent: "dismiss",
+                from: MailboxSyncStatus.failed,
+                to: MailboxSyncStatus.synced,
+                outcome: written ? "settled" : "superseded",
+            }, "Dismissed folder intent");
+        }
+        if (dismissed)
+            return dismissed;
+        // The row moved between the read and its write. Re-read rather than
+        // reporting a dismissal that did not happen.
+        return this.mailboxService.get(accountId, mailboxId);
+    };
+    /**
+     * Record a delete intent (T7) and enqueue IMAP DELETE.
+     *
+     * The row stays at `deleting` and stays visible until the worker confirms the
+     * server delete and removes it with the folder's mail (D8, D11). The enqueue
+     * happens only after the transition wins, and an enqueue failure stays thrown
+     * — a 500 to the caller, loud — rather than being swallowed or rolled back.
+     *
+     * @param mailboxId - The mailbox to delete
+     * @param accountId - The account ID for the IMAP sync event
+     */
+    deleteMailbox = async (mailboxId, accountId) => {
+        // Get current mailbox to capture path
+        const mailbox = await this.mailboxService.get(accountId, mailboxId);
+        const recorded = await this.mailboxService.transition(accountId, mailboxId, { from: INTENT_RECORDABLE_FROM, to: MailboxSyncStatus.deleting });
+        if (!recorded) {
+            await refuseContestedIntent(this.mailboxService, accountId, mailboxId, "folder");
+        }
+        this.log.info({
+            accountId,
+            mailboxId,
+            intent: "delete",
+            from: mailbox.syncStatus,
+            to: MailboxSyncStatus.deleting,
+            path: mailbox.fullPath,
+        }, "Recorded delete intent");
+        // Enqueue IMAP sync
+        await this.enqueueEvent({
+            type: "MAILBOX_DELETE",
+            eventId: randomUUID(),
+            timestamp: Date.now(),
+            accountId,
+            mailboxId,
+            path: mailbox.fullPath,
+        });
+    };
+    /**
+     * Enqueue a mailbox management event, ordered per account so events for
+     * different accounts can be processed in parallel.
+     */
+    enqueueEvent = async (event) => {
+        await this.queue.send({
+            body: event,
+            groupId: event.accountId,
+            deduplicationId: `${event.type}:${event.mailboxId}:${event.eventId}`,
+        });
+        this.log.info({ eventId: event.eventId, type: event.type, mailboxId: event.mailboxId }, `Enqueued ${event.type} event`);
+    };
+}

package/dist/mailbox-sync.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Mailbox synchronization service
+ *
+ * Orchestrates syncing mailbox data from IMAP server to the data backend.
+ */
+import type { IMailboxRepository, IMailboxSpecialUseRepository, MailboxItem } from "@remit/data-ports";
+import type { IImapConnection, MailboxSyncResult } from "./types.js";
+/**
+ * Account info needed for mailbox sync
+ */
+export interface SyncAccountInfo {
+    accountId: string;
+}
+/**
+ * Logger interface for MailboxSyncService.
+ *
+ * `info` is reserved here for the three mailbox lifecycle events — created,
+ * updated, deleted — and is the argued exception to `plugins/no-logger-info.grit`
+ * that the rest of this repo writes as a suppression. (The plugin matches the
+ * bare `logger` identifier, so it does not see an injected logger; the reasoning
+ * is written out instead of being silently absent.) A folder disappearing from
+ * someone's mail is destructive and irreversible from this service's side, and
+ * the only record that this process did it is the line it writes. That must not
+ * sit below the default threshold.
+ *
+ * Everything else this service has to say — a special-use flag it synced, a
+ * duplicate folder it skipped — is a routine trace and goes to `debug`.
+ */
+export interface MailboxSyncLogger {
+    info(obj: Record<string, unknown>, msg: string): void;
+    debug(obj: Record<string, unknown>, msg: string): void;
+    error(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * Service for synchronizing mailbox metadata between IMAP and the data backend.
+ */
+export declare class MailboxSyncService {
+    private mailboxService;
+    private specialUseService;
+    private log;
+    constructor(mailboxService: IMailboxRepository, specialUseService: IMailboxSpecialUseRepository, logger: MailboxSyncLogger);
+    /**
+     * Sync all mailboxes for an account from IMAP server
+     *
+     * @param account - Account info including accountId
+     * @param connection - Active IMAP connection
+     */
+    syncMailboxes: (account: SyncAccountInfo, connection: IImapConnection) => Promise<MailboxSyncResult>;
+    /**
+     * Sync metadata for a specific mailbox
+     *
+     * Opens the mailbox to get current UID validity, counts, etc.
+     */
+    syncMailboxMetadata: (accountId: string, mailboxId: string, connection: IImapConnection) => Promise<MailboxItem>;
+    /**
+     * Get all mailboxes for an account, handling pagination
+     */
+    private getAllMailboxes;
+    /**
+     * Fetch all mailboxes from IMAP server across all namespaces.
+     * Uses listMailboxes() to preserve original paths from the server.
+     */
+    private fetchAllMailboxes;
+    /**
+     * Create a new mailbox in the database
+     */
+    private createMailbox;
+    /**
+     * Update an existing mailbox with fresh data.
+     * Skips DB write if nothing has changed.
+     *
+     * @returns The updated mailbox, or null if skipped due to no changes
+     */
+    private updateMailbox;
+    /**
+     * Sync special-use attributes for a mailbox.
+     * Creates entries if they don't exist, updates if changed.
+     */
+    private syncSpecialUseAttributes;
+    /**
+     * Build a map of special-use designations to mailbox paths.
+     * Only includes mailboxes that have the IMAP special-use attribute.
+     */
+    private buildSpecialUseMap;
+    /**
+     * Check if a mailbox is a duplicate special-use folder.
+     * A folder is considered duplicate if:
+     * 1. Its name matches a common special-use folder name (e.g., "Trash")
+     * 2. It does NOT have the IMAP special-use attribute
+     * 3. Another folder already claimed that special-use designation
+     */
+    private isDuplicateSpecialUse;
+}