@remit/backend 0.0.143 → 0.0.145

package/dist/src/handlers/organize.js

@@ -0,0 +1,103 @@
+import { BadRequestError, NotFoundError } from "@remit/data-ports/errors";
+import { logger } from "@remit/logger";
+import { ownedAccount, queueOrganizeJob, } from "@remit/mailbox-service";
+import { buildOrganizeMatchDeps, matchOrganize, ORGANIZE_MATCH_LIMIT, organizePredicateRejection, } from "../service/organize.js";
+import { unwrap } from "../service/refusal.js";
+/**
+ * Normalize the request body into the flattened predicate the job row and the
+ * matcher share.
+ */
+export const predicateFromInput = (input) => ({
+    matchOperator: input.matchOperator,
+    literalClauses: input.literalClauses,
+    actionLabelId: input.actionLabelId,
+    actionMailboxId: input.actionMailboxId,
+});
+const assertAccount = async (client, accountId, accountConfigId, mode) => {
+    const account = await client.account.get(accountId);
+    unwrap(ownedAccount(account, accountConfigId, mode));
+};
+const toOrganizeJobResponse = (job) => ({
+    organizeJobId: job.organizeJobId,
+    accountConfigId: job.accountConfigId,
+    userId: job.userId,
+    state: job.state,
+    filterId: job.filterId,
+    matchOperator: job.matchOperator,
+    literalClauses: job.literalClauses,
+    actionLabelId: job.actionLabelId,
+    actionMailboxId: job.actionMailboxId,
+    matchedCount: job.matchedCount,
+    appliedCount: job.appliedCount,
+    failedCount: job.failedCount,
+    errorMessage: job.errorMessage,
+    createdAt: job.createdAt,
+    updatedAt: job.updatedAt,
+});
+/**
+ * What a create asks the worker to run. A saved filter is named and read when
+ * the job runs, so Run now and a filter's create share one path (#1354); an
+ * "all like these" predicate the matcher can never honour is answered here,
+ * not with a 202 the worker has to fail later (reader #463).
+ */
+const requestedJob = async (client, owner, input) => {
+    if (input.filterId) {
+        await client.filter.get(owner.accountConfigId, input.filterId);
+        return { ...owner, filterId: input.filterId };
+    }
+    const predicate = predicateFromInput(input);
+    const rejection = organizePredicateRejection(predicate);
+    if (rejection)
+        throw new BadRequestError(rejection.message);
+    return { ...owner, predicate };
+};
+export const OrganizeOperations = {
+    OrganizeOperations_createOrganizeJob: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { accountId } = context.request.params;
+        const input = context.request.requestBody;
+        const userId = ctx.identity.sub;
+        const client = ctx.client;
+        await assertAccount(client, accountId, accountConfigId, "act");
+        const job = await queueOrganizeJob({
+            organizeJobRequest: client.organizeJobRequest,
+            queue: client.queues.accountFanout,
+            logger,
+        }, await requestedJob(client, { accountConfigId, userId }, input));
+        return {
+            statusCode: 202,
+            organizeJobId: job.organizeJobId,
+            state: job.state,
+        };
+    },
+    OrganizeOperations_previewOrganize: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { accountId } = context.request.params;
+        const input = context.request.requestBody;
+        const client = ctx.client;
+        await assertAccount(client, accountId, accountConfigId, "read");
+        if (input.filterId) {
+            throw new BadRequestError("Preview takes a rule, not a saved filter. Run the filter to apply it.");
+        }
+        const result = await matchOrganize(buildOrganizeMatchDeps(client), accountConfigId, predicateFromInput(input), ORGANIZE_MATCH_LIMIT);
+        if (result.rejected)
+            throw new BadRequestError(result.rejected.message);
+        return {
+            matchedCount: result.messageIds.length,
+            messageIds: result.messageIds,
+        };
+    },
+};
+export const OrganizeJobDetailOperations = {
+    OrganizeJobDetailOperations_getOrganizeJob: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { accountId, organizeJobId } = context.request.params;
+        const client = ctx.client;
+        await assertAccount(client, accountId, accountConfigId, "read");
+        const job = await client.organizeJobRequest.get(organizeJobId);
+        if (job.accountConfigId !== accountConfigId) {
+            throw new NotFoundError(`Organize job not found: ${organizeJobId}`);
+        }
+        return toOrganizeJobResponse(job);
+    },
+};

package/dist/src/handlers/outbox-attachment.d.ts

