@remit/web-client 0.0.171 → 0.0.173

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.171",
+  "version": "0.0.173",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/components/compose/ComposeProvider.tsx

@@ -59,7 +59,12 @@ export const ComposeProvider = ({
 		enabled: !!pollingMessageId,
 		refetchInterval: (query) => {
 			const status = query.state.data?.status;
-			if (status === "sent" || status === "failed" || status === "blocked")
+			if (
+				status === "sent" ||
+				status === "unfiled" ||
+				status === "failed" ||
+				status === "blocked"
+			)
 				return false;
 			if (Date.now() - startedAtRef.current > MAX_POLL_DURATION_MS)
 				return false;
@@ -72,6 +77,7 @@ export const ComposeProvider = ({
 
 		const terminal =
 			polledMessage.status === "sent" ||
+			polledMessage.status === "unfiled" ||
 			polledMessage.status === "failed" ||
 			polledMessage.status === "blocked";
 

package/src/components/mail/OutboxPane.tsx

@@ -59,7 +59,7 @@ import {
 	matchesOutboxSearch,
 	outboxQueryIsUnsupported,
 } from "@/lib/outbox-search";
-import { isOutboxListRow, isUnsendableStatus } from "@/lib/outbox-status";
+import { isOutboxListRow, showsLastError } from "@/lib/outbox-status";
 import { normalizeSearchQuery } from "@/lib/search-query";
 import { parseSearchTokens } from "@/lib/search-tokens";
 import { useEditDraft, useRetainOpenPanels } from "@/routing";
@@ -87,6 +87,11 @@ const STATUS_CONFIG: Record<
 		label: "Sent",
 		className: "text-positive",
 	},
+	unfiled: {
+		icon: AlertTriangle,
+		label: "Sent, not filed",
+		className: "text-warning",
+	},
 	failed: {
 		icon: AlertCircle,
 		label: "Failed",
@@ -310,7 +315,7 @@ function OutboxMessageRow({
 	>;
 	if (!STATUS_CONFIG[status]) return null;
 
-	const showError = isUnsendableStatus(message.status);
+	const showError = showsLastError(message.status);
 
 	return (
 		<OutboxRow
@@ -414,7 +419,7 @@ function OutboxMessageDetail({ message, onBack }: OutboxMessageDetailProps) {
 							<span className={cn("text-xs font-medium", config.className)}>
 								{config.label}
 							</span>
-							{isUnsendableStatus(message.status) && message.lastError && (
+							{showsLastError(message.status) && message.lastError && (
 								<span className="text-xs text-fg-muted">
 									— {message.lastError}
 								</span>

package/src/components/ui/ErrorBanner.stories.tsx

@@ -6,10 +6,10 @@ import { ErrorBanner } from "./ErrorBanner";
  * message list, so it is opaque and it names its own severity out loud rather
  * than leaving colour to carry the meaning.
  *
- * A failure the user cannot act on still gets an action link, prefilled, so
- * reporting it is one click instead of a form they have to assemble. The
- * hrefs below stand in for the real report URL, which the app builds from
- * build-time constants Storybook has no `define` for.
+ * Every error banner carries a prefilled report link, so reporting a failure
+ * the user cannot act on is one click instead of a form they have to
+ * assemble. The hrefs below stand in for the real report URL, which the app
+ * builds from build-time constants Storybook has no `define` for.
  */
 const meta: Meta<typeof ErrorBanner> = {
 	title: "Components/ErrorBanner",
@@ -27,21 +27,38 @@ type Story = StoryObj<typeof ErrorBanner>;
 const REPORT_URL =
 	"https://github.com/remit-mail/reader/issues/new?title=Spellcheck+stopped";
 
-/** A mutation that failed, with the reason underneath. */
+/** A mutation that failed, with the reason underneath and a way out. */
 export const Failed: Story = {
 	name: "Error",
 	args: {
 		severity: "error",
 		title: "Couldn't move message",
 		detail: "Connection reset by peer",
+		action: { label: "Report an issue", href: REPORT_URL },
 	},
 };
 
-/** Nothing more to say than the title. */
+/** Nothing more to say than the title — the report link still stands. */
 export const NoDetail: Story = {
 	args: {
 		severity: "error",
 		title: "Couldn't move message",
+		action: { label: "Report an issue", href: REPORT_URL },
+	},
+};
+
+/**
+ * Report spam failing because the account has nowhere to file it. The reason
+ * names the folder and the fix, so this one is actionable without the report
+ * link — which is offered anyway, because the user should not have to decide.
+ */
+export const NoJunkFolder: Story = {
+	args: {
+		severity: "error",
+		title: "Couldn't report this message as spam",
+		detail:
+			"This account has no Junk folder. Create one named Junk or Spam in your mail provider, then report this message again.",
+		action: { label: "Report an issue", href: REPORT_URL },
 	},
 };
 

package/src/components/ui/ErrorBannerProvider.tsx

@@ -6,6 +6,7 @@ import {
 	useMemo,
 	useState,
 } from "react";
+import { buildBugReportContext, buildGitHubIssueUrl } from "@/lib/bug-report";
 import { isAlwaysFatal } from "@/lib/error-classifier";
 import { reportFatalError } from "@/lib/fatal-error";
 import { ErrorBannerStack } from "./ErrorBannerStack.js";
@@ -13,6 +14,7 @@ import {
 	appendBanner,
 	buildEntry,
 	dismissBanner,
+	type ErrorBannerAction,
 	type ErrorBannerEntry,
 	type PushErrorInput,
 } from "./error-banners.js";
@@ -28,6 +30,37 @@ const ErrorBannerContext = createContext<ErrorBannerContextValue | undefined>(
 	undefined,
 );
 
+/**
+ * A way out of every failure banner. A soft failure is still a failure the
+ * user could not prevent and cannot diagnose, and a banner offering only
+ * "Dismiss" is a dead end — the fatal screen has carried a prefilled report
+ * since issue #55 and the soft surface never did. The report is seeded from
+ * the banner it belongs to, so it names the failure instead of asking the
+ * user to describe it, and it carries the same breadcrumbs — failing request,
+ * navigation, console — the fatal report does.
+ *
+ * A caller that already has a better way out keeps it, and a warning or an
+ * informational banner gets none: those are not failures to report.
+ */
+export const bannerWayOut = (
+	input: PushErrorInput,
+): ErrorBannerAction | undefined => {
+	if (input.action) return input.action;
+	if ((input.severity ?? "error") !== "error") return undefined;
+	return {
+		label: "Report an issue",
+		href: buildGitHubIssueUrl(
+			buildBugReportContext({
+				title: `Bug: ${input.title}`,
+				errorMessage: input.detail
+					? `${input.title} — ${input.detail}`
+					: input.title,
+				stack: input.error instanceof Error ? input.error.stack : undefined,
+			}),
+		),
+	};
+};
+
 const generateId = (): string => {
 	if (
 		typeof globalThis.crypto !== "undefined" &&
@@ -58,7 +91,11 @@ export const ErrorBannerProvider = ({ children }: { children: ReactNode }) => {
 		if (input.error != null && isAlwaysFatal(input.error)) {
 			return reportFatalError(input.error).correlationId;
 		}
-		const entry = buildEntry(input, generateId(), Date.now());
+		const entry = buildEntry(
+			{ ...input, action: bannerWayOut(input) },
+			generateId(),
+			Date.now(),
+		);
 		setErrors((current) => appendBanner(current, entry));
 		return entry.id;
 	}, []);

package/src/components/ui/banner-way-out.test.ts

@@ -0,0 +1,71 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { ApiError } from "@/lib/api";
+import { bannerWayOut } from "./ErrorBannerProvider";
+
+const issueBody = (href: string): string =>
+	new URL(href).searchParams.get("body") ?? "";
+
+const issueTitle = (href: string): string =>
+	new URL(href).searchParams.get("title") ?? "";
+
+describe("bannerWayOut — no failure banner is a dead end", () => {
+	it("offers a prefilled report on a failure the user cannot act on", () => {
+		// The spam report that failed on test.remit.email offered nothing but
+		// Dismiss: no reason, no fix, no way to report it.
+		const action = bannerWayOut({
+			title: "Couldn't report this message as spam",
+			detail: "This message could not be processed.",
+			error: new ApiError("This message could not be processed.", 422),
+		});
+
+		assert.equal(action?.label, "Report an issue");
+		assert.ok(
+			action?.href.startsWith(
+				"https://github.com/remit-mail/reader/issues/new?",
+			),
+		);
+		assert.match(
+			issueTitle(action.href),
+			/Couldn't report this message as spam/,
+		);
+		assert.match(
+			issueBody(action.href),
+			/Couldn't report this message as spam/,
+		);
+	});
+
+	it("carries the stack of the error that caused the banner", () => {
+		const error = new Error("Connection reset by peer");
+		const action = bannerWayOut({
+			title: "Couldn't move this message",
+			error,
+		});
+
+		assert.ok(action !== undefined);
+		assert.match(issueBody(action.href), /Stacktrace/);
+	});
+
+	it("keeps an action the call site already chose", () => {
+		const action = bannerWayOut({
+			title: "Spellcheck stopped",
+			action: { label: "Report this", href: "https://example.invalid/report" },
+		});
+
+		assert.deepEqual(action, {
+			label: "Report this",
+			href: "https://example.invalid/report",
+		});
+	});
+
+	it("offers none on a warning or a statement of fact", () => {
+		assert.equal(
+			bannerWayOut({ severity: "warning", title: "Draft saved locally" }),
+			undefined,
+		);
+		assert.equal(
+			bannerWayOut({ severity: "info", title: "Sync finished" }),
+			undefined,
+		);
+	});
+});

package/src/hooks/useReportSpam.ts

@@ -51,7 +51,7 @@ interface UseReportSpamOptions {
  * despite a non-zero `failureCount`.
  */
 export const GENERIC_SPAM_ACTION_FAILURE =
-	"This message could not be processed. Please try again.";
+	"This message could not be processed. Please try again. If it keeps failing, report it.";
 
 /**
  * The server's designed failure text names the message by embedding its raw

package/src/lib/app-info.ts

@@ -2,10 +2,18 @@
  * Build-time constants injected by vite.config.ts via `define`.
  * __APP_SHA__ is the full git SHA (or "dev" in local builds without git).
  * __APP_BUILD_TIME__ is an ISO timestamp.
+ *
+ * Read through `typeof` because not every host that renders this app's
+ * components applies the `define` — Storybook's test runner mounts them
+ * without it — and a bare reference is a ReferenceError at module scope that
+ * takes the importing story down with it. An unknown build is the same
+ * "dev" the git-less local build already resolves to.
  */
 
-export const APP_SHA: string = __APP_SHA__;
-export const APP_BUILD_TIME: string = __APP_BUILD_TIME__;
+export const APP_SHA: string =
+	typeof __APP_SHA__ === "undefined" ? "dev" : __APP_SHA__;
+export const APP_BUILD_TIME: string =
+	typeof __APP_BUILD_TIME__ === "undefined" ? "unknown" : __APP_BUILD_TIME__;
 
 /** First 7 characters of the SHA, matching git's default short form. */
 export const APP_SHORT_SHA: string = APP_SHA.slice(0, 7);

package/src/lib/outbox-status.test.ts

@@ -3,7 +3,7 @@ import { describe, test } from "node:test";
 import {
 	describeOutboxStatus,
 	isOutboxListRow,
-	isUnsendableStatus,
+	showsLastError,
 } from "./outbox-status.js";
 
 describe("describeOutboxStatus", () => {
@@ -25,6 +25,13 @@ describe("describeOutboxStatus", () => {
 		assert.equal(desc.label, "Sent");
 	});
 
+	test("unfiled says the message was sent but not filed", () => {
+		const desc = describeOutboxStatus("unfiled");
+		assert.ok(desc);
+		assert.equal(desc.tone, "warning");
+		assert.match(desc.label, /not filed/);
+	});
+
 	test("failed is error tone (distinct from blocked)", () => {
 		const desc = describeOutboxStatus("failed");
 		assert.ok(desc);
@@ -33,19 +40,23 @@ describe("describeOutboxStatus", () => {
 	});
 });
 
-describe("isUnsendableStatus", () => {
-	test("sent must NOT be flagged as unsendable — never show error subtitle on success (issue #192)", () => {
-		assert.equal(isUnsendableStatus("sent"), false);
+describe("showsLastError", () => {
+	test("sent must NOT surface an error — never show an error subtitle on success (issue #192)", () => {
+		assert.equal(showsLastError("sent"), false);
 	});
 
-	test("failed and blocked are unsendable", () => {
-		assert.equal(isUnsendableStatus("failed"), true);
-		assert.equal(isUnsendableStatus("blocked"), true);
+	test("failed and blocked surface their error", () => {
+		assert.equal(showsLastError("failed"), true);
+		assert.equal(showsLastError("blocked"), true);
 	});
 
-	test("queued and sending are not unsendable", () => {
-		assert.equal(isUnsendableStatus("queued"), false);
-		assert.equal(isUnsendableStatus("sending"), false);
+	test("unfiled surfaces its reason — the row exists only to carry it", () => {
+		assert.equal(showsLastError("unfiled"), true);
+	});
+
+	test("queued and sending carry no error", () => {
+		assert.equal(showsLastError("queued"), false);
+		assert.equal(showsLastError("sending"), false);
 	});
 });
 
@@ -61,4 +72,8 @@ describe("isOutboxListRow", () => {
 		assert.equal(isOutboxListRow("failed"), true);
 		assert.equal(isOutboxListRow("blocked"), true);
 	});
+
+	test("keeps an unfiled row listed — it is the only copy the user has", () => {
+		assert.equal(isOutboxListRow("unfiled"), true);
+	});
 });

package/src/lib/outbox-status.ts

@@ -29,6 +29,7 @@ const STATUS_DESCRIPTORS: Record<OutboxDisplayStatus, OutboxStatusDescriptor> =
 		queued: { label: "Queued", tone: "neutral" },
 		sending: { label: "Sending…", tone: "info" },
 		sent: { label: "Sent", tone: "success" },
+		unfiled: { label: "Sent, not filed", tone: "warning" },
 		failed: { label: "Failed", tone: "error" },
 		blocked: { label: "Blocked", tone: "warning" },
 	};
@@ -56,11 +57,12 @@ export const describeOutboxStatus = (
  *
  * Critically: `sent` is NOT included. A successful send must never display
  * a stale lastError — that is the contradictory "green check + 'SMTP not
- * configured'" UI bug from issue #192.
+ * configured'" UI bug from issue #192. `unfiled` is: the message was
+ * delivered but could not be filed, and the reason is the whole point of
+ * the row still being there.
  */
-export const isUnsendableStatus = (
-	status: RemitImapOutboxMessageStatus,
-): boolean => status === "failed" || status === "blocked";
+export const showsLastError = (status: RemitImapOutboxMessageStatus): boolean =>
+	status === "failed" || status === "blocked" || status === "unfiled";
 
 /**
  * Whether the outbox list view should render this row.
@@ -68,7 +70,9 @@ export const isUnsendableStatus = (
  * `draft` belongs in the Drafts view. `sent` rows are deleted by the IMAP
  * APPEND handler (issue #178) — but until that happens we hide them from
  * the Outbox list so a successfully-sent message never appears in two
- * places at once (issue #193).
+ * places at once (issue #193). `unfiled` is the settled failure of that
+ * APPEND: the message is on no server folder, so the Outbox row is the only
+ * copy the user has and it stays listed.
  */
 export const isOutboxListRow = (
 	status: RemitImapOutboxMessageStatus,