@remit/backend 0.0.142 → 0.0.144

package/dist/src/service/organize.js

@@ -0,0 +1,384 @@
+import { NotFoundError } from "@remit/data-ports/errors";
+import { FilterClauseField, FilterDisabledReason, FilterState, } from "@remit/domain-enums";
+import { logger } from "@remit/logger";
+import { FilterPipeline, literalClausesMatch, literalClauseTerms, NO_ACTION, PlacementMoveService, } from "@remit/mailbox-service";
+import { buildFilterConfig } from "@remit/mailbox-service/filter-config";
+/**
+ * Hard cap on both the previewed and the applied set. A back-apply is a
+ * data-heavy corpus pass (remit-data-heavy: frugal), bounded by counting
+ * MATCHES as it pages a store-side narrowed listing, and the final match set
+ * never exceeds this. It bounds the answer, never the corpus the question is
+ * asked of (#459).
+ */
+export const ORGANIZE_MATCH_LIMIT = 500;
+/**
+ * The predicate a back-apply job snapshotted onto its row, read back verbatim so
+ * the worker runs exactly what the request asked for.
+ */
+export const predicateFromJob = (job) => ({
+    matchOperator: job.matchOperator,
+    literalClauses: job.literalClauses,
+    actionLabelId: job.actionLabelId,
+    actionMailboxId: job.actionMailboxId,
+});
+/**
+ * A `HasWords` clause matches the message body (RFC 031, `clauseMatches`). The
+ * live index-time filter evaluates it against the full parsed body
+ * (`body-sync.ts` `toFilterMessage`); the corpus slice carries only
+ * `From`/`Subject` at full fidelity and no faithful body, so it cannot serve a
+ * body-content clause without silently narrowing the match to whatever preview
+ * happened to be stored. A body-content clause on an "all like these" pass is
+ * refused instead of returning a wrong set.
+ */
+export const BODY_CONTENT_REJECTION_MESSAGE = "Organize cannot match a body-content (HasWords) clause over the mailbox: it reads only each message's preview, not its body";
+const bodyContentRejection = (clauses) => clauses.some((clause) => clause.field === FilterClauseField.HasWords)
+    ? {
+        reason: "BodyContentUnsupported",
+        message: BODY_CONTENT_REJECTION_MESSAGE,
+    }
+    : null;
+/**
+ * The refusal a predicate carries on its own, decidable without reading the
+ * corpus: a body-content clause is refused up front. `createOrganizeJob` runs
+ * this before enqueueing and {@link matchOrganize} runs it too, so preview, the
+ * worker and the request boundary all refuse the same rule (reader #463).
+ */
+export const organizePredicateRejection = (predicate) => bodyContentRejection(predicate.literalClauses);
+/**
+ * The store selects on the clause terms, this refines what it returned and
+ * stops at `limit` MATCHES. Serves `From`/`Subject` clauses at
+ * full fidelity from the core thread rows; body-content (`HasWords`) clauses are
+ * refused before this runs (see {@link bodyContentRejection}).
+ *
+ * The terms are a narrowing, not the verdict ({@link literalClauseTerms}), so
+ * every page is still run through {@link literalClausesMatch} — and paging
+ * continues until the cap fills or the store runs out, which is what makes the
+ * bound a bound on results rather than on the newest `limit` rows (#459).
+ * Deduped by message id: the same mail filed in two folders is one match.
+ */
+const matchLiteral = async (deps, accountConfigId, predicate, limit, scope) => {
+    const clauses = predicate.literalClauses;
+    const narrowing = literalClauseTerms(clauses, predicate.matchOperator);
+    if (!narrowing)
+        return [];
+    const matched = [];
+    const seen = new Set();
+    let continuationToken;
+    do {
+        const page = await deps.listAccountFilterMessages(accountConfigId, {
+            ...narrowing,
+            limit,
+            continuationToken,
+            mailboxIds: scope.mailboxIds,
+        });
+        for (const { messageId, message } of page.items) {
+            if (seen.has(messageId))
+                continue;
+            seen.add(messageId);
+            if (!literalClausesMatch(clauses, predicate.matchOperator, message)) {
+                continue;
+            }
+            matched.push(messageId);
+            if (matched.length >= limit)
+                return matched;
+        }
+        continuationToken = page.continuationToken;
+    } while (continuationToken);
+    return matched;
+};
+/**
+ * The matcher shared by preview and apply — the previewed set equals the applied
+ * set for the same input. Read-only. Returns the matching message ids, bounded.
+ *
+ * - An ad-hoc predicate with no clause matches nothing: a run-now request
+ *   carries none, and an empty predicate must never sweep the whole mailbox.
+ * - A predicate the corpus read cannot evaluate (a body-content clause on an
+ *   "all like these" pass, see {@link bodyContentRejection}) comes back as a
+ *   rejection, so a caller can tell a refused rule from a broken deployment
+ *   (reader #463).
+ */
+export const matchOrganize = async (deps, accountConfigId, predicate, limit = ORGANIZE_MATCH_LIMIT, scope = {}) => {
+    if (predicate.literalClauses.length === 0) {
+        return { rejected: null, messageIds: [] };
+    }
+    const rejection = scope.filterId
+        ? null
+        : organizePredicateRejection(predicate);
+    if (rejection)
+        return { rejected: rejection };
+    const messageIds = await matchLiteral(deps, accountConfigId, predicate, limit, scope);
+    return { rejected: null, messageIds };
+};
+/**
+ * The corpus read for a back-apply: one page of the account's messages,
+ * newest-first across every mailbox, with the clause terms evaluated in the
+ * query.
+ *
+ * `From`/`Subject`/`listId` come from the row verbatim (full fidelity), so a
+ * `From`, `Subject`, `FromDomain` or `ListId` clause matches here exactly as it
+ * does at index time. `text` is the row's stored body preview (`snippet`),
+ * the same text search matches free words against. An "all like these" pass
+ * refuses a body-content (`HasWords`) clause before reading it (see
+ * {@link bodyContentRejection}); a filter back-apply matches it on the
+ * preview, the mail search showed the user when the rule was made (#1354).
+ */
+const listAccountFilterMessagesFromClient = (client) => async (accountConfigId, query) => {
+    const page = await client.threadMessage.listByFieldTerms(accountConfigId, query.terms, {
+        operator: query.operator,
+        limit: query.limit,
+        continuationToken: query.continuationToken,
+        excludeDeleted: true,
+        mailboxIds: query.mailboxIds,
+    });
+    return {
+        items: page.items.map((row) => ({
+            messageId: row.messageId,
+            message: {
+                from: row.fromEmail ?? "",
+                fromName: row.fromName ?? "",
+                subject: row.subject ?? "",
+                text: row.snippet ?? "",
+                listId: row.listId ?? "",
+            },
+        })),
+        continuationToken: page.continuationToken,
+    };
+};
+/** The matcher deps for the running backend/worker. */
+export const buildOrganizeMatchDeps = (client) => ({
+    listAccountFilterMessages: listAccountFilterMessagesFromClient(client),
+});
+/**
+ * The exclusive-move arm of a back-apply, wired exactly like the body-sync
+ * placement mover (`sync-message-body.ts`): the local-first
+ * {@link PlacementMoveService} over the shared message-management queue. A move
+ * commits locally (marker + ThreadMessage + Message row) and enqueues a
+ * `PLACEMENT_MOVE_PUSH` for the reconciler; its marker state engine makes a
+ * redelivered job idempotent (mirrors #1297). Returns `undefined` when no
+ * message-management queue is wired — the same gate body sync uses to keep the
+ * move path off — so a move requested in that environment is counted as failed
+ * rather than silently dropped (see {@link applyOrganize}).
+ */
+export const buildOrganizeMoveService = (client) => {
+    const queueUrl = process.env.SQS_QUEUE_URL_MESSAGE_MGMT;
+    if (!queueUrl)
+        return undefined;
+    return new PlacementMoveService({
+        messageService: client.message,
+        threadMessageService: client.threadMessage,
+        markerService: client.placementMove,
+        addressService: client.address,
+        mailboxSpecialUseService: client.mailboxSpecialUse,
+        mailboxService: client.mailbox,
+        sqsQueueUrl: queueUrl,
+    });
+};
+/**
+ * Apply the back-apply action to every matched message, reusing the index-time
+ * apply plumbing: an idempotent MessageLabel upsert (additive) with
+ * `appliedByFilterId` deliberately ABSENT — this path attributes to no filter,
+ * exactly like a hand-applied label (RFC 034 Decision 3.3) — and an idempotent
+ * folder move (exclusive). One poisoned message never fails the batch; it is
+ * counted as failed and the pass continues.
+ *
+ * Every requested move happens. A standing filter acts at exactly two moments —
+ * when a message is first seen, and when the user presses "run rules now" — and
+ * holds no claim on that message afterwards, so it never arbitrates against a
+ * later user-initiated apply (reader #497). Cross-filter precedence stays where
+ * two filters collide over the same message at the same trigger
+ * (`FilterPipeline`/`selectMoveWinner`), and `applied` therefore counts moves
+ * that actually happened.
+ */
+export const applyOrganize = async (deps, accountConfigId, messageIds, predicate) => {
+    const { client, moveService } = deps;
+    const applyLabel = predicate.actionLabelId !== NO_ACTION && predicate.actionLabelId !== "";
+    const applyMove = predicate.actionMailboxId !== NO_ACTION && predicate.actionMailboxId !== "";
+    const applyToMessage = async (messageId) => {
+        if (applyMove) {
+            if (!moveService) {
+                // An exclusive move was requested but this caller wired no move
+                // service. Never silently pretend it applied — surface it as a
+                // failed message so the job's failedCount reflects reality.
+                throw new Error("Organize move action requested but no move service is wired");
+            }
+            const message = await client.message.get(messageId);
+            const accountId = await client.mailbox.resolveAccountId(message.mailboxId);
+            if (!accountId) {
+                throw new Error(`Cannot resolve owning account for mailbox ${message.mailboxId}`);
+            }
+            const outcome = await moveService.moveMessage(accountConfigId, messageId, predicate.actionMailboxId, accountId);
+            if (outcome === "refused")
+                return { kind: "skipped" };
+        }
+        if (applyLabel) {
+            await client.messageLabel.apply({
+                messageId,
+                labelId: predicate.actionLabelId,
+                accountConfigId,
+            });
+        }
+        return { kind: "applied" };
+    };
+    const result = {
+        applied: 0,
+        failed: 0,
+        failures: [],
+    };
+    for (const messageId of messageIds) {
+        // Per-message isolation: one poisoned message is counted, its reason kept
+        // for the job, and the pass continues.
+        const outcome = await applyToMessage(messageId).catch((error) => ({
+            kind: "failed",
+            reason: error instanceof Error ? error.message : String(error),
+        }));
+        if (outcome.kind === "skipped")
+            continue;
+        if (outcome.kind === "applied") {
+            result.applied += 1;
+            continue;
+        }
+        result.failed += 1;
+        result.failures.push(outcome.reason);
+        logger.warn({ accountConfigId, messageId, reason: outcome.reason }, "Organize could not apply its action to a message");
+    }
+    return result;
+};
+const FILTER_NOT_ACTIVE_MESSAGE = "This filter is turned off or has expired. Turn it on to run it over the inbox.";
+const FOLDER_MISSING_MESSAGE = "The folder this filter moves mail into no longer exists, so the filter was turned off. Pick another folder in the rule, then turn it on.";
+const FILTER_MISSING_MESSAGE = "This filter was deleted before it could run over the inbox.";
+const rejectFilter = (reason, message) => ({ rejected: { reason, message } });
+/** A standing filter's predicate and action, read the way index time reads them. */
+const predicateFromFilter = (filter) => ({
+    matchOperator: filter.matchOperator,
+    literalClauses: filter.literalClauses,
+    actionLabelId: filter.actionLabelId,
+    actionMailboxId: filter.actionMailboxId,
+});
+/**
+ * Read the filter a job names: refused when it was deleted or is not Active,
+ * since index time evaluates neither.
+ */
+const loadFilter = async (client, accountConfigId, filterId) => {
+    const stored = await client.filter
+        .get(accountConfigId, filterId)
+        .catch((error) => {
+        if (error instanceof NotFoundError)
+            return null;
+        throw error;
+    });
+    if (!stored)
+        return rejectFilter("FilterMissing", FILTER_MISSING_MESSAGE);
+    const filter = await client.filter.refreshExpiry(stored);
+    if (filter.state !== FilterState.Active) {
+        return rejectFilter("FilterNotActive", FILTER_NOT_ACTIVE_MESSAGE);
+    }
+    return { rejected: null, filter, predicate: predicateFromFilter(filter) };
+};
+/** Every inbox under the config — the folders a filter back-apply runs over. */
+const inboxMailboxIds = async (client, accountConfigId) => {
+    const accounts = await client.account.listMailSourcesByAccountConfig(accountConfigId);
+    const inboxes = await Promise.all(accounts.map((account) => client.mailboxSpecialUse.findInboxMailbox(account.accountId)));
+    return inboxes.flatMap((inbox) => (inbox ? [inbox.mailboxId] : []));
+};
+/**
+ * The message as the index-time pipeline reads it, from its thread row. The
+ * body is the stored preview, so a `HasWords` clause matches what search
+ * matched. A message deleted since the match has no row.
+ */
+const filterMessageOf = async (client, accountConfigId, messageId) => {
+    const row = await client.threadMessage
+        .getByMessageId(accountConfigId, messageId)
+        .catch((error) => {
+        if (error instanceof NotFoundError)
+            return null;
+        throw error;
+    });
+    if (!row)
+        return null;
+    return {
+        from: row.fromEmail ?? "",
+        fromName: row.fromName ?? "",
+        subject: row.subject ?? "",
+        text: row.snippet ?? "",
+        listId: row.listId ?? "",
+    };
+};
+/**
+ * Run one standing filter over the inbox as if each matching message had just
+ * arrived. Every message the matcher returns is a match: its label always
+ * applies, being additive. The index-time {@link FilterPipeline} only orders
+ * the exclusive move, so the move is skipped where it names another active
+ * filter. The pipeline sees the stored preview rather than the full body, so
+ * its verdict on whether this filter matches is not asked; and an evaluate it
+ * could not finish names no other filter, so the move goes ahead rather than
+ * silently dropping out.
+ */
+export const backApplyFilter = async (deps, accountConfigId, filterId) => {
+    const { client, matchDeps, moveService } = deps;
+    const loaded = await loadFilter(client, accountConfigId, filterId);
+    if (loaded.rejected)
+        return loaded;
+    const config = buildFilterConfig({
+        filterService: client.filter,
+        messageLabelService: client.messageLabel,
+        mailboxService: client.mailbox,
+        placementMoveService: moveService,
+    });
+    if (!config) {
+        throw new Error("Filter back-apply needs the message-management queue to move mail");
+    }
+    const pipeline = new FilterPipeline(config, logger);
+    const mailboxIds = await inboxMailboxIds(client, accountConfigId);
+    const nothing = {
+        rejected: null,
+        matched: 0,
+        applied: 0,
+        failed: 0,
+        failures: [],
+    };
+    if (mailboxIds.length === 0)
+        return nothing;
+    const match = await matchOrganize(matchDeps, accountConfigId, loaded.predicate, ORGANIZE_MATCH_LIMIT, { filterId, mailboxIds });
+    if (match.rejected)
+        return match;
+    const { filter, predicate } = loaded;
+    const folderAccountId = filter.actionMailboxId === NO_ACTION
+        ? undefined
+        : await client.mailbox.resolveAccountId(filter.actionMailboxId);
+    if (folderAccountId === null) {
+        await client.filter.update(accountConfigId, filterId, {
+            state: FilterState.Disabled,
+            disabledReason: FilterDisabledReason.FolderMissing,
+        });
+        return rejectFilter("FolderMissing", FOLDER_MISSING_MESSAGE);
+    }
+    const result = {
+        ...nothing,
+        matched: match.messageIds.length,
+    };
+    for (const messageId of match.messageIds) {
+        const message = await filterMessageOf(client, accountConfigId, messageId);
+        if (!message)
+            continue;
+        const accountId = await client.mailbox.resolveAccountId((await client.message.get(messageId)).mailboxId);
+        if (!accountId)
+            continue;
+        if (folderAccountId !== undefined && folderAccountId !== accountId) {
+            continue;
+        }
+        const decision = await pipeline.evaluate(accountConfigId, accountId, messageId, message);
+        const move = (decision.move?.filterId ?? filterId) === filterId;
+        if (!move && filter.actionLabelId === NO_ACTION)
+            continue;
+        const outcome = await applyOrganize({ client, moveService }, accountConfigId, [messageId], {
+            ...predicate,
+            actionMailboxId: move ? filter.actionMailboxId : NO_ACTION,
+        });
+        result.applied += outcome.applied;
+        result.failed += outcome.failed;
+        result.failures.push(...outcome.failures);
+    }
+    return result;
+};
+/** Whether a job row runs a standing filter rather than its own snapshot. */
+export const isFilterJob = (job) => job.filterId !== NO_ACTION;

