@remit/web-client 0.0.324 → 0.0.326

package/src/lib/format.ts

@@ -1,397 +0,0 @@
-import {
-	type FolderAppointmentSourceValue,
-	trashSourceMeetsAssurance,
-} from "@remit/data-ports/folder-role";
-
-/**
- * Get the user's preferred locale from browser settings.
- * Falls back to 'en-US' if unavailable.
- */
-const getLocale = (): string => {
-	if (typeof navigator !== "undefined") {
-		return navigator.language || navigator.languages?.[0] || "en-US";
-	}
-	return "en-US";
-};
-
-/**
- * Format a number according to user's locale.
- */
-export const formatNumber = (
-	value: number,
-	options?: Intl.NumberFormatOptions,
-): string => {
-	return new Intl.NumberFormat(getLocale(), options).format(value);
-};
-
-const EPOCH_STRING = /^-?\d+$/;
-
-/**
- * Coerce any accepted date input into a Date. An all-digit string is treated as
- * an epoch (the Postgres read path serializes int64 columns as numeric strings);
- * any other string goes through the normal Date parser.
- */
-export const toDate = (value: Date | string | number): Date => {
-	if (value instanceof Date) return value;
-	if (typeof value === "number") return new Date(value);
-	if (typeof value === "string") {
-		const trimmed = value.trim();
-		if (EPOCH_STRING.test(trimmed)) return new Date(Number(trimmed));
-		return new Date(trimmed);
-	}
-	return new Date(Number.NaN);
-};
-
-const isValidDate = (date: Date): boolean => Number.isFinite(date.getTime());
-
-/**
- * Format a date according to user's locale. A missing or unparseable date
- * renders as an empty string instead of throwing — display must never crash the
- * view over one bad row.
- */
-export const formatDate = (
-	date: Date | string | number,
-	options?: Intl.DateTimeFormatOptions,
-): string => {
-	const d = toDate(date);
-	if (!isValidDate(d)) return "";
-	return new Intl.DateTimeFormat(getLocale(), options).format(d);
-};
-
-/**
- * Format date with common presets.
- */
-export const formatDatePreset = (
-	date: Date | string | number,
-	preset: "short" | "medium" | "long" | "full" | "time" | "datetime",
-): string => {
-	const presets: Record<typeof preset, Intl.DateTimeFormatOptions> = {
-		short: { month: "short", day: "numeric" },
-		medium: { month: "short", day: "numeric", year: "numeric" },
-		long: { month: "long", day: "numeric", year: "numeric" },
-		full: { weekday: "long", month: "long", day: "numeric", year: "numeric" },
-		time: { hour: "numeric", minute: "numeric" },
-		datetime: {
-			month: "short",
-			day: "numeric",
-			hour: "numeric",
-			minute: "numeric",
-		},
-	};
-	return formatDate(date, presets[preset]);
-};
-
-/**
- * Format relative time (e.g., "2 hours ago", "in 3 days").
- */
-export const formatRelativeTime = (date: Date | string | number): string => {
-	const d = toDate(date);
-	if (!isValidDate(d)) return "";
-	const rtf = new Intl.RelativeTimeFormat(getLocale(), { numeric: "auto" });
-	const now = Date.now();
-	const diff = d.getTime() - now;
-	const diffSeconds = Math.round(diff / 1000);
-	const diffMinutes = Math.round(diff / (1000 * 60));
-	const diffHours = Math.round(diff / (1000 * 60 * 60));
-	const diffDays = Math.round(diff / (1000 * 60 * 60 * 24));
-	const diffWeeks = Math.round(diff / (1000 * 60 * 60 * 24 * 7));
-
-	if (Math.abs(diffSeconds) < 60) {
-		return rtf.format(diffSeconds, "second");
-	}
-	if (Math.abs(diffMinutes) < 60) {
-		return rtf.format(diffMinutes, "minute");
-	}
-	if (Math.abs(diffHours) < 24) {
-		return rtf.format(diffHours, "hour");
-	}
-	if (Math.abs(diffDays) < 7) {
-		return rtf.format(diffDays, "day");
-	}
-	if (Math.abs(diffWeeks) < 4) {
-		return rtf.format(diffWeeks, "week");
-	}
-
-	return formatDatePreset(d, "medium");
-};
-
-/**
- * Format email date intelligently based on age.
- * - Today: "10:42" (time only)
- * - Yesterday: "Yesterday"
- * - This week: "Tuesday" (day name)
- * - Older: "Jan 17" (or "Jan 17, 2023" if different year)
- */
-export const formatEmailDate = (date: Date | string | number): string => {
-	const d = toDate(date);
-	if (!isValidDate(d)) return "";
-	const now = new Date();
-
-	const isToday = d.toDateString() === now.toDateString();
-
-	const yesterday = new Date(now);
-	yesterday.setDate(yesterday.getDate() - 1);
-	const isYesterday = d.toDateString() === yesterday.toDateString();
-
-	const sixDaysAgo = new Date(now);
-	sixDaysAgo.setDate(sixDaysAgo.getDate() - 6);
-	const isThisWeek = d >= sixDaysAgo && d < now;
-
-	const isThisYear = d.getFullYear() === now.getFullYear();
-
-	if (isToday) {
-		return formatDate(d, { hour: "numeric", minute: "numeric" });
-	}
-	if (isYesterday) {
-		return "Yesterday";
-	}
-	if (isThisWeek) {
-		return formatDate(d, { weekday: "long" });
-	}
-	if (isThisYear) {
-		return formatDate(d, { month: "short", day: "numeric" });
-	}
-	return formatDate(d, { month: "short", day: "numeric", year: "numeric" });
-};
-
-/**
- * Confirmation title for the move-to-Trash delete flow. Reflects that delete
- * moves messages to Trash (not a permanent delete) and pluralizes on count.
- * The count is always a concrete list of ids — every predicate delete ends on
- * the wizard's review screen instead, which states what the predicate covers.
- */
-export const formatDeleteToTrashTitle = (count: number): string => {
-	const quantity = count === 1 ? "1" : formatNumber(count);
-	const noun = count === 1 ? "message" : "messages";
-	return `Move ${quantity} ${noun} to Trash?`;
-};
-
-export interface DeleteConfirmationCopy {
-	title: string;
-	description: string;
-	confirmLabel: string;
-}
-
-/**
- * What the caller knows about the account's Trash. Two folder names, never one:
- * the folder reader guessed and the folder that vanished are different facts.
- * Both optional — a caller holding no open mailbox passes neither, and the copy
- * drops the name clause rather than inventing one.
- */
-export interface DeleteConfirmationContext {
-	/** The folder reader files this account's deletes in. */
-	trashFolderLabel?: string;
-	/** The folder the user appointed, now gone from the mail server. */
-	staleFolderLabel?: string;
-}
-
-/**
- * What a delete will actually do to the selected mail.
- *
- * `unknown` is the state before the account's Trash appointment has resolved — a
- * real state on a cold open, and the one the copy must not guess at, because
- * guessing "move to Trash" over an expunge is the dishonesty this whole flow
- * exists to remove.
- *
- * `noTrash` is a resolved answer of "none": the account appoints no Trash, so
- * the server refuses the delete outright (#846) rather than moving anything.
- * It is a different fact from "this row is not in Trash" and must never share
- * an outcome with it — one promises a restore that can happen, the other a
- * delete that will not.
- *
- * `unavailable` is the appointment failing to resolve at all. A read that
- * cannot answer is not an answer: treating an errored `/config` as "no Trash
- * here" reinstates the same lie on the failure path, where an expired session
- * would collect "Move to Trash?" over an expunge. The delete is refused and the
- * failure is stated instead.
- *
- * `staleTrash` is a resolved answer of "the folder you chose is gone" (#887).
- * It is a repair rather than a first choice, and the copy says so, which a
- * single `noTrash` member cannot — this function only ever sees the member.
- *
- * `unconfirmed` is a folder reader matched by name that nobody ever confirmed.
- * Empty Trash refuses on it for the whole folder (D4); `deleteOutcomeFor`
- * produces it too, for the narrower case of a row that is already inside that
- * folder — deleting it expunges on the same name guess, and the guess is never
- * enough to destroy mail (#876). Both surfaces derive it from the server's own
- * 409, and the branch lives here so they word it identically.
- */
-export type DeleteOutcome =
-	| "trash"
-	| "permanent"
-	| "noTrash"
-	| "staleTrash"
-	| "unconfirmed"
-	| "unknown"
-	| "unavailable";
-
-/** Where an account's Trash answer came from (`FolderAppointmentSource`). */
-export type TrashSource = FolderAppointmentSourceValue;
-
-/** One account's Trash, as `/config` resolved it. */
-export interface TrashResolution {
-	mailboxId: string | undefined;
-	source: TrashSource;
-	/** `Stale` only: the path the folder the user chose last had. */
-	staleFolderPath?: string;
-}
-
-/** A row about to be deleted, and the account whose Trash decides its fate. */
-export interface DeleteTarget {
-	accountId: string | undefined;
-	mailboxId: string;
-}
-
-export interface DeleteOutcomeInput {
-	targets: readonly DeleteTarget[];
-	/**
-	 * Each account's Trash and where that answer came from. A key present is an
-	 * answer, `source` and all — a key absent is an account nothing is known
-	 * about yet.
-	 */
-	trashByAccount: ReadonlyMap<string, TrashResolution>;
-	/**
-	 * The appointments have actually arrived. Never `!isLoading`: React Query
-	 * v5 leaves a paused offline query pending-but-not-fetching, which reads as
-	 * loaded while `data` is still undefined.
-	 */
-	hasAppointments: boolean;
-	/** The read for them failed. */
-	isError: boolean;
-}
-
-/**
- * The outcome of deleting `targets`.
- *
- * One row bound for an expunge makes the whole delete unrecoverable, so a mixed
- * set is permanent: the wording may overstate what is destroyed, never what is
- * kept. One row on an account with no Trash refuses the whole call, so that
- * outranks both. An expunge on a Trash nobody confirmed outranks a plain
- * expunge in turn — the server refuses it (#876), so the dialog asks for the
- * same confirmation up front rather than offering a confirm that 409s. Pure,
- * so every branch — the failure ones above all — is testable without a DOM.
- */
-export const deleteOutcomeFor = ({
-	targets,
-	trashByAccount,
-	hasAppointments,
-	isError,
-}: DeleteOutcomeInput): DeleteOutcome => {
-	if (isError) return "unavailable";
-	if (!hasAppointments) return "unknown";
-	if (targets.length === 0) return "unknown";
-
-	let expunges = false;
-	let expungesUnconfirmed = false;
-	for (const target of targets) {
-		if (target.accountId === undefined) return "unknown";
-		const trash = trashByAccount.get(target.accountId);
-		if (trash === undefined) return "unknown";
-		if (trash.source === "Stale") return "staleTrash";
-		if (trash.mailboxId === undefined) return "noTrash";
-		if (trash.mailboxId === target.mailboxId) {
-			expunges = true;
-			if (!trashSourceMeetsAssurance(trash.source, "confirmed"))
-				expungesUnconfirmed = true;
-		}
-	}
-	if (expungesUnconfirmed) return "unconfirmed";
-	return expunges ? "permanent" : "trash";
-};
-
-/**
- * The delete erases mail rather than filing it. Both outcomes a row already
- * inside Trash produces say so — `unconfirmed` is only ever reached that way
- * (#876) — and anything that reports what a delete did reads this rather than
- * testing for `permanent`, which is how a run of expunged mail came to be
- * announced as "moved to Trash".
- */
-export const deleteExpunges = (outcome: DeleteOutcome): boolean =>
-	outcome === "permanent" || outcome === "unconfirmed";
-
-/**
- * The confirmation for a delete, worded for what the delete actually does.
- * Deleting mail that already sits in Trash expunges it on the server and
- * nothing survives that, so it is asked as a permanent delete — a dialog that
- * says "Move to Trash" over an expunge collects an answer to a question the
- * user was never asked.
- *
- * `noTrash`, `staleTrash`, `unconfirmed` and `unavailable` are not
- * confirmations at all but refusals: nothing is deleted, and the label names
- * the way out rather than the delete. The first three are answered in place by
- * the appointment prompt — a link to Settings as the only remedy leaves the
- * user to reassemble what they were doing. `unavailable` still routes to
- * re-authentication, because an account read that fails is a session that ended
- * under the reader far more often than it is anything else.
- */
-export const deleteConfirmationCopy = (
-	count: number,
-	outcome: DeleteOutcome,
-	context: DeleteConfirmationContext = {},
-): DeleteConfirmationCopy => {
-	const quantity = count === 1 ? "1" : formatNumber(count);
-	const noun = count === 1 ? "message" : "messages";
-	const { trashFolderLabel, staleFolderLabel } = context;
-
-	if (outcome === "noTrash") {
-		return {
-			title: `Can't delete ${quantity} ${noun} yet`,
-			description:
-				"No folder on this account is set as Trash, so there is nowhere to move the mail. Nothing has been deleted.",
-			confirmLabel: "Pick a Trash folder",
-		};
-	}
-	if (outcome === "staleTrash") {
-		return {
-			title: `Can't delete ${quantity} ${noun} yet`,
-			description: staleFolderLabel
-				? `The folder you set as this account's Trash — ${staleFolderLabel} — is gone from the mail server. Nothing has been deleted.`
-				: "The folder you set as this account's Trash is gone from the mail server. Nothing has been deleted.",
-			confirmLabel: "Pick another folder",
-		};
-	}
-	if (outcome === "unconfirmed") {
-		const folderClause = trashFolderLabel
-			? `reader files this account's deleted mail in ${trashFolderLabel} because of its name — nobody confirmed it.`
-			: "reader files this account's deleted mail in a folder it matched by name — nobody confirmed it.";
-		// count === 0: Empty Trash, acting on everything the folder holds. A
-		// positive count: a delete whose rows already sit in that folder, so
-		// this expunges them specifically, not the folder's whole contents.
-		return {
-			title: "Confirm this account's Trash folder",
-			description:
-				count > 0
-					? `${folderClause} Deleting ${quantity} ${noun} there erases them from the mail server, and that cannot be restored. Nothing has been deleted.`
-					: `${folderClause} Emptying a folder erases everything in it from the mail server, and that cannot be restored. Nothing has been emptied.`,
-			confirmLabel: "Confirm the folder",
-		};
-	}
-	if (outcome === "unavailable") {
-		return {
-			title: `Can't delete ${quantity} ${noun}`,
-			description:
-				"reader couldn't read this account's folder settings, so it can't say whether this would move the mail to Trash or erase it. Nothing has been deleted.",
-			confirmLabel: "Sign in again",
-		};
-	}
-	if (outcome === "unknown") {
-		return {
-			title: `Delete ${quantity} ${noun}?`,
-			description: "Checking where this account files deleted mail…",
-			confirmLabel: "Delete",
-		};
-	}
-	if (outcome === "permanent") {
-		return {
-			title: `Permanently delete ${quantity} ${noun}?`,
-			description:
-				"They are erased from the mail server and cannot be restored.",
-			confirmLabel: "Delete permanently",
-		};
-	}
-	return {
-		title: formatDeleteToTrashTitle(count),
-		description: "You can restore them from Trash later.",
-		confirmLabel: "Move to Trash",
-	};
-};

