@capxul/sdk 0.1.0-alpha.1 → 0.1.0-alpha.12

package/dist/{client-CweJSkaY.d.ts → client-64FvYfKr.d.ts}

@@ -1,9 +1,9 @@
 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 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, 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, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, V as VirtualAccount, Q as VirtualCard } from './types-75UokagF.js';
-import * as types from '@repo/api-contract/gen/types';
+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';
 
 /**
  * Accounts domain — individual user accounts per sdk-surface.md §1a.
@@ -40,6 +40,7 @@ type AccountListInput = {
 type AccountCreateSubAccountInput = {
     readonly accountId: AccountId;
     readonly name: string;
+    readonly purpose?: string;
 };
 type AccountCreateExternalAccountInput = {
     readonly accountId: AccountId;
@@ -53,43 +54,44 @@ type AccountCreateExternalAccountInput = {
     readonly panToken?: string;
     readonly last4?: string;
 };
-type RetrieveCodes$d = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type RetrieveCodes$e = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
 type LookupCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
 type UpdateCodes$1 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "INVALID_INPUT";
-type ListCodes$a = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type ListCodes$b = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
 type SafeRetrieveCodes$1 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "SAFE_NOT_READY";
 type RemoveCodes$5 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type SubAccountRemoveCodes$1 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "INVALID_INPUT";
 type AccountSafesClient = {
     readonly retrieve: (safeId: SafeId) => Promise<CapxulResult<Safe, SafeRetrieveCodes$1>>;
 };
 type AccountKycProfilesClient = {
     readonly create: (input: AccountCreateKycProfileInput) => Promise<CapxulResult<KycProfile, UpdateCodes$1>>;
-    readonly retrieve: (kycProfileId: KycProfileId) => Promise<CapxulResult<KycProfile, RetrieveCodes$d>>;
+    readonly retrieve: (kycProfileId: KycProfileId) => Promise<CapxulResult<KycProfile, RetrieveCodes$e>>;
 };
 type AccountExternalAccountsClient = {
     readonly create: (input: AccountCreateExternalAccountInput) => Promise<CapxulResult<ExternalAccount, UpdateCodes$1>>;
     readonly list: (input: {
         readonly accountId: AccountId;
-    } & AccountListInput) => Promise<CapxulResult<List<ExternalAccount>, ListCodes$a>>;
-    readonly retrieve: (externalAccountId: ExternalAccountId) => Promise<CapxulResult<ExternalAccount, RetrieveCodes$d>>;
+    } & AccountListInput) => Promise<CapxulResult<List<ExternalAccount>, ListCodes$b>>;
+    readonly retrieve: (externalAccountId: ExternalAccountId) => Promise<CapxulResult<ExternalAccount, RetrieveCodes$e>>;
     readonly remove: (externalAccountId: ExternalAccountId) => Promise<CapxulResult<void, RemoveCodes$5>>;
 };
 type AccountSubAccountsClient = {
-    readonly create: (input: AccountCreateSubAccountInput) => Promise<CapxulResult<SubAccount, UpdateCodes$1>>;
+    readonly create: (input: AccountCreateSubAccountInput) => Promise<CapxulResult<SubAccount, UpdateCodes$1 | "PROVIDER_ERROR">>;
     readonly list: (input: {
         readonly accountId: AccountId;
-    } & AccountListInput) => Promise<CapxulResult<List<SubAccount>, ListCodes$a>>;
-    readonly retrieve: (subAccountId: SubAccountId) => Promise<CapxulResult<SubAccount, RetrieveCodes$d>>;
-    readonly remove: (subAccountId: SubAccountId) => Promise<CapxulResult<void, RemoveCodes$5>>;
+    } & AccountListInput) => Promise<CapxulResult<List<SubAccount>, ListCodes$b | "PROVIDER_ERROR">>;
+    readonly retrieve: (subAccountId: SubAccountId) => Promise<CapxulResult<SubAccount, RetrieveCodes$e | "PROVIDER_ERROR">>;
+    readonly remove: (subAccountId: SubAccountId) => Promise<CapxulResult<SubAccount, SubAccountRemoveCodes$1 | "PROVIDER_ERROR">>;
 };
 type AccountBalanceLedgerClient = {
     readonly list: (input: {
         readonly accountId: AccountId;
-    } & AccountListInput) => Promise<CapxulResult<List<BalanceLedgerEntry>, ListCodes$a>>;
-    readonly retrieve: (entryId: string) => Promise<CapxulResult<BalanceLedgerEntry, RetrieveCodes$d>>;
+    } & AccountListInput) => Promise<CapxulResult<List<BalanceLedgerEntry>, ListCodes$b>>;
+    readonly retrieve: (entryId: string) => Promise<CapxulResult<BalanceLedgerEntry, RetrieveCodes$e>>;
 };
 type AccountsClient = {
-    readonly retrieve: (accountId: AccountId) => Promise<CapxulResult<Account, RetrieveCodes$d>>;
+    readonly retrieve: (accountId: AccountId) => Promise<CapxulResult<Account, RetrieveCodes$e>>;
     readonly lookup: (input: AccountLookupInput) => Promise<CapxulResult<AccountLookupResult, LookupCodes>>;
     readonly update: (input: {
         readonly accountId: AccountId;
@@ -111,7 +113,7 @@ type AccountsClient = {
  * on `create` only; subsequent reads omit it.
  */
 