package/dist/src/service/refusal.d.ts

@@ -0,0 +1,4 @@
+import { type HTTPError } from "@remit/data-ports/errors";
+import type { Refusable, Refusal } from "@remit/mailbox-service";
+export declare const refusalError: (refusal: Refusal) => HTTPError;
+export declare const unwrap: <T>(outcome: Refusable<T>) => T;

package/dist/src/service/refusal.js

@@ -0,0 +1,20 @@
+import { BadRequestError, ConflictError, ForbiddenError, MailboxNotSettledError, NotFoundError, } from "@remit/data-ports/errors";
+export const refusalError = (refusal) => {
+    switch (refusal.kind) {
+        case "Invalid":
+            return new BadRequestError(refusal.message);
+        case "Forbidden":
+            return new ForbiddenError(refusal.message);
+        case "NotFound":
+            return new NotFoundError(refusal.message);
+        case "Conflict":
+            return new ConflictError(refusal.message);
+        case "NotSettled":
+            return new MailboxNotSettledError(refusal.message, refusal.mailboxId, refusal.syncStatus);
+    }
+};
+export const unwrap = (outcome) => {
+    if (outcome.ok)
+        return outcome.value;
+    throw refusalError(outcome.refusal);
+};

package/dist/src/service/sender-category.d.ts

