@remit/backend 0.0.143 → 0.0.145

package/dist/src/handlers/label.js

@@ -0,0 +1,107 @@
+import { ownedAccount } from "@remit/mailbox-service";
+import { unwrap } from "../service/refusal.js";
+/**
+ * Every filter in the account whose action applies this label (issue #26). The
+ * count backs `LabelResponse.filterCount`; the list backs the cascade delete.
+ */
+export const findFiltersForLabel = async (deps, accountConfigId, labelId) => {
+    const filters = await deps.filter.listByAccountConfig(accountConfigId);
+    return filters.filter((filter) => filter.actionLabelId === labelId);
+};
+/**
+ * `filterCount` is computed here, not stored (issue #26) — every other field
+ * comes straight off the `LabelItem` row.
+ */
+const toLabelResponse = (item, filterCount) => ({
+    labelId: item.labelId,
+    accountConfigId: item.accountConfigId,
+    name: item.name,
+    color: item.color,
+    filterCount,
+    createdAt: item.createdAt,
+    updatedAt: item.updatedAt,
+});
+/**
+ * Delete a label and cascade in both directions (issue #26): every filter
+ * whose `actionLabelId` is this label is deleted outright — never left
+ * dangling, never blocking the delete — and every `MessageLabel` row for it is
+ * removed. The label row itself is deleted last so a failure mid-cascade never
+ * leaves the label gone while its filters or applied-to-messages still exist.
+ */
+export const deleteLabelWithCascade = async (deps, accountConfigId, labelId) => {
+    const filters = await findFiltersForLabel(deps, accountConfigId, labelId);
+    for (const filter of filters) {
+        await deps.filter.delete(accountConfigId, filter.filterId);
+    }
+    await deps.messageLabel.removeAllByLabelId(accountConfigId, labelId);
+    await deps.label.delete(accountConfigId, labelId);
+};
+export const LabelOperations = {
+    LabelOperations_listLabels: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { accountId } = context.request.params;
+        const { continuationToken } = context.request.query;
+        const client = ctx.client;
+        const account = await client.account.get(accountId);
+        unwrap(ownedAccount(account, accountConfigId, "read"));
+        const page = await client.label.listPageByAccountConfig(accountConfigId, {
+            continuationToken,
+        });
+        const filters = await client.filter.listByAccountConfig(accountConfigId);
+        const filterCountByLabelId = new Map();
+        for (const filter of filters) {
+            const labelId = filter.actionLabelId;
+            filterCountByLabelId.set(labelId, (filterCountByLabelId.get(labelId) ?? 0) + 1);
+        }
+        return {
+            items: page.items.map((item) => toLabelResponse(item, filterCountByLabelId.get(item.labelId) ?? 0)),
+            continuationToken: page.continuationToken,
+        };
+    },
+    LabelOperations_createLabel: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { accountId } = context.request.params;
+        const input = context.request.requestBody;
+        const client = ctx.client;
+        const account = await client.account.get(accountId);
+        unwrap(ownedAccount(account, accountConfigId, "act"));
+        const label = await client.label.create({
+            accountConfigId,
+            name: input.name,
+            color: input.color,
+        });
+        return toLabelResponse(label, 0);
+    },
+};
+export const LabelDetailOperations = {
+    LabelDetailOperations_getLabel: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { accountId, labelId } = context.request.params;
+        const client = ctx.client;
+        const account = await client.account.get(accountId);
+        unwrap(ownedAccount(account, accountConfigId, "read"));
+        const label = await client.label.get(accountConfigId, labelId);
+        const filters = await findFiltersForLabel(client, accountConfigId, labelId);
+        return toLabelResponse(label, filters.length);
+    },
+    LabelDetailOperations_updateLabel: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { accountId, labelId } = context.request.params;
+        const body = context.request.requestBody;
+        const client = ctx.client;
+        const account = await client.account.get(accountId);
+        unwrap(ownedAccount(account, accountConfigId, "act"));
+        const updated = await client.label.update(accountConfigId, labelId, body);
+        const filters = await findFiltersForLabel(client, accountConfigId, labelId);
+        return toLabelResponse(updated, filters.length);
+    },
+    LabelDetailOperations_deleteLabel: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { accountId, labelId } = context.request.params;
+        const client = ctx.client;
+        const account = await client.account.get(accountId);
+        unwrap(ownedAccount(account, accountConfigId, "act"));
+        await deleteLabelWithCascade(client, accountConfigId, labelId);
+        return { statusCode: 204 };
+    },
+};

