@remit/imap-worker 0.0.90 → 0.0.91

package/dist/poller.js

@@ -0,0 +1,51 @@
+import { createLogger } from "@remit/logger";
+import { startMetricsServer } from "@remit/logger-lambda/metrics";
+import { installNodeLogger } from "@remit/logger-lambda/node";
+import { runQueuePoller } from "@remit/sqs-client/poller";
+import { env } from "expect-env";
+import { handler } from "./index.js";
+installNodeLogger();
+/**
+ * Production queue poller — the deployed form of `e2e-processor-shim.ts`.
+ * Polls every imap-worker queue and invokes the production Lambda handler.
+ */
+const log = createLogger();
+// /metrics and nothing else, on the compose network (standalone-observability
+// D2). No health route on it: worker liveness is a heartbeat file, which keeps
+// answering when this server does not.
+startMetricsServer();
+await runQueuePoller({
+    log,
+    targets: [
+        {
+            queueUrl: env.SQS_QUEUE_URL_MAILBOXES,
+            handler,
+            functionName: "imap-worker-mailboxes",
+        },
+        {
+            queueUrl: env.SQS_QUEUE_URL_MESSAGES,
+            handler,
+            functionName: "imap-worker-messages",
+        },
+        {
+            queueUrl: env.SQS_QUEUE_URL_FLAGS,
+            handler,
+            functionName: "imap-worker-flags",
+        },
+        {
+            queueUrl: env.SQS_QUEUE_URL_BODY,
+            handler,
+            functionName: "imap-worker-body",
+        },
+        {
+            queueUrl: env.SQS_QUEUE_URL_MAILBOX_MGMT,
+            handler,
+            functionName: "imap-worker-mailbox-mgmt",
+        },
+        {
+            queueUrl: env.SQS_QUEUE_URL_MESSAGE_MGMT,
+            handler,
+            functionName: "imap-worker-message-mgmt",
+        },
+    ],
+});

package/dist/process.d.ts

@@ -0,0 +1,6 @@
+export type { ConnectionScope } from "@remit/mailbox-service";
+export { type BorrowedConnection, type ConnectImap, type ConnectionPool, type ConnectionPoolOptions, createConnectionPool, type PoolAccount, type PoolOverflow, } from "./connection-pool.js";
+export { type AccountObjectPage, type AccountObjectStore, type AttemptBudgets, DEFAULT_MAILBOX_FRESHNESS_MS, defaultImapWorkerConfig, type ImapFailureKind, type ImapWorkerConfig, type ImapWorkerQueueName, type ProcessContext, type TokenService, type WorkerMetrics, } from "./context.js";
+export type { ImapEvent, WorkerEvent } from "./events.js";
+export { processEvent } from "./processor.js";
+export type { WorkerQueues } from "./queues.js";

package/dist/process.js

@@ -0,0 +1,3 @@
+export { createConnectionPool, } from "./connection-pool.js";
+export { DEFAULT_MAILBOX_FRESHNESS_MS, defaultImapWorkerConfig, } from "./context.js";
+export { processEvent } from "./processor.js";

package/dist/processor.d.ts

@@ -0,0 +1,3 @@
+import type { ProcessContext } from "./context.js";
+import type { WorkerEvent } from "./events.js";
+export declare const processEvent: (event: WorkerEvent, ctx: ProcessContext, receiveCount: number) => Promise<void>;

package/dist/processor.js

