@remit/web-client 0.0.325 → 0.0.326

package/src/lib/bulk-actions.ts

@@ -1,400 +0,0 @@
-/**
- * Chunked bulk-action orchestration (issues #92, #114).
- *
- * The bulk endpoints cap a call at 100 ids (`BulkMessageInput.messageIds`,
- * `@maxItems(100)`); an action over a search result can run to thousands. These
- * helpers sequence the calls and tally which ids the run actually reached, so a
- * caller can always ask "what's still not done" instead of trusting the request
- * it sent. Delete, move and mark-read all take this path — the action itself is
- * the `ApplyBatch` the caller supplies.
- *
- * The endpoints enqueue the IMAP write and return; they do not apply it. So a
- * returned call means every id in it was accepted, not that the mail server
- * applied it. Delete is the one action that can accept some of a batch and not
- * the rest — a row whose placement changed under it is refused and counted in
- * the response (imap-mutations R3) — and it reports that itself, on the call,
- * rather than here: this layer only ever hands ids back, and an id this run did
- * reach is not one it should re-offer. The only failure it observes is a thrown
- * call: an infrastructure failure (auth, the write, or the enqueue) that takes
- * out the whole batch and stops the run.
- *
- * Cancellation is an `AbortSignal` the caller owns, handed to every call the run
- * makes (#113). Aborting ends the request in flight rather than waiting for it,
- * so at most the batch already on the wire is at stake instead of a whole page;
- * the run then stops before the next request leaves. A rejection raised while
- * the signal is aborted is that abort, so it reports `cancelled` rather than an
- * error — the user asked for it.
- *
- * That classification reads `signal.aborted`, deliberately, and not the shape of
- * the rejection (`isAbortError`): a genuine failure that raced the user's Stop
- * should read as a stop. The user pressed it and the run is over either way, and
- * an error banner for a run they ended themselves is the wrong answer.
- *
- * Pure, framework-agnostic, and independently testable — no React, no fetch.
- * `useEscalatedActions.ts` supplies the real `ApplyBatch`/`FetchIdsPage`
- * implementations (the generated SDK client) and owns the React state.
- */
-
-export const BULK_ACTION_CHUNK_SIZE = 100;
-
-/**
- * What a bulk run applies to every batch it reaches (#114). Delete, move and
- * mark-read differ only in the bulk call they issue and the caches that call
- * invalidates; the paging, chunking, progress and cancellation are the same.
- */
-export type EscalatedAction =
-	| { kind: "delete" }
-	| { kind: "move"; destinationMailboxId: string }
-	| { kind: "markRead" };
-
-/**
- * The mailboxes whose cached listings a bulk run affects: the mailbox it ran
- * over, plus a move's destination, which gains the messages the source loses.
- */
-export const mailboxesTouchedBy = (
-	action: EscalatedAction,
-	mailboxId: string,
-): string[] =>
-	action.kind === "move"
-		? [mailboxId, action.destinationMailboxId]
-		: [mailboxId];
-
-/** For a run with no Stop control to wire a signal to. */
-const NEVER_ABORTED = new AbortController().signal;
-
-/**
- * Resolves a promise to a discriminated result instead of throwing, so a
- * caller can branch on infrastructure failure as a value — the app's
- * try/catch rule requires a rethrow, and there is nothing to rethrow to here;
- * the caller's job on failure is to stop the run and report what happened,
- * not to keep propagating the same rejection past the point it's already
- * been handled.
- */
-const attempt = async <T>(
-	promise: Promise<T>,
-): Promise<{ ok: true; value: T } | { ok: false; error: unknown }> =>
-	promise.then(
-		(value) => ({ ok: true as const, value }),
-		(error) => ({ ok: false as const, error }),
-	);
-
-/** Split `ids` into chunks of at most `size`. Empty input yields no chunks. */
-export const chunkIds = (
-	ids: readonly string[],
-	size = BULK_ACTION_CHUNK_SIZE,
-): string[][] => {
-	if (ids.length === 0) return [];
-	const chunks: string[][] = [];
-	for (let i = 0; i < ids.length; i += size) {
-		chunks.push(ids.slice(i, i + size));
-	}
-	return chunks;
-};
-
-/** One message a run covers, as the surface that selected it knows it. */
-export interface BulkActionTarget {
-	id: string;
-	/**
-	 * Owning IMAP account — the `accountId` of the account API, never the
-	 * caller's `accountConfigId` (#456). Undefined on a row from a per-mailbox
-	 * listing, which does not carry one because every row in it shares the same
-	 * account.
-	 */
-	accountId: string | undefined;
-}
-
-/**
- * Split `targets` into chunks of at most `size` that each carry exactly one
- * account (#872).
- *
- * The bulk endpoints reject a batch spanning accounts outright, before applying
- * any of it, and the daily brief and Flagged are both cross-account lists — so
- * a selection ticked across two accounts sent as one batch deleted nothing.
- * Account is a property of the batch, not of the verb: delete and mark-read
- * cover whatever was ticked, and this is where that becomes one call per
- * account.
- *
- * Targets with no account form a group of their own, which keeps the id in the
- * run rather than dropping a message the user asked to be acted on. A surface
- * that carries no account is single-account by construction; one that carries
- * it for some rows and not others sends the unattributed ones together, and if
- * the server refuses that batch the run reports it like any other failure.
- *
- * Accounts and ids keep the order they were selected in.
- */
-export const chunkTargets = (
-	targets: readonly BulkActionTarget[],
-	size = BULK_ACTION_CHUNK_SIZE,
-): string[][] => {
-	const byAccount = new Map<string | undefined, string[]>();
-	for (const target of targets) {
-		const held = byAccount.get(target.accountId);
-		if (held) {
-			held.push(target.id);
-			continue;
-		}
-		byAccount.set(target.accountId, [target.id]);
-	}
-	return [...byAccount.values()].flatMap((ids) => chunkIds(ids, size));
-};
-
-export interface BatchResult {
-	successCount: number;
-	failureCount: number;
-}
-
-/** Applies the action to one batch of ids (≤100) with a single bulk call. */
-export type ApplyBatch = (
-	ids: string[],
-	signal: AbortSignal,
-) => Promise<BatchResult>;
-
-export interface BulkActionProgress {
-	/** Ids the action has been applied to so far. */
-	done: number;
-	/** The total the run was started against (may be an estimate for the
-	 *  predicate case — see `runPredicateAction`). */
-	total: number;
-}
-
-export interface BulkActionOutcome {
-	/** Ids the action was applied to (server-accepted, not merely "sent"). */
-	done: number;
-	/**
-	 * Ids the run did not reach, so the action was never applied to them: on
-	 * cancellation or a thrown error, the chunks the bounded run never attempted
-	 * (see `runChunkedAction`). Empty in the predicate case, which re-resolves on
-	 * every run rather than handing back a remainder (see `runPredicateAction`).
-	 * An aborted batch is counted here too: aborting the request does not
-	 * un-send what the server already accepted, so its ids are "may not have
-	 * landed" rather than "did not", and every action here is idempotent.
-	 * A returned batch call counts every id in it as reached. Delete's own
-	 * per-row refusals ride its response and are surfaced by the caller, not
-	 * folded in here (see the module header).
-	 */
-	failedIds: string[];
-	/**
-	 * Rows the server reached and refused: their placement changed under the
-	 * run, so the action never claimed them (imap-mutations R3). Summed across
-	 * every chunk so the caller states it once for the whole run rather than
-	 * once per hundred ids. Not folded into `failedIds` — those were never
-	 * reached, and these were.
-	 */
-	refused: number;
-	cancelled: boolean;
-	/** Set when a batch call threw — an infrastructure failure, not a
-	 *  per-item failure. The run stops at the point it was raised. */
-	error?: unknown;
-}
-
-/**
- * Bounded case: the full id list is known upfront (a materialized selection,
- * or a "select all loaded" that grew past 100 rows). Chunked synchronously, so
- * on cancellation or a thrown error every chunk not yet attempted — including
- * the one in flight when an error was thrown — is folded into `failedIds`. The
- * caller always gets back exactly the ids the action never reached, ready to
- * retry as-is: every action here is idempotent (re-trashing, re-moving or
- * re-marking a message it already applied to is a no-op).
- *
- * Chunks never mix accounts (see `chunkTargets`), and the run walks them as one
- * sequence: cancellation lands at whichever boundary comes next, whether or not
- * that is an account boundary, and progress counts toward the whole selection
- * rather than restarting per account.
- */
-export const runChunkedAction = async (
-	targets: readonly BulkActionTarget[],
-	applyBatch: ApplyBatch,
-	onProgress: (progress: BulkActionProgress) => void,
-	signal: AbortSignal,
-): Promise<BulkActionOutcome> => {
-	const chunks = chunkTargets(targets);
-	const total = targets.length;
-	let done = 0;
-	let refused = 0;
-	const failedIds: string[] = [];
-
-	for (let i = 0; i < chunks.length; i++) {
-		if (signal.aborted) {
-			failedIds.push(...chunks.slice(i).flat());
-			return { done, failedIds, refused, cancelled: true };
-		}
-		const chunk = chunks[i];
-		const attempted = await attempt(applyBatch(chunk, signal));
-		if (!attempted.ok) {
-			failedIds.push(...chunks.slice(i).flat());
-			if (signal.aborted) return { done, failedIds, refused, cancelled: true };
-			onProgress({ done, total });
-			return {
-				done,
-				failedIds,
-				refused,
-				cancelled: false,
-				error: attempted.error,
-			};
-		}
-		refused += attempted.value?.failureCount ?? 0;
-		done += chunk.length;
-		onProgress({ done, total });
-	}
-
-	return { done, failedIds, refused, cancelled: false };
-};
-
-/**
- * The same bounded run, adapted to the optimistic mutation hooks (#453).
- *
- * A selection is not always assembled by a surface that owns a progress bar —
- * the daily brief's toolbar and sheet hand a raw id list to `useDeleteMessages`,
- * `useMoveMessages`, `useToggleReadFor` and `useApplyLabel`, and select-all over
- * a 200-row search would send all 200 in one call, which the endpoint rejects
- * outright. Splitting the send inside those hooks puts the cap where the call is
- * made, so every caller is covered by construction rather than by remembering.
- *
- * Each chunk is a full mutation of its own, so it keeps that hook's optimistic
- * patch, rollback and error banner. The run stops at the first rejected chunk
- * and reports nothing itself: the hook that owns the call has already raised it.
- *
- * Every call site on this path hands over ids from a single account — a
- * focused row, or a selection the surface already scoped — so nothing here
- * carries an account to split by. A caller with a cross-account selection
- * belongs on `runChunkedAction`, whose targets name one (#872).
- *
- * These callers have no Stop control to wire a signal to — a mutation over a
- * handful of ids has no progress surface to stop from — so the run is handed a
- * signal that never aborts.
- */
-export const runChunkedMutation = async (
-	ids: readonly string[],
-	send: (chunk: string[]) => Promise<unknown>,
-): Promise<void> => {
-	await runChunkedAction(
-		ids.map((id) => ({ id, accountId: undefined })),
-		async (chunk) => {
-			await send(chunk);
-			return { successCount: chunk.length, failureCount: 0 };
-		},
-		() => {},
-		NEVER_ABORTED,
-	);
-};
-
-export interface FetchIdsPageResult {
-	ids: string[];
-	continuationToken?: string;
-}
-
-/** Fetches one page of matching message ids for the active predicate. */
-export type FetchIdsPage = (
-	continuationToken: string | undefined,
-	signal: AbortSignal,
-) => Promise<FetchIdsPageResult>;
-
-/**
- * Escalated case: the selection is a predicate (D2), not a materialized list.
- * Each page is fetched immediately before the chunk it feeds is acted on — a
- * page IS a chunk, sized to the same 100-id cap the write side enforces — so
- * ids are never held in memory beyond the batch in flight.
- *
- * Cancelling or a thrown error simply stops paging: nothing is added to
- * `failedIds` for the unreached remainder, because those ids were never
- * fetched — there is nothing to hand back. A predicate resolves fresh on
- * every run (D2), so resuming is re-invoking this same function with the same
- * predicate. Aborting also ends the page or batch on the wire, so the run gives
- * up at most the one request rather than the whole page it was mid-way through.
- */
-export const runPredicateAction = async (
-	fetchIdsPage: FetchIdsPage,
-	total: number,
-	applyBatch: ApplyBatch,
-	onProgress: (progress: BulkActionProgress) => void,
-	signal: AbortSignal,
-): Promise<BulkActionOutcome> => {
-	let done = 0;
-	let refused = 0;
-	const failedIds: string[] = [];
-	let token: string | undefined;
-
-	do {
-		if (signal.aborted) {
-			return { done, failedIds, refused, cancelled: true };
-		}
-
-		const fetched = await attempt(fetchIdsPage(token, signal));
-		if (!fetched.ok) {
-			if (signal.aborted) return { done, failedIds, refused, cancelled: true };
-			return {
-				done,
-				failedIds,
-				refused,
-				cancelled: false,
-				error: fetched.error,
-			};
-		}
-		const page = fetched.value;
-
-		if (page.ids.length > 0) {
-			const attempted = await attempt(applyBatch(page.ids, signal));
-			if (!attempted.ok) {
-				if (signal.aborted)
-					return { done, failedIds, refused, cancelled: true };
-				return {
-					done,
-					failedIds,
-					refused,
-					cancelled: false,
-					error: attempted.error,
-				};
-			}
-			refused += attempted.value?.failureCount ?? 0;
-			done += page.ids.length;
-			onProgress({ done, total });
-		}
-
-		token = page.continuationToken;
-	} while (token);
-
-	return { done, failedIds, refused, cancelled: false };
-};
-
-/**
- * Corrects a progress reading so its `total` can never read as less than
- * `done` (#109). `runPredicateAction`'s `total` is the count the server gave
- * before the run resolved the same predicate a second, independent time; if
- * more matches arrived in between, `done` can overtake it mid-run and a raw
- * "Deleting 1,340 of 1,284" would follow. Widening the denominator to match
- * keeps the bar's ratio sane (never past 100%) without claiming the original
- * count was exact — the honest fix is admitting the reading grew, not taking a
- * second count to reconcile it (the result set is live; a count taken any
- * later is no less stale than the first).
- */
-export const honestProgress = (
-	progress: BulkActionProgress,
-): BulkActionProgress => ({
-	done: progress.done,
-	total: Math.max(progress.total, progress.done),
-});
-
-export interface BulkRunOutcome {
-	done: number;
-	failedIds: string[];
-	/**
-	 * Rows the server reached and refused: their placement changed under the
-	 * run, so the action never claimed them (imap-mutations R3). Summed across
-	 * every chunk so the caller states it once for the whole run rather than
-	 * once per hundred ids. Not folded into `failedIds` — those were never
-	 * reached, and these were.
-	 */
-	refused: number;
-	cancelled: boolean;
-	error?: unknown;
-}
-
-/**
- * What asking for a run got: the run itself, or the reason there is none. One
- * run at a time is the design — a second one would page a second predicate
- * behind the same bar and the same Stop — so a commit pressed while one is
- * going is answered with what is going rather than with a run that replaces it.
- */
-export type BulkRunStart =
-	| { kind: "ran"; outcome: BulkRunOutcome }
-	| { kind: "refused"; reason: string };