@@ -0,0 +1,25 @@
+import type { MintOutboxAttachmentResponse, OutboxAttachmentRejection, OutboxAttachmentResponse } from "@remit/api-openapi-types";
+import type { OutboxAttachmentItem } from "@remit/data-ports";
+import type { Context } from "openapi-backend";
+import type { ApiConfig } from "../config/api-config.js";
+import type { HandlerContext } from "../types.js";
+export declare const toOutboxAttachmentResponse: (config: ApiConfig) => (item: OutboxAttachmentItem) => OutboxAttachmentResponse;
+interface RejectionResponse {
+    statusCode: number;
+    body: OutboxAttachmentRejection;
+}
+/**
+ * Reserve room on a draft and hand back somewhere to put the bytes. Small JSON
+ * in, small JSON out — the file itself never passes through here, which is what
+ * lets the upload live on its own fleet and keeps this operation under any
+ * payload ceiling the REST tier has.
+ */
+export declare const mintOutboxAttachment: (context: Context, ctx: HandlerContext) => Promise<MintOutboxAttachmentResponse | RejectionResponse>;
+/**
+ * Confirm the upload landed. The size in the response is read back from
+ * storage — on a deployment where the browser PUT straight to block storage
+ * this call is the first the API hears of the bytes, and the client's word for
+ * how many there are is not evidence.
+ */
+export declare const completeOutboxAttachment: (context: Context, ctx: HandlerContext) => Promise<OutboxAttachmentResponse | RejectionResponse>;
+export {};

package/dist/src/handlers/outbox-attachment.js

@@ -0,0 +1,77 @@
+import { OutboxAttachmentRejectionReason } from "@remit/domain-enums";
+import { outboxAttachmentContentId } from "@remit/mailbox-service/outbox-attachment-content";
+import { getContentSigner } from "../derive/contentSignature.js";
+import { buildStorageContentUrl } from "../derive/contentUrl.js";
+// Every error body the API emits carries a `code` (issue #371). A refusal here
+// is one kind, so the code is one value and `reason` says which refusal it was.
+const ATTACHMENT_REJECTED_CODE = "attachment_rejected";
+const TOO_LARGE = new Set([
+    OutboxAttachmentRejectionReason.FileTooLarge,
+    OutboxAttachmentRejectionReason.MessageTooLarge,
+    OutboxAttachmentRejectionReason.TooManyAttachments,
+]);
+export const toOutboxAttachmentResponse = (config) => (item) => ({
+    outboxAttachmentId: item.outboxAttachmentId,
+    outboxMessageId: item.outboxMessageId,
+    filename: item.filename,
+    contentType: item.contentType,
+    sizeBytes: item.sizeBytes,
+    state: item.state,
+    contentId: outboxAttachmentContentId(item.outboxAttachmentId),
+    contentUrl: buildStorageContentUrl({
+        domain: config.contentDeliveryDomain,
+        storageKey: item.storageKey,
+        sign: getContentSigner(config),
+    }),
+});
+const refuse = (detail) => ({
+    statusCode: TOO_LARGE.has(detail.reason) ? 413 : 400,
+    body: {
+        code: ATTACHMENT_REJECTED_CODE,
+        reason: detail.reason,
+        message: detail.message,
+        limitBytes: detail.limitBytes,
+        usedBytes: detail.usedBytes,
+    },
+});
+/**
+ * Reserve room on a draft and hand back somewhere to put the bytes. Small JSON
+ * in, small JSON out — the file itself never passes through here, which is what
+ * lets the upload live on its own fleet and keeps this operation under any
+ * payload ceiling the REST tier has.
+ */
+export const mintOutboxAttachment = async (context, ctx) => {
+    const accountConfigId = ctx.identity.accountConfigId;
+    const { outboxMessageId } = context.request.params;
+    const input = context.request.requestBody;
+    const client = ctx.client;
+    const result = await client.outboxAttachment.mint({
+        accountConfigId,
+        outboxMessageId,
+        filename: input.filename,
+        contentType: input.contentType,
+        sizeBytes: input.sizeBytes,
+    });
+    if (result.outcome === "Rejected")
+        return refuse(result.rejection);
+    return result.reservation;
+};
+/**
+ * Confirm the upload landed. The size in the response is read back from
+ * storage — on a deployment where the browser PUT straight to block storage
+ * this call is the first the API hears of the bytes, and the client's word for
+ * how many there are is not evidence.
+ */
+export const completeOutboxAttachment = async (context, ctx) => {
+    const accountConfigId = ctx.identity.accountConfigId;
+    const { outboxMessageId, outboxAttachmentId } = context.request.params;
+    const client = ctx.client;
+    const result = await client.outboxAttachment.complete({
+        accountConfigId,
+        outboxMessageId,
+        outboxAttachmentId,
+    });
+    if (result.outcome === "Rejected")
+        return refuse(result.rejection);
+    return toOutboxAttachmentResponse(ctx.config)(result.attachment);
+};

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

