@capxul/sdk-react 0.1.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,473 @@
+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 { QueryClient, UseQueryResult } from '@tanstack/react-query';
+import { CapxulClient } from '@capxul/sdk/client';
+import { CapxulError } from '@capxul/sdk/errors';
+import * as xstate from 'xstate';
+
+type CapxulClientProviderProps = {
+    readonly client: CapxulClient;
+    readonly children: ReactNode;
+};
+declare function CapxulClientProvider({ client, children, }: CapxulClientProviderProps): ReactNode;
+/**
+ * Returns the `@capxul/sdk` client attached to the nearest provider.
+ *
+ * @throws `Error` if called outside a provider subtree. This is a
+ * developer error, not a `CapxulError`, because a missing provider
+ * cannot be recovered at runtime.
+ */
+declare function useCapxul(): CapxulClient;
+
+/**
+ * `CapxulTransportContext` — sibling context that exposes the
+ * `HttpTransport` lifecycle singleton built by the lazy-DX
+ * `CapxulProvider` path (ADR #14c).
+ *
+ * Separate from `CapxulClientContext` because the legacy `config`
+ * path doesn't build an externally-observable transport. When the
+ * provider runs the legacy path, this context's value stays `null`
+ * and `useCapxulStatus()` reports `"ready"` as a permissive default
+ * (the legacy path implies the host has already wired auth and data;
+ * there is nothing for the consumer to gate on).
+ */
+
+type CapxulTransportProviderProps = {
+    readonly transport: HttpTransport;
+    readonly children: ReactNode;
+};
+declare function CapxulTransportProvider({ transport, children, }: CapxulTransportProviderProps): ReactNode;
+/**
+ * Read the transport's current lifecycle state. Subscribes via
+ * `useSyncExternalStore` so the host re-renders only when the
+ * transport's state machine transitions, not when the provider tree
+ * re-renders. Returns the `TransportState` discriminated union with
+ * the contract-locked statuses:
+ * `"idle" | "bootstrapping" | "ready" | "authenticated" | "error"`.
+ *
+ * Outside a provider tree (or inside the legacy `config` path that
+ * does not build an externally-observable transport), the hook
+ * returns a synthetic `{ status: "ready" }` snapshot — the legacy
+ * path implies the host has already wired auth + data so there is
+ * nothing to gate on.
+ */
+declare function useCapxulStatus(): TransportState;
+
+/**
+ * `CapxulProvider` — React context provider that wires both the
+ * `@capxul/sdk` client AND a TanStack Query `QueryClient` for the
+ * subtree.
+ *
+ * Two construction paths:
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+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.
+     */
+    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;
+    /**
+     * Optional TanStack Query `QueryClient`. Pass your app's existing
+     * client to share the cache across the SDK hooks and the host
+     * app's own queries; omit to receive a default instance scoped to
+     * this provider with a 30s `staleTime`.
+     */
+    readonly queryClient?: QueryClient;
+    readonly children: ReactNode;
+};
+declare function CapxulProvider({ config, publishableKey, browserConfig, queryClient, children, }: CapxulProviderProps): ReactNode;
+
+/**
+ * `QueryResult<T>` — the canonical three-state return shape for every
+ * read hook in `@capxul/sdk-react`, locked per CANON.md §4.29 and
+ * reaffirmed by the ADR #14c lazy-DX contract (item 4).
+ *
+ * Three variants:
+ * - `loading` — no data yet; the subscription is in flight (matches
+ *   the contract's `"loading"` status)
+ * - `data`    — data is live; will update reactively on next tick
+ *   (the contract calls this `"ready"` colloquially — same semantics,
+ *   different name; the canon name is binding)
+ * - `error`   — terminal failure; `error.code` is a narrowed
+ *   `CapxulErrorCode` so consumers can route via `matchError`
+ *
+ * Hooks NEVER throw for a "still loading" condition — the lazy-DX
+ * contract collapses the multi-step lifecycle (not-bootstrapped,
+ * bootstrapping, no-session, no-data, live) into these three states.
+ * Consumers that want to surface the underlying transport state use
+ * `useCapxulStatus()` which returns the 5-state `TransportState`
+ * union.
+ *
+ * `useMe()` is the first live hook and maps the SDK tuple into this
+ * shape. Hooks whose verticals have not landed still use the
+ * `NOT_IMPLEMENTED` helper below.
+ */
+
+type QueryResult<T> = {
+    readonly status: "loading";
+} | {
+    readonly status: "data";
+    readonly data: T;
+} | {
+    readonly status: "error";
+    readonly error: CapxulError;
+};
+
+/**
+ * Per-resource singular read hooks — 21 total.
+ *
+ * Catalogued in the reset hook proof matrix. `useMe()` is the first
+ * hook migrated to TanStack Query (PLAN.md task 1.8); it returns
+ * `UseQueryResult<Account, CapxulError>` and routes through
+ * `@capxul/sdk` `me.get()` with query key `["capxul", "me"]` and a
+ * 30s `staleTime` matching the `CapxulProvider` default. The
+ * remaining 19 hooks plus `useOperation()` still return
+ * `QueryResult<T>` per the reset transport contract — per-hook
+ * migration is the rollout pattern; later tasks lift each in turn.
+ * `useOperation()` routes through `operations.retrieve()` so harness
+ * observers can read durable operation state.
+ *
+ * Argument shapes follow sdk-surface.md §3b:
+ * - Single-ID reads take the branded ID directly
+ * - Composite-key reads (member, api-key, external account,
+ *   balance-ledger entry) take an options object
+ * - Owner-scoped composite keys use a discriminated `OwnerRef`
+ */
+
+/**
+ * Discriminated owner reference for hooks whose resource can belong
+ * to either a personal account or an organization.
+ */
+type OwnerRef = {
+    readonly ownerKind: "account";
+    readonly ownerId: AccountId;
+} | {
+    readonly ownerKind: "organization";
+    readonly ownerId: OrganizationId;
+};
+type UseMemberArgs = {
+    readonly organizationId: OrganizationId;
+    readonly memberId: MemberId;
+};
+type UseApiKeyArgs = {
+    readonly organizationId: OrganizationId;
+    readonly apiKeyId: ApiKeyId;
+};
+type UseExternalAccountArgs = OwnerRef & {
+    readonly externalAccountId: ExternalAccountId;
+};
+type UseBalanceLedgerEntryArgs = OwnerRef & {
+    readonly entryId: BalanceLedgerEntryId;
+};
+/**
+ * The authenticated caller's identity (first-party only per §4.2).
+ *
+ * First hook migrated to TanStack Query per PLAN.md task 1.8.
+ * Cache key `[capxul.id, "capxul", "me"]`; `staleTime` of 30s
+ * matches the `CapxulProvider` default `QueryClient`. The query
+ * function maps the SDK tuple into TanStack's throw-on-error
+ * contract: a non-null `error` tuple slot is rethrown so TanStack
+ * surfaces it on the result, and a non-`CapxulError` thrown by the
+ * SDK transport is normalized to `CapxulError({ code: "UNKNOWN",
+ * cause })` so the `UseQueryResult` `error` channel is always typed
+ * `CapxulError`.
+ *
+ * The `capxul.id` leading segment isolates cache state across
+ * `CapxulClient` swaps. Without it, swapping the client inside the
+ * same `QueryClient` (e.g. after a sign-out / sign-in) would return
+ * the previous account's cached data for up to the 30s stale window.
+ * See Codex P1 finding on PR #406.
+ */
+declare function useMe(): UseQueryResult<Account, CapxulError$1>;
+/**
+ * Account by id. Omit `accountId` for the calling user (alias for
+ * `useMe()` from a developer-perspective lens).
+ */
+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`).
+ */
+declare function useSafe(_safeId: SafeId): QueryResult<Safe>;
+declare function useTreasury(_organizationId: OrganizationId): QueryResult<Treasury>;
+/**
+ * Org-admin lens only — the hook NEVER returns `secret`.
+ */
+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>;
+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>;
+/**
+ * Immutable once written; `live` semantically only for late
+ * `paymentId` / `transferId` attachment per Doc 02 §"balance_ledger".
+ */
+declare function useBalanceLedgerEntry(_args: UseBalanceLedgerEntryArgs): QueryResult<BalanceLedgerEntry>;
+declare function useDocument(_documentId: DocumentId): QueryResult<Document>;
+/**
+ * Withdrawals v1 slice 1 (#440) — wired through `capxul.withdrawals.retrieve`.
+ * Mirrors `useOperation` (the canonical evidence subscription) since
+ * the withdrawal resource is operation-shaped at its core.
+ */
+declare function useWithdrawal(withdrawalId: WithdrawalId): QueryResult<Withdrawal>;
+/**
+ * The canonical evidence subscription per CANON.md §3.3 —
+ * `operationId` + `correlationId` are the cross-layer join keys for
+ * debugging any mutation's end-to-end trail.
+ */
+declare function useOperation(operationId: OperationId): QueryResult<Operation>;
+/**
+ * Org-admin lens only — the hook NEVER returns `signingSecret`.
+ */
+declare function useWebhookEndpoint(_endpointId: WebhookEndpointId): QueryResult<WebhookEndpoint>;
+declare function useWebhookEvent(_eventId: WebhookEventId): QueryResult<WebhookEvent>;
+
+/**
+ * Per-resource list read hooks — 17 total.
+ *
+ * Catalogued in Doc 08 §3. Every hook returns
+ * `QueryResult<List<T>>` per CANON.md §4.29. Slice C.1 scaffold:
+ * every hook returns `NOT_IMPLEMENTED` until Slice F wires real
+ * Convex subscriptions.
+ *
+ * Argument shapes follow sdk-surface.md §3b:
+ * - Cursor-paginated lists take `{ limit?, cursor? }` filters per
+ *   §4.16 (cursor pagination convention)
+ * - Org-scoped lists take `organizationId` explicitly per §4.30
+ *   (Shape A — no ambient org context)
+ * - Owner-scoped lists use the discriminated `OwnerRef`
+ */
+
+/**
+ * Cursor-pagination filters shared by list hooks. Mirrors the input
+ * shape used by the vanilla SDK's `<domain>.list(...)` methods.
+ */
+type PaginationFilters = {
+    readonly limit?: number;
+    readonly cursor?: string;
+};
+type OptionalOwnerFilter = {
+    readonly ownerKind?: undefined;
+    readonly ownerId?: undefined;
+};
+type AccountOwnerFilter = {
+    readonly ownerKind: "account";
+    readonly ownerId: AccountId;
+};
+type SubAccountOwnerFilter = {
+    readonly ownerKind: "sub_account";
+    readonly ownerId: SubAccountId;
+};
+type OrganizationOwnerFilter = {
+    readonly ownerKind: "organization";
+    readonly ownerId: OrganizationId;
+};
+/**
+ * Filters for virtual-account listing. Narrows by owner when both
+ * `ownerKind` and `ownerId` are supplied; otherwise returns every
+ * virtual account the caller can see across their scope.
+ */
+type VirtualAccountsFilters = PaginationFilters & (OptionalOwnerFilter | AccountOwnerFilter | SubAccountOwnerFilter | OrganizationOwnerFilter);
+type VirtualCardsFilters = PaginationFilters & (OptionalOwnerFilter | AccountOwnerFilter | SubAccountOwnerFilter | OrganizationOwnerFilter);
+type DocumentsFilters = PaginationFilters & {
+    readonly type?: "invoice" | "payroll_run" | "payroll_schedule" | "receipt" | "kyc_upload" | "bank_statement" | "tax_form";
+};
+type TransfersFilters = PaginationFilters;
+type PaymentsFilters = PaginationFilters;
+type WithdrawalsFilters = PaginationFilters;
+type OwnerScopedFilters = OwnerRef & PaginationFilters;
+type OrgScopedFilters = {
+    readonly organizationId: OrganizationId;
+} & PaginationFilters;
+type OrgDocumentsFilters = OrgScopedFilters & {
+    readonly type?: DocumentsFilters["type"];
+};
+/**
+ * "My orgs" — returns every organization the authenticated caller
+ * is a member of, with the co-member lens per row.
+ */
+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>>;
+declare function useVirtualAccounts(_filters?: VirtualAccountsFilters): QueryResult<List<VirtualAccount>>;
+declare function useVirtualCards(_filters?: VirtualCardsFilters): QueryResult<List<VirtualCard>>;
+/**
+ * Personal-scope payments feed (cursor-paginated per §4.16). Org-scope
+ * payments live on `useOrgPayments` per §4.30 (Shape A).
+ */
+declare function usePayments(_filters?: PaymentsFilters): QueryResult<List<Payment>>;
+declare function useOrgPayments(_args: OrgScopedFilters): QueryResult<List<Payment>>;
+declare function useTransfers(_filters?: TransfersFilters): QueryResult<List<Transfer>>;
+declare function useOrgTransfers(_args: OrgScopedFilters): QueryResult<List<Transfer>>;
+/**
+ * Append-only per-owner balance-delta feed. Live for late
+ * `paymentId` / `transferId` attachment per Doc 02.
+ */
+declare function useBalanceLedger(_args: OwnerScopedFilters): QueryResult<List<BalanceLedgerEntry>>;
+/**
+ * Personal-scope documents. `filters.type` narrows the polymorphic
+ * `Document` union to a single variant (invoice, payroll_run,
+ * receipt, etc. per §4.50).
+ */
+declare function useDocuments(_filters?: DocumentsFilters): QueryResult<List<Document>>;
+declare function useOrgDocuments(_args: OrgDocumentsFilters): QueryResult<List<Document>>;
+/**
+ * Withdrawals v1 slice 1 (#440) — wired through `capxul.withdrawals.list`.
+ */
+declare function useWithdrawals(filters?: WithdrawalsFilters): QueryResult<List<Withdrawal>>;
+/**
+ * Withdrawals v1 slice 1 (#440) — wired through
+ * `capxul.organizations.withdrawals.list`.
+ */
+declare function useOrgWithdrawals(args: OrgScopedFilters): QueryResult<List<Withdrawal>>;
+/**
+ * Org-admin lens only — the hook NEVER returns `secret` for any row.
+ */
+declare function useApiKeys(_organizationId: OrganizationId): QueryResult<List<ApiKey>>;
+/**
+ * Org-admin / service-key lens — org scope is inferred from the
+ * api-key claim, so no `organizationId` argument is needed.
+ */
+declare function useWebhookEndpoints(): QueryResult<List<WebhookEndpoint>>;
+
+declare function useAuthFlow(): {
+    readonly snapshot: xstate.MachineSnapshot<any, any, any, any, any, any, any, any>;
+    readonly send: (event: any) => void;
+};
+declare function useOnboardingFlow(): {
+    readonly snapshot: xstate.MachineSnapshot<any, any, any, any, any, any, any, any>;
+    readonly send: (event: any) => void;
+};
+declare function useProvisioningFlow(): {
+    readonly snapshot: xstate.MachineSnapshot<any, any, any, any, any, any, any, any>;
+    readonly send: (event: any) => void;
+};
+
+/**
+ * Browser-side Capxul SDK config — public ergonomics for `@capxul/sdk-react`
+ * consumers.
+ *
+ * The canonical type lives in `@capxul/sdk` (`transport.ts`); this file
+ * re-exports it so consumers can `import { BrowserCapxulConfig,
+ * createCapxulConfig } from "@capxul/sdk-react"` without crossing the
+ * package boundary themselves. The `BrowserCapxulConfig` discriminated
+ * union stays single-source-of-truth in `@capxul/sdk` so Stack 2 can
+ * extend it in-place when the `publishable-key` arm lands.
+ *
+ * `createCapxulConfig` is a runtime validator + freezer. It rejects
+ * secret/server-only fields (apiKey, data, signer, ...) per ADR 5 and
+ * PR #393's `assertBrowserCapxulConfig` precedent, but every error is
+ * a typed `CapxulError` produced by `Errors.invalidInput()` — never a
+ * raw `new Error(...)` (per `.claude/rules/error-handling.md`).
+ */
+
+/**
+ * Validate + freeze a `BrowserCapxulConfig`. The returned value is the
+ * same input object frozen via `Object.freeze` so callers cannot mutate
+ * it after handoff.
+ *
+ * Throws `Errors.invalidInput(...)` on:
+ *  - any unknown key (rejects `apiKey`, `data`, `signer`, `fetch`, typos,
+ *    Stack-2 server-only additions — the allow-list approach is
+ *    secret-safe by default)
+ *  - missing required field for the active `mode` arm
+ *  - an unknown `mode` value (exhaustive guard via `Errors.internalError`)
+ */
+declare function createCapxulConfig(input: BrowserCapxulConfig): BrowserCapxulConfig;
+
+type CapxulConnectorKind = "injected" | "local-private-key";
+type CapxulConnectorSession = {
+    readonly connectorId: string;
+    readonly connectorKind: CapxulConnectorKind;
+    readonly signerAddress: string;
+    readonly safeAddress?: string;
+    readonly signerProvider?: LocalPrivateKeySignerProvider;
+};
+type CapxulConnector = {
+    readonly id: string;
+    readonly name: string;
+    readonly kind: CapxulConnectorKind;
+    readonly autoConnect?: boolean;
+    connect(): Promise<CapxulConnectorSession>;
+    disconnect?(): Promise<void>;
+};
+type InjectedConnectorOptions = {
+    readonly id?: string;
+    readonly name?: string;
+};
+type LocalPrivateKeyConnectorOptions = {
+    readonly privateKey: `0x${string}`;
+    readonly safeAddress: string;
+    readonly id?: string;
+    readonly name?: string;
+};
+/**
+ * Resolve a signer through an injected EIP-1193 provider (e.g.
+ * MetaMask via `window.ethereum`).
+ *
+ * Throws `Errors.providerError("connector", "injected", cause)` on
+ * provider absence or empty `eth_requestAccounts` response. Provider
+ * rejections (user closed the prompt) bubble up unchanged so callers
+ * can map them per UX requirements.
+ */
+declare function injectedConnector(options?: InjectedConnectorOptions): CapxulConnector;
+/**
+ * Resolve a signer from a local private key (dev / e2e harness path).
+ *
+ * Validates the private key shape (`0x` + 64 hex chars) and the
+ * required `safeAddress` synchronously at factory time so misconfig
+ * surfaces before any UI flow advances. Per-call `connect()` is pure
+ * computation — `privateKeyToAccount` derives the address from the
+ * key with no I/O.
+ *
+ * Throws `Errors.invalidInput(...)` on bad inputs.
+ */
+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 };