@capxul/sdk 0.1.0-alpha.8 → 0.1.0-alpha.9

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @capxul/sdk
 
+## 0.1.0-alpha.9
+
+### Minor Changes
+
+- Add the canonical auth bootstrap flow.
+
+  `verifyOtp()` now resolves a verified email session into either an
+  `existing_member` identity or a `bootstrap_required` continuation. New and
+  incomplete members continue through `completeBootstrap()`, which validates a
+  server-issued bootstrap token, claims the username, provisions the account/Safe
+  through the backend bootstrap path, and returns the authenticated product
+  identity. The React SDK adds `useAuthBootstrapFlow()` as the typed first-run
+  flow wrapper.
+
 ## 0.1.0-alpha.8
 
 ### Minor Changes

package/dist/{client-ByzDfG98.d.ts → client-ChZrdf3R.d.ts}

@@ -1,7 +1,8 @@
 import { Account as Account$1 } from 'viem';
+import * as xstate from 'xstate';
 import { AnyStateMachine } from 'xstate';
-import { A as AccountId, S as SafeId, c as KycProfileId, b as ExternalAccountId, f as SubAccountId, d as OrganizationId, a as ApiKeyId, X as TimestampIso, D as DocumentId, O as OperationId, P as PaymentId, g as TransferId, k as WithdrawalId, W as WebhookEndpointId, j as WebhookEventId, M as MemberId, K as KybProfileId, V as VirtualAccountId, i as VirtualCardId } from './next-action-DkrwXYay.js';
-import { d as CapxulResult, C as CapxulError } from './errors-QHD5Tlok.js';
+import { A as AccountId, S as SafeId, c as KycProfileId, b as ExternalAccountId, f as SubAccountId, d as OrganizationId, a as ApiKeyId, X as TimestampIso, U as Username, E as Email, D as DocumentId, O as OperationId, P as PaymentId, g as TransferId, k as WithdrawalId, W as WebhookEndpointId, j as WebhookEventId, M as MemberId, K as KybProfileId, V as VirtualAccountId, i as VirtualCardId } from './next-action-DkrwXYay.js';
+import { d as CapxulResult, C as CapxulError$1 } from './errors-QHD5Tlok.js';
 import { A as Account, U as UserIdentifier, a as AccountLookupResult, S as Safe, i as KycProfile, E as ExternalAccount, L as List, v as SubAccount, B as BalanceLedgerEntry, b as ApiKey, a0 as CreateApiKeyRequest, a1 as CreateDocumentRequest, D as Document, O as Operation, l as OperationStatus, k as Money, C as CreatePaymentResult, o as Payment, F as TransferEndpoint, f as CreateTransferResult, y as Transfer, g as CreateWithdrawalResult, _ as Withdrawal, a2 as CreateWebhookEndpointRequest, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, a3 as CreateVirtualAccountRequest, V as VirtualAccount, a4 as CreateVirtualCardRequest, Q as VirtualCard } from './types-PM4AQRLP.js';
 
 /**
@@ -189,6 +190,38 @@ type AuthVerifyOtpInput = {
     readonly email: string;
     readonly otp: string;
 };
+type AuthBootstrapToken = string & {
+    readonly __capxulAuthBootstrapTokenBrand: "AuthBootstrapToken";
+};
+type AuthBootstrapReason = "new_member" | "missing_profile" | "missing_account" | "missing_safe" | "missing_signer_grant";
+type VerifyOtpResult = {
+    readonly kind: "existing_member";
+    readonly session: Session;
+    readonly account: Account;
+    readonly username: Username;
+    readonly safe: Safe;
+} | {
+    readonly kind: "bootstrap_required";
+    readonly session: Session;
+    readonly bootstrapToken: AuthBootstrapToken;
+    readonly email: Email;
+    readonly reason: AuthBootstrapReason;
+    readonly username?: Username;
+};
+type CompleteBootstrapInput = {
+    readonly bootstrapToken: AuthBootstrapToken;
+    readonly username: Username;
+    readonly signerProvider: LocalPrivateKeySignerProvider;
+    readonly displayName?: string;
+    readonly countryCode?: string;
+};
+type CompleteBootstrapResult = {
+    readonly kind: "authenticated";
+    readonly session: Session;
+    readonly account: Account;
+    readonly username: Username;
+    readonly safe: Safe;
+};
 type AuthServiceTokenMintInput = {
     readonly apiKey: string;
     readonly audience?: string;
@@ -211,13 +244,15 @@ type ServiceToken = {
     readonly expiresAt: TimestampIso;
 };
 type SendOtpCodes = "EMAIL_DELIVERY_FAILED" | "INVALID_INPUT" | "RATE_LIMITED" | "NETWORK_ERROR";
-type VerifyOtpCodes = "INVALID_INPUT" | "NOT_AUTHENTICATED" | "RATE_LIMITED" | "NETWORK_ERROR";
+type VerifyOtpCodes = "INVALID_INPUT" | "NOT_AUTHENTICATED" | "RATE_LIMITED" | "OPERATION_TIMEOUT" | "NETWORK_ERROR";
+type CompleteBootstrapCodes = "INVALID_INPUT" | "IDEMPOTENCY_CONFLICT" | "RATE_LIMITED" | "PROFILE_NOT_FOUND" | "SMART_ACCOUNT_MISSING" | "PROVIDER_UNAVAILABLE" | "PROVIDER_REJECTED" | "OPERATION_TIMEOUT" | "NETWORK_ERROR" | "INTERNAL_ERROR";
 type GetSessionCodes = "NETWORK_ERROR";
 type SignOutCodes = "NOT_AUTHENTICATED" | "NETWORK_ERROR";
 type ServiceTokenMintCodes = "API_KEY_INVALID" | "API_KEY_EXPIRED" | "INVALID_INPUT" | "RATE_LIMITED" | "NETWORK_ERROR";
 type AuthClient = {
     readonly sendOtp: (input: AuthSendOtpInput, options?: AuthMethodOptions) => Promise<CapxulResult<void, SendOtpCodes>>;
-    readonly verifyOtp: (input: AuthVerifyOtpInput, options?: AuthMethodOptions) => Promise<CapxulResult<Session, VerifyOtpCodes>>;
+    readonly verifyOtp: (input: AuthVerifyOtpInput, options?: AuthMethodOptions) => Promise<CapxulResult<VerifyOtpResult, VerifyOtpCodes>>;
+    readonly completeBootstrap: (input: CompleteBootstrapInput) => Promise<CapxulResult<CompleteBootstrapResult, CompleteBootstrapCodes>>;
     readonly getSession: () => Promise<CapxulResult<Session | null, GetSessionCodes>>;
     readonly signOut: () => Promise<CapxulResult<void, SignOutCodes>>;
     readonly serviceTokenMint: (input: AuthServiceTokenMintInput) => Promise<CapxulResult<ServiceToken, ServiceTokenMintCodes>>;
@@ -883,7 +918,7 @@ type TransportState = {
     readonly runtime: TransportRuntime;
 } | {
     readonly status: "error";
-    readonly error: CapxulError;
+    readonly error: CapxulError$1;
 };
 type TransportRuntime = {
     readonly authBaseUrl: string;
@@ -1103,6 +1138,161 @@ type VirtualCardsClient = {
     readonly cancel: (virtualCardId: VirtualCardId) => Promise<CapxulResult<VirtualCard, MutateCodes>>;
 };
 
+/**
+ * Unified error type used across the entire stack: backend, SDK, and frontend.
+ * One class, one set of codes, one language.
+ *
+ * Backend throws CapxulError → withErrorBoundary serializes to ConvexError →
+ * SDK deserializes back to CapxulError → frontend routes on err.code.
+ */
+type CapxulErrorCode = "NOT_AUTHENTICATED" | "EMAIL_DELIVERY_FAILED" | "API_KEY_INVALID" | "API_KEY_EXPIRED" | "PROFILE_NOT_FOUND" | "SMART_ACCOUNT_MISSING" | "PLAYER_NOT_FOUND" | "ACCOUNT_NOT_FOUND" | "PROVIDER_ERROR" | "INVALID_INPUT" | "ENV_MISSING" | "NOT_IMPLEMENTED" | "VERIFICATION_REQUIRED" | "INSUFFICIENT_BALANCE" | "INVALID_RECIPIENT" | "TRANSACTION_FAILED" | "RATE_LIMITED" | "NETWORK_ERROR" | "PERMISSION_DENIED" | "IDEMPOTENCY_CONFLICT" | "NOT_FOUND" | "OPERATION_CANCELED" | "OPERATION_TIMEOUT" | "ACTION_REQUIRED" | "KYC_REQUIRED" | "POLICY_DENIED" | "SAFE_NOT_READY" | "PROVIDER_UNAVAILABLE" | "PROVIDER_REJECTED" | "RECONCILIATION_FAILED" | "INTERNAL_ERROR" | "QUOTE_EXPIRED" | "QUOTE_NOT_FOUND" | "UNKNOWN";
+declare class CapxulError extends Error {
+    readonly code: CapxulErrorCode;
+    readonly details?: Record<string, unknown>;
+    readonly correlationId?: string;
+    readonly layer?: string;
+    constructor(code: CapxulErrorCode, message: string, options?: {
+        cause?: unknown;
+        details?: Record<string, unknown>;
+        correlationId?: string;
+        layer?: string;
+    });
+}
+
+type AuthBootstrapFlowError = CapxulError$1 | CapxulError;
+type AuthBootstrapFlowContext = {
+    readonly email: Email | null;
+    readonly code: string | null;
+    readonly username: Username | null;
+    readonly signerProvider: LocalPrivateKeySignerProvider | null;
+    readonly bootstrapToken: AuthBootstrapToken | null;
+    readonly bootstrapReason: AuthBootstrapReason | null;
+    readonly session: Session | null;
+    readonly account: Account | null;
+    readonly safe: Safe | null;
+    readonly error: AuthBootstrapFlowError | null;
+};
+type AuthBootstrapFlowEvent = {
+    readonly type: "ENTER_EMAIL";
+    readonly email: Email;
+} | {
+    readonly type: "REQUEST_OTP";
+} | {
+    readonly type: "ENTER_OTP";
+    readonly code: string;
+} | {
+    readonly type: "VERIFY_OTP";
+} | {
+    readonly type: "ENTER_USERNAME";
+    readonly username: Username;
+} | {
+    readonly type: "ENTER_SIGNER_PROVIDER";
+    readonly signerProvider: LocalPrivateKeySignerProvider;
+} | {
+    readonly type: "COMPLETE_BOOTSTRAP";
+} | {
+    readonly type: "BACK";
+} | {
+    readonly type: "RESET";
+} | {
+    readonly type: "SIGN_OUT";
+};
+declare function createAuthBootstrapFlowMachine(client: CapxulClient): xstate.StateMachine<AuthBootstrapFlowContext, {
+    readonly type: "ENTER_EMAIL";
+    readonly email: Email;
+} | {
+    readonly type: "REQUEST_OTP";
+} | {
+    readonly type: "ENTER_OTP";
+    readonly code: string;
+} | {
+    readonly type: "VERIFY_OTP";
+} | {
+    readonly type: "ENTER_USERNAME";
+    readonly username: Username;
+} | {
+    readonly type: "ENTER_SIGNER_PROVIDER";
+    readonly signerProvider: LocalPrivateKeySignerProvider;
+} | {
+    readonly type: "COMPLETE_BOOTSTRAP";
+} | {
+    readonly type: "BACK";
+} | {
+    readonly type: "RESET";
+} | {
+    readonly type: "SIGN_OUT";
+}, {
+    [x: string]: xstate.ActorRefFromLogic<xstate.PromiseActorLogic<void, void, xstate.EventObject>> | xstate.ActorRefFromLogic<xstate.PromiseActorLogic<void, {
+        email: Email;
+    }, xstate.EventObject>> | xstate.ActorRefFromLogic<xstate.PromiseActorLogic<VerifyOtpResult, {
+        email: Email;
+        code: string;
+    }, xstate.EventObject>> | xstate.ActorRefFromLogic<xstate.PromiseActorLogic<CompleteBootstrapResult, {
+        bootstrapToken: AuthBootstrapToken;
+        username: Username;
+        signerProvider: LocalPrivateKeySignerProvider;
+    }, xstate.EventObject>> | undefined;
+}, {
+    src: "sendOtp";
+    logic: xstate.PromiseActorLogic<void, {
+        email: Email;
+    }, xstate.EventObject>;
+    id: string | undefined;
+} | {
+    src: "verifyOtp";
+    logic: xstate.PromiseActorLogic<VerifyOtpResult, {
+        email: Email;
+        code: string;
+    }, xstate.EventObject>;
+    id: string | undefined;
+} | {
+    src: "signOut";
+    logic: xstate.PromiseActorLogic<void, void, xstate.EventObject>;
+    id: string | undefined;
+} | {
+    src: "completeBootstrap";
+    logic: xstate.PromiseActorLogic<CompleteBootstrapResult, {
+        bootstrapToken: AuthBootstrapToken;
+        username: Username;
+        signerProvider: LocalPrivateKeySignerProvider;
+    }, xstate.EventObject>;
+    id: string | undefined;
+}, {
+    type: "trackOtpRequested";
+    params: unknown;
+} | {
+    type: "trackTimeoutFailed";
+    params: unknown;
+} | {
+    type: "trackVerified";
+    params: unknown;
+} | {
+    type: "identifyAndTrack";
+    params: unknown;
+} | {
+    type: "trackSignedOut";
+    params: unknown;
+} | {
+    type: "trackFailed";
+    params: unknown;
+} | {
+    type: "trackBootstrapRequired";
+    params: unknown;
+}, never, never, "email" | "authenticated" | "error" | "bootstrap_required" | "sending_otp" | "otp_requested" | "signing_out" | "verifying_otp" | "completing_bootstrap", string, xstate.NonReducibleUnknown, xstate.NonReducibleUnknown, xstate.EventObject, xstate.MetaObject, {
+    id: "authBootstrap";
+    states: {
+        readonly email: {};
+        readonly sending_otp: {};
+        readonly otp_requested: {};
+        readonly verifying_otp: {};
+        readonly bootstrap_required: {};
+        readonly completing_bootstrap: {};
+        readonly authenticated: {};
+        readonly signing_out: {};
+        readonly error: {};
+    };
+}>;
+
 /**
  * Root `@capxul/sdk` client factory.
  *
@@ -1230,6 +1420,7 @@ type CapxulConfig = {
  */
 type CapxulFlowFactories = {
     readonly auth: () => AnyStateMachine;
+    readonly authBootstrap: () => ReturnType<typeof createAuthBootstrapFlowMachine>;
     readonly onboarding: () => AnyStateMachine;
     readonly provisioning: () => AnyStateMachine;
 };