@@ -0,0 +1,4 @@
+import type { OperationHandler, OutboxAttachmentOperationIds, OutboxDetailOperationIds, OutboxOperationIds } from "../types.js";
+export declare const OutboxOperations: Record<OutboxOperationIds, OperationHandler<OutboxOperationIds, "smtp">>;
+export declare const OutboxDetailOperations: Record<OutboxDetailOperationIds, OperationHandler<OutboxDetailOperationIds, "smtp">>;
+export declare const OutboxAttachmentOperations: Record<OutboxAttachmentOperationIds, OperationHandler<OutboxAttachmentOperationIds, "smtp">>;

package/dist/src/handlers/outbox.js

@@ -0,0 +1,136 @@
+import { ForbiddenError } from "@remit/data-ports/errors";
+import { completeOutboxAttachment, mintOutboxAttachment, toOutboxAttachmentResponse, } from "./outbox-attachment.js";
+const toOutboxMessageResponse = (config, item, attachments = []) => ({
+    attachments: attachments.map(toOutboxAttachmentResponse(config)),
+    outboxMessageId: item.outboxMessageId,
+    accountId: item.accountId,
+    fromAddress: item.fromAddress,
+    fromName: item.fromName,
+    toAddresses: item.toAddresses,
+    ccAddresses: item.ccAddresses ?? [],
+    bccAddresses: item.bccAddresses ?? [],
+    subject: item.subject,
+    textBody: item.textBody,
+    htmlBody: item.htmlBody,
+    inReplyTo: item.inReplyTo,
+    references: item.references ?? [],
+    status: item.status,
+    lastError: item.lastError,
+    sentAt: item.sentAt,
+    createdAt: item.createdAt,
+    updatedAt: item.updatedAt,
+});
+export const OutboxOperations = {
+    OutboxOperations_createOutboxMessage: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const input = context.request.requestBody;
+        const client = ctx.client;
+        const account = await client.account.get(input.accountId);
+        if (account.accountConfigId !== accountConfigId) {
+            throw new ForbiddenError(`Account ${input.accountId} not in account config`);
+        }
+        const fromAddress = account.email;
+        if (input.sendImmediately) {
+            const outbox = await client.outboxQueue.createAndSend({
+                accountId: input.accountId,
+                accountConfigId,
+                fromAddress,
+                toAddresses: input.toAddresses,
+                ccAddresses: input.ccAddresses,
+                bccAddresses: input.bccAddresses,
+                subject: input.subject,
+                textBody: input.textBody,
+                htmlBody: input.htmlBody,
+                inReplyTo: input.inReplyTo,
+                references: input.references,
+            });
+            return toOutboxMessageResponse(ctx.config, outbox);
+        }
+        const outbox = await client.outboxQueue.createDraft({
+            accountId: input.accountId,
+            accountConfigId,
+            fromAddress,
+            toAddresses: input.toAddresses,
+            ccAddresses: input.ccAddresses,
+            bccAddresses: input.bccAddresses,
+            subject: input.subject,
+            textBody: input.textBody,
+            htmlBody: input.htmlBody,
+            inReplyTo: input.inReplyTo,
+            references: input.references,
+        });
+        return toOutboxMessageResponse(ctx.config, outbox);
+    },
+    OutboxOperations_listOutboxMessages: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { continuationToken } = context.request.query;
+        const client = ctx.client;
+        const accounts = await client.account.listAllByAccountConfig(accountConfigId);
+        if (accounts.length === 0) {
+            return { items: [], continuationToken: null };
+        }
+        const result = await client.outboxMessage.listByAccounts(accounts.map((account) => account.accountId), { continuationToken });
+        return {
+            items: result.items.map((item) => toOutboxMessageResponse(ctx.config, item)),
+            continuationToken: result.continuationToken,
+        };
+    },
+};
+export const OutboxDetailOperations = {
+    OutboxDetailOperations_getOutboxMessage: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { outboxMessageId } = context.request.params;
+        const client = ctx.client;
+        // Default mode "read": the scoped get refuses a foreign message with
+        // NotFound (404, no existence leak) — no separate check needed.
+        const outbox = await client.outboxMessage.get(accountConfigId, outboxMessageId);
+        return toOutboxMessageResponse(ctx.config, outbox, await client.outboxAttachment.listFor(accountConfigId, outboxMessageId));
+    },
+    OutboxDetailOperations_updateOutboxMessage: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { outboxMessageId } = context.request.params;
+        const input = context.request.requestBody;
+        const client = ctx.client;
+        // updateDraft's own scoped get uses mode "act": a foreign message is
+        // denied with Forbidden (403), not feigned as NotFound.
+        const updated = await client.outboxQueue.updateDraft(accountConfigId, outboxMessageId, {
+            toAddresses: input.toAddresses,
+            ccAddresses: input.ccAddresses,
+            bccAddresses: input.bccAddresses,
+            subject: input.subject,
+            textBody: input.textBody,
+            htmlBody: input.htmlBody,
+            inReplyTo: input.inReplyTo,
+            references: input.references,
+        });
+        // Absent means "leave the files alone" — a body that only carries a subject
+        // must not strip them. Present states exactly what the draft keeps, so an
+        // empty list is a real instruction to remove them all.
+        if (input.attachmentIds !== undefined) {
+            await client.outboxAttachment.retainOnly(accountConfigId, updated.accountId, outboxMessageId, input.attachmentIds);
+        }
+        return toOutboxMessageResponse(ctx.config, updated, await client.outboxAttachment.listFor(accountConfigId, outboxMessageId));
+    },
+    OutboxDetailOperations_deleteOutboxMessage: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { outboxMessageId } = context.request.params;
+        const client = ctx.client;
+        // deleteDraft's own scoped get uses mode "act": a foreign message is
+        // denied with Forbidden (403), not feigned as NotFound.
+        await client.outboxQueue.deleteDraft(accountConfigId, outboxMessageId);
+        return { statusCode: 204 };
+    },
+    OutboxDetailOperations_sendOutboxMessage: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { outboxMessageId } = context.request.params;
+        const client = ctx.client;
+        // send's own scoped get uses mode "act": a foreign message is denied
+        // with Forbidden (403), not feigned as NotFound.
+        const sent = await client.outboxQueue.send(accountConfigId, outboxMessageId);
+        return toOutboxMessageResponse(ctx.config, sent);
+    },
+    OutboxDetailOperations_mintOutboxAttachment: mintOutboxAttachment,
+};
+export const OutboxAttachmentOperations = {
+    OutboxAttachmentOperations_completeOutboxAttachment: completeOutboxAttachment,
+};

