@capxul/sdk-react 3.1.0 → 4.0.0

package/dist/{controllers-BkL0hHuk.mjs → controllers-BgkCs0nW.mjs}

@@ -1,6 +1,6 @@
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { QueryClient, QueryClientProvider, useQueryClient } from "@tanstack/react-query";
-import { createCapxulClient, isCapxulError, resolveIdentityDestination, toCountryCode } from "@capxul/sdk";
+import { CapxulError, createCapxulClient, isCapxulError, resolveIdentityDestination, toCountryCode } from "@capxul/sdk";
 import { jsx } from "react/jsx-runtime";
 //#region src/internal/capxul-bootstrap-context.tsx
 const CapxulBootstrapContext = createContext(null);
@@ -40,11 +40,11 @@ function useCapxulClientOrNull() {
 const capxulKeys = {
 	root: ["capxul"],
 	profile: ["capxul", "profile"],
-	usernameAvailability: (username) => [
+	handleAvailability: (handle) => [
 		"capxul",
 		"profile",
-		"username-availability",
-		username
+		"handle-availability",
+		handle
 	],
 	account: ["capxul", "account"],
 	provisioning: ["capxul", "provisioning"],
@@ -179,6 +179,22 @@ async function guarded(runtime, verb, options, run) {
 		};
 	}
 }
+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?.at === "failed" ? 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" })
+	};
+}
 const ORGANIZATION_HANDLE = /^[a-z0-9-]{3,32}$/;
 function normalizeOrganization(organization) {
 	const name = typeof organization.name === "string" ? organization.name.trim() : "";
@@ -243,7 +259,7 @@ function createAuth(client, clearAuthenticatedQueries) {
 		};
 		const current = runtime.snapshot();
 		if (current.phase !== "authenticated" || !current.profileComplete) {
-			const completed = await completeProfile(submission.profileDetails, invocation);
+			const completed = await runtime.completeProfile(submission.profileDetails, invocation);
 			if (!completed.ok) return completed;
 		}
 		const refreshed = await read(invocation);
@@ -314,7 +330,10 @@ function createAuth(client, clearAuthenticatedQueries) {
 		}),
 		completePersonal: (profile, options) => guarded(runtime, "completePersonal", options, async (invocation) => {
 			const completed = await completeProfile(profile, invocation);
-			if (!completed.ok) return completed;
+			if (!completed.ok) return {
+				ok: false,
+				reason: completed.reason
+			};
 			const refreshed = await read(invocation);
 			if (!refreshed.ok) return refreshed;
 			return ensureAccount(invocation);
@@ -356,6 +375,14 @@ function createAuth(client, clearAuthenticatedQueries) {
 				ok: false,
 				reason: "UNKNOWN"
 			};
+		}).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();
@@ -365,7 +392,10 @@ function createAuth(client, clearAuthenticatedQueries) {
 		}),
 		resumeSubmittedOrganization: (submission, options) => guarded(runtime, "createOrganization", options, async (invocation) => {
 			const prepared = await prepareOrganization(submission, invocation);
-			return prepared.ok ? { ok: true } : prepared;
+			return prepared.ok ? { ok: true } : {
+				ok: false,
+				reason: prepared.reason
+			};
 		})
 	};
 }