@@ -0,0 +1,44 @@
+import { handleAppendSentMessage } from "./handlers/append-sent-message.js";
+import { handleDeleteAccountObjects } from "./handlers/delete-account-objects.js";
+import { handleEmptyTrash } from "./handlers/empty-trash.js";
+import { handleFlagPush } from "./handlers/flag-push.js";
+import { processMailboxManagement } from "./handlers/mailbox-management.js";
+import { handleMessageCopy } from "./handlers/message-copy.js";
+import { handleMessageDelete } from "./handlers/message-delete.js";
+import { handleMessageMove } from "./handlers/message-move.js";
+import { handlePlacementMovePush } from "./handlers/placement-move-push.js";
+import { syncMailboxes } from "./handlers/sync-mailboxes.js";
+import { syncMessageBody } from "./handlers/sync-message-body.js";
+import { syncMessages } from "./handlers/sync-messages.js";
+export const processEvent = async (event, ctx, receiveCount) => {
+    switch (event.type) {
+        case "SYNC_MAILBOXES":
+            return syncMailboxes(event, ctx);
+        case "SYNC_MESSAGES":
+            return syncMessages(event, ctx);
+        case "SYNC_MESSAGE_BODY":
+            return syncMessageBody(event, ctx, receiveCount);
+        case "MAILBOX_CREATE":
+        case "MAILBOX_RENAME":
+        case "MAILBOX_DELETE":
+            return processMailboxManagement(event, ctx);
+        case "MESSAGE_DELETE":
+            return handleMessageDelete(event, ctx, receiveCount);
+        case "MESSAGE_MOVE":
+            return handleMessageMove(event, ctx, receiveCount);
+        case "PLACEMENT_MOVE_PUSH":
+            return handlePlacementMovePush(event, ctx, receiveCount);
+        case "FLAG_PUSH":
+            return handleFlagPush(event, ctx, receiveCount);
+        case "MESSAGE_COPY":
+            return handleMessageCopy(event, ctx, receiveCount);
+        case "EMPTY_TRASH":
+            return handleEmptyTrash(event, ctx);
+        case "APPEND_SENT_MESSAGE":
+            return handleAppendSentMessage(event, ctx, receiveCount);
+        case "DELETE_ACCOUNT_OBJECTS":
+            return handleDeleteAccountObjects(event, ctx);
+        default:
+            throw new Error(`Unknown event type: ${event.type}`);
+    }
+};

package/dist/queues.d.ts

@@ -0,0 +1,10 @@
+import type { FifoQueueProducer, QueueProducer } from "@remit/data-ports";
+import type { ImapEvent, WorkerEvent } from "./events.js";
+export interface WorkerQueues {
+    mailboxes: FifoQueueProducer<ImapEvent>;
+    messages: FifoQueueProducer<ImapEvent>;
+    flags: FifoQueueProducer<ImapEvent>;
+    body: QueueProducer<ImapEvent>;
+    mailboxManagement: QueueProducer<ImapEvent>;
+    messageManagement: QueueProducer<WorkerEvent>;
+}

package/dist/queues.js

@@ -0,0 +1 @@
+export {};

package/dist/s3-account-objects.d.ts

@@ -0,0 +1,3 @@
+import { S3Client } from "@aws-sdk/client-s3";
+import type { AccountObjectStore } from "./context.js";
+export declare const s3AccountObjects: (bucket: () => string, s3?: S3Client) => AccountObjectStore;

package/dist/s3-account-objects.js

@@ -0,0 +1,26 @@
+import { DeleteObjectsCommand, ListObjectsV2Command, S3Client, } from "@aws-sdk/client-s3";
+const PAGE_SIZE = 1_000;
+export const s3AccountObjects = (bucket, s3 = new S3Client({})) => ({
+    list: async (prefix, continuationToken) => {
+        const result = await s3.send(new ListObjectsV2Command({
+            Bucket: bucket(),
+            Prefix: prefix,
+            MaxKeys: PAGE_SIZE,
+            ContinuationToken: continuationToken,
+        }));
+        return {
+            keys: (result.Contents ?? [])
+                .map((object) => object.Key)
+                .filter((key) => key !== undefined),
+            nextContinuationToken: result.IsTruncated
+                ? result.NextContinuationToken
+                : undefined,
+        };
+    },
+    delete: async (keys) => {
+        await s3.send(new DeleteObjectsCommand({
+            Bucket: bucket(),
+            Delete: { Objects: keys.map((Key) => ({ Key })), Quiet: true },
+        }));
+    },
+});

package/dist/scheduler/attachment-sweep.d.ts

@@ -0,0 +1,11 @@
+import type { RemitClient } from "@remit/backend/client";
+import type { AccountItem } from "@remit/data-ports";
+import type { Logger } from "@remit/logger";
+/**
+ * Collect attachment bytes the database does not know about. Both scheduler
+ * entry points build it the same way, so the hosted tick and the self-host loop
+ * collect identically — this is the only defence on the hosted side, where the
+ * browser PUTs straight to block storage and nothing consults the database on
+ * the way in.
+ */
+export declare const buildAttachmentSweep: (client: Pick<RemitClient, "storage" | "outboxAttachment">, log: Logger) => ((account: AccountItem) => Promise<void>);

