@capxul/sdk-react 2.0.1 → 2.1.0

package/README.md

@@ -24,13 +24,17 @@ export function Providers({ children }: { children: React.ReactNode }) {
   expose the Core SDK identity actor without a parallel React state model.
 - `useCapxulSend` carries caller-owned invocation controls to that actor.
 - `useCapxulAuth` is the stable six-verb application facade.
+- The provider restores Account readiness after a complete authenticated
+  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.
 - Rich-data hooks such as `useCapxulProfile`, `useCapxulOrgs`, members, roles,
-  treasury, and money hooks remain TanStack Query projections.
+  treasury, and money hooks remain TanStack Query projections. Personal
+  holdings and activity reads start only after the Account is claimed.
 
 The packed npm package exposes `@capxul/sdk-react` and
 `@capxul/sdk-react/testing`. The workspace-only `@capxul/sdk-react/headless`

package/dist/{controllers--rna89ya.mjs → controllers-Chqyy3HR.mjs}

@@ -81,11 +81,10 @@ const capxulKeys = {
 		"permissions"
 	],
 	activity: ["capxul", "activity"],
-	activityDetail: (kind, id) => [
+	activityDetail: (reference) => [
 		"capxul",
 		"activity",
-		kind,
-		id ?? "pending"
+		reference ?? "pending"
 	],
 	holdings: ["capxul", "holdings"],
 	payments: ["capxul", "payments"],
@@ -184,8 +183,11 @@ function createAuth(client, clearAuthenticatedQueries) {
 			ok: false,
 			reason: "INVALID_INPUT"
 		};
-		const completed = await completeProfile(submission.profileDetails, invocation);
-		if (!completed.ok) return completed;
+		const current = runtime.snapshot();
+		if (current.phase !== "authenticated" || !current.profileComplete) {
+			const completed = await completeProfile(submission.profileDetails, invocation);
+			if (!completed.ok) return completed;
+		}
 		const refreshed = await read(invocation);
 		if (!refreshed.ok) return refreshed;
 		const claimed = await reachClaimed(invocation);
@@ -257,6 +259,24 @@ function createAuth(client, clearAuthenticatedQueries) {
 			return ensureAccount(invocation);
 		}),
 		createOrganization: (submission, options) => guarded(runtime, "createOrganization", options, async (invocation) => {
+			const current = runtime.snapshot();
+			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,
+						reason: org.failure.code
+					};
+					return failure(await runtime.send({ _tag: "RetryOrganization" }, invocation)) ?? {
+						ok: true,
+						orgId: org.orgId
+					};
+				}
+			}
 			const prepared = await prepareOrganization(submission, invocation);
 			if (!prepared.ok) return prepared;
 			const created = await runtime.send({
@@ -291,20 +311,37 @@ function CapxulIdentityProvider({ client, children }) {
 	const runtime = client?._internal.identity ?? null;
 	const listeners = useRef(/* @__PURE__ */ new Set());
 	useEffect(() => {
-		if (client === null) return;
-		Promise.resolve().then(() => client.auth.getSession()).catch(() => void 0);
-	}, [client]);
+		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 (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;
 		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 });
 			for (const listener of listeners.current) try {
 				listener(record, state);
 			} catch {
 				listeners.current.delete(listener);
 			}
 		});
