@remit/web-client 0.0.325 → 0.0.327

package/dist/src/lib/organize/filter-edit-model.js

@@ -0,0 +1,104 @@
+import { pickedDateToExpiresAt } from "./filter-status";
+import { NO_ACTION } from "./organize-model";
+/**
+ * The persisted filter as the chip editor's rule (RFC 038 D6). Loads the whole
+ * rule the user edits: literal clauses, the match operator, the move action, and
+ * the scope (and, for a Temporary filter, the date it stops on).
+ *
+ * The scope maps `Standing` → "standing" and `Temporary` → "until"; a persisted
+ * filter is never the one-time "once" scope. `moveMailboxId` and `labelId` both
+ * drop the `"None"` sentinel to `undefined` so an empty select reads as "no
+ * action" (issue #26).
+ */
+export const filterToRule = (filter) => {
+    const clauses = filter.literalClauses.map((clause, index) => ({
+        id: `clause-${index}`,
+        field: clause.field,
+        value: clause.value,
+    }));
+    return {
+        clauses,
+        matchOperator: filter.matchOperator === "And" ? "all" : "any",
+        moveMailboxId: filter.actionMailboxId !== NO_ACTION ? filter.actionMailboxId : undefined,
+        labelId: filter.actionLabelId !== NO_ACTION ? filter.actionLabelId : undefined,
+        scope: filter.scope === "Temporary" ? "until" : "standing",
+        until: filter.scope === "Temporary"
+            ? expiresAtToPickedDate(filter.expiresAt)
+            : undefined,
+        name: filter.name,
+    };
+};
+/**
+ * The `YYYY-MM-DD` the date input shows for a stored `expiresAt`. The inverse of
+ * {@link pickedDateToExpiresAt}: it reads the local calendar day the timestamp
+ * falls on, so a date picked, saved, and reopened comes back unchanged. Empty
+ * or unparseable input yields an empty string — the picker's "no date" state.
+ */
+export const expiresAtToPickedDate = (expiresAt) => {
+    if (!expiresAt)
+        return "";
+    const ms = Date.parse(expiresAt);
+    if (Number.isNaN(ms))
+        return "";
+    const date = new Date(ms);
+    const pad = (value) => String(value).padStart(2, "0");
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+};
+const predicateActionKey = (rule) => JSON.stringify({
+    clauses: rule.clauses.map((clause) => [clause.field, clause.value]),
+    operator: rule.matchOperator,
+    move: rule.moveMailboxId ?? null,
+    label: rule.labelId ?? null,
+});
+/**
+ * Whether the edited rule changes the predicate or the action versus the one it
+ * was loaded from — the clauses, the match operator, the move target, the
+ * or the label target. A change here is what bumps
+ * `ruleChangedAt` and offers the re-back-apply (RFC 034 Decision 3.2); the name
+ * is deliberately excluded, so a cosmetic rename is not a rule change.
+ */
+export const ruleChangesPredicateOrAction = (rule, original) => predicateActionKey(rule) !== predicateActionKey(original);
+const scopeExpiryKey = (rule) => JSON.stringify({
+    scope: rule.scope === "until" ? "until" : "standing",
+    until: rule.scope === "until" ? (rule.until ?? "") : "",
+});
+/**
+ * Whether the edited rule changes scope (standing ↔ until-a-date) or the date
+ * itself, versus the one it was loaded from (reader #266). Scope and expiry
+ * are mutable on an existing filter, and a change here
+ * bumps `ruleChangedAt` the same way a predicate/action change does — moving a
+ * lapsed filter back to Standing (or extending its date) is the same kind of
+ * "the user just reasserted this rule" moment, and re-offers the back-apply so
+ * mail delivered while the filter sat inactive can be caught up.
+ */
+export const ruleChangesScopeOrExpiry = (rule, original) => scopeExpiryKey(rule) !== scopeExpiryKey(original);
+/**
+ * The PATCH body for an edited filter. A cosmetic rename sends `{ name }` only,
+ * so the server's `changesRuleAssertion` guard leaves `ruleChangedAt`
+ * untouched (RFC 034 Decision 3.2). A predicate or action change sends the
+ * operator, clauses, move target, and label target; a scope or expiry change
+ * sends `scope` and, for the `until` scope, `expiresAt` (reader #266) —
+ * either bumps `ruleChangedAt`.
+ */
+export const buildUpdateFilterInput = (rule, original) => {
+    const body = {};
+    const name = (rule.name ?? "").trim();
+    if (name !== (original.name ?? "").trim())
+        body.name = name;
+    if (ruleChangesPredicateOrAction(rule, original)) {
+        body.matchOperator = rule.matchOperator === "all" ? "And" : "Or";
+        body.literalClauses = rule.clauses.map((clause) => ({
+            field: clause.field,
+            value: clause.value,
+        }));
+        body.actionMailboxId = rule.moveMailboxId ?? NO_ACTION;
+        body.actionLabelId = rule.labelId ?? NO_ACTION;
+    }
+    if (ruleChangesScopeOrExpiry(rule, original)) {
+        body.scope = rule.scope === "until" ? "Temporary" : "Standing";
+        if (rule.scope === "until") {
+            body.expiresAt = pickedDateToExpiresAt(rule.until ?? "");
+        }
+    }
+    return body;
+};

