@remit/web-client 0.0.325 → 0.0.327

package/dist/src/lib/delete-folder.js

@@ -0,0 +1,110 @@
+export const MOVE_BATCH_SIZE = 100;
+const isInboxPath = (fullPath) => fullPath.trim().toLowerCase() === "inbox";
+/**
+ * A folder has children when another mailbox's path is nested under it — the
+ * folder's own path followed by the hierarchy delimiter. The delimiter matters:
+ * `Work` is not a parent of `Workshop`, only of `Work/Shop`. A server that
+ * reports no delimiter has a flat namespace, where nothing nests at all.
+ */
+export const hasChildFolders = (folder, all) => {
+    if (folder.hierarchyDelimiter.length === 0)
+        return false;
+    const prefix = `${folder.fullPath}${folder.hierarchyDelimiter}`;
+    return all.some((other) => other.mailboxId !== folder.mailboxId && other.fullPath.startsWith(prefix));
+};
+/**
+ * Sources that vouch for the mailbox they name: a person chose it, or the
+ * server flagged it. `Proposed` is a guess at a folder's name and vouches for
+ * nothing. `Reserved` is unreachable behind the inbox branch below and stays
+ * anyway — this set is a statement about evidence, not about branch order.
+ */
+const VOUCHED_SOURCES = [
+    "Appointed",
+    "Flagged",
+    "Reserved",
+];
+/**
+ * A `Stale` entry resolves to whatever the account would have had with no
+ * appointment at all, and that fallback can be the folder the server itself
+ * flags for the role. The entry no longer carries which it was, so read the
+ * flag off the folder: the mail server's designation is unchanged by the
+ * user's own choice going missing, and nothing behind this guard re-checks it.
+ * Flag values are the bare RFC 6154 names, identical to the canonical roles.
+ */
+const vouchesFor = (appointment, folder) => {
+    if (appointment.mailboxId !== folder.mailboxId)
+        return false;
+    if (appointment.source === "Stale")
+        return folder.specialUse?.includes(appointment.role) ?? false;
+    return VOUCHED_SOURCES.includes(appointment.source);
+};
+/** The canonical role a folder is vouched for, or `undefined` when none is. */
+export const vouchedRole = (folder, appointments) => appointments.find((a) => vouchesFor(a, folder))?.role;
+/**
+ * Why a folder can't be deleted, or `{ deletable: true }` when it can. The
+ * inbox is reserved, a folder somebody vouched for in a canonical role must be
+ * released first, and a folder with subfolders must have them handled before it
+ * goes. A role a folder only fills because its name reads that way is no reason
+ * to keep the folder: the message would name a remedy that does not apply.
+ */
+export function guardFolderDeletion(folder, all, appointments) {
+    if (isInboxPath(folder.fullPath))
+        return {
+            deletable: false,
+            reason: "inbox",
+            message: "The inbox can't be deleted.",
+        };
+    const role = vouchedRole(folder, appointments);
+    if (role)
+        return {
+            deletable: false,
+            reason: "role",
+            message: `This folder is your ${role} folder. Reassign that role before deleting it.`,
+        };
+    if (hasChildFolders(folder, all))
+        return {
+            deletable: false,
+            reason: "children",
+            message: "This folder has subfolders. Delete them first.",
+        };
+    return { deletable: true };
+}
+/** Destinations with the folder being deleted removed. */
+export function excludeFolder(targets, excludeMailboxId) {
+    return targets.filter((target) => target.mailboxId !== excludeMailboxId);
+}
+/** Progress at the start of a move; an empty set is already `moved`. */
+export function beginMove(total) {
+    return { total, moved: 0, phase: total === 0 ? "moved" : "moving" };
+}
+/**
+ * Count a successful batch. Clamps to `total` so a folder that grew mid-move
+ * never shows more moved than started, and only a still-`moving` progress
+ * advances — a failed or finished move stays put.
+ */
+export function advanceMove(progress, batchSize) {
+    if (progress.phase !== "moving")
+        return progress;
+    const moved = Math.min(progress.total, progress.moved + Math.max(0, batchSize));
+    return {
+        ...progress,
+        moved,
+        phase: moved >= progress.total ? "moved" : "moving",
+    };
+}
+/** A failed batch stops progress and surfaces the error; nothing advances after. */
+export function failMove(progress, error) {
+    return { ...progress, phase: "failed", error };
+}
+export function moveProgressLabel(progress) {
+    return `Moved ${progress.moved} of ${progress.total}`;
+}
+/** How long a wait has run, as `m:ss` — clamped at zero so a clock skew reads as 0:00. */
+export function elapsedLabel(ms) {
+    const seconds = Math.max(0, Math.floor(ms / 1000));
+    return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
+}
+/** Where the wizard opens: a straight confirm for an empty folder, otherwise the fate step. */
+export function initialStage(messageCount) {
+    return messageCount > 0 ? "choose-fate" : "confirm-empty";
+}