package/dist/src/handlers/mailbox-bindings.d.ts

@@ -0,0 +1,41 @@
+import type { IAccountSettingRepository, IFilterRepository, MailboxItem } from "@remit/data-ports";
+import type { CanonicalMailboxRoleValue } from "@remit/data-ports/folder-role";
+/**
+ * What a folder is bound to: the filters that move mail into it, and the
+ * canonical roles it has been appointed to.
+ */
+export interface MailboxBindings {
+    filterNames: string[];
+    roles: CanonicalMailboxRoleValue[];
+}
+/**
+ * `filter.actionMailboxId` has no reverse index, so the filters are listed for
+ * the account config and matched — they are few and per-config, so this is not
+ * a mailbox scan. Role appointments are `account_setting` rows whose *value* is
+ * a mailboxId, which a `mailbox_id` column scan cannot find, so the existing
+ * per-account appointment map answers for them.
+ */
+export declare const loadMailboxBindings: (client: {
+    filter: Pick<IFilterRepository, "listByAccountConfig">;
+    accountSetting: Pick<IAccountSettingRepository, "get">;
+}, accountConfigId: string, accountId: string, mailboxId: string) => Promise<MailboxBindings>;
+/**
+ * Refuse a delete while any durable reference is bound to the folder (D16).
+ *
+ * This is what makes the settled-target rule total: a binding is only created
+ * against a settled folder and only removed by the user, so a `mailboxId` that
+ * names nothing never exists and no reader of a filter's `actionMailboxId` or a
+ * role appointment needs a missing-target branch. It removes code rather than
+ * adding a check.
+ *
+ * The alternatives both cost more than they look. `Filter` has no enabled flag
+ * and its `actionMailboxId` sentinel means "no move action", so clearing the
+ * target silently turns a move-filter into one that does something else;
+ * deleting the user's filters outright is not a decision a folder delete gets
+ * to make.
+ *
+ * The message **names** each binding rather than counting them, because a count
+ * is not actionable — and this fires on ordinary configurations, since pointing
+ * a filter at a folder is what filters are for.
+ */
+export declare const assertNoBindings: (mailbox: Pick<MailboxItem, "fullPath">, bindings: MailboxBindings) => void;

package/dist/src/handlers/mailbox-bindings.js

