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

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @capxul/sdk-react
 
+## 0.1.0-alpha.4
+
+### Minor Changes
+
+- Post-alpha hardening — WAVE 1 + WAVE 2 cumulative
+
+  **WAVE 1 (merged 2026-05-03 12:44Z):**
+  - S2 story 1: wire onboarding readback hooks (#469) — `me.update`, `accounts.retrieve`, `accounts.update`, `useAccount`, `useSafe`
+  - S3 phase 1: Ink reference CLI scaffold + `auth+me` end-to-end against live alpha-3 Convex (#470). Stickiness gate (D3) fired.
+  - S5: split `CapxulProvider` into public single-input `BrowserCapxulConfig` + test-only `CapxulTestProvider` from `@capxul/sdk-react/proof` (#473). Q1 lock honored. 7 type-level provider-shape guards including `@ts-expect-error` against test-provider leaking to public barrel.
+
+  **WAVE 2 (merged 2026-05-03 12:54-13:16Z):**
+  - S3 phase 2: per-domain CLI commands closing #458 (#476) — `account retrieve/update`, `safe retrieve`, `payment retrieve`, `withdrawal retrieve/list`. 12/12 agent-driver tests pass.
+  - S2 story 2: `capxul.tokenTransfers.*` non-canonical SDK namespace (#479) — Option A per #477 (canon-aligned `transfers.*` shape deferred to alpha.5+ pending backend canon work). New `useTokenTransfers` + `useTokenTransfer` hooks; new `getByTxLogIndex` backend query. Hook proof matrix length unchanged at 41 (non-canonical hooks deliberately excluded).
+
+  **S1 (#456) closed no-op** — alpha publish infrastructure (tsup, lazy-DX, transport state machine, npm metadata, READMEs, CHANGELOG, changesets, OIDC release workflow) physically merged into `api-first` via PRs #449-#452 earlier the same day; the slice merge produced 0 file changes per clean-room probe.
+
+  **Friction issues filed for alpha.4+ polish:**
+  - #474 — `me.get` returns `NOT_IMPLEMENTED` when `config.data` is undefined; should be `NOT_AUTHENTICATED`.
+  - #475 — `@capxul/sdk/headless` slim entry point excludes xstate flow machines + brand constructors (1.6 MB → much smaller).
+  - #477 / #478 — `transfers.*` / `balanceLedger.*` / `treasury` canon-shape alignment with indexer feed.
+  - #471 — Vercel-capxul-web preview-deploy systemic failure on api-first base (separate from epic).
+
+### Patch Changes
+
+- Updated dependencies
+  - @capxul/sdk@0.1.0-alpha.4
+
+## 0.1.0-alpha.3
+
+### Patch Changes
+
+- Re-export `tryCatch` from `@capxul/sdk`.
+
+  `tryCatch` is referenced in `packages/sdk/README.md` (live on npm at
+  `0.1.0-alpha.2`) and in `.claude/rules/sdk.md` as the canonical
+  async-error helper for SDK operations:
+
+  ```ts
+  import { tryCatch } from "@capxul/sdk";
+
+  const [err, payment] = await tryCatch(capxul.payments.create({ ... }));
+  ```
+
+  The helper lives at `@repo/observability/try-catch.ts` and is bundled
+  into the SDK dist via tsup `noExternal`, but it was never re-exported
+  from `packages/sdk/src/index.ts`. Consumers following the README example
+  hit `Module '"@capxul/sdk"' has no exported member 'tryCatch'.` at
+  import time.
+
+  Caught during alpha.2 spike-install verification (REVIEW.html, "What's
+  not proven" row 6). One-line public-export addition; no runtime change.
+
+- Updated dependencies
+  - @capxul/sdk@0.1.0-alpha.3
+
 ## 0.1.0-alpha.2
 
 ### Patch Changes

package/dist/index.cjs

@@ -11,6 +11,45 @@ var viem = require('viem');
 var accounts = require('viem/accounts');
 
 // src/provider.tsx
+var CapxulClientContext = react.createContext(null);
+function CapxulClientProvider({
+  client,
+  children
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsx(CapxulClientContext.Provider, { value: client, children });
+}
+function useCapxul() {
+  const client = react.useContext(CapxulClientContext);
+  if (!client) {
+    throw new Error(
+      "useCapxul() was called outside a <CapxulProvider>. Wrap your app in <CapxulProvider config={...}> before rendering hooks from @capxul/sdk-react."
+    );
+  }
+  return client;
+}
+var CapxulTransportContext = react.createContext(null);
+function CapxulTransportProvider({
+  transport,
+  children
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsx(CapxulTransportContext.Provider, { value: transport, children });
+}
+function useCapxulStatus() {
+  const transport = react.useContext(CapxulTransportContext);
+  return react.useSyncExternalStore(
+    (listener) => {
+      if (!transport) return () => {
+      };
+      return transport.subscribe(listener);
+    },
+    () => transport?.getState() ?? FALLBACK_READY,
+    () => transport?.getState() ?? FALLBACK_READY
+  );
+}
+var FALLBACK_READY = Object.freeze({
+  status: "ready",
+  runtime: { authBaseUrl: "", convexUrl: "" }
+});
 
 // ../config/src/errors.ts
 var CapxulError = class extends Error {
@@ -83,56 +122,62 @@ function roleKeyFromLabel(label) {
 roleKeyFromLabel("OWNER");
 roleKeyFromLabel("FINANCE_MANAGER");
 roleKeyFromLabel("TEAM_LEAD");
-var CapxulClientContext = react.createContext(null);
-function CapxulClientProvider({
-  client,
-  children
-}) {
-  return /* @__PURE__ */ jsxRuntime.jsx(CapxulClientContext.Provider, { value: client, children });
-}
-function useCapxul() {
-  const client = react.useContext(CapxulClientContext);
-  if (!client) {
-    throw new Error(
-      "useCapxul() was called outside a <CapxulProvider>. Wrap your app in <CapxulProvider config={...}> before rendering hooks from @capxul/sdk-react."
-    );
-  }
-  return client;
-}
-var CapxulTransportContext = react.createContext(null);
-function CapxulTransportProvider({
-  transport,
-  children
-}) {
-  return /* @__PURE__ */ jsxRuntime.jsx(CapxulTransportContext.Provider, { value: transport, children });
+
+// src/config.ts
+function createCapxulConfig(input) {
+  assertOnlyKnownKeys(input);
+  assertModeRequiredFields(input);
+  return Object.freeze({ ...input });
 }
-function useCapxulStatus() {
-  const transport = react.useContext(CapxulTransportContext);
-  return react.useSyncExternalStore(
-    (listener) => {
-      if (!transport) return () => {
-      };
-      return transport.subscribe(listener);
-    },
-    () => transport?.getState() ?? FALLBACK_READY,
-    () => transport?.getState() ?? FALLBACK_READY
+var ALLOWED_BROWSER_CONFIG_KEYS = [
+  "mode",
+  "authBaseUrl",
+  "convexUrl",
+  "publishableKey",
+  "bootstrapUrl",
+  "fetchImpl"
+];
+function assertOnlyKnownKeys(input) {
+  const candidate = input;
+  const allowed = new Set(ALLOWED_BROWSER_CONFIG_KEYS);
+  const unknown = Object.keys(candidate).filter((key) => !allowed.has(key));
+  if (unknown.length === 0) return;
+  throw Errors.invalidInput(
+    "config",
+    `Browser Capxul config contains unknown or secret/server-only fields: ${unknown.join(", ")}. Allowed keys: ${ALLOWED_BROWSER_CONFIG_KEYS.join(", ")}.`
   );
 }
-var FALLBACK_READY = Object.freeze({
-  status: "ready",
-  runtime: { authBaseUrl: "", convexUrl: "" }
-});
+function assertModeRequiredFields(input) {
+  switch (input.mode) {
+    case "build-time-urls": {
+      if (!input.authBaseUrl || input.authBaseUrl.trim().length === 0) {
+        throw Errors.invalidInput("authBaseUrl", "non-empty string required.");
+      }
+      if (!input.convexUrl || input.convexUrl.trim().length === 0) {
+        throw Errors.invalidInput("convexUrl", "non-empty string required.");
+      }
+      return;
+    }
+    case "publishable-key": {
+      if (!input.publishableKey || input.publishableKey.trim().length === 0) {
+        throw Errors.invalidInput("publishableKey", "non-empty string required.");
+      }
+      return;
+    }
+    default: {
+      const value = input;
+      throw Errors.internalError(
+        `Unhandled BrowserCapxulConfig.mode: ${String(value.mode)}.`
+      );
+    }
+  }
+}
 function CapxulProvider({
   config,
-  publishableKey,
-  browserConfig,
   queryClient,
   children
 }) {
-  const wiring = react.useMemo(
-    () => buildWiring({ config, publishableKey, browserConfig }),
-    [config, publishableKey, browserConfig]
-  );
+  const wiring = react.useMemo(() => buildWiring(config), [config]);
   const defaultClient = react.useMemo(
     () => new reactQuery.QueryClient({
       defaultOptions: { queries: { staleTime: 3e4 } }
@@ -140,47 +185,14 @@ function CapxulProvider({
     []
   );
   const effectiveClient = queryClient ?? defaultClient;
-  const inner = /* @__PURE__ */ jsxRuntime.jsx(CapxulClientProvider, { client: wiring.client, children });
-  return /* @__PURE__ */ jsxRuntime.jsx(reactQuery.QueryClientProvider, { client: effectiveClient, children: wiring.transport ? /* @__PURE__ */ jsxRuntime.jsx(CapxulTransportProvider, { transport: wiring.transport, children: inner }) : inner });
+  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,
-  publishableKey,
-  browserConfig
-}) {
-  const sources = [
-    config !== void 0,
-    publishableKey !== void 0,
-    browserConfig !== void 0
-  ].filter(Boolean).length;
-  if (sources === 0) {
-    throw Errors.invalidInput(
-      "CapxulProvider",
-      "Pass exactly one of `config`, `publishableKey`, or `browserConfig`."
-    );
-  }
-  if (sources > 1) {
-    throw Errors.invalidInput(
-      "CapxulProvider",
-      "`config`, `publishableKey`, and `browserConfig` are mutually exclusive \u2014 pass exactly one."
-    );
-  }
-  if (config !== void 0) {
-    return {
-      client: sdk.createCapxulClient(config),
-      transport: null
-    };
-  }
-  const browserCfg = browserConfig ?? {
-    mode: "publishable-key",
-    // The narrowing above (`sources === 0` rejected; `config` not
-    // present) guarantees `publishableKey` is set on this branch.
-    publishableKey
-  };
-  const transport = sdk.makeHttpTransport(browserCfg);
+function buildWiring(config) {
+  const validated = createCapxulConfig(config);
+  const transport = sdk.makeHttpTransport(validated);
   const sdkConfig = {
     _transport: transport,
-    publishableKey: browserCfg.mode === "publishable-key" ? browserCfg.publishableKey : void 0
+    publishableKey: validated.mode === "publishable-key" ? validated.publishableKey : void 0
   };
   return {
     client: sdk.createCapxulClient(sdkConfig),
@@ -274,8 +286,12 @@ function useMe() {
     staleTime: 3e4
   });
 }
-function useAccount(_accountId) {
-  return notImplementedQuery("useAccount");
+function useAccount(accountId) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => accountId !== void 0 ? capxul.accounts.retrieve(accountId) : capxul.me.get(),
+    [capxul, accountId]
+  );
 }
 function useOrganization(_organizationId) {
   return notImplementedQuery("useOrganization");
@@ -283,8 +299,12 @@ function useOrganization(_organizationId) {
 function useMember(_args) {
   return notImplementedQuery("useMember");
 }
-function useSafe(_safeId) {
-  return notImplementedQuery("useSafe");
+function useSafe(safeId) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => capxul.accounts.safes.retrieve(safeId),
+    [capxul, safeId]
+  );
 }
 function useTreasury(_organizationId) {
   return notImplementedQuery("useTreasury");
@@ -316,6 +336,13 @@ function usePayment(_paymentId) {
 function useTransfer(_transferId) {
   return notImplementedQuery("useTransfer");
 }
+function useTokenTransfer(args) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => capxul.tokenTransfers.retrieve(args),
+    [capxul, args.txHash, args.logIndex, args.chainId]
+  );
+}
 function useBalanceLedgerEntry(_args) {
   return notImplementedQuery("useBalanceLedgerEntry");
 }
@@ -374,6 +401,13 @@ function useTransfers(_filters) {
 function useOrgTransfers(_args) {
   return notImplementedQuery("useOrgTransfers");
 }
+function useTokenTransfers(filters) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => capxul.tokenTransfers.list(filters),
+    [capxul, filters?.limit, filters?.cursor, filters?.direction]
+  );
+}
 function useBalanceLedger(_args) {
   return notImplementedQuery("useBalanceLedger");
 }
@@ -421,56 +455,6 @@ function useProvisioningFlow() {
   const [snapshot, send] = react$1.useActor(machine);
   return { snapshot, send };
 }
-
-// src/config.ts
-function createCapxulConfig(input) {
-  assertOnlyKnownKeys(input);
-  assertModeRequiredFields(input);
-  return Object.freeze({ ...input });
-}
-var ALLOWED_BROWSER_CONFIG_KEYS = [
-  "mode",
-  "authBaseUrl",
-  "convexUrl",
-  "publishableKey",
-  "bootstrapUrl",
-  "fetchImpl"
-];
-function assertOnlyKnownKeys(input) {
-  const candidate = input;
-  const allowed = new Set(ALLOWED_BROWSER_CONFIG_KEYS);
-  const unknown = Object.keys(candidate).filter((key) => !allowed.has(key));
-  if (unknown.length === 0) return;
-  throw Errors.invalidInput(
-    "config",
-    `Browser Capxul config contains unknown or secret/server-only fields: ${unknown.join(", ")}. Allowed keys: ${ALLOWED_BROWSER_CONFIG_KEYS.join(", ")}.`
-  );
-}
-function assertModeRequiredFields(input) {
-  switch (input.mode) {
-    case "build-time-urls": {
-      if (!input.authBaseUrl || input.authBaseUrl.trim().length === 0) {
-        throw Errors.invalidInput("authBaseUrl", "non-empty string required.");
-      }
-      if (!input.convexUrl || input.convexUrl.trim().length === 0) {
-        throw Errors.invalidInput("convexUrl", "non-empty string required.");
-      }
-      return;
-    }
-    case "publishable-key": {
-      if (!input.publishableKey || input.publishableKey.trim().length === 0) {
-        throw Errors.invalidInput("publishableKey", "non-empty string required.");
-      }
-      return;
-    }
-    default: {
-      const value = input;
-      throw Errors.internalError(
-        `Unhandled BrowserCapxulConfig.mode: ${String(value.mode)}.`
-      );
-    }
-  }
-}
 var PRIVATE_KEY_PATTERN = /^0x[0-9a-fA-F]{64}$/;
 var EVM_ADDRESS_PATTERN = /^0x[0-9a-fA-F]{40}$/;
 function injectedConnector(options = {}) {
@@ -604,6 +588,8 @@ exports.useProvisioningFlow = useProvisioningFlow;
 exports.useSafe = useSafe;
 exports.useSubAccount = useSubAccount;
 exports.useSubAccounts = useSubAccounts;
+exports.useTokenTransfer = useTokenTransfer;
+exports.useTokenTransfers = useTokenTransfers;
 exports.useTransfer = useTransfer;
 exports.useTransfers = useTransfers;
 exports.useTreasury = useTreasury;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { HttpTransport, TransportState, CapxulConfig, 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, TransferId, Transfer, Treasury, VirtualAccountId, VirtualAccount, VirtualCardId, VirtualCard, WebhookEndpointId, WebhookEndpoint, WebhookEventId, WebhookEvent, WithdrawalId, Withdrawal, List, LocalPrivateKeySignerProvider } from '@capxul/sdk';
+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';
 export { AuthFlowContext, AuthFlowEvent, BrowserCapxulConfig, OnboardingFlowContext, OnboardingFlowEvent, ProvisioningFlowContext, ProvisioningFlowEvent } from '@capxul/sdk';
 import { QueryClient, UseQueryResult } from '@tanstack/react-query';
 import { CapxulClient } from '@capxul/sdk/client';
@@ -55,55 +55,39 @@ declare function CapxulTransportProvider({ transport, children, }: CapxulTranspo
 declare function useCapxulStatus(): TransportState;
 
 /**
- * `CapxulProvider` — React context provider that wires both the
- * `@capxul/sdk` client AND a TanStack Query `QueryClient` for the
- * subtree.
+ * `CapxulProvider` — public React provider for `@capxul/sdk-react`.
  *
- * Two construction paths:
+ * 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.
  *
- * 1. **Legacy / harness path** — pass an already-assembled
- *    `config: CapxulConfig`. Used by the e2e harness and CLI-shaped
- *    integrations that build their own auth/data adapters.
+ * 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.
  *
- * 2. **Lazy-DX path (ADR #14c)** — pass either `publishableKey` or
- *    `browserConfig`. The provider builds an `HttpTransport`
- *    synchronously, injects it into `createCapxulClient` via the
- *    internal `_transport` slot, and exposes the transport through
- *    `CapxulTransportContext` so `useCapxulStatus()` can subscribe
- *    to its lifecycle state machine.
- *
- *    The lazy-DX provider mounts synchronously. There is no
- *    `useState` mutating config, no `useMemo` rebuilding config when
- *    state changes, and no Suspense gate at mount. State transitions
- *    happen on the transport (a stable singleton); React subscribes
- *    via `useSyncExternalStore` and re-renders only the components
- *    that actually depend on the transport state.
+ * 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.
  *
  * Per ADR 4 in the API-first architecture stack PLAN, only
  * `QueryClientProvider` is allowed to live OUTSIDE the single
  * `CapxulContext`. The `QueryClientProvider` is the outermost wrap;
- * the SDK client provider sits inside it; the optional transport
- * provider sits between the two when the lazy-DX path is active.
+ * the SDK client provider sits inside it; the transport provider sits
+ * between the two.
  */
 
 type CapxulProviderProps = {
     /**
-     * Pre-assembled `CapxulConfig` for the legacy / harness path.
-     * Mutually exclusive with `publishableKey` / `browserConfig`.
-     */
-    readonly config?: CapxulConfig;
-    /**
-     * Shorthand for the publishable-key arm of `BrowserCapxulConfig`.
-     * Provider builds the transport synchronously and injects it into
-     * the SDK client — the canonical lazy-DX entry point per ADR #14c.
+     * Browser-safe Capxul config — the discriminated union from
+     * `@capxul/sdk`. Either the `build-time-urls` arm or the
+     * `publishable-key` arm. Server-only fields (`apiKey`, `data`,
+     * `signer`, `signing`) are rejected at compile-time and at runtime
+     * via `createCapxulConfig`'s allow-list validator.
      */
-    readonly publishableKey?: string;
-    /**
-     * Full `BrowserCapxulConfig` for callers that need
-     * `mode: "build-time-urls"` or a custom `fetchImpl` (e.g. tests).
-     * Mutually exclusive with `publishableKey` / `config`.
-     */
-    readonly browserConfig?: BrowserCapxulConfig;
+    readonly config: BrowserCapxulConfig;
     /**
      * Optional TanStack Query `QueryClient`. Pass your app's existing
      * client to share the cache across the SDK hooks and the host
@@ -113,7 +97,7 @@ type CapxulProviderProps = {
     readonly queryClient?: QueryClient;
     readonly children: ReactNode;
 };
-declare function CapxulProvider({ config, publishableKey, browserConfig, queryClient, children, }: CapxulProviderProps): ReactNode;
+declare function CapxulProvider({ config, queryClient, children, }: CapxulProviderProps): ReactNode;
 
 /**
  * `QueryResult<T>` — the canonical three-state return shape for every
@@ -220,16 +204,27 @@ declare function useMe(): UseQueryResult<Account, CapxulError$1>;
 /**
  * Account by id. Omit `accountId` for the calling user (alias for
  * `useMe()` from a developer-perspective lens).
+ *
+ * Slice 2 (#457 story 1): wired via `capxul.accounts.retrieve` for
+ * the id-bearing call and `capxul.me.get()` for the self-lens
+ * shortcut. Returns the legacy `QueryResult<Account>` shape because
+ * only `useMe` has migrated to TanStack Query so far (PLAN.md task
+ * 1.8) — per-hook migration is the rollout pattern.
  */
-declare function useAccount(_accountId?: AccountId): QueryResult<Account>;
+declare function useAccount(accountId?: AccountId): QueryResult<Account>;
 declare function useOrganization(_organizationId: OrganizationId): QueryResult<Organization>;
 declare function useMember(_args: UseMemberArgs): QueryResult<Member>;
 /**
  * Live; status advances as the indexer reconciles the on-chain
  * deployment. Consumers pattern-match on `data.status` via
  * `matchStatus` (see `@capxul/sdk`).
+ *
+ * Slice 2 (#457 story 1): wired via
+ * `capxul.accounts.safes.retrieve(safeId)`. The SDK method is real
+ * post-Withdrawals v1 slice 1; this hook closes the React-side
+ * stub so onboarding can subscribe to Safe deploy progress.
  */
-declare function useSafe(_safeId: SafeId): QueryResult<Safe>;
+declare function useSafe(safeId: SafeId): QueryResult<Safe>;
 declare function useTreasury(_organizationId: OrganizationId): QueryResult<Treasury>;
 /**
  * Org-admin lens only — the hook NEVER returns `secret`.
@@ -243,6 +238,22 @@ declare function useVirtualAccount(_virtualAccountId: VirtualAccountId): QueryRe
 declare function useVirtualCard(_virtualCardId: VirtualCardId): QueryResult<VirtualCard>;
 declare function usePayment(_paymentId: PaymentId): QueryResult<Payment>;
 declare function useTransfer(_transferId: TransferId): QueryResult<Transfer>;
+type UseTokenTransferArgs = {
+    readonly txHash: string;
+    readonly logIndex: number;
+    readonly chainId?: number;
+};
+/**
+ * **NON-CANONICAL** raw on-chain ERC-20 transfer detail. Wired through
+ * `capxul.tokenTransfers.retrieve` per slice/02-story2-balance
+ * Option-A verdict. Identifier is the canonical on-chain composite
+ * `(txHash, logIndex)` so consumers don't have to round-trip through
+ * the Convex doc id.
+ *
+ * Intentionally NOT in `packages/sdk-react/ops/proof/hook-manifest.ts`
+ * — the canonical proof manifest tracks canon-aligned hooks only.
+ */
+declare function useTokenTransfer(args: UseTokenTransferArgs): QueryResult<TokenTransfer>;
 /**
  * Immutable once written; `live` semantically only for late
  * `paymentId` / `transferId` attachment per Doc 02 §"balance_ledger".
@@ -345,6 +356,17 @@ declare function usePayments(_filters?: PaymentsFilters): QueryResult<List<Payme
 declare function useOrgPayments(_args: OrgScopedFilters): QueryResult<List<Payment>>;
 declare function useTransfers(_filters?: TransfersFilters): QueryResult<List<Transfer>>;
 declare function useOrgTransfers(_args: OrgScopedFilters): QueryResult<List<Transfer>>;
+/**
+ * **NON-CANONICAL** raw on-chain ERC-20 transfer feed. Wired through
+ * `capxul.tokenTransfers.list` per slice/02-story2-balance Option-A
+ * verdict. Will be subsumed by canonical `useTransfers` once the
+ * `transfers.*` shape alignment lands. See `core/token-transfers.ts`
+ * doc-comment for the full contract.
+ *
+ * Intentionally NOT in `packages/sdk-react/ops/proof/hook-manifest.ts`
+ * — the canonical proof manifest tracks canon-aligned hooks only.
+ */
+declare function useTokenTransfers(filters?: TokenTransfersListInput): QueryResult<TokenTransfersListPage>;
 /**
  * Append-only per-owner balance-delta feed. Live for late
  * `paymentId` / `transferId` attachment per Doc 02.
@@ -470,4 +492,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 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, 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, 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 };