@capxul/sdk-react 0.1.0-alpha.9 → 0.2.0-alpha.3

package/dist/index.d.cts

@@ -1,10 +1,11 @@
 import { ReactNode } from 'react';
 import * as _capxul_sdk from '@capxul/sdk';
-import { HttpTransport, TransportState, BrowserCapxulConfig, AuthSessionStore, AccountId, OrganizationId, ApiKeyId, BalanceLedgerEntryId, ExternalAccountId, MemberId, Account, ApiKey, BalanceLedgerEntry, DocumentId, Document, ExternalAccount, KybProfile, KycProfile, CapxulError as CapxulError$1, Member, OperationId, Operation, Organization, PaymentId, Payment, SafeId, Safe, SubAccountId, SubAccount, TokenTransfer, TransferId, Transfer, Treasury, VirtualAccountId, VirtualAccount, VirtualCardId, VirtualCard, WebhookEndpointId, WebhookEndpoint, WebhookEventId, WebhookEvent, WithdrawalId, Withdrawal, List, TokenTransfersListInput, TokenTransfersListPage, LocalPrivateKeySignerProvider } from '@capxul/sdk';
+import { HttpTransport, TransportState, BrowserCapxulConfig, AuthSessionStore, AccountId, OrganizationId, ApiKeyId, BalanceLedgerEntryId, ExternalAccountId, MemberId, Account, ApiKey, BalanceLedgerEntry, DocumentId, Document, ExternalAccount, 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, MembershipStatus, TokenTransfersListInput, TokenTransfersListPage, MemberInviteResponse, Session } from '@capxul/sdk';
 export { AuthBootstrapFlowContext, AuthBootstrapFlowEvent, AuthFlowContext, AuthFlowEvent, BrowserCapxulConfig, OnboardingFlowContext, OnboardingFlowEvent, ProvisioningFlowContext, ProvisioningFlowEvent } from '@capxul/sdk';
-import { QueryClient, UseQueryResult } from '@tanstack/react-query';
+import { QueryClient, UseQueryResult, UseMutationResult } from '@tanstack/react-query';
 import { CapxulClient } from '@capxul/sdk/client';
 import { CapxulError } from '@capxul/sdk/errors';
