@capxul/sdk-react 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 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';
-export { AuthFlowContext, AuthFlowEvent, BrowserCapxulConfig, OnboardingFlowContext, OnboardingFlowEvent, ProvisioningFlowContext, ProvisioningFlowEvent } from '@capxul/sdk';
+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 { 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';
@@ -55,55 +56,64 @@ 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,
+ * 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.
  *
- * 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 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.
  *
- *    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`.
+     * 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 config?: CapxulConfig;
+    readonly config: BrowserCapxulConfig;
     /**
-     * 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.
+     * 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 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 sessionStore?: AuthSessionStore;
     /**
      * Optional TanStack Query `QueryClient`. Pass your app's existing
      * client to share the cache across the SDK hooks and the host
@@ -113,7 +123,7 @@ type CapxulProviderProps = {
     readonly queryClient?: QueryClient;
     readonly children: ReactNode;
 };
-declare function CapxulProvider({ config, publishableKey, browserConfig, queryClient, children, }: CapxulProviderProps): ReactNode;
+declare function CapxulProvider({ config, sessionStore, queryClient, children, }: CapxulProviderProps): ReactNode;
 
 /**
  * `QueryResult<T>` — the canonical three-state return shape for every
@@ -220,16 +230,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`.
@@ -237,12 +258,51 @@ 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>;
-declare function useSubAccount(_subAccountId: SubAccountId): QueryResult<SubAccount>;
+/**
+ * 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>;
+/**
+ * Funds v1 PR-2b (#421) — wired through `capxul.subAccounts.retrieve`.
+ *
+ * The top-level `subAccounts.retrieve` resolves to the same Convex
+ * query handler as `accounts.subAccounts.retrieve` /
+ * `organizations.subAccounts.retrieve`; visibility is gated server-side
+ * (canon §sub_account read contract — cross-scope reads surface as
+ * `NOT_FOUND` rather than a distinct permission code). The SDK has
+ * already branded the wire shape via `tryBrandSubAccount`, so the hook
+ * receives a fully-branded `SubAccount` (`SubAccountId`, `Money`,
+ * `TimestampIso`).
+ */
+declare function useSubAccount(subAccountId: SubAccountId): QueryResult<SubAccount>;
 declare function useVirtualAccount(_virtualAccountId: VirtualAccountId): QueryResult<VirtualAccount>;
 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".
@@ -333,8 +393,35 @@ 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>>;
-declare function useSubAccounts(_args: OwnerRef): QueryResult<List<SubAccount>>;
+/**
+ * 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>>;
+/**
+ * Funds v1 PR-2b (#421) — wired through the SDK.
+ *
+ * Branches on `args.ownerKind`: `account` scope reads through
+ * `capxul.accounts.subAccounts.list({ accountId })`; `organization`
+ * scope reads through `capxul.organizations.subAccounts.list({
+ * organizationId })`. Both resolve to the same Convex domain (server
+ * derives the writer scope per Pattern A — see `sdk.md`). The SDK
+ * has already branded each row via `tryBrandSubAccount`, so consumers
+ * receive `List<SubAccount>` with `SubAccountId`, `Money`, and
+ * `TimestampIso` in place.
+ *
+ * Note: `OwnerRef` admits only `"account" | "organization"`. A
+ * `sub_account` owner is a type error at the call site — not a runtime
+ * not-supported branch — because there is no `listChildSubAccounts`
+ * backend endpoint.
+ */
+declare function useSubAccounts(args: OwnerRef): QueryResult<List<SubAccount>>;
 declare function useVirtualAccounts(_filters?: VirtualAccountsFilters): QueryResult<List<VirtualAccount>>;
 declare function useVirtualCards(_filters?: VirtualCardsFilters): QueryResult<List<VirtualCard>>;
 /**
@@ -345,6 +432,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.
@@ -376,10 +474,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;
@@ -470,4 +664,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, 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 };