package/dist/src/handlers/sync-progress.d.ts

@@ -0,0 +1,46 @@
+import type { MailboxItem } from "@remit/data-ports";
+/** The subset of mailbox fields needed to derive sync progress. */
+export type MailboxSyncFields = Pick<MailboxItem, "lastMessageSyncAt" | "initialSyncCompletedAt" | "messageCount" | "lastSyncUid" | "highWaterMarkUid">;
+/** A mailbox row, as far as the sync-status projection reads it. */
+export type MailboxProgressFields = MailboxSyncFields & Pick<MailboxItem, "mailboxId" | "fullPath">;
+/** The per-mailbox entry `getSyncStatus` returns. */
+export interface MailboxSyncProgress {
+    mailboxId: string;
+    fullPath: string;
+    phase: string;
+    messagesTotal: number;
+    messagesSynced: number;
+    highWaterMarkUid: number;
+    lastSyncedAt: number | undefined;
+}
+/**
+ * Derive a per-mailbox sync phase from worker-written sync state.
+ *
+ * - pending:  never synced (lastMessageSyncAt is 0 / unset)
+ * - complete: the imap-worker drained the mailbox and stamped
+ *             initialSyncCompletedAt after the last batch write
+ *             (initialSyncCompletedAt >= lastMessageSyncAt), or the
+ *             mailbox is empty
+ * - syncing:  sync has started but is not yet complete
+ *
+ * Note: UID watermarks alone cannot express completion — backfill settles
+ * at the mailbox's smallest real UID (UIDs are sparse), so the completion
+ * marker written by the worker is the source of truth.
+ */
+export declare const deriveMailboxPhase: (mailbox: MailboxSyncFields) => string;
+/**
+ * Compute approximate messagesSynced from UID watermarks.
+ *
+ * UIDs are sparse (not necessarily contiguous), so this is an approximation.
+ * We clamp the result to [0, messagesTotal].
+ */
+export declare const computeMessagesSynced: (mailbox: MailboxSyncFields) => number;
+/**
+ * Project a mailbox row into its sync-status entry.
+ *
+ * `highWaterMarkUid` is carried through because a total cannot tell an arrival
+ * from a departure: a message landing in the same sync round that another one
+ * leaves nets to zero, and the client's freshness check saw nothing (#771). The
+ * highest UID only ever moves up, so it names the arrival on its own.
+ */
+export declare const toMailboxSyncProgress: (mailbox: MailboxProgressFields) => MailboxSyncProgress;