@@ -771,10 +801,10 @@ function organizationForm(props, state, auth, submitted) {
 		submit: (organization, options) => {
 			if (submitted !== null) return auth.createOrganization(submitted, options);
 			const normalized = normalizeOrganization(organization);
-			if (normalized === null) return Promise.resolve({
-				ok: false,
-				reason: "INVALID_INPUT"
-			});
+			if (normalized === null) return auth.createOrganization({
+				profileDetails,
+				organization
+			}, options);
 			const next = {
 				profileDetails,
 				organization: normalized

package/dist/{controllers-CJEsthW2.d.mts → controllers-DIf8elqQ.d.mts}

@@ -1,5 +1,5 @@
 import { ReactNode } from "react";
-import { CapxulClient, CapxulErrorCode, IdentityDestination, IdentityEvent, IdentityProfileDetails, IdentityState, IdentityTransition, OrgLane, Readiness, StateLabel } from "@capxul/sdk";
+import { CapxulClient, CapxulError, CapxulErrorCode, IdentityDestination, IdentityEvent, IdentityProfileDetails, IdentityState, IdentityTransition, OrgLane, Readiness, StateLabel } from "@capxul/sdk";
 //#region src/identity.d.ts
 type Destination = IdentityDestination;
 interface InvocationOptions {
@@ -34,6 +34,9 @@ type FacadeFailure = {
   readonly ok: false;
   readonly reason: CapxulErrorCode;
 };
+type CreateOrganizationFailure = FacadeFailure & {
+  readonly error: CapxulError;
+};
 type EmptyResult = {
   readonly ok: true;
 } | FacadeFailure;
@@ -51,7 +54,7 @@ interface CapxulAuth {
   readonly createOrganization: (submission: CreateOrganizationSubmission, options?: InvocationOptions) => Promise<{
     readonly ok: true;
     readonly orgId: string;
-  } | FacadeFailure>;
+  } | CreateOrganizationFailure>;
   readonly completePersonal: (profileDetails: ProfileDetails, options?: InvocationOptions) => Promise<EmptyResult>;
   readonly retry: (options?: InvocationOptions) => Promise<EmptyResult>;
 }
@@ -201,4 +204,4 @@ interface OnboardingControllerProps {
 }
 declare function CapxulOnboardingController(props: OnboardingControllerProps): ReactNode;
 //#endregion
-export { useCapxulAuth as A, CreateOrganizationSubmission as C, ProfileDetails as D, OrganizationDetails as E, useCapxulIdentity as M, useCapxulSend as N, SendResult as O, useCapxulTransitions as P, CapxulSend as S, InvocationOptions as T, ReadyDestination as _, AuthenticationSlots as a, Slot as b, ControllerAction as c, OnboardingControllerProps as d, OrgFailure as f, ProfileSlotProps as g, PendingAuthState as h, AuthenticatedState as i, useCapxulDestination as j, entered as k, FaultedState as l, OtpPendingState as m, AccountProgress as n, CapxulAuthenticationController as o, OrgProgress as p, ActionResult as r, CapxulOnboardingController as s, AccountFailure as t, NavigationAction as u, RetryAction as v, Destination as w, CapxulAuth as x, SignedOutState as y };
+export { entered as A, CreateOrganizationFailure as C, OrganizationDetails as D, InvocationOptions as E, useCapxulTransitions as F, useCapxulDestination as M, useCapxulIdentity as N, ProfileDetails as O, useCapxulSend as P, CapxulSend as S, Destination as T, ReadyDestination as _, AuthenticationSlots as a, Slot as b, ControllerAction as c, OnboardingControllerProps as d, OrgFailure as f, ProfileSlotProps as g, PendingAuthState as h, AuthenticatedState as i, useCapxulAuth as j, SendResult as k, FaultedState as l, OtpPendingState as m, AccountProgress as n, CapxulAuthenticationController as o, OrgProgress as p, ActionResult as r, CapxulOnboardingController as s, AccountFailure as t, NavigationAction as u, RetryAction as v, CreateOrganizationSubmission as w, CapxulAuth as x, SignedOutState as y };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as useCapxulAuth, C as CreateOrganizationSubmission, D as ProfileDetails, E as OrganizationDetails, M as useCapxulIdentity, N as useCapxulSend, O as SendResult, P as useCapxulTransitions, S as CapxulSend, T as InvocationOptions, _ as ReadyDestination, a as AuthenticationSlots, b as Slot, c as ControllerAction, d as OnboardingControllerProps, f as OrgFailure, g as ProfileSlotProps, h as PendingAuthState, i as AuthenticatedState, j as useCapxulDestination, k as entered, l as FaultedState, m as OtpPendingState, n as AccountProgress, o as CapxulAuthenticationController, p as OrgProgress, r as ActionResult, s as CapxulOnboardingController, t as AccountFailure, u as NavigationAction, v as RetryAction, w as Destination, x as CapxulAuth, y as SignedOutState } from "./controllers-CJEsthW2.mjs";
+import { A as entered, C as CreateOrganizationFailure, D as OrganizationDetails, E as InvocationOptions, F as useCapxulTransitions, M as useCapxulDestination, N as useCapxulIdentity, O as ProfileDetails, P as useCapxulSend, S as CapxulSend, T as Destination, _ as ReadyDestination, a as AuthenticationSlots, b as Slot, c as ControllerAction, d as OnboardingControllerProps, f as OrgFailure, g as ProfileSlotProps, h as PendingAuthState, i as AuthenticatedState, j as useCapxulAuth, k as SendResult, l as FaultedState, m as OtpPendingState, n as AccountProgress, o as CapxulAuthenticationController, p as OrgProgress, r as ActionResult, s as CapxulOnboardingController, t as AccountFailure, u as NavigationAction, v as RetryAction, w as CreateOrganizationSubmission, x as CapxulAuth, y as SignedOutState } from "./controllers-DIf8elqQ.mjs";
 import { ReactNode, RefCallback } from "react";
 import { QueryClient, UseMutationResult, UseQueryResult } from "@tanstack/react-query";
 import { Account, AccountRequirement, ActivityAnnotation, ActivityAnnotationInput, ActivityDetail, ActivityKind, ActivityListParams, ActivityPage, ActivityPhase, ActivityRange, ActivityReference, ActorReference, AddressBookEntry, BudgetId, CapxulClient, CapxulError, CapxulResult, CapxulSigner, CreateOrgInput, CurrentHoldings, HostObservability, IdentityDestination, InviteMemberInput, MemberView, Money, MoneyParseErrorReason, OrgId, OrgView, OrganizationPaymentBatchInput, OrganizationPaymentInput, PartyId, Payment, PaymentDirection, PaymentDocumentRef, PaymentDocumentRender, PaymentStatus, PaymentTiming, PaymentType, PaymentsPayInput, PayrollGroupId, PayrollGroupInput, PayrollRunId, PayrollRunStatus, Permission, PermissionMethods, PermissionReadResult, Profile, RoleView, SubmittedPermissionExecution, isClaimed, isRestoring } from "@capxul/sdk";
@@ -220,7 +220,7 @@ type ProfileDraft = {
   readonly displayName: string;
   readonly country: string;
   readonly withdrawalAddress: string;
-  readonly username?: string;
+  readonly handle?: string;
   readonly payoutAddresses?: readonly PayoutDraftEntry[];
 };
 type OrganizationDraft = {
@@ -295,23 +295,23 @@ declare function acknowledgeOnboardingDestination(destination: {
 }, ownerId: string): boolean;
 declare function clearOnboardingJourney(): void;
 //#endregion
-//#region src/headless/onboarding/use-capxul-username-availability.d.ts
-type UsernameAvailability = {
+//#region src/headless/onboarding/use-capxul-handle-availability.d.ts
+type HandleAvailability = {
   readonly available: boolean;
   readonly normalized: string;
 };
-type UseCapxulUsernameAvailabilityReturn = UseQueryResult<UsernameAvailability, CapxulError>;
+type UseCapxulHandleAvailabilityReturn = UseQueryResult<HandleAvailability, CapxulError>;
 /**
- * #1062: debounced availability probe for the username the user is typing.
+ * #1062: debounced availability probe for the handle 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
+ * boundary's message), not as `available: false` — only a handle someone
  * else owns is "taken".
  */
-declare function useCapxulUsernameAvailability(username: string, options?: {
+declare function useCapxulHandleAvailability(handle: string, options?: {
   readonly enabled?: boolean;
   readonly debounceMs?: number;
-}): UseCapxulUsernameAvailabilityReturn;
+}): UseCapxulHandleAvailabilityReturn;
 //#endregion
 //#region src/headless/media/use-capxul-image-upload.d.ts
 type ImageUploadTarget = {
@@ -622,16 +622,17 @@ declare const CapxulActivity: typeof Root$5 & {
 };
 //#endregion
 //#region src/headless/send-money/use-recipient-resolution.d.ts
-type SendMoneyRecipientMethod = "username" | "email-address";
-type SendMoneyRecipientStatus = "empty" | "checking" | "found" | "not-found" | "failed";
+type SendMoneyRecipientStatus = "empty" | "invalid" | "checking" | "known-party" | "new-email" | "external-warning" | "external-ready" | "not-found" | "failed";
 interface SendMoneyRecipientSlice {
-  readonly method: SendMoneyRecipientMethod;
-  readonly setMethod: (method: SendMoneyRecipientMethod) => void;
   readonly value: string;
   readonly change: (text: string) => void;
-  /** ADR-0023 R1: the status IS the failure code; the app owns the sentence. */
   readonly status: SendMoneyRecipientStatus;
   readonly label: string | null;
+  readonly kind: "person" | "organization" | "external_address" | "unresolved" | null;
+  readonly isCapxulAccount: boolean | null;
+  readonly publicValue: string | null;
+  readonly requiresAcknowledgement: boolean;
+  readonly acknowledgeExternalAddress: () => void;
 }
 //#endregion
 //#region src/headless/send-money/use-send-money.d.ts
@@ -997,7 +998,7 @@ declare const CapxulPayrollRun: typeof Root & {
 declare const capxulKeys: {
   root: readonly ["capxul"];
   profile: readonly ["capxul", "profile"];
-  usernameAvailability: (username: string) => readonly ["capxul", "profile", "username-availability", string];
+  handleAvailability: (handle: string) => readonly ["capxul", "profile", "handle-availability", string];
   account: readonly ["capxul", "account"];
   provisioning: readonly ["capxul", "provisioning"];
   binding: readonly ["capxul", "binding"];
@@ -1023,4 +1024,4 @@ declare const capxulKeys: {
   payment: (paymentId: string | undefined) => readonly ["capxul", "payments", string];
 };
 //#endregion
-export { type AccountFailure, type AccountProgress, type ActionResult, type ActivityDetailSlice, type ActivityExportSlice, type ActivityFilterValues, type ActivityFiltersSlice, type ActivityLoadMoreSlice, type ActivityReceipt, type ActivityRow, type ActivityRowsSlice, type ActivitySearchSlice, type ActivitySummarySlice, type AuthenticatedState, type AuthenticationSlots, type CanReason, CapxulActivity, type CapxulActivityProps, type CapxulAuth, CapxulAuthenticationController, type CapxulBootstrapState, type CapxulBootstrapStatus, CapxulContacts, type CapxulContactsProps, CapxulDashboardAccess, type CapxulDashboardAccessProps, CapxulOnboardingController, CapxulOrgMember, type CapxulOrgMemberProps, CapxulPayroll, type CapxulPayrollProps, CapxulPayrollRun, type CapxulPayrollRunBlockedReason, type CapxulPayrollRunProps, CapxulProvider, type CapxulProviderProps, type CapxulSend, CapxulSendMoney, type CapxulSendMoneyBlockedReason, type CapxulSendMoneyProps, type Contact, type ContactRelationship, type ContactRow, type ContactsActor, type ContactsAddBlockedReason, type ContactsAddError, type ContactsAddSlice, type ContactsListOptions, type ContactsListSlice, type ContactsRefusal, type ContactsSummarySlice, type ControllerAction, type CreateOrganizationSubmission, type CsvExport, type DashboardAccessErrorSlice, type DashboardAccessPhase, type DashboardAccessRedirectSlice, type DashboardScope, type Destination, type FaultedState, type ImageUploadInput, type ImageUploadTarget, type InvocationOptions, type NavigationAction, type OnboardingControllerProps, type OnboardingIntent, type OnboardingJourney, type OnboardingJourneyPosition, type OnboardingOrigin, type OnboardingStep, type OrgFailure, type OrgMemberAction, type OrgMemberCanSlice, type OrgMemberStanding, type OrgMemberStandingSlice, type OrgProgress, type OrganizationDetails, type OrganizationDraft, type OtpPendingState, type PayoutDraftChain, type PayoutDraftEntry, type PayrollGroupRow, type PayrollGroupsSlice, type PayrollRecipientOption, type PayrollRunActionsSlice, type PayrollRunAmountEntry, type PayrollRunAmountsSlice, type PayrollRunAssetSlice, type PayrollRunGroupOption, type PayrollRunPrefill, type PayrollRunRecipientsSlice, type PayrollRunStatus, type PayrollRunSummarySlice, type PayrollSummarySlice, type PendingAuthState, type ProfileDetails, type ProfileDraft, type ProfileSlotProps, type ReadyDestination, type RetryAction, type SendActor, type SendMoneyActionsSlice, type SendMoneyAmountSlice, type SendMoneyAssetError, type SendMoneyAssetOption, type SendMoneyAssetSlice, type SendMoneyRecipientMethod, type SendMoneyRecipientSlice, type SendMoneyRecipientStatus, type SendMoneySourceError, type SendMoneySourceOption, type SendMoneySourceSlice, type SendResult, type SentPayment, type SentPayrollRun, type SignedOutState, type Slot, type SummaryWindow, type UseCapxulAccountBalanceOptions, type UseCapxulAccountBalanceReturn, type UseCapxulAccountFundReturn, type UseCapxulCreateCommitmentReturn, type UseCapxulCreateOrgReturn, type UseCapxulImageUploadReturn, type UseCapxulInviteMemberReturn, type UseCapxulOrgMembersOptions, type UseCapxulOrgMembersReturn, type UseCapxulOrgRolesOptions, type UseCapxulOrgRolesReturn, type UseCapxulOrgTreasuryOptions, type UseCapxulOrgTreasuryReturn, type UseCapxulOrgsReturn, type UseCapxulPayReturn, type UseCapxulPaymentReturn, type UseCapxulPaymentsReturn, type UseCapxulProfileReturn, type UseCapxulRedirectPaymentReturn, type UseCapxulUsernameAvailabilityReturn, type UsernameAvailability, acknowledgeOnboardingDestination, activeOnboardingRecovery, capxulKeys, clearOnboardingJourney, currentOnboardingJourneyId, entered, invalidateOnboardingJourneyObservation, isClaimed, isRestoring, loadOnboardingJourney, onboardingJourneyPosition, saveOnboardingJourney, startOnboardingJourney, useCapxul, useCapxulAccountBalance, useCapxulAccountFund, useCapxulActivity, useCapxulActivityDetail, useCapxulAnnotateMovement, useCapxulAuth, useCapxulCancelPayment, useCapxulClaimPayment, useCapxulClientOrNull, useCapxulCreateCommitment, useCapxulCreateOrg, useCapxulDestination, useCapxulHoldings, useCapxulIdentity, useCapxulImageUpload, useCapxulInviteMember, useCapxulOrgMembers, useCapxulOrgRoles, useCapxulOrgTreasury, useCapxulOrganizationPay, useCapxulOrganizationPayBatch, useCapxulOrgs, useCapxulPay, useCapxulPayment, useCapxulPayments, useCapxulPermission, useCapxulPermissionAssign, useCapxulPermissionChange, useCapxulPermissionCreate, useCapxulPermissionReplace, useCapxulPermissionRevoke, useCapxulPermissions, useCapxulProfile, useCapxulRedirectPayment, useCapxulSend, useCapxulTransitions, useCapxulUsernameAvailability };
+export { type AccountFailure, type AccountProgress, type ActionResult, type ActivityDetailSlice, type ActivityExportSlice, type ActivityFilterValues, type ActivityFiltersSlice, type ActivityLoadMoreSlice, type ActivityReceipt, type ActivityRow, type ActivityRowsSlice, type ActivitySearchSlice, type ActivitySummarySlice, type AuthenticatedState, type AuthenticationSlots, type CanReason, CapxulActivity, type CapxulActivityProps, type CapxulAuth, CapxulAuthenticationController, type CapxulBootstrapState, type CapxulBootstrapStatus, CapxulContacts, type CapxulContactsProps, CapxulDashboardAccess, type CapxulDashboardAccessProps, CapxulOnboardingController, CapxulOrgMember, type CapxulOrgMemberProps, CapxulPayroll, type CapxulPayrollProps, CapxulPayrollRun, type CapxulPayrollRunBlockedReason, type CapxulPayrollRunProps, CapxulProvider, type CapxulProviderProps, type CapxulSend, CapxulSendMoney, type CapxulSendMoneyBlockedReason, type CapxulSendMoneyProps, type Contact, type ContactRelationship, type ContactRow, type ContactsActor, type ContactsAddBlockedReason, type ContactsAddError, type ContactsAddSlice, type ContactsListOptions, type ContactsListSlice, type ContactsRefusal, type ContactsSummarySlice, type ControllerAction, type CreateOrganizationFailure, type CreateOrganizationSubmission, type CsvExport, type DashboardAccessErrorSlice, type DashboardAccessPhase, type DashboardAccessRedirectSlice, type DashboardScope, type Destination, type FaultedState, type HandleAvailability, type ImageUploadInput, type ImageUploadTarget, type InvocationOptions, type NavigationAction, type OnboardingControllerProps, type OnboardingIntent, type OnboardingJourney, type OnboardingJourneyPosition, type OnboardingOrigin, type OnboardingStep, type OrgFailure, type OrgMemberAction, type OrgMemberCanSlice, type OrgMemberStanding, type OrgMemberStandingSlice, type OrgProgress, type OrganizationDetails, type OrganizationDraft, type OtpPendingState, type PayoutDraftChain, type PayoutDraftEntry, type PayrollGroupRow, type PayrollGroupsSlice, type PayrollRecipientOption, type PayrollRunActionsSlice, type PayrollRunAmountEntry, type PayrollRunAmountsSlice, type PayrollRunAssetSlice, type PayrollRunGroupOption, type PayrollRunPrefill, type PayrollRunRecipientsSlice, type PayrollRunStatus, type PayrollRunSummarySlice, type PayrollSummarySlice, type PendingAuthState, type ProfileDetails, type ProfileDraft, type ProfileSlotProps, type ReadyDestination, type RetryAction, type SendActor, type SendMoneyActionsSlice, type SendMoneyAmountSlice, type SendMoneyAssetError, type SendMoneyAssetOption, type SendMoneyAssetSlice, type SendMoneyRecipientSlice, type SendMoneyRecipientStatus, type SendMoneySourceError, type SendMoneySourceOption, type SendMoneySourceSlice, type SendResult, type SentPayment, type SentPayrollRun, type SignedOutState, type Slot, type SummaryWindow, type UseCapxulAccountBalanceOptions, type UseCapxulAccountBalanceReturn, type UseCapxulAccountFundReturn, type UseCapxulCreateCommitmentReturn, type UseCapxulCreateOrgReturn, type UseCapxulHandleAvailabilityReturn, type UseCapxulImageUploadReturn, type UseCapxulInviteMemberReturn, type UseCapxulOrgMembersOptions, type UseCapxulOrgMembersReturn, type UseCapxulOrgRolesOptions, type UseCapxulOrgRolesReturn, type UseCapxulOrgTreasuryOptions, type UseCapxulOrgTreasuryReturn, type UseCapxulOrgsReturn, type UseCapxulPayReturn, type UseCapxulPaymentReturn, type UseCapxulPaymentsReturn, type UseCapxulProfileReturn, type UseCapxulRedirectPaymentReturn, acknowledgeOnboardingDestination, activeOnboardingRecovery, capxulKeys, clearOnboardingJourney, currentOnboardingJourneyId, entered, invalidateOnboardingJourneyObservation, isClaimed, isRestoring, loadOnboardingJourney, onboardingJourneyPosition, saveOnboardingJourney, startOnboardingJourney, useCapxul, useCapxulAccountBalance, useCapxulAccountFund, useCapxulActivity, useCapxulActivityDetail, useCapxulAnnotateMovement, useCapxulAuth, useCapxulCancelPayment, useCapxulClaimPayment, useCapxulClientOrNull, useCapxulCreateCommitment, useCapxulCreateOrg, useCapxulDestination, useCapxulHandleAvailability, useCapxulHoldings, useCapxulIdentity, useCapxulImageUpload, useCapxulInviteMember, useCapxulOrgMembers, useCapxulOrgRoles, useCapxulOrgTreasury, useCapxulOrganizationPay, useCapxulOrganizationPayBatch, useCapxulOrgs, useCapxulPay, useCapxulPayment, useCapxulPayments, useCapxulPermission, useCapxulPermissionAssign, useCapxulPermissionChange, useCapxulPermissionCreate, useCapxulPermissionReplace, useCapxulPermissionRevoke, useCapxulPermissions, useCapxulProfile, useCapxulRedirectPayment, useCapxulSend, useCapxulTransitions };

package/dist/index.mjs

@@ -1,8 +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-BkL0hHuk.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-BgkCs0nW.mjs";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { CapxulError, Errors, PAYMENT_DIRECTIONS, PAYMENT_STATUSES, fingerprintPaymentIntent, formatMoney, isCapxulError, isClaimed, isClaimed as isClaimed$1, isMoneyParseError, isRestoring, isRestoring as isRestoring$1, parseMoney, paymentPhase, resolveIdentityDestination } from "@capxul/sdk";
+import { CAPXUL_OPERATIONS, CapxulError, EVM_ADDRESS_RE, Errors, HANDLE_RE, PAYMENT_DIRECTIONS, PAYMENT_STATUSES, fingerprintPaymentIntent, formatMoney, isCapxulError, isClaimed, isClaimed as isClaimed$1, isMoneyParseError, isRestoring, isRestoring as isRestoring$1, parseMoney, paymentPhase, resolveIdentityDestination, toEvmAddress, toPartyId } from "@capxul/sdk";
 import { Fragment, jsx } from "react/jsx-runtime";
 //#region src/internal/require-bootstrapped-client.ts
 /**
@@ -38,8 +38,8 @@ function useCapxulProfile() {
 	const client = useCapxulClientOrNull();
 	const identity = useCapxulIdentityOrNull();
 	return useQuery({
-		queryKey: capxulKeys.profile,
-		queryFn: async () => unwrapCapxulResult(await requireBootstrappedClient(client, "identity.loadCurrent").identity.loadCurrent()),
+		queryKey: [...capxulKeys.profile, identity?.phase === "authenticated" ? identity.session.authUserId : null],
+		queryFn: async () => unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.identity.loadCurrent).identity.loadCurrent()),
 		enabled: client !== null && identity?.phase === "authenticated"
 	});
 }
@@ -50,7 +50,7 @@ function useCapxulAccountBalance(options) {
 	return useQuery({
 		queryKey: capxulKeys.accountBalance,
 		queryFn: async () => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "accounts.read").accounts.read());
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.accounts.read).accounts.read());
 		},
 		enabled: client !== null && (options?.enabled ?? true)
 	});
@@ -62,7 +62,7 @@ function useCapxulAccountFund() {
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (amount) => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "_internal.accounts.fund")._internal.accounts.fund(amount));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS._internal.accounts.fund)._internal.accounts.fund(amount));
 		},
 		onSuccess: async () => {
 			await queryClient.invalidateQueries({ queryKey: capxulKeys.accountBalance });
@@ -238,8 +238,8 @@ function useCapxulPay() {
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (input) => {
-			rejectUnresolvedActor(input, "payments.pay");
-			const bootstrappedClient = requireBootstrappedClient(client, "payments.pay");
+			rejectUnresolvedActor(input, CAPXUL_OPERATIONS.payments.pay);
+			const bootstrappedClient = requireBootstrappedClient(client, CAPXUL_OPERATIONS.payments.pay);
 			return withPaymentRequestKey("personal-pay", {
 				actorId,
 				backendScope,
@@ -262,7 +262,7 @@ function useCapxulCreateCommitment() {
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (input) => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "payments.createCommitment").payments.createCommitment(input));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.payments.createCommitment).payments.createCommitment(input));
 		},
 		onSuccess: (payment) => invalidateMoneyState(queryClient, {
 			actor: { kind: "personal" },
@@ -290,7 +290,7 @@ function useCapxulRedirectPayment() {
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (input) => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "payments.redirect").payments.redirect(input));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.payments.redirect).payments.redirect(input));
 		},
 		onSuccess: (payment) => invalidateMoneyState(queryClient, {
 			actor: { kind: "personal" },
@@ -304,7 +304,7 @@ function useCapxulPayments(options) {
 	return useQuery({
 		queryKey: capxulKeys.payments,
 		queryFn: async () => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "payments.list").payments.list());
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.payments.list).payments.list());
 		},
 		enabled: client !== null && identity !== null && isClaimed$1(identity) && (options?.enabled ?? true)
 	});
@@ -315,7 +315,7 @@ function useCapxulPayment(paymentId, options) {
 		queryKey: capxulKeys.payment(paymentId),
 		queryFn: async () => {
 			if (paymentId === void 0) throw Errors.invalidInput("paymentId", "required for payments.get");
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "payments.get").payments.get(paymentId));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.payments.get).payments.get(paymentId));
 		},
 		enabled: client !== null && paymentId !== void 0 && (options?.enabled ?? true)
 	});
@@ -335,7 +335,7 @@ function useCapxulOrganizationPay(orgId) {
 	return useMutation({
 		mutationFn: async (input) => {
 			if (orgId === void 0) throw Errors.invalidInput("orgId", "required for useCapxulOrganizationPay");
-			const bootstrapped = requireBootstrappedClient(client, "organizationPayments.pay");
+			const bootstrapped = requireBootstrappedClient(client, CAPXUL_OPERATIONS.organizationPayments.pay);
 			return withPaymentRequestKey("organization-pay", {
 				backendScope,
 				orgId,
@@ -363,7 +363,7 @@ function useCapxulOrganizationPayBatch(orgId) {
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (input) => {
-			const bootstrapped = requireBootstrappedClient(client, "organizationPayments.payBatch");
+			const bootstrapped = requireBootstrappedClient(client, CAPXUL_OPERATIONS.organizationPayments.payBatch);
 			return withPaymentRequestKey("organization-pay-batch", {
 				backendScope,
 				orgId,
@@ -391,7 +391,7 @@ function usePermissionMutation(orgId, operation) {
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (input) => {
-			const method = requireBootstrappedClient(client, `permissions.${operation}`).org(orgId).permissions[operation];
+			const method = requireBootstrappedClient(client, CAPXUL_OPERATIONS.permissions[operation]).org(orgId).permissions[operation];
 			return unwrapCapxulResult(await method(input));
 		},
 		onSuccess: () => queryClient.invalidateQueries({ queryKey: capxulKeys.orgPermissions(orgId) })
@@ -408,7 +408,7 @@ function useCapxulPermissions(orgId, options) {
 	return useQuery({
 		queryKey: capxulKeys.orgPermissions(orgId),
 		queryFn: async () => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "permissions.list").org(orgId).permissions.list());
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.permissions.list).org(orgId).permissions.list());
 		},
 		enabled: client !== null && identity !== null && isClaimed$1(identity) && (options?.enabled ?? true)
 	});
@@ -419,7 +419,7 @@ function useCapxulPermission(orgId, permissionId) {
 		queryKey: [...capxulKeys.orgPermissions(orgId), permissionId ?? "pending"],
 		queryFn: async () => {
 			if (permissionId === void 0) throw Errors.invalidInput("permissionId", "required for permissions.get");
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "permissions.get").org(orgId).permissions.get(permissionId));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.permissions.get).org(orgId).permissions.get(permissionId));
 		},
 		enabled: client !== null && permissionId !== void 0
 	});
@@ -432,7 +432,7 @@ function useCapxulActivity(params) {
 	return useQuery({
 		queryKey: [...capxulKeys.activity, params ?? {}],
 		queryFn: async () => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "activity.list").activity.list(params));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.list).activity.list(params));
 		},
 		enabled: client !== null && identity !== null && isClaimed$1(identity)
 	});
@@ -444,7 +444,7 @@ function useCapxulActivityDetail(reference, actor) {
 		queryKey: capxulKeys.activityDetail(reference, actor),
 		queryFn: async () => {
 			if (reference === void 0) throw Errors.invalidInput("reference", "required for activity.get");
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "activity.get").activity.get(reference, actor === void 0 ? void 0 : { actor }));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.get).activity.get(reference, actor === void 0 ? void 0 : { actor }));
 		},
 		enabled: client !== null && reference !== void 0 && identity !== null && isClaimed$1(identity)
 	});
@@ -454,7 +454,7 @@ function useCapxulAnnotateMovement() {
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async (input) => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "activity.annotate").activity.annotate(input));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.annotate).activity.annotate(input));
 		},
 		onSuccess: () => queryClient.invalidateQueries({ queryKey: capxulKeys.activity })
 	});
@@ -468,7 +468,7 @@ function useCapxulHoldings(params) {
 	return useQuery({
 		queryKey: capxulKeys.holdings(actor),
 		queryFn: async () => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "holdings.current").holdings.current(actor === void 0 ? void 0 : { actor }));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.holdings.current).holdings.current(actor === void 0 ? void 0 : { actor }));
 		},
 		enabled: client !== null && identity !== null && isClaimed$1(identity)
 	});
@@ -494,7 +494,7 @@ function useCapxulOrgMembers(orgId, options) {
 		queryKey: capxulKeys.orgMembers(orgId),
 		queryFn: async () => {
 			if (orgId === void 0) throw Errors.invalidInput("orgId", "required for useCapxulOrgMembers");
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "org.members").org(orgId).members());
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.org.members).org(orgId).members());
 		},
 		enabled: client !== null && enabled && orgId !== void 0
 	});
@@ -508,7 +508,7 @@ function useCapxulOrgRoles(orgId, options) {
 		queryKey: capxulKeys.orgRoles(orgId),
 		queryFn: async () => {
 			if (orgId === void 0) throw Errors.invalidInput("orgId", "required for useCapxulOrgRoles");
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "org.roles").org(orgId).roles());
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.org.roles).org(orgId).roles());
 		},
 		enabled: client !== null && enabled && orgId !== void 0
 	});
@@ -522,7 +522,7 @@ function useCapxulOrgTreasury(orgId, options) {
 		queryKey: capxulKeys.orgTreasury(orgId),
 		queryFn: async () => {
 			if (orgId === void 0) throw Errors.invalidInput("orgId", "required for useCapxulOrgTreasury");
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "org.treasury").org(orgId).treasury());
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.org.treasury).org(orgId).treasury());
 		},
 		enabled: client !== null && enabled && orgId !== void 0
 	});
@@ -549,7 +549,7 @@ function useCapxulInviteMember(orgId) {
 	return useMutation({
 		mutationFn: async (input) => {
 			if (orgId === void 0) throw Errors.invalidInput("orgId", "required for useCapxulInviteMember");
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "org.invite").org(orgId).invite(input));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.org.invite).org(orgId).invite(input));
 		},
 		onSuccess: async () => {
 			if (orgId === void 0) return;
@@ -733,10 +733,10 @@ function isProfileDraft(value) {
 		"displayName",
 		"country",
 		"withdrawalAddress",
-		"username",
+		"handle",
 		"payoutAddresses"
 	]) || !isDraftText(value.displayName) || !isDraftText(value.country) || !isDraftText(value.withdrawalAddress)) return false;
-	if (value.username !== void 0 && !isDraftText(value.username)) return false;
+	if (value.handle !== void 0 && !isDraftText(value.handle)) return false;
 	if (value.payoutAddresses !== void 0 && !isPayoutDraftList(value.payoutAddresses)) return false;
 	return true;
 }
@@ -790,21 +790,21 @@ function useDebouncedValue(value, delayMs) {
 	return debounced;
 }
 //#endregion
-//#region src/headless/onboarding/use-capxul-username-availability.ts
+//#region src/headless/onboarding/use-capxul-handle-availability.ts
 /**
-* #1062: debounced availability probe for the username the user is typing.
+* #1062: debounced availability probe for the handle 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
+* boundary's message), not as `available: false` — only a handle someone
 * else owns is "taken".
 */
-function useCapxulUsernameAvailability(username, options) {
+function useCapxulHandleAvailability(handle, options) {
 	const client = useCapxulClientOrNull();
-	const candidate = useDebouncedValue(username.trim(), options?.debounceMs ?? 300);
+	const candidate = useDebouncedValue(handle.trim(), options?.debounceMs ?? 300);
 	return useQuery({
-		queryKey: capxulKeys.usernameAvailability(candidate),
+		queryKey: capxulKeys.handleAvailability(candidate),
 		queryFn: async () => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "identity.usernameAvailable").identity.usernameAvailable(candidate));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.identity.handleAvailable).identity.handleAvailable(candidate));
 		},
 		enabled: client !== null && candidate.length >= 3 && (options?.enabled ?? true)
 	});
@@ -822,7 +822,7 @@ function useCapxulImageUpload() {
 	const queryClient = useQueryClient();
 	return useMutation({
 		mutationFn: async ({ blob, target }) => {
-			const media = requireBootstrappedClient(client, "media.uploadImage").media;
+			const media = requireBootstrappedClient(client, CAPXUL_OPERATIONS.media.uploadImage).media;
 			const uploaded = unwrapCapxulResult(await media.uploadImage(blob));
 			if (target.kind === "profile") return { url: unwrapCapxulResult(await media.setProfileImage({ storageId: uploaded.storageId })).imageUrl };
 			return { url: unwrapCapxulResult(await media.setOrgLogo({
@@ -864,7 +864,7 @@ function useContacts(input) {
 	const [value, setValue] = useState("");
 	const [addError, setAddError] = useState(null);
 	const addContact = useMutation({
-		mutationFn: async (ref) => unwrapCapxulResult(await requireBook(book, "addressBook.add").add({ ref })),
+		mutationFn: async (ref) => unwrapCapxulResult(await requireBook(book, CAPXUL_OPERATIONS.addressBook.add).add({ ref })),
 		onSettled: invalidate
 	});
 	const addMutate = addContact.mutate;
@@ -935,7 +935,7 @@ function useContactsList(engine, options) {
 	const { book, refusal } = engine;
 	const query = useQuery({
 		queryKey: capxulKeys.contactsList(engine.scope, includeHidden),
-		queryFn: async () => unwrapCapxulResult(await requireBook(book, "addressBook.list").list({ includeHidden })),
+		queryFn: async () => unwrapCapxulResult(await requireBook(book, CAPXUL_OPERATIONS.addressBook.list).list({ includeHidden })),
 		enabled: book !== null
 	});
 	const reason = refusal ?? (query.isError ? "unavailable" : query.data === void 0 ? "loading" : null);
@@ -1128,7 +1128,7 @@ function useActivityDetail(reference, actor) {
 		queryKey: capxulKeys.activityDetail(reference, actor),
 		queryFn: async () => {
 			if (reference === void 0) throw Errors.invalidInput("reference", "required for activity.get");
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "activity.get").activity.get(reference, actor === void 0 ? void 0 : { actor }));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.get).activity.get(reference, actor === void 0 ? void 0 : { actor }));
 		},
 		enabled
 	});
@@ -1138,7 +1138,7 @@ function useActivityDetail(reference, actor) {
 		if (reference === void 0 || receiptDocument === null) throw Errors.invalidInput("receiptDocument", "no renderable document on this row");
 		setIsOpeningDocument(true);
 		try {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "paymentDocuments.render").paymentDocuments.render(receiptDocument.documentHash));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.paymentDocuments.render).paymentDocuments.render(receiptDocument.documentHash));
 		} finally {
 			setIsOpeningDocument(false);
 		}
@@ -1280,14 +1280,14 @@ function useActivitySummary(actor, window) {
 			const params = {};
 			if (actor !== void 0) params.actor = actor;
 			if (range !== void 0) params.window = range;
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "activity.summary").activity.summary(params));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.summary).activity.summary(params));
 		},
 		enabled
 	});
 	const primary = useQuery({
 		queryKey: [...capxulKeys.holdings(actor), "primary"],
 		queryFn: async () => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "holdings.primary").holdings.primary(actor === void 0 ? void 0 : { actor }));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.holdings.primary).holdings.primary(actor === void 0 ? void 0 : { actor }));
 		},
 		enabled
 	});
