@remit/web-client 0.0.134 → 0.0.136

package/src/components/mail/MessageAttachments.tsx

@@ -0,0 +1,153 @@
+import { messageOperationsDescribeMessageQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type {
+	RemitImapBodyPartResponse,
+	RemitImapDescribeMessageResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import { type AttachmentDownloadState, AttachmentList } from "@remit/ui";
+import { useQueryClient } from "@tanstack/react-query";
+import { useMemo, useState } from "react";
+import { useAuthProvider } from "@/auth/provider";
+import {
+	attachmentFailureContent,
+	attachmentReportUrl,
+	extractAttachmentFailureDetail,
+	extractAttachmentFailureReason,
+	fetchAttachment,
+	isRepairableByRefetch,
+	saveBlob,
+} from "@/lib/attachment-download";
+import {
+	type MessageAttachment,
+	selectMessageAttachments,
+} from "@/lib/message-attachments";
+
+interface MessageAttachmentsProps {
+	messageId: string;
+	/** Body parts from `describeMessage`; absent while the message is loading. */
+	bodyParts?: readonly RemitImapBodyPartResponse[];
+	/** The thread row's server-side attachment flag. */
+	hasAttachment?: boolean;
+	className?: string;
+}
+
+const IDLE: AttachmentDownloadState = { status: "idle" };
+
+/**
+ * The attachments carried by an open message, and the download behind each row.
+ *
+ * Download state is per row and lives here rather than in a query: a download is
+ * a one-shot user action with no cached result to hold, and the bytes are handed
+ * to the browser rather than rendered.
+ */
+export const MessageAttachments = ({
+	messageId,
+	bodyParts,
+	hasAttachment = false,
+	className,
+}: MessageAttachmentsProps) => {
+	const { getToken } = useAuthProvider();
+	const queryClient = useQueryClient();
+	const [downloads, setDownloads] = useState<
+		Record<string, AttachmentDownloadState>
+	>({});
+
+	const attachments = useMemo(
+		() => selectMessageAttachments(bodyParts ?? []),
+		[bodyParts],
+	);
+
+	const describeKey = messageOperationsDescribeMessageQueryKey({
+		path: { messageId },
+	});
+
+	/**
+	 * A stale signature and an unmaterialized part are both repaired by re-reading
+	 * the message: `describeMessage` re-signs every `contentUrl`, and it
+	 * materializes the deferred per-part objects on its way through. Re-hitting
+	 * the same URL alone cannot fix either (remit-mail/remit#1240), so the retry
+	 * goes through the read path and then uses the URL it just minted.
+	 */
+	const fetchThroughRefreshedDescribe = (
+		attachment: MessageAttachment,
+	): Promise<Blob> =>
+		fetchAttachment(attachment.contentUrl, getToken).catch(
+			(error: unknown): Promise<Blob> => {
+				if (!isRepairableByRefetch(extractAttachmentFailureReason(error))) {
+					throw error;
+				}
+				return queryClient
+					.refetchQueries({ queryKey: describeKey })
+					.then(() => {
+						const refreshed =
+							queryClient.getQueryData<RemitImapDescribeMessageResponse>(
+								describeKey,
+							);
+						const renewed = refreshed
+							? selectMessageAttachments(refreshed.bodyParts).find(
+									(candidate) => candidate.bodyPartId === attachment.bodyPartId,
+								)
+							: undefined;
+						return fetchAttachment(
+							renewed?.contentUrl ?? attachment.contentUrl,
+							getToken,
+						);
+					});
+			},
+		);
+
+	const setState = (id: string, state: AttachmentDownloadState) =>
+		setDownloads((current) => ({ ...current, [id]: state }));
+
+	const download = (bodyPartId: string) => {
+		const attachment = attachments.find(
+			(candidate) => candidate.bodyPartId === bodyPartId,
+		);
+		if (!attachment) {
+			throw new Error(
+				`No attachment part ${bodyPartId} on message ${messageId}`,
+			);
+		}
+
+		setState(bodyPartId, { status: "downloading" });
+		fetchThroughRefreshedDescribe(attachment)
+			.then((blob) => {
+				saveBlob(blob, attachment.filename);
+				setState(bodyPartId, IDLE);
+			})
+			.catch((error: unknown) => {
+				const reason = extractAttachmentFailureReason(error);
+				const fallback = extractAttachmentFailureDetail(error);
+				const { title, detail } = attachmentFailureContent(
+					reason,
+					attachment.filename,
+					fallback,
+				);
+				setState(bodyPartId, {
+					status: "failed",
+					title,
+					detail,
+					reportUrl: attachmentReportUrl(reason, attachment.filename, fallback),
+				});
+			});
+	};
+
+	// Only claim an attachment is unaccounted for once the parts have arrived;
+	// while `describeMessage` is in flight there is nothing to contradict.
+	const hasUnlistedAttachment =
+		hasAttachment && bodyParts !== undefined && attachments.length === 0;
+
+	return (
+		<AttachmentList
+			className={className}
+			attachments={attachments.map((attachment) => ({
+				attachmentId: attachment.bodyPartId,
+				filename: attachment.filename,
+				typeLabel: attachment.typeLabel,
+				sizeOctets: attachment.sizeOctets,
+				download: downloads[attachment.bodyPartId] ?? IDLE,
+			}))}
+			onDownload={download}
+			hasUnlistedAttachment={hasUnlistedAttachment}
+		/>
+	);
+};

package/src/components/mail/MessageCard.tsx

@@ -16,6 +16,7 @@ import { formatDatePreset } from "@/lib/format";
 import { cn } from "@/lib/utils";
 import { AutoMovedIndicator } from "./AutoMovedIndicator";
 import { MessageActionMenu } from "./MessageActionMenu";
+import { MessageAttachments } from "./MessageAttachments";
 import { MessageBody } from "./MessageBody";
 import { MobileMessageBar } from "./MobileMessageBar";
 import { RawMessageView } from "./RawMessageView";
@@ -134,7 +135,11 @@ const CollapsedCard = ({
 			trailing={
 				<>
 					{threadMessage.hasAttachment && (
-						<Paperclip className="size-3 shrink-0 text-fg-subtle" />
+						<Paperclip
+							className="size-3 shrink-0 text-fg-subtle"
+							role="img"
+							aria-label="Has an attachment"
+						/>
 					)}
 					<StarButton
 						isStarred={threadMessage.hasStars}
@@ -238,11 +243,6 @@ const ExpandedCard = ({
 										onToggleStar={onToggleStar}
 										isStarPending={isStarPending}
 									/>
-									{threadMessage.hasAttachment && (
-										<span className="text-fg-subtle p-0.5">
-											<Paperclip className="size-3.5" />
-										</span>
-									)}
 								</div>
 								{isUnread && (
 									// biome-ignore lint/a11y/useAriaPropsSupportedByRole: aria-label on decorative indicator provides useful context for assistive tech
@@ -324,6 +324,15 @@ const ExpandedCard = ({
 							isTrusted={isTrusted}
 							category={toDisplayCategory(threadMessage.category)}
 						/>
+						{/* The body slot runs edge to edge on a phone; the attachment
+						    list is app chrome, not part of the email, so it takes the
+						    gutter back. */}
+						<MessageAttachments
+							messageId={threadMessage.messageId}
+							bodyParts={messageData?.bodyParts}
+							hasAttachment={threadMessage.hasAttachment}
+							className="mt-4 px-2 lg:px-0"
+						/>
 					</div>
 				)
 			}

package/src/hooks/useSaveDraft.ts

@@ -8,6 +8,10 @@ import { useCallback, useRef, useState } from "react";
 
 export type SaveStatus = "idle" | "saving" | "saved" | "error";
 
+export type ImmediateSave =
+	| { outcome: "saved"; outboxMessageId: string }
+	| { outcome: "failed"; error: unknown };
+
 interface DraftData {
 	accountId: string;
 	toAddresses: string[];
@@ -25,6 +29,12 @@ interface UseSaveDraftOptions {
 	onDraftCreated: (id: string) => void;
 }
 
+const settled = (promise: Promise<unknown>): Promise<void> =>
+	promise.then(
+		() => undefined,
+		() => undefined,
+	);
+
 export const useSaveDraft = ({
 	outboxMessageId,
 	onDraftCreated,
@@ -35,6 +45,17 @@ export const useSaveDraft = ({
 	const closedIdsRef = useRef<Set<string>>(new Set());
 	const queryClient = useQueryClient();
 
+	// The entry a save writes to. That is the prop, except between a save
+	// creating the draft and the id arriving back as the prop — reading the prop
+	// in that window creates the same draft a second time and strands one of the
+	// two in the outbox.
+	const propIdRef = useRef(outboxMessageId);
+	const targetIdRef = useRef(outboxMessageId);
+	if (propIdRef.current !== outboxMessageId) {
+		propIdRef.current = outboxMessageId;
+		targetIdRef.current = outboxMessageId;
+	}
+
 	const createMutation = useMutation(
 		outboxOperationsCreateOutboxMessageMutation(),
 	);
@@ -47,9 +68,10 @@ export const useSaveDraft = ({
 			setSaveStatus("saving");
 			setSaveError(null);
 
-			if (outboxMessageId) {
+			const targetId = targetIdRef.current;
+			if (targetId) {
 				const result = await updateMutation.mutateAsync({
-					path: { outboxMessageId },
+					path: { outboxMessageId: targetId },
 					body: {
 						toAddresses: data.toAddresses,
 						ccAddresses: data.ccAddresses,
@@ -71,6 +93,7 @@ export const useSaveDraft = ({
 					sendImmediately: false,
 				},
 			});
+			targetIdRef.current = result.outboxMessageId;
 			onDraftCreated(result.outboxMessageId);
 			setSaveStatus("saved");
 			queryClient.invalidateQueries({
@@ -78,38 +101,60 @@ export const useSaveDraft = ({
 			});
 			return result;
 		},
-		[
-			outboxMessageId,
-			createMutation,
-			updateMutation,
-			onDraftCreated,
-			queryClient,
-		],
+		[createMutation, updateMutation, onDraftCreated, queryClient],
+	);
+
+	// One entry takes one write at a time. Overlapping writes settle in whatever
+	// order the network gives them, so an older body can land last — and two of
+	// them racing while the draft has no id yet each create one.
+	const writesRef = useRef<Promise<void>>(Promise.resolve());
+	const enqueueSave = useCallback(
+		(data: DraftData) => {
+			const write = writesRef.current.then(() => executeSave(data));
+			writesRef.current = settled(write);
+			return write;
+		},
+		[executeSave],
 	);
 
 	const saveDraft = useCallback(
 		(data: DraftData) => {
-			if (outboxMessageId && closedIdsRef.current.has(outboxMessageId)) return;
 			if (timerRef.current) clearTimeout(timerRef.current);
 			timerRef.current = setTimeout(() => {
+				const targetId = targetIdRef.current;
+				if (targetId && closedIdsRef.current.has(targetId)) return;
 				// Keep the real error, not just a vague "error" status — the caller
 				// surfaces its detail in a banner. A fatal 5xx additionally escalates
 				// through the global MutationCache.onError sink.
-				executeSave(data).catch((error: unknown) => {
+				enqueueSave(data).catch((error: unknown) => {
 					setSaveError(error);
 					setSaveStatus("error");
 				});
 			}, 2000);
 		},
-		[executeSave, outboxMessageId],
+		[enqueueSave],
 	);
 
+	// Whoever asks for this is acting on the draft right now and owns the
+	// outcome, so the failure is returned rather than thrown and `saveError` is
+	// left alone — the caller's own message is the accurate one, and setting
+	// `saveError` would raise a second "Couldn't save draft" banner beside it.
 	const saveImmediately = useCallback(
-		(data: DraftData) => {
+		(data: DraftData): Promise<ImmediateSave> => {
 			if (timerRef.current) clearTimeout(timerRef.current);
-			return executeSave(data);
+			return enqueueSave(data)
+				.then(
+					(result): ImmediateSave => ({
+						outcome: "saved",
+						outboxMessageId: result.outboxMessageId,
+					}),
+				)
+				.catch((error: unknown): ImmediateSave => {
+					setSaveStatus("error");
+					return { outcome: "failed", error };
+				});
 		},
-		[executeSave],
+		[enqueueSave],
 	);
 
 	// Called with an id, the entry is closed to autosave for good. Sending and

package/src/lib/attachment-download.test.ts

@@ -0,0 +1,207 @@
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import {
+	AttachmentFetchError,
+	attachmentFailureContent,
+	attachmentReportUrl,
+	classifyAttachmentFailure,
+	extractAttachmentFailureDetail,
+	extractAttachmentFailureReason,
+	fetchAttachment,
+	isRepairableByRefetch,
+	saveBlob,
+} from "./attachment-download";
+
+const originalFetch = globalThis.fetch;
+
+const respondWith = (
+	init: {
+		status: number;
+		statusText?: string;
+		headers?: Record<string, string>;
+	},
+	body: string = "bytes",
+) => {
+	globalThis.fetch = (async () =>
+		new Response(init.status === 204 ? null : body, {
+			status: init.status,
+			statusText: init.statusText ?? "",
+			headers: init.headers,
+		})) as typeof fetch;
+};
+
+afterEach(() => {
+	globalThis.fetch = originalFetch;
+});
+
+describe("classifyAttachmentFailure", () => {
+	it("reads an edge denial as an expired session", () => {
+		assert.equal(classifyAttachmentFailure(401, null), "auth");
+		assert.equal(classifyAttachmentFailure(403, "tenant-mismatch"), "auth");
+	});
+
+	it("reads an origin 403/404 as a missing object", () => {
+		assert.equal(classifyAttachmentFailure(403, null), "missing");
+		assert.equal(classifyAttachmentFailure(404, null), "missing");
+	});
+
+	// A stale signature is not a stale session — telling the user to sign in
+	// again would send them somewhere that cannot help.
+	it("separates an aged-out content signature from an expired session", () => {
+		assert.equal(classifyAttachmentFailure(403, "expired"), "link-expired");
+		assert.equal(isRepairableByRefetch("link-expired"), true);
+		assert.equal(isRepairableByRefetch("not-ready"), true);
+		assert.equal(isRepairableByRefetch("auth"), false);
+		assert.equal(isRepairableByRefetch("missing"), false);
+	});
+
+	it("reads anything else as generic", () => {
+		assert.equal(classifyAttachmentFailure(500, null), "generic");
+	});
+});
+
+describe("fetchAttachment", () => {
+	it("returns the bytes on a 200", async () => {
+		respondWith({ status: 200 }, "payload");
+		const blob = await fetchAttachment("https://cdn.test/x", async () => null);
+		assert.equal(await blob.text(), "payload");
+	});
+
+	it("sends the session token when there is one", async () => {
+		let seen: string | null = null;
+		globalThis.fetch = (async (_url: string, init?: RequestInit) => {
+			seen = new Headers(init?.headers).get("Authorization") ?? null;
+			return new Response("payload", { status: 200 });
+		}) as unknown as typeof fetch;
+		await fetchAttachment("https://cdn.test/x", async () => "tok");
+		assert.equal(seen, "Bearer tok");
+	});
+
+	it("treats a 202 as not-ready rather than as an empty file", async () => {
+		respondWith({ status: 202 });
+		await assert.rejects(
+			fetchAttachment("https://cdn.test/x", async () => null),
+			(error: unknown) =>
+				error instanceof AttachmentFetchError && error.reason === "not-ready",
+		);
+	});
+
+	it("throws with the classified reason on a failure status", async () => {
+		respondWith({ status: 404, statusText: "Not Found" });
+		await assert.rejects(
+			fetchAttachment("https://cdn.test/x", async () => null),
+			(error: unknown) =>
+				error instanceof AttachmentFetchError &&
+				error.reason === "missing" &&
+				error.status === 404,
+		);
+	});
+});
+
+describe("attachmentFailureContent", () => {
+	it("tells an expired session what to do, and names the file", () => {
+		const content = attachmentFailureContent(
+			"auth",
+			"report.pdf",
+			"irrelevant",
+		);
+		assert.match(content.title, /session expired/i);
+		assert.match(content.detail, /report\.pdf/);
+	});
+
+	it("distinguishes a missing object from a slow one", () => {
+		assert.notEqual(
+			attachmentFailureContent("missing", "x", "f").title,
+			attachmentFailureContent("not-ready", "x", "f").title,
+		);
+	});
+
+	it("surfaces the underlying error for an unclassified failure", () => {
+		const content = attachmentFailureContent(
+			"generic",
+			"x",
+			"Failed to download attachment (500 )",
+		);
+		assert.equal(content.detail, "Failed to download attachment (500 )");
+	});
+});
+
+describe("failure extraction", () => {
+	it("reads the reason off an AttachmentFetchError", () => {
+		assert.equal(
+			extractAttachmentFailureReason(
+				new AttachmentFetchError("missing", "gone", 404),
+			),
+			"missing",
+		);
+	});
+
+	it("treats an unrecognised throw as generic", () => {
+		assert.equal(extractAttachmentFailureReason("boom"), "generic");
+		assert.equal(extractAttachmentFailureDetail("boom"), "boom");
+		assert.equal(
+			extractAttachmentFailureDetail(new Error("transport lost")),
+			"transport lost",
+		);
+		assert.match(extractAttachmentFailureDetail({}), /unexpected error/);
+	});
+});
+
+describe("attachmentReportUrl", () => {
+	it("offers a prefilled issue for a failure the user cannot fix", () => {
+		const url = attachmentReportUrl("missing", "report.pdf", "gone");
+		assert.ok(url, "a reportable failure must carry an issue URL");
+		assert.ok(
+			url.startsWith("https://github.com/remit-mail/reader/issues/new?"),
+		);
+		assert.match(decodeURIComponent(url), /report\.pdf/);
+	});
+
+	it("offers none for an expired session, which is not a bug", () => {
+		assert.equal(
+			attachmentReportUrl("auth", "report.pdf", "denied"),
+			undefined,
+		);
+	});
+});
+
+describe("saveBlob", () => {
+	it("saves under the name it was given and cleans up the anchor", async () => {
+		const created: string[] = [];
+		const revoked: string[] = [];
+		const url = globalThis.URL as unknown as {
+			createObjectURL?: (blob: Blob) => string;
+			revokeObjectURL?: (value: string) => void;
+		};
+		url.createObjectURL = () => {
+			created.push("blob:test");
+			return "blob:test";
+		};
+		url.revokeObjectURL = (value) => revoked.push(value);
+
+		let clickedName: string | null = null;
+		const anchor = document.createElement("a");
+		anchor.click = () => {
+			clickedName = anchor.download;
+		};
+		const originalCreateElement = document.createElement.bind(document);
+		document.createElement = ((tag: string) =>
+			tag === "a"
+				? anchor
+				: originalCreateElement(tag)) as typeof document.createElement;
+
+		try {
+			saveBlob(new Blob(["x"]), "report.pdf");
+		} finally {
+			document.createElement = originalCreateElement;
+		}
+
+		assert.equal(clickedName, "report.pdf");
+		assert.deepEqual(created, ["blob:test"]);
+		assert.equal(document.body.contains(anchor), false);
+		assert.deepEqual(revoked, [], "revoking in the click's task cancels it");
+
+		await new Promise((resolve) => setTimeout(resolve, 5));
+		assert.deepEqual(revoked, ["blob:test"]);
+	});
+});