@capxul/sdk 0.1.0-alpha.8 → 0.2.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,127 @@
 # @capxul/sdk
 
+## 0.2.0-alpha.3
+
+### Patch Changes
+
+- 5b99a9b: **Publishable-key path + error classification (#675).** Two tangled bugs landed in the consumer-path proof.
+
+  **Reference-cli was on the wrong path.** `build-browser-config.ts` had a `build-time-urls` fallback that fired silently whenever `CAPXUL_REF_PUBLISHABLE_KEY` was unset, so the CLI routed direct to Convex URLs and bypassed `/v1/client/bootstrap` entirely. It "worked" through a code path no external SDK consumer will ever run, masking publishable-key path breakage.
+
+  Reference-cli now:
+  - Requires `CAPXUL_REF_PUBLISHABLE_KEY`. The repo ships a long-lived shared sandbox key at `apps/reference-cli/.env.example` so `git clone && export $(...)` works; the key targets `elated-oyster-269`, is environment `test` (`cap_pk_test_*`), and is intentionally shareable.
+  - Strips the `build-time-urls` arm entirely. There is no silent fallback — missing env produces a structured `ENV_MISSING` envelope with an actionable message.
+  - Keeps `bootstrap probe --mock` working env-less (the mock factory bypasses `buildBrowserInputs()`).
+
+  **Error classification.** The SDK's auth-layer catch was swallowing typed bootstrap errors. A bad publishable key produced HTTP 401 + `NOT_AUTHENTICATED: "Publishable key is invalid or revoked."` from the bootstrap endpoint, but `postBetterAuth`'s `catch (cause)` wrapped any throw from `transport.fetch()` as `NETWORK_ERROR: "BetterAuth … network failure."`, burying the real diagnosis on `cause`. Reference-cli then flattened further to `AUTH_ERROR`.
+
+  The SDK now:
+  - Preserves `CapxulError` verbatim in `postBetterAuth` and `exchangeConvexToken` catches. Genuine non-`CapxulError` throws still fall back to `NETWORK_ERROR`.
+  - Widens `SendOtpCodes` + `VerifyOtpCodes` to include `NOT_AUTHENTICATED` and `PERMISSION_DENIED` so consumers can exhaustively narrow bootstrap-layer errors.
+
+  **Consumer impact:** SDK consumers that switch on `err.code` from `auth.sendOtp` / `auth.verifyOtp` should now expect `NOT_AUTHENTICATED` (bad/revoked publishable key) and `PERMISSION_DENIED` (origin not on the key's allow-list) as additional possible codes alongside the existing BetterAuth + rate-limit codes. No type-narrowing regressions — the unions only widened.
+
+## 0.2.0-alpha.2
+
+### Minor Changes
+
+- 995383f: Epic 660: Unified auth surface
+  - Introduces AuthService promise-based auth API replacing the imperative capxul.auth.\* tuple interface
+  - Adds SignerProvisioner for deterministic Safe v1.4.1 address derivation from viem signers
+  - Adds useAuth() React hook with reactive state + promise-based methods
+  - Deprecates useAuthFlow and useAuthBootstrapFlow in favor of useAuth()
+  - Migrates reference CLI auth commands (send-otp, verify-otp, signout) to useAuth()
+  - Migrates test surfaces: walkthroughs, type tests, e2e harness signup, lazy-dx provider
+  - Adds @repo/safe-derive workspace package for Safe address derivation utilities
+  - Aligns CapxulConfig.data to \_data with internal SDK transport ownership (Epic 652)
+  - Pins esbuild to 0.25.12 to fix binary-version skew in fresh worktrees
+
+- 2ef4ee3: Reshape the organizations members surface around a single Membership entity
+  with a status lifecycle (`pending | active | revoked | expired`).
+  - Replaces the prior invitation/membership split (which produced a phantom
+    `MemberInvitation` type that never compiled) with a single `Member` type
+    exposing `status`, `email`, `acceptedAt`, `expiresAt`, and `resentCount`.
+  - New methods on `organizations.members.*`: `accept(token)`, `revoke(memberId)`,
+    `resend(memberId)`. `invite()` now returns a `MemberInviteResponse`
+    containing the raw invite token (returned once).
+  - Auto-accepts pending invitations on first sign-in for the matching email
+    via a BetterAuth post-signup hook.
+  - Nightly Convex cron expires overdue pending invitations.
+
+  Public type changes:
+  - Removed: `MemberInvitation` (was never exported; type didn't compile).
+  - Added: `MembershipStatus`, `MemberInviteResponse`.
+  - Updated: `Member` shape — see SDK reference for the full delta.
+
+  React hooks:
+  - New: `useAcceptInvitation`, `useRevokeMember`, `useResendInvitation`.
+  - Updated: `useInviteMember` returns `MemberInviteResponse` (was returning a
+    type that didn't exist).
+
+  Reference CLI:
+  - New commands: `org members invite`, `org members list`, `org members retrieve`,
+    `org members accept`, `org members updateRole`, `org members revoke`,
+    `org members remove`, `org members resend`.
+
+- c7146bf: **Transport ownership (#656):** The SDK now owns construction of the
+  authenticated `ConvexHttpClient`. Consumers no longer wire `data` manually
+  or provide `auth.createDataClient`. After `verifyOtp` exchanges a Convex
+  JWT, the SDK builds the default data client internally via
+  `createDefaultDataClient` and stores it on `config._data`.
+  - `CapxulConfig.data` renamed to `_data` (internal test seam).
+  - `CapxulAuthConfig.createDataClient` removed from public types.
+  - `convex` moved from `peerDependencies` to `dependencies`.
+
+### Patch Changes
+
+- Updated dependencies [995383f]
+  - @repo/safe-derive@0.0.1-alpha.0
+
+## 0.2.0-alpha.1
+
+### Minor Changes
+
+- **Transport ownership (#656):** The SDK now owns construction of the
+  authenticated `ConvexHttpClient`. Consumers no longer wire `data` manually
+  or provide `auth.createDataClient`. After `verifyOtp` exchanges a Convex
+  JWT, the SDK builds the default data client internally via
+  `createDefaultDataClient` and stores it on `config._data`.
+  - `CapxulConfig.data` renamed to `_data` (internal test seam).
+  - `CapxulAuthConfig.createDataClient` removed from public types.
+  - `convex` moved from `peerDependencies` to `dependencies`.
+
+### Patch Changes
+
+- Bundle `@repo/safe-derive` into the published artifact so the new
+  `SignerProvisioner` class works for external consumers.
+
+## 0.1.0-alpha.12
+
+### Minor Changes
+
+- Publish the post-alpha.11 SDK and React SDK surface: funds v1 sub-account
+  runtime coverage, React hook wiring, payments list support, and the latest
+  generated Convex API snapshots used by current alpha consumers.
+
+  Note: alpha.10 and alpha.11 were intermediate runner artifacts from the
+  prior release pipeline (manual `package.json` bumps that were never folded
+  back into the repo). alpha.12 reconciles `package.json`, the changesets
+  state, and npm to a single consistent version.
+
+## 0.1.0-alpha.9
+
+### Minor Changes
+
+- Add the canonical auth bootstrap flow.
+
+  `verifyOtp()` now resolves a verified email session into either an
+  `existing_member` identity or a `bootstrap_required` continuation. New and
+  incomplete members continue through `completeBootstrap()`, which validates a
+  server-issued bootstrap token, claims the username, provisions the account/Safe
+  through the backend bootstrap path, and returns the authenticated product
+  identity. The React SDK adds `useAuthBootstrapFlow()` as the typed first-run
+  flow wrapper.
+
 ## 0.1.0-alpha.8
 
 ### Minor Changes

package/README.md

@@ -186,6 +186,51 @@ Helpers:
 - Branded type constructors — `toEmail`, `toAccountId`,
   `toOrganizationId`, … — never cast raw strings
 
+## Organizations
+
+Create an organization, manage its treasury, and invite members with
+role-based access:
+
+```ts
+// Create
+const [err, org] = await capxul.organizations.create({ name: "Acme" });
+
+// Invite a member — returns the raw token once
+const [err, { member, inviteToken }] = await capxul.organizations.members.invite({
+  organizationId: org.id,
+  email: "alice@example.com",
+  role: "finance_manager",
+});
+
+// List members — defaults to active; pass status to filter
+const [err, list] = await capxul.organizations.members.list({
+  organizationId: org.id,
+  status: "pending", // "pending" | "active" | "revoked" | "expired" | "all"
+});
+
+// Accept an invitation (called by the invitee)
+const [err, member] = await capxul.organizations.members.accept({ token: inviteToken });
+
+// Revoke a pending invitation
+const [err] = await capxul.organizations.members.revoke({
+  organizationId: org.id,
+  memberId: member.id,
+});
+
+// Remove an active member
+const [err] = await capxul.organizations.members.remove({
+  organizationId: org.id,
+  memberId: member.id,
+});
+```
+
+Member roles: `owner`, `finance_manager`, `payments_operator`,
+`org_admin`, `viewer`, `accountant`. Only `owner` and `org_admin` can
+invite, revoke, remove, or change roles.
+
+Pending invitations auto-accept on first sign-in when the user's email
+matches. Overdue pending invitations expire via a nightly cron.
+
 ## Error model
 
 Every method returns a `CapxulResult<T, Codes>` tuple. Errors are

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

@@ -1,8 +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.cjs';
-import { d as CapxulResult, C as CapxulError } from './errors-GgKrSUKp.cjs';
-import { A as Account, U as UserIdentifier, a as AccountLookupResult, S as Safe, i as KycProfile, E as ExternalAccount, L as List, v as SubAccount, B as BalanceLedgerEntry, b as ApiKey, a0 as CreateApiKeyRequest, a1 as CreateDocumentRequest, D as Document, O as Operation, l as OperationStatus, k as Money, C as CreatePaymentResult, o as Payment, F as TransferEndpoint, f as CreateTransferResult, y as Transfer, g as CreateWithdrawalResult, _ as Withdrawal, a2 as CreateWebhookEndpointRequest, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, a3 as CreateVirtualAccountRequest, V as VirtualAccount, a4 as CreateVirtualCardRequest, Q as VirtualCard } from './types-hfcOE7Oi.cjs';
+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, V as VirtualAccountId, i as VirtualCardId } from './next-action-CTGl8wpy.cjs';
+import { d as CapxulResult, C as CapxulError$1 } from './errors-rqxuUhQP.cjs';
+import { A as Account, X as UserIdentifier, a as AccountLookupResult, S as Safe, k as KycProfile, E as ExternalAccount, L as List, F as SubAccount, B as BalanceLedgerEntry, b as ApiKey, a5 as CreateApiKeyRequest, a6 as CreateDocumentRequest, D as Document, O as Operation, q as OperationStatus, p as Money, C as CreatePaymentResult, t as Payment, Q as TransferEndpoint, f as CreateTransferResult, J as Transfer, g as CreateWithdrawalResult, a3 as Withdrawal, a7 as CreateWebhookEndpointRequest, a1 as WebhookEndpoint, a2 as WebhookEvent, s as Organization, W as Treasury, o as MembershipStatus, M as Member, n as MemberInviteResponse, a8 as CreateVirtualAccountRequest, Y as VirtualAccount, a9 as CreateVirtualCardRequest, _ as VirtualCard } from './types-Brucpq0Z.cjs';
 
 /**
  * Accounts domain — individual user accounts per sdk-surface.md §1a.
@@ -21,7 +22,6 @@ type AccountUpdateInput = Partial<{
 type LocalPrivateKeySignerProvider = {
     readonly kind: "local-private-key";
     readonly signerAddress: string;
-    readonly safeAddress: string;
 };
 type AccountProvisionPersonalInput = {
     readonly displayName?: string;
@@ -39,6 +39,7 @@ type AccountListInput = {
 type AccountCreateSubAccountInput = {
     readonly accountId: AccountId;
     readonly name: string;
+    readonly purpose?: string;
 };
 type AccountCreateExternalAccountInput = {
     readonly accountId: AccountId;
@@ -58,6 +59,7 @@ type UpdateCodes$1 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "
 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>>;
 };
@@ -74,12 +76,12 @@ type AccountExternalAccountsClient = {
     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$b>>;
-    readonly retrieve: (subAccountId: SubAccountId) => Promise<CapxulResult<SubAccount, RetrieveCodes$e>>;
-    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: {
@@ -189,6 +191,37 @@ 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 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;
@@ -210,14 +243,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" | "NOT_AUTHENTICATED" | "PERMISSION_DENIED";
+type VerifyOtpCodes = "INVALID_INPUT" | "NOT_AUTHENTICATED" | "RATE_LIMITED" | "OPERATION_TIMEOUT" | "NETWORK_ERROR" | "PROVIDER_ERROR" | "INTERNAL_ERROR" | "ENV_MISSING" | "UNKNOWN" | "PERMISSION_DENIED";
+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>>;
@@ -656,7 +691,7 @@ type WebhookEventsClient = {
 
 type OrganizationsCreateInput = {
     readonly name: string;
-    readonly country: string;
+    readonly country?: string;
 };
 type OrganizationsListInput = {
     readonly limit?: number;
@@ -675,6 +710,9 @@ type OrgMemberInviteInput = {
     readonly email: string;
     readonly role: Member["role"];
 };
+type OrgMemberAcceptInput = {
+    readonly token: string;
+};
 type OrgMemberUpdateRoleInput = {
     readonly organizationId: OrganizationId;
     readonly memberId: MemberId;
@@ -685,21 +723,23 @@ type OrgMemberRemoveInput = {
     readonly memberId: MemberId;
 };
 type OrgMemberRetrieveInput = OrgMemberRemoveInput;
+type OrgMemberRevokeInput = OrgMemberRemoveInput;
+type OrgMemberResendInput = OrgMemberRemoveInput;
 type OrgListInput = {
     readonly organizationId: OrganizationId;
     readonly limit?: number;
     readonly cursor?: string;
 };
-type OrgKybProfileStartInput = {
-    readonly organizationId: OrganizationId;
-};
-type OrgKybProfileRetrieveInput = {
+type OrgMemberListInput = {
     readonly organizationId: OrganizationId;
-    readonly kybProfileId: KybProfileId;
+    readonly status?: MembershipStatus | "all";
+    readonly limit?: number;
+    readonly cursor?: string;
 };
 type OrgCreateSubAccountInput = {
     readonly organizationId: OrganizationId;
     readonly name: string;
+    readonly purpose?: string;
 };
 type OrgCreateExternalAccountInput = {
     readonly organizationId: OrganizationId;
@@ -731,6 +771,7 @@ 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$4;
+type SubAccountRemoveCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "INVALID_INPUT";
 type OrgSafesClient = {
     readonly retrieve: (input: OrgSafeRetrieveInput) => Promise<CapxulResult<Safe, SafeRetrieveCodes>>;
 };
@@ -738,27 +779,26 @@ type OrgTreasuryClient = {
     readonly retrieve: (organizationId: OrganizationId) => Promise<CapxulResult<Treasury, TreasuryRetrieveCodes>>;
 };
 type OrgMembersClient = {
-    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<Member>, ListCodes$3>>;
+    readonly list: (input: OrgMemberListInput) => Promise<CapxulResult<List<Member>, ListCodes$3>>;
     readonly retrieve: (input: OrgMemberRetrieveInput) => Promise<CapxulResult<Member, RetrieveCodes$4>>;
-    readonly invite: (input: OrgMemberInviteInput) => Promise<CapxulResult<Member, UpdateCodes>>;
+    readonly invite: (input: OrgMemberInviteInput) => Promise<CapxulResult<MemberInviteResponse, UpdateCodes>>;
+    readonly accept: (input: OrgMemberAcceptInput) => Promise<CapxulResult<Member, UpdateCodes>>;
     readonly updateRole: (input: OrgMemberUpdateRoleInput) => Promise<CapxulResult<Member, UpdateCodes>>;
+    readonly revoke: (input: OrgMemberRevokeInput) => 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$4>>;
+    readonly resend: (input: OrgMemberResendInput) => Promise<CapxulResult<MemberInviteResponse, UpdateCodes>>;
 };
 type OrgSubAccountsClient = {
-    readonly create: (input: OrgCreateSubAccountInput) => Promise<CapxulResult<SubAccount, UpdateCodes>>;
-    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<SubAccount>, ListCodes$3>>;
+    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$4>>;
+    }) => 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>>;
@@ -789,7 +829,6 @@ type OrganizationsClient = {
     readonly treasury: OrgTreasuryClient;
     readonly members: OrgMembersClient;
     readonly apiKeys: OrgApiKeysClient;
-    readonly kybProfile: OrgKybProfileClient;
     readonly subAccounts: OrgSubAccountsClient;
     readonly externalAccounts: OrgExternalAccountsClient;
     readonly balanceLedger: OrgBalanceLedgerClient;
@@ -883,7 +922,7 @@ type TransportState = {
     readonly runtime: TransportRuntime;
 } | {
     readonly status: "error";
-    readonly error: CapxulError;
+    readonly error: CapxulError$1;
 };
 type TransportRuntime = {
     readonly authBaseUrl: string;
@@ -942,13 +981,20 @@ 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$3 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type RemoveCodes$1 = RetrieveCodes$3;
+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$3>>;
-    readonly remove: (subAccountId: SubAccountId) => Promise<CapxulResult<void, RemoveCodes$1>>;
+    readonly remove: (subAccountId: SubAccountId) => Promise<CapxulResult<SubAccount, RemoveCodes$1>>;
 };
 
 /**
@@ -1103,6 +1149,152 @@ 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 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: "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: "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;
+    }, 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;
+    }, 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.
  *
@@ -1150,11 +1342,6 @@ type CapxulAuthConfig = {
     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`. */
@@ -1170,12 +1357,13 @@ type CapxulConfig = {
      */
     readonly signer?: Account$1;
     /**
-     * Inject an authenticated Convex data client.
+     * @internal
      *
-     * Slice F.2 uses this for the restart payment + operation runtime
-     * path while the `/v1/*` service-token bridge remains unfinished.
+     * Test-only override seam for injecting an authenticated Convex data client.
+     * The SDK now owns runtime construction of the data client; this field is
+     * reserved for tests and the React provider's singleton lifecycle.
      */
-    readonly data?: CapxulDataClient;
+    readonly _data?: CapxulDataClient;
     /**
      * Chain + bundler configuration for on-chain submission.
      *
@@ -1230,6 +1418,7 @@ type CapxulConfig = {
  */
 type CapxulFlowFactories = {
     readonly auth: () => AnyStateMachine;
+    readonly authBootstrap: () => ReturnType<typeof createAuthBootstrapFlowMachine>;
     readonly onboarding: () => AnyStateMachine;
     readonly provisioning: () => AnyStateMachine;
 };
@@ -1292,4 +1481,4 @@ type CapxulClient = {
  */
 declare function createCapxulClient(config?: CapxulConfig): CapxulClient;
 
-export { type AccountProvisionPersonalInput as A, type BrowserCapxulConfig as B, type CapxulClient as C, type DocumentsClient as D, type ExternalAccountsClient as E, type VirtualCardsClient as F, type WebhookEndpointsClient as G, type HttpTransport as H, type WebhookEventsClient as I, type WithdrawalsClient as J, createCapxulClient as K, type LocalPrivateKeySignerProvider as L, type MeClient as M, makeHttpTransport as N, type OperationsClient as O, type PaymentsClient as P, toTokenTransferId as Q, type Session as S, type TokenTransfer as T, type VirtualAccountsClient as V, type WebhookEndpointCreateResult as W, type AccountsClient as a, type ApiKeyCreateResult as b, type ApiKeysClient as c, type AuthClient as d, type AuthSessionStore as e, type CapxulAuthConfig as f, type CapxulConfig as g, type CapxulDataClient as h, type CapxulFlowFactories as i, type CapxulSigningConfig as j, type OrgDocumentsClient as k, type OrgPaymentsClient as l, type OrgSafesClient as m, type OrgTransfersClient as n, type OrgTreasuryClient as o, type OrgWithdrawalsClient as p, type OrganizationsClient as q, type SubAccountsClient as r, type TokenTransferId as s, type TokenTransfersClient as t, type TokenTransfersListInput as u, type TokenTransfersListPage as v, type TokenTransfersRetrieveInput as w, type TransfersClient as x, type TransportRuntime as y, type TransportState as z };
+export { type WithdrawalsClient as $, type AccountProvisionPersonalInput as A, type BrowserCapxulConfig as B, CapxulError as C, type DocumentsClient as D, type ExternalAccountsClient as E, type SubAccountsClient as F, type TokenTransferId as G, type HttpTransport as H, type TokenTransfersClient as I, type TokenTransfersListInput as J, type TokenTransfersListPage as K, type LocalPrivateKeySignerProvider as L, type MeClient as M, type TokenTransfersRetrieveInput as N, type OperationsClient as O, type PaymentsClient as P, type TransfersClient as Q, type TransportRuntime as R, type Session as S, type TokenTransfer as T, type TransportState as U, type VerifyOtpResult as V, type VirtualAccountsClient as W, type VirtualCardsClient as X, type WebhookEndpointCreateResult as Y, type WebhookEndpointsClient as Z, type WebhookEventsClient as _, type CapxulClient as a, createAuthBootstrapFlowMachine as a0, createCapxulClient as a1, makeHttpTransport as a2, toTokenTransferId as a3, type CapxulConfig as b, type CompleteBootstrapInput as c, type CompleteBootstrapResult as d, type AccountsClient as e, type ApiKeyCreateResult as f, type ApiKeysClient as g, type AuthBootstrapFlowContext as h, type AuthBootstrapFlowError as i, type AuthBootstrapFlowEvent as j, type AuthBootstrapReason as k, type AuthBootstrapToken as l, type AuthClient as m, type AuthSessionStore as n, type CapxulAuthConfig as o, type CapxulDataClient as p, type CapxulFlowFactories as q, type CapxulSigningConfig as r, type OrgDocumentsClient as s, type OrgMembersClient as t, type OrgPaymentsClient as u, type OrgSafesClient as v, type OrgTransfersClient as w, type OrgTreasuryClient as x, type OrgWithdrawalsClient as y, type OrganizationsClient as z };