@@ -1329,7 +1329,7 @@ function useActivitySummary(actor, window) {
 //#region src/headless/activity/rows.ts
 /**
 * A Movement's phase is DERIVED, not asserted: `movementItems` returns `null`
-* for any Movement whose `canonicalState` is not `"finalized"`
+* for any Movement whose `canonicalState` is not `"included"`
 * (`activityList.ts:120`), so a Movement that reaches a page is finished and
 * carries no verdict of its own.
 */
@@ -1526,7 +1526,7 @@ function useActivity(input) {
 			filter ?? "none"
 		],
 		queryFn: async ({ pageParam }) => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "activity.list").activity.list(listParams(pageParam, limit)));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.list).activity.list(listParams(pageParam, limit)));
 		},
 		initialPageParam: void 0,
 		getNextPageParam: (last) => last.cursor ?? void 0,
@@ -1577,7 +1577,7 @@ function useActivity(input) {
 	const toCsv = useCallback(async () => {
 		setIsExporting(true);
 		try {
-			const bootstrapped = requireBootstrappedClient(client, "activity.list");
+			const bootstrapped = requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.list);
 			const items = [];
 			let cursor;
 			for (let page = 0; page < EXPORT_PAGE_CEILING; page += 1) {
@@ -1723,7 +1723,7 @@ function useOrgMeReading(orgId) {
 	const query = useQuery({
 		queryKey: capxulKeys.orgMe(orgId),
 		queryFn: async () => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "org.me").org(orgId).me());
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.org.me).org(orgId).me());
 		},
 		enabled: ready && orgId !== void 0
 	});
