@capxul/sdk 0.1.0-alpha.0

package/dist/client-o4R-ZFh2.d.ts

@@ -0,0 +1,1147 @@
+import { Account as Account$1 } from 'viem';
+import { AnyStateMachine } from 'xstate';
+import { AccountId, SafeId, KycProfileId, ExternalAccountId, SubAccountId, OrganizationId, ApiKeyId, TimestampIso, DocumentId, OperationId, PaymentId, TransferId, WithdrawalId, WebhookEndpointId, WebhookEventId, MemberId, KybProfileId, VirtualAccountId, VirtualCardId } from '@repo/platform-kernel';
+import { CapxulResult, CapxulError } from './errors.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-Cokyqgwm.js';
+import * as types from '@repo/api-contract/gen/types';
+
+/**
+ * Accounts domain — individual user accounts per sdk-surface.md §1a.
+ *
+ * Nested namespaces under `accounts.*` follow Pattern A per CANON.md
+ * §4.30: `accounts.safes.retrieve(safeId)`, `accounts.subAccounts.list()`,
+ * etc. — no ambient account context; the argument carries the scope.
+ */
+
+type AccountLookupInput = UserIdentifier;
+type AccountUpdateInput = Partial<{
+    readonly name: string;
+    readonly username: string;
+    readonly countryCode: string;
+}>;
+type LocalPrivateKeySignerProvider = {
+    readonly kind: "local-private-key";
+    readonly signerAddress: string;
+    readonly safeAddress: string;
+};
+type AccountProvisionPersonalInput = {
+    readonly displayName?: string;
+    readonly username?: string;
+    readonly countryCode?: string;
+    readonly signerProvider: LocalPrivateKeySignerProvider;
+};
+type AccountCreateKycProfileInput = {
+    readonly accountId: AccountId;
+};
+type AccountListInput = {
+    readonly limit?: number;
+    readonly cursor?: string;
+};
+type AccountCreateSubAccountInput = {
+    readonly accountId: AccountId;
+    readonly name: string;
+};
+type AccountCreateExternalAccountInput = {
+    readonly accountId: AccountId;
+    readonly kind: "bank" | "evm" | "solana" | "starknet" | "card_payout";
+    readonly label?: string;
+    readonly address?: string;
+    readonly iban?: string;
+    readonly bic?: string;
+    readonly accountHolder?: string;
+    readonly network?: "visa" | "mastercard";
+    readonly panToken?: string;
+    readonly last4?: string;
+};
+type RetrieveCodes$d = "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 SafeRetrieveCodes$1 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "SAFE_NOT_READY";
+type RemoveCodes$5 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+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>>;
+};
+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>>;
+    readonly remove: (externalAccountId: ExternalAccountId) => Promise<CapxulResult<void, RemoveCodes$5>>;
+};
+type AccountSubAccountsClient = {
+    readonly create: (input: AccountCreateSubAccountInput) => Promise<CapxulResult<SubAccount, UpdateCodes$1>>;
+    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>>;
+};
+type AccountBalanceLedgerClient = {
+    readonly list: (input: {
+        readonly accountId: AccountId;
+    } & AccountListInput) => Promise<CapxulResult<List<BalanceLedgerEntry>, ListCodes$a>>;
+    readonly retrieve: (entryId: string) => Promise<CapxulResult<BalanceLedgerEntry, RetrieveCodes$d>>;
+};
+type AccountsClient = {
+    readonly retrieve: (accountId: AccountId) => Promise<CapxulResult<Account, RetrieveCodes$d>>;
+    readonly lookup: (input: AccountLookupInput) => Promise<CapxulResult<AccountLookupResult, LookupCodes>>;
+    readonly update: (input: {
+        readonly accountId: AccountId;
+    } & AccountUpdateInput) => Promise<CapxulResult<Account, UpdateCodes$1>>;
+    readonly provisionPersonal: (input: AccountProvisionPersonalInput) => Promise<CapxulResult<Account, UpdateCodes$1 | "NETWORK_ERROR">>;
+    readonly safes: AccountSafesClient;
+    readonly kycProfiles: AccountKycProfilesClient;
+    readonly externalAccounts: AccountExternalAccountsClient;
+    readonly subAccounts: AccountSubAccountsClient;
+    readonly balanceLedger: AccountBalanceLedgerClient;
+};
+
+/**
+ * API keys domain — org-issued credentials per sdk-surface.md §1b +
+ * §4.21 + §4.57. Key types: `cap_test_` / `cap_live_` (secret) and
+ * `cap_pk_test_` / `cap_pk_live_` (publishable).
+ *
+ * All methods are org-nested. The one-time `secret` value is returned
+ * on `create` only; subsequent reads omit it.
+ */
+
+type ApiKeysCreateInput = types.CreateApiKeyRequest & {
+    readonly organizationId: OrganizationId;
+};
+type ApiKeysRetrieveInput = {
+    readonly organizationId: OrganizationId;
+    readonly apiKeyId: ApiKeyId;
+};
+type ApiKeysListInput = {
+    readonly organizationId: OrganizationId;
+    readonly limit?: number;
+    readonly cursor?: string;
+};
+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;
+/**
+ * Shape returned by `organizations.apiKeys.create` — the one-time
+ * secret `value` is included here and omitted from every subsequent
+ * read.
+ */
+type ApiKeyCreateResult = ApiKey & {
+    readonly value: string;
+};
+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 revoke: (input: ApiKeysRevokeInput) => Promise<CapxulResult<ApiKey, RevokeCodes>>;
+};
+
+interface CapxulDataClient {
+    query(name: any, args: any): Promise<any>;
+    mutation(name: any, args: any): Promise<any>;
+    action?(name: any, args: any): Promise<any>;
+}
+
+/**
+ * Authentication domain.
+ *
+ * Maps 1:1 to `/v1/auth/*` HTTP endpoints. Human sign-in via email OTP;
+ * partner servers mint short-lived service tokens from a long-lived
+ * API key per sdk-surface.md §3.2.
+ *
+ * Stack-1 update: outbound HTTP routes through `makeHttpTransport`
+ * (`packages/sdk/src/transport.ts`) so that `core/auth.ts` no longer
+ * owns base-URL validation or `fetch` indirection. The BetterAuth
+ * `/api/auth` path-mangling stays here — it is auth-protocol-specific
+ * and the transport layer is auth-protocol-agnostic by design.
+ *
+ * Lazy transport construction: when `config.auth.baseUrl` is absent the
+ * SDK is in scaffold/CLI mode and `sendOtp` / `verifyOtp` return the
+ * `NOT_IMPLEMENTED` `stub` tuple (preserving the prior behavior). Only
+ * when `baseUrl` is configured do we construct the transport — at
+ * which point the build-time-urls variant of `BrowserCapxulConfig`
+ * runs its own `Errors.invalidInput` validation.
+ */
+
+type Session = {
+    readonly authUserId: string;
+    readonly accountId?: AccountId;
+    readonly email: string;
+    readonly token: string;
+    readonly convexJwt?: string;
+    readonly expiresAt: TimestampIso;
+};
+type AuthSessionStore = {
+    get(): Session | null;
+    set(session: Session): void;
+    clear(): void;
+};
+type AuthSendOtpInput = {
+    readonly email: string;
+};
+type AuthVerifyOtpInput = {
+    readonly email: string;
+    readonly otp: string;
+};
+type AuthServiceTokenMintInput = {
+    readonly apiKey: string;
+    readonly audience?: string;
+};
+/**
+ * Options bag for auth methods that perform outbound `fetch` work.
+ *
+ * Accepts an `AbortSignal` so XState v5 actors (and any other caller
+ * that wants cancellation) can cancel the in-flight HTTP request when
+ * the actor stops. The signal flows through `transport.fetch`'s
+ * `RequestInit.signal` and into the underlying `fetch` impl, so
+ * `signal.aborted === true` propagates to the network layer per the
+ * Web Platform `fetch` contract. See PR #406 S5.
+ */
+type AuthMethodOptions = {
+    readonly signal?: AbortSignal;
+};
+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 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 getSession: () => Promise<CapxulResult<Session | null, GetSessionCodes>>;
+    readonly signOut: () => Promise<CapxulResult<void, SignOutCodes>>;
+    readonly serviceTokenMint: (input: AuthServiceTokenMintInput) => Promise<CapxulResult<ServiceToken, ServiceTokenMintCodes>>;
+    /** Internal bridge for flow hooks that need the authenticated Convex data client. */
+    readonly getDataClient: () => CapxulDataClient | null;
+};
+
+/**
+ * Documents domain — unified artifact primitive per sdk-surface.md §1a
+ * + §4.50.
+ *
+ * Subsumes the former `invoice` and `org_payroll_entry` top-level
+ * primitives. The `Document` union discriminates on `type`:
+ * `invoice | payroll_run | payroll_schedule | receipt | kyc_upload |
+ * bank_statement | tax_form`.
+ */
+
+type DocumentsCreateInput = types.CreateDocumentRequest;
+type DocumentsListInput = {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly type?: Document["type"];
+};
+type OrgDocumentsCreateInput = DocumentsCreateInput & {
+    readonly organizationId: OrganizationId;
+};
+type OrgDocumentsRetrieveInput = {
+    readonly organizationId: OrganizationId;
+    readonly documentId: DocumentId;
+};
+type OrgDocumentsListInput = {
+    readonly organizationId: OrganizationId;
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly type?: Document["type"];
+};
+type OrgDocumentsCancelInput = {
+    readonly organizationId: OrganizationId;
+    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 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 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 cancel: (input: OrgDocumentsCancelInput) => Promise<CapxulResult<Document, CancelCodes$1>>;
+};
+
+/**
+ * External-accounts domain — top-level `capxul.externalAccounts.*`.
+ *
+ * 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.
+ */
+
+type RetrieveCodes$a = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type RemoveCodes$4 = RetrieveCodes$a;
+type ExternalAccountsClient = {
+    readonly retrieve: (externalAccountId: ExternalAccountId) => Promise<CapxulResult<ExternalAccount, RetrieveCodes$a>>;
+    readonly remove: (externalAccountId: ExternalAccountId) => Promise<CapxulResult<void, RemoveCodes$4>>;
+};
+
+/**
+ * `me` — first-party-only surface for the authenticated user.
+ *
+ * Partner SDK code (service-key lens) uses `capxul.accounts.retrieve(id)`
+ * instead. This namespace exists because the CLI and `useMe()` hook
+ * in `@capxul/sdk-react` always know the calling user and shouldn't
+ * need to pass the account id.
+ *
+ * See `/docs/internal/reset/sdk-surface` + `packages/sdk/tests/walkthroughs/me-retrieve.ts`.
+ */
+
+type MeUpdateInput = Partial<{
+    readonly name: string;
+    readonly username: string;
+    readonly countryCode: string;
+}>;
+type MeGetCodes = "NOT_AUTHENTICATED" | "PROFILE_NOT_FOUND";
+type MeUpdateCodes = "NOT_AUTHENTICATED" | "PROFILE_NOT_FOUND" | "INVALID_INPUT";
+type MeClient = {
+    readonly get: () => Promise<CapxulResult<Account, MeGetCodes>>;
+    readonly update: (input: MeUpdateInput) => Promise<CapxulResult<Account, MeUpdateCodes>>;
+};
+
+/**
+ * Operations domain — durable async-work envelope per sdk-surface.md §1b.
+ *
+ * `retrieve` is a snapshot read (no polling). `wait` is the opt-in
+ * polling helper per CANON.md §4.40 — caller explicitly asks to block
+ * until a terminal condition or timeout.
+ */
+
+type OperationsWaitInput = {
+    readonly until?: readonly OperationStatus[];
+    readonly timeoutSeconds?: number;
+    readonly pollIntervalMs?: number;
+};
+type RetrieveCodes$9 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type WaitCodes = RetrieveCodes$9 | "OPERATION_TIMEOUT";
+type OperationsClient = {
+    readonly retrieve: (operationId: OperationId) => Promise<CapxulResult<Operation, RetrieveCodes$9>>;
+    readonly wait: (operationId: OperationId, input?: OperationsWaitInput) => Promise<CapxulResult<Operation, WaitCodes>>;
+};
+
+/**
+ * Payments domain.
+ *
+ * Exposes both the personal-scope `PaymentsClient` (under
+ * `capxul.payments.*`) and the org-scoped `OrgPaymentsClient` (under
+ * `capxul.organizations.payments.*`). The org variant takes
+ * `organizationId` explicitly on every call; there is no ambient org
+ * context.
+ *
+ * See `/docs/internal/reset/sdk-surface` and the walkthroughs in
+ * `packages/sdk/tests/walkthroughs/`.
+ */
+
+type PaymentsCreateInput = {
+    readonly to: UserIdentifier;
+    readonly amount: Money;
+    readonly reference?: string;
+    readonly idempotencyKey?: string;
+    readonly include?: readonly string[];
+    /**
+     * Funds v1 (#420): tag the payment with the originating sub-account.
+     * This personal data-path forwards the field to Convex; broader
+     * organization and React hook wiring lands in #421 alongside
+     * `include: ["balancesByCustody"]` read paths.
+     */
+    readonly source?: {
+        readonly subAccountId: SubAccountId;
+    };
+};
+type PaymentsListInput = {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly include?: readonly string[];
+};
+type OrgPaymentsCreateInput = {
+    readonly organizationId: OrganizationId;
+    readonly source?: {
+        readonly subAccountId: SubAccountId;
+    };
+    readonly to: UserIdentifier;
+    readonly amount: Money;
+    readonly reference?: string;
+    readonly idempotencyKey?: string;
+    readonly include?: readonly string[];
+};
+type OrgPaymentsRetrieveInput = {
+    readonly organizationId: OrganizationId;
+    readonly paymentId: PaymentId;
+};
+type OrgPaymentsListInput = {
+    readonly organizationId: OrganizationId;
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly include?: readonly string[];
+};
+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 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>>;
+};
+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>>;
+};
+
+/**
+ * Transfers domain — cross-custody internal moves per CANON.md §4.53.
+ *
+ * A transfer moves balance between custody sources owned by the same
+ * account or organization (e.g. EUR virtual-account → USD stablecoin
+ * pool). When currencies differ the wire carries an `fx` block with a
+ * quote id the caller confirms via `transfers.confirm(...)` per §4.58.
+ */
+
+type TransfersCreateInput = {
+    readonly source: TransferEndpoint;
+    readonly destination: TransferEndpoint;
+    readonly amount: Money;
+    readonly idempotencyKey?: string;
+    readonly include?: readonly string[];
+};
+type TransfersListInput = {
+    readonly limit?: number;
+    readonly cursor?: string;
+};
+type TransfersConfirmInput = {
+    readonly transferId: TransferId;
+    readonly quoteId: string;
+};
+type OrgTransfersCreateInput = TransfersCreateInput & {
+    readonly organizationId: OrganizationId;
+};
+type OrgTransfersRetrieveInput = {
+    readonly organizationId: OrganizationId;
+    readonly transferId: TransferId;
+};
+type OrgTransfersListInput = {
+    readonly organizationId: OrganizationId;
+    readonly limit?: number;
+    readonly cursor?: string;
+};
+type OrgTransfersConfirmInput = {
+    readonly organizationId: OrganizationId;
+    readonly transferId: TransferId;
+    readonly quoteId: string;
+};
+type OrgTransfersCancelInput = {
+    readonly organizationId: OrganizationId;
+    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 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 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 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.
+ *
+ * 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.
+ */
+
+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;
+    };
+    readonly reference?: string;
+    readonly idempotencyKey?: string;
+    readonly include?: readonly string[];
+};
+type WithdrawalsListInput = {
+    readonly limit?: number;
+    readonly cursor?: string;
+};
+type OrgWithdrawalsCreateInput = WithdrawalsCreateInput & {
+    readonly organizationId: OrganizationId;
+};
+type OrgWithdrawalsRetrieveInput = {
+    readonly organizationId: OrganizationId;
+    readonly withdrawalId: WithdrawalId;
+};
+type OrgWithdrawalsListInput = {
+    readonly organizationId: OrganizationId;
+    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 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>>;
+};
+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>>;
+};
+
+/**
+ * Webhook endpoints domain — developer-registered receivers per
+ * sdk-surface.md §1b. All methods are org-nested (accessed via
+ * `capxul.organizations.webhookEndpoints.*` per CANON.md §4.30).
+ * The top-level `webhookEndpoints` surface on `CapxulClient` is kept
+ * as an alias for discoverability; its methods proxy to the org
+ * variant at call time and require `organizationId` explicitly.
+ */
+
+type WebhookEndpointsCreateInput = types.CreateWebhookEndpointRequest & {
+    readonly organizationId: OrganizationId;
+};
+type WebhookEndpointsRetrieveInput = {
+    readonly organizationId: OrganizationId;
+    readonly webhookEndpointId: WebhookEndpointId;
+};
+type WebhookEndpointsListInput = {
+    readonly organizationId: OrganizationId;
+    readonly limit?: number;
+    readonly cursor?: string;
+};
+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;
+/**
+ * Shape returned by `organizations.webhookEndpoints.create` — the
+ * one-time `signingSecret` is included here and omitted from every
+ * subsequent read (per sdk-surface.md §1b).
+ */
+type WebhookEndpointCreateResult = WebhookEndpoint & {
+    readonly signingSecret: string;
+};
+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 remove: (input: WebhookEndpointsRemoveInput) => Promise<CapxulResult<void, RemoveCodes$3>>;
+};
+
+/**
+ * Webhook events domain — individual delivery attempt + payload per
+ * sdk-surface.md §1b. v1 is read-only (partner replay lands in v1.5
+ * per §4.20). All methods are org-nested.
+ */
+
+type WebhookEventsRetrieveInput = {
+    readonly organizationId: OrganizationId;
+    readonly webhookEventId: WebhookEventId;
+};
+type WebhookEventsListInput = {
+    readonly organizationId: OrganizationId;
+    readonly limit?: number;
+    readonly cursor?: string;
+    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 WebhookEventsClient = {
+    readonly retrieve: (input: WebhookEventsRetrieveInput) => Promise<CapxulResult<WebhookEvent, RetrieveCodes$4>>;
+    readonly list: (input: WebhookEventsListInput) => Promise<CapxulResult<List<WebhookEvent>, ListCodes$3>>;
+};
+
+/**
+ * Organizations domain per sdk-surface.md §1a.
+ *
+ * The org surface is broad because org-scoped flows for every money-
+ * movement + identity primitive live under `organizations.*` per
+ * CANON.md §4.30 (Shape A). Sub-client factories delegate to the
+ * dedicated domain factories in `core/*.ts` so the tuple-return +
+ * error-narrowing plumbing is shared.
+ */
+
+type OrganizationsCreateInput = {
+    readonly name: string;
+    readonly country: string;
+};
+type OrganizationsListInput = {
+    readonly limit?: number;
+    readonly cursor?: string;
+};
+type OrganizationsUpdateInput = {
+    readonly organizationId: OrganizationId;
+    readonly name?: string;
+};
+type OrgSafeRetrieveInput = {
+    readonly organizationId: OrganizationId;
+    readonly safeId: SafeId;
+};
+type OrgMemberInviteInput = {
+    readonly organizationId: OrganizationId;
+    readonly email: string;
+    readonly role: Member["role"];
+};
+type OrgMemberUpdateRoleInput = {
+    readonly organizationId: OrganizationId;
+    readonly memberId: MemberId;
+    readonly role: Member["role"];
+};
+type OrgMemberRemoveInput = {
+    readonly organizationId: OrganizationId;
+    readonly memberId: MemberId;
+};
+type OrgMemberRetrieveInput = OrgMemberRemoveInput;
+type OrgListInput = {
+    readonly organizationId: OrganizationId;
+    readonly limit?: number;
+    readonly cursor?: string;
+};
+type OrgKybProfileStartInput = {
+    readonly organizationId: OrganizationId;
+};
+type OrgKybProfileRetrieveInput = {
+    readonly organizationId: OrganizationId;
+    readonly kybProfileId: KybProfileId;
+};
+type OrgCreateSubAccountInput = {
+    readonly organizationId: OrganizationId;
+    readonly name: string;
+};
+type OrgCreateExternalAccountInput = {
+    readonly organizationId: OrganizationId;
+    readonly kind: "bank" | "evm" | "solana" | "starknet" | "card_payout";
+    readonly label?: string;
+    readonly address?: string;
+    readonly iban?: string;
+    readonly bic?: string;
+    readonly accountHolder?: string;
+    readonly network?: "visa" | "mastercard";
+    readonly panToken?: string;
+    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 UpdateCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "INVALID_INPUT";
+/**
+ * Org safe retrieve does NOT surface `SAFE_NOT_READY` — a co-member
+ * who tries to read an in-flight Safe hits `PERMISSION_DENIED` (Safes
+ * are admin-lens-only), and an admin gets `processing` via the
+ * operation field. The mid-deploy balance view surfaces via
+ * `treasury.retrieve` which DOES carry `SAFE_NOT_READY`.
+ *
+ * Contrast with `accounts.safes.retrieve` which DOES surface
+ * `SAFE_NOT_READY` because personal Safes are visible to the owner
+ * while deploying.
+ */
+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 OrgSafesClient = {
+    readonly retrieve: (input: OrgSafeRetrieveInput) => Promise<CapxulResult<Safe, SafeRetrieveCodes>>;
+};
+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 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>>;
+};
+type OrgSubAccountsClient = {
+    readonly create: (input: OrgCreateSubAccountInput) => Promise<CapxulResult<SubAccount, UpdateCodes>>;
+    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<SubAccount>, ListCodes$2>>;
+    readonly retrieve: (input: {
+        readonly organizationId: OrganizationId;
+        readonly subAccountId: SubAccountId;
+    }) => Promise<CapxulResult<SubAccount, RetrieveCodes$3>>;
+    readonly remove: (input: {
+        readonly organizationId: OrganizationId;
+        readonly subAccountId: SubAccountId;
+    }) => Promise<CapxulResult<void, RemoveCodes$2>>;
+};
+type OrgExternalAccountsClient = {
+    readonly create: (input: OrgCreateExternalAccountInput) => Promise<CapxulResult<ExternalAccount, UpdateCodes>>;
+    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<ExternalAccount>, ListCodes$2>>;
+    readonly retrieve: (input: {
+        readonly organizationId: OrganizationId;
+        readonly externalAccountId: ExternalAccountId;
+    }) => Promise<CapxulResult<ExternalAccount, RetrieveCodes$3>>;
+    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 retrieve: (input: {
+        readonly organizationId: OrganizationId;
+        readonly entryId: string;
+    }) => Promise<CapxulResult<BalanceLedgerEntry, RetrieveCodes$3>>;
+};
+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 update: (input: OrganizationsUpdateInput) => Promise<CapxulResult<Organization, UpdateCodes>>;
+    readonly safes: OrgSafesClient;
+    readonly treasury: OrgTreasuryClient;
+    readonly members: OrgMembersClient;
+    readonly apiKeys: OrgApiKeysClient;
+    readonly kybProfile: OrgKybProfileClient;
+    readonly subAccounts: OrgSubAccountsClient;
+    readonly externalAccounts: OrgExternalAccountsClient;
+    readonly balanceLedger: OrgBalanceLedgerClient;
+    readonly payments: OrgPaymentsClient;
+    readonly transfers: OrgTransfersClient;
+    readonly withdrawals: OrgWithdrawalsClient;
+    readonly documents: OrgDocumentsClient;
+    readonly webhookEndpoints: WebhookEndpointsClient;
+    readonly webhookEvents: WebhookEventsClient;
+};
+
+/**
+ * HTTP transport — the SDK's outbound network seam AND the canonical
+ * lifecycle observable for the publishable-key DX path (ADR #14c).
+ *
+ * The transport plays two roles:
+ *
+ * 1. **Network seam.** `fetch(path, init?)` resolves a path against
+ *    `authBaseUrl` (absolute URLs are forwarded unchanged). The
+ *    `build-time-urls` arm exposes the URLs immediately; the
+ *    `publishable-key` arm resolves them lazily on first use through
+ *    `/v1/client/bootstrap`, with singleflight + reset-on-failure.
+ *
+ * 2. **Lifecycle observable.** A 5-state machine
+ *    (`idle → bootstrapping → ready → authenticated → error`) drives
+ *    the React `useCapxulStatus()` hook. The transport is a stable
+ *    singleton across renders — React subscribes to its lifecycle via
+ *    `useSyncExternalStore` and re-renders only when the state
+ *    transitions, never because the provider rebuilt.
+ *
+ * The transport is auth-protocol-agnostic. Path mangling like
+ * BetterAuth's `/api/auth` prefix lives in `core/auth.ts` and stays
+ * out of this file.
+ */
+
+/**
+ * Browser-side SDK config — discriminated union per ADR 5.
+ *
+ * Stack 2 ships the full union:
+ * - `mode: "build-time-urls"` for explicit local/dev wiring
+ * - `mode: "publishable-key"` for browser-safe lazy bootstrap through
+ *   `/v1/client/bootstrap`
+ */
+type BrowserCapxulConfig = {
+    readonly mode: "build-time-urls";
+    readonly authBaseUrl: string;
+    readonly convexUrl: string;
+    /**
+     * Inject a `fetch` implementation. Defaults to `globalThis.fetch`.
+     * Named `fetchImpl` to avoid shadowing the global.
+     */
+    readonly fetchImpl?: typeof fetch;
+} | {
+    readonly mode: "publishable-key";
+    readonly publishableKey: string;
+    /**
+     * Override the absolute URL used for `/v1/client/bootstrap`.
+     *
+     * Defaults to `${CAPXUL_API_BASE_URL}/v1/client/bootstrap` from
+     * `@repo/config`. Tests and alternative staging deployments set
+     * this to point at a local mock server or a non-alpha Convex
+     * site. A trailing slash is stripped before joining.
+     */
+    readonly bootstrapUrl?: string;
+    readonly fetchImpl?: typeof fetch;
+};
+/**
+ * Transport lifecycle state — the canonical state machine for the
+ * publishable-key DX path per ADR #14c.
+ *
+ * Transitions:
+ * - `idle → bootstrapping` on first network call
+ * - `bootstrapping → ready` on successful `/v1/client/bootstrap`
+ * - `bootstrapping → error` on bootstrap failure
+ * - `error → bootstrapping` when a subsequent caller retries (reset-on-failure)
+ * - `ready → authenticated` via `markAuthenticated()` after verifyOtp
+ * - `authenticated → ready` via `signOut()` / `clearAuth()`
+ *
+ * The `build-time-urls` arm starts in `ready` immediately because no
+ * bootstrap is required.
+ */
+type TransportState = {
+    readonly status: "idle";
+} | {
+    readonly status: "bootstrapping";
+} | {
+    readonly status: "ready";
+    readonly runtime: TransportRuntime;
+} | {
+    readonly status: "authenticated";
+    readonly runtime: TransportRuntime;
+} | {
+    readonly status: "error";
+    readonly error: CapxulError;
+};
+type TransportRuntime = {
+    readonly authBaseUrl: string;
+    readonly convexUrl: string;
+};
+/**
+ * HTTP transport surface consumed by every domain client (auth, me,
+ * payments, …) once Stack 1 task 1.5 routes them through here.
+ *
+ * - `fetch(path, init?)` resolves a relative path against
+ *   `authBaseUrl` (absolute URLs are forwarded unchanged).
+ * - `authBaseUrl` and `convexUrl` are exposed as resolved values so
+ *   downstream consumers (e.g. Convex client construction) can read
+ *   them directly. The publishable-key arm populates these lazily
+ *   after the first bootstrap resolution; before that they are empty
+ *   strings.
+ * - `getState()` / `subscribe()` are the React-friendly observable
+ *   surface for `useCapxulStatus()`. Use `useSyncExternalStore` on the
+ *   React side.
+ * - `markAuthenticated()` / `clearAuth()` are the post-verifyOtp /
+ *   post-signOut transition methods (ADR #14c contract item 3 — the
+ *   provider does NOT setState; it lets the transport's state machine
+ *   drive React subscriptions).
+ */
+type HttpTransport = {
+    readonly fetch: (path: string, init?: RequestInit) => Promise<Response>;
+    readonly authBaseUrl: string;
+    readonly convexUrl: string;
+    readonly getState: () => TransportState;
+    readonly subscribe: (listener: () => void) => () => void;
+    readonly getDataClient: () => CapxulDataClient | null;
+    readonly markAuthenticated: (opts: {
+        readonly dataClient?: CapxulDataClient;
+    }) => void;
+    readonly clearAuth: () => void;
+};
+/**
+ * Build an `HttpTransport` from a `BrowserCapxulConfig`.
+ *
+ * Throws `Errors.invalidInput("authBaseUrl" | "convexUrl", reason)`
+ * when the build-time-urls variant is missing required URLs.
+ */
+declare function makeHttpTransport(config: BrowserCapxulConfig): HttpTransport;
+
+/**
+ * Sub-accounts domain — the top-level `capxul.subAccounts.*` surface.
+ *
+ * Per sdk-surface.md §1a, `sub_account` is a named partition under an
+ * account or organization that aggregates balance across custody
+ * sources (stablecoin pool + virtual accounts + cards). `create` and
+ * `list` live on the owner's nested namespace (Pattern A —
+ * `accounts.subAccounts.create(...)` or
+ * `organizations.subAccounts.create(...)`), so only `retrieve` and
+ * `remove` live at the top level.
+ */
+
+type RetrieveCodes$2 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type RemoveCodes$1 = RetrieveCodes$2;
+type SubAccountsClient = {
+    readonly retrieve: (subAccountId: SubAccountId) => Promise<CapxulResult<SubAccount, RetrieveCodes$2>>;
+    readonly remove: (subAccountId: SubAccountId) => Promise<CapxulResult<void, RemoveCodes$1>>;
+};
+
+/**
+ * Virtual accounts domain — International Bank Account Number (IBAN)-
+ * bearing receive rails per sdk-surface.md §1a + §4.51.
+ *
+ * Uses Pattern C (ownerKind in body): the caller specifies
+ * `owner = { kind: "account" | "sub_account" | "organization", id: ... }`
+ * in the create payload rather than nesting the route under the owner.
+ */
+
+type VirtualAccountsCreateInput = types.CreateVirtualAccountRequest;
+type VirtualAccountsListInput = {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly ownerKind?: "account" | "sub_account" | "organization";
+    readonly ownerId?: string;
+};
+type CreateCodes$1 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "KYC_REQUIRED" | "PROVIDER_UNAVAILABLE" | "RATE_LIMITED" | "NETWORK_ERROR";
+type RetrieveCodes$1 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$1 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RemoveCodes = RetrieveCodes$1;
+type VirtualAccountsClient = {
+    readonly create: (input: VirtualAccountsCreateInput) => Promise<CapxulResult<VirtualAccount, CreateCodes$1>>;
+    readonly retrieve: (virtualAccountId: VirtualAccountId) => Promise<CapxulResult<VirtualAccount, RetrieveCodes$1>>;
+    readonly list: (input?: VirtualAccountsListInput) => Promise<CapxulResult<List<VirtualAccount>, ListCodes$1>>;
+    readonly remove: (virtualAccountId: VirtualAccountId) => Promise<CapxulResult<void, RemoveCodes>>;
+};
+
+/**
+ * Virtual cards domain — issued Visa / Mastercard spending sub-account
+ * balance per sdk-surface.md §1a + §4.51.
+ *
+ * Uses Pattern C (ownerKind in body).
+ */
+
+type VirtualCardsCreateInput = types.CreateVirtualCardRequest;
+type VirtualCardsListInput = {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly ownerKind?: "account" | "sub_account" | "organization";
+    readonly ownerId?: string;
+};
+type CreateCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "KYC_REQUIRED" | "PROVIDER_UNAVAILABLE" | "RATE_LIMITED" | "NETWORK_ERROR";
+type RetrieveCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type MutateCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "PROVIDER_UNAVAILABLE";
+type VirtualCardsClient = {
+    readonly create: (input: VirtualCardsCreateInput) => Promise<CapxulResult<VirtualCard, CreateCodes>>;
+    readonly retrieve: (virtualCardId: VirtualCardId) => Promise<CapxulResult<VirtualCard, RetrieveCodes>>;
+    readonly list: (input?: VirtualCardsListInput) => Promise<CapxulResult<List<VirtualCard>, ListCodes>>;
+    readonly freeze: (virtualCardId: VirtualCardId) => Promise<CapxulResult<VirtualCard, MutateCodes>>;
+    readonly unfreeze: (virtualCardId: VirtualCardId) => Promise<CapxulResult<VirtualCard, MutateCodes>>;
+    readonly cancel: (virtualCardId: VirtualCardId) => Promise<CapxulResult<VirtualCard, MutateCodes>>;
+};
+
+/**
+ * Root `@capxul/sdk` client factory.
+ *
+ * Canonical construction per sdk-surface.md §3a:
+ *
+ * ```ts
+ * import { createCapxulClient, createLocalSigner } from "@capxul/sdk";
+ *
+ * const capxul = createCapxulClient({
+ *   apiKey: process.env.CAPXUL_API_KEY!,
+ *   signer: createLocalSigner(process.env.CAPXUL_PRIVATE_KEY as `0x${string}`),
+ * });
+ * ```
+ *
+ * Three auth modes are mutually exclusive:
+ * - `apiKey` — server-to-server partner flows (`cap_live_` / `cap_test_`)
+ * - `publishableKey` — installed-app flows with OTP-established human
+ *   sessions (`cap_pk_live_` / `cap_pk_test_`); sessions persist
+ *   via the SDK's auth adapter (file / cookie depending on runtime)
+ * - neither — unauthenticated only; useful for `auth.sendOtp` +
+ *   `auth.verifyOtp` bootstrap before a session exists
+ *
+ * The `signer` (viem `Account`) is required for methods that submit
+ * on-chain UserOperations (payments, withdrawals, transfers) per
+ * CANON.md §4.28.
+ */
+
+type CapxulSigningConfig = {
+    /** EVM chain ID (currently Base Sepolia). */
+    readonly chainId: number;
+    /** JSON-RPC URL for UserOperation submission. */
+    readonly rpcUrl: string;
+    /** Alchemy gas policy ID for UserOperation sponsorship. */
+    readonly gasPolicyId: string;
+};
+type CapxulAuthConfig = {
+    /**
+     * Convex `.site` URL that hosts the BetterAuth endpoints.
+     *
+     * Optional when the client is configured with a publishable key and
+     * lazy bootstrap resolves the runtime URLs instead.
+     */
+    readonly baseUrl?: string;
+    /** Optional explicit Convex token endpoint. Defaults to `${baseUrl}/api/auth/convex/token`. */
+    readonly convexTokenUrl?: string;
+    /** Scenario/browser-local session store shared by auth + onboarding hooks. */
+    readonly sessionStore?: AuthSessionStore;
+    /**
+     * Optional bridge for environments that can build an authenticated data
+     * client after BetterAuth returns a session.
+     */
+    readonly createDataClient?: (session: Session) => Promise<CapxulDataClient>;
+};
+type CapxulConfig = {
+    /** Server-to-server partner key. Mutually exclusive with `publishableKey`. */
+    readonly apiKey?: string;
+    /**
+     * Installed-app publishable key. Pairs with an OTP-established human
+     * session persisted by the SDK's auth adapter.
+     */
+    readonly publishableKey?: string;
+    /**
+     * viem `Account` used to sign UserOperations for on-chain methods
+     * (payments, withdrawals, transfers) per CANON.md §4.28.
+     */
+    readonly signer?: Account$1;
+    /**
+     * Inject an authenticated Convex data client.
+     *
+     * Slice F.2 uses this for the restart payment + operation runtime
+     * path while the `/v1/*` service-token bridge remains unfinished.
+     */
+    readonly data?: CapxulDataClient;
+    /**
+     * Chain + bundler configuration for on-chain submission.
+     *
+     * Required alongside `signer` for runtime `payments.create`.
+     */
+    readonly signing?: CapxulSigningConfig;
+    /** Human OTP auth runtime configuration. */
+    readonly auth?: CapxulAuthConfig;
+    /**
+     * Override the API base URL. Defaults to `https://api.capxul.com`
+     * in production builds; point at `http://localhost:<port>/v1` for
+     * local development against Convex's httpAction router.
+     */
+    readonly baseUrl?: string;
+    /**
+     * Inject a `fetch` implementation. Defaults to global `fetch`. Used
+     * for testing or to plug in `undici` / `node-fetch` in older Node
+     * environments.
+     */
+    readonly fetch?: typeof fetch;
+    /**
+     * @internal
+     *
+     * Inject a pre-built `HttpTransport`. The `@capxul/sdk-react`
+     * `CapxulProvider` uses this in the lazy-DX path (ADR #14c) so the
+     * provider's externally-built transport is the SAME singleton used by
+     * the auth client's bootstrap calls. Without injection, the SDK would
+     * build a second transport internally — the `useCapxulStatus()` hook
+     * would observe a different state machine than the one auth methods
+     * actually drive.
+     *
+     * Underscored to mark it as an internal SDK seam, not a partner-facing
+     * config field. Do not document publicly.
+     */
+    readonly _transport?: HttpTransport;
+};
+/**
+ * Per-call factories for the three Stack-1 XState v5 flow machines.
+ *
+ * Each factory returns a fresh machine instance bound to this
+ * `CapxulClient`. The consumer is responsible for creating a single
+ * actor (e.g. via `createActor` / React's `useMemo` + `useActor`) and
+ * keeping it alive for the duration of the flow. Calling a factory
+ * twice yields two independent machines — useful for parallel
+ * onboarding sessions in tests, never the desired pattern in app code.
+ *
+ * The return types are intentionally erased to `AnyStateMachine` to
+ * keep this surface stable across XState v5 type-parameter changes;
+ * downstream consumers (`@capxul/sdk-react` hooks, the e2e harness's
+ * `xstateFlowSequence` primitive) re-import the precise types from
+ * `./flows/*` when they need them.
+ */
+type CapxulFlowFactories = {
+    readonly auth: () => AnyStateMachine;
+    readonly onboarding: () => AnyStateMachine;
+    readonly provisioning: () => AnyStateMachine;
+};
+type CapxulClient = {
+    /**
+     * @internal
+     *
+     * Per-client UUID minted at construction. Used as a TanStack Query
+     * cache-key prefix to isolate per-client cache when multiple
+     * `CapxulClient` instances are mounted in the same React tree.
+     *
+     * MUST NOT be passed to `identify()`, `track()`, or any analytics
+     * surface — PostHog has no way to distinguish "namespace UUID" from
+     * "person UUID" and conflating the two creates fake users in
+     * analytics. Treat as opaque cache implementation detail.
+     *
+     * Stable for the lifetime of the client; new on every
+     * `createCapxulClient()` call. See Codex P1 finding on PR #406.
+     */
+    readonly id: string;
+    readonly auth: AuthClient;
+    readonly me: MeClient;
+    readonly accounts: AccountsClient;
+    readonly organizations: OrganizationsClient;
+    readonly payments: PaymentsClient;
+    readonly transfers: TransfersClient;
+    readonly withdrawals: WithdrawalsClient;
+    readonly documents: DocumentsClient;
+    readonly subAccounts: SubAccountsClient;
+    readonly virtualAccounts: VirtualAccountsClient;
+    readonly virtualCards: VirtualCardsClient;
+    readonly externalAccounts: ExternalAccountsClient;
+    readonly operations: OperationsClient;
+    readonly webhookEndpoints: WebhookEndpointsClient;
+    readonly webhookEvents: WebhookEventsClient;
+    readonly apiKeys: ApiKeysClient;
+    readonly flows: CapxulFlowFactories;
+};
+/**
+ * Construct a Capxul client. Every method stub in Slice C throws
+ * `NOT_IMPLEMENTED` per CANON.md §2 (types-first scaffold). Slice F.2
+ * wires the restart `payments` + `operations` runtime path through an
+ * injected authenticated Convex client; the broader `/v1/*` surface is
+ * still pending.
+ *
+ * Two-pass construction: the per-domain clients (`auth`, `me`, …) are
+ * built first, then `flows` is assigned with factories that close over
+ * the fully-built `client` so the spawned XState machines can call
+ * back into `client.auth.sendOtp`, `client.accounts.provisionPersonal`,
+ * etc. The intermediate `clientWithoutFlows` value is typed without
+ * `flows`; `Object.assign` mutates a single `flows` field on it before
+ * the returned `CapxulClient` cast — minimal and contained.
+ */
+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 };