package/src/lib/calendar-collection-copy.test.ts

@@ -1,23 +0,0 @@
-import assert from "node:assert";
-import { describe, test } from "node:test";
-import { calendarUrlSegmentFor } from "./calendar-collection-copy.js";
-
-describe("calendarUrlSegmentFor", () => {
-	test("folds a name into a path segment", () => {
-		assert.strictEqual(
-			calendarUrlSegmentFor("Harbour Projects"),
-			"harbour-projects",
-		);
-	});
-
-	test("drops accents and punctuation at either end", () => {
-		assert.strictEqual(
-			calendarUrlSegmentFor("  Café & Crèche!  "),
-			"cafe-creche",
-		);
-	});
-
-	test("stays within the 64 characters the API accepts", () => {
-		assert.strictEqual(calendarUrlSegmentFor("a".repeat(80)).length, 64);
-	});
-});

package/src/lib/calendar-collection-copy.ts

@@ -1,21 +0,0 @@
-export interface CollectionConfirmCopy {
-	title: string;
-	description: string;
-}
-
-export const deleteCalendarConfirmCopy = (
-	calendarName: string,
-): CollectionConfirmCopy => ({
-	title: `Delete ${calendarName}?`,
-	description: `This removes ${calendarName} and every event in it, and any subscription address stops working. It cannot be undone.`,
-});
-
-/** A starting address for a new calendar, from the name typed so far. */
-export const calendarUrlSegmentFor = (displayName: string): string =>
-	displayName
-		.normalize("NFKD")
-		.replace(/[̀-ͯ]/g, "")
-		.toLowerCase()
-		.replace(/[^a-z0-9]+/g, "-")
-		.replace(/^-+|-+$/g, "")
-		.slice(0, 64);