-type ApiKeysCreateInput = types.CreateApiKeyRequest & {
+type ApiKeysCreateInput = CreateApiKeyRequest & {
     readonly organizationId: OrganizationId;
 };
 type ApiKeysRetrieveInput = {
@@ -125,9 +127,9 @@ type ApiKeysListInput = {
 };
 type ApiKeysRevokeInput = ApiKeysRetrieveInput;
 type CreateCodes$8 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "RATE_LIMITED" | "NETWORK_ERROR";
-type RetrieveCodes$c = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$9 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
-type RevokeCodes = RetrieveCodes$c;
+type RetrieveCodes$d = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$a = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RevokeCodes = RetrieveCodes$d;
 /**
  * Shape returned by `organizations.apiKeys.create` — the one-time
  * secret `value` is included here and omitted from every subsequent
@@ -138,8 +140,8 @@ type ApiKeyCreateResult = ApiKey & {
 };
 type ApiKeysClient = {
     readonly create: (input: ApiKeysCreateInput) => Promise<CapxulResult<ApiKeyCreateResult, CreateCodes$8>>;
-    readonly retrieve: (input: ApiKeysRetrieveInput) => Promise<CapxulResult<ApiKey, RetrieveCodes$c>>;
-    readonly list: (input: ApiKeysListInput) => Promise<CapxulResult<List<ApiKey>, ListCodes$9>>;
+    readonly retrieve: (input: ApiKeysRetrieveInput) => Promise<CapxulResult<ApiKey, RetrieveCodes$d>>;
+    readonly list: (input: ApiKeysListInput) => Promise<CapxulResult<List<ApiKey>, ListCodes$a>>;
     readonly revoke: (input: ApiKeysRevokeInput) => Promise<CapxulResult<ApiKey, RevokeCodes>>;
 };
 
@@ -190,6 +192,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,14 +245,16 @@ type ServiceToken = {
     readonly token: string;
     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 SendOtpCodes = "EMAIL_DELIVERY_FAILED" | "INVALID_INPUT" | "RATE_LIMITED" | "NETWORK_ERROR" | "PROVIDER_ERROR" | "INTERNAL_ERROR" | "ENV_MISSING" | "UNKNOWN";
+type VerifyOtpCodes = "INVALID_INPUT" | "NOT_AUTHENTICATED" | "RATE_LIMITED" | "OPERATION_TIMEOUT" | "NETWORK_ERROR" | "PROVIDER_ERROR" | "INTERNAL_ERROR" | "ENV_MISSING" | "UNKNOWN";
+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>>;
@@ -236,7 +272,7 @@ type AuthClient = {
  * bank_statement | tax_form`.
  */
 
-type DocumentsCreateInput = types.CreateDocumentRequest;
+type DocumentsCreateInput = CreateDocumentRequest;
 type DocumentsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
@@ -260,19 +296,19 @@ type OrgDocumentsCancelInput = {
     readonly documentId: DocumentId;
 };
 type CreateCodes$7 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "IDEMPOTENCY_CONFLICT" | "RATE_LIMITED" | "NETWORK_ERROR";
-type RetrieveCodes$b = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$8 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RetrieveCodes$c = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$9 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
 type CancelCodes$1 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "OPERATION_CANCELED";
 type DocumentsClient = {
     readonly create: (input: DocumentsCreateInput) => Promise<CapxulResult<Document, CreateCodes$7>>;
-    readonly retrieve: (documentId: DocumentId) => Promise<CapxulResult<Document, RetrieveCodes$b>>;
-    readonly list: (input?: DocumentsListInput) => Promise<CapxulResult<List<Document>, ListCodes$8>>;
+    readonly retrieve: (documentId: DocumentId) => Promise<CapxulResult<Document, RetrieveCodes$c>>;
+    readonly list: (input?: DocumentsListInput) => Promise<CapxulResult<List<Document>, ListCodes$9>>;
     readonly cancel: (documentId: DocumentId) => Promise<CapxulResult<Document, CancelCodes$1>>;
 };
 type OrgDocumentsClient = {
     readonly create: (input: OrgDocumentsCreateInput) => Promise<CapxulResult<Document, CreateCodes$7>>;
-    readonly retrieve: (input: OrgDocumentsRetrieveInput) => Promise<CapxulResult<Document, RetrieveCodes$b>>;
-    readonly list: (input: OrgDocumentsListInput) => Promise<CapxulResult<List<Document>, ListCodes$8>>;
+    readonly retrieve: (input: OrgDocumentsRetrieveInput) => Promise<CapxulResult<Document, RetrieveCodes$c>>;
+    readonly list: (input: OrgDocumentsListInput) => Promise<CapxulResult<List<Document>, ListCodes$9>>;
     readonly cancel: (input: OrgDocumentsCancelInput) => Promise<CapxulResult<Document, CancelCodes$1>>;
 };
 
@@ -282,14 +318,26 @@ type OrgDocumentsClient = {
  * Per sdk-surface.md §1a, `external_account` is a reusable withdrawal
  * destination. `create` + `list` live under the owner's nested
  * namespace (Pattern A — `accounts.externalAccounts.*` or
- * `organizations.externalAccounts.*`). `retrieve` and `remove` work by
- * ID without scoping.
+ * `organizations.externalAccounts.*`). The top-level `retrieve` and
+ * `remove` keep PERSONAL-scope semantics — for org rows route via
+ * the `organizations.externalAccounts.*` namespace which carries
+ * `organizationId` end-to-end and pins the row's owner pair to
+ * prevent cross-org IDOR (revision 1, #464).
+ *
+ * Withdrawals v1 W1 (#464) wires these stubs through the
+ * `externalAccounts/{queries,mutations}` Convex domain. The wire shape
+ * matches OpenAPI: `{ object: "external_account", id, kind, status,
+ * ..., operation: { id, status, correlationId } }` — the trust-chain
+ * ids live under the canonical nested `operation: OperationSummary`
+ * envelope (revision 3, #464), matching Withdrawal / Payment /
+ * Transfer / Organization. The SDK rebrands `id` + the nested
+ * `operation` sub-ids at the read edge.
  */
 
-type RetrieveCodes$a = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type RemoveCodes$4 = RetrieveCodes$a;
+type RetrieveCodes$b = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type RemoveCodes$4 = RetrieveCodes$b;
 type ExternalAccountsClient = {
-    readonly retrieve: (externalAccountId: ExternalAccountId) => Promise<CapxulResult<ExternalAccount, RetrieveCodes$a>>;
+    readonly retrieve: (externalAccountId: ExternalAccountId) => Promise<CapxulResult<ExternalAccount, RetrieveCodes$b>>;
     readonly remove: (externalAccountId: ExternalAccountId) => Promise<CapxulResult<void, RemoveCodes$4>>;
 };
 
@@ -329,10 +377,10 @@ type OperationsWaitInput = {
     readonly timeoutSeconds?: number;
     readonly pollIntervalMs?: number;
 };
-type RetrieveCodes$9 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type WaitCodes = RetrieveCodes$9 | "OPERATION_TIMEOUT";
+type RetrieveCodes$a = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type WaitCodes = RetrieveCodes$a | "OPERATION_TIMEOUT";
 type OperationsClient = {
-    readonly retrieve: (operationId: OperationId) => Promise<CapxulResult<Operation, RetrieveCodes$9>>;
+    readonly retrieve: (operationId: OperationId) => Promise<CapxulResult<Operation, RetrieveCodes$a>>;
     readonly wait: (operationId: OperationId, input?: OperationsWaitInput) => Promise<CapxulResult<Operation, WaitCodes>>;
 };
 
@@ -393,17 +441,17 @@ type OrgPaymentsListInput = {
 };
 type CreateCodes$6 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "INVALID_RECIPIENT" | "INSUFFICIENT_BALANCE" | "IDEMPOTENCY_CONFLICT" | "RATE_LIMITED" | "NETWORK_ERROR";
 type OrgCreateCodes = CreateCodes$6 | "POLICY_DENIED" | "SAFE_NOT_READY";
-type RetrieveCodes$8 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$7 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RetrieveCodes$9 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$8 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
 type PaymentsClient = {
     readonly create: (input: PaymentsCreateInput) => Promise<CapxulResult<CreatePaymentResult, CreateCodes$6>>;
-    readonly retrieve: (paymentId: PaymentId) => Promise<CapxulResult<Payment, RetrieveCodes$8>>;
-    readonly list: (input?: PaymentsListInput) => Promise<CapxulResult<List<Payment>, ListCodes$7>>;
+    readonly retrieve: (paymentId: PaymentId) => Promise<CapxulResult<Payment, RetrieveCodes$9>>;
+    readonly list: (input?: PaymentsListInput) => Promise<CapxulResult<List<Payment>, ListCodes$8>>;
 };
 type OrgPaymentsClient = {
     readonly create: (input: OrgPaymentsCreateInput) => Promise<CapxulResult<CreatePaymentResult, OrgCreateCodes>>;
-    readonly retrieve: (input: OrgPaymentsRetrieveInput) => Promise<CapxulResult<Payment, RetrieveCodes$8>>;
-    readonly list: (input: OrgPaymentsListInput) => Promise<CapxulResult<List<Payment>, ListCodes$7>>;
+    readonly retrieve: (input: OrgPaymentsRetrieveInput) => Promise<CapxulResult<Payment, RetrieveCodes$9>>;
+    readonly list: (input: OrgPaymentsListInput) => Promise<CapxulResult<List<Payment>, ListCodes$8>>;
 };
 
 /**
@@ -452,56 +500,46 @@ type OrgTransfersCancelInput = {
     readonly transferId: TransferId;
 };
 type CreateCodes$5 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "INSUFFICIENT_BALANCE" | "IDEMPOTENCY_CONFLICT" | "RATE_LIMITED" | "NETWORK_ERROR";
-type RetrieveCodes$7 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$6 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RetrieveCodes$8 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$7 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
 type ConfirmCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "QUOTE_EXPIRED" | "QUOTE_NOT_FOUND";
 type CancelCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "OPERATION_CANCELED";
 type TransfersClient = {
     readonly create: (input: TransfersCreateInput) => Promise<CapxulResult<CreateTransferResult, CreateCodes$5>>;
-    readonly retrieve: (transferId: TransferId) => Promise<CapxulResult<Transfer, RetrieveCodes$7>>;
-    readonly list: (input?: TransfersListInput) => Promise<CapxulResult<List<Transfer>, ListCodes$6>>;
+    readonly retrieve: (transferId: TransferId) => Promise<CapxulResult<Transfer, RetrieveCodes$8>>;
+    readonly list: (input?: TransfersListInput) => Promise<CapxulResult<List<Transfer>, ListCodes$7>>;
     readonly confirm: (input: TransfersConfirmInput) => Promise<CapxulResult<Transfer, ConfirmCodes>>;
     readonly cancel: (transferId: TransferId) => Promise<CapxulResult<Transfer, CancelCodes>>;
 };
 type OrgTransfersClient = {
     readonly create: (input: OrgTransfersCreateInput) => Promise<CapxulResult<CreateTransferResult, CreateCodes$5>>;
-    readonly retrieve: (input: OrgTransfersRetrieveInput) => Promise<CapxulResult<Transfer, RetrieveCodes$7>>;
-    readonly list: (input: OrgTransfersListInput) => Promise<CapxulResult<List<Transfer>, ListCodes$6>>;
+    readonly retrieve: (input: OrgTransfersRetrieveInput) => Promise<CapxulResult<Transfer, RetrieveCodes$8>>;
+    readonly list: (input: OrgTransfersListInput) => Promise<CapxulResult<List<Transfer>, ListCodes$7>>;
     readonly confirm: (input: OrgTransfersConfirmInput) => Promise<CapxulResult<Transfer, ConfirmCodes>>;
     readonly cancel: (input: OrgTransfersCancelInput) => Promise<CapxulResult<Transfer, CancelCodes>>;
 };
 
 /**
  * Withdrawals domain — funds exit Capxul via an `external_account` per
- * sdk-surface.md §1a + §4.52 + withdrawal-orchestration.mdx (slice 1
- * of Withdrawals v1, #440).
- *
- * Slice 1 NOTE — transitional input shape:
- * Until the `external_accounts` resource lands (slice 1.x or v2), the
- * destination input includes a `kind` field so the backend + SDK can
- * route to the chain_wallet rail without a real external_accounts
- * lookup. When the resource lands, `kind` becomes optional / ignored
- * and the kind is inferred from the resolved row.
+ * sdk-surface.md §1a + §4.52 + withdrawal-orchestration.mdx.
  *
- * Slice 1 NOTE — chain_wallet rail integration:
- * For evm destinations, the `externalAccountId` is treated as the
- * destination address (must start with `0x`) so the chain_wallet rail
- * can call `transferAsOwner` directly. For solana / starknet the SDK
- * accepts the create call but does NOT execute the rail submission —
- * the row stays in `processing` until external_accounts lands. The
- * caller can transition it via `markFailed` if needed.
+ * Withdrawals v1 W2 (#465) refactor:
+ * - The `kind` shim on `destination` is GONE. The backend now resolves
+ *   the destination row by FK and infers kind + rail. Anything that
+ *   doesn't route to `chain_wallet` returns `VERIFICATION_REQUIRED`.
+ * - Org-scope `create` is now a real mutation (no longer a stub).
+ *   Personal-scope keeps the on-chain submission tail; org-scope
+ *   returns the `processing` row only — Safe + Zodiac orchestration
+ *   ships in W3+ (D6).
+ * - All raw `try/catch` blocks have been replaced with `tryCatch` from
+ *   `@repo/observability`, mirroring `core/external-accounts.ts`
+ *   (precedent D2).
  */
 
 type WithdrawalsCreateInput = {
     readonly amount: Money;
     readonly destination: {
         readonly externalAccountId: ExternalAccountId;
-        /**
-         * Slice 1 transitional field. Required until the
-         * `external_accounts` resource lands; will become optional / ignored
-         * when the resource is the source of truth for kind.
-         */
-        readonly kind: "evm" | "solana" | "starknet" | "bank" | "momo" | "card_payout";
     };
     readonly source?: {
         readonly subAccountId: SubAccountId;
@@ -514,6 +552,22 @@ type WithdrawalsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
 };
+/**
+ * Withdrawals v1 W4 (#467) — input for the reconciliation pipe.
+ * Caller passes the same `txHash` that `recordSubmitted` wrote; the
+ * backend cross-checks the value against the persisted operation row.
+ *
+ * `withdrawalId` accepts either the branded `WithdrawalId` or a raw
+ * string. `txHash` is a raw string at the SDK boundary — the backend
+ * re-validates the shape via `toTxHash` at the mutation handler (the
+ * SDK package is no longer coupled to `@repo/types`'s brand surface
+ * post the alpha-epic decoupling; see
+ * `packages/sdk/docs/internal/decoupling-prep.md`).
+ */
+type WithdrawalsRecordCompletedInput = {
+    readonly withdrawalId: WithdrawalId | string;
+    readonly txHash: string;
+};
 type OrgWithdrawalsCreateInput = WithdrawalsCreateInput & {
     readonly organizationId: OrganizationId;
 };
@@ -526,18 +580,40 @@ type OrgWithdrawalsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
 };
-type CreateCodes$4 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "INSUFFICIENT_BALANCE" | "IDEMPOTENCY_CONFLICT" | "KYC_REQUIRED" | "POLICY_DENIED" | "RATE_LIMITED" | "NETWORK_ERROR";
-type RetrieveCodes$6 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$5 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type CreateCodes$4 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "INSUFFICIENT_BALANCE" | "IDEMPOTENCY_CONFLICT" | "KYC_REQUIRED" | "POLICY_DENIED" | "RATE_LIMITED" | "NETWORK_ERROR" | "NOT_FOUND" | "VERIFICATION_REQUIRED";
+type RetrieveCodes$7 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$6 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+/**
+ * Narrow code set for `recordCompleted`. Mirror of `recordSubmitted`'s
+ * code surface — the SDK does NOT export `recordSubmitted` publicly
+ * (the create signing tail invokes it), but the call shape is the
+ * reference. Per ADR 9, `recordCompleted` is exposed on personal-scope
+ * `WithdrawalsClient` ONLY.
+ */
+type RecordCompletedCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "NOT_FOUND" | "NETWORK_ERROR" | "INTERNAL_ERROR";
 type WithdrawalsClient = {
     readonly create: (input: WithdrawalsCreateInput) => Promise<CapxulResult<CreateWithdrawalResult, CreateCodes$4>>;
-    readonly retrieve: (withdrawalId: WithdrawalId) => Promise<CapxulResult<Withdrawal, RetrieveCodes$6>>;
-    readonly list: (input?: WithdrawalsListInput) => Promise<CapxulResult<List<Withdrawal>, ListCodes$5>>;
+    readonly retrieve: (withdrawalId: WithdrawalId) => Promise<CapxulResult<Withdrawal, RetrieveCodes$7>>;
+    readonly list: (input?: WithdrawalsListInput) => Promise<CapxulResult<List<Withdrawal>, ListCodes$6>>;
+    /**
+     * Withdrawals v1 W4 (#467) — reconciliation pipe.
+     *
+     * Caller invokes this AFTER `withdrawals.create` resolves AND after
+     * the on-chain receipt confirms (e.g., via the harness's
+     * `chain.waitReceipt`). The mutation patches the withdrawal +
+     * execution + attempt + operation rows to terminal happy state and
+     * emits a single `operation.succeeded` outbox event joined to the
+     * original correlationId. Idempotent on already-`completed` rows.
+     *
+     * Personal-scope only — the org-scope client does NOT expose this
+     * method (mirror of `recordSubmitted`; see ADR 9 in #467).
+     */
+    readonly recordCompleted: (input: WithdrawalsRecordCompletedInput) => Promise<CapxulResult<null, RecordCompletedCodes>>;
 };
 type OrgWithdrawalsClient = {
     readonly create: (input: OrgWithdrawalsCreateInput) => Promise<CapxulResult<CreateWithdrawalResult, CreateCodes$4>>;
-    readonly retrieve: (input: OrgWithdrawalsRetrieveInput) => Promise<CapxulResult<Withdrawal, RetrieveCodes$6>>;
-    readonly list: (input: OrgWithdrawalsListInput) => Promise<CapxulResult<List<Withdrawal>, ListCodes$5>>;
+    readonly retrieve: (input: OrgWithdrawalsRetrieveInput) => Promise<CapxulResult<Withdrawal, RetrieveCodes$7>>;
+    readonly list: (input: OrgWithdrawalsListInput) => Promise<CapxulResult<List<Withdrawal>, ListCodes$6>>;
 };
 
 /**
@@ -549,7 +625,7 @@ type OrgWithdrawalsClient = {
  * variant at call time and require `organizationId` explicitly.
  */
 
-type WebhookEndpointsCreateInput = types.CreateWebhookEndpointRequest & {
+type WebhookEndpointsCreateInput = CreateWebhookEndpointRequest & {
     readonly organizationId: OrganizationId;
 };
 type WebhookEndpointsRetrieveInput = {
@@ -563,9 +639,9 @@ type WebhookEndpointsListInput = {
 };
 type WebhookEndpointsRemoveInput = WebhookEndpointsRetrieveInput;
 type CreateCodes$3 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "RATE_LIMITED" | "NETWORK_ERROR";
-type RetrieveCodes$5 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$4 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
-type RemoveCodes$3 = RetrieveCodes$5;
+type RetrieveCodes$6 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$5 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RemoveCodes$3 = RetrieveCodes$6;
 /**
  * Shape returned by `organizations.webhookEndpoints.create` — the
  * one-time `signingSecret` is included here and omitted from every
@@ -576,8 +652,8 @@ type WebhookEndpointCreateResult = WebhookEndpoint & {
 };
 type WebhookEndpointsClient = {
     readonly create: (input: WebhookEndpointsCreateInput) => Promise<CapxulResult<WebhookEndpointCreateResult, CreateCodes$3>>;
-    readonly retrieve: (input: WebhookEndpointsRetrieveInput) => Promise<CapxulResult<WebhookEndpoint, RetrieveCodes$5>>;
-    readonly list: (input: WebhookEndpointsListInput) => Promise<CapxulResult<List<WebhookEndpoint>, ListCodes$4>>;
+    readonly retrieve: (input: WebhookEndpointsRetrieveInput) => Promise<CapxulResult<WebhookEndpoint, RetrieveCodes$6>>;
+    readonly list: (input: WebhookEndpointsListInput) => Promise<CapxulResult<List<WebhookEndpoint>, ListCodes$5>>;
     readonly remove: (input: WebhookEndpointsRemoveInput) => Promise<CapxulResult<void, RemoveCodes$3>>;
 };
 
@@ -598,11 +674,11 @@ type WebhookEventsListInput = {
     readonly endpointId?: string;
     readonly type?: string;
 };
-type RetrieveCodes$4 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$3 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RetrieveCodes$5 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$4 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
 type WebhookEventsClient = {
-    readonly retrieve: (input: WebhookEventsRetrieveInput) => Promise<CapxulResult<WebhookEvent, RetrieveCodes$4>>;
-    readonly list: (input: WebhookEventsListInput) => Promise<CapxulResult<List<WebhookEvent>, ListCodes$3>>;
+    readonly retrieve: (input: WebhookEventsRetrieveInput) => Promise<CapxulResult<WebhookEvent, RetrieveCodes$5>>;
+    readonly list: (input: WebhookEventsListInput) => Promise<CapxulResult<List<WebhookEvent>, ListCodes$4>>;
 };
 
 /**
@@ -661,6 +737,7 @@ type OrgKybProfileRetrieveInput = {
 type OrgCreateSubAccountInput = {
     readonly organizationId: OrganizationId;
     readonly name: string;
+    readonly purpose?: string;
 };
 type OrgCreateExternalAccountInput = {
     readonly organizationId: OrganizationId;
@@ -675,8 +752,8 @@ type OrgCreateExternalAccountInput = {
     readonly last4?: string;
 };
 type CreateCodes$2 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "RATE_LIMITED" | "NETWORK_ERROR";
-type RetrieveCodes$3 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$2 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RetrieveCodes$4 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$3 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
 type UpdateCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "INVALID_INPUT";
 /**
  * Org safe retrieve does NOT surface `SAFE_NOT_READY` — a co-member
@@ -691,7 +768,8 @@ type UpdateCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "IN
  */
 type SafeRetrieveCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
 type TreasuryRetrieveCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "SAFE_NOT_READY";
-type RemoveCodes$2 = RetrieveCodes$3;
+type RemoveCodes$2 = RetrieveCodes$4;
+type SubAccountRemoveCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "INVALID_INPUT";
 type OrgSafesClient = {
     readonly retrieve: (input: OrgSafeRetrieveInput) => Promise<CapxulResult<Safe, SafeRetrieveCodes>>;
 };
@@ -699,52 +777,52 @@ type OrgTreasuryClient = {
     readonly retrieve: (organizationId: OrganizationId) => Promise<CapxulResult<Treasury, TreasuryRetrieveCodes>>;
 };
 type OrgMembersClient = {
-    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<Member>, ListCodes$2>>;
-    readonly retrieve: (input: OrgMemberRetrieveInput) => Promise<CapxulResult<Member, RetrieveCodes$3>>;
+    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<Member>, ListCodes$3>>;
+    readonly retrieve: (input: OrgMemberRetrieveInput) => Promise<CapxulResult<Member, RetrieveCodes$4>>;
     readonly invite: (input: OrgMemberInviteInput) => Promise<CapxulResult<Member, UpdateCodes>>;
     readonly updateRole: (input: OrgMemberUpdateRoleInput) => Promise<CapxulResult<Member, UpdateCodes>>;
     readonly remove: (input: OrgMemberRemoveInput) => Promise<CapxulResult<void, RemoveCodes$2>>;
 };
 type OrgKybProfileClient = {
     readonly start: (input: OrgKybProfileStartInput) => Promise<CapxulResult<KybProfile, CreateCodes$2>>;
-    readonly retrieve: (input: OrgKybProfileRetrieveInput) => Promise<CapxulResult<KybProfile, RetrieveCodes$3>>;
+    readonly retrieve: (input: OrgKybProfileRetrieveInput) => Promise<CapxulResult<KybProfile, RetrieveCodes$4>>;
 };
 type OrgSubAccountsClient = {
-    readonly create: (input: OrgCreateSubAccountInput) => Promise<CapxulResult<SubAccount, UpdateCodes>>;
-    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<SubAccount>, ListCodes$2>>;
+    readonly create: (input: OrgCreateSubAccountInput) => Promise<CapxulResult<SubAccount, UpdateCodes | "PROVIDER_ERROR">>;
+    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<SubAccount>, ListCodes$3 | "PROVIDER_ERROR">>;
     readonly retrieve: (input: {
         readonly organizationId: OrganizationId;
         readonly subAccountId: SubAccountId;
-    }) => Promise<CapxulResult<SubAccount, RetrieveCodes$3>>;
+    }) => Promise<CapxulResult<SubAccount, RetrieveCodes$4 | "PROVIDER_ERROR">>;
     readonly remove: (input: {
         readonly organizationId: OrganizationId;
         readonly subAccountId: SubAccountId;
-    }) => Promise<CapxulResult<void, RemoveCodes$2>>;
+    }) => Promise<CapxulResult<SubAccount, SubAccountRemoveCodes | "PROVIDER_ERROR">>;
 };
 type OrgExternalAccountsClient = {
     readonly create: (input: OrgCreateExternalAccountInput) => Promise<CapxulResult<ExternalAccount, UpdateCodes>>;
-    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<ExternalAccount>, ListCodes$2>>;
+    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<ExternalAccount>, ListCodes$3>>;
     readonly retrieve: (input: {
         readonly organizationId: OrganizationId;
         readonly externalAccountId: ExternalAccountId;
-    }) => Promise<CapxulResult<ExternalAccount, RetrieveCodes$3>>;
+    }) => Promise<CapxulResult<ExternalAccount, RetrieveCodes$4>>;
     readonly remove: (input: {
         readonly organizationId: OrganizationId;
         readonly externalAccountId: ExternalAccountId;
     }) => Promise<CapxulResult<void, RemoveCodes$2>>;
 };
 type OrgBalanceLedgerClient = {
-    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<BalanceLedgerEntry>, ListCodes$2>>;
+    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<BalanceLedgerEntry>, ListCodes$3>>;
     readonly retrieve: (input: {
         readonly organizationId: OrganizationId;
         readonly entryId: string;
-    }) => Promise<CapxulResult<BalanceLedgerEntry, RetrieveCodes$3>>;
+    }) => Promise<CapxulResult<BalanceLedgerEntry, RetrieveCodes$4>>;
 };
 type OrgApiKeysClient = ApiKeysClient;
 type OrganizationsClient = {
     readonly create: (input: OrganizationsCreateInput) => Promise<CapxulResult<Organization, CreateCodes$2>>;
-    readonly retrieve: (organizationId: OrganizationId) => Promise<CapxulResult<Organization, RetrieveCodes$3>>;
-    readonly list: (input?: OrganizationsListInput) => Promise<CapxulResult<List<Organization>, ListCodes$2>>;
+    readonly retrieve: (organizationId: OrganizationId) => Promise<CapxulResult<Organization, RetrieveCodes$4>>;
+    readonly list: (input?: OrganizationsListInput) => Promise<CapxulResult<List<Organization>, ListCodes$3>>;
     readonly update: (input: OrganizationsUpdateInput) => Promise<CapxulResult<Organization, UpdateCodes>>;
     readonly safes: OrgSafesClient;
     readonly treasury: OrgTreasuryClient;
@@ -844,7 +922,7 @@ type TransportState = {
     readonly runtime: TransportRuntime;
 } | {
     readonly status: "error";
-    readonly error: CapxulError;
+    readonly error: CapxulError$1;
 };
 type TransportRuntime = {
     readonly authBaseUrl: string;
@@ -871,6 +949,7 @@ type TransportRuntime = {
  */
 type HttpTransport = {
     readonly fetch: (path: string, init?: RequestInit) => Promise<Response>;
+    readonly ensureRuntime: () => Promise<TransportRuntime>;
     readonly authBaseUrl: string;
     readonly convexUrl: string;
     readonly getState: () => TransportState;
@@ -884,8 +963,11 @@ type HttpTransport = {
 /**
  * Build an `HttpTransport` from a `BrowserCapxulConfig`.
  *
- * Throws `Errors.invalidInput("authBaseUrl" | "convexUrl", reason)`
- * when the build-time-urls variant is missing required URLs.
+ * Throws `CapxulError<"INVALID_INPUT">` with
+ * `details.source === "sdk-config"` when local transport config is
+ * malformed. Backend bootstrap failures also throw `CapxulError`, but
+ * carry `details.source === "backend-bootstrap"` so consumers can
+ * distinguish setup mistakes from server-side bootstrap refusals.
  */
 declare function makeHttpTransport(config: BrowserCapxulConfig): HttpTransport;
 
@@ -899,13 +981,118 @@ declare function makeHttpTransport(config: BrowserCapxulConfig): HttpTransport;
  * `accounts.subAccounts.create(...)` or
  * `organizations.subAccounts.create(...)`), so only `retrieve` and
  * `remove` live at the top level.
+ *
+ * Wired in PR-2a of the funds-v1 balance-closure stack: the backend
+ * always returns truthful `balance: Money` per canon §sub_account
+ * (PR-1 made `toCanonShape` populate it from `computeSubAccountBalance`).
+ * The SDK brands the wire shape and passes the balance through as-is.
+ * NO zero-balance fallback exists at the SDK layer — if the backend
+ * ever omits `balance`, that is a bug to surface, not paper over.
  */
 
-type RetrieveCodes$2 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type RemoveCodes$1 = RetrieveCodes$2;
+type RetrieveCodes$3 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "PROVIDER_ERROR";
+type RemoveCodes$1 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "INVALID_INPUT" | "PROVIDER_ERROR";
 type SubAccountsClient = {
-    readonly retrieve: (subAccountId: SubAccountId) => Promise<CapxulResult<SubAccount, RetrieveCodes$2>>;
-    readonly remove: (subAccountId: SubAccountId) => Promise<CapxulResult<void, RemoveCodes$1>>;
+    readonly retrieve: (subAccountId: SubAccountId) => Promise<CapxulResult<SubAccount, RetrieveCodes$3>>;
+    readonly remove: (subAccountId: SubAccountId) => Promise<CapxulResult<SubAccount, RemoveCodes$1>>;
+};
+
+/**
+ * **NON-CANONICAL surface.**
+ *
+ * `capxul.tokenTransfers.*` exposes the indexer's raw on-chain ERC-20
+ * transfer rows directly to consumers, backed by
+ * `packages/backend/convex/tokenTransfers/queries.ts`. Authorized at
+ * `slice/02-story2-balance` per the conductor's Option-A verdict —
+ * the canonical SDK `transfers.*` namespace assumes a cross-custody
+ * internal-move shape (`Transfer = { source, destination, fx,
+ * operation, ... }`) that has no canon-aligned backing query yet.
+ * Surfacing the on-chain feed under a separate, clearly-marked
+ * non-canonical namespace lets the Ink CLI's activity dashboard
+ * progress without forcing canon synthesis.
+ *
+ * **NOT in `packages/api-contract`.** Do NOT use this surface as the
+ * basis for new canon. When `transfers.*` shape alignment lands
+ * (post-alpha.4 follow-up issue), the canonical `transfers.*` will
+ * subsume this and `tokenTransfers.*` becomes a deprecation alias.
+ *
+ * Stub families that REMAIN deferred at this slice
+ * (per `[DEFERRED-CANON]` markers in
+ * `.claude/worktrees/post-alpha-wire2/.progress.txt`):
+ * - `transfers.{create,retrieve,list,confirm,cancel}` — canon shape mismatch
+ * - `accounts.balanceLedger.{list,retrieve}` — no canon backing query
+ * - `organizations.balanceLedger.*` — no canon backing query
+ * - `organizations.transfers.*` — canon shape mismatch
+ * - `organizations.treasury.retrieve` — backing query has different shape
+ */
+
+/**
+ * Branded id for an on-chain `tokenTransfer` row. Backed by the
+ * Convex document id; the brand prevents accidental swaps with other
+ * SDK ids without leaking the document-id constraint into call sites.
+ *
+ * Returned in `TokenTransfer.id` for clients that want a stable
+ * back-reference; the canonical lookup key is the
+ * `(txHash, logIndex)` composite used by `retrieve`.
+ */
+type TokenTransferId = string & {
+    readonly __capxulTokenTransferIdBrand: "TokenTransferId";
+};
+declare const toTokenTransferId: (raw: string) => TokenTransferId;
+/**
+ * Raw on-chain ERC-20 transfer row. Shape mirrors
+ * `tokenTransfers/queries.ts` `list` / `getByTxLogIndex` output. The
+ * primitive fields (`txHash`, `tokenAddress`, etc.) match
+ * `@repo/api-contract` conventions — `string` for hashes/addresses,
+ * `number` for block + chain ids — so consumers don't need to import
+ * a brand surface that isn't in the SDK's published deps.
+ */
+type TokenTransfer = {
+    readonly id: TokenTransferId;
+    readonly object: "token_transfer";
+    readonly direction: "in" | "out";
+    /** Token-units string ("123456" not "1.23456"). Decimals carried in `tokenDecimals`. */
+    readonly amount: string;
+    readonly tokenSymbol: string;
+    readonly tokenDecimals: number;
+    readonly tokenAddress: string;
+    readonly counterpartyName: string | null;
+    readonly counterpartyAddress: string;
+    readonly description: string;
+    /** Block timestamp in epoch milliseconds. */
+    readonly createdAt: number;
+    readonly txHash: string;
+    readonly blockNumber: number;
+    readonly chainId: number;
+};
+type TokenTransfersListPage = {
+    readonly object: "list";
+    readonly data: readonly TokenTransfer[];
+    readonly page: {
+        readonly hasMore: boolean;
+        /** Block-timestamp cursor (epoch ms) for the next page; null when exhausted. */
+        readonly nextCursor: number | null;
+    };
+    /** Caller's display currency. The backend echoes it so renderers don't need a second round-trip. */
+    readonly displayCurrency: string;
+};
+type TokenTransfersListInput = {
+    readonly limit?: number;
+    /** Block-timestamp cursor (epoch ms) returned in the previous page's `page.nextCursor`. */
+    readonly cursor?: number;
+    readonly direction?: "in" | "out";
+};
+type TokenTransfersRetrieveInput = {
+    readonly txHash: string;
+    readonly logIndex: number;
+    /** Optional chain filter. When omitted, the first index hit wins (single-chain default). */
+    readonly chainId?: number;
+};
+type ListCodes$2 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RetrieveCodes$2 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type TokenTransfersClient = {
+    readonly list: (input?: TokenTransfersListInput) => Promise<CapxulResult<TokenTransfersListPage, ListCodes$2>>;
+    readonly retrieve: (input: TokenTransfersRetrieveInput) => Promise<CapxulResult<TokenTransfer, RetrieveCodes$2>>;
 };
 
 /**
@@ -917,7 +1104,7 @@ type SubAccountsClient = {
  * in the create payload rather than nesting the route under the owner.
  */
 
-type VirtualAccountsCreateInput = types.CreateVirtualAccountRequest;
+type VirtualAccountsCreateInput = CreateVirtualAccountRequest;
 type VirtualAccountsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
@@ -942,7 +1129,7 @@ type VirtualAccountsClient = {
  * Uses Pattern C (ownerKind in body).
  */
 
-type VirtualCardsCreateInput = types.CreateVirtualCardRequest;
+type VirtualCardsCreateInput = CreateVirtualCardRequest;
 type VirtualCardsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
@@ -962,6 +1149,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" | "INDEXER_DELIVERY_TIMEOUT" | "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.
  *
@@ -1089,6 +1431,7 @@ type CapxulConfig = {
  */
 type CapxulFlowFactories = {
     readonly auth: () => AnyStateMachine;
+    readonly authBootstrap: () => ReturnType<typeof createAuthBootstrapFlowMachine>;
     readonly onboarding: () => AnyStateMachine;
     readonly provisioning: () => AnyStateMachine;
 };
@@ -1115,6 +1458,13 @@ type CapxulClient = {
     readonly organizations: OrganizationsClient;
     readonly payments: PaymentsClient;
     readonly transfers: TransfersClient;
+    /**
+     * **NON-CANONICAL.** On-chain ERC-20 transfer feed (raw indexer
+     * rows). NOT part of `packages/api-contract`. Slated for
+     * deprecation when canonical `transfers.*` shape alignment lands.
+     * See `core/token-transfers.ts` for the doc-comment contract.
+     */
+    readonly tokenTransfers: TokenTransfersClient;
     readonly withdrawals: WithdrawalsClient;
     readonly documents: DocumentsClient;
     readonly subAccounts: SubAccountsClient;
@@ -1144,4 +1494,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 HttpTransport as H, type LocalPrivateKeySignerProvider as L, type MeClient as M, type OperationsClient as O, type PaymentsClient as P, type Session as S, type TransfersClient 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 TransportRuntime as s, type TransportState as t, type VirtualCardsClient as u, type WebhookEndpointsClient as v, type WebhookEventsClient as w, type WithdrawalsClient as x, createCapxulClient as y, makeHttpTransport 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 };