package/dist/src/lib/display-category.d.ts

@@ -0,0 +1,18 @@
+import type { RemitImapMessageCategory } from "@remit/api-http-client/types.gen.ts";
+import type { ThreadCategory } from "@remit/ui";
+/**
+ * Map an API message category to a kit display category.
+ *
+ * The API category is total (RFC 032 Tier 2) and carries `uncategorized` for
+ * messages that are metadata-synced but not yet body-classified. That state is
+ * shown as itself, not collapsed into `personal`: collapsing made an
+ * unclassified message identical on screen to one the classifier positively
+ * decided was personal, so a classification gap read as a large personal inbox
+ * rather than as missing work (issue #45).
+ *
+ * Both response fields that feed this are required, so no caller reaches the
+ * `undefined` branch. The parameter stays tolerant anyway: this is the one place
+ * an absent category is turned into a value, and the answer has to be
+ * `uncategorized` rather than a crash or a `personal` default.
+ */
+export declare function toDisplayCategory(category: RemitImapMessageCategory | undefined): ThreadCategory;

package/dist/src/lib/display-category.js

@@ -0,0 +1,20 @@
+/**
+ * Map an API message category to a kit display category.
+ *
+ * The API category is total (RFC 032 Tier 2) and carries `uncategorized` for
+ * messages that are metadata-synced but not yet body-classified. That state is
+ * shown as itself, not collapsed into `personal`: collapsing made an
+ * unclassified message identical on screen to one the classifier positively
+ * decided was personal, so a classification gap read as a large personal inbox
+ * rather than as missing work (issue #45).
+ *
+ * Both response fields that feed this are required, so no caller reaches the
+ * `undefined` branch. The parameter stays tolerant anyway: this is the one place
+ * an absent category is turned into a value, and the answer has to be
+ * `uncategorized` rather than a crash or a `personal` default.
+ */
+export function toDisplayCategory(category) {
+    if (category === undefined)
+        return "uncategorized";
+    return category;
+}

