@remit/web-client 0.0.229 → 0.0.230

package/src/components/onboarding/credential-steps.tsx

@@ -0,0 +1,441 @@
+/**
+ * The two steps that turn a mailbox address into a working connection: enter a
+ * credential, then prove it against the server.
+ *
+ * They are shared rather than copied because two flows reach them. Onboarding
+ * arrives with server settings the user just confirmed; a config import arrives
+ * with server settings the file carried and a credential it deliberately did
+ * not, and both then need the same answer from the same test endpoint. The rail
+ * labels differ between the two, so they are props.
+ */
+
+import { accountOperationsTestConnectionMutation } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import {
+	AppPasswordHint,
+	Banner,
+	Button,
+	CheckRow,
+	FieldLabel,
+	Input,
+	PasswordInput,
+	securityToApi,
+	WizardShell,
+} from "@remit/ui";
+import { useMutation } from "@tanstack/react-query";
+import { useCallback, useEffect, useState } from "react";
+import {
+	getAppPasswordUrl,
+	type SecurityMode,
+} from "../../lib/autodiscovery.js";
+
+export interface ServerConfig {
+	host: string;
+	port: number;
+	security: SecurityMode;
+}
+
+export type TestPhase =
+	| "idle"
+	| "running"
+	| "success"
+	| "auth-failure"
+	| "network-failure";
+
+interface TestResult {
+	imapState: "pending" | "running" | "ok" | "failed";
+	smtpState: "pending" | "running" | "ok" | "failed";
+	imapDetail?: string;
+	smtpDetail?: string;
+	rawError?: string;
+	phase: TestPhase;
+}
+
+export interface CredentialsStepProps {
+	steps: string[];
+	activeStep: number;
+	title: string;
+	subtitle: string;
+	email: string;
+	username: string;
+	password: string;
+	/** Shown above the fields — the import flow says where the servers came from. */
+	notice?: React.ReactNode;
+	/** A refusal from the last attempt, in the server's own words. */
+	error?: string;
+	continueLabel?: string;
+	backLabel?: string;
+	onContinue: () => void;
+	onBack: () => void;
+	onChange: (username: string, password: string) => void;
+}
+
+export function CredentialsStep({
+	steps,
+	activeStep,
+	title,
+	subtitle,
+	email,
+	username,
+	password,
+	notice,
+	error,
+	continueLabel = "Test connection",
+	backLabel = "Back",
+	onContinue,
+	onBack,
+	onChange,
+}: CredentialsStepProps) {
+	const [localUsername, setLocalUsername] = useState(username || email);
+	const [localPassword, setLocalPassword] = useState(password);
+	const [validationError, setValidationError] = useState<string | null>(null);
+
+	const appPasswordUrl = getAppPasswordUrl(email);
+	const isValid = localUsername.trim() !== "" && localPassword.trim() !== "";
+
+	useEffect(() => {
+		onChange(localUsername, localPassword);
+	}, [localUsername, localPassword, onChange]);
+
+	const handleContinue = useCallback(() => {
+		if (!isValid) {
+			setValidationError("Enter your username and password.");
+			return;
+		}
+		setValidationError(null);
+		onContinue();
+	}, [isValid, onContinue]);
+
+	// Keyboard: Enter advances, Esc goes back
+	useEffect(() => {
+		const handler = (e: KeyboardEvent) => {
+			if (e.key === "Enter") handleContinue();
+			if (e.key === "Escape") onBack();
+		};
+		window.addEventListener("keydown", handler);
+		return () => window.removeEventListener("keydown", handler);
+	}, [handleContinue, onBack]);
+
+	return (
+		<WizardShell
+			steps={steps}
+			activeStep={activeStep}
+			title={title}
+			subtitle={subtitle}
+			footer={
+				<>
+					<Button variant="ghost" onClick={onBack}>
+						{backLabel}
+					</Button>
+					<Button variant="primary" onClick={handleContinue}>
+						{continueLabel}
+					</Button>
+				</>
+			}
+		>
+			<div className="space-y-3">
+				{error && <Banner tone="danger">{error}</Banner>}
+				{validationError && (
+					<div className="rounded-md bg-danger-soft px-3 py-2 text-sm text-danger">
+						{validationError}
+					</div>
+				)}
+				{notice}
+				<div>
+					<FieldLabel htmlFor="credentials-username">Username</FieldLabel>
+					<Input
+						id="credentials-username"
+						value={localUsername}
+						onChange={(e) => {
+							setLocalUsername(e.target.value);
+							setValidationError(null);
+						}}
+						autoComplete="username"
+					/>
+				</div>
+				<div>
+					<FieldLabel htmlFor="credentials-password">
+						Password or app password
+					</FieldLabel>
+					<PasswordInput
+						id="credentials-password"
+						value={localPassword}
+						onChange={(e) => {
+							setLocalPassword(e.target.value);
+							setValidationError(null);
+						}}
+						autoComplete="current-password"
+					/>
+				</div>
+				<AppPasswordHint url={appPasswordUrl} />
+			</div>
+		</WizardShell>
+	);
+}
+
+export interface ConnectionTestStepProps {
+	steps: string[];
+	activeStep: number;
+	email: string;
+	imapConfig: ServerConfig;
+	smtpConfig: ServerConfig;
+	username: string;
+	password: string;
+	/** Where Back goes when the server refused the credential. */
+	onBackToCredentials: () => void;
+	/**
+	 * Where Back goes when the server could not be reached at all. Onboarding
+	 * sends it to the servers step; an import has no such step and sends it back
+	 * to the credential, where the account's own settings are editable.
+	 */
+	onBackToServers: () => void;
+	credentialsBackLabel?: string;
+	serversBackLabel?: string;
+	successLabel?: string;
+	onSuccess: () => void;
+}
+
+export function ConnectionTestStep({
+	steps,
+	activeStep,
+	email,
+	imapConfig,
+	smtpConfig,
+	username,
+	password,
+	onSuccess,
+	onBackToCredentials,
+	onBackToServers,
+	credentialsBackLabel = "Back to credentials",
+	serversBackLabel = "Back to servers",
+	successLabel = "Start syncing",
+}: ConnectionTestStepProps) {
+	const [testResult, setTestResult] = useState<TestResult>({
+		imapState: "running",
+		smtpState: "pending",
+		phase: "running",
+	});
+	const [attempt, setAttempt] = useState(0);
+	const smtpConfigured = smtpConfig.host.trim() !== "";
+	const imapTls = securityToApi(imapConfig.security);
+	const smtpTls = securityToApi(smtpConfig.security);
+
+	const testMutation = useMutation({
+		...accountOperationsTestConnectionMutation(),
+	});
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: runs on mount and each Retry via `attempt`; the connection inputs are read intentionally and must not re-trigger the test on every render
+	useEffect(() => {
+		let cancelled = false;
+		const timers: number[] = [];
+
+		setTestResult({
+			imapState: "running",
+			smtpState: "pending",
+			phase: "running",
+		});
+
+		testMutation.mutate(
+			{
+				body: {
+					username,
+					password,
+					imapHost: imapConfig.host,
+					imapPort: imapConfig.port,
+					imapTls: imapTls.tls,
+					imapStartTls: imapTls.startTls,
+					smtpHost: smtpConfig.host,
+					smtpPort: smtpConfig.port,
+					smtpTls: smtpTls.tls,
+					smtpStartTls: smtpTls.startTls,
+				},
+			},
+			{
+				onSuccess: (data) => {
+					if (cancelled) return;
+					// Show IMAP result first, then SMTP. SMTP is optional: when no
+					// host was given the account is receive-only, so IMAP alone
+					// decides success.
+					const imapOk = data.imapSuccess;
+					const smtpOk = smtpConfigured ? data.smtpSuccess : true;
+
+					setTestResult({
+						imapState: imapOk ? "ok" : "failed",
+						smtpState: smtpConfigured ? "running" : "ok",
+						imapDetail: imapOk
+							? `Connected — ${imapConfig.host}:${imapConfig.port}`
+							: data.imapError,
+						phase: "running",
+					});
+
+					timers.push(
+						window.setTimeout(() => {
+							if (cancelled) return;
+							// An auth error can come from either protocol; route on the
+							// one that actually failed. IMAP failures take precedence in
+							// the raw-error display since IMAP is tested first.
+							const isAuthError = (msg: string | undefined): boolean => {
+								const m = msg?.toLowerCase() ?? "";
+								return (
+									m.includes("auth") ||
+									m.includes("login") ||
+									m.includes("535") ||
+									m.includes("credential")
+								);
+							};
+							const isAuthFailure =
+								(!imapOk && isAuthError(data.imapError)) ||
+								(imapOk &&
+									smtpConfigured &&
+									!data.smtpSuccess &&
+									isAuthError(data.smtpError));
+
+							setTestResult({
+								imapState: imapOk ? "ok" : "failed",
+								smtpState: !smtpConfigured
+									? "ok"
+									: data.smtpSuccess
+										? "ok"
+										: "failed",
+								imapDetail: imapOk
+									? `Connected — ${imapConfig.host}:${imapConfig.port}`
+									: data.imapError,
+								smtpDetail: !smtpConfigured
+									? "Not set up — receive-only"
+									: data.smtpSuccess
+										? `Connected — ${smtpConfig.host}:${smtpConfig.port}`
+										: data.smtpError,
+								rawError: !imapOk
+									? data.imapError
+									: smtpConfigured && !data.smtpSuccess
+										? data.smtpError
+										: undefined,
+								phase:
+									imapOk && smtpOk
+										? "success"
+										: isAuthFailure
+											? "auth-failure"
+											: "network-failure",
+							});
+
+							if (imapOk && smtpOk) {
+								timers.push(
+									window.setTimeout(() => {
+										if (!cancelled) onSuccess();
+									}, 800),
+								);
+							}
+						}, 400),
+					);
+				},
+				onError: (err) => {
+					if (cancelled) return;
+					const msg = err instanceof Error ? err.message : "Connection failed";
+					setTestResult({
+						imapState: "failed",
+						smtpState: "failed",
+						imapDetail: msg,
+						smtpDetail: msg,
+						rawError: msg,
+						phase: "network-failure",
+					});
+				},
+			},
+		);
+
+		return () => {
+			cancelled = true;
+			for (const t of timers) window.clearTimeout(t);
+		};
+	}, [attempt]);
+
+	const { phase } = testResult;
+
+	// Keyboard: Esc goes back based on failure type
+	useEffect(() => {
+		const handler = (e: KeyboardEvent) => {
+			if (e.key === "Escape") {
+				if (phase === "auth-failure") onBackToCredentials();
+				else if (phase === "network-failure") onBackToServers();
+			}
+		};
+		window.addEventListener("keydown", handler);
+		return () => window.removeEventListener("keydown", handler);
+	}, [phase, onBackToCredentials, onBackToServers]);
+
+	const footer =
+		phase === "auth-failure" ? (
+			<>
+				<Button variant="ghost" onClick={onBackToCredentials}>
+					{credentialsBackLabel}
+				</Button>
+				<Button variant="primary" onClick={() => setAttempt((a) => a + 1)}>
+					Retry
+				</Button>
+			</>
+		) : phase === "network-failure" ? (
+			<>
+				<Button variant="ghost" onClick={onBackToServers}>
+					{serversBackLabel}
+				</Button>
+				<Button variant="primary" onClick={() => setAttempt((a) => a + 1)}>
+					Retry
+				</Button>
+			</>
+		) : phase === "success" ? (
+			<>
+				<span className="text-2xs text-fg-subtle">Connection verified</span>
+				<Button variant="primary" onClick={onSuccess}>
+					{successLabel}
+				</Button>
+			</>
+		) : (
+			<>
+				<span className="text-2xs text-fg-subtle">Testing…</span>
+				<span />
+			</>
+		);
+
+	return (
+		<WizardShell
+			steps={steps}
+			activeStep={activeStep}
+			title="Testing the connection"
+			subtitle={`Checking ${email}`}
+			footer={footer}
+		>
+			<div className="divide-y divide-line">
+				<CheckRow
+					label={`IMAP — ${imapConfig.host}:${imapConfig.port}`}
+					detail={testResult.imapDetail}
+					state={testResult.imapState}
+				/>
+				<CheckRow
+					label={
+						smtpConfigured
+							? `SMTP — ${smtpConfig.host}:${smtpConfig.port}`
+							: "SMTP — sending"
+					}
+					detail={
+						smtpConfigured
+							? testResult.smtpDetail
+							: "Not set up — you can add sending later in Settings"
+					}
+					state={testResult.smtpState}
+				/>
+				{(phase === "auth-failure" || phase === "network-failure") &&
+					testResult.rawError && (
+						<div className="py-3">
+							{phase === "auth-failure" && (
+								<p className="mb-2 text-xs text-fg-muted">
+									Check your password — many providers require an app password.
+								</p>
+							)}
+							<code className="block rounded bg-surface-sunken px-2.5 py-2 text-2xs text-fg-muted">
+								{testResult.rawError}
+							</code>
+						</div>
+					)}
+			</div>
+		</WizardShell>
+	);
+}

