@capxul/sdk-react 4.2.0-rc.2 → 4.2.0-rc.4

package/dist/capxul-source.json

@@ -1,11 +1,11 @@
 {
   "source": {
-    "commit": "fe4f1c05f1de962a7a76825816bdff2beaf5fc88",
-    "tree": "45b0c3cfdd39d23a4cfb1c1bcc047521f16bc12d",
+    "commit": "400e4b861e8c10091ad2d9e71fc0502fe222a801",
+    "tree": "c3afb8bb5f3ce69ee8aa1e8fbe811fe213627887",
     "branch": "codex/programme-rc",
     "repository": "https://github.com/Xelmar-tech/infrastructure",
     "lockfileSha256": "5870f53b72706d103220c1bcf733cb4fb71196aea32a9cfbdc277d73cc959264"
   },
   "name": "@capxul/sdk-react",
-  "version": "4.2.0-rc.2"
+  "version": "4.2.0-rc.4"
 }

package/dist/{controllers-BPEhjKX9.mjs → controllers-DaT-AGx6.mjs}

@@ -151,10 +151,35 @@ const capxulKeys = {
 	]
 };
 //#endregion
-//#region src/identity.tsx
-const MISSING_IDENTITY_PROVIDER = Symbol("MISSING_IDENTITY_PROVIDER");
-const IdentityContext = createContext(MISSING_IDENTITY_PROVIDER);
-function controls(options) {
+//#region src/internal/invocation-controls.ts
+/**
+* Keep only the five public option fields, and only when they hold the right
+* kind of value. A named action verb takes its attempt as an optional FIRST
+* argument, so a screen that wires one straight to a DOM handler
+* (`onClick={row.hide}`) hands us a React SyntheticEvent. That is not an
+* attempt: it must reach neither the SDK call nor the callback echo.
+*/
+function toInvocationOptions(options) {
+	if (typeof options !== "object" || options === null) return void 0;
+	const attempt = {};
+	if (typeof options.correlationId === "string") attempt.correlationId = options.correlationId;
+	if (typeof options.journeyId === "string") attempt.journeyId = options.journeyId;
+	if (typeof options.timeoutMs === "number") attempt.timeoutMs = options.timeoutMs;
+	if (typeof options.deadlineMs === "number") attempt.deadlineMs = options.deadlineMs;
+	if (options.signal instanceof AbortSignal) attempt.signal = options.signal;
+	return Object.keys(attempt).length === 0 ? void 0 : attempt;
+}
+/**
+* Map the public camel-case invocation options onto the Core SDK's control
+* spelling. ONE definition, because the identity facade and every headless
+* engine must hand the SDK the same shape: a caller that captured one user
+* attempt before it started gets that attempt's `correlation_id`/`journey_id`
+* on whichever operation it starts (#1960 R02).
+*
+* It creates no identifiers. An absent option stays absent, so an automatic
+* read keeps its own invocation context instead of borrowing an attempt's.
+*/
+function toInvocationControls(options) {
 	if (options === void 0) return void 0;
 	return {
 		...options.signal === void 0 ? {} : { signal: options.signal },
@@ -164,12 +189,16 @@ function controls(options) {
 		...options.journeyId === void 0 ? {} : { journey_id: options.journeyId }
 	};
 }
+//#endregion
+//#region src/identity.tsx
+const MISSING_IDENTITY_PROVIDER = Symbol("MISSING_IDENTITY_PROVIDER");
+const IdentityContext = createContext(MISSING_IDENTITY_PROVIDER);
 const failure = (result) => result.ok ? null : {
 	ok: false,
 	reason: result.refused
 };
 async function guarded(runtime, verb, options, run) {
-	const invocation = controls(options);
+	const invocation = toInvocationControls(options);
 	try {
 		return await (runtime.runFacade?.(verb, invocation, run) ?? run(invocation));
 	} catch {
@@ -215,18 +244,102 @@ function normalizeOrganization(organization) {
 		return null;
 	}
 }
+/** The Organization id when its lane is already running or finished, else null. */
+const runningOrganization = (state) => {
+	if (state.phase !== "authenticated" || state.account.at !== "claimed") return null;
+	const org = state.account.org;
+	return org !== null && (org.at === "loading" || org.at === "settingUp" || org.at === "ready") ? org.orgId : null;
+};
+/** A superseded session read waits at most this long for the winning read. */
+const SESSION_SETTLE_LIMIT_MS = 3e4;
+const accountInFlight = (state) => state.phase === "authenticated" && (state.account.at === "deriving" || state.account.at === "claiming");
 function createAuth(client, clearAuthenticatedQueries) {
 	const runtime = client._internal.identity;
+	const settledSession = (invocation) => new Promise((resolve) => {
+		let done = false;
+		let stop = null;
+		let timer = null;
+		const onAbort = () => finish({
+			ok: false,
+			reason: "CANCELLED"
+		});
+		const finish = (result) => {
+			if (done) return;
+			done = true;
+			stop?.();
+			if (timer !== null) clearTimeout(timer);
+			invocation?.signal?.removeEventListener("abort", onAbort);
+			resolve(result);
+		};
+		if (invocation?.signal?.aborted) {
+			onAbort();
+			return;
+		}
+		invocation?.signal?.addEventListener("abort", onAbort, { once: true });
+		const unsubscribe = runtime.subscribeTransitions((record) => {
+			if (record.slot !== "identity:session") return;
+			if (record.outcome === "applied" && record.event === "SessionRead") finish({ ok: true });
+			else if (record.outcome === "failed" || record.outcome === "cancelled") finish({
+				ok: false,
+				reason: record.error_code
+			});
+		});
+		if (done) {
+			unsubscribe();
+			return;
+		}
+		stop = unsubscribe;
+		timer = setTimeout(() => finish({
+			ok: false,
+			reason: "UNKNOWN"
+		}), SESSION_SETTLE_LIMIT_MS);
+	});
 	const read = async (invocation) => {
 		const result = await runtime.send({ _tag: "ReadSession" }, invocation);
-		return failure(result) ?? { ok: true };
+		const refused = failure(result);
+		if (refused === null) return { ok: true };
+		return refused.reason === "SUPERSEDED" ? settledSession(invocation) : refused;
 	};
 	const ensureAccount = async (invocation) => {
 		const result = await runtime.send({ _tag: "EnsureAccount" }, invocation);
 		return failure(result) ?? { ok: true };
 	};
+	const settledAccount = (invocation) => new Promise((resolve) => {
+		let done = false;
+		let stop = null;
+		const onAbort = () => finish({
+			ok: false,
+			reason: "CANCELLED"
+		});
+		const finish = (result) => {
+			if (done) return;
+			done = true;
+			stop?.();
+			invocation?.signal?.removeEventListener("abort", onAbort);
+			resolve(result);
+		};
+		if (invocation?.signal?.aborted) {
+			onAbort();
+			return;
+		}
+		invocation?.signal?.addEventListener("abort", onAbort, { once: true });
+		const unsubscribe = runtime.subscribe((state) => {
+			if (!accountInFlight(state)) finish({ ok: true });
+		});
+		if (done) {
+			unsubscribe();
+			return;
+		}
+		stop = unsubscribe;
+		if (!accountInFlight(runtime.snapshot())) finish({ ok: true });
+	});
 	const reachClaimed = async (invocation) => {
 		let state = runtime.snapshot();
+		if (accountInFlight(state)) {
+			const settled = await settledAccount(invocation);
+			if (!settled.ok) return settled;
+			state = runtime.snapshot();
+		}
 		if (state.phase !== "authenticated" || state.account.at === "unknown") {
 			const result = await runtime.send({ _tag: "EnsureAccount" }, invocation);
 			const refused = failure(result);
@@ -238,6 +351,16 @@ function createAuth(client, clearAuthenticatedQueries) {
 			reason: "WRONG_STATE"
 		};
 		if (state.account.at === "claimed") return { ok: true };
+		if (accountInFlight(state)) {
+			const settled = await settledAccount(invocation);
+			if (!settled.ok) return settled;
+			state = runtime.snapshot();
+			if (state.phase !== "authenticated") return {
+				ok: false,
+				reason: "WRONG_STATE"
+			};
+			if (state.account.at === "claimed") return { ok: true };
+		}
 		const event = state.account.at === "failed" ? { _tag: "RetryAccount" } : state.account.at === "counterfactual" ? { _tag: "ClaimAccount" } : { _tag: "EnsureAccount" };
 		const result = await runtime.send(event, invocation);
 		const refused = failure(result);
@@ -258,13 +381,13 @@ function createAuth(client, clearAuthenticatedQueries) {
 			ok: false,
 			reason: "INVALID_INPUT"
 		};
+		const refreshed = await read(invocation);
+		if (!refreshed.ok) return refreshed;
 		const current = runtime.snapshot();
 		if (current.phase !== "authenticated" || !current.profileComplete) {
 			const completed = await runtime.completeProfile(submission.profileDetails, invocation);
 			if (!completed.ok) return completed;
 		}
-		const refreshed = await read(invocation);
-		if (!refreshed.ok) return refreshed;
 		const claimed = await reachClaimed(invocation);
 		return claimed.ok ? {
 			ok: true,
@@ -341,12 +464,13 @@ function createAuth(client, clearAuthenticatedQueries) {
 		}),
 		createOrganization: (submission, options) => guarded(runtime, "createOrganization", options, async (invocation) => {
 			const current = runtime.snapshot();
+			const running = runningOrganization(current);
+			if (running !== null) return {
+				ok: true,
+				orgId: running
+			};
 			if (current.phase === "authenticated" && current.account.at === "claimed") {
 				const org = current.account.org;
-				if (org !== null && (org.at === "loading" || org.at === "settingUp" || org.at === "ready")) return {
-					ok: true,
-					orgId: org.orgId
-				};
 				if (org?.at === "failed" && org.orgId !== null) {
 					if (!org.retryable) return {
 						ok: false,
@@ -361,6 +485,11 @@ function createAuth(client, clearAuthenticatedQueries) {
 			}
 			const prepared = await prepareOrganization(submission, invocation);
 			if (!prepared.ok) return prepared;
+			const opened = runningOrganization(runtime.snapshot());
+			if (opened !== null) return {
+				ok: true,
+				orgId: opened
+			};
 			const created = await runtime.send({
 				_tag: "CreateOrganization",
 				draft: prepared.organization
@@ -442,7 +571,7 @@ function CapxulIdentityProvider({ client, children }) {
 	}, []);
 	const value = useMemo(() => {
 		if (client === null || runtime === null) return null;
-		const send = (event, options) => runtime.send(event, controls(options));
+		const send = (event, options) => runtime.send(event, toInvocationControls(options));
 		const clearAuthenticatedQueries = async () => {
 			await queryClient.cancelQueries({ queryKey: capxulKeys.root });
 			await queryClient.resetQueries({ queryKey: capxulKeys.root });
@@ -821,4 +950,4 @@ function organizationForm(props, state, auth, submitted) {
 	});
 }
 //#endregion
-export { useCapxulAuth as a, useCapxulIdentityOrNull as c, capxulKeys as d, useCapxulClientOrNull as f, entered as i, useCapxulSend as l, CapxulOnboardingController as n, useCapxulDestination as o, useCapxul as p, CapxulProvider as r, useCapxulIdentity as s, CapxulAuthenticationController as t, useCapxulTransitions as u };
+export { useCapxulAuth as a, useCapxulIdentityOrNull as c, toInvocationControls as d, toInvocationOptions as f, useCapxul as h, entered as i, useCapxulSend as l, useCapxulClientOrNull as m, CapxulOnboardingController as n, useCapxulDestination as o, capxulKeys as p, CapxulProvider as r, useCapxulIdentity as s, CapxulAuthenticationController as t, useCapxulTransitions as u };

package/dist/index.d.mts

@@ -383,9 +383,9 @@ interface Contact {
 interface ContactRow extends Contact {
   /** Ours: one initials rule, not one copy per screen. */
   readonly initials: string;
-  readonly rename: (name: string) => void;
-  readonly hide: () => void;
-  readonly unhide: () => void;
+  readonly rename: (name: string, options?: InvocationOptions) => void;
+  readonly hide: (options?: InvocationOptions) => void;
+  readonly unhide: (options?: InvocationOptions) => void;
 }
 /** ADR-0023 R1: refusal CODES, never sentences — the app owns the words. */
 type ContactsRefusal = "loading" | "org-unavailable" | "unavailable";
@@ -421,7 +421,13 @@ interface ContactsListOptions {
 interface ContactsAddSlice {
   readonly value: string;
   readonly change: (text: string) => void;
-  readonly submit: () => void;
+  /**
+   * #1960 R02: hand it the options the screen captured BEFORE the click. The
+   * same snapshot reaches the SDK add call and comes back on `onAdded`/
+   * `onFailed`, so the UI observation and the operation share one identity even
+   * when the reply lands after an account switch. Omitted stays omitted.
+   */
+  readonly submit: (options?: InvocationOptions) => void;
   readonly isSubmitting: boolean;
   readonly blocked: boolean;
   readonly blockedReason: ContactsAddBlockedReason | null;
@@ -431,9 +437,14 @@ interface ContactsAddSlice {
 //#region src/headless/contacts/contacts.d.ts
 interface CapxulContactsProps {
   readonly actor: ContactsActor;
-  readonly onAdded: (contact: Contact) => void;
+  /**
+   * `options` is exactly what the caller handed `.Add.submit` or a row verb, so
+   * the screen's own observation of the finished action can reuse the attempt
+   * identity the SDK operation ran under (#1960 R02).
+   */
+  readonly onAdded: (contact: Contact, options?: InvocationOptions) => void;
   /** ADR-0023 R1: the app maps `error.code` to its own copy; no SDK sentence. */
-  readonly onFailed: (error: CapxulError) => void;
+  readonly onFailed: (error: CapxulError, options?: InvocationOptions) => void;
   readonly children: ReactNode;
 }
 declare function Root$6({ actor, onAdded, onFailed, children }: CapxulContactsProps): import("react/jsx-runtime").JSX.Element;
@@ -545,7 +556,12 @@ interface ActivityRowsSlice {
   readonly rows: readonly ActivityRow[];
   readonly isLoading: boolean;
   readonly error: CapxulError | null;
-  readonly retry: () => void;
+  /**
+   * #1960 R02: pass the options captured before the retry was selected and the
+   * re-read runs under the same attempt identity as the UI observation. Omit
+   * them and the read keeps its own invocation context.
+   */
+  readonly retry: (options?: InvocationOptions) => void;
   /** Server read time of the newest page, so the app can say which read is older. */
   readonly observedAt: number | null;
 }
@@ -589,7 +605,8 @@ interface CsvExport {
   readonly truncated: boolean;
 }
 interface ActivityExportSlice {
-  readonly toCsv: () => Promise<CsvExport>;
+  /** Same contract as `retry`: the export's pages run under the caller's attempt. */
+  readonly toCsv: (options?: InvocationOptions) => Promise<CsvExport>;
   readonly isExporting: boolean;
 }
 //#endregion

package/dist/index.mjs

@@ -1,5 +1,5 @@
 "use client";
-import { a as useCapxulAuth, c as useCapxulIdentityOrNull, d as capxulKeys, f as useCapxulClientOrNull, i as entered, l as useCapxulSend, n as CapxulOnboardingController, o as useCapxulDestination, p as useCapxul, r as CapxulProvider, s as useCapxulIdentity, t as CapxulAuthenticationController, u as useCapxulTransitions } from "./controllers-BPEhjKX9.mjs";
+import { a as useCapxulAuth, c as useCapxulIdentityOrNull, d as toInvocationControls, f as toInvocationOptions, h as useCapxul, i as entered, l as useCapxulSend, m as useCapxulClientOrNull, n as CapxulOnboardingController, o as useCapxulDestination, p as capxulKeys, r as CapxulProvider, s as useCapxulIdentity, t as CapxulAuthenticationController, u as useCapxulTransitions } from "./controllers-DaT-AGx6.mjs";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { CAPXUL_OPERATIONS, CapxulError, EVM_ADDRESS_RE, Errors, HANDLE_RE, PAYMENT_DIRECTIONS, PAYMENT_STATUSES, fingerprintPaymentIntent, formatMoney, isCapxulError, isClaimed, isClaimed as isClaimed$1, isMoneyParseError, isRestoring, isRestoring as isRestoring$1, parseMoney, paymentPhase, resolveIdentityDestination, toEvmAddress, toPartyId } from "@capxul/sdk";
@@ -879,6 +879,8 @@ function useCapxulUploadImage() {
 }
 //#endregion
 //#region src/headless/contacts/use-contacts.ts
+/** One captured snapshot, or nothing — never a fabricated empty options object. */
+const carry = (options) => options === void 0 ? {} : { options };
 function useContacts(input) {
 	const { actor, onAdded, onFailed } = input;
 	const client = useCapxulClientOrNull();
@@ -895,35 +897,40 @@ function useContacts(input) {
 	const writeMutate = useMutation({
 		mutationFn: async (command) => {
 			const target = requireBook(book, `addressBook.${command.kind}`);
+			const controls = toInvocationControls(command.options);
 			return unwrapCapxulResult(command.kind === "rename" ? await target.label({
 				entryId: command.id,
 				label: command.name
-			}) : command.kind === "hide" ? await target.hide(command.id) : await target.unhide(command.id));
+			}, controls) : command.kind === "hide" ? await target.hide(command.id, controls) : await target.unhide(command.id, controls));
 		},
 		onSettled: invalidate,
-		onError: onFailed
+		onError: (error, command) => onFailed(error, command.options)
 	}).mutate;
 	const [value, setValue] = useState("");
 	const [addError, setAddError] = useState(null);
 	const addContact = useMutation({
-		mutationFn: async (ref) => unwrapCapxulResult(await requireBook(book, CAPXUL_OPERATIONS.addressBook.add).add({ ref })),
+		mutationFn: async (command) => unwrapCapxulResult(await requireBook(book, CAPXUL_OPERATIONS.addressBook.add).add({ ref: command.ref }, toInvocationControls(command.options))),
 		onSettled: invalidate
 	});
 	const addMutate = addContact.mutate;
 	const blockedReason = refusal !== null ? "org-unavailable" : value.trim() === "" ? "empty" : null;
 	const submitGate = useRef(false);
-	const submit = useCallback(() => {
+	const submit = useCallback((options) => {
 		if (blockedReason !== null || submitGate.current) return;
+		const attempt = toInvocationOptions(options);
 		submitGate.current = true;
 		setAddError(null);
-		addMutate(refFromTypedText(value), {
+		addMutate({
+			ref: refFromTypedText(value),
+			...carry(attempt)
+		}, {
 			onSuccess: (entry) => {
 				setValue("");
-				onAdded(toContact(entry));
+				onAdded(toContact(entry), attempt);
 			},
 			onError: (error) => {
 				setAddError(error.code === "INVALID_INPUT" ? "unresolved" : "failed");
-				onFailed(error);
+				onFailed(error, attempt);
 			},
 			onSettled: () => {
 				submitGate.current = false;
@@ -944,18 +951,21 @@ function useContacts(input) {
 		book,
 		scope,
 		refusal,
-		rename: useCallback((id, name) => writeMutate({
+		rename: useCallback((id, name, options) => writeMutate({
 			kind: "rename",
 			id,
-			name
+			name,
+			...carry(toInvocationOptions(options))
 		}), [writeMutate]),
-		hide: useCallback((id) => writeMutate({
+		hide: useCallback((id, options) => writeMutate({
 			kind: "hide",
-			id
+			id,
+			...carry(toInvocationOptions(options))
 		}), [writeMutate]),
-		unhide: useCallback((id) => writeMutate({
+		unhide: useCallback((id, options) => writeMutate({
 			kind: "unhide",
-			id
+			id,
+			...carry(toInvocationOptions(options))
 		}), [writeMutate]),
 		add: {
 			value,
@@ -989,9 +999,9 @@ function useContactsList(engine, options) {
 			if (entries === void 0) return [];
 			return (limit === void 0 ? entries : entries.slice(0, limit)).map((entry) => Object.assign(toContact(entry), {
 				initials: initialsOf(entry.label),
-				rename: (name) => rename(entry.id, name),
-				hide: () => hide(entry.id),
-				unhide: () => unhide(entry.id)
+				rename: (name, attempt) => rename(entry.id, name, attempt),
+				hide: (attempt) => hide(entry.id, attempt),
+				unhide: (attempt) => unhide(entry.id, attempt)
 			}));
 		}, [
 			entries,
@@ -1567,6 +1577,12 @@ function useActivity(input) {
 		if (filter !== void 0) params.filter = filter;
 		return params;
 	}, [actor, filter]);
+	const selectedRetry = useRef(void 0);
+	const takeSelectedRetry = useCallback(() => {
+		const attempt = selectedRetry.current;
+		selectedRetry.current = void 0;
+		return toInvocationControls(attempt);
+	}, []);
 	const query = useInfiniteQuery({
 		queryKey: [
 			...capxulKeys.activity,
@@ -1576,7 +1592,7 @@ function useActivity(input) {
 			filter ?? "none"
 		],
 		queryFn: async ({ pageParam }) => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.list).activity.list(listParams(pageParam, limit)));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.list).activity.list(listParams(pageParam, limit), takeSelectedRetry()));
 		},
 		initialPageParam: void 0,
 		getNextPageParam: (last) => last.cursor ?? void 0,
@@ -1624,14 +1640,15 @@ function useActivity(input) {
 		observerRef.current = observer;
 	}, [loadMore]);
 	const [isExporting, setIsExporting] = useState(false);
-	const toCsv = useCallback(async () => {
+	const toCsv = useCallback(async (options) => {
 		setIsExporting(true);
+		const controls = toInvocationControls(toInvocationOptions(options));
 		try {
 			const bootstrapped = requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.list);
 			const items = [];
 			let cursor;
 			for (let page = 0; page < EXPORT_PAGE_CEILING; page += 1) {
-				const result = unwrapCapxulResult(await bootstrapped.activity.list(listParams(cursor, EXPORT_PAGE_SIZE)));
+				const result = unwrapCapxulResult(await bootstrapped.activity.list(listParams(cursor, EXPORT_PAGE_SIZE), controls));
 				items.push(...result.items);
 				cursor = result.cursor ?? void 0;
 				if (cursor === void 0) break;
@@ -1654,7 +1671,8 @@ function useActivity(input) {
 		setDirection(void 0);
 		setStatus([]);
 	}, []);
-	const retry = useCallback(() => {
+	const retry = useCallback((options) => {
+		selectedRetry.current = toInvocationOptions(options);
 		refetch();
 	}, [refetch]);
 	return {

package/dist/testing/index.mjs

@@ -1,4 +1,4 @@
-import { n as CapxulOnboardingController, r as CapxulProvider, t as CapxulAuthenticationController } from "../controllers-BPEhjKX9.mjs";
+import { n as CapxulOnboardingController, r as CapxulProvider, t as CapxulAuthenticationController } from "../controllers-DaT-AGx6.mjs";
 import "react";
 import { jsx } from "react/jsx-runtime";
 import { createCapxulTestClient } from "@capxul/sdk/testing";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capxul/sdk-react",
-  "version": "4.2.0-rc.2",
+  "version": "4.2.0-rc.4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Xelmar-tech/infrastructure.git",
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@capxul/sdk": "4.2.0-rc.2"
+    "@capxul/sdk": "4.2.0-rc.4"
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.66.9",
@@ -43,9 +43,9 @@
     "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
     "vite-plus": "0.3.0",
     "vitest": "4.1.11",
-    "@capxul/errors": "0.3.0",
     "@capxul/typescript-config": "0.0.0",
-    "@capxul/types": "0.3.0"
+    "@capxul/types": "0.3.0",
+    "@capxul/errors": "0.3.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.66.9",