package/dist/src/lib/drafts.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Drafts view grouping logic.
+ *
+ * Pure function: takes Remit outbox drafts and IMAP thread rows and returns
+ * two labeled sections:
+ *
+ *  1. Not yet sent (Remit) — outbox rows with status === "draft" belonging to
+ *     the account that owns the open \Drafts mailbox.
+ *  2. On the server — IMAP \Drafts thread rows already loaded for the mailbox.
+ *
+ * Sections with no rows are omitted entirely (mirrors `briefSections`).
+ *
+ * --- Dedup note ---
+ * Remit draft rows and IMAP \Drafts messages are rendered in both sections
+ * without client-side dedup. There is currently no IMAP APPEND-as-draft path
+ * and no IMAP uid / Message-ID back-reference on the outbox model, so the two
+ * sets are distinct objects with no shared key. If a future change starts
+ * appending Remit drafts into IMAP \Drafts the dedup key would be the RFC822
+ * `Message-ID` header. Until that ships, rendering both sections faithfully is
+ * the correct behaviour (issue #505).
+ */
+import type { RemitImapOutboxMessageResponse, RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+import type { ThreadRowData, ThreadSection } from "@remit/ui";
+/**
+ * Map a Remit outbox draft to the ThreadRowData shape used by remit-ui row
+ * components.
+ */
+export declare function toDraftRowData(draft: RemitImapOutboxMessageResponse): ThreadRowData;
+/**
+ * Map a RemitImapThreadMessageResponse to the ThreadRowData shape used by
+ * remit-ui row body components.  Mirrors toThreadRowData in lib/brief.ts.
+ */
+export declare function toImapDraftRowData(thread: RemitImapThreadMessageResponse): ThreadRowData;
+export interface GroupDraftSectionsInput {
+    /** All outbox messages. Will be filtered to status === "draft" and accountId. */
+    outboxMessages: RemitImapOutboxMessageResponse[];
+    /** The accountId that owns the open \Drafts mailbox. */
+    accountId: string;
+    /** Thread rows already loaded for the \Drafts mailbox (IMAP). */
+    imapThreads: RemitImapThreadMessageResponse[];
+}
+/**
+ * Group outbox drafts and IMAP thread rows into the two-section Drafts view.
+ *
+ * @param input.outboxMessages  Full outbox list (will be filtered here).
+ * @param input.accountId       Owner account of the open \Drafts mailbox.
+ * @param input.imapThreads     IMAP \Drafts threads already loaded.
+ * @returns                     Array of ThreadSection — empty sections omitted.
+ */
+export declare function groupDraftSections({ outboxMessages, accountId, imapThreads, }: GroupDraftSectionsInput): ThreadSection[];

package/dist/src/lib/drafts.js

@@ -0,0 +1,91 @@
+/**
+ * Drafts view grouping logic.
+ *
+ * Pure function: takes Remit outbox drafts and IMAP thread rows and returns
+ * two labeled sections:
+ *
+ *  1. Not yet sent (Remit) — outbox rows with status === "draft" belonging to
+ *     the account that owns the open \Drafts mailbox.
+ *  2. On the server — IMAP \Drafts thread rows already loaded for the mailbox.
+ *
+ * Sections with no rows are omitted entirely (mirrors `briefSections`).
+ *
+ * --- Dedup note ---
+ * Remit draft rows and IMAP \Drafts messages are rendered in both sections
+ * without client-side dedup. There is currently no IMAP APPEND-as-draft path
+ * and no IMAP uid / Message-ID back-reference on the outbox model, so the two
+ * sets are distinct objects with no shared key. If a future change starts
+ * appending Remit drafts into IMAP \Drafts the dedup key would be the RFC822
+ * `Message-ID` header. Until that ships, rendering both sections faithfully is
+ * the correct behaviour (issue #505).
+ */
+import { formatEmailDate } from "./format.js";
+import { rowSettlement } from "./row-settlement.js";
+/**
+ * Map a Remit outbox draft to the ThreadRowData shape used by remit-ui row
+ * components.
+ */
+export function toDraftRowData(draft) {
+    const recipients = draft.toAddresses.join(", ");
+    return {
+        id: draft.outboxMessageId,
+        accountId: draft.accountId,
+        fromName: draft.fromName ?? draft.fromAddress ?? "Me",
+        fromEmail: draft.fromAddress ?? "",
+        subject: draft.subject ?? "(No subject)",
+        snippet: recipients ? `To: ${recipients}` : "(No recipients)",
+        timeLabel: formatEmailDate(draft.updatedAt),
+        isRead: true,
+    };
+}
+/**
+ * Map a RemitImapThreadMessageResponse to the ThreadRowData shape used by
+ * remit-ui row body components.  Mirrors toThreadRowData in lib/brief.ts.
+ */
+export function toImapDraftRowData(thread) {
+    return {
+        id: thread.messageId,
+        accountId: thread.accountId,
+        fromName: thread.fromName ?? thread.fromEmail ?? "Unknown",
+        fromEmail: thread.fromEmail ?? "",
+        subject: thread.subject ?? "(No subject)",
+        snippet: thread.snippet ?? "",
+        timeLabel: formatEmailDate(thread.sentDate),
+        isRead: thread.isRead,
+        hasAttachment: thread.hasAttachment,
+        starred: thread.hasStars === true,
+        ...rowSettlement(thread),
+    };
+}
+/**
+ * Group outbox drafts and IMAP thread rows into the two-section Drafts view.
+ *
+ * @param input.outboxMessages  Full outbox list (will be filtered here).
+ * @param input.accountId       Owner account of the open \Drafts mailbox.
+ * @param input.imapThreads     IMAP \Drafts threads already loaded.
+ * @returns                     Array of ThreadSection — empty sections omitted.
+ */
+export function groupDraftSections({ outboxMessages, accountId, imapThreads, }) {
+    // Only outbox rows with status === "draft" for this account. failed/blocked
+    // rows live in the Outbox view and must never appear in Drafts (issue #505).
+    const remitDrafts = outboxMessages
+        .filter((m) => m.status === "draft" && m.accountId === accountId)
+        .map(toDraftRowData);
+    const imapDrafts = imapThreads.map(toImapDraftRowData);
+    const sections = [];
+    if (remitDrafts.length > 0) {
+        sections.push({
+            id: "remit-drafts",
+            label: "Not yet sent (Remit)",
+            threads: remitDrafts,
+        });
+    }
+    if (imapDrafts.length > 0) {
+        sections.push({
+            id: "imap-drafts",
+            label: "On the server",
+            threads: imapDrafts,
+        });
+    }
+    return sections;
+}

package/dist/src/lib/error-classifier.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Extract an HTTP status code from a thrown error, regardless of which client
+ * raised it.
+ *
+ * Two client shapes coexist in the web client:
+ *  - the hand-written `api` wrapper throws `ApiError` (carries `.status`);
+ *  - the generated `@remit/api-http-client` (hey-api) throws the parsed JSON error
+ *    body. A response interceptor (see `lib/client.ts`) re-wraps those as
+ *    `ApiError` too, so in practice both paths carry `.status`. As a belt-and-
+ *    braces fallback we also read a numeric `status`/`statusCode` off a plain
+ *    object.
+ */
+export declare const getErrorStatus: (error: unknown) => number | undefined;
+/** The error carries a real HTTP status — our API answered. */
+export declare const hasHttpStatus: (error: unknown) => boolean;
+/** A genuine first-party server failure: an HTTP 5xx. */
+export declare const isServerError: (error: unknown) => boolean;
+/**
+ * A deliberately cancelled request (route change, React Query cancellation).
+ * Never a failure.
+ */
+export declare const isAbortError: (error: unknown) => boolean;
+/**
+ * A transport failure from a wifi drop, tab wake, captive portal, or a timeout:
+ * the request never reached a server, so it is environmental, not a proven
+ * first-party failure.
+ *
+ * This is decided at the fetch boundary, not inferred here. Every app-owned
+ * request goes through `taggedFetch`, which knows a `fetch()` rejection is
+ * transport-level because `fetch` rejects for no other reason, and tags it a
+ * `NetworkError`. Reading that tag is exact; matching browser failure strings
+ * was not — the list is open-ended (WebKit alone has four, undici another) and
+ * anything missed would put a full-screen fatal page in front of someone who
+ * had merely walked out of wifi range.
+ *
+ * `navigator.onLine === false` is kept as a second signal for an error that
+ * reached us from outside that boundary while the browser reports no
+ * connectivity at all.
+ */
+export declare const isNetworkError: (error: unknown) => boolean;
+/**
+ * An exception raised by our own client code rather than by a request: it
+ * carries no HTTP status, is not an abort, and was not tagged as transport.
+ * That leaves a programming error — the one class the user can do nothing
+ * about and must never be asked to shrug off.
+ */
+export declare const isClientBug: (error: unknown) => boolean;
+/**
+ * Fatal with no opt-out: our API answered "I'm broken", or our own code threw.
+ * Neither is something a call site can reclassify as soft, and neither may be
+ * reduced to a dismissible banner — both belong on the full-screen page, which
+ * offers a way forward and a bug report (issue #55).
+ */
+export declare const isAlwaysFatal: (error: unknown) => boolean;
+/**
+ * The session is gone. Not 403: a handler answers 403 for a resource belonging
+ * to another account config, which is a refusal a call site can state where it
+ * stands. A 401 is the user signed out from under whatever they were doing.
+ */
+export declare const isUnauthenticated: (error: unknown) => boolean;
+/**
+ * Who is waiting on this request's answer. One decision turns on it, and only
+ * one: whether a 401 overrides the call site's own `meta.softError`.
+ *
+ * "user" — the user did something and the app owes them the outcome. Every
+ * mutation is this, the debounced autosave included: it carries text that is on
+ * screen, and if it is refused for want of a session then so is the send behind
+ * it. No banner a call site can render signs anyone back in, so this is the one
+ * 4xx a call site may not keep to itself.
+ *
+ * "nobody" — a poll, a prefetch, a best-effort background trigger, an inline
+ * sub-resource with an error surface of its own. A 401 there is not news the
+ * app may take the whole screen for, and `meta.softError` decides as usual.
+ *
+ * Reads are "nobody" as a class, which is not the same as saying no read
+ * matters: a read the screen is actually waiting on has no `meta.softError` on
+ * it, so rule 1 escalates it anyway. The only reads this spares are the ones
+ * that already declared they own their failures — the update poll mounted at
+ * the app root, the message body with its own inline banner. Escalating those
+ * put the full-screen page over every screen in the app.
+ */
+export type Awaiting = "user" | "nobody";
+/**
+ * The single fail-fast decision: should this error escalate to the full-screen
+ * fatal overlay? Default is YES — a non-2xx must never silently vanish.
+ *
+ * The contract (issue #1059):
+ *  1. DEFAULT = escalate.
+ *  2. A 5xx (500–599) ALWAYS escalates — no opt-out, even on a background
+ *     refetch, even when the call site marked `meta.softError`. Our API
+ *     answered "I'm broken"; that is never benign. The single exception is a
+ *     502/503/504 on a call site that declared it is polling across a restart it
+ *     asked for (`meta.restartExpected`, #468): there the backend being gone is
+ *     the operation working, and that call site renders the wait itself.
+ *  3. A client-side exception ALWAYS escalates, on the same terms. It is our
+ *     bug; there is nothing for the user to retry and nothing to dismiss.
+ *  4. A 401 on a request the user is waiting on ALWAYS escalates, on the same
+ *     terms. Dismissing it leaves them signed out with no way back in, and a
+ *     send that keeps failing becomes a loop with no exit — `BetterAuthShell`
+ *     re-gates only when `useSession()` revalidates, which a banner never makes
+ *     happen. See `Awaiting` for what nobody waiting on it means.
+ *  5. The ONLY soft (do-NOT-escalate) exemptions:
+ *     a. aborts / cancellations — never a failure;
+ *     b. network/offline errors — environmental, recovered by React Query's
+ *        reconnect/retry;
+ *     c. a non-5xx error on a query/mutation that opted out via
+ *        `meta.softError === true` — the call site owns that error's UX
+ *        (e.g. a 404 empty state, a 4xx "Reconnect" banner) — or, where it owns
+ *        one status and not the rest, `meta.softErrorStatuses`.
+ */
+export declare const shouldEscalate: (error: unknown, meta?: Record<string, unknown>, awaiting?: Awaiting) => boolean;
+/**
+ * The meta a call site sets to keep its own non-5xx failures off the
+ * full-screen fatal page, because it renders them itself — a banner, a retry,
+ * an empty state. Rules 2, 3 and 4 above still win: a 5xx, a client-side
+ * exception, and a 401 on something the user is waiting on, escalate regardless.
+ *
+ * Two classes of call site must always carry it. One is a request the user
+ * never asked for and is not waiting on — a debounced autosave, a
+ * dwell-triggered mark-as-read: a refusal there is not news worth stopping the
+ * app for. The other is any surface holding text the user has not finished
+ * writing. The fatal page unmounts the app, so escalating from a composer
+ * throws the message away and leaves nothing to retry, which is a worse outcome
+ * than the failure it reports.
+ */
+export declare const softErrorMeta: {
+    softError: true;
+};
+/**
+ * The narrow form, for a call site that owns one outcome and none of the others.
+ * A read whose record may legitimately be gone owns the 404 and nothing else: a
+ * blanket `softErrorMeta` there would also swallow the 401 and the 403, and a
+ * background read that answers a lapsed session with nothing leaves the user
+ * looking at a screen that has quietly stopped working.
+ */
+export declare const softErrorStatuses: (...statuses: number[]) => {
+    softErrorStatuses: number[];
+};
+/**
+ * The one opt-out from rule 2, for a request watching a restart the run it is
+ * following performs. Set it only while a run is known to be in flight — the
+ * update poll carries it while it holds a run it started or the server's last
+ * answer reported one going — because a 502 outside that window is the API being
+ * broken, which is exactly what rule 2 is for.
+ *
+ * A call site that sets this owns the whole wait, so the window outlives the
+ * budget: the give-up screen keeps polling a server it has stopped expecting,
+ * and a fatal page thrown over that verdict would replace the one screen that
+ * names the run and the log to read. A 500 from that same poll still escalates.
+ */
+export declare const restartExpectedMeta: {
+    restartExpected: true;
+};
+/** The record is not there. */
+export declare const isNotFound: (error: unknown) => boolean;

package/dist/src/lib/error-classifier.js

@@ -0,0 +1,213 @@
+import { ApiError } from "./api";
+import { NetworkError } from "./network-error";
+/**
+ * Extract an HTTP status code from a thrown error, regardless of which client
+ * raised it.
+ *
+ * Two client shapes coexist in the web client:
+ *  - the hand-written `api` wrapper throws `ApiError` (carries `.status`);
+ *  - the generated `@remit/api-http-client` (hey-api) throws the parsed JSON error
+ *    body. A response interceptor (see `lib/client.ts`) re-wraps those as
+ *    `ApiError` too, so in practice both paths carry `.status`. As a belt-and-
+ *    braces fallback we also read a numeric `status`/`statusCode` off a plain
+ *    object.
+ */
+export const getErrorStatus = (error) => {
+    if (error instanceof ApiError)
+        return error.status;
+    if (error && typeof error === "object") {
+        const candidate = error;
+        if (typeof candidate.status === "number")
+            return candidate.status;
+        if (typeof candidate.statusCode === "number")
+            return candidate.statusCode;
+    }
+    return undefined;
+};
+/** The error carries a real HTTP status — our API answered. */
+export const hasHttpStatus = (error) => getErrorStatus(error) !== undefined;
+/** A genuine first-party server failure: an HTTP 5xx. */
+export const isServerError = (error) => {
+    const status = getErrorStatus(error);
+    return status !== undefined && status >= 500 && status <= 599;
+};
+/**
+ * A deliberately cancelled request (route change, React Query cancellation).
+ * Never a failure.
+ */
+export const isAbortError = (error) => {
+    if (typeof DOMException !== "undefined" &&
+        error instanceof DOMException &&
+        error.name === "AbortError") {
+        return true;
+    }
+    if (error &&
+        typeof error === "object" &&
+        "name" in error &&
+        error.name === "AbortError") {
+        return true;
+    }
+    return false;
+};
+const isOffline = () => typeof navigator !== "undefined" && navigator.onLine === false;
+/**
+ * A transport failure from a wifi drop, tab wake, captive portal, or a timeout:
+ * the request never reached a server, so it is environmental, not a proven
+ * first-party failure.
+ *
+ * This is decided at the fetch boundary, not inferred here. Every app-owned
+ * request goes through `taggedFetch`, which knows a `fetch()` rejection is
+ * transport-level because `fetch` rejects for no other reason, and tags it a
+ * `NetworkError`. Reading that tag is exact; matching browser failure strings
+ * was not — the list is open-ended (WebKit alone has four, undici another) and
+ * anything missed would put a full-screen fatal page in front of someone who
+ * had merely walked out of wifi range.
+ *
+ * `navigator.onLine === false` is kept as a second signal for an error that
+ * reached us from outside that boundary while the browser reports no
+ * connectivity at all.
+ */
+export const isNetworkError = (error) => {
+    if (isAbortError(error))
+        return false;
+    if (hasHttpStatus(error))
+        return false;
+    if (error instanceof NetworkError)
+        return true;
+    return isOffline();
+};
+/**
+ * An exception raised by our own client code rather than by a request: it
+ * carries no HTTP status, is not an abort, and was not tagged as transport.
+ * That leaves a programming error — the one class the user can do nothing
+ * about and must never be asked to shrug off.
+ */
+export const isClientBug = (error) => !hasHttpStatus(error) && !isAbortError(error) && !isNetworkError(error);
+/**
+ * Fatal with no opt-out: our API answered "I'm broken", or our own code threw.
+ * Neither is something a call site can reclassify as soft, and neither may be
+ * reduced to a dismissible banner — both belong on the full-screen page, which
+ * offers a way forward and a bug report (issue #55).
+ */
+export const isAlwaysFatal = (error) => isServerError(error) || isClientBug(error);
+/**
+ * The session is gone. Not 403: a handler answers 403 for a resource belonging
+ * to another account config, which is a refusal a call site can state where it
+ * stands. A 401 is the user signed out from under whatever they were doing.
+ */
+export const isUnauthenticated = (error) => getErrorStatus(error) === 401;
+const isSoftErrorMeta = (error, meta) => {
+    if (meta?.softError === true)
+        return true;
+    const owned = meta?.softErrorStatuses;
+    if (!Array.isArray(owned))
+        return false;
+    const status = getErrorStatus(error);
+    return status !== undefined && owned.includes(status);
+};
+/**
+ * The statuses answered for the seconds a service is not there. Every `/api/*`
+ * request is proxied to apisix, which stays up while the backend behind it
+ * restarts and refuses in milliseconds — the 29ms 502 in #468, not a dial Caddy
+ * waited out. 503 and 504 are the same gap through a hop that answers
+ * differently.
+ */
+const RESTART_GAP_STATUSES = [502, 503, 504];
+/**
+ * The gap in a restart this call site asked for. A self-update stops and starts
+ * the backend on purpose, so the poll watching that run meets a proxy with
+ * nothing behind it — the designed shape of the operation the user pressed, not
+ * our API answering "I'm broken".
+ *
+ * A 500 is not in it: a server that answered is a server that is up, and up and
+ * broken is never designed.
+ */
+const isDesignedRestartGap = (error, meta) => {
+    if (meta?.restartExpected !== true)
+        return false;
+    const status = getErrorStatus(error);
+    return status !== undefined && RESTART_GAP_STATUSES.includes(status);
+};
+/**
+ * The single fail-fast decision: should this error escalate to the full-screen
+ * fatal overlay? Default is YES — a non-2xx must never silently vanish.
+ *
+ * The contract (issue #1059):
+ *  1. DEFAULT = escalate.
+ *  2. A 5xx (500–599) ALWAYS escalates — no opt-out, even on a background
+ *     refetch, even when the call site marked `meta.softError`. Our API
+ *     answered "I'm broken"; that is never benign. The single exception is a
+ *     502/503/504 on a call site that declared it is polling across a restart it
+ *     asked for (`meta.restartExpected`, #468): there the backend being gone is
+ *     the operation working, and that call site renders the wait itself.
+ *  3. A client-side exception ALWAYS escalates, on the same terms. It is our
+ *     bug; there is nothing for the user to retry and nothing to dismiss.
+ *  4. A 401 on a request the user is waiting on ALWAYS escalates, on the same
+ *     terms. Dismissing it leaves them signed out with no way back in, and a
+ *     send that keeps failing becomes a loop with no exit — `BetterAuthShell`
+ *     re-gates only when `useSession()` revalidates, which a banner never makes
+ *     happen. See `Awaiting` for what nobody waiting on it means.
+ *  5. The ONLY soft (do-NOT-escalate) exemptions:
+ *     a. aborts / cancellations — never a failure;
+ *     b. network/offline errors — environmental, recovered by React Query's
+ *        reconnect/retry;
+ *     c. a non-5xx error on a query/mutation that opted out via
+ *        `meta.softError === true` — the call site owns that error's UX
+ *        (e.g. a 404 empty state, a 4xx "Reconnect" banner) — or, where it owns
+ *        one status and not the rest, `meta.softErrorStatuses`.
+ */
+export const shouldEscalate = (error, meta, awaiting = "nobody") => {
+    if (isServerError(error))
+        return !isDesignedRestartGap(error, meta);
+    if (isAbortError(error))
+        return false;
+    if (isNetworkError(error))
+        return false;
+    if (awaiting === "user" && isUnauthenticated(error))
+        return true;
+    if (isAlwaysFatal(error))
+        return true;
+    if (isSoftErrorMeta(error, meta))
+        return false;
+    return true;
+};
+/**
+ * The meta a call site sets to keep its own non-5xx failures off the
+ * full-screen fatal page, because it renders them itself — a banner, a retry,
+ * an empty state. Rules 2, 3 and 4 above still win: a 5xx, a client-side
+ * exception, and a 401 on something the user is waiting on, escalate regardless.
+ *
+ * Two classes of call site must always carry it. One is a request the user
+ * never asked for and is not waiting on — a debounced autosave, a
+ * dwell-triggered mark-as-read: a refusal there is not news worth stopping the
+ * app for. The other is any surface holding text the user has not finished
+ * writing. The fatal page unmounts the app, so escalating from a composer
+ * throws the message away and leaves nothing to retry, which is a worse outcome
+ * than the failure it reports.
+ */
+export const softErrorMeta = { softError: true };
+/**
+ * The narrow form, for a call site that owns one outcome and none of the others.
+ * A read whose record may legitimately be gone owns the 404 and nothing else: a
+ * blanket `softErrorMeta` there would also swallow the 401 and the 403, and a
+ * background read that answers a lapsed session with nothing leaves the user
+ * looking at a screen that has quietly stopped working.
+ */
+export const softErrorStatuses = (...statuses) => ({ softErrorStatuses: statuses });
+/**
+ * The one opt-out from rule 2, for a request watching a restart the run it is
+ * following performs. Set it only while a run is known to be in flight — the
+ * update poll carries it while it holds a run it started or the server's last
+ * answer reported one going — because a 502 outside that window is the API being
+ * broken, which is exactly what rule 2 is for.
+ *
+ * A call site that sets this owns the whole wait, so the window outlives the
+ * budget: the give-up screen keeps polling a server it has stopped expecting,
+ * and a fatal page thrown over that verdict would replace the one screen that
+ * names the run and the log to read. A 500 from that same poll still escalates.
+ */
+export const restartExpectedMeta = {
+    restartExpected: true,
+};
+/** The record is not there. */
+export const isNotFound = (error) => getErrorStatus(error) === 404;