package/dist/src/lib/organize/filter-run.d.ts

@@ -0,0 +1,27 @@
+import type { OrganizeJobFailure, OrganizeJobProgress } from "../../hooks/useOrganizeJob";
+/** Where a Run now stands, as the filter's row says it. */
+export type FilterRunStatus = {
+    kind: "queuing";
+} | {
+    kind: "running";
+} | {
+    kind: "done";
+    matched: number;
+    applied: number;
+} | {
+    kind: "failed";
+    error: unknown;
+};
+export interface FilterRunReading {
+    progress: OrganizeJobProgress;
+    failure: OrganizeJobFailure | undefined;
+    isStarting: boolean;
+    isRunning: boolean;
+    isDone: boolean;
+}
+/**
+ * The row's status for the job a Run now started. A job the worker failed —
+ * a filter turned off since, or deleted — is a failure like a refused start,
+ * never a lingering "running".
+ */
+export declare const filterRunStatus: (reading: FilterRunReading) => FilterRunStatus | undefined;

package/dist/src/lib/organize/filter-run.js

@@ -0,0 +1,27 @@
+/**
+ * The row's status for the job a Run now started. A job the worker failed —
+ * a filter turned off since, or deleted — is a failure like a refused start,
+ * never a lingering "running".
+ */
+export const filterRunStatus = (reading) => {
+    if (reading.failure)
+        return { kind: "failed", error: reading.failure.error };
+    if (reading.isStarting)
+        return { kind: "queuing" };
+    if (reading.isDone) {
+        if (reading.progress.state === "Failed") {
+            return {
+                kind: "failed",
+                error: new Error(reading.progress.errorMessage || "The run over the inbox failed."),
+            };
+        }
+        return {
+            kind: "done",
+            matched: reading.progress.matchedCount,
+            applied: reading.progress.appliedCount,
+        };
+    }
+    if (reading.isRunning)
+        return { kind: "running" };
+    return undefined;
+};

package/dist/src/lib/organize/filter-status.d.ts

@@ -0,0 +1,30 @@
+import type { RemitImapFilterResponse } from "@remit/api-http-client/types.gen.ts";
+export type FilterDisplayStatus = "Active" | "Expired" | "Disabled";
+export type FilterDisabledReason = RemitImapFilterResponse["disabledReason"];
+/**
+ * The displayed Active/Expired status of a filter.
+ *
+ * RFC 034 Decision 1.2: `expiresAt` is the source of truth, `state` is only a
+ * lazily-patched cache. A `Temporary` filter whose `expiresAt` is in the past
+ * is Expired the instant that comparison is made, even if the server has not
+ * yet patched `state` to `Expired`. So the client compares `expiresAt` against
+ * `now` directly and also honors a `state` the server already flipped.
+ *
+ * An `Expired` filter is never hidden — it stays listed so the user can see
+ * what it was and when it stopped (RFC 034 Decision 1.2, "stops on its own").
+ */
+export declare const filterDisplayStatus: (filter: Pick<RemitImapFilterResponse, "scope" | "expiresAt" | "state">, now: number) => FilterDisplayStatus;
+export declare const disabledReasonCopy: (filter: Pick<RemitImapFilterResponse, "disabledReason" | "actionMailboxId">) => string | undefined;
+/**
+ * Human-readable rendering of an expiry timestamp, e.g. "Jul 16, 2026".
+ * Returns `undefined` for an absent or unparseable value so a standing filter
+ * (no `expiresAt`) renders nothing.
+ */
+export declare const formatExpiresAt: (expiresAt: string | undefined) => string | undefined;
+/**
+ * Turn a plain picked calendar date (`YYYY-MM-DD`, from a native date input)
+ * into an ISO 8601 timestamp with the local zone offset, at end of that day —
+ * the filter is meant to stay active through the whole picked day (RFC 034
+ * Decision 1.1, a zoned civil date). Returns `undefined` for empty input.
+ */
+export declare const pickedDateToExpiresAt: (pickedDate: string, referenceDate?: Date) => string | undefined;

