@remit/web-client 0.0.172 → 0.0.173

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.172",
+  "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/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);