package/dist/scheduler/attachment-sweep.js

@@ -0,0 +1,23 @@
+import { sweepAbandonedOutboxAttachments } from "@remit/storage-service";
+/**
+ * Collect attachment bytes the database does not know about. Both scheduler
+ * entry points build it the same way, so the hosted tick and the self-host loop
+ * collect identically — this is the only defence on the hosted side, where the
+ * browser PUTs straight to block storage and nothing consults the database on
+ * the way in.
+ */
+export const buildAttachmentSweep = (client, log) => async (account) => {
+    const { deleted, skipped } = await sweepAbandonedOutboxAttachments({
+        storage: client.storage,
+        // Reaps the draft's lapsed reservations first, so a row that has
+        // stopped holding room stops vouching for its bytes too and the
+        // object is collected on this same pass.
+        listKnownAttachmentIds: (accountConfigId, outboxMessageId) => client.outboxAttachment.reapAndListLive(accountConfigId, outboxMessageId),
+        onSkipped: (outboxMessageId, error) => {
+            log.error({ outboxMessageId, error }, "Left a draft's attachment objects alone: its rows could not be read");
+        },
+    }, account.accountConfigId, account.accountId);
+    if (deleted > 0 || skipped > 0) {
+        log.warn({ accountId: account.accountId, deleted, skipped }, "Outbox attachment sweep");
+    }
+};

package/dist/scheduler/calendar-subscriptions.d.ts

@@ -0,0 +1,26 @@
+import type { RemitClient } from "@remit/backend/client";
+import { type CalendarFeedFetcher } from "@remit/calendar-service";
+import type { ICalendarCollectionRepository, ICalendarStore } from "@remit/data-ports";
+import type { Logger } from "@remit/logger";
+export interface CalendarSubscriptionTally {
+    refreshed: number;
+    failed: number;
+    notDue: number;
+}
+export interface CalendarSubscriptionRefreshDeps {
+    calendarCollection: Pick<ICalendarCollectionRepository, "listEnabledSubscriptions">;
+    calendarStore: ICalendarStore;
+    log: Logger;
+    fetcher?: CalendarFeedFetcher;
+}
+/**
+ * Re-reads every enabled subscription whose last fetch is at least
+ * `intervalMs` old. A disabled subscription is never listed, which is what
+ * stops its refresh while leaving its events in place.
+ *
+ * One feed's failure is recorded on its own collection and counted here; it
+ * never stops the others. The log names the calendar and the reason, never the
+ * URL, which for a Google secret address is the whole credential.
+ */
+export declare const refreshDueCalendarSubscriptions: (deps: CalendarSubscriptionRefreshDeps, now: number, intervalMs: number) => Promise<CalendarSubscriptionTally>;
+export declare const buildCalendarSubscriptionRefresh: (client: Pick<RemitClient, "calendarCollection" | "calendarStore">, log: Logger) => ((now: number, intervalMs: number) => Promise<CalendarSubscriptionTally>);

package/dist/scheduler/calendar-subscriptions.js

@@ -0,0 +1,35 @@
+import { isSubscriptionDue, refreshCalendarSubscription, } from "@remit/calendar-service";
+import pMap from "p-map";
+const REFRESH_CONCURRENCY = 4;
+/**
+ * Re-reads every enabled subscription whose last fetch is at least
+ * `intervalMs` old. A disabled subscription is never listed, which is what
+ * stops its refresh while leaving its events in place.
+ *
+ * One feed's failure is recorded on its own collection and counted here; it
+ * never stops the others. The log names the calendar and the reason, never the
+ * URL, which for a Google secret address is the whole credential.
+ */
+export const refreshDueCalendarSubscriptions = async (deps, now, intervalMs) => {
+    const enabled = await deps.calendarCollection.listEnabledSubscriptions();
+    const due = enabled.filter((collection) => isSubscriptionDue(collection, now, intervalMs));
+    const outcomes = await pMap(due, (collection) => refreshCalendarSubscription(deps.calendarStore, collection, now, deps.fetcher).then((refresh) => {
+        if (refresh.ok)
+            return true;
+        deps.log.warn({ calendarId: collection.calendarId, reason: refresh.reason }, "Calendar subscription could not be refreshed");
+        return false;
+    }, (error) => {
+        deps.log.error({ calendarId: collection.calendarId, error }, "Calendar subscription refresh failed");
+        return false;
+    }), { concurrency: REFRESH_CONCURRENCY });
+    return {
+        refreshed: outcomes.filter(Boolean).length,
+        failed: outcomes.filter((ok) => !ok).length,
+        notDue: enabled.length - due.length,
+    };
+};
+export const buildCalendarSubscriptionRefresh = (client, log) => (now, intervalMs) => refreshDueCalendarSubscriptions({
+    calendarCollection: client.calendarCollection,
+    calendarStore: client.calendarStore,
+    log,
+}, now, intervalMs);