@@ -1753,67 +1753,126 @@ function useSignerStatus(client) {
 }
 //#endregion
 //#region src/headless/send-money/use-recipient-resolution.ts
-function toTargetReference(method, text) {
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const PARTY_ID_RE = /^party_[0-9A-Za-z]+$/;
+const RESOLVE_DEBOUNCE_MS = 400;
+function parseRecipient(text) {
 	const trimmed = text.trim();
-	if (trimmed === "") return null;
-	return method === "username" ? {
-		kind: "handle",
-		handle: trimmed.replace(/^@/, "")
-	} : {
-		kind: "email",
-		email: trimmed
+	if (trimmed === "") return { status: "empty" };
+	if (PARTY_ID_RE.test(trimmed)) return {
+		status: "valid",
+		reference: {
+			kind: "party",
+			partyId: toPartyId(trimmed)
+		}
 	};
+	if (EVM_ADDRESS_RE.test(trimmed)) return {
+		status: "valid",
+		reference: {
+			kind: "address",
+			address: toEvmAddress(trimmed)
+		}
+	};
+	if (EMAIL_RE.test(trimmed)) return {
+		status: "valid",
+		reference: {
+			kind: "email",
+			email: trimmed.toLowerCase()
+		}
+	};
+	const handle = trimmed.replace(/^@/, "").toLowerCase();
+	if (HANDLE_RE.test(handle)) return {
+		status: "valid",
+		reference: {
+			kind: "handle",
+			handle
+		}
+	};
+	return { status: "invalid" };
 }
-/** How long the engine waits after the last keystroke before resolving. */
-const RESOLVE_DEBOUNCE_MS = 400;
-function useRecipientResolution(client) {
-	const [method, setMethodState] = useState("email-address");
+function sameReference(left, right) {
+	return JSON.stringify(left) === JSON.stringify(right);
+}
+function publicRecipientValue(value) {
+	if (value === null) return null;
+	if (value.status === "known_party") return value.handle ?? value.label;
+	return value.status === "external_address" ? value.safeAddress : null;
+}
+function recipientStatus(parsed, settled, acknowledged) {
+	if (parsed.status === "empty" || parsed.status === "invalid") return parsed.status;
+	if (settled === null) return "checking";
+	if (!settled.ok) return settled.error.code === "INVALID_INPUT" ? "not-found" : "failed";
+	if (settled.value.status === "known_party") return "known-party";
+	if (settled.value.status === "new_email") return "new-email";
+	return acknowledged ? "external-ready" : "external-warning";
+}
+function useRecipientResolution(client, scope, organizationId) {
 	const [text, setText] = useState("");
-	const reference = useMemo(() => toTargetReference(method, text), [method, text]);
+	const parsed = useMemo(() => parseRecipient(text), [text]);
+	const reference = parsed.status === "valid" ? parsed.reference : null;
 	const debouncedReference = useDebouncedValue(reference, RESOLVE_DEBOUNCE_MS);
+	const debouncedText = useDebouncedValue(text, RESOLVE_DEBOUNCE_MS);
 	const [outcome, setOutcome] = useState(null);
+	const [acknowledgedOutcome, setAcknowledgedOutcome] = useState(null);
+	const capturedAcknowledgement = useRef(null);
+	const change = useCallback((next) => {
+		if (next === text) return;
+		setAcknowledgedOutcome(null);
+		setOutcome(null);
+		setText(next);
+	}, [text]);
 	useEffect(() => {
 		if (debouncedReference === null || client === null) {
 			setOutcome(null);
 			return;
 		}
 		const controller = new AbortController();
-		setOutcome({
-			reference: debouncedReference,
-			status: "checking",
-			label: null
-		});
+		setOutcome(null);
 		client.targets.resolve(debouncedReference, { signal: controller.signal }).then((result) => {
-			if (controller.signal.aborted) return;
-			setOutcome(result.ok ? {
-				reference: debouncedReference,
-				status: "found",
-				label: result.value.label
-			} : {
-				reference: debouncedReference,
-				status: result.error.code === "INVALID_INPUT" ? "not-found" : "failed",
-				label: null
+			if (!controller.signal.aborted) setOutcome({
+				client,
+				scope,
+				text: debouncedText,
+				input: debouncedReference,
+				result
 			});
 		});
 		return () => controller.abort();
-	}, [client, debouncedReference]);
-	const setMethod = useCallback((next) => {
-		setMethodState(next);
-		setText("");
-	}, []);
-	const settled = outcome !== null && outcome.reference === debouncedReference ? outcome : null;
-	const status = reference === null ? "empty" : reference !== debouncedReference || settled === null ? "checking" : settled.status;
-	const resolvedReference = status === "found" ? settled?.reference ?? null : null;
+	}, [
+		client,
+		scope,
+		debouncedReference,
+		debouncedText
+	]);
+	const settled = reference !== null && debouncedReference !== null && outcome !== null && outcome.client === client && outcome.scope === scope && outcome.text === text && sameReference(reference, debouncedReference) && sameReference(outcome.input, debouncedReference) ? outcome.result : null;
+	const status = recipientStatus(parsed, settled, acknowledgedOutcome === outcome);
+	const ready = settled?.ok === true && (settled.value.status !== "external_address" || status === "external-ready");
+	const value = settled?.ok === true ? settled.value : null;
+	const acknowledgeExternalAddress = useCallback(() => {
+		if (value?.status !== "external_address" || outcome === null) return;
+		setAcknowledgedOutcome(outcome);
+		if (capturedAcknowledgement.current === outcome) return;
+		capturedAcknowledgement.current = outcome;
+		client?._internal.captureExternalAddressAcknowledged(value.safeAddress, organizationId);
+	}, [
+		client,
+		organizationId,
+		value,
+		outcome
+	]);
 	return {
 		slice: {
-			method,
-			setMethod,
 			value: text,
-			change: setText,
+			change,
 			status,
-			label: status === "found" ? settled?.label ?? null : null
+			label: value?.label ?? null,
+			kind: value?.kind ?? null,
+			isCapxulAccount: value?.isCapxulAccount ?? null,
+			publicValue: publicRecipientValue(value),
+			requiresAcknowledgement: status === "external-warning",
+			acknowledgeExternalAddress
 		},
-		resolvedReference,
+		resolvedReference: ready && value !== null ? value.reference : null,
 		trimmed: text.trim()
 	};
 }
@@ -1858,7 +1917,11 @@ function useSendMoney(input) {
 	const parsed = useMemo(() => selectedAssetMoney === null || amountText.trim() === "" ? null : parseMoney(amountText, selectedAssetMoney), [amountText, selectedAssetMoney]);
 	const parsedMoney = parsed !== null && !isMoneyParseError(parsed) ? parsed : null;
 	const amountError = parsed !== null && isMoneyParseError(parsed) ? parsed.reason : null;
-	const recipient = useRecipientResolution(client);
+	const recipient = useRecipientResolution(client, JSON.stringify([
+		actor.kind,
+		orgId,
+		account?.id
+	]), orgId);
 	const resolvedReference = recipient.resolvedReference;
 	const personalPay = useCapxulPay();
 	const organizationPay = useCapxulOrganizationPay(orgId);
@@ -1870,6 +1933,7 @@ function useSendMoney(input) {
 		if (parsedMoney === null || resolvedReference === null) return;
 		const amount = parsedMoney;
 		const sentRecipient = recipient.trimmed;
+		const externalAddressAcknowledged = recipient.slice.status === "external-ready";
 		const callbacks = {
 			onSuccess: (payment) => onSent({
 				payment,
@@ -1885,7 +1949,8 @@ function useSendMoney(input) {
 			submitGate.current = true;
 			personalPay.mutate({
 				to: resolvedReference,
-				amount
+				amount,
+				...externalAddressAcknowledged ? { externalAddressAcknowledged: true } : {}
 			}, callbacks);
 			return;
 		}
@@ -1894,7 +1959,8 @@ function useSendMoney(input) {
 		organizationPay.mutate({
 			permissionId: selectedSource.id,
 			to: resolvedReference,
-			amount
+			amount,
+			...externalAddressAcknowledged ? { externalAddressAcknowledged: true } : {}
 		}, callbacks);
 	}, [
 		actor.kind,
@@ -1905,6 +1971,7 @@ function useSendMoney(input) {
 		parsedMoney,
 		personalPay,
 		recipient.trimmed,
+		recipient.slice.status,
 		resolvedReference,
 		selectedSource
 	]);
@@ -2175,7 +2242,7 @@ function useDashboardAccess(scope) {
 	const lifecycle = useQuery({
 		queryKey: capxulKeys.orgLifecycle(orgId),
 		queryFn: async () => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "org.getLifecycle").org(orgId).getLifecycle());
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.org.getLifecycle).org(orgId).getLifecycle());
 		},
 		enabled: wantsLifecycle && client !== null
 	});
@@ -2337,7 +2404,7 @@ function useOrgRoster(orgId) {
 	const client = useCapxulClientOrNull();
 	const query = useQuery({
 		queryKey: capxulKeys.contactsList(orgId ?? "pending", false),
-		queryFn: async () => unwrapCapxulResult(await scopedClient(client, "org.addressBook.list", orgId).addressBook.list({ includeHidden: false })),
+		queryFn: async () => unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.addressBook.list, orgId).addressBook.list({ includeHidden: false })),
 		enabled: client !== null && orgId !== void 0
 	});
 	const entries = query.data;
@@ -2359,7 +2426,7 @@ function usePayrollGroups(orgId) {
 	const client = useCapxulClientOrNull();
 	return useQuery({
 		queryKey: capxulKeys.payrollGroups(orgId),
-		queryFn: async () => unwrapCapxulResult(await scopedClient(client, "org.payroll.groups.list", orgId).payroll.groups.list()),
+		queryFn: async () => unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.payroll.groups.list, orgId).payroll.groups.list()),
 		enabled: client !== null && orgId !== void 0
 	});
 }
@@ -2367,7 +2434,7 @@ function usePayrollRuns(orgId) {
 	const client = useCapxulClientOrNull();
 	return useQuery({
 		queryKey: capxulKeys.payrollRuns(orgId),
-		queryFn: async () => unwrapCapxulResult(await scopedClient(client, "org.payroll.runs", orgId).payroll.runs()),
+		queryFn: async () => unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.payroll.runs, orgId).payroll.runs()),
 		enabled: client !== null && orgId !== void 0
 	});
 }
