@capxul/sdk-react 4.2.0 → 4.20.0-beta.10

package/README.md

@@ -28,10 +28,12 @@ export function Providers({ children }: { children: React.ReactNode }) {
   session. Account and Organization readiness transitions refresh active
   authenticated queries.
 - `CapxulAuthenticationController` and `CapxulOnboardingController` select
-  app-owned slots and render no SDK-owned DOM. Supplying the onboarding
-  controller's `recoveryOptions` factory lets a fresh actor resume account
-  prerequisites before the stored Organization replay; a failed prerequisite
-  returns the same manual replay instead of looping.
+  app-owned slots and render no SDK-owned DOM. The onboarding controller keeps
+  no Organization submission: after a reload the Core SDK reads the pending
+  Organization from the backend and attaches it, so the app re-submits nothing.
+  A claimed identity with no Organization and no app-held form step reports
+  `organizationProgress` with `{ at: "loading", orgId: null }` until that
+  attach lands.
 - Rich-data hooks such as `useCapxulProfile`, `useCapxulOrgs`, members, roles,
   treasury, and money hooks remain TanStack Query projections. Personal
   holdings and activity reads start only after the Account is claimed.
@@ -54,6 +56,8 @@ export function Providers({ children }: { children: React.ReactNode }) {
   engine hook stays module-scoped. Both actor paths ship: a personal actor omits
   `.Source` and spends the personal Account; an organization actor holds the
   Budget the payment is drawn from and spends the treasury Account.
+  The submitted amount uses the selected registry AssetId and precision. This
+  includes 18-decimal WETH.
 - `CapxulContacts` is the compound address-book component. One root owns the
   book behaviour and draws nothing. The `.Summary`, `.List`, and `.Add` region
   parts each hand the screen one finished slice, and a `.List` row carries its
@@ -73,6 +77,9 @@ export function Providers({ children }: { children: React.ReactNode }) {
   and an amount the caller passed in `prefill` wins over it. Both engine hooks
   stay module-scoped.
 
+Activity groups use AssetId. The SDK resolves symbols and precision only for
+display and CSV output. Assets with the same peg remain separate.
+
 Payroll confirmation restores a saved run before enabling submission. An
 uncertain run keeps its period, amounts, recipients, and SDK request key across
 close/reopen and reload. Its fields remain fixed until Core confirms success or terminal closure.
@@ -96,6 +103,16 @@ The testing harness uses the real public provider and controllers and imports
 its client factory only through `@capxul/sdk/testing`; it owns no renderer or
 parallel identity state.
 
+## Activity documents
+
+`CapxulActivity.Detail` exposes `documents`, `selectedDocument`, and
+`selectDocument({ documentHash, contentHash })`. Selection defaults to the
+instruction, then the Movement Memo. `renderDocument()` returns safe semantic
+HTML. `downloadDocument()` returns exact bytes for a deliberate download.
+The host owns the panel and download action. Do not log these results.
+Account or Organization changes clear selection and cancel pending reads.
+These methods replace the receipt-only selector and action.
+
 ## Documentation
 
 - [Maintainer context](./CONTEXT.md)

package/dist/{controllers-BPEhjKX9.mjs → controllers-L1UqwWS1.mjs}

@@ -37,6 +37,24 @@ function useCapxulClientOrNull() {
 }
 //#endregion
 //#region src/internal/reactivity-keys.ts
+/**
+* The account a read is answered FOR, as a key segment (#2007 R19).
+*
+* A read whose answer depends on who is asking belongs to the (scope, account)
+* pair, not to the scope. Replacing one claimed account with another is not a
+* state-label change. Keying is what
+* makes the new person miss rather than read the previous person's answer.
+* `undefined` while no account is claimed — no such read may run then anyway.
+*/
+function actingAccount(identity) {
+	return identity !== null && identity.phase === "authenticated" && identity.account.at === "claimed" ? identity.account.address : void 0;
+}
+/** Keep invalidation prefixes shared, but never share a personal result across accounts.
+* Session reads also run before an Account is claimed (for example `orgs()`).
+*/
+function accountKey(key, identity) {
+	return [...key, actingAccount(identity) ?? (identity?.phase === "authenticated" ? identity.session.authUserId : null)];
+}
 const capxulKeys = {
 	root: ["capxul"],
 	profile: ["capxul", "profile"],
@@ -80,11 +98,12 @@ const capxulKeys = {
 		orgId ?? "pending",
 		"permissions"
 	],
-	orgMe: (orgId) => [
+	orgMe: (orgId, account) => [
 		"capxul",
 		"org",
 		orgId ?? "pending",
-		"me"
+		"me",
+		account ?? "pending"
 	],
 	orgLifecycle: (orgId) => [
 		"capxul",
@@ -151,10 +170,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 +208,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 +263,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 +370,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 +400,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 +483,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 +504,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
@@ -417,7 +565,7 @@ function CapxulIdentityProvider({ client, children }) {
 				if (!active) return;
 				state = runtime.snapshot();
 			}
-			if (state.phase === "authenticated" && state.profileComplete && state.account.at === "unknown") await runtime.send({ _tag: "EnsureAccount" }, { signal: controller.signal });
+			if (client._internal.accountSetup !== "explicit" && state.phase === "authenticated" && state.profileComplete && state.account.at === "unknown") await runtime.send({ _tag: "EnsureAccount" }, { signal: controller.signal });
 		}).catch(() => void 0);
 		return () => {
 			active = false;
@@ -426,9 +574,16 @@ function CapxulIdentityProvider({ client, children }) {
 	}, [client, runtime]);
 	useEffect(() => {
 		if (runtime === null) return;
+		let previousAccount = actingAccount(runtime.snapshot());
 		return runtime.subscribeTransitions((record) => {
 			const state = runtime.snapshot();
-			if (record.outcome === "applied" && record.from !== record.to && (record.to === "authenticated:claimed" || record.to === "authenticated:claimed:ready")) queryClient.invalidateQueries({ queryKey: capxulKeys.root });
+			const account = actingAccount(state);
+			const accountChanged = previousAccount !== void 0 && account !== void 0 && account !== previousAccount;
+			previousAccount = account;
+			if (record.outcome === "applied" && (record.from !== record.to || accountChanged) && (record.to === "authenticated:claimed" || record.to === "authenticated:claimed:ready")) queryClient.invalidateQueries({
+				queryKey: capxulKeys.root,
+				...accountChanged ? { refetchType: "none" } : {}
+			});
 			for (const listener of listeners.current) try {
 				listener(record, state);
 			} catch {
@@ -442,7 +597,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 });
@@ -565,6 +720,7 @@ function clearClientScopedQueries(queryClient, ownsQueryClient) {
 }
 function CapxulProvider(props) {
 	const { publishableKey, client: injectedClient, requirement, signer, observability, bootstrapBaseUrl, queryClient, children } = props;
+	const accountSetup = "accountSetup" in props ? props.accountSetup : void 0;
 	const [resolvedQueryClient] = useState(() => queryClient ?? makeDefaultQueryClient());
 	const [ownsQueryClient] = useState(() => queryClient === void 0);
 	const [attempt, setAttempt] = useState(0);
@@ -576,13 +732,15 @@ function CapxulProvider(props) {
 		...requirement === void 0 ? {} : { requirement },
 		...signer === void 0 ? {} : { signer },
 		...observability === void 0 ? {} : { observability },
-		...bootstrapBaseUrl === void 0 ? {} : { bootstrapBaseUrl }
+		...bootstrapBaseUrl === void 0 ? {} : { bootstrapBaseUrl },
+		...accountSetup === void 0 ? {} : { accountSetup }
 	}, [
 		publishableKey,
 		requirement,
 		signer,
 		observability,
 		bootstrapBaseUrl,
+		accountSetup,
 		attempt
 	]);
 	const [ownedBootstrap, setOwnedBootstrap] = useState(null);
@@ -821,4 +979,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 { useCapxul as _, useCapxulAuth as a, useCapxulIdentityOrNull as c, toInvocationControls as d, toInvocationOptions as f, useCapxulClientOrNull as g, capxulKeys as h, entered as i, useCapxulSend as l, actingAccount as m, CapxulOnboardingController as n, useCapxulDestination as o, accountKey as p, CapxulProvider as r, useCapxulIdentity as s, CapxulAuthenticationController as t, useCapxulTransitions as u };