package/src/components/settings/ConfigExportCard.tsx

@@ -0,0 +1,114 @@
+/**
+ * Settings › Advanced: the two halves of moving a configuration between
+ * instances (#1021). Export writes the file this instance is set up with;
+ * import reads one back in through the wizard.
+ *
+ * A failed export says so where the button is. A dead download control is the
+ * worse outcome: the reader cannot tell whether it saved, whether it is broken,
+ * or whether they missed something.
+ */
+
+import {
+	Badge,
+	Button,
+	Card,
+	CardBody,
+	CardHeader,
+	CardTitle,
+} from "@remit/ui";
+import { Download, FileJson, Loader2 } from "lucide-react";
+
+export interface ConfigExportCardProps {
+	fileName: string;
+	state?: "ready" | "downloading" | "failed";
+	/** The server's own words, kept for a bug report. */
+	error?: string;
+	onDownload?: () => void;
+	onImport?: () => void;
+}
+
+export function ConfigExportCard({
+	fileName,
+	state = "ready",
+	error,
+	onDownload,
+	onImport,
+}: ConfigExportCardProps) {
+	const downloading = state === "downloading";
+	return (
+		<Card className="max-w-xl">
+			<CardHeader>
+				<CardTitle>Configuration file</CardTitle>
+			</CardHeader>
+			<CardBody>
+				<p className="text-sm text-fg-muted">
+					One versioned JSON document carrying every setting this instance
+					holds: accounts and their servers, folder roles, rules, labels,
+					flagged senders and appearance. No passwords and no OAuth tokens — you
+					sign in again wherever you import it.
+				</p>
+				{state === "failed" && (
+					<div className="mt-3 space-y-2 rounded-sm border border-danger/40 bg-danger-soft px-3 py-2.5">
+						<p className="text-sm font-medium text-danger">
+							The config file could not be written.
+						</p>
+						<p className="text-xs text-fg-muted">
+							Nothing was downloaded. Try again — if it keeps failing, use{" "}
+							<code className="rounded bg-surface-sunken px-1 py-0.5">
+								remit config save
+							</code>{" "}
+							on the host in the meantime.
+						</p>
+						{error && (
+							<code className="block rounded bg-surface-sunken px-2.5 py-2 text-2xs text-fg-muted">
+								{error}
+							</code>
+						)}
+					</div>
+				)}
+				<div className="mt-3 flex flex-wrap items-center gap-2">
+					<Button
+						variant="secondary"
+						size="sm"
+						disabled={downloading}
+						icon={
+							downloading ? (
+								<Loader2 className="size-3.5 animate-spin" />
+							) : (
+								<Download className="size-3.5" />
+							)
+						}
+						onClick={onDownload}
+					>
+						{downloading ? "Preparing…" : `Download ${fileName}`}
+					</Button>
+					<Badge tone="neutral">no passwords</Badge>
+				</div>
+				<p className="mt-3 text-2xs text-fg-subtle">
+					On the host, the same file comes from{" "}
+					<code className="rounded bg-surface-sunken px-1 py-0.5">
+						remit config save ~/{fileName}
+					</code>
+					.
+				</p>
+				<div className="mt-5 border-t border-line pt-4">
+					<p className="text-sm font-medium text-fg">Import a config file</p>
+					<p className="mt-1 text-sm text-fg-muted">
+						Read a file from another Reader into this one. It shows what will
+						change before anything is written, and asks for each account's
+						credentials afterwards.
+					</p>
+					<Button
+						className="mt-3"
+						variant="secondary"
+						size="sm"
+						icon={<FileJson className="size-3.5" />}
+						onClick={onImport}
+					>
+						Import a config file
+					</Button>
+				</div>
+			</CardBody>
+		</Card>
+	);
+}