package/dist/src/handlers/sync-progress.js

@@ -0,0 +1,63 @@
+/**
+ * Derive a per-mailbox sync phase from worker-written sync state.
+ *
+ * - pending:  never synced (lastMessageSyncAt is 0 / unset)
+ * - complete: the imap-worker drained the mailbox and stamped
+ *             initialSyncCompletedAt after the last batch write
+ *             (initialSyncCompletedAt >= lastMessageSyncAt), or the
+ *             mailbox is empty
+ * - syncing:  sync has started but is not yet complete
+ *
+ * Note: UID watermarks alone cannot express completion — backfill settles
+ * at the mailbox's smallest real UID (UIDs are sparse), so the completion
+ * marker written by the worker is the source of truth.
+ */
+export const deriveMailboxPhase = (mailbox) => {
+    if (!mailbox.lastMessageSyncAt)
+        return "pending";
+    const messageCount = mailbox.messageCount ?? 0;
+    const initialSyncCompletedAt = mailbox.initialSyncCompletedAt ?? 0;
+    // Completion marker is fresh: no batch was written after the worker
+    // recorded the mailbox as drained.
+    if (initialSyncCompletedAt > 0 &&
+        initialSyncCompletedAt >= mailbox.lastMessageSyncAt) {
+        return "complete";
+    }
+    // Also complete if messageCount is 0 (empty mailbox)
+    if (messageCount === 0)
+        return "complete";
+    return "syncing";
+};
+/**
+ * Compute approximate messagesSynced from UID watermarks.
+ *
+ * UIDs are sparse (not necessarily contiguous), so this is an approximation.
+ * We clamp the result to [0, messagesTotal].
+ */
+export const computeMessagesSynced = (mailbox) => {
+    const messagesTotal = mailbox.messageCount ?? 0;
+    const lastSyncUid = mailbox.lastSyncUid ?? 0;
+    const highWaterMarkUid = mailbox.highWaterMarkUid ?? 0;
+    if (highWaterMarkUid === 0)
+        return 0;
+    // UID range approximation: number of UIDs in the synced range
+    const synced = highWaterMarkUid - lastSyncUid + 1;
+    return Math.min(Math.max(synced, 0), messagesTotal);
+};
+/**
+ * Project a mailbox row into its sync-status entry.
+ *
+ * `highWaterMarkUid` is carried through because a total cannot tell an arrival
+ * from a departure: a message landing in the same sync round that another one
+ * leaves nets to zero, and the client's freshness check saw nothing (#771). The
+ * highest UID only ever moves up, so it names the arrival on its own.
+ */
+export const toMailboxSyncProgress = (mailbox) => ({
+    mailboxId: mailbox.mailboxId,
+    fullPath: mailbox.fullPath,
+    phase: deriveMailboxPhase(mailbox),
+    messagesTotal: mailbox.messageCount ?? 0,
+    messagesSynced: computeMessagesSynced(mailbox),
+    highWaterMarkUid: mailbox.highWaterMarkUid ?? 0,
+    lastSyncedAt: mailbox.lastMessageSyncAt || undefined,
+});

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