@@ -0,0 +1,51 @@
+import type { MessageCategoryValue } from "@remit/mailbox-service";
+import type { RemitClient } from "./data-client.js";
+/**
+ * How much of a sender's already-classified mail one override reaches: the
+ * newest 500 of their messages held in the local store. A back-apply is a
+ * bounded recent batch, never the sender's whole history — the store-side
+ * narrowing pages until this many MATCHES, so a quiet sender's mail is reached
+ * however old it is, and a bulk sender's oldest mail is deliberately left as
+ * the classifier decided it. The same constant the organize back-apply bounds
+ * its match set with (`ORGANIZE_MATCH_LIMIT`), for the same reason.
+ */
+export declare const SENDER_CATEGORY_BACKAPPLY_LIMIT = 500;
+export interface SenderCategoryBackApplyDeps {
+    client: Pick<RemitClient, "message" | "threadMessage">;
+}
+export interface SenderCategoryBackApplyResult {
+    matched: number;
+    applied: number;
+    failed: number;
+}
+/**
+ * Back-apply a sender's `Address.flags.category` override to mail that was
+ * already classified before the override was set (#415). Issue #299 gave the
+ * override full effect on the sender's NEXT message only; this is the
+ * retroactive half, deliberately bounded to
+ * {@link SENDER_CATEGORY_BACKAPPLY_LIMIT}.
+ *
+ * This is the one path that intentionally rewrites an already-decided
+ * `Message.category`, so it does not — and must not — reuse body sync's
+ * `hasDecidedCategory` write-once guard. Its consistency story is that
+ * `category` is a key attribute of no provisioned index: the DynamoDB LSI that
+ * would have sorted on it was never provisioned and cannot be (#516), and the
+ * filtered-mailbox read path is served by the SQL-only
+ * `tm_by_mailbox_category_date` index, where an update simply moves the row.
+ * What a rewrite can still break is the Message/ThreadMessage pair disagreeing
+ * — the badge is served from the thread row and so is the category filter — so
+ * both are written per message, thread rows first, and a redelivered job
+ * re-runs the same idempotent writes.
+ *
+ * Nothing here touches placement: `category` is not an input to
+ * `classifyPlacement`, so an override re-labels mail where it already sits and
+ * files nothing. No remote mail-server state changes, which is why this is not
+ * an IMAP mutation and does not take the mutator pattern.
+ *
+ * Per-message isolation, exactly as `applyOrganize` has it: one poisoned
+ * message is counted as failed and the pass continues, so a single missing
+ * thread row never costs the other 499 their re-label. Unlike a job row, this
+ * count is not the end of the story — the caller is expected to leave a pass
+ * with failures unacknowledged so redelivery converges the rest.
+ */
+export declare const backApplySenderCategory: (deps: SenderCategoryBackApplyDeps, accountConfigId: string, normalizedEmail: string, category: MessageCategoryValue, limit?: number) => Promise<SenderCategoryBackApplyResult>;

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

