@capxul/sdk-react 0.1.0-alpha.6 → 0.1.0-alpha.9

package/CHANGELOG.md

@@ -1,6 +1,25 @@
 # @capxul/sdk-react
 
-## 0.1.0-alpha.6
+## 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.
+
+### Patch Changes
+
+- Updated dependencies
+  - @capxul/sdk@0.1.0-alpha.9
+
+## 0.1.0-alpha.8
 
 ### Minor Changes
 
@@ -32,21 +51,7 @@
 ### Patch Changes
 
 - Updated dependencies [57203a4]
-  - @capxul/sdk@0.1.0-alpha.6
-
-## 0.1.0-alpha.5
-
-### Patch Changes
-
-- Widen the React peer dependency to `>=18.2.0 <20` so React 18-era Ink 5
-  CLI apps can install `@capxul/sdk-react` without forcing React 19 into
-  Ink's React reconciler. The provider and hooks only use React 18-compatible
-  APIs (`createContext`, `useContext`, `useMemo`, `useEffect`, `useState`, and
-  `useSyncExternalStore`), preserving React 19 compatibility while unblocking
-  React 18 hosts.
-
-- Updated dependencies
-  - @capxul/sdk@0.1.0-alpha.5
+  - @capxul/sdk@0.1.0-alpha.8
 
 ## 0.1.0-alpha.4
 

package/README.md