package/src/lib/calendar-density.ts

@@ -1,46 +0,0 @@
-/**
- * How much of a day this device shows at once.
- *
- * A phone on a train and a monitor on a desk want different amounts of the
- * same week, and the answer belongs to the screen rather than to the calendar:
- * it is not a fact about the view, so it is in no tier of the address, and a
- * link shared from one device must not resize the day on another. Stored the
- * way the intelligence rail's preference is (`lib/intelligence-pref.ts`), and
- * a storage failure falls back to the default rather than crashing.
- */
-import type { AgendaDensity, Density } from "@remit/ui";
-
-export const CALENDAR_DENSITY_KEY = "remit:calendar-density";
-
-/** Roomy enough to read a title at a glance, which is the common case. */
-export const DEFAULT_CALENDAR_DENSITY: Density = "comfortable";
-
-export function readCalendarDensity(): Density {
-	try {
-		return localStorage.getItem(CALENDAR_DENSITY_KEY) === "compact"
-			? "compact"
-			: DEFAULT_CALENDAR_DENSITY;
-	} catch {
-		return DEFAULT_CALENDAR_DENSITY;
-	}
-}
-
-export function writeCalendarDensity(density: Density): void {
-	try {
-		localStorage.setItem(CALENDAR_DENSITY_KEY, density);
-	} catch {
-		// Storage unavailable — the in-memory default stands.
-	}
-}
-
-/**
- * The same preference, as the strip reads it.
- *
- * The strip has three readings and the preference has two, so the third — a
- * month of coloured dots with no titles on it — is not reachable from Glance.
- * That is deliberate: the preference says how much of a day this screen shows,
- * not whether to say what is on it, and one calendar-wide answer beats a second
- * control that means something different at every zoom.
- */
-export const agendaDensityOf = (density: Density): AgendaDensity =>
-	density === "compact" ? "pills" : "detail";