@@ -2383,7 +2450,7 @@ function useOrgTerms(orgId) {
 	const client = useCapxulClientOrNull();
 	return useQuery({
 		queryKey: capxulKeys.payrollTerms(orgId),
-		queryFn: async () => unwrapCapxulResult(await scopedClient(client, "org.payroll.terms", orgId).payroll.terms()),
+		queryFn: async () => unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.payroll.terms, orgId).payroll.terms()),
 		enabled: client !== null && orgId !== void 0
 	});
 }
@@ -2391,7 +2458,7 @@ function useOrgTreasury(orgId) {
 	const client = useCapxulClientOrNull();
 	return useQuery({
 		queryKey: capxulKeys.orgTreasury(orgId),
-		queryFn: async () => unwrapCapxulResult(await scopedClient(client, "org.treasury", orgId).treasury()),
+		queryFn: async () => unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.treasury, orgId).treasury()),
 		enabled: client !== null && orgId !== void 0
 	});
 }
@@ -2404,7 +2471,7 @@ function useOrgMe(orgId) {
 	const client = useCapxulClientOrNull();
 	return useQuery({
 		queryKey: capxulKeys.orgMe(orgId),
-		queryFn: async () => unwrapCapxulResult(await scopedClient(client, "org.me", orgId).me()),
+		queryFn: async () => unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.me, orgId).me()),
 		enabled: client !== null && orgId !== void 0
 	});
 }
