@remit/web-client 0.0.325 → 0.0.327

package/dist/src/lib/config-import.js

@@ -0,0 +1,371 @@
+/**
+ * What a config import report means on screen (#1021).
+ *
+ * `POST /config/import` answers with one flat report: per-item verdicts, a list
+ * of blocking errors and a list of non-blocking warnings, each keyed by a code.
+ * The screens group that into sections, and turn a code into copy that says
+ * what failed and what to do about it. Nothing here touches the network or the
+ * DOM, so every branch the wizard can land in is decidable in a unit test.
+ */
+// `ApiError` above is the wire model for an error body; this is the thrown
+// wrapper `lib/client.ts` puts every HTTP failure in.
+import { ApiError as ThrownApiError } from "./api.js";
+import { getErrorStatus } from "./error-classifier.js";
+import { safeJsonParse } from "./json.js";
+export const IMPORT_SECTION_ORDER = [
+    "accounts",
+    "labels",
+    "filters",
+    "addressFlags",
+    "settings",
+];
+const SECTION_TITLES = {
+    accounts: "Accounts",
+    labels: "Labels",
+    filters: "Rules & filters",
+    addressFlags: "Senders",
+    settings: "Folders & appearance",
+};
+export const IMPORT_VERDICTS = [
+    "created",
+    "updated",
+    "unchanged",
+    "skipped",
+    "rejected",
+];
+export const verdictTone = {
+    created: "positive",
+    updated: "accent",
+    unchanged: "neutral",
+    skipped: "warning",
+    rejected: "danger",
+};
+/**
+ * The wire model spells the verdict as a plain string, so a value this client
+ * does not know reads as rejected rather than as an unstyled row: an item the
+ * screen cannot vouch for is one the reader must look at.
+ */
+export const asVerdict = (value) => IMPORT_VERDICTS.includes(value)
+    ? value
+    : "rejected";
+/**
+ * A section this client does not know is not folded into one it does. Quietly
+ * filing an unrecognised item under "settings" would tell the reader something
+ * false about what a newer Reader's file is doing to their configuration, which
+ * is the failure the whole format exists to prevent. Unknown reads as unknown,
+ * and the screen shows it under its own heading.
+ */
+export const UNKNOWN_SECTION = "unknown";
+export const asSection = (value) => IMPORT_SECTION_ORDER.includes(value)
+    ? value
+    : undefined;
+export const groupReportSections = (items) => {
+    const grouped = new Map();
+    items.forEach((item, index) => {
+        const section = asSection(item.section) ?? UNKNOWN_SECTION;
+        const entries = grouped.get(section) ?? [];
+        entries.push({
+            id: `${section}-${item.key}-${index}`,
+            label: item.key,
+            verdict: asVerdict(item.verdict),
+            reason: section === UNKNOWN_SECTION
+                ? (item.reason ??
+                    `This instance does not know the "${item.section}" section, so it cannot say what this entry does.`)
+                : item.reason,
+        });
+        grouped.set(section, entries);
+    });
+    const ordered = [...IMPORT_SECTION_ORDER, UNKNOWN_SECTION];
+    return ordered
+        .filter((section) => grouped.has(section))
+        .map((section) => ({
+        id: section,
+        title: section === UNKNOWN_SECTION
+            ? "Not recognised"
+            : SECTION_TITLES[section],
+        entries: grouped.get(section) ?? [],
+    }));
+};
+export const countVerdicts = (items) => {
+    const counts = {
+        created: 0,
+        updated: 0,
+        unchanged: 0,
+        skipped: 0,
+        rejected: 0,
+    };
+    for (const item of items)
+        counts[asVerdict(item.verdict)] += 1;
+    return counts;
+};
+const READ_FAILURE_COPY = {
+    NotAnObject: () => ({
+        title: "That is not a Reader config file",
+        explanation: "The file was read, but it is not a configuration document — a Reader config is a JSON object carrying a kind and a schemaVersion.",
+        fix: "Export one from Settings › Advanced on the instance you are moving from, or run remit config save on its host.",
+    }),
+    WrongKind: () => ({
+        title: "That is not a Reader config file",
+        explanation: "The file parses as JSON but does not declare itself a Reader configuration, so nothing here can be trusted to mean what it looks like.",
+        fix: "Export one from Settings › Advanced on the instance you are moving from, or run remit config save on its host.",
+    }),
+    UnsupportedVersion: (error) => ({
+        title: "This file was written by a newer Reader",
+        explanation: error.message ||
+            "The file declares a schema version this instance does not read, so importing it would drop settings it cannot understand.",
+        fix: "Update this Reader, then import again. The file is unchanged and safe to keep.",
+    }),
+    UnknownKeys: (error) => ({
+        title: "The file contains settings this version does not know",
+        explanation: "An unknown key is refused rather than quietly dropped: losing configuration without saying so is exactly what this feature exists to prevent.",
+        fix: `Update this Reader, or remove the named keys from the file and import again. ${error.message}`,
+    }),
+    CredentialPresent: () => ({
+        title: "The file carries a credential",
+        explanation: "A configuration document describes which credential an account needs; it never carries one. Reader refuses the file rather than importing around it — the secret may now be in your backups, your chat history, or a pull request.",
+        fix: "Delete the field from the file and import again, then change that mailbox's password. Exports written by Reader never contain one.",
+    }),
+    Malformed: (error) => ({
+        title: "The file does not match the configuration format",
+        explanation: "Every part of the document has to validate before anything is written, and this one does not.",
+        fix: `Re-export it from the instance you are moving from. ${error.message}`,
+    }),
+    duplicate_key: (error) => ({
+        title: "The file names something twice",
+        explanation: "A configuration names each account, label and filter once, so a document with two of the same key has no single answer to import.",
+        fix: `Remove the duplicate and import again. ${error.message}`,
+    }),
+    unknown_label: (error) => ({
+        title: "A rule points at a label that is not here",
+        explanation: "The file applies a label neither it nor this instance carries, so the rule would land doing nothing.",
+        fix: `Add the label to the file, or create it here first, then import again. ${error.message}`,
+    }),
+    unknown_account: (error) => ({
+        title: "A rule points at an account that is not here",
+        explanation: "The file files mail into a folder on an account it does not carry, so the rule has no destination to bind to.",
+        fix: `Export the configuration again from an instance that holds both, then import that file. ${error.message}`,
+    }),
+};
+const UNRECOGNISED_FAILURE = (error) => ({
+    title: "The file could not be imported",
+    explanation: error.message || "The import was refused and nothing was written.",
+    fix: "Re-export the configuration from the instance you are moving from and try again. If it keeps failing, report it with the line below.",
+});
+export const WRITE_FAILURE_CODE = "import_write_failed";
+export const CONFLICT_CODE = "config_not_empty";
+/**
+ * The 409 a non-empty configuration answers with, or nothing.
+ *
+ * The endpoint's body is flat — `code`, `message`, `details` — but it does not
+ * always arrive that way: `lib/client.ts` re-wraps every HTTP failure as an
+ * `ApiError` so the fail-fast classifier can read a status off it, and that
+ * moves the body onto `error.body`. Reading the code off the error itself finds
+ * nothing there and turns the refusal into "check your connection", which is
+ * how the abort-or-merge screen became unreachable. Both shapes are checked,
+ * and the code is what decides: a status is confirmation where there is one,
+ * never the thing being matched on.
+ */
+export const readConflict = (error) => {
+    const status = getErrorStatus(error);
+    if (status !== undefined && status !== 409)
+        return undefined;
+    const body = error instanceof ThrownApiError ? error.body : error;
+    if (typeof body !== "object" || body === null)
+        return undefined;
+    const flat = body;
+    if (flat.code !== CONFLICT_CODE)
+        return undefined;
+    return {
+        message: typeof flat.message === "string" ? flat.message : "",
+        details: typeof flat.details === "object" && flat.details !== null
+            ? flat.details
+            : undefined,
+    };
+};
+/**
+ * The blocking failure to render, when there is one. `import_write_failed` is
+ * deliberately not one of these: the import got past validation and part of it
+ * may be live, which is a different screen with a different instruction.
+ */
+export const readFailure = (report) => {
+    const error = report.errors.find((it) => it.code !== WRITE_FAILURE_CODE);
+    if (!error)
+        return undefined;
+    const build = READ_FAILURE_COPY[error.code] ?? UNRECOGNISED_FAILURE;
+    return { ...build(error), raw: `${error.code}: ${error.message}` };
+};
+export const writeFailure = (report) => report.errors.find((it) => it.code === WRITE_FAILURE_CODE);
+const NOT_LANDED_DETAIL = "Nothing from this section was written.";
+/**
+ * What a stopped import wrote, section by section. The write order is fixed, so
+ * the section the failure names splits the document in three: what is before it
+ * ran, it did not, and what is after it was never reached.
+ *
+ * `applied` is the server's answer on whether any of it was written, because
+ * only the backend knows whether it had a transaction: false means no section
+ * of the file was written, however far the write order got. It does not say
+ * why — a transaction undid the earlier writes, or the first one failed — and
+ * the report carries no flag that does, so this says what the file put in and
+ * never what the instance now holds.
+ *
+ * A failure that names no section leaves the split undecidable, and every
+ * section reads `unknown` rather than `landed`. Telling someone their accounts
+ * are in when nothing said so is the one answer this screen must never give:
+ * they would stop looking.
+ */
+export const sectionResults = (report) => {
+    const failure = writeFailure(report);
+    const named = failure?.details?.section;
+    const failedSection = named ? asSection(named) : undefined;
+    const nothingLanded = !report.applied;
+    const counts = new Map();
+    for (const item of report.items) {
+        if (asVerdict(item.verdict) === "rejected")
+            continue;
+        const section = asSection(item.section);
+        if (!section)
+            continue;
+        counts.set(section, (counts.get(section) ?? 0) + 1);
+    }
+    const everySection = (state, detail) => IMPORT_SECTION_ORDER.map((section) => ({
+        section,
+        title: SECTION_TITLES[section],
+        state,
+        detail,
+    }));
+    if (!failedSection) {
+        if (nothingLanded)
+            return everySection("not-landed", NOT_LANDED_DETAIL);
+        const detail = named
+            ? `The import stopped in "${named}", which this instance does not recognise, so it cannot say whether this section was written.`
+            : "The import stopped without naming where, so it cannot say whether this section was written. Open Settings to see what is here.";
+        return everySection("unknown", detail);
+    }
+    const failedAt = IMPORT_SECTION_ORDER.indexOf(failedSection);
+    return IMPORT_SECTION_ORDER.map((section, index) => {
+        const title = SECTION_TITLES[section];
+        if (section === failedSection) {
+            return {
+                section,
+                title,
+                state: "failed",
+                detail: failure?.message ?? "This section could not be written.",
+            };
+        }
+        if (index > failedAt) {
+            return {
+                section,
+                title,
+                state: "not-attempted",
+                detail: "Not attempted — the import stopped before this section.",
+            };
+        }
+        if (nothingLanded) {
+            return {
+                section,
+                title,
+                state: "not-landed",
+                detail: NOT_LANDED_DETAIL,
+            };
+        }
+        const written = counts.get(section) ?? 0;
+        return {
+            section,
+            title,
+            state: "landed",
+            detail: written === 0
+                ? "Nothing in the file for this section."
+                : `${written} ${written === 1 ? "entry" : "entries"} written.`,
+        };
+    });
+};
+export const FOLDER_PENDING_CODE = "folder_not_found_yet";
+/**
+ * The folders the file names that this account does not hold yet. They are
+ * recorded rather than dropped: the binder writes each setting the moment IMAP
+ * discovery produces its folder, so the copy has to say waiting, never lost.
+ */
+export const pendingFolders = (report) => {
+    const seen = new Set();
+    const folders = [];
+    for (const warning of report.warnings) {
+        if (warning.code !== FOLDER_PENDING_CODE)
+            continue;
+        const path = warning.details?.folderPath;
+        if (!path)
+            continue;
+        const filter = warning.details?.filter;
+        const accountId = warning.details?.accountId;
+        const key = `${accountId ?? ""}:${path}:${filter ?? ""}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        folders.push({
+            path,
+            accountId,
+            waitingFor: filter
+                ? `Rule “${filter}”`
+                : "A folder role or a folder's own settings",
+        });
+    }
+    return folders;
+};
+/* ------------------------------------------------------------------ */
+/* Reading a file off disk                                            */
+/* ------------------------------------------------------------------ */
+/**
+ * A config document is small — the largest realistic export is tens of
+ * kilobytes — so anything past this is a file picked by mistake, and saying so
+ * beats posting megabytes to be told the same thing.
+ */
+export const MAX_CONFIG_FILE_BYTES = 2 * 1024 * 1024;
+const NOT_JSON = Symbol("not json");
+export const readConfigText = async (name, size, text) => {
+    if (size > MAX_CONFIG_FILE_BYTES) {
+        return {
+            ok: false,
+            failure: {
+                title: "That file is too large to be a config file",
+                explanation: `${name} is ${Math.round(size / 1024)} kB. A Reader configuration is tens of kilobytes; a file this size is something else.`,
+                fix: "Pick the .json file written by Settings › Advanced, or by remit config save.",
+                raw: `${size} bytes > ${MAX_CONFIG_FILE_BYTES} byte limit`,
+            },
+        };
+    }
+    let syntaxError = "";
+    const parsed = await safeJsonParse(text).catch((cause) => {
+        syntaxError = cause instanceof Error ? cause.message : String(cause);
+        return NOT_JSON;
+    });
+    if (parsed === NOT_JSON) {
+        return {
+            ok: false,
+            failure: {
+                title: "That file is not JSON",
+                explanation: `${name} could not be read as JSON at all, so there is nothing in it to import.`,
+                fix: "Pick the .json file written by Settings › Advanced, or by remit config save.",
+                raw: syntaxError,
+            },
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return {
+            ok: false,
+            failure: {
+                title: "That is not a Reader config file",
+                explanation: `${name} is valid JSON but not a configuration document — a Reader config is a JSON object carrying a kind and a schemaVersion.`,
+                fix: "Export one from Settings › Advanced on the instance you are moving from, or run remit config save on its host.",
+                raw: `expected a JSON object, found ${Array.isArray(parsed) ? "an array" : typeof parsed}`,
+            },
+        };
+    }
+    return { ok: true, document: parsed };
+};
+/* ------------------------------------------------------------------ */
+/* The export half                                                    */
+/* ------------------------------------------------------------------ */
+export const exportFileName = (now) => {
+    const iso = now.toISOString().slice(0, 10);
+    return `reader-config.${iso}.json`;
+};
+export const formatFileSize = (bytes) => bytes < 1024 ? `${bytes} B` : `${Math.round(bytes / 1024)} kB`;

package/dist/src/lib/console-errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tiny ring-buffer that captures the last N console errors, uncaught
+ * exceptions, and unhandled promise rejections. Install once at app
+ * startup; consumers call getRecentErrors() to read the buffer.
+ *
+ * Dependency-free and side-effect-free until install() is called.
+ */
+/**
+ * Record a single line into the recent-errors ring. Exposed so the global
+ * `reportFatalError` seam (lib/fatal-error.ts) can land fatal errors in the
+ * same buffer the bug-report flow reads, without re-implementing the ring.
+ */
+export declare function recordError(entry: string): void;
+export declare function install(): void;
+/** Returns a copy of the captured entries (oldest first, up to 20). */
+export declare function getRecentErrors(): readonly string[];

package/dist/src/lib/console-errors.js

@@ -0,0 +1,80 @@
+/**
+ * Tiny ring-buffer that captures the last N console errors, uncaught
+ * exceptions, and unhandled promise rejections. Install once at app
+ * startup; consumers call getRecentErrors() to read the buffer.
+ *
+ * Dependency-free and side-effect-free until install() is called.
+ */
+import { reportFatalError } from "./fatal-error";
+const MAX_ENTRIES = 20;
+const ring = [];
+// Browser-spec noise, not app errors: the ResizeObserver spec fires these when
+// observation callbacks don't settle within a frame. They surface as window
+// `error` events with a null `error` and are safe to ignore. The live message
+// carries a trailing period, so strip it before matching this canonical set.
+const BENIGN_RESIZE_OBSERVER_MESSAGES = new Set([
+    "ResizeObserver loop limit exceeded",
+    "ResizeObserver loop completed with undelivered notifications",
+]);
+function isBenignResizeObserverError(message) {
+    if (typeof message !== "string")
+        return false;
+    return BENIGN_RESIZE_OBSERVER_MESSAGES.has(message.replace(/\.\s*$/, ""));
+}
+function push(entry) {
+    ring.push(entry);
+    if (ring.length > MAX_ENTRIES)
+        ring.shift();
+}
+/**
+ * Record a single line into the recent-errors ring. Exposed so the global
+ * `reportFatalError` seam (lib/fatal-error.ts) can land fatal errors in the
+ * same buffer the bug-report flow reads, without re-implementing the ring.
+ */
+export function recordError(entry) {
+    push(entry);
+}
+function formatArgs(args) {
+    return args
+        .map((a) => {
+        if (typeof a === "string")
+            return a;
+        if (a instanceof Error)
+            return `${a.name}: ${a.message}`;
+        try {
+            return JSON.stringify(a);
+        }
+        catch {
+            return String(a);
+        }
+    })
+        .join(" ");
+}
+export function install() {
+    const originalError = console.error.bind(console);
+    console.error = (...args) => {
+        push(formatArgs(args));
+        originalError(...args);
+    };
+    window.addEventListener("error", (event) => {
+        if (isBenignResizeObserverError(event.message))
+            return;
+        push(`Uncaught ${event.error instanceof Error ? `${event.error.name}: ${event.error.message}` : String(event.message)} (${event.filename}:${event.lineno})`);
+        // An uncaught exception is, by definition, unhandled — escalate it.
+        reportFatalError(event.error ?? event.message);
+    });
+    window.addEventListener("unhandledrejection", (event) => {
+        const reason = event.reason;
+        const detail = reason instanceof Error
+            ? `${reason.name}: ${reason.message}`
+            : String(reason);
+        push(`Unhandled rejection: ${detail}`);
+        // A rejection that bubbles to the window was never handled by any
+        // caller — route it through the same fatal seam.
+        reportFatalError(reason);
+    });
+}
+/** Returns a copy of the captured entries (oldest first, up to 20). */
+export function getRecentErrors() {
+    return ring.slice();
+}

package/dist/src/lib/conversation-target.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What the reading pane needs to show a conversation.
+ *
+ * The thread is the whole address — `ConversationView` fetches by it — and the
+ * rest is what the list already knows about the row the reader pointed at, so
+ * the pane paints a subject before the thread's own messages arrive. A thread no
+ * list holds carries none of it and still opens.
+ */
+import type { RemitImapMessageAuthenticity } from "@remit/api-http-client/types.gen.ts";
+export interface ConversationTarget {
+    threadId: string;
+    mailboxId: string;
+    subject?: string;
+    messageId?: string;
+    authenticity?: RemitImapMessageAuthenticity;
+}

package/dist/src/lib/conversation-target.js

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

package/dist/src/lib/dedupe-thread-messages.d.ts

@@ -0,0 +1,14 @@
+import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+/**
+ * Pure helper: collapse a flattened list of thread messages to one row per
+ * `threadMessageId`, keeping the first occurrence.
+ *
+ * Belt-and-braces guard for issue #166. The web client appends every fetched
+ * page as-is and relies on the keyset cursor never handing back an overlapping
+ * page. `threadMessageId` is unique per message, so two rows sharing one are
+ * the same message — dropping the later row removes a duplicate, never a
+ * distinct result. Applied where pages are flattened into the list, so every
+ * consumer of the list sees a clean array and no render site has to remember
+ * to dedupe.
+ */
+export declare const dedupeThreadMessages: (items: RemitImapThreadMessageResponse[]) => RemitImapThreadMessageResponse[];

package/dist/src/lib/dedupe-thread-messages.js

@@ -0,0 +1,23 @@
+/**
+ * Pure helper: collapse a flattened list of thread messages to one row per
+ * `threadMessageId`, keeping the first occurrence.
+ *
+ * Belt-and-braces guard for issue #166. The web client appends every fetched
+ * page as-is and relies on the keyset cursor never handing back an overlapping
+ * page. `threadMessageId` is unique per message, so two rows sharing one are
+ * the same message — dropping the later row removes a duplicate, never a
+ * distinct result. Applied where pages are flattened into the list, so every
+ * consumer of the list sees a clean array and no render site has to remember
+ * to dedupe.
+ */
+export const dedupeThreadMessages = (items) => {
+    const seen = new Set();
+    const deduped = [];
+    for (const item of items) {
+        if (seen.has(item.threadMessageId))
+            continue;
+        seen.add(item.threadMessageId);
+        deduped.push(item);
+    }
+    return deduped;
+};

package/dist/src/lib/delete-folder.d.ts

@@ -0,0 +1,66 @@
+import type { RemitImapFolderAppointment } from "@remit/api-http-client/types.gen.ts";
+export declare const MOVE_BATCH_SIZE = 100;
+export interface FolderNode {
+    mailboxId: string;
+    fullPath: string;
+    hierarchyDelimiter: string;
+    messageCount: number;
+    /** RFC 6154 SPECIAL-USE flags, bare (`Trash`, not `\Trash`). */
+    specialUse?: readonly string[];
+}
+/** Where a role's answer came from. */
+export type RoleAppointmentSource = RemitImapFolderAppointment["source"];
+export interface RoleAppointment {
+    role: string;
+    source: RoleAppointmentSource;
+    mailboxId?: string | null;
+}
+export type DeleteBlockReason = "inbox" | "role" | "children";
+export interface DeleteGuard {
+    deletable: boolean;
+    reason?: DeleteBlockReason;
+    message?: string;
+}
+/**
+ * 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 declare const hasChildFolders: (folder: Pick<FolderNode, "mailboxId" | "fullPath" | "hierarchyDelimiter">, all: readonly Pick<FolderNode, "mailboxId" | "fullPath">[]) => boolean;
+/** The canonical role a folder is vouched for, or `undefined` when none is. */
+export declare const vouchedRole: (folder: Pick<FolderNode, "mailboxId" | "specialUse">, appointments: readonly RoleAppointment[]) => string | undefined;
+/**
+ * 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 declare function guardFolderDeletion(folder: FolderNode, all: readonly FolderNode[], appointments: readonly RoleAppointment[]): DeleteGuard;
+/** Destinations with the folder being deleted removed. */
+export declare function excludeFolder<T extends {
+    mailboxId: string;
+}>(targets: readonly T[], excludeMailboxId: string): T[];
+export type MovePhase = "moving" | "moved" | "failed";
+export interface MoveProgress {
+    total: number;
+    moved: number;
+    phase: MovePhase;
+    error?: string;
+}
+/** Progress at the start of a move; an empty set is already `moved`. */
+export declare function beginMove(total: number): MoveProgress;
+/**
+ * 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 declare function advanceMove(progress: MoveProgress, batchSize: number): MoveProgress;
+/** A failed batch stops progress and surfaces the error; nothing advances after. */
+export declare function failMove(progress: MoveProgress, error: string): MoveProgress;
+export declare function moveProgressLabel(progress: MoveProgress): string;
+/** How long a wait has run, as `m:ss` — clamped at zero so a clock skew reads as 0:00. */
+export declare function elapsedLabel(ms: number): string;
+/** Where the wizard opens: a straight confirm for an empty folder, otherwise the fate step. */
+export declare function initialStage(messageCount: number): "confirm-empty" | "choose-fate";