@@ -1,7 +1,4 @@
-import type { MessageCategoryValue } from "@remit/mailbox-service";
 import { denormalizeMessageCategory } from "@remit/mailbox-service";
-import type { RemitClient } from "./data-client.js";
-
 /**
  * How much of a sender's already-classified mail one override reaches: the
  * newest 500 of their messages held in the local store. A back-apply is a
@@ -12,17 +9,6 @@ import type { RemitClient } from "./data-client.js";
  * its match set with (`ORGANIZE_MATCH_LIMIT`), for the same reason.
  */
 export const SENDER_CATEGORY_BACKAPPLY_LIMIT = 500;
-
-export interface SenderCategoryBackApplyDeps {
-	client: Pick<RemitClient, "message" | "threadMessage">;
-}
-
-export interface SenderCategoryBackApplyResult {
-	matched: number;
-	applied: number;
-	failed: number;
-}
-
 /**
  * The sender's newest messages in the local store, bounded at `limit`, newest
  * first and deduplicated by messageId.
@@ -34,36 +20,27 @@ export interface SenderCategoryBackApplyResult {
  * out, which is what makes the bound a bound on the sender's messages rather
  * than on how far back the read reached (#459).
  */
-const listSenderMessageIds = async (
-	deps: SenderCategoryBackApplyDeps,
-	accountConfigId: string,
-	normalizedEmail: string,
-	limit: number,
-): Promise<string[]> => {
-	const wanted = normalizedEmail.toLowerCase();
-	const messageIds: string[] = [];
-	const seen = new Set<string>();
-	let continuationToken: string | undefined;
-
-	do {
-		const page = await deps.client.threadMessage.listByFieldTerms(
-			accountConfigId,
-			[{ field: "sender", contains: wanted }],
-			{ limit, continuationToken, excludeDeleted: true },
-		);
-		for (const row of page.items) {
-			if (row.fromEmail?.toLowerCase() !== wanted) continue;
-			if (seen.has(row.messageId)) continue;
-			seen.add(row.messageId);
-			messageIds.push(row.messageId);
-			if (messageIds.length >= limit) return messageIds;
-		}
-		continuationToken = page.continuationToken;
-	} while (continuationToken);
-
-	return messageIds;
+const listSenderMessageIds = async (deps, accountConfigId, normalizedEmail, limit) => {
+    const wanted = normalizedEmail.toLowerCase();
+    const messageIds = [];
+    const seen = new Set();
+    let continuationToken;
+    do {
+        const page = await deps.client.threadMessage.listByFieldTerms(accountConfigId, [{ field: "sender", contains: wanted }], { limit, continuationToken, excludeDeleted: true });
+        for (const row of page.items) {
+            if (row.fromEmail?.toLowerCase() !== wanted)
+                continue;
+            if (seen.has(row.messageId))
+                continue;
+            seen.add(row.messageId);
+            messageIds.push(row.messageId);
+            if (messageIds.length >= limit)
+                return messageIds;
+        }
+        continuationToken = page.continuationToken;
+    } while (continuationToken);
+    return messageIds;
 };
-
 /**
  * Back-apply a sender's `Address.flags.category` override to mail that was
  * already classified before the override was set (#415). Issue #299 gave the
@@ -94,42 +71,24 @@ const listSenderMessageIds = async (
  * count is not the end of the story — the caller is expected to leave a pass
  * with failures unacknowledged so redelivery converges the rest.
  */
-export const backApplySenderCategory = async (
-	deps: SenderCategoryBackApplyDeps,
-	accountConfigId: string,
-	normalizedEmail: string,
-	category: MessageCategoryValue,
-	limit: number = SENDER_CATEGORY_BACKAPPLY_LIMIT,
-): Promise<SenderCategoryBackApplyResult> => {
-	const messageIds = await listSenderMessageIds(
-		deps,
-		accountConfigId,
-		normalizedEmail,
-		limit,
-	);
-
-	const relabel = async (messageId: string): Promise<void> => {
-		await denormalizeMessageCategory(
-			{ threadMessageService: deps.client.threadMessage },
-			accountConfigId,
-			messageId,
-			{ category },
-		);
-		await deps.client.message.update(messageId, { category });
-	};
-
-	let applied = 0;
-	let failed = 0;
-	for (const messageId of messageIds) {
-		const ok = await relabel(messageId)
-			.then(() => true)
-			.catch(() => false);
-		if (ok) {
-			applied += 1;
-		} else {
-			failed += 1;
-		}
-	}
-
-	return { matched: messageIds.length, applied, failed };
+export const backApplySenderCategory = async (deps, accountConfigId, normalizedEmail, category, limit = SENDER_CATEGORY_BACKAPPLY_LIMIT) => {
+    const messageIds = await listSenderMessageIds(deps, accountConfigId, normalizedEmail, limit);
+    const relabel = async (messageId) => {
+        await denormalizeMessageCategory({ threadMessageService: deps.client.threadMessage }, accountConfigId, messageId, { category });
+        await deps.client.message.update(messageId, { category });
+    };
+    let applied = 0;
+    let failed = 0;
+    for (const messageId of messageIds) {
+        const ok = await relabel(messageId)
+            .then(() => true)
+            .catch(() => false);
+        if (ok) {
+            applied += 1;
+        }
+        else {
+            failed += 1;
+        }
+    }
+    return { matched: messageIds.length, applied, failed };
 };

package/dist/src/service/sqs.d.ts

@@ -0,0 +1 @@
+export declare const sqsClient: import("@aws-sdk/client-sqs").SQSClient;

package/{src/service/sqs.ts → dist/src/service/sqs.js}

@@ -1,4 +1,3 @@
 import { createQueueProducer } from "@remit/sqs-client/producer";
 import { env } from "expect-env";
-
 export const sqsClient = createQueueProducer({ queueUrl: env.SQS_QUEUE_URL });

package/dist/src/service/trigger-sync.d.ts

@@ -0,0 +1,51 @@
+import { SendMessageCommand, type SQSClient } from "@aws-sdk/client-sqs";
+interface TriggerAccountSyncInput {
+    sqsClient: SQSClient;
+    queueUrl: string;
+    accountId: string;
+    /**
+     * Set by POST /sync, whose callers ask for a sync of one named account: the
+     * refresh control, pull-to-refresh, and the web client's automatic poll
+     * (`useStaleAccountSync`) — a timer, not a person. It travels on the event
+     * and makes the worker's fan-out sync every mailbox even if one just ran.
+     *
+     * Everything else triggers a sync as a side effect of doing something else
+     * (config load, OAuth connect, account create, the scheduled tick), leaves
+     * this unset, and takes the freshness gate — see `mailboxNeedsSync` in
+     * imap-worker's sync-mailboxes handler.
+     *
+     * How often a timer may do that is bounded on the client, by the poll's own
+     * floor (`MIN_POLL_INTERVAL_MS` in the client hook, 30s) rather than by the
+     * gate: `mailboxPollIntervalSeconds` can lengthen the interval, never
+     * shorten it past that.
+     */
+    explicitRequest?: boolean;
+    /**
+     * Override the FIFO `MessageDeduplicationId`. Defaults to the event's own
+     * id, so the queue suppresses a re-send of one event and nothing else —
+     * every manual call site (POST /sync, OAuth connect, config load,
+     * pull-to-refresh, the client's online-poll) always enqueues. A shared,
+     * time-bucketed id instead turned SQS's 5-minute window into a rate limiter
+     * and silently discarded a sync the user asked for whenever one had run
+     * recently (issue #37). What a trigger costs is bounded in the worker's
+     * fan-out (`mailboxNeedsSync`), by skipping mailboxes not worth
+     * re-enumerating — never by dropping the trigger.
+     *
+     * The scheduled-sync tick (#1247) passes `buildScheduledSyncDedupId()`,
+     * which is bucketed by the tick's own cadence: there it collapses a
+     * re-invocation of a single tick, never two ticks or a manual trigger.
+     */
+    dedupId?: string;
+}
+/**
+ * Build the scheduler's own dedup namespace, bucketed by tick interval so
+ * consecutive ticks each get a fresh id (never colliding with each other)
+ * while still deduping a genuine double-invocation of the same tick (e.g. a
+ * retried Lambda) — see `dedupId` above.
+ */
+export declare const buildScheduledSyncDedupId: (accountId: string, now: number, bucketMs: number) => string;
+export declare const buildSyncMailboxesCommand: (input: Omit<TriggerAccountSyncInput, "sqsClient">) => SendMessageCommand;
+export declare const triggerAccountSync: (input: TriggerAccountSyncInput) => Promise<{
+    eventId: string;
+}>;
+export {};