+import { Account as Account$1 } from 'viem';
 import * as xstate from 'xstate';
 
 type CapxulClientProviderProps = {
@@ -71,7 +72,7 @@ declare function useCapxulStatus(): TransportState;
  * `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
+ * 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
@@ -164,12 +165,10 @@ type QueryResult<T> = {
 /**
  * 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
+ * Catalogued in the reset hook proof matrix. TanStack Query-backed
+ * hooks return `UseQueryResult<T, CapxulError>` and route through
+ * public `@capxul/sdk` reads with a 30s `staleTime` matching the
+ * `CapxulProvider` default. Hooks not yet migrated 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
@@ -238,8 +237,8 @@ declare function useMe(): UseQueryResult<Account, CapxulError$1>;
  * 1.8) — per-hook migration is the rollout pattern.
  */
 declare function useAccount(accountId?: AccountId): QueryResult<Account>;
-declare function useOrganization(_organizationId: OrganizationId): QueryResult<Organization>;
-declare function useMember(_args: UseMemberArgs): QueryResult<Member>;
+declare function useOrganization(organizationId: OrganizationId): UseQueryResult<Organization, CapxulError$1>;
+declare function useMember(args: UseMemberArgs): UseQueryResult<Member, CapxulError$1>;
 /**
  * Live; status advances as the indexer reconciles the on-chain
  * deployment. Consumers pattern-match on `data.status` via
@@ -251,13 +250,12 @@ declare function useMember(_args: UseMemberArgs): QueryResult<Member>;
  * stub so onboarding can subscribe to Safe deploy progress.
  */
 declare function useSafe(safeId: SafeId): QueryResult<Safe>;
-declare function useTreasury(_organizationId: OrganizationId): QueryResult<Treasury>;
+declare function useTreasury(organizationId: OrganizationId): UseQueryResult<Treasury, CapxulError$1>;
 /**
  * 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>;
 /**
  * Withdrawals v1 W1 (#464) — wired through the SDK.
  *
@@ -270,10 +268,22 @@ declare function useKybProfile(_organizationId: OrganizationId): QueryResult<Kyb
  * differ but the wire shape is identical.
  */
 declare function useExternalAccount(args: UseExternalAccountArgs): QueryResult<ExternalAccount>;
-declare function useSubAccount(_subAccountId: SubAccountId): QueryResult<SubAccount>;
+/**
+ * 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 usePayment(paymentId: PaymentId): UseQueryResult<Payment, CapxulError$1>;
 declare function useTransfer(_transferId: TransferId): QueryResult<Transfer>;
 type UseTokenTransferArgs = {
     readonly txHash: string;
@@ -295,7 +305,7 @@ declare function useTokenTransfer(args: UseTokenTransferArgs): QueryResult<Token
  * 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 useBalanceLedgerEntry(args: UseBalanceLedgerEntryArgs): QueryResult<BalanceLedgerEntry>;
 declare function useDocument(_documentId: DocumentId): QueryResult<Document>;
 /**
  * Withdrawals v1 slice 1 (#440) — wired through `capxul.withdrawals.retrieve`.
@@ -318,10 +328,10 @@ declare function useWebhookEvent(_eventId: WebhookEventId): QueryResult<WebhookE
 /**
  * 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.
+ * Catalogued in Doc 08 §3. TanStack Query-backed hooks return
+ * `UseQueryResult<List<T>, CapxulError>` and route through public
+ * `@capxul/sdk` reads. Hooks not yet migrated still return
+ * `QueryResult<List<T>>` per CANON.md §4.29.
  *
  * Argument shapes follow sdk-surface.md §3b:
  * - Cursor-paginated lists take `{ limit?, cursor? }` filters per
@@ -379,8 +389,11 @@ type OrgDocumentsFilters = OrgScopedFilters & {
  * "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 useOrganizations(filters?: PaginationFilters): UseQueryResult<List<Organization>, CapxulError$1>;
+type MembersFilters = {
+    readonly status?: MembershipStatus | "all";
+};
+declare function useMembers(organizationId: OrganizationId, filters?: MembersFilters): UseQueryResult<List<Member>, CapxulError$1>;
 /**
  * Withdrawals v1 W1 (#464) — wired through the SDK.
  *
@@ -392,14 +405,31 @@ declare function useMembers(_organizationId: OrganizationId): QueryResult<List<M
  * `pending_verification` rows visible (D5).
  */
 declare function useExternalAccounts(args: OwnerRef): QueryResult<List<ExternalAccount>>;
-declare function useSubAccounts(_args: OwnerRef): QueryResult<List<SubAccount>>;
+/**
+ * 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>>;
 /**
  * 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 usePayments(filters?: PaymentsFilters): UseQueryResult<List<Payment>, CapxulError$1>;
 declare function useOrgPayments(_args: OrgScopedFilters): QueryResult<List<Payment>>;
 declare function useTransfers(_filters?: TransfersFilters): QueryResult<List<Transfer>>;
 declare function useOrgTransfers(_args: OrgScopedFilters): QueryResult<List<Transfer>>;
@@ -418,7 +448,9 @@ declare function useTokenTransfers(filters?: TokenTransfersListInput): QueryResu
  * Append-only per-owner balance-delta feed. Live for late
  * `paymentId` / `transferId` attachment per Doc 02.
  */
-declare function useBalanceLedger(_args: OwnerScopedFilters): QueryResult<List<BalanceLedgerEntry>>;
+declare function useBalanceLedger(args: OwnerScopedFilters): QueryResult<List<BalanceLedgerEntry>>;
+declare function useAccountBalanceLedger(accountId: AccountId, filters?: PaginationFilters): QueryResult<List<BalanceLedgerEntry>>;
+declare function useOrgBalanceLedger(args: OrgScopedFilters): QueryResult<List<BalanceLedgerEntry>>;
 /**
  * Personal-scope documents. `filters.type` narrows the polymorphic
  * `Document` union to a single variant (invoice, payroll_run,
@@ -445,6 +477,46 @@ declare function useApiKeys(_organizationId: OrganizationId): QueryResult<List<A
  */
 declare function useWebhookEndpoints(): QueryResult<List<WebhookEndpoint>>;
 
+/**
+ * Org-scoped member mutation hooks — TanStack `useMutation` wrappers.
+ *
+ * Slice 5 (#627): invite, accept, updateRole, revoke, remove, resend.
+ * Each hook returns the standard `{ mutate, mutateAsync, isPending, error, data }`
+ * shape so consumers can fire-and-forget or await + handle errors.
+ */
+
+type InviteMemberArgs = {
+    readonly organizationId: OrganizationId;
+    readonly email: string;
+    readonly role: Member["role"];
+};
+type AcceptInvitationArgs = {
+    readonly token: string;
+};
+type UpdateMemberRoleArgs = {
+    readonly organizationId: OrganizationId;
+    readonly memberId: MemberId;
+    readonly role: Member["role"];
+};
+type RevokeMemberArgs = {
+    readonly organizationId: OrganizationId;
+    readonly memberId: MemberId;
+};
+type RemoveMemberArgs = {
+    readonly organizationId: OrganizationId;
+    readonly memberId: MemberId;
+};
+type ResendInvitationArgs = {
+    readonly organizationId: OrganizationId;
+    readonly memberId: MemberId;
+};
+declare function useInviteMember(): UseMutationResult<MemberInviteResponse, CapxulError$1, InviteMemberArgs>;
+declare function useAcceptInvitation(): UseMutationResult<Member, CapxulError$1, AcceptInvitationArgs>;
+declare function useUpdateMemberRole(): UseMutationResult<Member, CapxulError$1, UpdateMemberRoleArgs>;
+declare function useRevokeMember(): UseMutationResult<Member, CapxulError$1, RevokeMemberArgs>;
+declare function useRemoveMember(): UseMutationResult<void, CapxulError$1, RemoveMemberArgs>;
+declare function useResendInvitation(): UseMutationResult<MemberInviteResponse, CapxulError$1, ResendInvitationArgs>;
+
 /**
  * Lowercased, shape-validated email address. Brand prevents swapping
  * with `phoneNumber`, `username`, or other string identifiers (per
@@ -465,10 +537,51 @@ type Username = string & {
     readonly __capxulUsernameBrand: "Username";
 };
 
+type User = {
+    readonly account: Account;
+    readonly username: Username;
+    readonly safe: Safe;
+    readonly session: Session;
+};
+type AuthState = "idle" | "sendingOtp" | "awaitingOtp" | "bootstrapping" | "authenticated" | "error";
+type UseAuthResult = {
+    readonly state: AuthState;
+    readonly user: User | null;
+    readonly error: Error | null;
+    readonly signIn: (email: string) => Promise<void>;
+    readonly verifyOtp: (email: string, otp: string) => Promise<Session>;
+    readonly signOut: () => Promise<void>;
+};
+type UseAuthOptions = {
+    /** Optional external signer to use during bootstrap instead of auto-provisioning. */
+    readonly signer?: Account$1;
+};
+/**
+ * Canonical auth hook — replaces `useAuthFlow` and `useAuthBootstrapFlow`.
+ *
+ * Reactive state (`state`, `user`, `error`) is suitable for UI
+ * observers; `signIn`, `verifyOtp`, and `signOut` return promises so
+ * the reference CLI can drive the flow imperatively.
+ *
+ * Auto-provisions a fresh local-private-key signer via
+ * `SignerProvisioner` when the backend signals `bootstrap_required`.
+ * Pass an optional `signer` to override auto-provisioning (used by
+ * test harnesses that pre-build a deterministic actor).
+ */
+declare function useAuth(options?: UseAuthOptions): UseAuthResult;
+
+/**
+ * @deprecated Use `useAuth()` instead. `useAuthFlow` will be removed
+ * in a future release.
+ */
 declare function useAuthFlow(): {
     readonly snapshot: xstate.MachineSnapshot<any, any, any, any, any, any, any, any>;
     readonly send: (event: any) => void;
 };
+/**
+ * @deprecated Use `useAuth()` instead. `useAuthBootstrapFlow` will be
+ * removed in a future release.
+ */
 declare function useAuthBootstrapFlow(): {
     readonly snapshot: xstate.MachineSnapshot<_capxul_sdk.AuthBootstrapFlowContext, {
         readonly type: "ENTER_EMAIL";
@@ -483,9 +596,6 @@ declare function useAuthBootstrapFlow(): {
     } | {
         readonly type: "ENTER_USERNAME";
         readonly username: Username;
-    } | {
-        readonly type: "ENTER_SIGNER_PROVIDER";
-        readonly signerProvider: _capxul_sdk.LocalPrivateKeySignerProvider;
     } | {
         readonly type: "COMPLETE_BOOTSTRAP";
     } | {
@@ -498,7 +608,6 @@ declare function useAuthBootstrapFlow(): {
         [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, {
@@ -532,9 +641,6 @@ declare function useAuthBootstrapFlow(): {
     } | {
         readonly type: "ENTER_USERNAME";
         readonly username: Username;
-    } | {
-        readonly type: "ENTER_SIGNER_PROVIDER";
-        readonly signerProvider: _capxul_sdk.LocalPrivateKeySignerProvider;
     } | {
         readonly type: "COMPLETE_BOOTSTRAP";
     } | {
@@ -591,8 +697,6 @@ type CapxulConnectorSession = {
     readonly connectorId: string;
     readonly connectorKind: CapxulConnectorKind;
     readonly signerAddress: string;
-    readonly safeAddress?: string;
-    readonly signerProvider?: LocalPrivateKeySignerProvider;
 };
 type CapxulConnector = {
     readonly id: string;
@@ -608,7 +712,6 @@ type InjectedConnectorOptions = {
 };
 type LocalPrivateKeyConnectorOptions = {
     readonly privateKey: `0x${string}`;
-    readonly safeAddress: string;
     readonly id?: string;
     readonly name?: string;
 };
@@ -625,14 +728,13 @@ declare function injectedConnector(options?: InjectedConnectorOptions): CapxulCo
 /**
  * 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.
+ * Validates the private key shape (`0x` + 64 hex chars) 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 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 };
+export { type AuthState, 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 UseAuthOptions, type UseAuthResult, type UseBalanceLedgerEntryArgs, type UseExternalAccountArgs, type UseMemberArgs, type UseTokenTransferArgs, type User, type VirtualAccountsFilters, type VirtualCardsFilters, type WithdrawalsFilters, createCapxulConfig, injectedConnector, localPrivateKeyConnector, useAcceptInvitation, useAccount, useAccountBalanceLedger, useApiKey, useApiKeys, useAuth, useAuthBootstrapFlow, useAuthFlow, useBalanceLedger, useBalanceLedgerEntry, useCapxul, useCapxulStatus, useDocument, useDocuments, useExternalAccount, useExternalAccounts, useInviteMember, useKycProfile, useMe, useMember, useMembers, useOnboardingFlow, useOperation, useOrgBalanceLedger, useOrgDocuments, useOrgPayments, useOrgTransfers, useOrgWithdrawals, useOrganization, useOrganizations, usePayment, usePayments, useProvisioningFlow, useRemoveMember, useResendInvitation, useRevokeMember, useSafe, useSubAccount, useSubAccounts, useTokenTransfer, useTokenTransfers, useTransfer, useTransfers, useTreasury, useUpdateMemberRole, useVirtualAccount, useVirtualAccounts, useVirtualCard, useVirtualCards, useWebhookEndpoint, useWebhookEndpoints, useWebhookEvent, useWithdrawal, useWithdrawals };