package/dist/src/lib/organize/filter-status.js

@@ -0,0 +1,84 @@
+/**
+ * The displayed Active/Expired status of a filter.
+ *
+ * RFC 034 Decision 1.2: `expiresAt` is the source of truth, `state` is only a
+ * lazily-patched cache. A `Temporary` filter whose `expiresAt` is in the past
+ * is Expired the instant that comparison is made, even if the server has not
+ * yet patched `state` to `Expired`. So the client compares `expiresAt` against
+ * `now` directly and also honors a `state` the server already flipped.
+ *
+ * An `Expired` filter is never hidden — it stays listed so the user can see
+ * what it was and when it stopped (RFC 034 Decision 1.2, "stops on its own").
+ */
+export const filterDisplayStatus = (filter, now) => {
+    if (filter.state === "Expired")
+        return "Expired";
+    const running = filter.state === "Disabled" ? "Disabled" : "Active";
+    if (filter.scope !== "Temporary")
+        return running;
+    if (!filter.expiresAt)
+        return running;
+    const expiresAtMs = Date.parse(filter.expiresAt);
+    if (Number.isNaN(expiresAtMs))
+        return running;
+    return expiresAtMs <= now ? "Expired" : running;
+};
+const DISABLED_REASON_COPY = {
+    UserDisabled: "Turned off. Turn it on to run it on new mail again.",
+    AwaitingFolder: "Off until its folder exists on the mail server. It turns on by itself once the folder is created.",
+    FolderCreateFailed: "Off: the mail server refused to create its folder. Pick another folder in the rule, then turn it on.",
+    FolderMissing: "Off: the folder it moves mail into no longer exists. Pick another folder in the rule, then turn it on.",
+};
+export const disabledReasonCopy = (filter) => {
+    if (filter.disabledReason === "None")
+        return undefined;
+    const folderless = filter.disabledReason === "AwaitingFolder" ||
+        filter.disabledReason === "FolderCreateFailed";
+    if (folderless && filter.actionMailboxId !== "None") {
+        return DISABLED_REASON_COPY.UserDisabled;
+    }
+    return DISABLED_REASON_COPY[filter.disabledReason];
+};
+/**
+ * Human-readable rendering of an expiry timestamp, e.g. "Jul 16, 2026".
+ * Returns `undefined` for an absent or unparseable value so a standing filter
+ * (no `expiresAt`) renders nothing.
+ */
+export const formatExpiresAt = (expiresAt) => {
+    if (!expiresAt)
+        return undefined;
+    const ms = Date.parse(expiresAt);
+    if (Number.isNaN(ms))
+        return undefined;
+    return new Date(ms).toLocaleDateString(undefined, {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+    });
+};
+/**
+ * Turn a plain picked calendar date (`YYYY-MM-DD`, from a native date input)
+ * into an ISO 8601 timestamp with the local zone offset, at end of that day —
+ * the filter is meant to stay active through the whole picked day (RFC 034
+ * Decision 1.1, a zoned civil date). Returns `undefined` for empty input.
+ */
+export const pickedDateToExpiresAt = (pickedDate, referenceDate = new Date()) => {
+    if (!pickedDate)
+        return undefined;
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(pickedDate);
+    if (!match)
+        return undefined;
+    const [, year, month, day] = match;
+    const local = new Date(Number(year), Number(month) - 1, Number(day), 23, 59, 59, 0);
+    if (Number.isNaN(local.getTime()))
+        return undefined;
+    const offsetMinutes = -referenceDate.getTimezoneOffset();
+    const sign = offsetMinutes >= 0 ? "+" : "-";
+    const abs = Math.abs(offsetMinutes);
+    const offHours = String(Math.floor(abs / 60)).padStart(2, "0");
+    const offMins = String(abs % 60).padStart(2, "0");
+    const pad = (value) => String(value).padStart(2, "0");
+    return (`${local.getFullYear()}-${pad(local.getMonth() + 1)}-${pad(local.getDate())}` +
+        `T${pad(local.getHours())}:${pad(local.getMinutes())}:${pad(local.getSeconds())}` +
+        `${sign}${offHours}:${offMins}`);
+};