@@ -0,0 +1,28 @@
+import type { FifoQueueProducer } from "@remit/data-ports";
+import { type FireAndForgetLogger } from "../service/fire-and-forget.js";
+import { type SyncMailboxesEvent } from "../service/trigger-sync.js";
+import type { OperationHandler, SyncOperationIds } from "../types.js";
+interface SyncTriggerDeps {
+    queue: FifoQueueProducer<SyncMailboxesEvent>;
+    logger: FireAndForgetLogger & {
+        info: (fields: Record<string, unknown>, message: string) => void;
+    };
+}
+/**
+ * Fire-and-forget enqueue for the POST /sync kick.
+ *
+ * POST /sync is a best-effort nudge: the web client polls it to wake a sync and
+ * acts on no enqueue result in the response. So the enqueue must never fail —
+ * nor leak onto — this request or any concurrent read when the queue is
+ * unreachable. Previously this handler `await`ed the SQS send directly; with the
+ * queue down (smoke/e2e, or an SQS outage in prod) the awaited rejection escaped
+ * the handler's promise and landed on whatever read was in flight on the shared
+ * event loop, 500-ing unrelated `/mailboxes`, `/threads` and `/outbox` reads.
+ *
+ * Routing it through fireAndForget catches the rejection at the source, logs it
+ * loudly with the alertable structured fields, and resolves to void. A genuine
+ * account-lookup / ownership failure still propagates and 500s as normal.
+ */
+export declare const triggerSyncSafe: (accountId: string, accountConfigId: string, deps: SyncTriggerDeps) => Promise<void>;
+export declare const SyncOperations: Record<SyncOperationIds, OperationHandler<SyncOperationIds, "sync">>;
+export {};

package/dist/src/handlers/sync.js

@@ -0,0 +1,73 @@
+import { logger } from "@remit/logger";
+import { ownedAccount } from "@remit/mailbox-service";
+import { fireAndForget, } from "../service/fire-and-forget.js";
+import { unwrap } from "../service/refusal.js";
+import { triggerAccountSync, } from "../service/trigger-sync.js";
+import { toMailboxSyncProgress } from "./sync-progress.js";
+/**
+ * Fire-and-forget enqueue for the POST /sync kick.
+ *
+ * POST /sync is a best-effort nudge: the web client polls it to wake a sync and
+ * acts on no enqueue result in the response. So the enqueue must never fail —
+ * nor leak onto — this request or any concurrent read when the queue is
+ * unreachable. Previously this handler `await`ed the SQS send directly; with the
+ * queue down (smoke/e2e, or an SQS outage in prod) the awaited rejection escaped
+ * the handler's promise and landed on whatever read was in flight on the shared
+ * event loop, 500-ing unrelated `/mailboxes`, `/threads` and `/outbox` reads.
+ *
+ * Routing it through fireAndForget catches the rejection at the source, logs it
+ * loudly with the alertable structured fields, and resolves to void. A genuine
+ * account-lookup / ownership failure still propagates and 500s as normal.
+ */
+export const triggerSyncSafe = async (accountId, accountConfigId, deps) => {
+    await fireAndForget(async () => {
+        const { eventId } = await triggerAccountSync({
+            queue: deps.queue,
+            accountId,
+            // POST /sync asks for a sync of this account by name — the refresh
+            // control, pull-to-refresh, and the client's automatic poll all land
+            // here — so it syncs every mailbox regardless of how recently one
+            // ran.
+            explicitRequest: true,
+        });
+        deps.logger.info({ accountId, eventId }, "Sync triggered - enqueued SYNC_MAILBOXES event");
+    }, {
+        source: "trigger_sync",
+        message: "Failed to enqueue SYNC_MAILBOXES on POST /sync (best-effort)",
+        ids: { accountId, accountConfigId },
+        logger: deps.logger,
+    });
+};
+export const SyncOperations = {
+    SyncOperations_triggerSync: async (context, ctx) => {
+        const accountConfigId = ctx.identity.accountConfigId;
+        const { accountId } = context.request.params;
+        const account = await ctx.client.account.get(accountId);
+        unwrap(ownedAccount(account, accountConfigId, "act"));
+        void triggerSyncSafe(account.accountId, accountConfigId, {
+            queue: ctx.client.queues.sync,
+            logger,
+        });
+        return {
+            triggered: true,
+            message: `Sync triggered for account ${accountId}`,
+        };
+    },
+    SyncOperations_getSyncStatus: 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, "read"));
+        // Collect all mailboxes (read-only — does not write or contend with sync lock)
+        const mailboxes = await client.mailbox.listAllByAccount(accountId);
+        return {
+            accountId: account.accountId,
+            syncPhase: account.syncPhase,
+            mailboxCountTotal: account.mailboxCountTotal,
+            mailboxCountSynced: account.mailboxCountSynced,
+            lastSyncAt: account.lastSyncAt,
+            mailboxes: mailboxes.map(toMailboxSyncProgress),
+        };
+    },
+};

package/dist/src/handlers/system-update.d.ts

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