package/dist/scheduler/config.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Periodic mailbox-sync scheduler (#1247, restructured #1251): the tick rate
+ * and the offline-sync threshold are separate, independently configured
+ * knobs — never hardcode a cadence — following the repo's
+ * env-var-with-a-safe-default convention (see `METRICS_PORT` in
+ * remit-logger-lambda/src/metrics.ts).
+ *
+ * `tickIntervalSeconds` drives how often the tick itself runs — the
+ * EventBridge schedule rate on a managed deployment, the runner's loop delay
+ * everywhere else — and must stay well below `offlineIntervalSeconds` so a tick
+ * reliably observes every account crossing the threshold. CDK and this runtime
+ * default must agree — see infra/lib/config.ts's `mailboxSync` stage config.
+ *
+ * `offlineIntervalSeconds` is the only due-ness threshold: an account is due
+ * once its last successful sync is older than this interval. There is no
+ * "online" tier — client-side polling (useStaleAccountSync) covers an
+ * account while its mail is actively open in the web client.
+ *
+ * The defaults below are a floor for a deployment that sets neither. The
+ * standalone stack sets both, at a cadence sized for one box and a handful of
+ * accounts, and the checker's stall threshold is derived from those values —
+ * see deploy/vps/docker-compose.sqlite.yml's `scheduler` service.
+ */
+export declare const getTickIntervalMs: (env?: NodeJS.ProcessEnv) => number;
+export declare const getOfflineIntervalMs: (env?: NodeJS.ProcessEnv) => number;
+export declare const SCHEDULER_PAGE_SIZE = 100;
+export declare const SCHEDULER_ENQUEUE_CONCURRENCY = 10;

package/{src/scheduler/config.ts → dist/scheduler/config.js}

@@ -21,35 +21,16 @@
  * accounts, and the checker's stall threshold is derived from those values —
  * see deploy/vps/docker-compose.sqlite.yml's `scheduler` service.
  */
-
 const DEFAULT_TICK_INTERVAL_SECONDS = 60 * 60; // 1 hour
 const DEFAULT_OFFLINE_INTERVAL_SECONDS = 12 * 60 * 60; // 12 hours
-
-const parsePositiveIntSeconds = (
-	raw: string | undefined,
-	fallback: number,
-): number => {
-	if (!raw) return fallback;
-	const parsed = Number.parseInt(raw, 10);
-	return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+const parsePositiveIntSeconds = (raw, fallback) => {
+    if (!raw)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 };
-
-export const getTickIntervalMs = (
-	env: NodeJS.ProcessEnv = process.env,
-): number =>
-	parsePositiveIntSeconds(
-		env.MAILBOX_SYNC_TICK_INTERVAL_SECONDS,
-		DEFAULT_TICK_INTERVAL_SECONDS,
-	) * 1000;
-
-export const getOfflineIntervalMs = (
-	env: NodeJS.ProcessEnv = process.env,
-): number =>
-	parsePositiveIntSeconds(
-		env.MAILBOX_SYNC_OFFLINE_INTERVAL_SECONDS,
-		DEFAULT_OFFLINE_INTERVAL_SECONDS,
-	) * 1000;
-
+export const getTickIntervalMs = (env = process.env) => parsePositiveIntSeconds(env.MAILBOX_SYNC_TICK_INTERVAL_SECONDS, DEFAULT_TICK_INTERVAL_SECONDS) * 1000;
+export const getOfflineIntervalMs = (env = process.env) => parsePositiveIntSeconds(env.MAILBOX_SYNC_OFFLINE_INTERVAL_SECONDS, DEFAULT_OFFLINE_INTERVAL_SECONDS) * 1000;
 // Page size + enqueue concurrency are implementation details of the tick
 // itself, not stage config — unlike the two intervals above, nothing outside
 // this worker needs to agree with them.

package/{src/scheduler/decide-due.ts → dist/scheduler/decide-due.d.ts}

@@ -10,17 +10,8 @@
  * misses an account by a few seconds simply catches it on the next tick,
  * which arrives long before the threshold matters again.
  */
-
 export interface SchedulableAccount {
-	readonly accountId: string;
-	readonly lastSyncAt?: number;
+    readonly accountId: string;
+    readonly lastSyncAt?: number;
 }
-
-export const isSyncDue = (
-	account: SchedulableAccount,
-	now: number,
-	offlineIntervalMs: number,
-): boolean => {
-	if (!account.lastSyncAt) return true;
-	return now - account.lastSyncAt >= offlineIntervalMs;
-};
+export declare const isSyncDue: (account: SchedulableAccount, now: number, offlineIntervalMs: number) => boolean;

package/dist/scheduler/decide-due.js

@@ -0,0 +1,17 @@
+/**
+ * Pure scheduling decision for the periodic mailbox-sync tick (#1247,
+ * restructured #1251).
+ *
+ * One tier: an account is due once its last successful sync is older than
+ * `offlineIntervalMs`. An account that has never synced is always due. The
+ * tick interval is decoupled from this threshold and runs far more often
+ * than `offlineIntervalMs` (see config.ts), so — unlike the prior two-tier
+ * design — no slack is needed to compensate for sampling lag: a tick that
+ * misses an account by a few seconds simply catches it on the next tick,
+ * which arrives long before the threshold matters again.
+ */
+export const isSyncDue = (account, now, offlineIntervalMs) => {
+    if (!account.lastSyncAt)
+        return true;
+    return now - account.lastSyncAt >= offlineIntervalMs;
+};

package/dist/scheduler/handler.d.ts

@@ -0,0 +1,21 @@
+import type { ScheduledHandler } from "aws-lambda";
+import type { WorkerQueues } from "../queues.js";
+/**
+ * EventBridge-scheduled entry point for the periodic mailbox-sync tick
+ * (#1247, restructured #1251). Ticks at `MAILBOX_SYNC_TICK_INTERVAL_SECONDS`
+ * (rate schedule, wired in infra/stacks/dev/stacks/remit-worker-stack.ts) and
+ * delegates the actual decision + enqueue to `runSchedulerTick` — the same
+ * function the timer loop calls on a deployment with no EventBridge (see
+ * `runner.ts`), so every deployment runs one code path.
+ *
+ * Uses the EventBridge event's own `time` (the scheduled fire time) as the
+ * tick's `now`, rather than `Date.now()` at processing time. This is what
+ * keeps `buildScheduledSyncDedupId`'s time bucket aligned to the schedule
+ * instead of wall-clock/Lambda-cold-start jitter (review #1250): every
+ * distinct scheduled firing gets a `time` exactly `tickIntervalMs` apart
+ * from the last, so consecutive ticks always land in different buckets,
+ * while a genuine retry of the same invocation carries the same `time` and
+ * correctly dedupes.
+ */
+export declare const buildScheduledHandler: (queues: WorkerQueues) => ScheduledHandler;
+export declare const handler: ScheduledHandler;

package/{src/scheduler/handler.ts → dist/scheduler/handler.js}

@@ -1,23 +1,15 @@
 import { getClient } from "@remit/backend/client";
 import { createLogger } from "@remit/logger";
 import { installNodeLogger, withTelemetry } from "@remit/logger-lambda/node";
-import type { ScheduledHandler } from "aws-lambda";
-import { createEmitEvent } from "../emit.js";
-import {
-	sqsWorkerQueues,
-	type WorkerQueues,
-	workerQueueUrlsFromEnv,
-} from "../queues.js";
+import { lambdaEmitEvent } from "../lambda-context.js";
+import { sqsWorkerQueues, workerQueueUrlsFromEnv } from "../sqs-queues.js";
 import { buildAttachmentSweep } from "./attachment-sweep.js";
 import { buildCalendarSubscriptionRefresh } from "./calendar-subscriptions.js";
 import { getOfflineIntervalMs, getTickIntervalMs } from "./config.js";
 import { runSchedulerTick } from "./run-tick.js";
 import { redriveStrandedPlacements } from "./stranded-placement-redrive.js";
-
 installNodeLogger();
-
 const log = createLogger();
-
 /**
  * EventBridge-scheduled entry point for the periodic mailbox-sync tick
  * (#1247, restructured #1251). Ticks at `MAILBOX_SYNC_TICK_INTERVAL_SECONDS`
@@ -35,35 +27,26 @@ const log = createLogger();
  * while a genuine retry of the same invocation carries the same `time` and
  * correctly dedupes.
  */
-export const buildScheduledHandler = (queues: WorkerQueues): ScheduledHandler =>
-	withTelemetry(async (event) => {
-		const client = await getClient();
-		const now = Date.parse(event.time);
-
-		await runSchedulerTick({
-			accountService: client.account,
-			queue: queues.mailboxes,
-			log,
-			tickIntervalMs: getTickIntervalMs(),
-			offlineIntervalMs: getOfflineIntervalMs(),
-			now,
-			// The hosted side is the one that needs this: a browser PUTs straight
-			// to block storage, so nothing refuses an upload against a draft that is
-			// already gone and this sweep is the only thing that collects it.
-			sweepAttachments: buildAttachmentSweep(client, log),
-			refreshCalendarSubscriptions: buildCalendarSubscriptionRefresh(
-				client,
-				log,
-			),
-			redriveStrandedPlacements: (account, tickNow) =>
-				redriveStrandedPlacements(
-					{ client, emit: createEmitEvent(queues), log },
-					account,
-					tickNow,
-				),
-		});
-	});
-
-export const handler: ScheduledHandler = buildScheduledHandler(
-	sqsWorkerQueues(workerQueueUrlsFromEnv()),
-);
+export const buildScheduledHandler = (queues) => withTelemetry(async (event) => {
+    const client = await getClient();
+    const now = Date.parse(event.time);
+    await runSchedulerTick({
+        accountService: client.account,
+        queue: queues.mailboxes,
+        log,
+        tickIntervalMs: getTickIntervalMs(),
+        offlineIntervalMs: getOfflineIntervalMs(),
+        now,
+        // The hosted side is the one that needs this: a browser PUTs straight
+        // to block storage, so nothing refuses an upload against a draft that is
+        // already gone and this sweep is the only thing that collects it.
+        sweepAttachments: buildAttachmentSweep(client, log),
+        refreshCalendarSubscriptions: buildCalendarSubscriptionRefresh(client, log),
+        redriveStrandedPlacements: (account, tickNow) => redriveStrandedPlacements({
+            client,
+            emit: lambdaEmitEvent(queues, client.mailboxLock),
+            log,
+        }, account, tickNow),
+    });
+});
+export const handler = buildScheduledHandler(sqsWorkerQueues(workerQueueUrlsFromEnv()));

package/{src/scheduler/loop.ts → dist/scheduler/loop.d.ts}

@@ -1,7 +1,5 @@
-import { setTimeout as delay } from "node:timers/promises";
 import type { Heartbeat } from "@remit/sqs-client/heartbeat";
 import type { RunSchedulerTickDeps, SchedulerTickResult } from "./run-tick.js";
-
 /**
  * The scheduled-sync loop, separated from the wiring in runner.ts for the same
  * reason `runQueuePoller` is separate from the container that starts it: the
@@ -14,25 +12,11 @@ import type { RunSchedulerTickDeps, SchedulerTickResult } from "./run-tick.js";
  * healthy for as long as it kept crashing.
  */
 export interface SchedulerLoopOptions {
-	readonly tick: (deps: RunSchedulerTickDeps) => Promise<SchedulerTickResult>;
-	readonly tickDeps: RunSchedulerTickDeps;
-	readonly heartbeat: Heartbeat;
-	readonly onHeartbeatError: (error: unknown) => void;
-	readonly tickIntervalMs: number;
-	readonly wait?: (ms: number) => Promise<void>;
+    readonly tick: (deps: RunSchedulerTickDeps) => Promise<SchedulerTickResult>;
+    readonly tickDeps: RunSchedulerTickDeps;
+    readonly heartbeat: Heartbeat;
+    readonly onHeartbeatError: (error: unknown) => void;
+    readonly tickIntervalMs: number;
+    readonly wait?: (ms: number) => Promise<void>;
 }
-
-export const runSchedulerLoop = async ({
-	tick,
-	tickDeps,
-	heartbeat,
-	onHeartbeatError,
-	tickIntervalMs,
-	wait = (ms) => delay(ms),
-}: SchedulerLoopOptions): Promise<never> => {
-	for (;;) {
-		await tick(tickDeps);
-		await heartbeat().catch(onHeartbeatError);
-		await wait(tickIntervalMs);
-	}
-};
+export declare const runSchedulerLoop: ({ tick, tickDeps, heartbeat, onHeartbeatError, tickIntervalMs, wait, }: SchedulerLoopOptions) => Promise<never>;

package/dist/scheduler/loop.js

@@ -0,0 +1,8 @@
+import { setTimeout as delay } from "node:timers/promises";
+export const runSchedulerLoop = async ({ tick, tickDeps, heartbeat, onHeartbeatError, tickIntervalMs, wait = (ms) => delay(ms), }) => {
+    for (;;) {
+        await tick(tickDeps);
+        await heartbeat().catch(onHeartbeatError);
+        await wait(tickIntervalMs);
+    }
+};

package/dist/scheduler/run-tick.d.ts

@@ -0,0 +1,62 @@
+import { type SyncMailboxesEvent } from "@remit/backend/trigger-sync";
+import type { AccountItem, FifoQueueProducer, IAccountRepository } from "@remit/data-ports";
+import type { Logger } from "@remit/logger";
+import type { CalendarSubscriptionTally } from "./calendar-subscriptions.js";
+export interface RunSchedulerTickDeps {
+    accountService: Pick<IAccountRepository, "listAllAccountsPage">;
+    queue: FifoQueueProducer<SyncMailboxesEvent>;
+    log: Logger;
+    offlineIntervalMs: number;
+    /**
+     * How often this tick itself runs — the dedup-id bucket width for
+     * `buildScheduledSyncDedupId`, so consecutive ticks each get a fresh id.
+     */
+    tickIntervalMs: number;
+    /** Injectable for tests; defaults to `Date.now()`. */
+    now?: number;
+    /**
+     * Collect attachment bytes the database does not know about, for one account.
+     *
+     * The tick already walks every account on a cadence, which is the only thing
+     * this needs. It exists because an upload URL minted for a draft stays valid
+     * after that draft is discarded, and where the browser writes straight to
+     * block storage nothing is in the path to refuse it — see
+     * `sweepAbandonedOutboxAttachments`. Optional only so a test can leave it out;
+     * both real entry points pass it.
+     */
+    sweepAttachments?: (account: AccountItem) => Promise<void>;
+    /**
+     * Re-read the calendar subscriptions whose last fetch is older than
+     * `offlineIntervalMs` — the same knob that says how stale mail may get.
+     * Optional only so a test can leave it out; both real entry points pass it.
+     */
+    refreshCalendarSubscriptions?: (now: number, intervalMs: number) => Promise<CalendarSubscriptionTally>;
+    redriveStrandedPlacements: (account: AccountItem, now: number) => Promise<number>;
+}
+export interface SchedulerTickResult {
+    scanned: number;
+    enqueued: number;
+    skipped: number;
+    swept: number;
+    sweepFailed: number;
+    subscriptionsRefreshed: number;
+    subscriptionsFailed: number;
+    redriven: number;
+    redriveFailed: number;
+}
+/**
+ * One tick of the periodic mailbox-sync scheduler (#1247, restructured
+ * #1251). Pages through every account (never loading the whole account base
+ * into memory), decides per account via `isSyncDue` against the single
+ * offline threshold, and enqueues SYNC_MAILBOXES for the accounts that are
+ * due — in bounded-concurrency batches, never an unbounded `Promise.all`.
+ *
+ * Every enqueue goes through the same `triggerAccountSync` the manual
+ * POST /sync path uses, with a scheduler-specific, time-bucketed dedup id
+ * (`buildScheduledSyncDedupId`, bucketed by `tickIntervalMs`) so this tick
+ * can never collide with its own previous tick or with a concurrent manual
+ * trigger (see trigger-sync.ts). Concurrent-sync safety for the mailbox
+ * itself is MailboxLockService's job, inside the worker handler — this tick
+ * only decides "is a sync due" and enqueues; it never talks to IMAP.
+ */
+export declare const runSchedulerTick: (deps: RunSchedulerTickDeps) => Promise<SchedulerTickResult>;