package/src/lib/fresh-mailbox-count.test.ts

@@ -1,145 +0,0 @@
-/**
- * awaitFreshMailboxCount — the gate a folder delete holds behind while the
- * server is asked what the folder actually holds. It reports a count only from
- * a round that stamped past the baseline, reports `pending` rather than a count
- * when the segment runs out, and refuses outright on a folder the account does
- * not list.
- */
-
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import {
-	awaitFreshMailboxCount,
-	FRESH_COUNT_MISSING_MESSAGE,
-	type MailboxCountReading,
-	mailboxSyncStamp,
-} from "./fresh-mailbox-count.js";
-
-const reading = (
-	messagesTotal: number,
-	lastSyncedAt?: number,
-): MailboxCountReading => ({
-	mailboxId: "mbx-1",
-	messagesTotal,
-	lastSyncedAt,
-});
-
-const noDelay = () => Promise.resolve();
-
-/** A clock that jumps a minute per reading, so a segment expires in two polls. */
-const impatientClock = () => {
-	let clock = 0;
-	return () => {
-		clock += 60_000;
-		return clock;
-	};
-};
-
-describe("mailboxSyncStamp", () => {
-	it("reads the folder's stamp, and zero for a folder never synced", () => {
-		assert.equal(mailboxSyncStamp([reading(0, 100)], "mbx-1"), 100);
-		assert.equal(mailboxSyncStamp([reading(0)], "mbx-1"), 0);
-	});
-
-	it("refuses a folder the account does not list", () => {
-		assert.throws(() => mailboxSyncStamp([], "mbx-1"), {
-			message: FRESH_COUNT_MISSING_MESSAGE,
-		});
-	});
-});
-
-describe("awaitFreshMailboxCount", () => {
-	it("resolves with the count a round stamped past the baseline", async () => {
-		const responses = [[reading(0, 100)], [reading(0, 100)], [reading(3, 200)]];
-		let call = 0;
-		const outcome = await awaitFreshMailboxCount({
-			mailboxId: "mbx-1",
-			since: 100,
-			readMailboxes: async () => responses[call++] as MailboxCountReading[],
-			delay: noDelay,
-		});
-		assert.deepEqual(outcome, { status: "fresh", messageCount: 3 });
-		assert.equal(call, 3);
-	});
-
-	it("never reports a count from a round older than the baseline", async () => {
-		// The stamp stands still — the folder was never re-read, so the zero
-		// sitting in the row is exactly the stale count that must not be trusted.
-		const outcome = await awaitFreshMailboxCount({
-			mailboxId: "mbx-1",
-			since: 100,
-			readMailboxes: async () => [reading(0, 100)],
-			delay: noDelay,
-			now: impatientClock(),
-		});
-		assert.deepEqual(outcome, { status: "pending" });
-	});
-
-	it("resumes against the same baseline and then reports the count", async () => {
-		let stamp = 100;
-		const readMailboxes = async () => [reading(2, stamp)];
-		const first = await awaitFreshMailboxCount({
-			mailboxId: "mbx-1",
-			since: 100,
-			readMailboxes,
-			delay: noDelay,
-			now: impatientClock(),
-		});
-		assert.deepEqual(first, { status: "pending" });
-
-		stamp = 300;
-		const second = await awaitFreshMailboxCount({
-			mailboxId: "mbx-1",
-			since: 100,
-			readMailboxes,
-			delay: noDelay,
-			now: impatientClock(),
-		});
-		assert.deepEqual(second, { status: "fresh", messageCount: 2 });
-	});
-
-	it("refuses a folder the account no longer lists", async () => {
-		await assert.rejects(
-			awaitFreshMailboxCount({
-				mailboxId: "mbx-1",
-				since: 100,
-				readMailboxes: async () => [],
-				delay: noDelay,
-			}),
-			{ message: FRESH_COUNT_MISSING_MESSAGE },
-		);
-	});
-
-	it("propagates a failed read rather than counting it as zero", async () => {
-		await assert.rejects(
-			awaitFreshMailboxCount({
-				mailboxId: "mbx-1",
-				since: 100,
-				readMailboxes: async () => {
-					throw new Error("sync status 500");
-				},
-				delay: noDelay,
-			}),
-			{ message: "sync status 500" },
-		);
-	});
-
-	it("stops on abort and never reports a count", async () => {
-		const controller = new AbortController();
-		let call = 0;
-		controller.abort();
-		await assert.rejects(
-			awaitFreshMailboxCount({
-				mailboxId: "mbx-1",
-				since: 100,
-				readMailboxes: async () => {
-					call += 1;
-					return [reading(0, 200)];
-				},
-				signal: controller.signal,
-				delay: noDelay,
-			}),
-		);
-		assert.equal(call, 0, "an aborted wait reads nothing");
-	});
-});