package/src/components/settings/ConfigTransferPanel.tsx

@@ -0,0 +1,72 @@
+/**
+ * The export card wired to the endpoint behind it.
+ *
+ * The download is minted in the browser from the export response rather than
+ * linked, because the route is bearer-authenticated and a plain link carries no
+ * token. `fetchQuery` rather than a mounted query: reading a whole
+ * configuration is what pressing the button asks for, not what opening the
+ * screen does.
+ *
+ * The read carries no `softError` meta on purpose. `GET /config/export` declares
+ * no refusal, so its failures are a 5xx — which must reach the fatal page rather
+ * than a card, and never be softened client-side — or a transport failure, which
+ * does not escalate and is exactly what the card's failed state renders.
+ */
+
+import { configOperationsExportConfigOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQueryClient } from "@tanstack/react-query";
+import { useState } from "react";
+import { exportFileName } from "@/lib/config-import";
+import { useGoToSection } from "@/routing";
+import { ConfigExportCard } from "./ConfigExportCard";
+
+const saveJson = (fileName: string, body: unknown): void => {
+	const url = URL.createObjectURL(
+		new Blob([JSON.stringify(body, null, 2)], { type: "application/json" }),
+	);
+	const anchor = document.createElement("a");
+	anchor.href = url;
+	anchor.download = fileName;
+	anchor.click();
+	URL.revokeObjectURL(url);
+};
+
+export function ConfigTransferPanel() {
+	const queryClient = useQueryClient();
+	const goToSection = useGoToSection();
+	const [state, setState] = useState<"ready" | "downloading" | "failed">(
+		"ready",
+	);
+	const [error, setError] = useState<string | undefined>(undefined);
+	const fileName = exportFileName(new Date());
+
+	const handleDownload = () => {
+		if (state === "downloading") return;
+		setState("downloading");
+		setError(undefined);
+		queryClient
+			.fetchQuery(configOperationsExportConfigOptions())
+			.then((response) => {
+				saveJson(fileName, response.document);
+				setState("ready");
+			})
+			.catch((cause: unknown) => {
+				setState("failed");
+				setError(
+					cause instanceof Error
+						? cause.message
+						: "GET /config/export did not answer with a configuration.",
+				);
+			});
+	};
+
+	return (
+		<ConfigExportCard
+			fileName={fileName}
+			state={state}
+			error={error}
+			onDownload={handleDownload}
+			onImport={() => goToSection("importConfig")}
+		/>
+	);
+}