@remit/web-client 0.0.62 → 0.0.64

package/src/hooks/useOrganizeWiden.test.ts

@@ -0,0 +1,151 @@
+/**
+ * The widen step's two-phase preview. On a semantic-capable deployment it runs
+ * the anchor preview once and stops. On a deployment that reports
+ * `semanticUnavailable` (no vector pipeline — semantic-capability.ts) it
+ * re-previews with sender-derived literal clauses — one `From` clause per
+ * distinct sender, combined with `Or`, no anchor — and reports the literal match
+ * count, so every commit scope acts on the sender-matched set.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { createElement, useEffect } from "react";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { type HttpMock, mockFetch } from "../test-support/http";
+import { useOrganizeWiden } from "./useOrganizeWiden";
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+});
+
+type Widen = ReturnType<typeof useOrganizeWiden>;
+type Responder = Parameters<typeof mockFetch>[0];
+
+const PREVIEW_PATH = "/organize/preview";
+
+const mount = (senders: string[], responder: Responder) => {
+	http = mockFetch(responder);
+	harness = createDomHarness();
+	const holder: { current: Widen | undefined } = { current: undefined };
+	function Probe() {
+		const widen = useOrganizeWiden("acc-1", "msg-1", senders);
+		holder.current = widen;
+		const { preview } = widen;
+		useEffect(() => {
+			preview();
+		}, [preview]);
+		return null;
+	}
+	harness.renderApp(createElement(Probe));
+	return holder;
+};
+
+async function settle(minCalls: number): Promise<void> {
+	const dom = harness;
+	const mock = http;
+	if (!dom || !mock) throw new Error("not mounted");
+	for (let attempt = 0; attempt < 40; attempt += 1) {
+		await dom.flush();
+		if (mock.to(PREVIEW_PATH).length >= minCalls) {
+			await dom.flush();
+			await dom.wait(1);
+			await dom.flush();
+			return;
+		}
+		await dom.wait(1);
+	}
+}
+
+describe("useOrganizeWiden — semantic-capable deployment", () => {
+	it("previews the anchor once and reports the semantic match, no fallback", async () => {
+		const holder = mount([], () => ({
+			matchedCount: 42,
+			messageIds: ["a", "b"],
+			semanticUnavailable: false,
+		}));
+		await settle(1);
+
+		assert.equal(http?.to(PREVIEW_PATH).length, 1);
+		const [call] = http?.to(PREVIEW_PATH) ?? [];
+		assert.equal(call.body?.anchorMessageId, "msg-1");
+		assert.deepEqual(call.body?.literalClauses, []);
+
+		const widen = holder.current;
+		assert.equal(widen?.matchedCount, 42);
+		assert.equal(widen?.semanticUnavailable, false);
+		assert.equal(widen?.senderFallback, false);
+		assert.deepEqual(widen?.matchPredicate, {
+			anchorMessageId: "msg-1",
+			matchOperator: "And",
+			literalClauses: [],
+		});
+	});
+});
+
+describe("useOrganizeWiden — no vector pipeline, senders present", () => {
+	it("re-previews with distinct sender From clauses combined with Or and no anchor", async () => {
+		const holder = mount(
+			["npm@github.com", "npm@github.com", "a@x.com"],
+			(call) =>
+				call.body?.anchorMessageId
+					? { matchedCount: 0, messageIds: [], semanticUnavailable: true }
+					: {
+							matchedCount: 128,
+							messageIds: ["m"],
+							semanticUnavailable: false,
+						},
+		);
+		await settle(2);
+
+		const calls = http?.to(PREVIEW_PATH) ?? [];
+		assert.equal(calls.length, 2);
+		// The second preview is the literal fallback: no anchor, Or, distinct
+		// sender From clauses.
+		const second = calls[1];
+		assert.equal(second.body?.anchorMessageId, undefined);
+		assert.equal(second.body?.matchOperator, "Or");
+		assert.deepEqual(second.body?.literalClauses, [
+			{ field: "From", value: "npm@github.com" },
+			{ field: "From", value: "a@x.com" },
+		]);
+
+		const widen = holder.current;
+		assert.equal(widen?.matchedCount, 128);
+		assert.equal(widen?.semanticUnavailable, true);
+		assert.equal(widen?.senderFallback, true);
+		assert.deepEqual(widen?.senders, ["npm@github.com", "a@x.com"]);
+		assert.deepEqual(widen?.matchPredicate, {
+			matchOperator: "Or",
+			literalClauses: [
+				{ field: "From", value: "npm@github.com" },
+				{ field: "From", value: "a@x.com" },
+			],
+		});
+	});
+});
+
+describe("useOrganizeWiden — no vector pipeline, no senders", () => {
+	it("does not re-preview and stays capability-absent with the anchor predicate", async () => {
+		const holder = mount([], () => ({
+			matchedCount: 0,
+			messageIds: [],
+			semanticUnavailable: true,
+		}));
+		await settle(1);
+		// Give any spurious second preview a chance to fire before asserting none did.
+		await harness?.flush();
+
+		assert.equal(http?.to(PREVIEW_PATH).length, 1);
+		const widen = holder.current;
+		assert.equal(widen?.semanticUnavailable, true);
+		assert.equal(widen?.senderFallback, false);
+		assert.deepEqual(widen?.senders, []);
+		assert.equal(widen?.matchPredicate.anchorMessageId, "msg-1");
+	});
+});

package/src/hooks/useOrganizeWiden.ts

@@ -0,0 +1,104 @@
+import { organizeOperationsPreviewOrganizeMutation } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation } from "@tanstack/react-query";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { buildOrganizeInput } from "@/lib/organize/organize-model";
+import {
+	buildSenderFallbackDraft,
+	deriveSenderClauses,
+	distinctSenders,
+	type OrganizeMatchPredicate,
+} from "@/lib/organize/sender-fallback";
+
+/**
+ * "Select similar messages" (the widen step) with a sender-derived fallback for
+ * deployments without the vector pipeline.
+ *
+ * The first preview runs the semantic anchor (POST /organize/preview). When the
+ * server reports `semanticUnavailable` — no vector pipeline on this deployment
+ * (semantic-capability.ts) — the widen re-previews with the literal vocabulary
+ * that matches vector-free: one `From` clause per distinct sender in the
+ * selection, combined with `Or`, no anchor. The counts shown, the one-time
+ * back-apply, and any standing filter then all carry that same literal
+ * predicate, so the previewed set equals the set every commit scope acts on.
+ *
+ * A semantic-capable deployment never fires the second preview and keeps exactly
+ * the anchor behaviour.
+ */
+export const useOrganizeWiden = (
+	accountId: string | undefined,
+	anchorMessageId: string | undefined,
+	senders: readonly string[],
+) => {
+	const mutation = useMutation(organizeOperationsPreviewOrganizeMutation());
+	const { mutate, reset: mutationReset } = mutation;
+	const [fellBack, setFellBack] = useState(false);
+
+	const distinct = useMemo(() => distinctSenders(senders), [senders]);
+
+	const preview = useCallback(() => {
+		if (!accountId || !anchorMessageId) return;
+		setFellBack(false);
+		mutate({
+			path: { accountId },
+			body: buildOrganizeInput({
+				anchorMessageId,
+				matchOperator: "And",
+				literalClauses: [],
+			}),
+		});
+	}, [accountId, anchorMessageId, mutate]);
+
+	const reset = useCallback(() => {
+		setFellBack(false);
+		mutationReset();
+	}, [mutationReset]);
+
+	const data = mutation.data;
+	// The first preview came back capability-absent and there are senders to
+	// match on: re-preview with the literal clauses before showing any count, so
+	// the count the user sees is the sender-match count, never a flash of the
+	// empty semantic result.
+	const willFallBack =
+		data?.semanticUnavailable === true && !fellBack && distinct.length > 0;
+
+	useEffect(() => {
+		if (!willFallBack || !accountId) return;
+		setFellBack(true);
+		mutate({
+			path: { accountId },
+			body: buildOrganizeInput(buildSenderFallbackDraft(distinct)),
+		});
+	}, [willFallBack, accountId, distinct, mutate]);
+
+	// The literal re-preview has no anchor, so its response reports
+	// `semanticUnavailable: false`; `fellBack` is what remembers the capability
+	// was absent once the fallback has run.
+	const capabilityAbsent = fellBack || (data?.semanticUnavailable ?? false);
+	const isPending = mutation.isPending || willFallBack;
+
+	const matchPredicate: OrganizeMatchPredicate = fellBack
+		? { matchOperator: "Or", literalClauses: deriveSenderClauses(distinct) }
+		: {
+				...(anchorMessageId ? { anchorMessageId } : {}),
+				matchOperator: "And",
+				literalClauses: [],
+			};
+
+	return {
+		preview,
+		reset,
+		matchedCount: isPending ? undefined : data?.matchedCount,
+		messageIds: isPending ? undefined : data?.messageIds,
+		// The deployment ships no vector pipeline — the widen matched on senders
+		// (or, with no senders, on nothing) rather than semantic similarity.
+		semanticUnavailable: capabilityAbsent,
+		// The widen fell back to sender matching and produced a usable literal
+		// match set: the commit scopes reach it, and the copy names the senders.
+		senderFallback: fellBack,
+		senders: distinct,
+		matchPredicate,
+		isPending,
+		isError: mutation.isError,
+		error: mutation.error,
+	};
+};