@@ -40,7 +40,12 @@ import { CapxulProvider } from "@capxul/sdk-react";
 
 export default function RootLayout({ children }) {
   return (
-    <CapxulProvider publishableKey={process.env.NEXT_PUBLIC_CAPXUL_KEY!}>
+    <CapxulProvider
+      config={{
+        mode: "publishable-key",
+        publishableKey: process.env.NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY!,
+      }}
+    >
       {children}
     </CapxulProvider>
   );
@@ -119,6 +124,21 @@ subscription against the transport singleton — only the components
 that actually call it re-render when state changes. The provider
 itself never re-renders.
 
+## Publishable-key proof status
+
+The publishable-key path is runtime-proven where the repo can run it
+without secrets:
+
+| Surface | Runtime proof | Expected safe signal |
+|---|---|---|
+| Provider + `useMe()` | `corepack pnpm --filter @capxul/sdk-react check-types` plus the headless proof tests under `packages/sdk-react/ops/proof` | provider reaches `useCapxulStatus().status === "ready"` after one bootstrap request |
+| Reference CLI mock | `corepack pnpm --filter @capxul/reference-cli build && node apps/reference-cli/dist/cli.js bootstrap probe --mock --json` | `ok:true`, `mode:"publishable-key"`, `bootstrapRequests:1`, `authRequests:1`, `keyLengthClass:"provided"` |
+| Reference CLI live | same command without `--mock`, with `CAPXUL_REF_PUBLISHABLE_KEY` and optional `CAPXUL_REF_BOOTSTRAP_URL` set locally | success only when the key/origin/runtime are valid; otherwise sanitized SDK error JSON |
+
+Do not paste or commit publishable keys, session tokens, Convex JWTs,
+cookies, or provider payloads. Proof output reports only
+`keyLengthClass`.
+
 ## Hooks catalogue
 
 | Surface | Hook |

package/dist/index.cjs

@@ -110,7 +110,12 @@ var Errors = {
     "Idempotency key was already used for a different request",
     { details }
   ),
-  emailDeliveryFailed: (detail) => new CapxulError("EMAIL_DELIVERY_FAILED", `Failed to send email: ${detail}`),
+  emailDeliveryFailed: (detail, details) => new CapxulError("EMAIL_DELIVERY_FAILED", `Failed to send email: ${detail}`, {
+    details
+  }),
+  rateLimited: (details) => new CapxulError("RATE_LIMITED", "Request was rate limited", {
+    details: { ...details }
+  }),
   internalError: (reason) => new CapxulError("INTERNAL_ERROR", `Internal error: ${reason}`),
   /**
    * Verification gate. Surfaced when a request hits a verification
@@ -217,6 +222,48 @@ function createReactDataClient(convexUrl, sessionStore) {
     }
   };
 }
+function createLazyReactDataClient(transport, sessionStore, createClient = createReactDataClient) {
+  let client = null;
+  let initializeClient = null;
+  let closed = false;
+  function closedError() {
+    return new Error("Capxul React data client is closed");
+  }
+  async function getClient() {
+    if (closed) throw closedError();
+    if (client) return client;
+    initializeClient ??= (async () => {
+      const runtime = await transport.ensureRuntime();
+      if (closed) throw closedError();
+      const nextClient = createClient(runtime.convexUrl, sessionStore);
+      if (closed) {
+        nextClient.close();
+        throw closedError();
+      }
+      client = nextClient;
+      return nextClient;
+    })().catch((error) => {
+      if (!closed) {
+        initializeClient = null;
+      }
+      throw error;
+    });
+    return initializeClient;
+  }
+  return {
+    query: async (name, args) => (await getClient()).query(name, args),
+    mutation: async (name, args) => (await getClient()).mutation(name, args),
+    action: async (name, args) => (await getClient()).action?.(name, args),
+    refreshAuth: () => {
+      client?.refreshAuth();
+    },
+    close: () => {
+      closed = true;
+      client?.close();
+      client = null;
+    }
+  };
+}
 function CapxulProvider({
   config,
   sessionStore,
@@ -246,12 +293,12 @@ function CapxulProvider({
 function buildWiring(config, sessionStore) {
   const validated = createCapxulConfig(config);
   const transport = sdk.makeHttpTransport(validated);
-  const dataClient = validated.mode === "build-time-urls" ? createReactDataClient(validated.convexUrl, sessionStore) : null;
+  const dataClient = validated.mode === "build-time-urls" ? createReactDataClient(validated.convexUrl, sessionStore) : createLazyReactDataClient(transport, sessionStore);
   const sdkConfig = {
     _transport: transport,
     publishableKey: validated.mode === "publishable-key" ? validated.publishableKey : void 0,
     data: dataClient ?? void 0,
-    auth: dataClient ? {
+    auth: validated.mode === "build-time-urls" || validated.mode === "publishable-key" ? {
       // The auth client builds the BetterAuth root URL from this
       // value. Convex's `.cloud` URL is the wrong host (BetterAuth
       // is mounted on the `.site` URL), but the build-time-urls
@@ -554,6 +601,12 @@ function useAuthFlow() {
   const [snapshot, send] = react$1.useActor(machine);
   return { snapshot, send };
 }
+function useAuthBootstrapFlow() {
+  const client = useCapxul();
+  const machine = react.useMemo(() => client.flows.authBootstrap(), [client]);
+  const [snapshot, send] = react$1.useActor(machine);
+  return { snapshot, send };
+}
 function useOnboardingFlow() {
   const client = useCapxul();
   const machine = react.useMemo(() => client.flows.onboarding(), [client]);
@@ -671,6 +724,7 @@ exports.localPrivateKeyConnector = localPrivateKeyConnector;
 exports.useAccount = useAccount;
 exports.useApiKey = useApiKey;
 exports.useApiKeys = useApiKeys;
+exports.useAuthBootstrapFlow = useAuthBootstrapFlow;
 exports.useAuthFlow = useAuthFlow;
 exports.useBalanceLedger = useBalanceLedger;
 exports.useBalanceLedgerEntry = useBalanceLedgerEntry;

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { ReactNode } from 'react';
+import * as _capxul_sdk from '@capxul/sdk';
 import { HttpTransport, TransportState, BrowserCapxulConfig, AuthSessionStore, AccountId, OrganizationId, ApiKeyId, BalanceLedgerEntryId, ExternalAccountId, MemberId, Account, ApiKey, BalanceLedgerEntry, DocumentId, Document, ExternalAccount, KybProfile, KycProfile, CapxulError as CapxulError$1, Member, OperationId, Operation, Organization, PaymentId, Payment, SafeId, Safe, SubAccountId, SubAccount, TokenTransfer, TransferId, Transfer, Treasury, VirtualAccountId, VirtualAccount, VirtualCardId, VirtualCard, WebhookEndpointId, WebhookEndpoint, WebhookEventId, WebhookEvent, WithdrawalId, Withdrawal, List, TokenTransfersListInput, TokenTransfersListPage, LocalPrivateKeySignerProvider } from '@capxul/sdk';
-export { AuthFlowContext, AuthFlowEvent, BrowserCapxulConfig, OnboardingFlowContext, OnboardingFlowEvent, ProvisioningFlowContext, ProvisioningFlowEvent } from '@capxul/sdk';
+export { AuthBootstrapFlowContext, AuthBootstrapFlowEvent, AuthFlowContext, AuthFlowEvent, BrowserCapxulConfig, OnboardingFlowContext, OnboardingFlowEvent, ProvisioningFlowContext, ProvisioningFlowEvent } from '@capxul/sdk';
 import { QueryClient, UseQueryResult } from '@tanstack/react-query';
 import { CapxulClient } from '@capxul/sdk/client';
 import { CapxulError } from '@capxul/sdk/errors';
@@ -444,10 +445,106 @@ declare function useApiKeys(_organizationId: OrganizationId): QueryResult<List<A
  */
 declare function useWebhookEndpoints(): QueryResult<List<WebhookEndpoint>>;
 
+/**
+ * Lowercased, shape-validated email address. Brand prevents swapping
+ * with `phoneNumber`, `username`, or other string identifiers (per
+ * `CANON.md` §4.54 and `sdk-surface.md` §5h).
+ */
+type Email = string & {
+    readonly __capxulEmailBrand: "Email";
+};
+/**
+ * Public Capxul username. 3–30 chars, letter-first, lowercased,
+ * remaining chars from `[a-z0-9_-]` (per `CANON.md` §4.54 and
+ * `sdk-surface.md` §5h). Constructor lowercases before validating so
+ * mixed-case input canonicalizes cleanly when the first char is a
+ * letter; purely invalid shapes (too short, illegal chars, digit-first)
+ * still throw.
+ */
+type Username = string & {
+    readonly __capxulUsernameBrand: "Username";
+};
+
 declare function useAuthFlow(): {
     readonly snapshot: xstate.MachineSnapshot<any, any, any, any, any, any, any, any>;
     readonly send: (event: any) => void;
 };
+declare function useAuthBootstrapFlow(): {
+    readonly snapshot: xstate.MachineSnapshot<_capxul_sdk.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: _capxul_sdk.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<_capxul_sdk.CompleteBootstrapResult, {
+            bootstrapToken: _capxul_sdk.AuthBootstrapToken;
+            username: Username;
+            signerProvider: _capxul_sdk.LocalPrivateKeySignerProvider;
+        }, xstate.EventObject>> | xstate.ActorRefFromLogic<xstate.PromiseActorLogic<void, {
+            email: Email;
+        }, xstate.EventObject>> | xstate.ActorRefFromLogic<xstate.PromiseActorLogic<_capxul_sdk.VerifyOtpResult, {
+            email: Email;
+            code: string;
+        }, xstate.EventObject>> | undefined;
+    }, "email" | "error" | "bootstrap_required" | "authenticated" | "sending_otp" | "otp_requested" | "signing_out" | "verifying_otp" | "completing_bootstrap", string, xstate.NonReducibleUnknown, 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: {};
+        };
+    }>;
+    readonly send: (event: {
+        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: _capxul_sdk.LocalPrivateKeySignerProvider;
+    } | {
+        readonly type: "COMPLETE_BOOTSTRAP";
+    } | {
+        readonly type: "BACK";
+    } | {
+        readonly type: "RESET";
+    } | {
+        readonly type: "SIGN_OUT";
+    }) => void;
+};
 declare function useOnboardingFlow(): {
     readonly snapshot: xstate.MachineSnapshot<any, any, any, any, any, any, any, any>;
     readonly send: (event: any) => void;
@@ -538,4 +635,4 @@ declare function injectedConnector(options?: InjectedConnectorOptions): CapxulCo
  */
 declare function localPrivateKeyConnector(options: LocalPrivateKeyConnectorOptions): CapxulConnector;
 
-export { CapxulClientProvider, type CapxulClientProviderProps, type CapxulConnector, type CapxulConnectorKind, type CapxulConnectorSession, CapxulProvider, type CapxulProviderProps, CapxulTransportProvider, type CapxulTransportProviderProps, type DocumentsFilters, type InjectedConnectorOptions, type LocalPrivateKeyConnectorOptions, type OrgDocumentsFilters, type OrgScopedFilters, type OwnerRef, type OwnerScopedFilters, type PaginationFilters, type PaymentsFilters, type QueryResult, type TransfersFilters, type UseApiKeyArgs, type UseBalanceLedgerEntryArgs, type UseExternalAccountArgs, type UseMemberArgs, type UseTokenTransferArgs, type VirtualAccountsFilters, type VirtualCardsFilters, type WithdrawalsFilters, createCapxulConfig, injectedConnector, localPrivateKeyConnector, useAccount, useApiKey, useApiKeys, useAuthFlow, useBalanceLedger, useBalanceLedgerEntry, useCapxul, useCapxulStatus, useDocument, useDocuments, useExternalAccount, useExternalAccounts, useKybProfile, useKycProfile, useMe, useMember, useMembers, useOnboardingFlow, useOperation, useOrgDocuments, useOrgPayments, useOrgTransfers, useOrgWithdrawals, useOrganization, useOrganizations, usePayment, usePayments, useProvisioningFlow, useSafe, useSubAccount, useSubAccounts, useTokenTransfer, useTokenTransfers, useTransfer, useTransfers, useTreasury, useVirtualAccount, useVirtualAccounts, useVirtualCard, useVirtualCards, useWebhookEndpoint, useWebhookEndpoints, useWebhookEvent, useWithdrawal, useWithdrawals };
+export { CapxulClientProvider, type CapxulClientProviderProps, type CapxulConnector, type CapxulConnectorKind, type CapxulConnectorSession, CapxulProvider, type CapxulProviderProps, CapxulTransportProvider, type CapxulTransportProviderProps, type DocumentsFilters, type InjectedConnectorOptions, type LocalPrivateKeyConnectorOptions, type OrgDocumentsFilters, type OrgScopedFilters, type OwnerRef, type OwnerScopedFilters, type PaginationFilters, type PaymentsFilters, type QueryResult, type TransfersFilters, type UseApiKeyArgs, type UseBalanceLedgerEntryArgs, type UseExternalAccountArgs, type UseMemberArgs, type UseTokenTransferArgs, type VirtualAccountsFilters, type VirtualCardsFilters, type WithdrawalsFilters, createCapxulConfig, injectedConnector, localPrivateKeyConnector, useAccount, useApiKey, useApiKeys, useAuthBootstrapFlow, useAuthFlow, useBalanceLedger, useBalanceLedgerEntry, useCapxul, useCapxulStatus, useDocument, useDocuments, useExternalAccount, useExternalAccounts, useKybProfile, useKycProfile, useMe, useMember, useMembers, useOnboardingFlow, useOperation, useOrgDocuments, useOrgPayments, useOrgTransfers, useOrgWithdrawals, useOrganization, useOrganizations, usePayment, usePayments, useProvisioningFlow, useSafe, useSubAccount, useSubAccounts, useTokenTransfer, useTokenTransfers, useTransfer, useTransfers, useTreasury, useVirtualAccount, useVirtualAccounts, useVirtualCard, useVirtualCards, useWebhookEndpoint, useWebhookEndpoints, useWebhookEvent, useWithdrawal, useWithdrawals };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { ReactNode } from 'react';
+import * as _capxul_sdk from '@capxul/sdk';
 import { HttpTransport, TransportState, BrowserCapxulConfig, AuthSessionStore, AccountId, OrganizationId, ApiKeyId, BalanceLedgerEntryId, ExternalAccountId, MemberId, Account, ApiKey, BalanceLedgerEntry, DocumentId, Document, ExternalAccount, KybProfile, KycProfile, CapxulError as CapxulError$1, Member, OperationId, Operation, Organization, PaymentId, Payment, SafeId, Safe, SubAccountId, SubAccount, TokenTransfer, TransferId, Transfer, Treasury, VirtualAccountId, VirtualAccount, VirtualCardId, VirtualCard, WebhookEndpointId, WebhookEndpoint, WebhookEventId, WebhookEvent, WithdrawalId, Withdrawal, List, TokenTransfersListInput, TokenTransfersListPage, LocalPrivateKeySignerProvider } from '@capxul/sdk';
-export { AuthFlowContext, AuthFlowEvent, BrowserCapxulConfig, OnboardingFlowContext, OnboardingFlowEvent, ProvisioningFlowContext, ProvisioningFlowEvent } from '@capxul/sdk';
+export { AuthBootstrapFlowContext, AuthBootstrapFlowEvent, AuthFlowContext, AuthFlowEvent, BrowserCapxulConfig, OnboardingFlowContext, OnboardingFlowEvent, ProvisioningFlowContext, ProvisioningFlowEvent } from '@capxul/sdk';
 import { QueryClient, UseQueryResult } from '@tanstack/react-query';
 import { CapxulClient } from '@capxul/sdk/client';
 import { CapxulError } from '@capxul/sdk/errors';
@@ -444,10 +445,106 @@ declare function useApiKeys(_organizationId: OrganizationId): QueryResult<List<A
  */
 declare function useWebhookEndpoints(): QueryResult<List<WebhookEndpoint>>;
 
+/**
+ * Lowercased, shape-validated email address. Brand prevents swapping
+ * with `phoneNumber`, `username`, or other string identifiers (per
+ * `CANON.md` §4.54 and `sdk-surface.md` §5h).
+ */
+type Email = string & {
+    readonly __capxulEmailBrand: "Email";
+};
+/**
+ * Public Capxul username. 3–30 chars, letter-first, lowercased,
+ * remaining chars from `[a-z0-9_-]` (per `CANON.md` §4.54 and
+ * `sdk-surface.md` §5h). Constructor lowercases before validating so
+ * mixed-case input canonicalizes cleanly when the first char is a
+ * letter; purely invalid shapes (too short, illegal chars, digit-first)
+ * still throw.
+ */
+type Username = string & {
+    readonly __capxulUsernameBrand: "Username";
+};
+
 declare function useAuthFlow(): {
     readonly snapshot: xstate.MachineSnapshot<any, any, any, any, any, any, any, any>;
     readonly send: (event: any) => void;
 };
+declare function useAuthBootstrapFlow(): {
+    readonly snapshot: xstate.MachineSnapshot<_capxul_sdk.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: _capxul_sdk.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<_capxul_sdk.CompleteBootstrapResult, {
+            bootstrapToken: _capxul_sdk.AuthBootstrapToken;
+            username: Username;
+            signerProvider: _capxul_sdk.LocalPrivateKeySignerProvider;
+        }, xstate.EventObject>> | xstate.ActorRefFromLogic<xstate.PromiseActorLogic<void, {
+            email: Email;
+        }, xstate.EventObject>> | xstate.ActorRefFromLogic<xstate.PromiseActorLogic<_capxul_sdk.VerifyOtpResult, {
+            email: Email;
+            code: string;
+        }, xstate.EventObject>> | undefined;
+    }, "email" | "error" | "bootstrap_required" | "authenticated" | "sending_otp" | "otp_requested" | "signing_out" | "verifying_otp" | "completing_bootstrap", string, xstate.NonReducibleUnknown, 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: {};
+        };
+    }>;
+    readonly send: (event: {
+        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: _capxul_sdk.LocalPrivateKeySignerProvider;
+    } | {
+        readonly type: "COMPLETE_BOOTSTRAP";
+    } | {
+        readonly type: "BACK";
+    } | {
+        readonly type: "RESET";
+    } | {
+        readonly type: "SIGN_OUT";
+    }) => void;
+};
 declare function useOnboardingFlow(): {
     readonly snapshot: xstate.MachineSnapshot<any, any, any, any, any, any, any, any>;
     readonly send: (event: any) => void;
@@ -538,4 +635,4 @@ declare function injectedConnector(options?: InjectedConnectorOptions): CapxulCo
  */
 declare function localPrivateKeyConnector(options: LocalPrivateKeyConnectorOptions): CapxulConnector;
 
-export { CapxulClientProvider, type CapxulClientProviderProps, type CapxulConnector, type CapxulConnectorKind, type CapxulConnectorSession, CapxulProvider, type CapxulProviderProps, CapxulTransportProvider, type CapxulTransportProviderProps, type DocumentsFilters, type InjectedConnectorOptions, type LocalPrivateKeyConnectorOptions, type OrgDocumentsFilters, type OrgScopedFilters, type OwnerRef, type OwnerScopedFilters, type PaginationFilters, type PaymentsFilters, type QueryResult, type TransfersFilters, type UseApiKeyArgs, type UseBalanceLedgerEntryArgs, type UseExternalAccountArgs, type UseMemberArgs, type UseTokenTransferArgs, type VirtualAccountsFilters, type VirtualCardsFilters, type WithdrawalsFilters, createCapxulConfig, injectedConnector, localPrivateKeyConnector, useAccount, useApiKey, useApiKeys, useAuthFlow, useBalanceLedger, useBalanceLedgerEntry, useCapxul, useCapxulStatus, useDocument, useDocuments, useExternalAccount, useExternalAccounts, useKybProfile, useKycProfile, useMe, useMember, useMembers, useOnboardingFlow, useOperation, useOrgDocuments, useOrgPayments, useOrgTransfers, useOrgWithdrawals, useOrganization, useOrganizations, usePayment, usePayments, useProvisioningFlow, useSafe, useSubAccount, useSubAccounts, useTokenTransfer, useTokenTransfers, useTransfer, useTransfers, useTreasury, useVirtualAccount, useVirtualAccounts, useVirtualCard, useVirtualCards, useWebhookEndpoint, useWebhookEndpoints, useWebhookEvent, useWithdrawal, useWithdrawals };
+export { CapxulClientProvider, type CapxulClientProviderProps, type CapxulConnector, type CapxulConnectorKind, type CapxulConnectorSession, CapxulProvider, type CapxulProviderProps, CapxulTransportProvider, type CapxulTransportProviderProps, type DocumentsFilters, type InjectedConnectorOptions, type LocalPrivateKeyConnectorOptions, type OrgDocumentsFilters, type OrgScopedFilters, type OwnerRef, type OwnerScopedFilters, type PaginationFilters, type PaymentsFilters, type QueryResult, type TransfersFilters, type UseApiKeyArgs, type UseBalanceLedgerEntryArgs, type UseExternalAccountArgs, type UseMemberArgs, type UseTokenTransferArgs, type VirtualAccountsFilters, type VirtualCardsFilters, type WithdrawalsFilters, createCapxulConfig, injectedConnector, localPrivateKeyConnector, useAccount, useApiKey, useApiKeys, useAuthBootstrapFlow, useAuthFlow, useBalanceLedger, useBalanceLedgerEntry, useCapxul, useCapxulStatus, useDocument, useDocuments, useExternalAccount, useExternalAccounts, useKybProfile, useKycProfile, useMe, useMember, useMembers, useOnboardingFlow, useOperation, useOrgDocuments, useOrgPayments, useOrgTransfers, useOrgWithdrawals, useOrganization, useOrganizations, usePayment, usePayments, useProvisioningFlow, useSafe, useSubAccount, useSubAccounts, useTokenTransfer, useTokenTransfers, useTransfer, useTransfers, useTreasury, useVirtualAccount, useVirtualAccounts, useVirtualCard, useVirtualCards, useWebhookEndpoint, useWebhookEndpoints, useWebhookEvent, useWithdrawal, useWithdrawals };

package/dist/index.js

@@ -108,7 +108,12 @@ var Errors = {
     "Idempotency key was already used for a different request",
     { details }
   ),
-  emailDeliveryFailed: (detail) => new CapxulError("EMAIL_DELIVERY_FAILED", `Failed to send email: ${detail}`),
+  emailDeliveryFailed: (detail, details) => new CapxulError("EMAIL_DELIVERY_FAILED", `Failed to send email: ${detail}`, {
+    details
+  }),
+  rateLimited: (details) => new CapxulError("RATE_LIMITED", "Request was rate limited", {
+    details: { ...details }
+  }),
   internalError: (reason) => new CapxulError("INTERNAL_ERROR", `Internal error: ${reason}`),
   /**
    * Verification gate. Surfaced when a request hits a verification
@@ -215,6 +220,48 @@ function createReactDataClient(convexUrl, sessionStore) {
     }
   };
 }
+function createLazyReactDataClient(transport, sessionStore, createClient = createReactDataClient) {
+  let client = null;
+  let initializeClient = null;
+  let closed = false;
+  function closedError() {
+    return new Error("Capxul React data client is closed");
+  }
+  async function getClient() {
+    if (closed) throw closedError();
+    if (client) return client;
+    initializeClient ??= (async () => {
+      const runtime = await transport.ensureRuntime();
+      if (closed) throw closedError();
+      const nextClient = createClient(runtime.convexUrl, sessionStore);
+      if (closed) {
+        nextClient.close();
+        throw closedError();
+      }
+      client = nextClient;
+      return nextClient;
+    })().catch((error) => {
+      if (!closed) {
+        initializeClient = null;
+      }
+      throw error;
+    });
+    return initializeClient;
+  }
+  return {
+    query: async (name, args) => (await getClient()).query(name, args),
+    mutation: async (name, args) => (await getClient()).mutation(name, args),
+    action: async (name, args) => (await getClient()).action?.(name, args),
+    refreshAuth: () => {
+      client?.refreshAuth();
+    },
+    close: () => {
+      closed = true;
+      client?.close();
+      client = null;
+    }
+  };
+}
 function CapxulProvider({
   config,
   sessionStore,
@@ -244,12 +291,12 @@ function CapxulProvider({
 function buildWiring(config, sessionStore) {
   const validated = createCapxulConfig(config);
   const transport = makeHttpTransport(validated);
-  const dataClient = validated.mode === "build-time-urls" ? createReactDataClient(validated.convexUrl, sessionStore) : null;
+  const dataClient = validated.mode === "build-time-urls" ? createReactDataClient(validated.convexUrl, sessionStore) : createLazyReactDataClient(transport, sessionStore);
   const sdkConfig = {
     _transport: transport,
     publishableKey: validated.mode === "publishable-key" ? validated.publishableKey : void 0,
     data: dataClient ?? void 0,
-    auth: dataClient ? {
+    auth: validated.mode === "build-time-urls" || validated.mode === "publishable-key" ? {
       // The auth client builds the BetterAuth root URL from this
       // value. Convex's `.cloud` URL is the wrong host (BetterAuth
       // is mounted on the `.site` URL), but the build-time-urls
@@ -552,6 +599,12 @@ function useAuthFlow() {
   const [snapshot, send] = useActor(machine);
   return { snapshot, send };
 }
+function useAuthBootstrapFlow() {
+  const client = useCapxul();
+  const machine = useMemo(() => client.flows.authBootstrap(), [client]);
+  const [snapshot, send] = useActor(machine);
+  return { snapshot, send };
+}
 function useOnboardingFlow() {
   const client = useCapxul();
   const machine = useMemo(() => client.flows.onboarding(), [client]);
@@ -660,4 +713,4 @@ function validateAndNormalizeEvmAddress(field, raw) {
   }
 }
 
-export { CapxulClientProvider, CapxulProvider, CapxulTransportProvider, createCapxulConfig, injectedConnector, localPrivateKeyConnector, useAccount, useApiKey, useApiKeys, useAuthFlow, useBalanceLedger, useBalanceLedgerEntry, useCapxul, useCapxulStatus, useDocument, useDocuments, useExternalAccount, useExternalAccounts, useKybProfile, useKycProfile, useMe, useMember, useMembers, useOnboardingFlow, useOperation, useOrgDocuments, useOrgPayments, useOrgTransfers, useOrgWithdrawals, useOrganization, useOrganizations, usePayment, usePayments, useProvisioningFlow, useSafe, useSubAccount, useSubAccounts, useTokenTransfer, useTokenTransfers, useTransfer, useTransfers, useTreasury, useVirtualAccount, useVirtualAccounts, useVirtualCard, useVirtualCards, useWebhookEndpoint, useWebhookEndpoints, useWebhookEvent, useWithdrawal, useWithdrawals };
+export { CapxulClientProvider, CapxulProvider, CapxulTransportProvider, createCapxulConfig, injectedConnector, localPrivateKeyConnector, useAccount, useApiKey, useApiKeys, useAuthBootstrapFlow, useAuthFlow, useBalanceLedger, useBalanceLedgerEntry, useCapxul, useCapxulStatus, useDocument, useDocuments, useExternalAccount, useExternalAccounts, useKybProfile, useKycProfile, useMe, useMember, useMembers, useOnboardingFlow, useOperation, useOrgDocuments, useOrgPayments, useOrgTransfers, useOrgWithdrawals, useOrganization, useOrganizations, usePayment, usePayments, useProvisioningFlow, useSafe, useSubAccount, useSubAccounts, useTokenTransfer, useTokenTransfers, useTransfer, useTransfers, useTreasury, useVirtualAccount, useVirtualAccounts, useVirtualCard, useVirtualCards, useWebhookEndpoint, useWebhookEndpoints, useWebhookEvent, useWithdrawal, useWithdrawals };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capxul/sdk-react",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.9",
   "description": "React provider + hooks for the @capxul/sdk headless client.",
   "license": "UNLICENSED",
   "private": false,
@@ -46,13 +46,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@capxul/sdk": "0.1.0-alpha.6"
+    "@capxul/sdk": "0.1.0-alpha.9"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5",
     "@xstate/react": "^5",
     "convex": ">=1.0.0",
-    "react": ">=18.2.0 <20",
+    "react": ">=19.0.0",
     "viem": ">=2.0.0"
   },
   "devDependencies": {
@@ -70,8 +70,8 @@
     "typescript": "5.9.2",
     "viem": "2.47.10",
     "vitest": "^4.1.2",
-    "@repo/config": "0.0.0",
     "@repo/observability": "0.0.0",
+    "@repo/config": "0.0.0",
     "@repo/platform-kernel": "0.0.0",
     "@repo/typescript-config": "0.0.0"
   },