@@ -2460,7 +2527,7 @@ function usePayroll(orgId) {
 	const invalidate = useCallback(() => queryClient.invalidateQueries({ queryKey: capxulKeys.payrollGroups(orgId) }), [orgId, queryClient]);
 	const write = useMutation({
 		mutationFn: async (command) => {
-			const payroll = scopedClient(client, `org.payroll.groups.${command.kind}`, orgId).payroll;
+			const payroll = scopedClient(client, CAPXUL_OPERATIONS.org.payroll.groups[command.kind], orgId).payroll;
 			if (command.kind === "remove") {
 				unwrapCapxulResult(await payroll.groups.remove(command.id));
 				return null;
@@ -2811,7 +2878,7 @@ function usePayrollRun(input) {
 	const authorize = useMutation({
 		mutationFn: async (command) => {
 			const runAt = Date.now();
-			return unwrapCapxulResult(await scopedClient(client, "org.payroll.authorizeRun", orgId).payroll.authorizeRun({
+			return unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.payroll.authorizeRun, orgId).payroll.authorizeRun({
 				permissionId: command.permissionId,
 				period: {
 					start: runAt,
@@ -2968,4 +3035,4 @@ const CapxulPayrollRun = Object.assign(Root, {
 	Actions
 });
 //#endregion
-export { CapxulActivity, CapxulAuthenticationController, CapxulContacts, CapxulDashboardAccess, CapxulOnboardingController, CapxulOrgMember, CapxulPayroll, CapxulPayrollRun, CapxulProvider, CapxulSendMoney, acknowledgeOnboardingDestination, activeOnboardingRecovery, capxulKeys, clearOnboardingJourney, currentOnboardingJourneyId, entered, invalidateOnboardingJourneyObservation, isClaimed, isRestoring, loadOnboardingJourney, onboardingJourneyPosition, saveOnboardingJourney, startOnboardingJourney, useCapxul, useCapxulAccountBalance, useCapxulAccountFund, useCapxulActivity, useCapxulActivityDetail, useCapxulAnnotateMovement, useCapxulAuth, useCapxulCancelPayment, useCapxulClaimPayment, useCapxulClientOrNull, useCapxulCreateCommitment, useCapxulCreateOrg, useCapxulDestination, useCapxulHoldings, useCapxulIdentity, useCapxulImageUpload, useCapxulInviteMember, useCapxulOrgMembers, useCapxulOrgRoles, useCapxulOrgTreasury, useCapxulOrganizationPay, useCapxulOrganizationPayBatch, useCapxulOrgs, useCapxulPay, useCapxulPayment, useCapxulPayments, useCapxulPermission, useCapxulPermissionAssign, useCapxulPermissionChange, useCapxulPermissionCreate, useCapxulPermissionReplace, useCapxulPermissionRevoke, useCapxulPermissions, useCapxulProfile, useCapxulRedirectPayment, useCapxulSend, useCapxulTransitions, useCapxulUsernameAvailability };
+export { CapxulActivity, CapxulAuthenticationController, CapxulContacts, CapxulDashboardAccess, CapxulOnboardingController, CapxulOrgMember, CapxulPayroll, CapxulPayrollRun, CapxulProvider, CapxulSendMoney, acknowledgeOnboardingDestination, activeOnboardingRecovery, capxulKeys, clearOnboardingJourney, currentOnboardingJourneyId, entered, invalidateOnboardingJourneyObservation, isClaimed, isRestoring, loadOnboardingJourney, onboardingJourneyPosition, saveOnboardingJourney, startOnboardingJourney, useCapxul, useCapxulAccountBalance, useCapxulAccountFund, useCapxulActivity, useCapxulActivityDetail, useCapxulAnnotateMovement, useCapxulAuth, useCapxulCancelPayment, useCapxulClaimPayment, useCapxulClientOrNull, useCapxulCreateCommitment, useCapxulCreateOrg, useCapxulDestination, useCapxulHandleAvailability, useCapxulHoldings, useCapxulIdentity, useCapxulImageUpload, useCapxulInviteMember, useCapxulOrgMembers, useCapxulOrgRoles, useCapxulOrgTreasury, useCapxulOrganizationPay, useCapxulOrganizationPayBatch, useCapxulOrgs, useCapxulPay, useCapxulPayment, useCapxulPayments, useCapxulPermission, useCapxulPermissionAssign, useCapxulPermissionChange, useCapxulPermissionCreate, useCapxulPermissionReplace, useCapxulPermissionRevoke, useCapxulPermissions, useCapxulProfile, useCapxulRedirectPayment, useCapxulSend, useCapxulTransitions };

package/dist/testing/index.d.mts

@@ -1,4 +1,4 @@
-import { a as AuthenticationSlots, d as OnboardingControllerProps } from "../controllers-CJEsthW2.mjs";
+import { a as AuthenticationSlots, d as OnboardingControllerProps } from "../controllers-DIf8elqQ.mjs";
 import * as React from "react";
 import { ReactNode } from "react";
 import { CapxulTestClient, CapxulTestClock, CapxulTestObservation, CreateCapxulTestClientOptions, SeedTestIdentityInput, createCapxulTestClient } from "@capxul/sdk/testing";

package/dist/testing/index.mjs

@@ -1,4 +1,4 @@
-import { n as CapxulOnboardingController, r as CapxulProvider, t as CapxulAuthenticationController } from "../controllers-BkL0hHuk.mjs";
+import { n as CapxulOnboardingController, r as CapxulProvider, t as CapxulAuthenticationController } from "../controllers-BgkCs0nW.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": "3.1.0",
+  "version": "4.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Xelmar-tech/infrastructure.git",
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@capxul/sdk": "3.1.0"
+    "@capxul/sdk": "4.0.0"
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.66.9",
@@ -43,8 +43,8 @@
     "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
     "vite-plus": "0.3.0",
     "vitest": "4.1.11",
-    "@capxul/errors": "0.2.0",
-    "@capxul/types": "0.2.3",
+    "@capxul/errors": "0.3.0",
+    "@capxul/types": "0.3.0",
     "@capxul/typescript-config": "0.0.0"
   },
   "peerDependencies": {