package/src/lib/organize/organize-copy.test.ts

@@ -3,7 +3,9 @@ import { describe, it } from "node:test";
 import {
 	commitButtonLabel,
 	commitDisabledReason,
+	formatSenderList,
 	scopeActionCount,
+	senderFallbackSummary,
 } from "./organize-copy";
 import type { OrganizeDraft } from "./organize-model";
 
@@ -91,3 +93,42 @@ describe("scopeActionCount", () => {
 		assert.equal(scopeActionCount("standing", 3, 48), 48);
 	});
 });
+
+describe("formatSenderList", () => {
+	it("names a single sender bare", () => {
+		assert.equal(formatSenderList(["npm@github.com"]), "npm@github.com");
+	});
+
+	it("joins a couple with 'and'", () => {
+		assert.equal(
+			formatSenderList(["a@x.com", "b@y.com"]),
+			"a@x.com and b@y.com",
+		);
+	});
+
+	it("lists up to three in full", () => {
+		assert.equal(
+			formatSenderList(["a@x.com", "b@y.com", "c@z.com"]),
+			"a@x.com, b@y.com and c@z.com",
+		);
+	});
+
+	it("truncates past three, summing the rest", () => {
+		assert.equal(
+			formatSenderList(["a@x.com", "b@y.com", "c@z.com", "d@w.com"]),
+			"a@x.com, b@y.com, c@z.com and 1 other",
+		);
+		assert.equal(
+			formatSenderList(["a@x.com", "b@y.com", "c@z.com", "d@w.com", "e@v.com"]),
+			"a@x.com, b@y.com, c@z.com and 2 others",
+		);
+	});
+});
+
+describe("senderFallbackSummary", () => {
+	it("states it is matching all mail from the senders, never 'similar'", () => {
+		const summary = senderFallbackSummary(["npm@github.com"]);
+		assert.match(summary, /isn't available on this server/);
+		assert.match(summary, /matching all mail from npm@github\.com instead/);
+	});
+});

package/src/lib/organize/organize-copy.ts

@@ -59,3 +59,32 @@ export const scopeActionCount = (
 	selectionCount: number,
 	matchedCount: number,
 ): number => (scope === "just-these" ? selectionCount : matchedCount);
+
+/** How many sender addresses are named before the rest are summed as "N others". */
+const MAX_SENDERS_SHOWN = 3;
+
+/**
+ * The sender addresses read out in prose: all of them when there are a few, or
+ * the first {@link MAX_SENDERS_SHOWN} and a count of the rest so a long selection
+ * stays legible in the sheet.
+ */
+export const formatSenderList = (senders: readonly string[]): string => {
+	if (senders.length === 0) return "these senders";
+	if (senders.length === 1) return senders[0];
+	if (senders.length <= MAX_SENDERS_SHOWN) {
+		return `${senders.slice(0, -1).join(", ")} and ${senders[senders.length - 1]}`;
+	}
+	const shown = senders.slice(0, MAX_SENDERS_SHOWN);
+	const rest = senders.length - MAX_SENDERS_SHOWN;
+	return `${shown.join(", ")} and ${rest} other${rest === 1 ? "" : "s"}`;
+};
+
+/**
+ * The heading when the widen fell back to sender matching (no vector pipeline on
+ * this server). States the actual semantics — matching every mail from these
+ * senders — and never claims semantic similarity.
+ */
+export const senderFallbackSummary = (senders: readonly string[]): string =>
+	`Similar-mail matching isn't available on this server — matching all mail from ${formatSenderList(
+		senders,
+	)} instead.`;

package/src/lib/organize/sender-fallback.test.ts

@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	buildSenderFallbackDraft,
+	deriveSenderClauses,
+	distinctSenders,
+} from "./sender-fallback";
+
+describe("distinctSenders", () => {
+	it("drops empties and blanks, trimming what remains", () => {
+		assert.deepEqual(
+			distinctSenders(["  npm@github.com ", "", "   ", "a@x.com"]),
+			["npm@github.com", "a@x.com"],
+		);
+	});
+
+	it("de-duplicates case-insensitively, keeping first-seen casing and order", () => {
+		assert.deepEqual(
+			distinctSenders([
+				"NPM@github.com",
+				"a@x.com",
+				"npm@GITHUB.com",
+				"a@x.com",
+			]),
+			["NPM@github.com", "a@x.com"],
+		);
+	});
+});
+
+describe("deriveSenderClauses", () => {
+	it("emits one From clause per distinct sender", () => {
+		assert.deepEqual(
+			deriveSenderClauses(["npm@github.com", "npm@github.com", "a@x.com"]),
+			[
+				{ field: "From", value: "npm@github.com" },
+				{ field: "From", value: "a@x.com" },
+			],
+		);
+	});
+
+	it("is empty when no sender survives", () => {
+		assert.deepEqual(deriveSenderClauses(["", "  "]), []);
+	});
+});
+
+describe("buildSenderFallbackDraft", () => {
+	it("combines the sender clauses with Or and carries no anchor", () => {
+		const draft = buildSenderFallbackDraft(["npm@github.com", "a@x.com"]);
+		assert.equal(draft.matchOperator, "Or");
+		assert.equal(draft.anchorMessageId, undefined);
+		assert.deepEqual(draft.literalClauses, [
+			{ field: "From", value: "npm@github.com" },
+			{ field: "From", value: "a@x.com" },
+		]);
+	});
+});