@@ -1292,4 +1483,4 @@ type CapxulClient = {
  */
 declare function createCapxulClient(config?: CapxulConfig): CapxulClient;
 
-export { type AccountProvisionPersonalInput as A, type BrowserCapxulConfig as B, type CapxulClient as C, type DocumentsClient as D, type ExternalAccountsClient as E, type VirtualCardsClient as F, type WebhookEndpointsClient as G, type HttpTransport as H, type WebhookEventsClient as I, type WithdrawalsClient as J, createCapxulClient as K, type LocalPrivateKeySignerProvider as L, type MeClient as M, makeHttpTransport as N, type OperationsClient as O, type PaymentsClient as P, toTokenTransferId as Q, type Session as S, type TokenTransfer as T, type VirtualAccountsClient as V, type WebhookEndpointCreateResult as W, type AccountsClient as a, type ApiKeyCreateResult as b, type ApiKeysClient as c, type AuthClient as d, type AuthSessionStore as e, type CapxulAuthConfig as f, type CapxulConfig as g, type CapxulDataClient as h, type CapxulFlowFactories as i, type CapxulSigningConfig as j, type OrgDocumentsClient as k, type OrgPaymentsClient as l, type OrgSafesClient as m, type OrgTransfersClient as n, type OrgTreasuryClient as o, type OrgWithdrawalsClient as p, type OrganizationsClient as q, type SubAccountsClient as r, type TokenTransferId as s, type TokenTransfersClient as t, type TokenTransfersListInput as u, type TokenTransfersListPage as v, type TokenTransfersRetrieveInput as w, type TransfersClient as x, type TransportRuntime as y, type TransportState as z };
+export { createAuthBootstrapFlowMachine as $, type AccountProvisionPersonalInput as A, type BrowserCapxulConfig as B, CapxulError as C, type DocumentsClient as D, type ExternalAccountsClient as E, type TokenTransferId as F, type TokenTransfersClient as G, type HttpTransport as H, type TokenTransfersListInput as I, type TokenTransfersListPage as J, type TokenTransfersRetrieveInput as K, type LocalPrivateKeySignerProvider as L, type MeClient as M, type TransfersClient as N, type OperationsClient as O, type PaymentsClient as P, type TransportRuntime as Q, type TransportState as R, type Session as S, type TokenTransfer as T, type VirtualAccountsClient as U, type VerifyOtpResult as V, type VirtualCardsClient as W, type WebhookEndpointCreateResult as X, type WebhookEndpointsClient as Y, type WebhookEventsClient as Z, type WithdrawalsClient as _, type CapxulClient as a, createCapxulClient as a0, makeHttpTransport as a1, toTokenTransferId as a2, type AccountsClient as b, type ApiKeyCreateResult as c, type ApiKeysClient as d, type AuthBootstrapFlowContext as e, type AuthBootstrapFlowError as f, type AuthBootstrapFlowEvent as g, type AuthBootstrapReason as h, type AuthBootstrapToken as i, type AuthClient as j, type AuthSessionStore as k, type CapxulAuthConfig as l, type CapxulConfig as m, type CapxulDataClient as n, type CapxulFlowFactories as o, type CapxulSigningConfig as p, type CompleteBootstrapInput as q, type CompleteBootstrapResult as r, type OrgDocumentsClient as s, type OrgPaymentsClient as t, type OrgSafesClient as u, type OrgTransfersClient as v, type OrgTreasuryClient as w, type OrgWithdrawalsClient as x, type OrganizationsClient as y, type SubAccountsClient as z };

package/dist/{client-DDAVWtzJ.d.cts → client-DG6ODWu6.d.cts}

@@ -1,7 +1,8 @@
 import { Account as Account$1 } from 'viem';
+import * as xstate from 'xstate';
 import { AnyStateMachine } from 'xstate';
-import { A as AccountId, S as SafeId, c as KycProfileId, b as ExternalAccountId, f as SubAccountId, d as OrganizationId, a as ApiKeyId, X as TimestampIso, D as DocumentId, O as OperationId, P as PaymentId, g as TransferId, k as WithdrawalId, W as WebhookEndpointId, j as WebhookEventId, M as MemberId, K as KybProfileId, V as VirtualAccountId, i as VirtualCardId } from './next-action-DkrwXYay.cjs';
-import { d as CapxulResult, C as CapxulError } from './errors-GgKrSUKp.cjs';
+import { A as AccountId, S as SafeId, c as KycProfileId, b as ExternalAccountId, f as SubAccountId, d as OrganizationId, a as ApiKeyId, X as TimestampIso, U as Username, E as Email, D as DocumentId, O as OperationId, P as PaymentId, g as TransferId, k as WithdrawalId, W as WebhookEndpointId, j as WebhookEventId, M as MemberId, K as KybProfileId, V as VirtualAccountId, i as VirtualCardId } from './next-action-DkrwXYay.cjs';
+import { d as CapxulResult, C as CapxulError$1 } from './errors-GgKrSUKp.cjs';
 import { A as Account, U as UserIdentifier, a as AccountLookupResult, S as Safe, i as KycProfile, E as ExternalAccount, L as List, v as SubAccount, B as BalanceLedgerEntry, b as ApiKey, a0 as CreateApiKeyRequest, a1 as CreateDocumentRequest, D as Document, O as Operation, l as OperationStatus, k as Money, C as CreatePaymentResult, o as Payment, F as TransferEndpoint, f as CreateTransferResult, y as Transfer, g as CreateWithdrawalResult, _ as Withdrawal, a2 as CreateWebhookEndpointRequest, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, a3 as CreateVirtualAccountRequest, V as VirtualAccount, a4 as CreateVirtualCardRequest, Q as VirtualCard } from './types-hfcOE7Oi.cjs';
 
 /**
@@ -189,6 +190,38 @@ type AuthVerifyOtpInput = {
     readonly email: string;
     readonly otp: string;
 };
+type AuthBootstrapToken = string & {
+    readonly __capxulAuthBootstrapTokenBrand: "AuthBootstrapToken";
+};
+type AuthBootstrapReason = "new_member" | "missing_profile" | "missing_account" | "missing_safe" | "missing_signer_grant";
+type VerifyOtpResult = {
+    readonly kind: "existing_member";
+    readonly session: Session;
+    readonly account: Account;
+    readonly username: Username;
+    readonly safe: Safe;
+} | {
+    readonly kind: "bootstrap_required";
+    readonly session: Session;
+    readonly bootstrapToken: AuthBootstrapToken;
+    readonly email: Email;
+    readonly reason: AuthBootstrapReason;
+    readonly username?: Username;
+};
+type CompleteBootstrapInput = {
+    readonly bootstrapToken: AuthBootstrapToken;
+    readonly username: Username;
+    readonly signerProvider: LocalPrivateKeySignerProvider;
+    readonly displayName?: string;
+    readonly countryCode?: string;
+};
+type CompleteBootstrapResult = {
+    readonly kind: "authenticated";
+    readonly session: Session;
+    readonly account: Account;
+    readonly username: Username;
+    readonly safe: Safe;
+};
 type AuthServiceTokenMintInput = {
     readonly apiKey: string;
     readonly audience?: string;
@@ -211,13 +244,15 @@ type ServiceToken = {
     readonly expiresAt: TimestampIso;
 };
 type SendOtpCodes = "EMAIL_DELIVERY_FAILED" | "INVALID_INPUT" | "RATE_LIMITED" | "NETWORK_ERROR";
-type VerifyOtpCodes = "INVALID_INPUT" | "NOT_AUTHENTICATED" | "RATE_LIMITED" | "NETWORK_ERROR";
+type VerifyOtpCodes = "INVALID_INPUT" | "NOT_AUTHENTICATED" | "RATE_LIMITED" | "OPERATION_TIMEOUT" | "NETWORK_ERROR";
+type CompleteBootstrapCodes = "INVALID_INPUT" | "IDEMPOTENCY_CONFLICT" | "RATE_LIMITED" | "PROFILE_NOT_FOUND" | "SMART_ACCOUNT_MISSING" | "PROVIDER_UNAVAILABLE" | "PROVIDER_REJECTED" | "OPERATION_TIMEOUT" | "NETWORK_ERROR" | "INTERNAL_ERROR";
 type GetSessionCodes = "NETWORK_ERROR";
 type SignOutCodes = "NOT_AUTHENTICATED" | "NETWORK_ERROR";
 type ServiceTokenMintCodes = "API_KEY_INVALID" | "API_KEY_EXPIRED" | "INVALID_INPUT" | "RATE_LIMITED" | "NETWORK_ERROR";
 type AuthClient = {
     readonly sendOtp: (input: AuthSendOtpInput, options?: AuthMethodOptions) => Promise<CapxulResult<void, SendOtpCodes>>;
-    readonly verifyOtp: (input: AuthVerifyOtpInput, options?: AuthMethodOptions) => Promise<CapxulResult<Session, VerifyOtpCodes>>;
+    readonly verifyOtp: (input: AuthVerifyOtpInput, options?: AuthMethodOptions) => Promise<CapxulResult<VerifyOtpResult, VerifyOtpCodes>>;
+    readonly completeBootstrap: (input: CompleteBootstrapInput) => Promise<CapxulResult<CompleteBootstrapResult, CompleteBootstrapCodes>>;
     readonly getSession: () => Promise<CapxulResult<Session | null, GetSessionCodes>>;
     readonly signOut: () => Promise<CapxulResult<void, SignOutCodes>>;
     readonly serviceTokenMint: (input: AuthServiceTokenMintInput) => Promise<CapxulResult<ServiceToken, ServiceTokenMintCodes>>;
@@ -883,7 +918,7 @@ type TransportState = {
     readonly runtime: TransportRuntime;
 } | {
     readonly status: "error";
-    readonly error: CapxulError;
+    readonly error: CapxulError$1;
 };
 type TransportRuntime = {
     readonly authBaseUrl: string;
@@ -1103,6 +1138,161 @@ type VirtualCardsClient = {
     readonly cancel: (virtualCardId: VirtualCardId) => Promise<CapxulResult<VirtualCard, MutateCodes>>;
 };
 
+/**
+ * Unified error type used across the entire stack: backend, SDK, and frontend.
+ * One class, one set of codes, one language.
+ *
+ * Backend throws CapxulError → withErrorBoundary serializes to ConvexError →
+ * SDK deserializes back to CapxulError → frontend routes on err.code.
+ */
+type CapxulErrorCode = "NOT_AUTHENTICATED" | "EMAIL_DELIVERY_FAILED" | "API_KEY_INVALID" | "API_KEY_EXPIRED" | "PROFILE_NOT_FOUND" | "SMART_ACCOUNT_MISSING" | "PLAYER_NOT_FOUND" | "ACCOUNT_NOT_FOUND" | "PROVIDER_ERROR" | "INVALID_INPUT" | "ENV_MISSING" | "NOT_IMPLEMENTED" | "VERIFICATION_REQUIRED" | "INSUFFICIENT_BALANCE" | "INVALID_RECIPIENT" | "TRANSACTION_FAILED" | "RATE_LIMITED" | "NETWORK_ERROR" | "PERMISSION_DENIED" | "IDEMPOTENCY_CONFLICT" | "NOT_FOUND" | "OPERATION_CANCELED" | "OPERATION_TIMEOUT" | "ACTION_REQUIRED" | "KYC_REQUIRED" | "POLICY_DENIED" | "SAFE_NOT_READY" | "PROVIDER_UNAVAILABLE" | "PROVIDER_REJECTED" | "RECONCILIATION_FAILED" | "INTERNAL_ERROR" | "QUOTE_EXPIRED" | "QUOTE_NOT_FOUND" | "UNKNOWN";
+declare class CapxulError extends Error {
+    readonly code: CapxulErrorCode;
+    readonly details?: Record<string, unknown>;
+    readonly correlationId?: string;
+    readonly layer?: string;
+    constructor(code: CapxulErrorCode, message: string, options?: {
+        cause?: unknown;
+        details?: Record<string, unknown>;
+        correlationId?: string;
+        layer?: string;
+    });
+}
+
+type AuthBootstrapFlowError = CapxulError$1 | CapxulError;
+type AuthBootstrapFlowContext = {
+    readonly email: Email | null;
+    readonly code: string | null;
+    readonly username: Username | null;
+    readonly signerProvider: LocalPrivateKeySignerProvider | null;
+    readonly bootstrapToken: AuthBootstrapToken | null;
+    readonly bootstrapReason: AuthBootstrapReason | null;
+    readonly session: Session | null;
+    readonly account: Account | null;
+    readonly safe: Safe | null;
+    readonly error: AuthBootstrapFlowError | null;
+};
+type AuthBootstrapFlowEvent = {
+    readonly type: "ENTER_EMAIL";
+    readonly email: Email;
+} | {
+    readonly type: "REQUEST_OTP";
+} | {
+    readonly type: "ENTER_OTP";
+    readonly code: string;
+} | {
+    readonly type: "VERIFY_OTP";
+} | {
+    readonly type: "ENTER_USERNAME";
+    readonly username: Username;
+} | {
+    readonly type: "ENTER_SIGNER_PROVIDER";
+    readonly signerProvider: LocalPrivateKeySignerProvider;
+} | {
+    readonly type: "COMPLETE_BOOTSTRAP";
+} | {
+    readonly type: "BACK";
+} | {
+    readonly type: "RESET";
+} | {
+    readonly type: "SIGN_OUT";
+};
+declare function createAuthBootstrapFlowMachine(client: CapxulClient): xstate.StateMachine<AuthBootstrapFlowContext, {
+    readonly type: "ENTER_EMAIL";
+    readonly email: Email;
+} | {
+    readonly type: "REQUEST_OTP";
+} | {
+    readonly type: "ENTER_OTP";
+    readonly code: string;
+} | {
+    readonly type: "VERIFY_OTP";
+} | {
+    readonly type: "ENTER_USERNAME";
+    readonly username: Username;
+} | {
+    readonly type: "ENTER_SIGNER_PROVIDER";
+    readonly signerProvider: LocalPrivateKeySignerProvider;
+} | {
+    readonly type: "COMPLETE_BOOTSTRAP";
+} | {
+    readonly type: "BACK";
+} | {
+    readonly type: "RESET";
+} | {
+    readonly type: "SIGN_OUT";
+}, {
+    [x: string]: xstate.ActorRefFromLogic<xstate.PromiseActorLogic<void, void, xstate.EventObject>> | xstate.ActorRefFromLogic<xstate.PromiseActorLogic<void, {
+        email: Email;
+    }, xstate.EventObject>> | xstate.ActorRefFromLogic<xstate.PromiseActorLogic<VerifyOtpResult, {
+        email: Email;
+        code: string;
+    }, xstate.EventObject>> | xstate.ActorRefFromLogic<xstate.PromiseActorLogic<CompleteBootstrapResult, {
+        bootstrapToken: AuthBootstrapToken;
+        username: Username;
+        signerProvider: LocalPrivateKeySignerProvider;
+    }, xstate.EventObject>> | undefined;
+}, {
+    src: "sendOtp";
+    logic: xstate.PromiseActorLogic<void, {
+        email: Email;
+    }, xstate.EventObject>;
+    id: string | undefined;
+} | {
+    src: "verifyOtp";
+    logic: xstate.PromiseActorLogic<VerifyOtpResult, {
+        email: Email;
+        code: string;
+    }, xstate.EventObject>;
+    id: string | undefined;
+} | {
+    src: "signOut";
+    logic: xstate.PromiseActorLogic<void, void, xstate.EventObject>;
+    id: string | undefined;
+} | {
+    src: "completeBootstrap";
+    logic: xstate.PromiseActorLogic<CompleteBootstrapResult, {
+        bootstrapToken: AuthBootstrapToken;
+        username: Username;
+        signerProvider: LocalPrivateKeySignerProvider;
+    }, xstate.EventObject>;
+    id: string | undefined;
+}, {
+    type: "trackOtpRequested";
+    params: unknown;
+} | {
+    type: "trackTimeoutFailed";
+    params: unknown;
+} | {
+    type: "trackVerified";
+    params: unknown;
+} | {
+    type: "identifyAndTrack";
+    params: unknown;
+} | {
+    type: "trackSignedOut";
+    params: unknown;
+} | {
+    type: "trackFailed";
+    params: unknown;
+} | {
+    type: "trackBootstrapRequired";
+    params: unknown;
+}, never, never, "email" | "authenticated" | "error" | "bootstrap_required" | "sending_otp" | "otp_requested" | "signing_out" | "verifying_otp" | "completing_bootstrap", string, xstate.NonReducibleUnknown, xstate.NonReducibleUnknown, xstate.EventObject, xstate.MetaObject, {
+    id: "authBootstrap";
+    states: {
+        readonly email: {};
+        readonly sending_otp: {};
+        readonly otp_requested: {};
+        readonly verifying_otp: {};
+        readonly bootstrap_required: {};
+        readonly completing_bootstrap: {};
+        readonly authenticated: {};
+        readonly signing_out: {};
+        readonly error: {};
+    };
+}>;
+
 /**
  * Root `@capxul/sdk` client factory.
  *
@@ -1230,6 +1420,7 @@ type CapxulConfig = {
  */
 type CapxulFlowFactories = {
     readonly auth: () => AnyStateMachine;
+    readonly authBootstrap: () => ReturnType<typeof createAuthBootstrapFlowMachine>;
     readonly onboarding: () => AnyStateMachine;
     readonly provisioning: () => AnyStateMachine;
 };
@@ -1292,4 +1483,4 @@ type CapxulClient = {
  */
 declare function createCapxulClient(config?: CapxulConfig): CapxulClient;
 
-export { type AccountProvisionPersonalInput as A, type BrowserCapxulConfig as B, type CapxulClient as C, type DocumentsClient as D, type ExternalAccountsClient as E, type VirtualCardsClient as F, type WebhookEndpointsClient as G, type HttpTransport as H, type WebhookEventsClient as I, type WithdrawalsClient as J, createCapxulClient as K, type LocalPrivateKeySignerProvider as L, type MeClient as M, makeHttpTransport as N, type OperationsClient as O, type PaymentsClient as P, toTokenTransferId as Q, type Session as S, type TokenTransfer as T, type VirtualAccountsClient as V, type WebhookEndpointCreateResult as W, type AccountsClient as a, type ApiKeyCreateResult as b, type ApiKeysClient as c, type AuthClient as d, type AuthSessionStore as e, type CapxulAuthConfig as f, type CapxulConfig as g, type CapxulDataClient as h, type CapxulFlowFactories as i, type CapxulSigningConfig as j, type OrgDocumentsClient as k, type OrgPaymentsClient as l, type OrgSafesClient as m, type OrgTransfersClient as n, type OrgTreasuryClient as o, type OrgWithdrawalsClient as p, type OrganizationsClient as q, type SubAccountsClient as r, type TokenTransferId as s, type TokenTransfersClient as t, type TokenTransfersListInput as u, type TokenTransfersListPage as v, type TokenTransfersRetrieveInput as w, type TransfersClient as x, type TransportRuntime as y, type TransportState as z };
+export { createAuthBootstrapFlowMachine as $, type AccountProvisionPersonalInput as A, type BrowserCapxulConfig as B, CapxulError as C, type DocumentsClient as D, type ExternalAccountsClient as E, type TokenTransferId as F, type TokenTransfersClient as G, type HttpTransport as H, type TokenTransfersListInput as I, type TokenTransfersListPage as J, type TokenTransfersRetrieveInput as K, type LocalPrivateKeySignerProvider as L, type MeClient as M, type TransfersClient as N, type OperationsClient as O, type PaymentsClient as P, type TransportRuntime as Q, type TransportState as R, type Session as S, type TokenTransfer as T, type VirtualAccountsClient as U, type VerifyOtpResult as V, type VirtualCardsClient as W, type WebhookEndpointCreateResult as X, type WebhookEndpointsClient as Y, type WebhookEventsClient as Z, type WithdrawalsClient as _, type CapxulClient as a, createCapxulClient as a0, makeHttpTransport as a1, toTokenTransferId as a2, type AccountsClient as b, type ApiKeyCreateResult as c, type ApiKeysClient as d, type AuthBootstrapFlowContext as e, type AuthBootstrapFlowError as f, type AuthBootstrapFlowEvent as g, type AuthBootstrapReason as h, type AuthBootstrapToken as i, type AuthClient as j, type AuthSessionStore as k, type CapxulAuthConfig as l, type CapxulConfig as m, type CapxulDataClient as n, type CapxulFlowFactories as o, type CapxulSigningConfig as p, type CompleteBootstrapInput as q, type CompleteBootstrapResult as r, type OrgDocumentsClient as s, type OrgPaymentsClient as t, type OrgSafesClient as u, type OrgTransfersClient as v, type OrgTreasuryClient as w, type OrgWithdrawalsClient as x, type OrganizationsClient as y, type SubAccountsClient as z };