package/src/lib/fresh-mailbox-count.ts

@@ -1,114 +0,0 @@
-import { abortableDelay } from "./mailbox-sync-wait";
-
-/**
- * How many messages a folder holds *on the mail server*, rather than how many
- * the last sync round left in the local row.
- *
- * Every count the client can read — the mailbox row's `messageCount`, and so
- * the folder list and the sync-status projection over it — is whatever the last
- * round wrote. Mail that arrived since is invisible in it, which is fine for a
- * badge and fatal for a delete: `deleteMailbox` takes the folder's mail with it
- * and IMAP has no undo.
- *
- * So the count is taken from a round asked for on the spot: trigger a sync,
- * then wait for the folder's `lastSyncedAt` to advance past the stamp read
- * before the trigger, and read the count that round wrote alongside it (every
- * message-sync round writes both from the same IMAP STATUS).
- *
- * What the advancing stamp proves is that *some* round's write landed after the
- * baseline read — not necessarily the round this triggered. A round already in
- * flight can land first and satisfy the wait. That is accepted: its STATUS was
- * taken within milliseconds of the baseline, and the error it can carry is a
- * count from a moment too early, which either agrees with the trigger's round
- * or reports mail the folder had and the delete then refuses. The mistake lands
- * on the side of not deleting.
- *
- * Nothing here decides on a count read before the trigger, and every way out
- * other than an advanced stamp throws or reports `pending`: a folder missing
- * from the account, a failed read, an aborted wait. Uncertainty about what a
- * folder holds is never permission to delete it.
- */
-
-/** The read fields the wait needs off a sync-status entry. */
-export interface MailboxCountReading {
-	mailboxId: string;
-	messagesTotal: number;
-	lastSyncedAt?: number;
-}
-
-/** A count from a round that reported after the baseline, or no round yet. */
-export type FreshCountOutcome =
-	| { status: "fresh"; messageCount: number }
-	| { status: "pending" };
-
-export interface AwaitFreshMailboxCountOptions {
-	/** Reads every mailbox's sync-status entry; called once per poll. */
-	readMailboxes: () => Promise<readonly MailboxCountReading[]>;
-	/** The folder to count. */
-	mailboxId: string;
-	/** The folder's `lastSyncedAt` as read before the sync was triggered. */
-	since: number;
-	/** Aborts the wait; a round that lands afterwards resolves nothing. */
-	signal?: AbortSignal;
-	/** How long this stretch of waiting runs before reporting `pending`. */
-	segmentMs?: number;
-	pollIntervalMs?: number;
-	/** Injectable clock/sleep for tests. */
-	delay?: (ms: number, signal?: AbortSignal) => Promise<void>;
-	now?: () => number;
-}
-
-/**
- * How long one stretch of waiting runs before handing the decision back to the
- * user. An explicit sync fans the whole account out on one FIFO group with
- * INBOX first, so a folder on a large account can sit behind minutes of other
- * mailboxes: this is not long enough to conclude anything, only long enough
- * that someone watching a spinner deserves to be asked whether to keep waiting.
- */
-export const FRESH_COUNT_SEGMENT_MS = 120_000;
-export const FRESH_COUNT_POLL_INTERVAL_MS = 2_000;
-
-export const FRESH_COUNT_MISSING_MESSAGE =
-	"This folder is no longer in the account's folder list, so nothing was deleted.";
-
-const entryFor = (
-	mailboxes: readonly MailboxCountReading[],
-	mailboxId: string,
-): MailboxCountReading => {
-	const entry = mailboxes.find((mailbox) => mailbox.mailboxId === mailboxId);
-	if (!entry) throw new Error(FRESH_COUNT_MISSING_MESSAGE);
-	return entry;
-};
-
-/** The folder's last sync stamp, or a refusal when the account does not list it. */
-export const mailboxSyncStamp = (
-	mailboxes: readonly MailboxCountReading[],
-	mailboxId: string,
-): number => entryFor(mailboxes, mailboxId).lastSyncedAt ?? 0;
-
-/**
- * Poll for one segment. Resolves `fresh` with the count once a round reports
- * past `since`, `pending` when the segment runs out with the folder still
- * unreported — the caller asks the user whether to wait on, and calling again
- * with the same `since` resumes without triggering a second round.
- */
-export async function awaitFreshMailboxCount({
-	readMailboxes,
-	mailboxId,
-	since,
-	signal,
-	segmentMs = FRESH_COUNT_SEGMENT_MS,
-	pollIntervalMs = FRESH_COUNT_POLL_INTERVAL_MS,
-	delay = abortableDelay,
-	now = Date.now,
-}: AwaitFreshMailboxCountOptions): Promise<FreshCountOutcome> {
-	const deadline = now() + segmentMs;
-	for (;;) {
-		signal?.throwIfAborted();
-		const entry = entryFor(await readMailboxes(), mailboxId);
-		if ((entry.lastSyncedAt ?? 0) > since)
-			return { status: "fresh", messageCount: entry.messagesTotal };
-		if (now() >= deadline) return { status: "pending" };
-		await delay(pollIntervalMs, signal);
-	}
-}