package/src/lib/organize/sender-fallback.ts

@@ -0,0 +1,64 @@
+import type {
+	RemitImapFilterClause,
+	RemitImapOrganizeInput,
+} from "@remit/api-http-client/types.gen.ts";
+import type { OrganizeDraft } from "./organize-model";
+
+/**
+ * The widen fallback for a deployment that ships no vector pipeline (self-host
+ * sqlite — semantic-capability.ts). The semantic anchor matches nothing there,
+ * so a widen degrades to the literal vocabulary RFC 031 already matches
+ * vector-free: one `From` clause per distinct sender in the selection, combined
+ * with `Or`, no anchor. The same predicate matches at index time (RFC 034), so a
+ * standing filter built from it keeps working on future mail.
+ */
+
+/**
+ * Distinct sender addresses from the selection, trimmed, empties dropped, and
+ * de-duplicated case-insensitively while preserving first-seen casing and order.
+ */
+export const distinctSenders = (senders: readonly string[]): string[] => {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const raw of senders) {
+		const value = raw.trim();
+		if (value === "") continue;
+		const key = value.toLowerCase();
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push(value);
+	}
+	return out;
+};
+
+/**
+ * One `From` literal clause per distinct sender address. A `From` clause matches
+ * the sender address or display name (match.ts `clauseMatches`), so the address
+ * is the precise, stable key.
+ */
+export const deriveSenderClauses = (
+	senders: readonly string[],
+): RemitImapFilterClause[] =>
+	distinctSenders(senders).map((value) => ({ field: "From", value }));
+
+/**
+ * The literal predicate that stands in for the semantic anchor: the sender `From`
+ * clauses combined with `Or` and no anchor. The preview, the one-time back-apply,
+ * and the standing filter all carry exactly this.
+ */
+export const buildSenderFallbackDraft = (
+	senders: readonly string[],
+): OrganizeDraft => ({
+	matchOperator: "Or",
+	literalClauses: deriveSenderClauses(senders),
+});
+
+/**
+ * The predicate the widen previewed, handed to the organize sentence so the set
+ * it previews equals the set every commit scope acts on. Either the semantic
+ * anchor or the sender-derived literal fallback, never both.
+ */
+export type OrganizeMatchPredicate = Pick<
+	RemitImapOrganizeInput,
+	"anchorMessageId" | "matchOperator" | "literalClauses"
+>;