-	}, [runtime]);
+	}, [queryClient, runtime]);
 	const addTransitionListener = useCallback((listener) => {
 		listeners.current.add(listener);
 		return () => listeners.current.delete(listener);

package/dist/index.d.mts

@@ -69,7 +69,8 @@ type UseCapxulAccountFundReturn = UseMutationResult<{
 declare function useCapxulAccountFund(): UseCapxulAccountFundReturn;
 //#endregion
 //#region src/hooks/use-capxul-money.d.ts
-type UseCapxulPayReturn = UseMutationResult<Payment, CapxulError, PaymentsPayInput>;
+type CapxulPayIntent = PaymentsPayInput;
+type UseCapxulPayReturn = UseMutationResult<Payment, CapxulError, CapxulPayIntent>;
 declare function useCapxulPay(): UseCapxulPayReturn;
 type UseCapxulCreateCommitmentReturn = UseMutationResult<Payment, CapxulError, PaymentsPayInput & {
   readonly timing: Exclude<PaymentTiming, {
@@ -321,7 +322,7 @@ declare function useCapxulHoldings(): UseQueryResult<CurrentHoldings, CapxulErro
 //#endregion
 //#region src/hooks/use-capxul-orgs.d.ts
 /**
- * List the Orgs you belong to (canon §C1 "Org list" / §C3). Binds directly to
+ * List the Organizations that the current user can access. Binds directly to
  * the locked `capxul.orgs()` SDK method.
  */
 type UseCapxulOrgsReturn = UseQueryResult<readonly OrgView[], CapxulError>;
@@ -341,8 +342,8 @@ type UseCapxulOrgMembersOptions = {
   readonly enabled?: boolean;
 };
 /**
- * The members of an Org (canon §C1 "Members" / §C3, D8/D9). Binds directly to
- * the entity-scoped `capxul.org(orgId).members()` (D13). Gated by
+ * List the members of one Organization. Binds directly to
+ * `capxul.org(orgId).members()`. Gated by
  * `orgId !== undefined`; callers may additionally gate on canonical identity
  * readiness through `options.enabled`.
  */
@@ -354,9 +355,8 @@ type UseCapxulOrgRolesOptions = {
   readonly enabled?: boolean;
 };
 /**
- * The roles seeded on an Org (canon §C1 "Roles" / §C3, D4/D6). Binds directly
- * to the entity-scoped `capxul.org(orgId).roles()` (D13). Gated by
- * `orgId !== undefined`. RED until S2.
+ * List the roles for one Organization. Binds directly
+ * to `capxul.org(orgId).roles()`. Gated by `orgId !== undefined`.
  */
 type UseCapxulOrgRolesReturn = UseQueryResult<readonly RoleView[], CapxulError>;
 declare function useCapxulOrgRoles(orgId: OrgId | undefined, options?: UseCapxulOrgRolesOptions): UseCapxulOrgRolesReturn;
@@ -366,29 +366,26 @@ type UseCapxulOrgTreasuryOptions = {
   readonly enabled?: boolean;
 };
 /**
- * The Org treasury — the real M2 `Account` over the Org Safe (canon §C3, D3).
+ * Return the Organization treasury Account.
  * NEVER `AccountStatus` (the deploy-readiness ladder, no balance). Binds
- * directly to the entity-scoped `capxul.org(orgId).treasury()` (D13). Gated by
- * `orgId !== undefined`. RED until S1.
+ * Binds directly to `capxul.org(orgId).treasury()`. Gated by `orgId !== undefined`.
  */
 type UseCapxulOrgTreasuryReturn = UseQueryResult<Account, CapxulError>;
 declare function useCapxulOrgTreasury(orgId: OrgId | undefined, options?: UseCapxulOrgTreasuryOptions): UseCapxulOrgTreasuryReturn;
 //#endregion
 //#region src/hooks/use-capxul-create-org.d.ts
 /**
- * Create an Org (canon §C2 J1 / §C3, S1). Binds directly to the locked
+ * Create an Organization. Binds directly to the
  * `capxul.createOrg(input)` SDK method. On success, invalidates the org list.
- * RED until S1 — `mutate` rejects with `Errors.notImplemented("org","createOrg")`.
  */
 type UseCapxulCreateOrgReturn = UseMutationResult<OrgView, CapxulError, CreateOrgInput>;
 declare function useCapxulCreateOrg(): UseCapxulCreateOrgReturn;
 //#endregion
 //#region src/hooks/use-capxul-invite-member.d.ts
 /**
- * Invite a member to an Org by email (canon §C2 J2 virality loop / §C3, S3, D8).
- * Entity-scoped via the closed-over `orgId` (D13). Binds directly to
+ * Invite a member to an Organization by email. The hook uses the closed-over `orgId`.
+ * It binds directly to
  * `capxul.org(orgId).invite(input)`. On success, invalidates the member list.
- * RED until S3 — `mutate` rejects with `Errors.notImplemented("org","invite")`.
  */
 type UseCapxulInviteMemberReturn = UseMutationResult<MemberView, CapxulError, InviteMemberInput>;
 declare function useCapxulInviteMember(orgId: OrgId | undefined): UseCapxulInviteMemberReturn;
@@ -421,7 +418,7 @@ type OnboardingOrigin = {
   readonly kind: "organization";
   readonly organizationId: string;
 } | {
-  readonly kind: "proof";
+  readonly kind: "verification";
   readonly organizationId?: string;
 };
 type OnboardingJourney = {
@@ -445,7 +442,7 @@ type OnboardingJourneyPosition = {
   readonly intent: OnboardingIntent;
   readonly step: OnboardingStep;
   readonly organizationId?: string;
-  readonly proof: boolean;
+  readonly verification: boolean;
 };
 declare function startOnboardingJourney(input: {
   readonly intent: OnboardingIntent;

package/dist/index.mjs

@@ -1,7 +1,8 @@
 "use client";
-import { a as useCapxulAuth, c as useCapxulIdentityOrNull, d as capxulKeys, f as useCapxulClientOrNull, i as entered, l as useCapxulSend, n as CapxulOnboardingController, o as useCapxulDestination, p as useCapxul, r as CapxulProvider, s as useCapxulIdentity, t as CapxulAuthenticationController, u as useCapxulTransitions } from "./controllers--rna89ya.mjs";
+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-Chqyy3HR.mjs";
 import { useEffect, useState } from "react";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { fingerprintPaymentIntent } from "@capxul/sdk";
 //#region ../errors/src/errors.ts
 const CAPXUL_ERROR_CODES = [
 	"NOT_AUTHENTICATED",
@@ -32,7 +33,7 @@ const CAPXUL_ERROR_CODES = [
 	"WORK_DIED",
 	"ACTOR_STOPPED"
 ];
-var CapxulError = class extends Error {
+var CapxulError$1 = class extends Error {
 	code;
 	details;
 	correlationId;
@@ -47,33 +48,33 @@ var CapxulError = class extends Error {
 	}
 };
 const Errors = {
-	notAuthenticated: (message, opts) => new CapxulError("NOT_AUTHENTICATED", message ?? "Not authenticated", opts?.failure_mode ? { details: { failure_mode: opts.failure_mode } } : void 0),
-	emailDeliveryFailed: (detail) => new CapxulError("EMAIL_DELIVERY_FAILED", "Failed to send email", { details: { detail } }),
-	profileNotFound: (authUserId) => new CapxulError("PROFILE_NOT_FOUND", `Profile not found for user ${authUserId}`, { details: { authUserId } }),
-	smartAccountMissing: (authUserId) => new CapxulError("SMART_ACCOUNT_MISSING", "Smart account not provisioned", { details: { authUserId } }),
-	playerNotFound: (playerId) => new CapxulError("PLAYER_NOT_FOUND", playerId ? `Openfort player ${playerId} not found` : "Openfort player not found", playerId === void 0 ? void 0 : { details: { playerId } }),
-	accountNotFound: (accountId) => new CapxulError("ACCOUNT_NOT_FOUND", accountId ? `Openfort account ${accountId} not found` : "Openfort account not found", accountId === void 0 ? void 0 : { details: { accountId } }),
+	notAuthenticated: (message, opts) => new CapxulError$1("NOT_AUTHENTICATED", message ?? "Not authenticated", opts?.failure_mode ? { details: { failure_mode: opts.failure_mode } } : void 0),
+	emailDeliveryFailed: (detail) => new CapxulError$1("EMAIL_DELIVERY_FAILED", "Failed to send email", { details: { detail } }),
+	profileNotFound: (authUserId) => new CapxulError$1("PROFILE_NOT_FOUND", `Profile not found for user ${authUserId}`, { details: { authUserId } }),
+	smartAccountMissing: (authUserId) => new CapxulError$1("SMART_ACCOUNT_MISSING", "Smart account not provisioned", { details: { authUserId } }),
+	playerNotFound: (playerId) => new CapxulError$1("PLAYER_NOT_FOUND", playerId ? `Openfort player ${playerId} not found` : "Openfort player not found", playerId === void 0 ? void 0 : { details: { playerId } }),
+	accountNotFound: (accountId) => new CapxulError$1("ACCOUNT_NOT_FOUND", accountId ? `Openfort account ${accountId} not found` : "Openfort account not found", accountId === void 0 ? void 0 : { details: { accountId } }),
 	providerError: (provider, operation, cause, opts) => {
 		const details = {
 			provider,
 			operation
 		};
 		if (opts?.failure_mode) details.failure_mode = opts.failure_mode;
-		return new CapxulError("PROVIDER_ERROR", `Provider error: ${provider} ${operation}`, {
+		return new CapxulError$1("PROVIDER_ERROR", `Provider error: ${provider} ${operation}`, {
 			cause,
 			details
 		});
 	},
-	capabilityUnavailable: (provider, operation) => new CapxulError("CAPABILITY_UNAVAILABLE", "Provider capability is unavailable", { details: {
+	capabilityUnavailable: (provider, operation) => new CapxulError$1("CAPABILITY_UNAVAILABLE", "Provider capability is unavailable", { details: {
 		provider,
 		operation
 	} }),
-	invalidInput: (field, reason) => new CapxulError("INVALID_INPUT", `Invalid ${field}: ${reason}`, { details: {
+	invalidInput: (field, reason) => new CapxulError$1("INVALID_INPUT", `Invalid ${field}: ${reason}`, { details: {
 		field,
 		reason
 	} }),
-	envMissing: (name) => new CapxulError("ENV_MISSING", `Environment variable ${name} not configured`, { details: { name } }),
-	notImplemented: (domain, method) => new CapxulError("NOT_IMPLEMENTED", `${domain}.${method} is not yet implemented. This feature is planned for a future release.`, { details: {
+	envMissing: (name) => new CapxulError$1("ENV_MISSING", `Environment variable ${name} not configured`, { details: { name } }),
+	notImplemented: (domain, method) => new CapxulError$1("NOT_IMPLEMENTED", `${domain}.${method} is not yet implemented. This feature is planned for a future release.`, { details: {
 		domain,
 		method
 	} }),
@@ -85,7 +86,7 @@ const Errors = {
 	* message string. The redacted message names the timeout budget; the
 	* native `cause` carries the same information for `reportError` fidelity.
 	*/
-	providerTimeout: (provider, operation, timeoutMs) => new CapxulError("PROVIDER_ERROR", `Provider error: ${provider} ${operation} (timeout exceeded ${timeoutMs}ms)`, {
+	providerTimeout: (provider, operation, timeoutMs) => new CapxulError$1("PROVIDER_ERROR", `Provider error: ${provider} ${operation} (timeout exceeded ${timeoutMs}ms)`, {
 		details: {
 			provider,
 			operation,
@@ -94,14 +95,14 @@ const Errors = {
 		cause: /* @__PURE__ */ new Error(`timeout: ${operation} exceeded ${timeoutMs}ms`)
 	}),
 	verificationRequired: (details) => {
-		return new CapxulError("VERIFICATION_REQUIRED", "rail" in details ? `Verification is required before ${details.rail} can use ${details.currentKind}.` : `Verification tier ${details.requiredTier} is required.`, { details });
+		return new CapxulError$1("VERIFICATION_REQUIRED", "rail" in details ? `Verification is required before ${details.rail} can use ${details.currentKind}.` : `Verification tier ${details.requiredTier} is required.`, { details });
 	},
-	insufficientBalance: (asset, available, required) => new CapxulError("INSUFFICIENT_BALANCE", `Insufficient ${asset} balance`, { details: {
+	insufficientBalance: (asset, available, required) => new CapxulError$1("INSUFFICIENT_BALANCE", `Insufficient ${asset} balance`, { details: {
 		asset,
 		available,
 		required
 	} }),
-	invalidRecipient: (reason) => new CapxulError("INVALID_RECIPIENT", `Invalid recipient: ${reason}`, { details: { reason } }),
+	invalidRecipient: (reason) => new CapxulError$1("INVALID_RECIPIENT", `Invalid recipient: ${reason}`, { details: { reason } }),
 	/**
 	* The org Zodiac Roles modifier REFUSED the spend on-chain (G4 · #547): the
 	* member's role condition (per-tx cap, per-day allowance, allowed recipient,
@@ -112,7 +113,7 @@ const Errors = {
 	* `disallowed_recipient` / `condition_violation`); leak-safe — no on-chain
 	* identifiers ever enter the details.
 	*/
-	rolePermissionDenied: (details) => new CapxulError("ROLE_PERMISSION_DENIED", `Org role denied this spend on-chain (${details.reason}).`, { details: details.operation === void 0 ? { reason: details.reason } : {
+	rolePermissionDenied: (details) => new CapxulError$1("ROLE_PERMISSION_DENIED", `Org role denied this spend on-chain (${details.reason}).`, { details: details.operation === void 0 ? { reason: details.reason } : {
 		reason: details.reason,
 		operation: details.operation
 	} }),
@@ -123,28 +124,28 @@ const Errors = {
 	* Roles condition violation) from an inconclusive infra failure. A confirmed
 	* revert is the ONLY mode the org spend port may map to a roles denial.
 	*/
-	transactionFailed: (operation, cause, extra) => new CapxulError("TRANSACTION_FAILED", `Transaction failed: ${operation}`, {
+	transactionFailed: (operation, cause, extra) => new CapxulError$1("TRANSACTION_FAILED", `Transaction failed: ${operation}`, {
 		cause,
 		details: extra?.reason === void 0 ? { operation } : {
 			operation,
 			reason: extra.reason
 		}
 	}),
-	rateLimited: (details) => new CapxulError("RATE_LIMITED", "Rate limit exceeded", details === void 0 ? void 0 : { details: { ...details } }),
-	networkError: (operation, cause) => new CapxulError("NETWORK_ERROR", `Network error during ${operation}`, {
+	rateLimited: (details) => new CapxulError$1("RATE_LIMITED", "Rate limit exceeded", details === void 0 ? void 0 : { details: { ...details } }),
+	networkError: (operation, cause) => new CapxulError$1("NETWORK_ERROR", `Network error during ${operation}`, {
 		cause,
 		details: { operation }
 	}),
-	unknown: (cause) => new CapxulError("UNKNOWN", "Unknown error", { cause }),
-	otpExpired: (details) => new CapxulError("OTP_EXPIRED", "Verification code has expired. Request a new one.", details === void 0 ? void 0 : { details: { ...details } }),
-	signerRejected: (details) => new CapxulError("SIGNER_REJECTED", "Signer rejected the request.", {
+	unknown: (cause) => new CapxulError$1("UNKNOWN", "Unknown error", { cause }),
+	otpExpired: (details) => new CapxulError$1("OTP_EXPIRED", "Verification code has expired. Request a new one.", details === void 0 ? void 0 : { details: { ...details } }),
+	signerRejected: (details) => new CapxulError$1("SIGNER_REJECTED", "Signer rejected the request.", {
 		cause: details.cause,
 		details: details.reason === void 0 ? { source: details.source } : {
 			source: details.source,
 			reason: details.reason
 		}
 	}),
-	cancelled: (details) => new CapxulError("CANCELLED", "Operation was cancelled.", details === void 0 ? void 0 : { details: { ...details } }),
+	cancelled: (details) => new CapxulError$1("CANCELLED", "Operation was cancelled.", details === void 0 ? void 0 : { details: { ...details } }),
 	/**
 	* Method called from a flow state where its precondition fails (TA16). The
 	* SDK's method API short-circuits with this error before driving the
@@ -153,7 +154,7 @@ const Errors = {
 	* `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: {
+	wrongState: (details) => new CapxulError$1("WRONG_STATE", `${details.method} called from state '${details.currentState}'; valid states: ${details.validStates.join(", ")}`, { details: {
 		...details,
 		validStates: [...details.validStates]
 	} })
@@ -242,6 +243,137 @@ async function invalidateMoneyState(queryClient, input) {
 	await Promise.all(invalidations);
 }
 //#endregion
+//#region src/internal/payment-request-key.ts
+const STORAGE_PREFIX = "capxul.payment.request-key.v3";
+const attemptReleases = /* @__PURE__ */ new Set();
+let pagehideInstalled = false;
+async function storageKey(operation, intent) {
+	return `${STORAGE_PREFIX}:${await fingerprintPaymentIntent({
+		operation,
+		intent
+	})}`;
+}
+function paymentLockManager() {
+	const manager = navigator.locks;
+	if (manager === void 0 || typeof manager.query !== "function") throw new Error("Web Locks are required for payment request keys");
+	return manager;
+}
+function attemptLockName(storageSlot, attemptId) {
+	return `${storageSlot}:attempt:${attemptId}`;
+}
+async function heldAttemptIds(manager, storageSlot) {
+	const prefix = `${storageSlot}:attempt:`;
+	return ((await manager.query()).held ?? []).map((lock) => lock.name).filter((name) => name.startsWith(prefix)).map((name) => name.slice(prefix.length));
+}
+async function holdAttemptLock(name) {
+	const manager = paymentLockManager();
+	let acquired;
+	let release;
+	const ready = new Promise((resolve) => {
+		acquired = resolve;
+	});
+	const held = manager.request(name, async () => {
+		acquired?.();
+		await new Promise((resolve) => {
+			release = resolve;
+		});
+	});
+	await Promise.race([ready, held.then(() => Promise.reject(/* @__PURE__ */ new Error("Payment attempt lock ended before acquisition")))]);
+	return () => {
+		release?.();
+		held.catch(() => void 0);
+	};
+}
+function releaseAttemptOnPagehide(release) {
+	attemptReleases.add(release);
+	if (!pagehideInstalled) {
+		pagehideInstalled = true;
+		window.addEventListener("pagehide", () => {
+			for (const releaseAttempt of attemptReleases) releaseAttempt();
+			attemptReleases.clear();
+		});
+	}
+	return () => attemptReleases.delete(release);
+}
+function readState(key) {
+	const stored = localStorage.getItem(key);
+	if (stored === null) return null;
+	const state = JSON.parse(stored);
+	if (typeof state.key !== "string" || !Array.isArray(state.active) || state.active.some((attempt) => typeof attempt !== "string") || typeof state.resolved !== "boolean") throw new TypeError("Invalid payment request key state");
+	return state;
+}
+async function beginPaymentRequestKey(operation, intent) {
+	const storageSlot = await storageKey(operation, intent);
+	let releaseAttemptLock;
+	let forgetPagehideRelease;
+	try {
+		const attemptId = `attempt_${crypto.randomUUID()}`;
+		releaseAttemptLock = await holdAttemptLock(attemptLockName(storageSlot, attemptId));
+		forgetPagehideRelease = releaseAttemptOnPagehide(releaseAttemptLock);
+		const manager = paymentLockManager();
+		const key = await manager.request(storageSlot, async () => {
+			let state = readState(storageSlot) ?? {
+				key: `pay_${Array.from(crypto.getRandomValues(new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, "0")).join("")}`,
+				active: [],
+				resolved: false
+			};
+			const registered = state.active.includes(attemptId);
+			const active = await heldAttemptIds(manager, storageSlot);
+			if (!registered && active.every((id) => id === attemptId) && state.resolved) state = {
+				key: `pay_${crypto.randomUUID()}`,
+				active: [],
+				resolved: false
+			};
+			state.active = active;
+			localStorage.setItem(storageSlot, JSON.stringify(state));
+			return state.key;
+		});
+		let finished = false;
+		return {
+			key,
+			finish: async (succeeded) => {
+				if (finished) return;
+				try {
+					await manager.request(storageSlot, async () => {
+						const state = readState(storageSlot);
+						if (state === null || state.key !== key) return;
+						const attemptIndex = state.active.indexOf(attemptId);
+						if (attemptIndex < 0) return;
+						state.active.splice(attemptIndex, 1);
+						state.active = (await heldAttemptIds(manager, storageSlot)).filter((id) => id !== attemptId);
+						state.resolved = succeeded;
+						if (state.active.length === 0 && state.resolved) localStorage.removeItem(storageSlot);
+						else localStorage.setItem(storageSlot, JSON.stringify(state));
+					});
+					finished = true;
+				} finally {
+					forgetPagehideRelease?.();
+					releaseAttemptLock?.();
+				}
+			}
+		};
+	} catch (cause) {
+		forgetPagehideRelease?.();
+		releaseAttemptLock?.();
+		throw Errors.providerError("sdk-react", "paymentRequestKey", cause);
+	}
+}
+async function withPaymentRequestKey(operation, intent, work) {
+	const attempt = await beginPaymentRequestKey(operation, intent);
+	try {
+		const result = await work(attempt.key);
+		try {
+			await attempt.finish(true);
+		} catch {}
+		return result;
+	} catch (cause) {
+		try {
+			await attempt.finish(false);
+		} catch {}
+		throw cause;
+	}
+}
+//#endregion
 //#region src/internal/reject-unresolved-actor.ts
 /**
 * Guard for mutation hooks whose variables carry an optional `actor` field
@@ -261,12 +393,22 @@ function rejectUnresolvedActor(variables, operation) {
 //#region src/hooks/use-capxul-money.ts
 function useCapxulPay() {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
+	const actorId = identity?.phase === "authenticated" ? identity.session.authUserId : "signed-out";
+	const backendScope = client === null ? "pending" : `${client._internal.bootstrap.convexUrl}:${String(client._internal.bootstrap.chainId)}`;
 	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");
+			return withPaymentRequestKey("personal-pay", {
+				actorId,
+				backendScope,
+				input
+			}, async (requestKey) => unwrapCapxulResult(await bootstrappedClient.payments.pay({
+				...input,
+				requestKey
+			}), bootstrappedClient._internal.telemetry, "mutation"));
 		},
 		onSuccess: async (payment) => {
 			await invalidateMoneyState(queryClient, {
@@ -322,13 +464,14 @@ function useCapxulRedirectPayment() {
 }
 function useCapxulPayments(options) {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	return useQuery({
 		queryKey: capxulKeys.payments,
 		queryFn: async () => {
 			const bootstrappedClient = requireBootstrappedClient(client, "payments.list");
 			return unwrapCapxulResult(await bootstrappedClient.payments.list(), bootstrappedClient._internal.telemetry);
 		},
-		enabled: client !== null && (options?.enabled ?? true)
+		enabled: client !== null && identity?.phase === "authenticated" && identity.account.at === "claimed" && (options?.enabled ?? true)
 	});
 }
 function useCapxulPayment(paymentId, options) {
@@ -347,36 +490,56 @@ function useCapxulPayment(paymentId, options) {
 //#region src/hooks/use-capxul-organization-payments.ts
 function useCapxulOrganizationPay(orgId) {
 	const client = useCapxulClientOrNull();
+	const backendScope = client === null ? "pending" : `${client._internal.bootstrap.convexUrl}:${String(client._internal.bootstrap.chainId)}`;
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (input) => {
 			const bootstrapped = requireBootstrappedClient(client, "organizationPayments.pay");
-			return unwrapCapxulResult(await bootstrapped.org(orgId).payments.pay(input), bootstrapped._internal.telemetry, "mutation");
+			return withPaymentRequestKey("organization-pay", {
+				backendScope,
+				orgId,
+				...input
+			}, async (requestKey) => unwrapCapxulResult(await bootstrapped.org(orgId).payments.pay({
+				...input,
+				requestKey
+			}), bootstrapped._internal.telemetry, "mutation"));
 		},
-		onSuccess: (payment) => invalidateMoneyState(queryClient, {
-			actor: {
-				kind: "organization",
-				organizationId: orgId
-			},
-			payment
-		})
+		onSuccess: async (payment) => {
+			return invalidateMoneyState(queryClient, {
+				actor: {
+					kind: "organization",
+					organizationId: orgId
+				},
+				payment
+			});
+		}
 	});
 }
 function useCapxulOrganizationPayBatch(orgId) {
 	const client = useCapxulClientOrNull();
+	const backendScope = client === null ? "pending" : `${client._internal.bootstrap.convexUrl}:${String(client._internal.bootstrap.chainId)}`;
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (input) => {
 			const bootstrapped = requireBootstrappedClient(client, "organizationPayments.payBatch");
-			return unwrapCapxulResult(await bootstrapped.org(orgId).payments.payBatch(input), bootstrapped._internal.telemetry, "mutation");
+			return withPaymentRequestKey("organization-pay-batch", {
+				backendScope,
+				orgId,
+				...input
+			}, async (requestKey) => unwrapCapxulResult(await bootstrapped.org(orgId).payments.payBatch({
+				...input,
+				requestKey
+			}), bootstrapped._internal.telemetry, "mutation"));
 		},
-		onSuccess: (payments) => Promise.all(payments.map((payment) => invalidateMoneyState(queryClient, {
-			actor: {
-				kind: "organization",
-				organizationId: orgId
-			},
-			payment
-		})))
+		onSuccess: async (payments) => {
+			return Promise.all(payments.map((payment) => invalidateMoneyState(queryClient, {
+				actor: {
+					kind: "organization",
+					organizationId: orgId
+				},
+				payment
+			})));
+		}
 	});
 }
 //#endregion
@@ -425,25 +588,27 @@ function useCapxulPermission(orgId, permissionId) {
 //#region src/hooks/use-capxul-activity.ts
 function useCapxulActivity(params) {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	return useQuery({
 		queryKey: [...capxulKeys.activity, params ?? {}],
 		queryFn: async () => {
 			const bootstrapped = requireBootstrappedClient(client, "activity.list");
 			return unwrapCapxulResult(await bootstrapped.activity.list(params), bootstrapped._internal.telemetry);
 		},
-		enabled: client !== null
+		enabled: client !== null && identity?.phase === "authenticated" && identity.account.at === "claimed"
 	});
 }
 function useCapxulActivityDetail(reference) {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	return useQuery({
-		queryKey: capxulKeys.activityDetail(reference?.kind ?? "payment", reference?.id),
+		queryKey: capxulKeys.activityDetail(reference),
 		queryFn: async () => {
 			if (reference === void 0) throw new Error("activity reference is required");
 			const bootstrapped = requireBootstrappedClient(client, "activity.get");
 			return unwrapCapxulResult(await bootstrapped.activity.get(reference), bootstrapped._internal.telemetry);
 		},
-		enabled: client !== null && reference !== void 0
+		enabled: client !== null && reference !== void 0 && identity?.phase === "authenticated" && identity.account.at === "claimed"
 	});
 }
 function useCapxulAnnotateMovement() {
@@ -461,13 +626,14 @@ function useCapxulAnnotateMovement() {
 //#region src/hooks/use-capxul-holdings.ts
 function useCapxulHoldings() {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	return useQuery({
 		queryKey: capxulKeys.holdings,
 		queryFn: async () => {
 			const bootstrapped = requireBootstrappedClient(client, "holdings.current");
 			return unwrapCapxulResult(await bootstrapped.holdings.current(), bootstrapped._internal.telemetry);
 		},
-		enabled: client !== null
+		enabled: client !== null && identity?.phase === "authenticated" && identity.account.at === "claimed"
 	});
 }
 //#endregion
@@ -613,7 +779,7 @@ function loadOnboardingJourney(expectedOwnerId) {
 		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);
+		const value = migrateStoredJourney(JSON.parse(raw));
 		if (!isValidJourney(value)) return discardInvalidJourney();
 		if (expectedOwnerId !== void 0 && value.ownerId !== expectedOwnerId) return discardInvalidJourney();
 		if (expectedOwnerId !== void 0) markOnboardingOwnerValidated(expectedOwnerId);
@@ -622,6 +788,20 @@ function loadOnboardingJourney(expectedOwnerId) {
 		return discardInvalidJourney();
 	}
 }
+function migrateStoredJourney(value) {
+	if (!isRecord(value) || !isRecord(value.origin) || value.origin.kind !== "proof") return value;
+	const migrated = {
+		...value,
+		origin: {
+			...value.origin,
+			kind: "verification"
+		}
+	};
+	try {
+		sessionStorage.setItem(JOURNEY_KEY, JSON.stringify(migrated));
+	} catch {}
+	return migrated;
+}
 function saveOnboardingJourney(journey) {
 	if (!isValidJourney(journey)) {
 		discardInvalidJourney();
@@ -642,17 +822,17 @@ function invalidateOnboardingJourneyObservation() {
 }
 /** Where the journey stands — the pure position apps map to their routes. */
 function onboardingJourneyPosition(journey) {
-	const proof = journey.origin?.kind === "proof";
+	const verification = journey.origin?.kind === "verification";
 	if (journey.organizationId !== void 0) return {
 		intent: journey.intent,
 		step: "provisioning",
 		organizationId: journey.organizationId,
-		proof
+		verification
 	};
 	return {
 		intent: journey.intent,
 		step: journey.step,
-		proof
+		verification
 	};
 }
 /**
@@ -715,7 +895,7 @@ 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));
+	return value.kind === "verification" && hasOnlyKeys(value, ["kind", "organizationId"]) && (value.organizationId === void 0 || isBoundedId(value.organizationId));
 }
 function isProfileDraft(value) {
 	if (!isRecord(value) || !hasOnlyKeys(value, [

package/dist/testing/index.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capxul/sdk-react",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Xelmar-tech/infrastructure.git",
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@capxul/sdk": "2.0.1"
+    "@capxul/sdk": "2.1.0"
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.66.9",
@@ -42,8 +42,8 @@
     "react-dom": "^19.2.6",
     "vite-plus": "0.1.23",
     "vitest": "npm:@voidzero-dev/vite-plus-test@0.1.23",
-    "@capxul/types": "0.1.0",
     "@capxul/errors": "0.0.1",
+    "@capxul/types": "0.1.0",
     "@capxul/typescript-config": "0.0.0"
   },
   "peerDependencies": {