package/src/lib/calendar-feed-copy.ts

@@ -1,29 +0,0 @@
-/**
- * What the two destructive feed actions say before they are taken.
- *
- * Both take a working subscription away from whoever holds the address, and
- * neither can be undone by re-minting — the new address is a different secret.
- * The copy names the calendar, so a confirmation opened from the wrong row is
- * visibly the wrong one.
- */
-
-export interface FeedConfirmCopy {
-	title: string;
-	description: string;
-}
-
-export const rotateFeedConfirmCopy = (
-	calendarName: string,
-): FeedConfirmCopy => ({
-	title: `Replace the address for ${calendarName}?`,
-	description:
-		"Every client already subscribed to the current address stops updating and has to be pointed at the new one. The new address is shown once.",
-});
-
-export const revokeFeedConfirmCopy = (
-	calendarName: string,
-): FeedConfirmCopy => ({
-	title: `Stop sharing ${calendarName}?`,
-	description:
-		"The address stops working immediately and every client subscribed to it stops updating. Sharing again mints a different address.",
-});

package/src/lib/calendar-feed-url.ts

@@ -1,14 +0,0 @@
-/**
- * The address a subscriber points its calendar client at (issue #1067).
- *
- * `webcal://` rather than `https://`: Apple Calendar, Outlook and Thunderbird
- * hand a `webcal:` link straight to their subscription dialog, where an https
- * one downloads a file that never refreshes. The host carries its port, so a
- * deployment that is not on 443 is subscribable on the same terms.
- */
-
-const FEED_PATH_PREFIX = "/feeds/calendar/";
-const FEED_PATH_SUFFIX = ".ics";
-
-export const calendarFeedUrl = (host: string, feedToken: string): string =>
-	`webcal://${host}${FEED_PATH_PREFIX}${feedToken}${FEED_PATH_SUFFIX}`;

