@capxul/sdk-react 0.0.0-rc-2cdddbb91

package/dist/onboarding-controller-DWuvVuC8.mjs

@@ -0,0 +1,1108 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { QueryClient, QueryClientProvider, useQueryClient } from "@tanstack/react-query";
+import { CapxulError, createCapxulClient, isCapxulError, resolveIdentityDestination, toCountryCode, toHandle, toOrgId } from "@capxul/sdk";
+import { jsx } from "react/jsx-runtime";
+//#region src/platform/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/platform/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
+	});
+}
+/**
+* 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/platform/query-keys.ts
+/**
+* An Organization id a consumer passed as a plain string (often a URL
+* parameter), as a key segment. An absent or empty id names no Organization.
+*/
+function orgKeySegment(orgId) {
+	return orgId === void 0 || orgId === "" ? void 0 : toOrgId(orgId);
+}
+/**
+* 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"],
+	handleAvailability: (handle) => [
+		"capxul",
+		"profile",
+		"handle-availability",
+		handle
+	],
+	account: ["capxul", "account"],
+	provisioning: ["capxul", "provisioning"],
+	binding: ["capxul", "binding"],
+	accountBalance: ["capxul", "accountBalance"],
+	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"
+	],
+	orgPermissions: (orgId) => [
+		"capxul",
+		"org",
+		orgId ?? "pending",
+		"permissions"
+	],
+	orgMe: (orgId, account) => [
+		"capxul",
+		"org",
+		orgId ?? "pending",
+		"me",
+		account ?? "pending"
+	],
+	orgLifecycle: (orgId) => [
+		"capxul",
+		"org",
+		orgId ?? "pending",
+		"lifecycle"
+	],
+	contacts: (scope) => [
+		"capxul",
+		"contacts",
+		scope
+	],
+	contactsList: (scope, includeHidden) => [
+		"capxul",
+		"contacts",
+		scope,
+		includeHidden ? "all" : "visible"
+	],
+	payrollRuns: (orgId) => [
+		"capxul",
+		"org",
+		orgId ?? "pending",
+		"payroll",
+		"runs"
+	],
+	payrollGroups: (orgId) => [
+		"capxul",
+		"org",
+		orgId ?? "pending",
+		"payroll",
+		"groups"
+	],
+	payrollTerms: (orgId) => [
+		"capxul",
+		"org",
+		orgId ?? "pending",
+		"payroll",
+		"terms"
+	],
+	activity: ["capxul", "activity"],
+	activityDetail: (reference, actor) => [
+		"capxul",
+		"activity",
+		actor ?? "self",
+		reference ?? "pending"
+	],
+	activitySummary: (actor, window) => [
+		"capxul",
+		"activity",
+		"summary",
+		actor ?? "self",
+		window ?? "all"
+	],
+	holdings: (actor) => [
+		"capxul",
+		"holdings",
+		actor ?? "self"
+	],
+	payments: ["capxul", "payments"],
+	payment: (paymentId) => [
+		"capxul",
+		"payments",
+		paymentId ?? "pending"
+	]
+};
+//#endregion
+//#region src/platform/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 },
+		...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs },
+		...options.deadlineMs === void 0 ? {} : { deadlineMs: options.deadlineMs },
+		...options.correlationId === void 0 ? {} : { correlation_id: options.correlationId },
+		...options.journeyId === void 0 ? {} : { journey_id: options.journeyId }
+	};
+}
+//#endregion
+//#region src/platform/identity-lanes.ts
+const failure = (result) => result.ok ? null : {
+	ok: false,
+	reason: result.refused
+};
+/** 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");
+/**
+* The session slot keeps the latest ReadSession only: a second reader
+* interrupts the first and the machine refuses the first with SUPERSEDED.
+* Two onboarding callers read at once after a reload (the controller's
+* resume and the recovery submit), so the loser must wait for the winner's
+* read to land and then continue on the shared state, not fail.
+*/
+function settledSession(runtime, invocation) {
+	return 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",
+			error: new CapxulError("UNKNOWN", "The session did not settle in time.", {
+				mode: "timeout",
+				layer: "identity",
+				details: { limitMs: SESSION_SETTLE_LIMIT_MS }
+			})
+		}), SESSION_SETTLE_LIMIT_MS);
+	});
+}
+/** Read the session; a superseded read waits for the winning one. */
+async function readSession(runtime, invocation) {
+	const result = await runtime.send({ _tag: "ReadSession" }, invocation);
+	const refused = failure(result);
+	if (refused === null) return { ok: true };
+	return refused.reason === "SUPERSEDED" ? settledSession(runtime, invocation) : refused;
+}
+/**
+* The account lane accepts no account event while a derivation or claim is
+* landing. A person who submits the Organization before their own Safe claim
+* settles must wait for it, not be refused with WRONG_STATE.
+*/
+function settledAccount(runtime, invocation) {
+	return 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 });
+	});
+}
+/** Drive the person's own Account to claimed, waiting out a landing derivation or claim. */
+async function reachClaimed(runtime, invocation) {
+	let state = runtime.snapshot();
+	if (accountInFlight(state)) {
+		const settled = await settledAccount(runtime, 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);
+		if (refused !== null) return refused;
+		state = result.state;
+	}
+	if (state.phase !== "authenticated") return {
+		ok: false,
+		reason: "WRONG_STATE"
+	};
+	if (state.account.at === "claimed") return { ok: true };
+	if (accountInFlight(state)) {
+		const settled = await settledAccount(runtime, 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);
+	if (refused !== null) return refused;
+	const next = result.state;
+	return next.phase === "authenticated" && next.account.at === "claimed" ? { ok: true } : {
+		ok: false,
+		reason: "WRONG_STATE"
+	};
+}
+//#endregion
+//#region src/platform/organization-submission.ts
+function organizationFailure(reason, state) {
+	const stateFailure = state.phase === "faulted" ? state.failure : state.phase === "authenticated" && state.account.at === "failed" ? state.account.failure : state.phase === "authenticated" && state.account.at === "claimed" ? state.account.org?.failure : void 0;
+	if (stateFailure?.code === reason) return {
+		ok: false,
+		reason,
+		error: stateFailure.error ?? new CapxulError(stateFailure.code === "WORK_DIED" ? "UNKNOWN" : stateFailure.code, stateFailure.message, {
+			...stateFailure.mode === void 0 ? {} : { details: { failure_mode: stateFailure.mode } },
+			layer: "identity"
+		})
+	};
+	return {
+		ok: false,
+		reason,
+		error: new CapxulError(reason === "WORK_DIED" ? "UNKNOWN" : reason, reason === "INVALID_INPUT" ? "Organization details are invalid." : "Organization creation failed.", { layer: "identity" })
+	};
+}
+function normalizeOrganization(organization) {
+	const name = typeof organization.name === "string" ? organization.name.trim() : "";
+	const handle = typeof organization.handle === "string" ? organization.handle.trim().toLowerCase() : "";
+	if (name.length === 0) return null;
+	if (organization.bio !== void 0 && typeof organization.bio !== "string") return null;
+	if (organization.size !== void 0 && typeof organization.size !== "string") return null;
+	if (organization.logoStorageId !== void 0 && (typeof organization.logoStorageId !== "string" || organization.logoStorageId.length === 0)) return null;
+	try {
+		return {
+			name,
+			handle: toHandle(handle),
+			country: toCountryCode(organization.country),
+			...organization.bio === void 0 ? {} : { bio: organization.bio },
+			...organization.size === void 0 ? {} : { size: organization.size },
+			...organization.logoStorageId === void 0 ? {} : { logoStorageId: organization.logoStorageId }
+		};
+	} catch {
+		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;
+	return state.account.org?.orgId ?? null;
+};
+//#endregion
+//#region src/platform/identity-auth.ts
+async function guarded(runtime, verb, options, run) {
+	const invocation = toInvocationControls(options);
+	try {
+		return await (runtime.runFacade?.(verb, invocation, run) ?? run(invocation));
+	} catch (cause) {
+		const error = isCapxulError(cause) ? cause : new CapxulError("UNKNOWN", "The identity request failed unexpectedly.", {
+			cause,
+			layer: "identity"
+		});
+		return {
+			ok: false,
+			reason: error.code,
+			error
+		};
+	}
+}
+/** The auth verbs behind `useCapxulAuth`, each run as one guarded facade call. */
+function createAuth(client, clearAuthenticatedQueries) {
+	const runtime = client._internal.identity;
+	const completeProfile = async (profile, invocation) => {
+		const result = await runtime.completeProfile(profile, invocation);
+		return result.ok ? { ok: true } : result;
+	};
+	const prepareOrganization = async (submission, invocation) => {
+		const organization = normalizeOrganization(submission.organization);
+		if (organization === null) return {
+			ok: false,
+			reason: "INVALID_INPUT"
+		};
+		const refreshed = await readSession(runtime, 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 claimed = await reachClaimed(runtime, invocation);
+		return claimed.ok ? {
+			ok: true,
+			organization
+		} : claimed;
+	};
+	return {
+		requestCode: (email, options) => guarded(runtime, "requestCode", options, async (invocation) => {
+			const result = await client.auth.signIn({ email }, invocation);
+			if (!result.ok) return {
+				ok: false,
+				reason: result.error.code
+			};
+			const state = runtime.snapshot();
+			return state.phase === "otp_pending" ? {
+				ok: true,
+				requestedAt: state.requestedAt
+			} : {
+				ok: false,
+				reason: state.phase === "faulted" ? state.failure.code : "UNKNOWN"
+			};
+		}),
+		verifyCode: (otp, options) => guarded(runtime, "verifyCode", options, async (invocation) => {
+			const state = runtime.snapshot();
+			const email = state.phase === "otp_pending" ? state.email : state.phase === "faulted" && state.resume !== null ? state.resume.email : "";
+			if (!/^\d{6}$/.test(otp)) {
+				const refused = await runtime.send({
+					_tag: "VerifyOtp",
+					email,
+					otp,
+					now: Date.now()
+				}, invocation);
+				return failure(refused) ?? {
+					ok: false,
+					reason: "UNKNOWN"
+				};
+			}
+			const result = await client.auth.verifyOtp({
+				email,
+				code: otp
+			}, invocation);
+			if (!result.ok) return {
+				ok: false,
+				reason: result.error.code
+			};
+			const next = runtime.snapshot();
+			return next.phase === "authenticated" ? {
+				ok: true,
+				authUserId: next.session.authUserId,
+				profileComplete: next.profileComplete
+			} : {
+				ok: false,
+				reason: next.phase === "faulted" ? next.failure.code : "UNKNOWN"
+			};
+		}),
+		signOut: (options) => guarded(runtime, "signOut", options, async (invocation) => {
+			const result = await client.auth.signOut(invocation);
+			if (!result.ok) return {
+				ok: false,
+				reason: result.error.code
+			};
+			await clearAuthenticatedQueries();
+			return { ok: true };
+		}),
+		completePersonal: (profile, options) => guarded(runtime, "completePersonal", options, async (invocation) => {
+			const completed = await completeProfile(profile, invocation);
+			if (!completed.ok) return {
+				ok: false,
+				reason: completed.reason
+			};
+			const refreshed = await readSession(runtime, invocation);
+			if (!refreshed.ok) return refreshed;
+			return failure(await runtime.send({ _tag: "EnsureAccount" }, invocation)) ?? { ok: true };
+		}),
+		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
+			};
+			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 begun = await client.onboarding.beginOrganization(prepared.organization, invocation);
+			if (!begun.ok) return {
+				ok: false,
+				reason: begun.error.code,
+				error: begun.error
+			};
+			const { orgId, setup } = begun.value;
+			if (setup.status === "awaitingAuthorization") {
+				const authorized = await client.org(orgId).setup.authorize(invocation);
+				if (!authorized.ok) return {
+					ok: false,
+					reason: authorized.error.code,
+					error: authorized.error
+				};
+			}
+			return {
+				ok: true,
+				orgId: String(orgId)
+			};
+		}).then((result) => {
+			if (result.ok) return result;
+			if ("error" in result && result.error instanceof CapxulError) return {
+				ok: false,
+				reason: result.reason,
+				error: result.error
+			};
+			return organizationFailure(result.reason, runtime.snapshot());
+		}),
+		retry: (options) => guarded(runtime, "retry", options, async (invocation) => {
+			const state = runtime.snapshot();
+			const orgId = runningOrganization(state);
+			if (orgId !== null) {
+				const scoped = client.org(toOrgId(orgId));
+				const current = await scoped.setup.get(invocation);
+				if (!current.ok) return {
+					ok: false,
+					reason: current.error.code
+				};
+				const result = current.value.status === "awaitingAuthorization" ? await scoped.setup.authorize(invocation) : await scoped.setup.resume(invocation);
+				return result.ok ? { ok: true } : {
+					ok: false,
+					reason: result.error.code
+				};
+			}
+			const result = await runtime.send({ _tag: "RetryAccount" }, invocation);
+			return failure(result) ?? { ok: true };
+		}),
+		resumeSubmittedOrganization: (submission, options) => guarded(runtime, "createOrganization", options, async (invocation) => {
+			const prepared = await prepareOrganization(submission, invocation);
+			return prepared.ok ? { ok: true } : {
+				ok: false,
+				reason: prepared.reason
+			};
+		})
+	};
+}
+//#endregion
+//#region src/platform/identity.tsx
+const MISSING_IDENTITY_PROVIDER = Symbol("MISSING_IDENTITY_PROVIDER");
+const IdentityContext = createContext(MISSING_IDENTITY_PROVIDER);
+function CapxulIdentityProvider({ client, children }) {
+	const queryClient = useQueryClient();
+	const runtime = client?._internal.identity ?? null;
+	const listeners = useRef(/* @__PURE__ */ new Set());
+	useEffect(() => {
+		if (client === null || runtime === null) return;
+		const controller = new AbortController();
+		let active = true;
+		Promise.resolve().then(async () => {
+			const restored = await client.auth.getSession({ signal: controller.signal });
+			if (!active || !restored.ok) return;
+			let state = runtime.snapshot();
+			if (state.phase === "authenticated" && state.account.at === "unknown") {
+				await runtime.send({ _tag: "ReadSession" }, { signal: controller.signal });
+				if (!active) return;
+				state = runtime.snapshot();
+			}
+			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;
+			controller.abort();
+		};
+	}, [client, runtime]);
+	useEffect(() => {
+		if (runtime === null) return;
+		let previousAccount = actingAccount(runtime.snapshot());
+		return runtime.subscribeTransitions((record) => {
+			const state = runtime.snapshot();
+			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:organization")) queryClient.invalidateQueries({
+				queryKey: capxulKeys.root,
+				...accountChanged ? { refetchType: "none" } : {}
+			});
+			for (const listener of listeners.current) try {
+				listener(record, state);
+			} catch {
+				listeners.current.delete(listener);
+			}
+		});
+	}, [queryClient, runtime]);
+	const addTransitionListener = useCallback((listener) => {
+		listeners.current.add(listener);
+		return () => listeners.current.delete(listener);
+	}, []);
+	const value = useMemo(() => {
+		if (client === null || runtime === null) return null;
+		const send = (event, options) => runtime.send(event, toInvocationControls(options));
+		const clearAuthenticatedQueries = async () => {
+			await queryClient.cancelQueries({ queryKey: capxulKeys.root });
+			await queryClient.resetQueries({ queryKey: capxulKeys.root });
+		};
+		const auth = createAuth(client, clearAuthenticatedQueries);
+		return {
+			runtime,
+			send,
+			auth,
+			resumeSubmittedOrganization: auth.resumeSubmittedOrganization,
+			addTransitionListener
+		};
+	}, [
+		client,
+		runtime,
+		addTransitionListener,
+		queryClient
+	]);
+	return /* @__PURE__ */ jsx(IdentityContext.Provider, {
+		value,
+		children
+	});
+}
+function useIdentityContext() {
+	const value = useContext(IdentityContext);
+	if (value === MISSING_IDENTITY_PROVIDER) throw new Error("identity hooks must be used within <CapxulProvider>");
+	if (value === null) throw new Error("identity hooks require a ready <CapxulProvider>");
+	return value;
+}
+const noSubscribe = () => () => void 0;
+const noState = () => null;
+function useCapxulIdentityOrNull() {
+	const value = useContext(IdentityContext);
+	if (value === MISSING_IDENTITY_PROVIDER) throw new Error("identity hooks must be used within <CapxulProvider>");
+	return useSyncExternalStore(value?.runtime.subscribe ?? noSubscribe, value?.runtime.snapshot ?? noState, value?.runtime.snapshot ?? noState);
+}
+function useCapxulIdentity() {
+	const state = useCapxulIdentityOrNull();
+	if (state === null) throw new Error("identity hooks require a ready <CapxulProvider>");
+	return state;
+}
+function useCapxulSend() {
+	return useIdentityContext().send;
+}
+function useCapxulAuth() {
+	return useIdentityContext().auth;
+}
+function useResumeSubmittedOrganization() {
+	return useIdentityContext().resumeSubmittedOrganization;
+}
+function useCapxulDestination() {
+	const state = useCapxulIdentity();
+	const next = resolveIdentityDestination(state);
+	const held = useRef(null);
+	const key = JSON.stringify(next);
+	if (held.current?.key !== key) held.current = {
+		key,
+		value: next
+	};
+	return held.current.value;
+}
+function useCapxulTransitions(listener) {
+	const { addTransitionListener } = useIdentityContext();
+	useEffect(() => addTransitionListener(listener), [addTransitionListener, listener]);
+}
+const entered = (record, target) => record.outcome === "applied" && record.from !== target && record.to === target;
+//#endregion
+//#region src/platform/provider.tsx
+/**
+* Transient failure codes worth a retry — network blips, rate limits, and
+* upstream provider/unknown hiccups that a later attempt may clear. Everything
+* else (including any future code) is deterministic and NOT retried: retrying a
+* deterministic failure only multiplies the failed backend actions. A fresh
+* user with no Safe yet hits `SMART_ACCOUNT_MISSING` on every attempt, so the
+* old blanket `retry: 2` tripled that (and every other deterministic) failed
+* action for zero benefit (#1031).
+*/
+const RETRYABLE_QUERY_ERROR_CODES = /* @__PURE__ */ new Set([
+	"NETWORK_ERROR",
+	"RATE_LIMITED",
+	"PROVIDER_ERROR",
+	"UNKNOWN"
+]);
+/** Matches the previous `retry: 2` budget (initial attempt + up to 2 retries). */
+const MAX_CAPXUL_QUERY_RETRIES = 2;
+/**
+* TanStack `retry` predicate: `failureCount` is 0-indexed and checked before
+* increment, so `< MAX` reproduces the old numeric budget for retryable codes.
+* Exported for direct unit coverage of the deterministic-vs-transient split.
+*/
+function shouldRetryCapxulQuery(failureCount, error) {
+	if (failureCount >= MAX_CAPXUL_QUERY_RETRIES) return false;
+	if (!isCapxulError(error)) return false;
+	if (error.chain !== void 0) return error.chain.retryable;
+	return RETRYABLE_QUERY_ERROR_CODES.has(error.code);
+}
+/**
+* The default query client used when the host injects none. Exported so a test
+* can pin that `queries.retry` is wired to `shouldRetryCapxulQuery` — reverting
+* it to the old blanket `retry: 2` must fail a test (#1031).
+*/
+function makeDefaultQueryClient() {
+	return new QueryClient({ defaultOptions: {
+		queries: {
+			retry: shouldRetryCapxulQuery,
+			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, 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);
+	const retry = useCallback(() => {
+		setAttempt((n) => n + 1);
+	}, []);
+	const bootstrapInput = useMemo(() => publishableKey === void 0 ? null : {
+		publishableKey,
+		...requirement === void 0 ? {} : { requirement },
+		...signer === void 0 ? {} : { signer },
+		...observability === void 0 ? {} : { observability },
+		...bootstrapBaseUrl === void 0 ? {} : { bootstrapBaseUrl },
+		...accountSetup === void 0 ? {} : { accountSetup }
+	}, [
+		publishableKey,
+		requirement,
+		signer,
+		observability,
+		bootstrapBaseUrl,
+		accountSetup,
+		attempt
+	]);
+	const [ownedBootstrap, setOwnedBootstrap] = useState(null);
+	const activeOwnedBootstrap = bootstrapInput !== null && ownedBootstrap?.input === bootstrapInput ? ownedBootstrap : null;
+	const client = injectedClient ?? activeOwnedBootstrap?.client ?? null;
+	const previousClientRef = useRef(injectedClient ?? null);
+	useEffect(() => {
+		if (bootstrapInput === null) return;
+		let cancelled = false;
+		let created = null;
+		setOwnedBootstrap({
+			input: bootstrapInput,
+			client: null,
+			status: "bootstrapping",
+			error: null
+		});
+		(async () => {
+			const result = await createCapxulClient(bootstrapInput);
+			if (cancelled) {
+				if (result.ok) await result.value._internal.close?.();
+				return;
+			}
+			if (result.ok) {
+				created = result.value;
+				setOwnedBootstrap({
+					input: bootstrapInput,
+					client: result.value,
+					status: "ready",
+					error: null
+				});
+			} else setOwnedBootstrap({
+				input: bootstrapInput,
+				client: null,
+				status: "error",
+				error: result.error
+			});
+		})();
+		return () => {
+			cancelled = true;
+			created?._internal.close?.();
+		};
+	}, [bootstrapInput]);
+	useEffect(() => {
+		const previous = previousClientRef.current;
+		if (previous !== null && previous !== client) clearClientScopedQueries(resolvedQueryClient, ownsQueryClient);
+		previousClientRef.current = client;
+	}, [
+		client,
+		ownsQueryClient,
+		resolvedQueryClient
+	]);
+	const bootstrapState = useMemo(() => ({
+		status: injectedClient === void 0 ? activeOwnedBootstrap?.status ?? "bootstrapping" : "ready",
+		error: injectedClient === void 0 ? activeOwnedBootstrap?.error ?? null : null,
+		retry
+	}), [
+		activeOwnedBootstrap,
+		injectedClient,
+		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: /* @__PURE__ */ jsx(CapxulIdentityProvider, {
+					client,
+					children
+				})
+			})
+		})
+	});
+}
+//#endregion
+//#region ../protocol/src/errors/failure-modes.ts
+/**
+* Why an operation failed — the one flat vocabulary. The first four are the
+* auth/provider diagnoses that predate this file. The rest name the chain
+* path. `FailureMode` is derived from this list so a runtime membership check
+* (the SDK's `$exception` projection, the observability schema) and the type
+* can never drift apart.
+*/
+const FAILURE_MODES = [
+	"auth-origin-mismatch",
+	"stale-openfort-cache",
+	"app-env-allowlist",
+	"no-secure-context",
+	"signer-not-ready",
+	"rate-limited",
+	"timeout",
+	"upstream-down",
+	"revert",
+	"insufficient-balance",
+	"insufficient-allowance",
+	"rejected",
+	"unauthorized",
+	"forbidden",
+	"bad-request",
+	"method-unsupported",
+	"unknown"
+];
+function isFailureMode(value) {
+	return typeof value === "string" && FAILURE_MODES.includes(value);
+}
+//#endregion
+//#region ../protocol/src/errors/model.ts
+/**
+* `Code` narrows to the literal a factory passes, so `Errors.invalidInput(...)`
+* is a `CapxulError<"INVALID_INPUT">`. An operation's error channel is then the
+* union of the codes it can actually produce.
+*/
+var CapxulError$1 = class extends Error {
+	code;
+	details;
+	correlationId;
+	layer;
+	/** The one-word cause (`FailureMode`). `chain.mode` when a chain cause is set. */
+	mode;
+	/** The structured chain-path cause. Never rewritten by a later layer. */
+	chain;
+	constructor(code, message, options = {}) {
+		super(message, "cause" in options ? { cause: options.cause } : void 0);
+		this.name = "CapxulError";
+		this.code = code;
+		if (options.details !== void 0) this.details = options.details;
+		if (options.correlationId !== void 0) this.correlationId = options.correlationId;
+		if (options.layer !== void 0) this.layer = options.layer;
+		const legacy = options.details?.failure_mode;
+		const mode = options.chain?.mode ?? (isFailureMode(options.mode) ? options.mode : void 0) ?? (isFailureMode(legacy) ? legacy : void 0);
+		if (mode !== void 0) this.mode = mode;
+		if (options.chain !== void 0) this.chain = options.chain;
+	}
+};
+//#endregion
+//#region ../protocol/src/primitives/absurd.ts
+/**
+* The default branch of an exhaustive switch: `default: return absurd(value)`.
+* The compiler proves it unreachable; if a value the types rule out arrives at
+* run time anyway, it fails as a named defect instead of falling through.
+*/
+function absurd(value) {
+	throw new CapxulError$1("UNKNOWN", "An exhaustive switch received a value its type rules out.", { details: {
+		defect: "unreachable_case",
+		value: String(value)
+	} });
+}
+//#endregion
+//#region src/access/controllers.tsx
+const action = async (send, event) => {
+	const result = await send(event);
+	return result.ok ? { ok: true } : {
+		ok: false,
+		reason: result.refused
+	};
+};
+function CapxulAuthenticationController({ slots }) {
+	const state = useCapxulIdentity();
+	const destination = useCapxulDestination();
+	const auth = useCapxulAuth();
+	const send = useCapxulSend();
+	switch (state.phase) {
+		case "signed_out": return slots.email({
+			state,
+			requestCode: auth.requestCode
+		});
+		case "otp_pending": return slots.otp({
+			state,
+			verifyCode: auth.verifyCode,
+			back: () => action(send, { _tag: "Reset" })
+		});
+		case "restoring":
+		case "otp_sending":
+		case "otp_verifying":
+		case "signing_out": return slots.pending({ state });
+		case "faulted": return slots.failure({
+			state,
+			recover: () => action(send, state.resume === null ? { _tag: "Reset" } : {
+				_tag: "ResumeOtpEntry",
+				now: Date.now()
+			}),
+			back: () => action(send, { _tag: "Reset" })
+		});
+		case "authenticated": return slots.success({
+			state,
+			destination
+		});
+		default: return absurd(state);
+	}
+}
+function ready(destination) {
+	return destination?.to === "dashboardPersonal" || destination?.to === "dashboardOrganization";
+}
+//#endregion
+//#region src/access/onboarding-controller.tsx
+function CapxulOnboardingController(props) {
+	const state = useCapxulIdentity();
+	const destination = useCapxulDestination();
+	const auth = useCapxulAuth();
+	const resumeSubmittedOrganization = useResumeSubmittedOrganization();
+	const resumedSubmission = useRef(null);
+	const [failedRecovery, setFailedRecovery] = useState(null);
+	const [organizationActions, setOrganizationActions] = useState(0);
+	async function withOrganizationProgress(action) {
+		setOrganizationActions((count) => count + 1);
+		try {
+			return await action();
+		} finally {
+			setOrganizationActions((count) => count - 1);
+		}
+	}
+	const createOrganization = (submission, options) => withOrganizationProgress(() => auth.createOrganization(submission, options));
+	const submission = props.submittedOrganization;
+	const accountAt = state.phase === "authenticated" ? state.account.at : null;
+	useEffect(() => {
+		if (props.intent !== "organization" || submission === null || props.recoveryOptions === void 0 || accountAt !== "unknown" && accountAt !== "counterfactual" || resumedSubmission.current === submission) return;
+		resumedSubmission.current = submission;
+		setFailedRecovery(null);
+		resumeSubmittedOrganization(submission, props.recoveryOptions()).then((result) => {
+			if (!result.ok) setFailedRecovery(submission);
+		});
+	}, [
+		accountAt,
+		props.intent,
+		props.recoveryOptions,
+		resumeSubmittedOrganization,
+		submission
+	]);
+	if (state.phase !== "authenticated") return null;
+	const { slots, navigation } = props;
+	if (props.intent === null) return slots.intent({
+		state,
+		select: props.onIntent,
+		back: navigation.selectorBack
+	});
+	if (props.intent === "personal" && !state.profileComplete) return slots.profile({
+		intent: "personal",
+		state,
+		completePersonal: auth.completePersonal,
+		cancel: navigation.profileCancel
+	});
+	if (props.intent === "organization" && props.organizationProfile === null && submission === null) return slots.profile({
+		intent: "organization",
+		state,
+		continueOrganization: props.onOrganizationProfile,
+		cancel: navigation.profileCancel
+	});
+	if (props.intent === "organization" && props.organizationProfile !== null && submission === null) return organizationForm(props, state, createOrganization, null);
+	if (submission !== null && failedRecovery === submission && state.account.at !== "claimed") return organizationForm(props, state, createOrganization, submission);
+	if (submission !== null && state.account.at !== "claimed") {
+		if (state.account.at === "failed") {
+			const retry = state.account.retryable ? (options) => createOrganization(submission, options) : void 0;
+			return slots.accountFailure({
+				state,
+				account: state.account,
+				...retry === void 0 ? {} : { retry }
+			});
+		}
+		return slots.accountProgress({
+			state,
+			account: state.account
+		});
+	}
+	if (submission !== null && state.account.at === "claimed") {
+		const org = state.account.org;
+		if (org === null) return organizationForm(props, state, createOrganization, submission);
+		if (org.observation === "error" || org.setup?.status === "failed" || org.setup?.status === "needsAttention" || org.setup?.status === "awaitingAuthorization" && organizationActions === 0) {
+			const retry = org.orgId === null ? (options) => createOrganization(submission, options) : (options) => withOrganizationProgress(() => auth.retry(options));
+			return slots.organizationFailure({
+				state,
+				org,
+				retry
+			});
+		}
+		if (org.setup?.status !== "ready" || org.observation !== "connected") return slots.organizationProgress({
+			state,
+			org
+		});
+	}
+	if (state.account.at === "failed") return slots.accountFailure({
+		state,
+		account: state.account,
+		...state.account.retryable ? { retry: auth.retry } : {}
+	});
+	if (state.account.at !== "claimed") return slots.accountProgress({
+		state,
+		account: state.account
+	});
+	return ready(destination) ? slots.ready({
+		state,
+		destination
+	}) : null;
+}
+function organizationForm(props, state, createOrganization, submitted) {
+	const profileDetails = submitted?.profileDetails ?? props.organizationProfile;
+	if (profileDetails === null) return null;
+	return props.slots.organization({
+		state,
+		profileDetails,
+		submitted,
+		pinnedHandle: submitted?.organization.handle ?? null,
+		submit: (organization, options) => {
+			if (submitted !== null) return createOrganization(submitted, options);
+			const normalized = normalizeOrganization(organization);
+			if (normalized === null) return createOrganization({
+				profileDetails,
+				organization
+			}, options);
+			const next = {
+				profileDetails,
+				organization: normalized
+			};
+			props.onSubmittedOrganization(next);
+			return createOrganization(next, options);
+		},
+		back: () => {
+			props.onOrganizationProfile(null);
+			props.navigation.organizationBack();
+		},
+		cancel: props.navigation.organizationCancel
+	});
+}
+//#endregion
+export { orgKeySegment as _, entered as a, useCapxulIdentity as c, useCapxulTransitions as d, toInvocationControls as f, capxulKeys as g, actingAccount as h, CapxulProvider as i, useCapxulIdentityOrNull as l, accountKey as m, CapxulAuthenticationController as n, useCapxulAuth as o, toInvocationOptions as p, absurd as r, useCapxulDestination as s, CapxulOnboardingController as t, useCapxulSend as u, useCapxulClientOrNull as v, useCapxul as y };