@capxul/sdk-react 0.1.0-alpha.4 → 0.1.0-alpha.8

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @capxul/sdk-react
 
+## 0.1.0-alpha.8
+
+### Minor Changes
+
+- 3af04a9: Public `<CapxulProvider>` now wires authenticated Convex reads end-to-end (#487, closes #484).
+
+  The `build-time-urls` arm of `BrowserCapxulConfig` now causes the provider to internally instantiate a `ConvexReactClient`, wrap it as a `CapxulDataClient`, and feed it as `config.data` into `createCapxulClient`. The existing `auth.createDataClient` callback is wired to the same singleton so a `verifyOtp` call refreshes the data client's auth header without churning the WebSocket. The provider also wraps `client.auth.signOut` so the data client survives sign-out — post-signout reads return typed backend `NOT_AUTHENTICATED` instead of the SDK's `NOT_IMPLEMENTED` stub (closes the #474 friction as a side-effect).
+
+  New optional `sessionStore?: AuthSessionStore` prop lets browser apps opt into `localStorage`-backed persistence and Node consumers (CLIs, e2e harnesses) opt into file-backed persistence. Defaults to in-memory.
+
+  This closes the architectural gap that made the React hook surface (`useMe`, `useAccount`, `useSafe`, ...) impossible to exercise end-to-end through the public provider — previously `config.data` was never populated, so every authenticated read short-circuited to `NOT_IMPLEMENTED`. The Ink reference CLI (`apps/reference-cli/`) is rebuilt on top of the public provider as proof: 17/17 agent-driver assertions pass against live alpha-3 Convex, including a dev-OTP authenticated round-trip that mints a real session via `AUTH_DEV_OTP=00000` and exercises three distinct hook end-states (`NOT_AUTHENTICATED`, `PROFILE_NOT_FOUND`, post-signout `NOT_AUTHENTICATED`).
+
+- 57203a4: Withdrawals v1 W2 (#465) — public surface tightening + org-scope create
+  - `WithdrawalsCreateInput.destination` no longer accepts `kind`. The
+    backend now resolves the `external_account` row by FK and infers
+    the kind + rail server-side. Anything that doesn't route to
+    `chain_wallet` (or is chain_wallet but non-EVM in slice 1) returns
+    `VERIFICATION_REQUIRED` with `details.rail` + `details.currentKind`.
+  - `organizations.withdrawals.create` is now a real mutation (no
+    longer a `NOT_IMPLEMENTED` stub). Returns the `processing` row
+    only — Safe + Zodiac submission orchestration ships in W3+.
+  - `Errors.verificationRequired({ rail, currentKind })` factory
+    added; the `VERIFICATION_REQUIRED` code now broadens to cover
+    both KYC tier gates and unsupported withdrawal rails.
+
+  **Migration:** Remove `destination.kind` from any
+  `capxul.withdrawals.create({ destination: { kind, externalAccountId } })`
+  call sites. Pass only `externalAccountId`.
+
+### Patch Changes
+
+- Updated dependencies [57203a4]
+  - @capxul/sdk@0.1.0-alpha.8
+
 ## 0.1.0-alpha.4
 
 ### Minor Changes

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

@@ -5,6 +5,7 @@ var react = require('react');
 var sdk = require('@capxul/sdk');
 var reactQuery = require('@tanstack/react-query');
 var jsxRuntime = require('react/jsx-runtime');
+var react$2 = require('convex/react');
 var errors = require('@capxul/sdk/errors');
 var react$1 = require('@xstate/react');
 var viem = require('viem');
@@ -109,8 +110,35 @@ var Errors = {
     "Idempotency key was already used for a different request",
     { details }
   ),
-  emailDeliveryFailed: (detail) => new CapxulError("EMAIL_DELIVERY_FAILED", `Failed to send email: ${detail}`),
-  internalError: (reason) => new CapxulError("INTERNAL_ERROR", `Internal error: ${reason}`)
+  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
+   * boundary the actor cannot cross under their current state. Two
+   * variants share this code:
+   *
+   * - Rail gate (Withdrawals v1 W2, #465): the resolved
+   *   `external_account.kind` routes to a withdrawal rail (e.g.
+   *   `fiat_offramp`, `card_payout`) that is not yet supported. Carries
+   *   `details.rail` + `details.currentKind`.
+   * - KYC tier gate (legacy / future): the actor's KYC tier is below
+   *   the required tier. Carries `details.requiredTier`.
+   *
+   * Code is shared because both expose the same UX shape ("you cannot
+   * proceed until verification advances"); the `details.*` keys
+   * differentiate the route.
+   */
+  verificationRequired: (details) => {
+    const message = "rail" in details ? `Withdrawal rail "${details.rail}" (kind=${details.currentKind}) is not yet supported.` : `Verification tier ${details.requiredTier} is required.`;
+    return new CapxulError("VERIFICATION_REQUIRED", message, {
+      details: { ...details }
+    });
+  }
 };
 
 // ../config/src/org-roles.ts
@@ -172,12 +200,87 @@ function assertModeRequiredFields(input) {
     }
   }
 }
+function createReactDataClient(convexUrl, sessionStore) {
+  const client = new react$2.ConvexReactClient(convexUrl);
+  const refreshAuth = () => {
+    const session = sessionStore.get();
+    const jwt = session?.convexJwt;
+    if (jwt) {
+      client.setAuth(() => Promise.resolve(jwt));
+    } else {
+      client.clearAuth();
+    }
+  };
+  refreshAuth();
+  return {
+    query: (name, args) => client.query(name, args),
+    mutation: (name, args) => client.mutation(name, args),
+    action: (name, args) => client.action(name, args),
+    refreshAuth,
+    close: () => {
+      void client.close();
+    }
+  };
+}
+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,
   queryClient,
   children
 }) {
-  const wiring = react.useMemo(() => buildWiring(config), [config]);
+  const defaultSessionStore = react.useMemo(() => createMemorySessionStore(), []);
+  const effectiveSessionStore = sessionStore ?? defaultSessionStore;
+  const wiring = react.useMemo(
+    () => buildWiring(config, effectiveSessionStore),
+    [config, effectiveSessionStore]
+  );
+  react.useEffect(() => {
+    return () => {
+      wiring.dataClient?.close();
+    };
+  }, [wiring]);
   const defaultClient = react.useMemo(
     () => new reactQuery.QueryClient({
       defaultOptions: { queries: { staleTime: 3e4 } }
@@ -187,16 +290,58 @@ function CapxulProvider({
   const effectiveClient = queryClient ?? defaultClient;
   return /* @__PURE__ */ jsxRuntime.jsx(reactQuery.QueryClientProvider, { client: effectiveClient, children: /* @__PURE__ */ jsxRuntime.jsx(CapxulTransportProvider, { transport: wiring.transport, children: /* @__PURE__ */ jsxRuntime.jsx(CapxulClientProvider, { client: wiring.client, children }) }) });
 }
-function buildWiring(config) {
+function buildWiring(config, sessionStore) {
   const validated = createCapxulConfig(config);
   const transport = sdk.makeHttpTransport(validated);
+  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
+    publishableKey: validated.mode === "publishable-key" ? validated.publishableKey : void 0,
+    data: dataClient ?? void 0,
+    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
+      // transport already encodes the correct `authBaseUrl` via
+      // its discriminated union. We pass `convexUrl` here only so
+      // `core/auth.ts`'s `createTransportProvider` short-circuits
+      // to the externally-injected `_transport` cache slot.
+      baseUrl: transport.authBaseUrl,
+      sessionStore,
+      createDataClient: async (_session) => {
+        dataClient.refreshAuth();
+        return dataClient;
+      }
+    } : void 0
   };
+  const client = sdk.createCapxulClient(sdkConfig);
+  if (dataClient) {
+    const originalSignOut = client.auth.signOut;
+    Object.assign(client.auth, {
+      signOut: async () => {
+        const result = await originalSignOut();
+        dataClient.refreshAuth();
+        sdkConfig.data = dataClient;
+        return result;
+      }
+    });
+  }
   return {
-    client: sdk.createCapxulClient(sdkConfig),
-    transport
+    client,
+    transport,
+    dataClient
+  };
+}
+function createMemorySessionStore() {
+  let current = null;
+  return {
+    get: () => current,
+    set: (session) => {
+      current = session;
+    },
+    clear: () => {
+      current = null;
+    }
   };
 }
 function notImplementedQuery(hookName) {
@@ -318,8 +463,15 @@ function useKycProfile(_accountId) {
 function useKybProfile(_organizationId) {
   return notImplementedQuery("useKybProfile");
 }
-function useExternalAccount(_args) {
-  return notImplementedQuery("useExternalAccount");
+function useExternalAccount(args) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => args.ownerKind === "account" ? capxul.externalAccounts.retrieve(args.externalAccountId) : capxul.organizations.externalAccounts.retrieve({
+      organizationId: args.ownerId,
+      externalAccountId: args.externalAccountId
+    }),
+    [capxul, args.ownerKind, args.ownerId, args.externalAccountId]
+  );
 }
 function useSubAccount(_subAccountId) {
   return notImplementedQuery("useSubAccount");
@@ -377,8 +529,14 @@ function useOrganizations() {
 function useMembers(_organizationId) {
   return notImplementedQuery("useMembers");
 }
-function useExternalAccounts(_args) {
-  return notImplementedQuery("useExternalAccounts");
+function useExternalAccounts(args) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => args.ownerKind === "account" ? capxul.accounts.externalAccounts.list({ accountId: args.ownerId }) : capxul.organizations.externalAccounts.list({
+      organizationId: args.ownerId
+    }),
+    [capxul, args.ownerKind, args.ownerId]
+  );
 }
 function useSubAccounts(_args) {
   return notImplementedQuery("useSubAccounts");

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { HttpTransport, TransportState, BrowserCapxulConfig, 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';
+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';
 import { QueryClient, UseQueryResult } from '@tanstack/react-query';
 import { CapxulClient } from '@capxul/sdk/client';
@@ -58,16 +58,30 @@ declare function useCapxulStatus(): TransportState;
  * `CapxulProvider` — public React provider for `@capxul/sdk-react`.
  *
  * Single-input contract: accepts ONLY `{ config: BrowserCapxulConfig,
- * queryClient?, children }`. The browser config is the secret-safe
- * discriminated union from `@capxul/sdk` — `apiKey`, `data`, `signer`,
- * and other server-only fields are rejected at compile-time AND at
- * runtime via `createCapxulConfig`'s allow-list validator.
+ * sessionStore?, queryClient?, children }`. The browser config is the
+ * secret-safe discriminated union from `@capxul/sdk` — `apiKey`,
+ * `data`, `signer`, and other server-only fields are rejected at
+ * compile-time AND at runtime via `createCapxulConfig`'s allow-list
+ * validator.
  *
  * The provider builds an `HttpTransport` synchronously and injects it
  * into `createCapxulClient` via the internal `_transport` slot. The
  * transport is exposed through `CapxulTransportContext` so
  * `useCapxulStatus()` can subscribe to its lifecycle state machine.
  *
+ * The provider also builds a `ConvexReactClient`-backed data client
+ * for the `build-time-urls` arm and feeds it as `config.data` so the
+ * SDK domain methods (`me.get`, `accounts.retrieve`, ...) and the
+ * React hooks built on top can run authenticated reads against live
+ * Convex. The auth lifecycle threads through the optional
+ * `sessionStore` prop: `verifyOtp` writes a session to the store
+ * (which the SDK auth client persists), and the provider's data
+ * client re-reads the JWT on demand via `refreshAuth()`. Without a
+ * session store the provider falls back to an in-memory one, which
+ * is fine for browser apps that hold the page until next reload but
+ * inadequate for CLI / Node consumers that need cross-process
+ * persistence — those pass a file-backed store via the prop.
+ *
  * Tests and the e2e harness need the server-augmented `CapxulConfig`
  * shape (with `data`, `signer`, `signing`). Those callers use
  * `CapxulTestProvider` from `@capxul/sdk-react/proof` instead.
@@ -88,6 +102,17 @@ type CapxulProviderProps = {
      * via `createCapxulConfig`'s allow-list validator.
      */
     readonly config: BrowserCapxulConfig;
+    /**
+     * Auth session persistence adapter. The SDK auth client writes
+     * sessions here on `verifyOtp` and clears them on `signOut`. The
+     * provider's data client re-reads the JWT from this store on every
+     * `refreshAuth` call so reads carry the right auth header.
+     *
+     * Defaults to an in-memory store scoped to this provider. Pass a
+     * file-backed (Node CLI) or `localStorage`-backed (browser) store
+     * to persist sessions across process or page lifetimes.
+     */
+    readonly sessionStore?: AuthSessionStore;
     /**
      * Optional TanStack Query `QueryClient`. Pass your app's existing
      * client to share the cache across the SDK hooks and the host
@@ -97,7 +122,7 @@ type CapxulProviderProps = {
     readonly queryClient?: QueryClient;
     readonly children: ReactNode;
 };
-declare function CapxulProvider({ config, queryClient, children, }: CapxulProviderProps): ReactNode;
+declare function CapxulProvider({ config, sessionStore, queryClient, children, }: CapxulProviderProps): ReactNode;
 
 /**
  * `QueryResult<T>` — the canonical three-state return shape for every
@@ -232,7 +257,18 @@ declare function useTreasury(_organizationId: OrganizationId): QueryResult<Treas
 declare function useApiKey(_args: UseApiKeyArgs): QueryResult<ApiKey>;
 declare function useKycProfile(_accountId: AccountId): QueryResult<KycProfile>;
 declare function useKybProfile(_organizationId: OrganizationId): QueryResult<KybProfile>;
-declare function useExternalAccount(_args: UseExternalAccountArgs): QueryResult<ExternalAccount>;
+/**
+ * Withdrawals v1 W1 (#464) — wired through the SDK.
+ *
+ * Branches on `args.ownerKind` so `account` scope reads via the
+ * top-level `capxul.externalAccounts.retrieve(id)` (visibility-gated
+ * server-side by the caller's accountId), and `organization` scope
+ * reads via `capxul.organizations.externalAccounts.retrieve({ ... })`
+ * which adds an org-scope check for cross-org isolation. Both routes
+ * resolve to the same Convex query handler — the SDK ergonomics
+ * differ but the wire shape is identical.
+ */
+declare function useExternalAccount(args: UseExternalAccountArgs): QueryResult<ExternalAccount>;
 declare function useSubAccount(_subAccountId: SubAccountId): QueryResult<SubAccount>;
 declare function useVirtualAccount(_virtualAccountId: VirtualAccountId): QueryResult<VirtualAccount>;
 declare function useVirtualCard(_virtualCardId: VirtualCardId): QueryResult<VirtualCard>;
@@ -344,7 +380,17 @@ type OrgDocumentsFilters = OrgScopedFilters & {
  */
 declare function useOrganizations(): QueryResult<List<Organization>>;
 declare function useMembers(_organizationId: OrganizationId): QueryResult<List<Member>>;
-declare function useExternalAccounts(_args: OwnerRef): QueryResult<List<ExternalAccount>>;
+/**
+ * Withdrawals v1 W1 (#464) — wired through the SDK.
+ *
+ * Personal scope reads through `capxul.accounts.externalAccounts.list({
+ * accountId })` (Pattern A nested namespace); org scope reads through
+ * `capxul.organizations.externalAccounts.list({ organizationId })`.
+ * Both resolve to the same Convex query handler — the SDK ergonomics
+ * differ. Backend filters out `revoked` rows but keeps
+ * `pending_verification` rows visible (D5).
+ */
+declare function useExternalAccounts(args: OwnerRef): QueryResult<List<ExternalAccount>>;
 declare function useSubAccounts(_args: OwnerRef): QueryResult<List<SubAccount>>;
 declare function useVirtualAccounts(_filters?: VirtualAccountsFilters): QueryResult<List<VirtualAccount>>;
 declare function useVirtualCards(_filters?: VirtualCardsFilters): QueryResult<List<VirtualCard>>;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { HttpTransport, TransportState, BrowserCapxulConfig, 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';
+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';
 import { QueryClient, UseQueryResult } from '@tanstack/react-query';
 import { CapxulClient } from '@capxul/sdk/client';
@@ -58,16 +58,30 @@ declare function useCapxulStatus(): TransportState;
  * `CapxulProvider` — public React provider for `@capxul/sdk-react`.
  *
  * Single-input contract: accepts ONLY `{ config: BrowserCapxulConfig,
- * queryClient?, children }`. The browser config is the secret-safe
- * discriminated union from `@capxul/sdk` — `apiKey`, `data`, `signer`,
- * and other server-only fields are rejected at compile-time AND at
- * runtime via `createCapxulConfig`'s allow-list validator.
+ * sessionStore?, queryClient?, children }`. The browser config is the
+ * secret-safe discriminated union from `@capxul/sdk` — `apiKey`,
+ * `data`, `signer`, and other server-only fields are rejected at
+ * compile-time AND at runtime via `createCapxulConfig`'s allow-list
+ * validator.
  *
  * The provider builds an `HttpTransport` synchronously and injects it
  * into `createCapxulClient` via the internal `_transport` slot. The
  * transport is exposed through `CapxulTransportContext` so
  * `useCapxulStatus()` can subscribe to its lifecycle state machine.
  *
+ * The provider also builds a `ConvexReactClient`-backed data client
+ * for the `build-time-urls` arm and feeds it as `config.data` so the
+ * SDK domain methods (`me.get`, `accounts.retrieve`, ...) and the
+ * React hooks built on top can run authenticated reads against live
+ * Convex. The auth lifecycle threads through the optional
+ * `sessionStore` prop: `verifyOtp` writes a session to the store
+ * (which the SDK auth client persists), and the provider's data
+ * client re-reads the JWT on demand via `refreshAuth()`. Without a
+ * session store the provider falls back to an in-memory one, which
+ * is fine for browser apps that hold the page until next reload but
+ * inadequate for CLI / Node consumers that need cross-process
+ * persistence — those pass a file-backed store via the prop.
+ *
  * Tests and the e2e harness need the server-augmented `CapxulConfig`
  * shape (with `data`, `signer`, `signing`). Those callers use
  * `CapxulTestProvider` from `@capxul/sdk-react/proof` instead.
@@ -88,6 +102,17 @@ type CapxulProviderProps = {
      * via `createCapxulConfig`'s allow-list validator.
      */
     readonly config: BrowserCapxulConfig;
+    /**
+     * Auth session persistence adapter. The SDK auth client writes
+     * sessions here on `verifyOtp` and clears them on `signOut`. The
+     * provider's data client re-reads the JWT from this store on every
+     * `refreshAuth` call so reads carry the right auth header.
+     *
+     * Defaults to an in-memory store scoped to this provider. Pass a
+     * file-backed (Node CLI) or `localStorage`-backed (browser) store
+     * to persist sessions across process or page lifetimes.
+     */
+    readonly sessionStore?: AuthSessionStore;
     /**
      * Optional TanStack Query `QueryClient`. Pass your app's existing
      * client to share the cache across the SDK hooks and the host
@@ -97,7 +122,7 @@ type CapxulProviderProps = {
     readonly queryClient?: QueryClient;
     readonly children: ReactNode;
 };
-declare function CapxulProvider({ config, queryClient, children, }: CapxulProviderProps): ReactNode;
+declare function CapxulProvider({ config, sessionStore, queryClient, children, }: CapxulProviderProps): ReactNode;
 
 /**
  * `QueryResult<T>` — the canonical three-state return shape for every
@@ -232,7 +257,18 @@ declare function useTreasury(_organizationId: OrganizationId): QueryResult<Treas
 declare function useApiKey(_args: UseApiKeyArgs): QueryResult<ApiKey>;
 declare function useKycProfile(_accountId: AccountId): QueryResult<KycProfile>;
 declare function useKybProfile(_organizationId: OrganizationId): QueryResult<KybProfile>;
-declare function useExternalAccount(_args: UseExternalAccountArgs): QueryResult<ExternalAccount>;
+/**
+ * Withdrawals v1 W1 (#464) — wired through the SDK.
+ *
+ * Branches on `args.ownerKind` so `account` scope reads via the
+ * top-level `capxul.externalAccounts.retrieve(id)` (visibility-gated
+ * server-side by the caller's accountId), and `organization` scope
+ * reads via `capxul.organizations.externalAccounts.retrieve({ ... })`
+ * which adds an org-scope check for cross-org isolation. Both routes
+ * resolve to the same Convex query handler — the SDK ergonomics
+ * differ but the wire shape is identical.
+ */
+declare function useExternalAccount(args: UseExternalAccountArgs): QueryResult<ExternalAccount>;
 declare function useSubAccount(_subAccountId: SubAccountId): QueryResult<SubAccount>;
 declare function useVirtualAccount(_virtualAccountId: VirtualAccountId): QueryResult<VirtualAccount>;
 declare function useVirtualCard(_virtualCardId: VirtualCardId): QueryResult<VirtualCard>;
@@ -344,7 +380,17 @@ type OrgDocumentsFilters = OrgScopedFilters & {
  */
 declare function useOrganizations(): QueryResult<List<Organization>>;
 declare function useMembers(_organizationId: OrganizationId): QueryResult<List<Member>>;
-declare function useExternalAccounts(_args: OwnerRef): QueryResult<List<ExternalAccount>>;
+/**
+ * Withdrawals v1 W1 (#464) — wired through the SDK.
+ *
+ * Personal scope reads through `capxul.accounts.externalAccounts.list({
+ * accountId })` (Pattern A nested namespace); org scope reads through
+ * `capxul.organizations.externalAccounts.list({ organizationId })`.
+ * Both resolve to the same Convex query handler — the SDK ergonomics
+ * differ. Backend filters out `revoked` rows but keeps
+ * `pending_verification` rows visible (D5).
+ */
+declare function useExternalAccounts(args: OwnerRef): QueryResult<List<ExternalAccount>>;
 declare function useSubAccounts(_args: OwnerRef): QueryResult<List<SubAccount>>;
 declare function useVirtualAccounts(_filters?: VirtualAccountsFilters): QueryResult<List<VirtualAccount>>;
 declare function useVirtualCards(_filters?: VirtualCardsFilters): QueryResult<List<VirtualCard>>;

package/dist/index.js

@@ -1,8 +1,9 @@
 "use client";
-import { createContext, useContext, useSyncExternalStore, useMemo, useState, useEffect } from 'react';
+import { createContext, useContext, useSyncExternalStore, useMemo, useEffect, useState } from 'react';
 import { makeHttpTransport, createCapxulClient, CapxulError as CapxulError$1 } from '@capxul/sdk';
 import { QueryClient, QueryClientProvider, useQuery } from '@tanstack/react-query';
 import { jsx } from 'react/jsx-runtime';
+import { ConvexReactClient } from 'convex/react';
 import { CapxulError as CapxulError$2 } from '@capxul/sdk/errors';
 import { useActor } from '@xstate/react';
 import { getAddress } from 'viem';
@@ -107,8 +108,35 @@ var Errors = {
     "Idempotency key was already used for a different request",
     { details }
   ),
-  emailDeliveryFailed: (detail) => new CapxulError("EMAIL_DELIVERY_FAILED", `Failed to send email: ${detail}`),
-  internalError: (reason) => new CapxulError("INTERNAL_ERROR", `Internal error: ${reason}`)
+  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
+   * boundary the actor cannot cross under their current state. Two
+   * variants share this code:
+   *
+   * - Rail gate (Withdrawals v1 W2, #465): the resolved
+   *   `external_account.kind` routes to a withdrawal rail (e.g.
+   *   `fiat_offramp`, `card_payout`) that is not yet supported. Carries
+   *   `details.rail` + `details.currentKind`.
+   * - KYC tier gate (legacy / future): the actor's KYC tier is below
+   *   the required tier. Carries `details.requiredTier`.
+   *
+   * Code is shared because both expose the same UX shape ("you cannot
+   * proceed until verification advances"); the `details.*` keys
+   * differentiate the route.
+   */
+  verificationRequired: (details) => {
+    const message = "rail" in details ? `Withdrawal rail "${details.rail}" (kind=${details.currentKind}) is not yet supported.` : `Verification tier ${details.requiredTier} is required.`;
+    return new CapxulError("VERIFICATION_REQUIRED", message, {
+      details: { ...details }
+    });
+  }
 };
 
 // ../config/src/org-roles.ts
@@ -170,12 +198,87 @@ function assertModeRequiredFields(input) {
     }
   }
 }
+function createReactDataClient(convexUrl, sessionStore) {
+  const client = new ConvexReactClient(convexUrl);
+  const refreshAuth = () => {
+    const session = sessionStore.get();
+    const jwt = session?.convexJwt;
+    if (jwt) {
+      client.setAuth(() => Promise.resolve(jwt));
+    } else {
+      client.clearAuth();
+    }
+  };
+  refreshAuth();
+  return {
+    query: (name, args) => client.query(name, args),
+    mutation: (name, args) => client.mutation(name, args),
+    action: (name, args) => client.action(name, args),
+    refreshAuth,
+    close: () => {
+      void client.close();
+    }
+  };
+}
+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,
   queryClient,
   children
 }) {
-  const wiring = useMemo(() => buildWiring(config), [config]);
+  const defaultSessionStore = useMemo(() => createMemorySessionStore(), []);
+  const effectiveSessionStore = sessionStore ?? defaultSessionStore;
+  const wiring = useMemo(
+    () => buildWiring(config, effectiveSessionStore),
+    [config, effectiveSessionStore]
+  );
+  useEffect(() => {
+    return () => {
+      wiring.dataClient?.close();
+    };
+  }, [wiring]);
   const defaultClient = useMemo(
     () => new QueryClient({
       defaultOptions: { queries: { staleTime: 3e4 } }
@@ -185,16 +288,58 @@ function CapxulProvider({
   const effectiveClient = queryClient ?? defaultClient;
   return /* @__PURE__ */ jsx(QueryClientProvider, { client: effectiveClient, children: /* @__PURE__ */ jsx(CapxulTransportProvider, { transport: wiring.transport, children: /* @__PURE__ */ jsx(CapxulClientProvider, { client: wiring.client, children }) }) });
 }
-function buildWiring(config) {
+function buildWiring(config, sessionStore) {
   const validated = createCapxulConfig(config);
   const transport = makeHttpTransport(validated);
+  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
+    publishableKey: validated.mode === "publishable-key" ? validated.publishableKey : void 0,
+    data: dataClient ?? void 0,
+    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
+      // transport already encodes the correct `authBaseUrl` via
+      // its discriminated union. We pass `convexUrl` here only so
+      // `core/auth.ts`'s `createTransportProvider` short-circuits
+      // to the externally-injected `_transport` cache slot.
+      baseUrl: transport.authBaseUrl,
+      sessionStore,
+      createDataClient: async (_session) => {
+        dataClient.refreshAuth();
+        return dataClient;
+      }
+    } : void 0
   };
+  const client = createCapxulClient(sdkConfig);
+  if (dataClient) {
+    const originalSignOut = client.auth.signOut;
+    Object.assign(client.auth, {
+      signOut: async () => {
+        const result = await originalSignOut();
+        dataClient.refreshAuth();
+        sdkConfig.data = dataClient;
+        return result;
+      }
+    });
+  }
   return {
-    client: createCapxulClient(sdkConfig),
-    transport
+    client,
+    transport,
+    dataClient
+  };
+}
+function createMemorySessionStore() {
+  let current = null;
+  return {
+    get: () => current,
+    set: (session) => {
+      current = session;
+    },
+    clear: () => {
+      current = null;
+    }
   };
 }
 function notImplementedQuery(hookName) {
@@ -316,8 +461,15 @@ function useKycProfile(_accountId) {
 function useKybProfile(_organizationId) {
   return notImplementedQuery("useKybProfile");
 }
-function useExternalAccount(_args) {
-  return notImplementedQuery("useExternalAccount");
+function useExternalAccount(args) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => args.ownerKind === "account" ? capxul.externalAccounts.retrieve(args.externalAccountId) : capxul.organizations.externalAccounts.retrieve({
+      organizationId: args.ownerId,
+      externalAccountId: args.externalAccountId
+    }),
+    [capxul, args.ownerKind, args.ownerId, args.externalAccountId]
+  );
 }
 function useSubAccount(_subAccountId) {
   return notImplementedQuery("useSubAccount");
@@ -375,8 +527,14 @@ function useOrganizations() {
 function useMembers(_organizationId) {
   return notImplementedQuery("useMembers");
 }
-function useExternalAccounts(_args) {
-  return notImplementedQuery("useExternalAccounts");
+function useExternalAccounts(args) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => args.ownerKind === "account" ? capxul.accounts.externalAccounts.list({ accountId: args.ownerId }) : capxul.organizations.externalAccounts.list({
+      organizationId: args.ownerId
+    }),
+    [capxul, args.ownerKind, args.ownerId]
+  );
 }
 function useSubAccounts(_args) {
   return notImplementedQuery("useSubAccounts");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capxul/sdk-react",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.8",
   "description": "React provider + hooks for the @capxul/sdk headless client.",
   "license": "UNLICENSED",
   "private": false,
@@ -46,7 +46,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@capxul/sdk": "0.1.0-alpha.4"
+    "@capxul/sdk": "0.1.0-alpha.8"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5",