@capxul/sdk-react 1.0.0-alpha.9 → 1.2.0

package/dist/index.mjs

@@ -1,152 +1,7 @@
 "use client";
-import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
-import { QueryClient, QueryClientProvider, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { captureExceptionSync, createCapxulClient, isSettingUpLifecycle } from "@capxul/sdk";
-import { jsx } from "react/jsx-runtime";
-//#region src/internal/capxul-bootstrap-context.tsx
-const CapxulBootstrapContext = createContext(null);
-function CapxulBootstrapProvider({ value, children }) {
-	return /* @__PURE__ */ jsx(CapxulBootstrapContext.Provider, {
-		value,
-		children
-	});
-}
-function useCapxul() {
-	const state = useContext(CapxulBootstrapContext);
-	if (state === null) throw new Error("useCapxul must be used within <CapxulProvider>");
-	return state;
-}
-//#endregion
-//#region src/internal/capxul-client-context.tsx
-const MISSING_CAPXUL_CLIENT_PROVIDER = Symbol("MISSING_CAPXUL_CLIENT_PROVIDER");
-const CapxulClientContext = createContext(MISSING_CAPXUL_CLIENT_PROVIDER);
-function CapxulClientProvider({ client, children }) {
-	return /* @__PURE__ */ jsx(CapxulClientContext.Provider, {
-		value: client,
-		children
-	});
-}
-function useCapxulClient() {
-	const client = useCapxulClientOrNull();
-	if (client === null) throw new Error("useCapxulClient called before <CapxulProvider> bootstrap resolved");
-	return client;
-}
-/**
-* Returns the client, or `null` while `<CapxulProvider>` is still bootstrapping.
-* Data hooks use this so they can sit in `isPending` (disabled query) until the
-* client resolves, rather than throwing during bootstrap.
-*/
-function useCapxulClientOrNull() {
-	const client = useContext(CapxulClientContext);
-	if (client === MISSING_CAPXUL_CLIENT_PROVIDER) throw new Error("useCapxulClient must be used within <CapxulProvider>");
-	return client;
-}
-//#endregion
-//#region src/provider.tsx
-function makeDefaultQueryClient() {
-	return new QueryClient({ defaultOptions: {
-		queries: {
-			retry: 2,
-			staleTime: 3e4
-		},
-		mutations: { retry: 0 }
-	} });
-}
-function isCapxulQueryKey(queryKey) {
-	return queryKey[0] === "capxul";
-}
-function clearClientScopedQueries(queryClient, ownsQueryClient) {
-	if (ownsQueryClient) {
-		queryClient.clear();
-		return;
-	}
-	queryClient.removeQueries({ predicate: (query) => isCapxulQueryKey(query.queryKey) });
-}
-function CapxulProvider(props) {
-	const { publishableKey, client: injectedClient, requirement, signer, queryClient, children } = props;
-	const [resolvedQueryClient] = useState(() => queryClient ?? makeDefaultQueryClient());
-	const [ownsQueryClient] = useState(() => queryClient === void 0);
-	const [client, setClient] = useState(injectedClient ?? null);
-	const previousClientRef = useRef(injectedClient ?? null);
-	const [status, setStatus] = useState(injectedClient === void 0 ? "bootstrapping" : "ready");
-	const [error, setError] = useState(null);
-	const [attempt, setAttempt] = useState(0);
-	const retry = useCallback(() => {
-		setAttempt((n) => n + 1);
-	}, []);
-	useEffect(() => {
-		if (publishableKey === void 0) return;
-		let cancelled = false;
-		let created = null;
-		setStatus("bootstrapping");
-		setError(null);
-		setClient(null);
-		(async () => {
-			const result = await createCapxulClient({
-				publishableKey,
-				...requirement === void 0 ? {} : { requirement },
-				...signer === void 0 ? {} : { signer }
-			});
-			if (cancelled) {
-				if (result.ok) await result.value._internal.close?.();
-				return;
-			}
-			if (result.ok) {
-				created = result.value;
-				setClient(result.value);
-				setStatus("ready");
-			} else {
-				setError(result.error);
-				setStatus("error");
-			}
-		})();
-		return () => {
-			cancelled = true;
-			created?._internal.close?.();
-		};
-	}, [
-		publishableKey,
-		requirement,
-		signer,
-		attempt
-	]);
-	useEffect(() => {
-		if (injectedClient === void 0) return;
-		setClient(injectedClient);
-		setStatus("ready");
-		setError(null);
-	}, [injectedClient]);
-	useEffect(() => {
-		const previous = previousClientRef.current;
-		if (previous !== null && previous !== client) clearClientScopedQueries(resolvedQueryClient, ownsQueryClient);
-		previousClientRef.current = client;
-	}, [
-		client,
-		ownsQueryClient,
-		resolvedQueryClient
-	]);
-	const bootstrapState = useMemo(() => ({
-		status,
-		error,
-		retry
-	}), [
-		status,
-		error,
-		retry
-	]);
-	if (publishableKey === void 0 === (injectedClient === void 0)) throw new Error("CapxulProvider requires exactly one of `publishableKey` or `client`");
-	return /* @__PURE__ */ jsx(QueryClientProvider, {
-		client: resolvedQueryClient,
-		children: /* @__PURE__ */ jsx(CapxulBootstrapProvider, {
-			value: bootstrapState,
-			children: /* @__PURE__ */ jsx(CapxulClientProvider, {
-				client,
-				children
-			})
-		})
-	});
-}
-//#endregion
+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-BU11km12.mjs";
+import { useEffect, useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 //#region ../errors/src/errors.ts
 const CAPXUL_ERROR_CODES = [
 	"NOT_AUTHENTICATED",
@@ -170,7 +25,11 @@ const CAPXUL_ERROR_CODES = [
 	"OTP_EXPIRED",
 	"SIGNER_REJECTED",
 	"CANCELLED",
-	"WRONG_STATE"
+	"WRONG_STATE",
+	"STALE_EPOCH",
+	"SUPERSEDED",
+	"WORK_DIED",
+	"ACTOR_STOPPED"
 ];
 var CapxulError = class extends Error {
 	code;
@@ -215,8 +74,7 @@ const Errors = {
 	} }),
 	/**
 	* Sibling factory to {@link Errors.providerError} for the per-state timeout
-	* path in flows (initially ProvisioningFlow's mint_openfort / deploy_safe /
-	* register_indexer `after:` timers). Same `PROVIDER_ERROR` code as
+	* path in flows. Same `PROVIDER_ERROR` code as
 	* `providerError`, plus a `details.reason: "timeout"` discriminator so
 	* downstream observers can distinguish failure modes without parsing the
 	* message string. The redacted message names the timeout budget; the
@@ -286,8 +144,8 @@ const Errors = {
 	* Method called from a flow state where its precondition fails (TA16). The
 	* SDK's method API short-circuits with this error before driving the
 	* internal state machine. `currentState` is the Effect-machine snapshot
-	* tag (stringified — substrate is `@effect/experimental/Machine` per
-	* `docs/canon/decisions/state-machine-substrate.md`); `validStates`
+	* tag (stringified from the SDK's actor-shell snapshot; see
+	* `packages/errors/CONTEXT.md`); `validStates`
 	* enumerates the states the method accepts.
 	*/
 	wrongState: (details) => new CapxulError("WRONG_STATE", `${details.method} called from state '${details.currentState}'; valid states: ${details.validStates.join(", ")}`, { details: {
@@ -313,162 +171,32 @@ function requireBootstrappedClient(client, method) {
 	return client;
 }
 //#endregion
-//#region src/internal/reactivity-keys.ts
-const capxulKeys = {
-	session: ["capxul", "session"],
-	profile: ["capxul", "profile"],
-	account: ["capxul", "account"],
-	accountLifecycle: ["capxul", "accountLifecycle"],
-	provisioning: ["capxul", "provisioning"],
-	binding: ["capxul", "binding"],
-	accountBalance: ["capxul", "accountBalance"],
-	subAccounts: (accountId) => [
-		"capxul",
-		"subAccounts",
-		accountId ?? "pending"
-	],
-	orgs: ["capxul", "orgs"],
-	org: (orgId) => [
-		"capxul",
-		"org",
-		orgId ?? "pending"
-	],
-	orgMembers: (orgId) => [
-		"capxul",
-		"org",
-		orgId ?? "pending",
-		"members"
-	],
-	orgRoles: (orgId) => [
-		"capxul",
-		"org",
-		orgId ?? "pending",
-		"roles"
-	],
-	orgTreasury: (orgId) => [
-		"capxul",
-		"org",
-		orgId ?? "pending",
-		"treasury"
-	]
-};
-//#endregion
 //#region src/internal/unwrap-capxul-result.ts
 /**
-* Unwrap a `CapxulResult` for TanStack query/mutation functions —
-* throws into error paths, optionally reporting the error to telemetry first.
+* Unwrap a `CapxulResult` for TanStack query/mutation functions and throw into
+* React Query's error path.
 *
-* When `telemetry` is provided and the result is `{ ok: false }`,
-* `captureExceptionSync` is called (fire-and-forget) before the throw. `operation`
-* tags the telemetry event so query reads and mutation writes stay
-* distinguishable in error tracking (defaults to `"query"`).
+* Failure observation belongs to the core SDK method boundary. The legacy
+* telemetry/operation arguments remain temporarily source-compatible with the
+* existing hook call sites, but are deliberately ignored so React cannot
+* report the same logical failure a second time.
 */
-function unwrapCapxulResult(result, telemetry, operation = "query") {
+function unwrapCapxulResult(result, _legacyTelemetry, _legacyOperation = "query") {
 	if (result.ok) return result.value;
-	if (telemetry) try {
-		captureExceptionSync(telemetry, result.error, {
-			layer: "react-query",
-			operation
-		});
-	} catch {}
 	throw result.error;
 }
 //#endregion
-//#region src/hooks/use-capxul-session.ts
-function useCapxulSession() {
-	const client = useCapxulClientOrNull();
-	return useQuery({
-		queryKey: capxulKeys.session,
-		queryFn: async () => unwrapCapxulResult(await requireBootstrappedClient(client, "auth.getSession").auth.getSession(), client._internal.telemetry),
-		enabled: client !== null
-	});
-}
-//#endregion
 //#region src/hooks/use-capxul-profile.ts
 function useCapxulProfile() {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	return useQuery({
 		queryKey: capxulKeys.profile,
 		queryFn: async () => unwrapCapxulResult(await requireBootstrappedClient(client, "identity.loadCurrent").identity.loadCurrent(), client._internal.telemetry),
-		enabled: client !== null
+		enabled: client !== null && identity?.phase === "authenticated"
 	});
 }
 //#endregion
-//#region src/internal/is-vitest-runtime.ts
-/** True under Vitest — disables hook polling intervals that fight fake timers. */
-function isVitestRuntime() {
-	return typeof process !== "undefined" && process.env["VITEST"] === "true";
-}
-//#endregion
-//#region src/internal/invalidate-auth-boundary.ts
-/** Background refetch after verifyOtp — avoids hard reset cancel errors in UI. */
-async function invalidateAuthBoundary(queryClient) {
-	await Promise.all([
-		queryClient.invalidateQueries({ queryKey: capxulKeys.session }),
-		queryClient.invalidateQueries({ queryKey: capxulKeys.profile }),
-		queryClient.invalidateQueries({ queryKey: capxulKeys.accountLifecycle }),
-		queryClient.invalidateQueries({ queryKey: capxulKeys.accountBalance })
-	]);
-}
-/** Hard reset after signOut — drop cached authenticated rows immediately. */
-async function resetAuthBoundary(queryClient) {
-	await queryClient.cancelQueries({ queryKey: capxulKeys.accountBalance });
-	await Promise.all([
-		queryClient.resetQueries({ queryKey: capxulKeys.session }),
-		queryClient.resetQueries({ queryKey: capxulKeys.profile }),
-		queryClient.resetQueries({ queryKey: capxulKeys.accountLifecycle }),
-		queryClient.resetQueries({ queryKey: capxulKeys.accountBalance })
-	]);
-}
-//#endregion
-//#region src/hooks/use-capxul-account-lifecycle.ts
-const LOADING_LIFECYCLE = { status: "loading" };
-function useCapxulAccountLifecycle() {
-	const client = useCapxulClientOrNull();
-	const queryClient = useQueryClient();
-	const query = useQuery({
-		queryKey: capxulKeys.accountLifecycle,
-		queryFn: async () => {
-			const bootstrappedClient = requireBootstrappedClient(client, "account.getLifecycle");
-			return unwrapCapxulResult(await bootstrappedClient.account.getLifecycle(), bootstrappedClient._internal.telemetry);
-		},
-		enabled: client !== null,
-		refetchInterval: (q) => {
-			if (isVitestRuntime()) return false;
-			const data = q.state.data;
-			if (data === void 0) return false;
-			if (data.status === "loading" || isSettingUpLifecycle(data)) return 2e3;
-			return false;
-		}
-	});
-	const retryMutation = useMutation({
-		mutationFn: async () => {
-			const bootstrappedClient = requireBootstrappedClient(client, "account.retrySetup");
-			return unwrapCapxulResult(await bootstrappedClient.account.retrySetup(), bootstrappedClient._internal.telemetry, "mutation");
-		},
-		onSuccess: async () => {
-			await invalidateAuthBoundary(queryClient);
-		}
-	});
-	const lifecycle = query.data ?? LOADING_LIFECYCLE;
-	const failedError = lifecycle.status === "failed" ? lifecycle.error : null;
-	const queryError = query.isError ? query.error : null;
-	return {
-		lifecycle: queryError !== null && lifecycle.status === "loading" ? {
-			status: "failed",
-			at: "connecting",
-			error: queryError
-		} : lifecycle,
-		isSettingUp: isSettingUpLifecycle(lifecycle),
-		error: failedError ?? queryError,
-		isLoading: query.isLoading,
-		isFetching: query.isFetching,
-		isError: query.isError,
-		retry: retryMutation.mutateAsync,
-		isRetrying: retryMutation.isPending
-	};
-}
-//#endregion
 //#region src/hooks/use-capxul-account-balance.ts
 function useCapxulAccountBalance(options) {
 	const client = useCapxulClientOrNull();
@@ -497,46 +225,6 @@ function useCapxulAccountFund() {
 	});
 }
 //#endregion
-//#region src/hooks/use-capxul-sign-in.ts
-function useCapxulSignIn() {
-	const client = useCapxulClientOrNull();
-	return useMutation({ mutationFn: async (input) => {
-		const bootstrappedClient = requireBootstrappedClient(client, "auth.signIn");
-		return unwrapCapxulResult(await bootstrappedClient.auth.signIn(input), bootstrappedClient._internal.telemetry, "mutation");
-	} });
-}
-//#endregion
-//#region src/hooks/use-capxul-verify-otp.ts
-function useCapxulVerifyOtp() {
-	const client = useCapxulClientOrNull();
-	const queryClient = useQueryClient();
-	return useMutation({
-		mutationFn: async (input) => {
-			const bootstrappedClient = requireBootstrappedClient(client, "auth.verifyOtp");
-			return unwrapCapxulResult(await bootstrappedClient.auth.verifyOtp(input), bootstrappedClient._internal.telemetry, "mutation");
-		},
-		onSuccess: async () => {
-			await invalidateAuthBoundary(queryClient);
-		}
-	});
-}
-//#endregion
-//#region src/hooks/use-capxul-sign-out.ts
-function useCapxulSignOut() {
-	const client = useCapxulClientOrNull();
-	const queryClient = useQueryClient();
-	return useMutation({
-		onMutate: async () => {
-			await queryClient.cancelQueries({ queryKey: capxulKeys.accountBalance });
-		},
-		mutationFn: async () => {
-			const bootstrappedClient = requireBootstrappedClient(client, "auth.signOut");
-			return unwrapCapxulResult(await bootstrappedClient.auth.signOut(), bootstrappedClient._internal.telemetry, "mutation");
-		},
-		onSuccess: () => resetAuthBoundary(queryClient)
-	});
-}
-//#endregion
 //#region src/hooks/use-capxul-sub-accounts.ts
 function useCapxulSubAccountsList(accountId, options) {
 	const client = useCapxulClientOrNull();
@@ -611,65 +299,160 @@ function useCapxulTransfer() {
 	});
 }
 //#endregion
-//#region src/hooks/use-capxul-orgs.ts
-function useCapxulOrgs(options) {
+//#region src/internal/invalidate-money-state.ts
+async function invalidateMoneyState(queryClient, input) {
+	const invalidations = [queryClient.invalidateQueries({ queryKey: capxulKeys.payments })];
+	if (input.payment !== void 0) invalidations.push(queryClient.invalidateQueries({ queryKey: capxulKeys.payment(input.payment.id) }));
+	if (input.actor.kind === "account" || input.actor.kind === "personal") invalidations.push(queryClient.invalidateQueries({ queryKey: capxulKeys.accountBalance }));
+	else {
+		const orgId = input.actor.kind === "org" ? input.actor.orgId : input.actor.organizationId;
+		invalidations.push(queryClient.invalidateQueries({ queryKey: capxulKeys.orgTreasury(orgId) }));
+	}
+	await Promise.all(invalidations);
+}
+//#endregion
+//#region src/internal/reject-unresolved-actor.ts
+/**
+* Guard for mutation hooks whose variables carry an optional `actor` field
+* (`useCapxulPay`, `useCapxulPayout`, `useCapxulAddDestination`,
+* `useCapxulRemoveDestination`). Mirrors `requireActorScope` on the query path:
+* an EXPLICITLY-passed `actor: undefined` (the `capxulOrgScope(notYetLoadedOrgId)`
+* footgun) must fail loudly rather than silently fall back to the personal
+* scope. Omitting the `actor` key entirely keeps the personal-scope default.
+*
+* Throws `CapxulError` code `INVALID_INPUT` with `details.field === "actor"`;
+* called inside an async mutationFn it surfaces as `mutation.error: CapxulError`.
+*/
+function rejectUnresolvedActor(variables, operation) {
+	if (Object.hasOwn(variables, "actor") && variables.actor === void 0) throw Errors.invalidInput("actor", `explicitly provided but undefined for ${operation} — actor scope not yet resolved; omit actor for the personal scope`);
+}
+//#endregion
+//#region src/hooks/use-capxul-money.ts
+function useCapxulPay() {
+	const client = useCapxulClientOrNull();
+	const queryClient = useQueryClient();
+	return useMutation({
+		mutationFn: async (input) => {
+			rejectUnresolvedActor(input, "payments.pay");
+			const bootstrappedClient = requireBootstrappedClient(client, "payments.pay");
+			return unwrapCapxulResult(await bootstrappedClient.payments.pay(input), bootstrappedClient._internal.telemetry, "mutation");
+		},
+		onSuccess: async (payment) => {
+			await invalidateMoneyState(queryClient, {
+				actor: { kind: "personal" },
+				payment
+			});
+		}
+	});
+}
+function useCapxulPayout() {
+	const client = useCapxulClientOrNull();
+	const queryClient = useQueryClient();
+	return useMutation({
+		mutationFn: async (input) => {
+			rejectUnresolvedActor(input, "payments.payout");
+			const bootstrappedClient = requireBootstrappedClient(client, "payments.payout");
+			return unwrapCapxulResult(await bootstrappedClient.payments.payout(input), bootstrappedClient._internal.telemetry, "mutation");
+		},
+		onSuccess: async (payment, variables) => {
+			await invalidateMoneyState(queryClient, {
+				actor: variables.actor ?? { kind: "personal" },
+				payment
+			});
+		}
+	});
+}
+function useCapxulWithdraw() {
+	const client = useCapxulClientOrNull();
+	const queryClient = useQueryClient();
+	return useMutation({
+		mutationFn: async (input) => {
+			const bootstrappedClient = requireBootstrappedClient(client, "payments.withdraw");
+			return unwrapCapxulResult(await bootstrappedClient.payments.withdraw(input), bootstrappedClient._internal.telemetry, "mutation");
+		},
+		onSuccess: async (payment) => {
+			await invalidateMoneyState(queryClient, {
+				actor: { kind: "personal" },
+				payment
+			});
+		}
+	});
+}
+function useCapxulPayments(options) {
 	const client = useCapxulClientOrNull();
 	return useQuery({
-		queryKey: capxulKeys.orgs,
+		queryKey: capxulKeys.payments,
 		queryFn: async () => {
-			const bootstrappedClient = requireBootstrappedClient(client, "orgs");
-			return unwrapCapxulResult(await bootstrappedClient.orgs(), bootstrappedClient._internal.telemetry);
+			const bootstrappedClient = requireBootstrappedClient(client, "payments.list");
+			return unwrapCapxulResult(await bootstrappedClient.payments.list(), bootstrappedClient._internal.telemetry);
 		},
 		enabled: client !== null && (options?.enabled ?? true)
 	});
 }
+function useCapxulPayment(paymentId, options) {
+	const client = useCapxulClientOrNull();
+	return useQuery({
+		queryKey: capxulKeys.payment(paymentId),
+		queryFn: async () => {
+			if (paymentId === void 0) throw Errors.invalidInput("paymentId", "required for payments.get");
+			const bootstrappedClient = requireBootstrappedClient(client, "payments.get");
+			return unwrapCapxulResult(await bootstrappedClient.payments.get(paymentId), bootstrappedClient._internal.telemetry);
+		},
+		enabled: client !== null && paymentId !== void 0 && (options?.enabled ?? true)
+	});
+}
 //#endregion
-//#region src/hooks/use-capxul-org.ts
-function useCapxulOrg(orgId, options) {
-	const client = useCapxulClient();
+//#region src/hooks/use-capxul-orgs.ts
+function useCapxulOrgs(options) {
+	const client = useCapxulClientOrNull();
 	return useQuery({
-		queryKey: capxulKeys.org(orgId),
+		queryKey: capxulKeys.orgs,
 		queryFn: async () => {
-			if (orgId === void 0) throw Errors.invalidInput("orgId", "required for useCapxulOrg");
-			return unwrapCapxulResult(await client.orgs(), client._internal.telemetry).find((org) => org.id === orgId) ?? null;
+			const bootstrappedClient = requireBootstrappedClient(client, "orgs");
+			return unwrapCapxulResult(await bootstrappedClient.orgs(), bootstrappedClient._internal.telemetry);
 		},
-		enabled: (options?.enabled ?? true) && orgId !== void 0
+		enabled: client !== null && (options?.enabled ?? true)
 	});
 }
 //#endregion
 //#region src/hooks/use-capxul-org-members.ts
 function useCapxulOrgMembers(orgId, options) {
-	const client = useCapxulClient();
+	const client = useCapxulClientOrNull();
+	const enabled = options?.enabled ?? true;
 	return useQuery({
 		queryKey: capxulKeys.orgMembers(orgId),
 		queryFn: async () => {
 			if (orgId === void 0) throw Errors.invalidInput("orgId", "required for useCapxulOrgMembers");
-			return unwrapCapxulResult(await client.org(orgId).members(), client._internal.telemetry);
+			const bootstrappedClient = requireBootstrappedClient(client, "org.members");
+			return unwrapCapxulResult(await bootstrappedClient.org(orgId).members(), bootstrappedClient._internal.telemetry);
 		},
-		enabled: (options?.enabled ?? true) && orgId !== void 0
+		enabled: client !== null && enabled && orgId !== void 0
 	});
 }
 //#endregion
 //#region src/hooks/use-capxul-org-roles.ts
 function useCapxulOrgRoles(orgId, options) {
-	const client = useCapxulClient();
+	const client = useCapxulClientOrNull();
+	const enabled = options?.enabled ?? true;
 	return useQuery({
 		queryKey: capxulKeys.orgRoles(orgId),
 		queryFn: async () => {
 			if (orgId === void 0) throw Errors.invalidInput("orgId", "required for useCapxulOrgRoles");
-			return unwrapCapxulResult(await client.org(orgId).roles(), client._internal.telemetry);
+			const bootstrappedClient = requireBootstrappedClient(client, "org.roles");
+			return unwrapCapxulResult(await bootstrappedClient.org(orgId).roles(), bootstrappedClient._internal.telemetry);
 		},
-		enabled: (options?.enabled ?? true) && orgId !== void 0
+		enabled: client !== null && enabled && orgId !== void 0
 	});
 }
 //#endregion
 //#region src/hooks/use-capxul-org-deploy-roles.ts
 function useCapxulOrgDeployRoles() {
-	const client = useCapxulClient();
+	const client = useCapxulClientOrNull();
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (orgId) => {
-			return unwrapCapxulResult(await client.org(orgId).deployRoles(), client._internal.telemetry, "mutation");
+			const bootstrappedClient = requireBootstrappedClient(client, "org.deployRoles");
+			return unwrapCapxulResult(await bootstrappedClient.org(orgId).deployRoles(), bootstrappedClient._internal.telemetry, "mutation");
 		},
 		onSuccess: async (_roles, orgId) => {
 			await queryClient.invalidateQueries({ queryKey: capxulKeys.orgRoles(orgId) });
@@ -681,65 +464,43 @@ function useCapxulOrgDeployRoles() {
 //#endregion
 //#region src/hooks/use-capxul-org-treasury.ts
 function useCapxulOrgTreasury(orgId, options) {
-	const client = useCapxulClient();
+	const client = useCapxulClientOrNull();
+	const enabled = options?.enabled ?? true;
 	return useQuery({
 		queryKey: capxulKeys.orgTreasury(orgId),
 		queryFn: async () => {
 			if (orgId === void 0) throw Errors.invalidInput("orgId", "required for useCapxulOrgTreasury");
-			return unwrapCapxulResult(await client.org(orgId).treasury(), client._internal.telemetry);
+			const bootstrappedClient = requireBootstrappedClient(client, "org.treasury");
+			return unwrapCapxulResult(await bootstrappedClient.org(orgId).treasury(), bootstrappedClient._internal.telemetry);
 		},
-		enabled: (options?.enabled ?? true) && orgId !== void 0
+		enabled: client !== null && enabled && orgId !== void 0
 	});
 }
 //#endregion
 //#region src/hooks/use-capxul-create-org.ts
 function useCapxulCreateOrg() {
-	const client = useCapxulClient();
+	const client = useCapxulClientOrNull();
 	const queryClient = useQueryClient();
 	return useMutation({
-		mutationFn: async (input) => unwrapCapxulResult(await client.createOrg(input), client._internal.telemetry, "mutation"),
+		mutationFn: async (input) => {
+			const bootstrappedClient = requireBootstrappedClient(client, "createOrg");
+			return unwrapCapxulResult(await bootstrappedClient.createOrg(input), bootstrappedClient._internal.telemetry, "mutation");
+		},
 		onSuccess: async () => {
 			await queryClient.invalidateQueries({ queryKey: capxulKeys.orgs });
 		}
 	});
 }
 //#endregion
-//#region src/hooks/use-capxul-complete-personal-onboarding.ts
-function useCapxulCompletePersonalOnboarding() {
-	const client = useCapxulClient();
-	const queryClient = useQueryClient();
-	return useMutation({
-		mutationFn: async (input) => unwrapCapxulResult(await client.onboarding.completePersonal(input), client._internal.telemetry, "mutation"),
-		onSuccess: async () => {
-			await Promise.all([queryClient.invalidateQueries({ queryKey: capxulKeys.profile }), queryClient.invalidateQueries({ queryKey: capxulKeys.accountLifecycle })]);
-		}
-	});
-}
-//#endregion
-//#region src/hooks/use-capxul-complete-organization-onboarding.ts
-function useCapxulCompleteOrganizationOnboarding() {
-	const client = useCapxulClient();
-	const queryClient = useQueryClient();
-	return useMutation({
-		mutationFn: async (input) => unwrapCapxulResult(await client.onboarding.completeOrganization(input), client._internal.telemetry, "mutation"),
-		onSuccess: async () => {
-			await Promise.all([
-				queryClient.invalidateQueries({ queryKey: capxulKeys.profile }),
-				queryClient.invalidateQueries({ queryKey: capxulKeys.accountLifecycle }),
-				queryClient.invalidateQueries({ queryKey: capxulKeys.orgs })
-			]);
-		}
-	});
-}
-//#endregion
 //#region src/hooks/use-capxul-invite-member.ts
 function useCapxulInviteMember(orgId) {
-	const client = useCapxulClient();
+	const client = useCapxulClientOrNull();
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (input) => {
 			if (orgId === void 0) throw Errors.invalidInput("orgId", "required for useCapxulInviteMember");
-			return unwrapCapxulResult(await client.org(orgId).invite(input), client._internal.telemetry, "mutation");
+			const bootstrappedClient = requireBootstrappedClient(client, "org.invite");
+			return unwrapCapxulResult(await bootstrappedClient.org(orgId).invite(input), bootstrappedClient._internal.telemetry, "mutation");
 		},
 		onSuccess: async () => {
 			if (orgId === void 0) return;
@@ -750,12 +511,13 @@ function useCapxulInviteMember(orgId) {
 //#endregion
 //#region src/hooks/use-capxul-remove-member.ts
 function useCapxulRemoveMember(orgId) {
-	const client = useCapxulClient();
+	const client = useCapxulClientOrNull();
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (input) => {
 			if (orgId === void 0) throw Errors.invalidInput("orgId", "required for useCapxulRemoveMember");
-			return unwrapCapxulResult(await client.org(orgId).removeMember(input), client._internal.telemetry, "mutation");
+			const bootstrappedClient = requireBootstrappedClient(client, "org.removeMember");
+			return unwrapCapxulResult(await bootstrappedClient.org(orgId).removeMember(input), bootstrappedClient._internal.telemetry, "mutation");
 		},
 		onSuccess: async () => {
 			if (orgId === void 0) return;
@@ -766,12 +528,13 @@ function useCapxulRemoveMember(orgId) {
 //#endregion
 //#region src/hooks/use-capxul-assign-role.ts
 function useCapxulAssignRole(orgId) {
-	const client = useCapxulClient();
+	const client = useCapxulClientOrNull();
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (input) => {
 			if (orgId === void 0) throw Errors.invalidInput("orgId", "required for useCapxulAssignRole");
-			return unwrapCapxulResult(await client.org(orgId).assignRole(input), client._internal.telemetry, "mutation");
+			const bootstrappedClient = requireBootstrappedClient(client, "org.assignRole");
+			return unwrapCapxulResult(await bootstrappedClient.org(orgId).assignRole(input), bootstrappedClient._internal.telemetry, "mutation");
 		},
 		onSuccess: async () => {
 			if (orgId === void 0) return;
@@ -780,11 +543,273 @@ function useCapxulAssignRole(orgId) {
 	});
 }
 //#endregion
-//#region src/hooks/use-capxul-switch-acting-entity.ts
-function useCapxulSwitchActingEntity() {
-	return useMutation({ mutationFn: async (_input) => void 0 });
+//#region src/headless/journey/journey-state.ts
+const JOURNEY_KEY = "capxul.onboarding.journey.v1";
+const VALIDATED_OWNER_KEY = "capxul.onboarding.validated-owner.v1";
+const JOURNEY_VERSION = 1;
+const MAX_DRAFT_TEXT_LENGTH = 200;
+const MAX_ID_LENGTH = 160;
+const MAX_STORED_JOURNEY_LENGTH = 8192;
+const MAX_PAYOUT_DRAFT_ENTRIES = 10;
+/**
+* The owner whose stored journey may currently be attributed to observations.
+* Persisted in sessionStorage rather than module memory so `currentOnboarding-
+* JourneyId` is a pure function of durable state — attribution is the same
+* regardless of the order of renders, reloads, or telemetry emits. Established
+* only when an authenticated owner is (journey start, or an owner-matched load)
+* and cleared at every auth boundary or on discard.
+*/
+function markOnboardingOwnerValidated(ownerId) {
+	try {
+		sessionStorage.setItem(VALIDATED_OWNER_KEY, ownerId);
+	} catch {}
+}
+function clearValidatedOnboardingOwner() {
+	try {
+		sessionStorage.removeItem(VALIDATED_OWNER_KEY);
+	} catch {}
+}
+function validatedOnboardingOwner() {
+	try {
+		return sessionStorage.getItem(VALIDATED_OWNER_KEY);
+	} catch {
+		return null;
+	}
+}
+function startOnboardingJourney(input) {
+	const journey = {
+		version: JOURNEY_VERSION,
+		ownerId: input.ownerId,
+		journeyId: `journey_${createRandomId()}`,
+		intent: input.intent,
+		entryPoint: input.entryPoint,
+		step: input.step ?? "profile",
+		...input.origin === void 0 ? {} : { origin: input.origin }
+	};
+	markOnboardingOwnerValidated(journey.ownerId);
+	saveOnboardingJourney(journey);
+	return journey;
+}
+function loadOnboardingJourney(expectedOwnerId) {
+	try {
+		const raw = sessionStorage.getItem(JOURNEY_KEY);
+		if (raw === null) return null;
+		if (raw.length > MAX_STORED_JOURNEY_LENGTH) return discardInvalidJourney();
+		const value = JSON.parse(raw);
+		if (!isValidJourney(value)) return discardInvalidJourney();
+		if (expectedOwnerId !== void 0 && value.ownerId !== expectedOwnerId) return discardInvalidJourney();
+		if (expectedOwnerId !== void 0) markOnboardingOwnerValidated(expectedOwnerId);
+		return value;
+	} catch {
+		return discardInvalidJourney();
+	}
+}
+function saveOnboardingJourney(journey) {
+	if (!isValidJourney(journey)) {
+		discardInvalidJourney();
+		return;
+	}
+	try {
+		sessionStorage.setItem(JOURNEY_KEY, JSON.stringify(journey));
+	} catch {}
+}
+function currentOnboardingJourneyId() {
+	const journey = loadOnboardingJourney();
+	const owner = validatedOnboardingOwner();
+	return journey !== null && owner !== null && journey.ownerId === owner ? journey.journeyId : void 0;
+}
+/** Stop observation attribution while no authenticated owner is established. */
+function invalidateOnboardingJourneyObservation() {
+	clearValidatedOnboardingOwner();
+}
+/** Where the journey stands — the pure position apps map to their routes. */
+function onboardingJourneyPosition(journey) {
+	const proof = journey.origin?.kind === "proof";
+	if (journey.organizationId !== void 0) return {
+		intent: journey.intent,
+		step: "provisioning",
+		organizationId: journey.organizationId,
+		proof
+	};
+	return {
+		intent: journey.intent,
+		step: journey.step,
+		proof
+	};
+}
+/**
+* The interruption-recovery decision (behavior map §4): a journey that does
+* not match the ready destination the app just rendered must resume; a
+* matching one needs no recovery. Returns the journey to resume, or null.
+*/
+function activeOnboardingRecovery(ownerId, renderedReadyDestination) {
+	const journey = loadOnboardingJourney(ownerId);
+	if (journey === null) return null;
+	return (renderedReadyDestination?.kind === "personal" ? journey.intent === "personal" && journey.step === "provisioning" && journey.organizationId === void 0 : renderedReadyDestination?.kind === "organization" && journey.intent === "organization" && journey.step === "provisioning" && journey.organizationId === renderedReadyDestination.organizationId) ? null : journey;
+}
+function acknowledgeOnboardingDestination(destination, ownerId) {
+	const journey = loadOnboardingJourney(ownerId);
+	if (journey === null) return false;
+	if (!(destination.kind === "personal" ? journey.intent === "personal" && journey.step === "provisioning" : journey.intent === "organization" && journey.step === "provisioning" && journey.organizationId === destination.organizationId)) return false;
+	clearOnboardingJourney();
+	return true;
+}
+function clearOnboardingJourney() {
+	clearValidatedOnboardingOwner();
+	try {
+		sessionStorage.removeItem(JOURNEY_KEY);
+	} catch {}
+}
+function isValidJourney(value) {
+	if (!isRecord(value) || value.version !== JOURNEY_VERSION) return false;
+	if (!hasOnlyKeys(value, [
+		"version",
+		"ownerId",
+		"journeyId",
+		"intent",
+		"entryPoint",
+		"origin",
+		"step",
+		"profile",
+		"organization",
+		"stableHandle",
+		"organizationId"
+	])) return false;
+	if (!isBoundedId(value.ownerId)) return false;
+	if (!isBoundedId(value.journeyId) || !value.journeyId.startsWith("journey_")) return false;
+	if (value.intent !== "personal" && value.intent !== "organization") return false;
+	if (value.entryPoint !== "signup" && value.entryPoint !== "dashboard") return false;
+	if (value.step !== "profile" && value.step !== "organization" && value.step !== "provisioning") return false;
+	if (value.origin !== void 0 && !isOrigin(value.origin)) return false;
+	if (value.profile !== void 0 && !isProfileDraft(value.profile)) return false;
+	if (value.organization !== void 0 && !isOrganizationDraft(value.organization)) return false;
+	if (value.stableHandle !== void 0 && !isDraftText(value.stableHandle)) return false;
+	if (value.organizationId !== void 0 && !isBoundedId(value.organizationId)) return false;
+	if (value.organization !== void 0 && value.stableHandle !== value.organization.handle) return false;
+	if (value.stableHandle !== void 0 && value.organization === void 0) return false;
+	if (value.intent === "personal" && (value.step === "organization" || value.organization !== void 0 || value.stableHandle !== void 0)) return false;
+	if (value.step === "organization" && value.intent !== "organization") return false;
+	if (value.organizationId !== void 0 && value.intent !== "organization") return false;
+	if (value.organizationId !== void 0 && value.step !== "provisioning") return false;
+	return true;
+}
+function isOrigin(value) {
+	if (!isRecord(value)) return false;
+	if (value.kind === "personal") return hasOnlyKeys(value, ["kind"]);
+	if (value.kind === "organization") return hasOnlyKeys(value, ["kind", "organizationId"]) && isBoundedId(value.organizationId);
+	return value.kind === "proof" && hasOnlyKeys(value, ["kind", "organizationId"]) && (value.organizationId === void 0 || isBoundedId(value.organizationId));
+}
+function isProfileDraft(value) {
+	if (!isRecord(value) || !hasOnlyKeys(value, [
+		"displayName",
+		"country",
+		"withdrawalAddress",
+		"username",
+		"payoutAddresses"
+	]) || !isDraftText(value.displayName) || !isDraftText(value.country) || !isDraftText(value.withdrawalAddress)) return false;
+	if (value.username !== void 0 && !isDraftText(value.username)) return false;
+	if (value.payoutAddresses !== void 0 && !isPayoutDraftList(value.payoutAddresses)) return false;
+	return true;
+}
+function isPayoutDraftList(value) {
+	return Array.isArray(value) && value.length <= MAX_PAYOUT_DRAFT_ENTRIES && value.every((entry) => isRecord(entry) && hasOnlyKeys(entry, ["chain", "address"]) && (entry.chain === "evm" || entry.chain === "solana" || entry.chain === "starknet") && isDraftText(entry.address));
+}
+function isOrganizationDraft(value) {
+	if (!isRecord(value) || !hasOnlyKeys(value, [
+		"name",
+		"handle",
+		"country",
+		"bio",
+		"size"
+	]) || !isDraftText(value.name) || !isDraftText(value.handle) || !isDraftText(value.country)) return false;
+	if (value.bio !== void 0 && !isDraftText(value.bio)) return false;
+	if (value.size !== void 0 && !isDraftText(value.size)) return false;
+	return true;
+}
+function isDraftText(value) {
+	return typeof value === "string" && value.length <= MAX_DRAFT_TEXT_LENGTH;
+}
+function isBoundedId(value) {
+	return typeof value === "string" && value.length > 0 && value.length <= MAX_ID_LENGTH;
+}
+function discardInvalidJourney() {
+	clearValidatedOnboardingOwner();
+	try {
+		sessionStorage.removeItem(JOURNEY_KEY);
+	} catch {}
+	return null;
+}
+function createRandomId() {
+	if (typeof globalThis.crypto?.randomUUID === "function") return globalThis.crypto.randomUUID();
+	return Math.random().toString(36).slice(2);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOnlyKeys(value, allowed) {
+	return Object.keys(value).every((key) => allowed.includes(key));
+}
+//#endregion
+//#region src/internal/use-debounced-value.ts
+/** The value as of `delayMs` after its last change (initial value immediate). */
+function useDebouncedValue(value, delayMs) {
+	const [debounced, setDebounced] = useState(value);
+	useEffect(() => {
+		const timer = setTimeout(() => setDebounced(value), delayMs);
+		return () => clearTimeout(timer);
+	}, [value, delayMs]);
+	return debounced;
+}
+//#endregion
+//#region src/headless/onboarding/use-capxul-username-availability.ts
+/**
+* #1062: debounced availability probe for the username the user is typing.
+* Disabled until the candidate reaches the 3-character floor; a malformed or
+* reserved candidate surfaces as the query's error (INVALID_INPUT with the
+* boundary's message), not as `available: false` — only a username someone
+* else owns is "taken".
+*/
+function useCapxulUsernameAvailability(username, options) {
+	const client = useCapxulClientOrNull();
+	const candidate = useDebouncedValue(username.trim(), options?.debounceMs ?? 300);
+	return useQuery({
+		queryKey: capxulKeys.usernameAvailability(candidate),
+		queryFn: async () => {
+			const bootstrappedClient = requireBootstrappedClient(client, "identity.usernameAvailable");
+			return unwrapCapxulResult(await bootstrappedClient.identity.usernameAvailable(candidate), bootstrappedClient._internal.telemetry);
+		},
+		enabled: client !== null && candidate.length >= 3 && (options?.enabled ?? true)
+	});
+}
+//#endregion
+//#region src/headless/media/use-capxul-image-upload.ts
+/**
+* #1061 / ADR-0014: the whole upload→record sequence as one mutation —
+* upload the blob, then bind the returned storage id to the profile image or
+* the org logo. The url is the resolved serving URL (re-read from queries,
+* never persisted by consumers).
+*/
+function useCapxulImageUpload() {
+	const client = useCapxulClientOrNull();
+	const queryClient = useQueryClient();
+	return useMutation({
+		mutationFn: async ({ blob, target }) => {
+			const bootstrappedClient = requireBootstrappedClient(client, "media.uploadImage");
+			const media = bootstrappedClient.media;
+			const telemetry = bootstrappedClient._internal.telemetry;
+			const uploaded = unwrapCapxulResult(await media.uploadImage(blob), telemetry);
+			if (target.kind === "profile") return { url: unwrapCapxulResult(await media.setProfileImage({ storageId: uploaded.storageId }), telemetry).imageUrl };
+			return { url: unwrapCapxulResult(await media.setOrgLogo({
+				orgId: target.orgId,
+				storageId: uploaded.storageId
+			}), telemetry).logoUrl };
+		},
+		onSuccess: async (_value, input) => {
+			await queryClient.invalidateQueries({ queryKey: input.target.kind === "profile" ? capxulKeys.profile : capxulKeys.orgs });
+		}
+	});
 }
 //#endregion
-export { CapxulProvider, useCapxul, useCapxulAccountBalance, useCapxulAccountFund, useCapxulAccountLifecycle, useCapxulAssignRole, useCapxulClientOrNull, useCapxulCompleteOrganizationOnboarding, useCapxulCompletePersonalOnboarding, useCapxulCreateOrg, useCapxulInviteMember, useCapxulOrg, useCapxulOrgDeployRoles, useCapxulOrgMembers, useCapxulOrgRoles, useCapxulOrgTreasury, useCapxulOrgs, useCapxulProfile, useCapxulRemoveMember, useCapxulSession, useCapxulSignIn, useCapxulSignOut, useCapxulSubAccountCreate, useCapxulSubAccountDelete, useCapxulSubAccountRename, useCapxulSubAccountsList, useCapxulSwitchActingEntity, useCapxulTransfer, useCapxulVerifyOtp };
+export { CapxulAuthenticationController, CapxulOnboardingController, CapxulProvider, acknowledgeOnboardingDestination, activeOnboardingRecovery, clearOnboardingJourney, currentOnboardingJourneyId, entered, invalidateOnboardingJourneyObservation, loadOnboardingJourney, onboardingJourneyPosition, saveOnboardingJourney, startOnboardingJourney, useCapxul, useCapxulAccountBalance, useCapxulAccountFund, useCapxulAssignRole, useCapxulAuth, useCapxulClientOrNull, useCapxulCreateOrg, useCapxulDestination, useCapxulIdentity, useCapxulImageUpload, useCapxulInviteMember, useCapxulOrgDeployRoles, useCapxulOrgMembers, useCapxulOrgRoles, useCapxulOrgTreasury, useCapxulOrgs, useCapxulPay, useCapxulPayment, useCapxulPayments, useCapxulPayout, useCapxulProfile, useCapxulRemoveMember, useCapxulSend, useCapxulSubAccountCreate, useCapxulSubAccountDelete, useCapxulSubAccountRename, useCapxulSubAccountsList, useCapxulTransfer, useCapxulTransitions, useCapxulUsernameAvailability, useCapxulWithdraw };
 
 //# sourceMappingURL=index.mjs.map