@@ -0,0 +1,61 @@
+import { FILTER_NO_ACTION } from "@remit/data-ports";
+import { BadRequestError } from "@remit/data-ports/errors";
+import { loadFolderAppointmentsForAccount } from "./folder-role-appointments.js";
+/**
+ * `filter.actionMailboxId` has no reverse index, so the filters are listed for
+ * the account config and matched — they are few and per-config, so this is not
+ * a mailbox scan. Role appointments are `account_setting` rows whose *value* is
+ * a mailboxId, which a `mailbox_id` column scan cannot find, so the existing
+ * per-account appointment map answers for them.
+ */
+export const loadMailboxBindings = async (client, accountConfigId, accountId, mailboxId) => {
+    const [filters, appointments] = await Promise.all([
+        client.filter.listByAccountConfig(accountConfigId),
+        loadFolderAppointmentsForAccount(client.accountSetting, accountConfigId, accountId),
+    ]);
+    const filterNames = filters
+        .filter((filter) => filter.actionMailboxId !== FILTER_NO_ACTION &&
+        filter.actionMailboxId === mailboxId)
+        .map((filter) => filter.name);
+    const roles = [];
+    for (const [role, appointment] of appointments) {
+        if (appointment.mailboxId === mailboxId) {
+            roles.push(role);
+        }
+    }
+    return { filterNames, roles };
+};
+const asList = (items) => items.length === 1
+    ? items[0]
+    : `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+/**
+ * Refuse a delete while any durable reference is bound to the folder (D16).
+ *
+ * This is what makes the settled-target rule total: a binding is only created
+ * against a settled folder and only removed by the user, so a `mailboxId` that
+ * names nothing never exists and no reader of a filter's `actionMailboxId` or a
+ * role appointment needs a missing-target branch. It removes code rather than
+ * adding a check.
+ *
+ * The alternatives both cost more than they look. `Filter` has no enabled flag
+ * and its `actionMailboxId` sentinel means "no move action", so clearing the
+ * target silently turns a move-filter into one that does something else;
+ * deleting the user's filters outright is not a decision a folder delete gets
+ * to make.
+ *
+ * The message **names** each binding rather than counting them, because a count
+ * is not actionable — and this fires on ordinary configurations, since pointing
+ * a filter at a folder is what filters are for.
+ */
+export const assertNoBindings = (mailbox, bindings) => {
+    const clauses = [];
+    if (bindings.filterNames.length > 0) {
+        clauses.push(`the ${bindings.filterNames.length === 1 ? "filter" : "filters"} ${asList(bindings.filterNames.map((name) => `“${name}”`))}`);
+    }
+    if (bindings.roles.length > 0) {
+        clauses.push(`the ${asList(bindings.roles)} ${bindings.roles.length === 1 ? "role" : "roles"}`);
+    }
+    if (clauses.length === 0)
+        return;
+    throw new BadRequestError(`“${mailbox.fullPath}” is used by ${asList(clauses)}.`);
+};

package/dist/src/handlers/mailbox.d.ts

@@ -0,0 +1,23 @@
+import type { RenameMailboxInput } from "@remit/api-openapi-types";
+import type { IAccountSettingRepository, MailboxItem } from "@remit/data-ports";
+import { type FolderPathDeps } from "@remit/mailbox-service";
+import type { MailboxDetailOperationIds, MailboxOperationIds, OperationHandler, TrashOperationIds } from "../types.js";
+/**
+ * The mute flag and the display-name override are user preferences that live
+ * in per-mailbox AccountSetting rows (RFC 032), not on the Mailbox entity.
+ * Pick only those keys from a PATCH body: each follows the same `null` → remove,
+ * value → set, absent/undefined → no-op semantics as UpdateAddressFlagsInput.
+ * The canonical role a folder fills is appointed separately — see
+ * FolderRoleOperations.appointFolderRole (RFC 032 exclusive-folder-appointment).
+ */
+export declare const pickMailboxOverrideChanges: (body: RenameMailboxInput) => {
+    displayNameOverride?: string | null;
+    muted?: RenameMailboxInput["muted"];
+};
+export type MailboxPatchClient = FolderPathDeps & {
+    accountSetting: Pick<IAccountSettingRepository, "get" | "upsert" | "delete">;
+};
+export declare const applyMailboxPatch: (client: MailboxPatchClient, accountConfigId: string, mailboxId: string, accountId: string, body: RenameMailboxInput) => Promise<MailboxItem>;
+export declare const MailboxOperations: Record<MailboxOperationIds, OperationHandler<MailboxOperationIds, "sync">>;
+export declare const MailboxDetailOperations: Record<MailboxDetailOperationIds, OperationHandler<MailboxDetailOperationIds, "sync">>;
+export declare const TrashOperations: Record<TrashOperationIds, OperationHandler<TrashOperationIds, "sync">>;

package/dist/src/handlers/mailbox.js

@@ -0,0 +1,211 @@
+import { BadRequestError, ConflictError } from "@remit/data-ports/errors";
+import { MessageSystemFlag } from "@remit/domain-enums";
+import { changeFolderPath, createFolder, folderInAccount, folderInFlight, ownedAccount, ownedFolder, } from "@remit/mailbox-service";
+import { applyPendingMoveCountPrediction, } from "../derive/pendingMoveCounts.js";
+import { unwrap } from "../service/refusal.js";
+import { applyMailboxOverrideChanges, loadMailboxOverrides, loadMailboxOverridesForConfig, } from "./account-overrides.js";
+import { assertNoBindings, loadMailboxBindings } from "./mailbox-bindings.js";
+/**
+ * The mute flag and the display-name override are user preferences that live
+ * in per-mailbox AccountSetting rows (RFC 032), not on the Mailbox entity.
+ * Pick only those keys from a PATCH body: each follows the same `null` → remove,
+ * value → set, absent/undefined → no-op semantics as UpdateAddressFlagsInput.
+ * The canonical role a folder fills is appointed separately — see
+ * FolderRoleOperations.appointFolderRole (RFC 032 exclusive-folder-appointment).
+ */
+export const pickMailboxOverrideChanges = (body) => {
+    const changes = {};
+    if (Object.hasOwn(body, "displayNameOverride")) {
+        changes.displayNameOverride = body.displayNameOverride;
+    }
+    if (Object.hasOwn(body, "muted")) {
+        changes.muted = body.muted;
+    }
+    return changes;
+};
+// Overrides land first and independently, so an override-only PATCH never
+// touches the folder's mutation state.
+export const applyMailboxPatch = async (client, accountConfigId, mailboxId, accountId, body) => {
+    const { fullPath } = body;
+    const applyOverrides = async () => {
+        const changes = pickMailboxOverrideChanges(body);
+        if (Object.keys(changes).length === 0)
+            return;
+        await applyMailboxOverrideChanges(client.accountSetting, accountConfigId, mailboxId, changes);
+    };
+    if (!fullPath) {
+        const folder = unwrap(await ownedFolder(client, accountConfigId, accountId, mailboxId));
+        await applyOverrides();
+        return folder;
+    }
+    const { outcome, mailbox } = unwrap(await changeFolderPath(client, accountConfigId, {
+        accountId,
+        mailboxId,
+        fullPath,
+    }));
+    await applyOverrides();
+    if (outcome === "AlreadyRecorded") {
+        throw new ConflictError(folderInFlight(mailbox));
+    }
+    return mailbox;
+};
+/**
+ * Every pending placement move (issue #1271) for an account, on whichever
+ * backend is active (`RemitClient.placementMove` is present on both — see
+ * `create-remit-client.ts`). Read-only; feeds
+ * `applyPendingMoveCountPrediction`'s read-time adjustment only, never mutates
+ * stored counts (epic #1281 invariant 4). Markers are written by the
+ * imap-worker bulk sync path through `RemitClient.placementMove` on every
+ * backend, so this is a real signal on the self-host stack too.
+ */
+const loadPendingMoves = (client, accountId) => client.placementMove.listByAccountId(accountId);
+/**
+ * Every pending `\Seen` flag-push marker (issue #1273) for an account —
+ * `\Flagged` (star) markers are excluded, since only read/unread state feeds
+ * `unseenCount`'s prediction. `RemitClient.flagPush` is present and WRITTEN
+ * on both backends, so this is a real signal on the self-host stack too.
+ */
+const loadPendingUnseenFlagPushes = async (client, accountId) => {
+    const pushes = await client.flagPush.listByAccountId(accountId);
+    return pushes
+        .filter((push) => push.flagName === MessageSystemFlag.Seen)
+        .map((push) => ({ mailboxId: push.mailboxId, operation: push.operation }));
+};
+const toMailboxResponse = (mailbox, overrides = {}) => ({
+    mailboxId: mailbox.mailboxId,
+    accountId: mailbox.accountId,
+    namespaceType: mailbox.namespaceType,
+    namespacePrefix: mailbox.namespacePrefix,
+    hierarchyDelimiter: mailbox.hierarchyDelimiter,
+    fullPath: mailbox.fullPath,
+    messageCount: mailbox.messageCount,
+    unseenCount: mailbox.unseenCount,
+    deletedCount: mailbox.deletedCount,
+    specialUse: mailbox.specialUse ? Array.from(mailbox.specialUse) : undefined,
+    lastSyncUid: mailbox.lastSyncUid,
+    highWaterMarkUid: mailbox.highWaterMarkUid,
+    lastMessageSyncAt: mailbox.lastMessageSyncAt,
+    syncStatus: mailbox.syncStatus,
+    // The row is the only thing that knows what a rename is aiming at, and
+    // `fullPath` stays the confirmed one throughout (D2), so without this a
+    // client cannot tell a create in flight from a rename in flight, name the
+    // target of a failed rename, or offer the right retry.
+    pendingPath: mailbox.pendingPath,
+    syncFailureReason: mailbox.syncFailureReason,
+    muted: overrides.muted,
+    displayNameOverride: overrides.displayNameOverride,
+    createdAt: mailbox.createdAt,
+    updatedAt: mailbox.updatedAt,
+});
+export const MailboxOperations = {
+    MailboxOperations_listMailboxes: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { accountId } = context.request.params;
+        const { continuationToken } = context.request.query;
+        const client = ctx.client;
+        const account = await client.account.get(accountId);
+        unwrap(ownedAccount(account, accountConfigId, "read"));
+        const result = await client.mailbox.listByAccount(accountId, {
+            continuationToken,
+        });
+        // Overrides (mute / display-name / role) live in per-mailbox AccountSetting
+        // rows (RFC 032). Load the whole config's set in one query and key it by
+        // mailboxId so each mailbox surfaces its overrides without an N+1.
+        const overridesByMailbox = await loadMailboxOverridesForConfig(client.accountSetting, accountConfigId);
+        // Read-time prediction for any pending placement move (issue #1271) and
+        // pending \Seen flag push (issue #1273) — adjusts messageCount /
+        // unseenCount only, never the stored row (epic #1281 invariant 4).
+        const pendingMoves = await loadPendingMoves(client, accountId);
+        const pendingUnseenFlagPushes = await loadPendingUnseenFlagPushes(client, accountId);
+        // A folder mid-mutation is listed, labelled (D11). Hiding a `deleting` one
+        // made a delete that does not settle look like a folder that silently
+        // vanished, while the server still held it.
+        const items = applyPendingMoveCountPrediction(result.items, pendingMoves, pendingUnseenFlagPushes);
+        return {
+            items: items.map((mailbox) => toMailboxResponse(mailbox, overridesByMailbox.get(mailbox.mailboxId) ?? {})),
+            continuationToken: result.continuationToken,
+        };
+    },
+    MailboxOperations_createMailbox: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { accountId } = context.request.params;
+        const { namespaceType, fullPath } = context.request
+            .requestBody;
+        const created = await createFolder(ctx.client, accountConfigId, {
+            accountId,
+            namespaceType,
+            fullPath,
+        });
+        const { outcome, mailbox } = unwrap(created);
+        if (outcome === "Existing") {
+            throw new BadRequestError(`A folder named “${fullPath}” is already there.`);
+        }
+        return toMailboxResponse(mailbox);
+    },
+};
+export const MailboxDetailOperations = {
+    MailboxDetailOperations_getMailbox: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { accountId, mailboxId } = context.request.params;
+        const client = ctx.client;
+        const account = await client.account.get(accountId);
+        unwrap(ownedAccount(account, accountConfigId, "read"));
+        const mailbox = await client.mailbox.get(accountId, mailboxId);
+        unwrap(folderInAccount(mailbox, accountId, "read"));
+        const overrides = await loadMailboxOverrides(client.accountSetting, accountConfigId, mailboxId);
+        // Read-time prediction for any pending placement move (issue #1271) and
+        // pending \Seen flag push (issue #1273) — adjusts messageCount /
+        // unseenCount only, never the stored row (epic #1281 invariant 4).
+        const pendingMoves = await loadPendingMoves(client, accountId);
+        const pendingUnseenFlagPushes = await loadPendingUnseenFlagPushes(client, accountId);
+        const adjusted = applyPendingMoveCountPrediction([mailbox], pendingMoves, pendingUnseenFlagPushes)[0] ?? mailbox;
+        return toMailboxResponse(adjusted, overrides);
+    },
+    MailboxDetailOperations_renameMailbox: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { accountId, mailboxId } = context.request.params;
+        const body = context.request.requestBody;
+        const client = ctx.client;
+        const mailbox = await applyMailboxPatch(client, accountConfigId, mailboxId, accountId, body);
+        const overrides = await loadMailboxOverrides(client.accountSetting, accountConfigId, mailboxId);
+        return toMailboxResponse(mailbox, overrides);
+    },
+    MailboxDetailOperations_deleteMailbox: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { accountId, mailboxId } = context.request.params;
+        const client = ctx.client;
+        const account = await client.account.get(accountId);
+        unwrap(ownedAccount(account, accountConfigId, "act"));
+        const mailbox = await client.mailbox.get(accountId, mailboxId);
+        unwrap(folderInAccount(mailbox, accountId, "act"));
+        // Cheapest first (D4, D13). None of the three becomes possible by
+        // retrying the same request, so all three are 400 and all three run
+        // before anything is recorded.
+        if (mailbox.fullPath.toUpperCase() === "INBOX") {
+            throw new BadRequestError("The inbox can't be deleted.");
+        }
+        const children = await client.mailbox.findByPathPrefix(accountId, mailbox.fullPath, mailbox.hierarchyDelimiter);
+        if (children.length > 0) {
+            // The server would keep the parent's name as a placeholder and leave the
+            // children untouched — an outcome no local row describes (D9).
+            throw new BadRequestError(`“${mailbox.fullPath}” has folders inside it. Delete those first.`);
+        }
+        assertNoBindings(mailbox, await loadMailboxBindings(client, accountConfigId, accountId, mailboxId));
+        await client.mailboxQueue.deleteMailbox(mailboxId, accountId);
+        return { statusCode: 204 };
+    },
+};
+export const TrashOperations = {
+    TrashOperations_emptyTrash: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { accountId } = context.request.params;
+        const client = ctx.client;
+        const account = await client.account.get(accountId);
+        unwrap(ownedAccount(account, accountConfigId, "act"));
+        // The service resolves Trash, marks the rows and counts them, all off one
+        // read, and refuses with a coded 409 when the role is unresolved. Counting
+        // here as well would be a second answer free to disagree with the one that
+        // acts, and "0 deleted" reads as success to a user whose Trash is untouched.
+        return client.messageMove.emptyTrash(accountConfigId, accountId);
+    },
+};

package/dist/src/handlers/me.d.ts

@@ -0,0 +1,2 @@
+import type { MeOperationIds, OperationHandler } from "../types.js";
+export declare const MeOperations: Record<MeOperationIds, OperationHandler<MeOperationIds, "accountFanout">>;

package/dist/src/handlers/me.js

@@ -0,0 +1,117 @@
+import { BadRequestError, NotFoundError } from "@remit/data-ports/errors";
+import { SYNC_WARNING_SURFACE_ATTEMPTS } from "@remit/data-ports/sync-warning-state";
+import { logger } from "@remit/logger";
+import { toVipSuggestionEntry } from "./vip-suggestions.js";
+const DOWNLOAD_URL_TTL_SECONDS = 60 * 60;
+const SURFACED_WARNING_CAP = 200;
+export const MeOperations = {
+    MeOperations_listVipSuggestions: async (_context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { address } = ctx.client;
+        const items = await address.listSuggestedVips({ accountConfigId });
+        return { suggestions: items.map(toVipSuggestionEntry) };
+    },
+    MeOperations_listQuarantine: async (_context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { quarantine, syncWarning } = ctx.client;
+        const [entries, warnings] = await Promise.all([
+            quarantine.listByAccountConfigId(accountConfigId),
+            syncWarning.listSurfacedByAccountConfigId(accountConfigId, SYNC_WARNING_SURFACE_ATTEMPTS, SURFACED_WARNING_CAP),
+        ]);
+        return {
+            entries,
+            warnings: warnings.items,
+            warningsTotal: warnings.total,
+        };
+    },
+    MeOperations_deleteMe: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { confirmEmail } = context.request
+            .requestBody;
+        const callerEmail = ctx.identity.email;
+        if (typeof confirmEmail !== "string" || confirmEmail.trim() === "") {
+            throw new BadRequestError("confirmEmail is required");
+        }
+        if (confirmEmail.toLowerCase() !== callerEmail.toLowerCase()) {
+            throw new BadRequestError("confirmEmail does not match your account email");
+        }
+        const { accountConfig } = ctx.client;
+        try {
+            await accountConfig.update(accountConfigId, {
+                state: "deleting",
+                deletedAt: Date.now(),
+            });
+        }
+        catch (err) {
+            // If already in "deleting" state, treat as idempotent
+            if (err instanceof Error &&
+                (err.name === "ConditionalCheckFailedException" ||
+                    err.message.includes("ConditionalCheckFailed"))) {
+                return {
+                    statusCode: 202,
+                    message: "Account deletion already in progress",
+                };
+            }
+            throw err;
+        }
+        await ctx.client.queues.accountFanout.send({
+            body: { type: "AccountDelete", accountConfigId },
+        });
+        // biome-ignore lint/plugin/no-logger-info: account deletion is an audit-grade signal
+        logger.info({ accountConfigId }, "Account deletion initiated");
+        return {
+            statusCode: 202,
+            message: "Account deletion initiated",
+        };
+    },
+    MeOperations_createExport: async (_context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const userId = ctx.identity.sub;
+        const { accountExportRequest } = ctx.client;
+        const exportRequest = await accountExportRequest.create({
+            accountConfigId,
+            userId,
+            state: "Pending",
+        });
+        await ctx.client.queues.accountFanout.send({
+            body: {
+                type: "AccountExport",
+                accountConfigId,
+                accountExportRequestId: exportRequest.accountExportRequestId,
+            },
+        });
+        // biome-ignore lint/plugin/no-logger-info: account export is an audit-grade signal
+        logger.info({
+            accountConfigId,
+            accountExportRequestId: exportRequest.accountExportRequestId,
+        }, "Account export initiated");
+        return {
+            statusCode: 202,
+            exportId: exportRequest.accountExportRequestId,
+        };
+    },
+    MeOperations_getExport: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const exportId = context.request.params.exportId;
+        const { accountExportRequest, storage } = ctx.client;
+        const exportRequest = await accountExportRequest.get(exportId);
+        if (exportRequest.accountConfigId !== accountConfigId) {
+            throw new NotFoundError(`Export not found: ${exportId}`);
+        }
+        const downloadUrl = exportRequest.state === "Ready" && exportRequest.objectKey
+            ? await storage.getPresignedDownloadUrl(exportRequest.objectKey, DOWNLOAD_URL_TTL_SECONDS)
+            : undefined;
+        return {
+            accountExportRequestId: exportRequest.accountExportRequestId,
+            accountConfigId: exportRequest.accountConfigId,
+            userId: exportRequest.userId,
+            state: exportRequest.state,
+            createdAt: exportRequest.createdAt,
+            updatedAt: exportRequest.updatedAt,
+            objectKey: exportRequest.objectKey,
+            downloadUrl,
+            expiresAt: exportRequest.expiresAt,
+            errorMessage: exportRequest.errorMessage,
+        };
+    },
+};

package/dist/src/handlers/message.d.ts

@@ -0,0 +1,82 @@
+import type { BodyPartResponse } from "@remit/api-openapi-types";
+import { type ContentSigner } from "../derive/contentSignature.js";
+import type { MessageBulkOperationIds, MessageOperationIds, OperationHandler } from "../types.js";
+export declare const isStorageNotFoundError: (error: unknown) => boolean;
+/**
+ * Decode the raw `.eml` bytes into a string for inspection. RFC822/MIME
+ * sources are 7-bit/8-bit ASCII-compatible (non-ASCII bytes are encoded via
+ * quoted-printable / base64 inside the body), so `latin1` round-trips every
+ * byte 1:1 without loss or replacement characters — unlike `utf8`, which would
+ * mangle raw 8-bit bytes. Headers and structure stay byte-accurate.
+ */
+export declare const decodeRawEml: (body: Buffer) => string;
+/**
+ * Extract the accountConfigId + accountId segments from a bodyStorageKey URI
+ * such as
+ * `s3://bucket/accounts/{accountConfigId}/{accountId}/messages/{messageId}/body.eml`.
+ * Returns null when the URI shape doesn't match — caller falls back to the
+ * slow path without writing a parsed-body cache.
+ */
+export declare const extractAccountIdsFromBodyKey: (uri: string) => {
+    accountConfigId: string;
+    accountId: string;
+} | null;
+/**
+ * Map a list of stored `BodyPart` rows to API `BodyPartResponse` objects,
+ * populating `contentUrl` from the CloudFront distribution domain. Pure
+ * function so the URL-construction contract can be pinned in tests without
+ * standing up the full handler. The contract requires every `contentUrl`
+ * to be a real URL (#299), so the API refuses to start without the domain.
+ */
+export interface BodyPartLike {
+    bodyPartId: string;
+    mediaType: string;
+    mediaSubtype: string;
+    sizeOctets: number;
+    disposition?: string;
+    dispositionFilename?: string;
+    isMultipart: boolean;
+    contentId?: string;
+    partPath: string;
+}
+export declare const isMediaType: (value: unknown) => value is BodyPartResponse["mediaType"];
+export declare const isContentDisposition: (value: unknown) => value is NonNullable<BodyPartResponse["disposition"]>;
+export declare const FORWARDED_MESSAGE_FILENAME = "Forwarded message.eml";
+export declare const buildBodyPartResponses: (parts: readonly BodyPartLike[], context: {
+    contentDeliveryDomain: string;
+    accountConfigId: string;
+    accountId: string;
+    messageId: string;
+    sign?: ContentSigner;
+}) => BodyPartResponse[];
+export interface SpamReportBulkFailure {
+    messageId: string;
+    reason: string;
+}
+export interface SpamReportBulkOutcome {
+    successCount: number;
+    failureCount: number;
+    failures?: SpamReportBulkFailure[];
+}
+/**
+ * The fallback for a failure nobody designed copy for — an AWS SDK message
+ * naming a queue URL, an `ECONNREFUSED host:port`, a programmer error.
+ * Everything reaching it is flattened, same policy as `error.ts`'s "Internal
+ * server error" flattening, because `SpamReportBulkResult.reason` is shown to
+ * the user as-is. It says "try again" because retrying is the only thing left
+ * to say about a cause we cannot name; an outcome the service DOES understand
+ * carries its own text through `DESIGNED_FAILURES` instead of landing here.
+ */
+export declare const GENERIC_FAILURE_REASON = "This message could not be processed. Please try again. If it keeps failing, report it.";
+/**
+ * Drive one report-spam/not-spam operation per message, concurrently. Each
+ * message's own wait for its move to settle (SpamReportService's R2 wait) is
+ * bounded on its own, but running the batch sequentially would let those
+ * waits accumulate across the whole request — 50 messages could each wait
+ * seconds, serializing into minutes and dying at the proxy. Running them
+ * concurrently instead bounds the whole request by a single message's wait,
+ * regardless of batch size.
+ */
+export declare const settleSpamReportBulk: (messageIds: string[], run: (messageId: string) => Promise<void>) => Promise<SpamReportBulkOutcome>;
+export declare const MessageOperations: Record<MessageOperationIds, OperationHandler<MessageOperationIds, "sync" | "messageManagement" | "body">>;
+export declare const MessageBulkOperations: Record<MessageBulkOperationIds, OperationHandler<MessageBulkOperationIds, "sync" | "messageManagement" | "body">>;