package/dist/src/lib/organize/label-delete-copy.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The delete-confirmation copy for a label (issue #26). Deleting a label
+ * cascades in both directions server-side — every filter whose action applies
+ * it is deleted outright, never left dangling — so the confirmation names the
+ * filter count up front rather than surprising the user after the fact. The
+ * API itself never blocks the delete; the confirmation is the only gate.
+ */
+export declare const deleteLabelConfirmCopy: (labelName: string, filterCount: number) => {
+    title: string;
+    description?: string;
+};

package/dist/src/lib/organize/label-delete-copy.js

@@ -0,0 +1,17 @@
+/**
+ * The delete-confirmation copy for a label (issue #26). Deleting a label
+ * cascades in both directions server-side — every filter whose action applies
+ * it is deleted outright, never left dangling — so the confirmation names the
+ * filter count up front rather than surprising the user after the fact. The
+ * API itself never blocks the delete; the confirmation is the only gate.
+ */
+export const deleteLabelConfirmCopy = (labelName, filterCount) => {
+    if (filterCount === 0) {
+        return { title: `Delete the "${labelName}" label?` };
+    }
+    const filterNoun = filterCount === 1 ? "filter" : "filters";
+    return {
+        title: `Delete the "${labelName}" label?`,
+        description: `This also deletes ${filterCount} ${filterNoun} that ${filterCount === 1 ? "applies" : "apply"} it — they can't be recovered.`,
+    };
+};

package/dist/src/lib/organize/organize-model.d.ts

@@ -0,0 +1,110 @@
+import type { RemitImapCreateFilterInput, RemitImapFilterClause, RemitImapFilterMatchOperator, RemitImapOrganizeInput } from "@remit/api-http-client/types.gen.ts";
+import type { MatchDoor, MatchOperator, RuleClause, RuleScope } from "@remit/ui";
+/**
+ * The four commit scopes the smart-organize sentence offers (RFC 034 recap):
+ *
+ * - `just-these` — a one-time action on the current selection. Existing
+ *   message-action API, nothing persisted.
+ * - `all-like-these` — a one-time retroactive back-apply across the matching
+ *   corpus (POST /organize job). Nothing standing persisted.
+ * - `standing` — "these and new mail like this": a permanent `Filter`.
+ * - `temporary` — "until <date>": a `Filter` that expires on its own.
+ */
+export type OrganizeScope = "just-these" | "all-like-these" | "standing" | "temporary";
+/** The `"None"` sentinel the API uses for an absent label / move action. */
+export declare const NO_ACTION = "None";
+/**
+ * The predicate a preview counts and a commit acts on: the operator and the
+ * literal clauses. The set it previews equals the set every commit scope acts on.
+ */
+export type OrganizeMatchPredicate = Pick<RemitImapOrganizeInput, "matchOperator" | "literalClauses">;
+/**
+ * The user's in-progress organize decision, independent of which scope they
+ * land on. The predicate drives the match set; `moveMailboxId` and
+ * `labelId` are the two committable actions (issue #26) — independent of each
+ * other, since a move is exclusive and a label is additive (RFC 034 Decision
+ * 3.1).
+ */
+export interface OrganizeDraft {
+    /** How `literalClauses` combine. Ignored when there are none. */
+    matchOperator: RemitImapFilterMatchOperator;
+    /** Literal from/subject/has-words clauses (RFC 031). */
+    literalClauses: RemitImapFilterClause[];
+    /**
+     * Destination the match set is moved into — the exclusive action (RFC 034
+     * Decision 3.1). Absent means "keep where they are": no move action.
+     */
+    moveMailboxId?: string;
+    /**
+     * Label applied to the match set — the additive action (RFC 034 Decision
+     * 3.1, issue #26). Absent applies no label.
+     */
+    labelId?: string;
+    /**
+     * ISO 8601 date-time with zone offset. Present only for the `temporary`
+     * scope; a plain picked date (RFC 034 non-goal: no event-based expiry).
+     */
+    expiresAt?: string;
+}
+/**
+ * Whether the draft carries a committable action — a move destination and/or
+ * a label (issue #26), either satisfies this. A draft with neither has
+ * nothing to commit; the caller disables the CTA and says why (ux.md).
+ */
+export declare const hasCommittableAction: (draft: OrganizeDraft) => boolean;
+/**
+ * Ask for a saved filter's pass over the inbox. The server reads the filter's
+ * own rule and action when the job runs and ignores the predicate fields,
+ * which the request shape still requires.
+ */
+export declare const buildRunFilterInput: (filterId: string) => RemitImapOrganizeInput;
+/**
+ * Build the read-only preview / back-apply matcher input. The action fields do
+ * not affect which messages match — the preview returns exactly the set a job
+ * with the same predicate would apply to — so a preview can pass this before
+ * the user has chosen a folder or a label.
+ */
+export declare const buildOrganizeInput: (draft: OrganizeDraft) => RemitImapOrganizeInput;
+/**
+ * The two independent answers the wizard collects (#477 4.6). Neither is a
+ * scope: the door says what the action covers and the scope step says how long
+ * it holds, and the four `OrganizeScope` values fall out of the pair.
+ */
+export interface WizardCommitAnswers {
+    /**
+     * The door the match came through. An escalated predicate is not one: it has
+     * no clauses to build a rule from, so a scope reconstructed for it would be a
+     * rule matching everything. Typed to the doors so that cannot be written
+     * rather than merely not written.
+     */
+    mode: MatchDoor;
+    /** Absent on the verbs that never reach the scope step — those act once. */
+    ruleScope?: RuleScope;
+}
+/**
+ * Which of the four commit scopes the wizard's answers add up to. Reconstructed
+ * here and nowhere else, so a driver cannot invent a fifth: the ticked list at
+ * scope once is `just-these`, the properties door at scope once is `all-like-these`,
+ * and the two persisting scopes are `standing` and `temporary`.
+ */
+export declare const organizeScopeFor: ({ mode, ruleScope, }: WizardCommitAnswers) => OrganizeScope;
+export interface WizardDraftInput extends WizardCommitAnswers {
+    clauses: readonly RuleClause[];
+    matchOperator: MatchOperator;
+    moveMailboxId?: string;
+    /** ISO 8601 civil date (`YYYY-MM-DD`) the `until` scope stops on. */
+    until?: string;
+}
+/**
+ * The commit draft for a set of wizard answers. This is where the `until`
+ * scope's civil date becomes `expiresAt`, a zoned date-time (#477 5.4): the
+ * wizard collects the day the rule stops on, and the day only becomes an
+ * instant once there is a draft to carry it.
+ */
+export declare const buildWizardDraft: ({ ruleScope, clauses, matchOperator, moveMailboxId, until, }: WizardDraftInput) => OrganizeDraft;
+/**
+ * Build the `createFilter` body for a standing or temporary filter. `ttl` is
+ * derived server-side from `expiresAt`; `expiresAt` is sent only for the
+ * temporary scope (RFC 034 Decision 1.3).
+ */
+export declare const buildCreateFilterInput: (draft: OrganizeDraft, scope: Extract<OrganizeScope, "standing" | "temporary">, name: string) => RemitImapCreateFilterInput;

package/dist/src/lib/organize/organize-model.js

@@ -0,0 +1,81 @@
+import { pickedDateToExpiresAt } from "./filter-status";
+/** The `"None"` sentinel the API uses for an absent label / move action. */
+export const NO_ACTION = "None";
+/**
+ * Whether the draft carries a committable action — a move destination and/or
+ * a label (issue #26), either satisfies this. A draft with neither has
+ * nothing to commit; the caller disables the CTA and says why (ux.md).
+ */
+export const hasCommittableAction = (draft) => (draft.moveMailboxId !== undefined && draft.moveMailboxId !== NO_ACTION) ||
+    (draft.labelId !== undefined && draft.labelId !== NO_ACTION);
+/**
+ * Ask for a saved filter's pass over the inbox. The server reads the filter's
+ * own rule and action when the job runs and ignores the predicate fields,
+ * which the request shape still requires.
+ */
+export const buildRunFilterInput = (filterId) => ({
+    filterId,
+    matchOperator: "And",
+    literalClauses: [],
+    actionLabelId: NO_ACTION,
+    actionMailboxId: NO_ACTION,
+});
+/**
+ * Build the read-only preview / back-apply matcher input. The action fields do
+ * not affect which messages match — the preview returns exactly the set a job
+ * with the same predicate would apply to — so a preview can pass this before
+ * the user has chosen a folder or a label.
+ */
+export const buildOrganizeInput = (draft) => ({
+    matchOperator: draft.matchOperator,
+    literalClauses: draft.literalClauses,
+    actionLabelId: draft.labelId ?? NO_ACTION,
+    actionMailboxId: draft.moveMailboxId ?? NO_ACTION,
+});
+/**
+ * Which of the four commit scopes the wizard's answers add up to. Reconstructed
+ * here and nowhere else, so a driver cannot invent a fifth: the ticked list at
+ * scope once is `just-these`, the properties door at scope once is `all-like-these`,
+ * and the two persisting scopes are `standing` and `temporary`.
+ */
+export const organizeScopeFor = ({ mode, ruleScope, }) => {
+    if (ruleScope === "standing")
+        return "standing";
+    if (ruleScope === "until")
+        return "temporary";
+    return mode === "selected" ? "just-these" : "all-like-these";
+};
+/**
+ * The commit draft for a set of wizard answers. This is where the `until`
+ * scope's civil date becomes `expiresAt`, a zoned date-time (#477 5.4): the
+ * wizard collects the day the rule stops on, and the day only becomes an
+ * instant once there is a draft to carry it.
+ */
+export const buildWizardDraft = ({ ruleScope, clauses, matchOperator, moveMailboxId, until, }) => ({
+    matchOperator: matchOperator === "all" ? "And" : "Or",
+    literalClauses: clauses.map((clause) => ({
+        field: clause.field,
+        value: clause.value,
+    })),
+    moveMailboxId,
+    expiresAt: ruleScope === "until" ? pickedDateToExpiresAt(until ?? "") : undefined,
+});
+/**
+ * Build the `createFilter` body for a standing or temporary filter. `ttl` is
+ * derived server-side from `expiresAt`; `expiresAt` is sent only for the
+ * temporary scope (RFC 034 Decision 1.3).
+ */
+export const buildCreateFilterInput = (draft, scope, name) => {
+    const filterScope = scope === "standing" ? "Standing" : "Temporary";
+    return {
+        name,
+        scope: filterScope,
+        ...(scope === "temporary" && draft.expiresAt
+            ? { expiresAt: draft.expiresAt }
+            : {}),
+        matchOperator: draft.matchOperator,
+        literalClauses: draft.literalClauses,
+        actionLabelId: draft.labelId ?? NO_ACTION,
+        actionMailboxId: draft.moveMailboxId ?? NO_ACTION,
+    };
+};

package/dist/src/lib/organize/organize-poll.d.ts

@@ -0,0 +1,11 @@
+import type { RemitImapOrganizeJobState } from "@remit/api-http-client/types.gen.ts";
+export declare const isTerminalJobState: (state: RemitImapOrganizeJobState | undefined) => boolean;
+/**
+ * Exponential backoff for job polling: 1s, 2s, 4s, 8s, capped at 15s. `attempt`
+ * is the number of polls already made (0 for the first delay). Backoff keeps a
+ * long-running back-apply from hammering the job endpoint while staying
+ * responsive for the common fast case — and there is never a client-side loop
+ * over message pages (remit is data-heavy; the corpus is queried once, server
+ * side, by the job itself).
+ */
+export declare const nextPollDelayMs: (attempt: number) => number;

package/dist/src/lib/organize/organize-poll.js

@@ -0,0 +1,21 @@
+/** States a back-apply job stops at — polling ends here (RFC 034, #1278). */
+const TERMINAL_STATES = new Set([
+    "Complete",
+    "Failed",
+]);
+export const isTerminalJobState = (state) => state !== undefined && TERMINAL_STATES.has(state);
+const BASE_POLL_MS = 1_000;
+const MAX_POLL_MS = 15_000;
+/**
+ * Exponential backoff for job polling: 1s, 2s, 4s, 8s, capped at 15s. `attempt`
+ * is the number of polls already made (0 for the first delay). Backoff keeps a
+ * long-running back-apply from hammering the job endpoint while staying
+ * responsive for the common fast case — and there is never a client-side loop
+ * over message pages (remit is data-heavy; the corpus is queried once, server
+ * side, by the job itself).
+ */
+export const nextPollDelayMs = (attempt) => {
+    const clampedAttempt = Math.max(0, attempt);
+    const delay = BASE_POLL_MS * 2 ** clampedAttempt;
+    return Math.min(delay, MAX_POLL_MS);
+};

package/dist/src/lib/organize/rule-model.d.ts

@@ -0,0 +1,69 @@
+import type { ClauseField, FilterRule, PreviewCount } from "@remit/ui";
+import type { OrganizeDraft, OrganizeMatchPredicate } from "./organize-model";
+/**
+ * The clause fields the Organize editor may offer (RFC 038 D2). Gated on what
+ * the backend matcher evaluates, not on what the generated enum carries: every
+ * one of these is honored by the literal matcher and the back-apply corpus
+ * projection (match.ts), so a chip never previews a set the apply can't
+ * reproduce. `ListId` and `FromDomain` joined once their matcher shipped (#262).
+ */
+export declare const SUPPORTED_CLAUSE_FIELDS: ClauseField[];
+/**
+ * Canonical form of a `ListId` clause value, matching the backend's
+ * `normalizeListId` (list-id.ts): the bracketed identifier when present,
+ * otherwise the whole value, trimmed and case-folded. Normalizing at input keeps
+ * the chip the user sees identical to the value the matcher compares, so
+ * `<weekly.news.example.com>` and `Weekly.News.Example.com` are one list.
+ */
+export declare const normalizeListId: (value: string) => string;
+/** Canonicalize a clause value for its field before it becomes a chip. */
+export declare const normalizeClauseValue: (field: ClauseField, value: string) => string;
+/**
+ * The match-relevant projection of a rule — the operator and the literal
+ * clauses. Preview and apply
+ * both derive from this, so the set the editor counts is the set a commit acts
+ * on. Fields that do not change the match set (folder, scope, name, date) are
+ * deliberately absent.
+ */
+export declare const rulePredicate: (rule: FilterRule) => OrganizeMatchPredicate;
+/**
+ * Whether the matcher behind `/organize/preview` can evaluate this predicate at
+ * all. It reads no message body and rejects a `HasWords` clause rather than
+ * narrowing the match silently (`bodyContentRejection`, backend/service/organize.ts). Asking it
+ * anyway is refused with a 400, on preview and on a back-apply alike, so the
+ * caller must not ask.
+ */
+export declare const isEvaluablePredicate: (predicate: OrganizeMatchPredicate) => boolean;
+/**
+ * A stable key for a predicate's match set. Two predicates with the same key
+ * match the same messages; a change to the key is what marks the live count
+ * stale and schedules the next preview.
+ */
+export declare const predicateSignature: (predicate: OrganizeMatchPredicate) => string;
+/**
+ * The commit draft for a rule. The match fields are exactly
+ * {@link rulePredicate}'s — the previewed predicate — with the folder action
+ * and, for the `until` scope, the derived expiry added. The expiry never enters
+ * the match set, so preview and apply still count and act on the same messages.
+ */
+export declare const ruleToDraft: (rule: FilterRule) => OrganizeDraft;
+export interface PreviewState {
+    /** The last count that came back, `undefined` before the first lands. */
+    count?: number;
+    /** The ids that count was counted over, as the server bounded them. */
+    matchedIds?: readonly string[];
+    /** The signature the {@link count} was counted for. */
+    previewedSignature?: string;
+    /** The signature the last error was raised for. */
+    errorSignature?: string;
+    error?: string;
+}
+/**
+ * The live count for the rule on screen. The count is `ready` only when it was
+ * counted for the current predicate; a predicate change since then reads
+ * `stale` (recounting, never blank) so the commit gate can hold apply until it
+ * settles.
+ */
+export declare const derivePreview: (state: PreviewState, currentSignature: string) => PreviewCount;
+/** How long a rule change settles before the next preview fires. */
+export declare const PREVIEW_DEBOUNCE_MS = 350;