package/src/lib/calendar-format.ts

@@ -1,74 +0,0 @@
-/**
- * The words a calendar surface puts a time in. Every component in `@remit/ui`
- * takes its text already formatted and owns no clock, so the formatting lives
- * on this side of the seam.
- */
-import type { CalendarEventData } from "@remit/ui";
-
-const DAY = new Intl.DateTimeFormat(undefined, {
-	weekday: "short",
-	day: "numeric",
-	month: "long",
-});
-
-const CLOCK = new Intl.DateTimeFormat(undefined, {
-	hour: "2-digit",
-	minute: "2-digit",
-	hour12: false,
-});
-
-const LONG_DAY = new Intl.DateTimeFormat(undefined, {
-	weekday: "long",
-	day: "numeric",
-	month: "long",
-	timeZone: "UTC",
-});
-
-const CIVIL_DAY = new Intl.DateTimeFormat(undefined, {
-	weekday: "short",
-	day: "numeric",
-	month: "long",
-	timeZone: "UTC",
-});
-
-/**
- * "Wed 10 March", for a civil date `YYYY-MM-DD`. A date with no hours is the
- * same day wherever the reader is, so it is never read as an instant.
- */
-export function formatCivilDay(date: string): string {
-	return CIVIL_DAY.format(new Date(`${date}T00:00:00Z`));
-}
-
-/** A span as the kit is handed it: when it starts, when it ends, whether it has hours. */
-export type CalendarSpan = Pick<CalendarEventData, "start" | "end" | "allDay">;
-
-/**
- * "Wed 10 June, 10:00 – 11:00", or the day alone when it runs all of it. An
- * all-day span is read off its civil date: parsed as an instant, it lands on
- * the day before anywhere west of UTC.
- */
-export function formatEventWhen(event: CalendarSpan): string {
-	if (event.allDay)
-		return `${formatCivilDay(event.start.slice(0, 10))}, all day`;
-	const start = new Date(event.start);
-	const end = new Date(event.end);
-	const day = DAY.format(start);
-	const sameDay = DAY.format(end) === day;
-	if (sameDay) return `${day}, ${CLOCK.format(start)} – ${CLOCK.format(end)}`;
-	return `${day}, ${CLOCK.format(start)} – ${DAY.format(end)}, ${CLOCK.format(end)}`;
-}
-
-/** "Thursday 11 June", for a civil date `YYYY-MM-DD` read on no clock at all. */
-export function formatDayLabel(date: string): string {
-	return LONG_DAY.format(new Date(`${date}T00:00:00Z`));
-}
-
-/** "10:00", for a clock time `HH:MM` already on the right clock. */
-export function formatClock(time: string): string {
-	return CLOCK.format(new Date(`1970-01-01T${time}:00`));
-}
-
-/** "10:00", for an instant, on this device's clock. */
-export function formatInstantClock(iso: string): string {
-	return CLOCK.format(new Date(iso));
-}

package/src/lib/calendar-report.ts

@@ -1,21 +0,0 @@
-import { buildBugReportContext, buildGitHubIssueUrl } from "./bug-report";
-
-/** A prefilled issue for an invitation answer or read that did not land. */
-export function calendarReportHref(what: string): string {
-	return buildGitHubIssueUrl(
-		buildBugReportContext({
-			title: `Calendar invitation: ${what}`,
-			errorMessage: what,
-		}),
-	);
-}
-
-/** A prefilled issue for an event the calendar could not look up. */
-export function calendarEventReportHref(what: string): string {
-	return buildGitHubIssueUrl(
-		buildBugReportContext({
-			title: `Calendar event: ${what}`,
-			errorMessage: what,
-		}),
-	);
-}