@satoshai/kit 0.7.0 → 0.8.1

package/dist/index.d.ts

@@ -3,53 +3,93 @@ import { ClarityValue, TupleCV, PostCondition, PostConditionMode } from '@stacks
 import { ClarityAbi, ExtractAbiFunctionNames, Pretty, ExtractAbiFunction, ClarityAbiArgToPrimitiveTypeValue } from 'clarity-abitype';
 export { ClarityAbi } from 'clarity-abitype';
 
+/** Discriminated type for narrowing caught errors to `BaseError`. */
 type BaseErrorType = BaseError & {
     name: 'StacksKitError';
 };
+/**
+ * Base error class for all `@satoshai/kit` errors.
+ *
+ * All errors thrown by hooks extend this class, so you can catch them with
+ * `error instanceof BaseError` and use {@link BaseError.walk | walk()} to
+ * traverse the cause chain.
+ *
+ * @example
+ * ```ts
+ * import { BaseError } from '@satoshai/kit';
+ *
+ * try {
+ *   await signMessageAsync({ message: 'hello' });
+ * } catch (err) {
+ *   if (err instanceof BaseError) {
+ *     console.log(err.shortMessage); // human-readable summary
+ *     console.log(err.walk());       // root cause
+ *   }
+ * }
+ * ```
+ */
 declare class BaseError extends Error {
     name: string;
+    /** Short, human-readable error summary without details or cause chain. */
     shortMessage: string;
     constructor(shortMessage: string, options?: {
         cause?: Error;
         details?: string;
     });
+    /**
+     * Walk the error cause chain. If `fn` is provided, returns the first error
+     * where `fn` returns `true`; otherwise returns the root cause.
+     */
     walk(fn?: (err: unknown) => boolean): unknown;
 }
+/** Discriminated type for narrowing to `WalletNotConnectedError`. */
 type WalletNotConnectedErrorType = WalletNotConnectedError & {
     name: 'WalletNotConnectedError';
 };
+/** Thrown when a mutation hook is called before a wallet is connected. */
 declare class WalletNotConnectedError extends BaseError {
     name: string;
     constructor();
 }
+/** Discriminated type for narrowing to `WalletNotFoundError`. */
 type WalletNotFoundErrorType = WalletNotFoundError & {
     name: 'WalletNotFoundError';
 };
+/** Thrown when a wallet's browser extension is not installed (e.g. OKX). */
 declare class WalletNotFoundError extends BaseError {
     name: string;
+    /** The wallet ID that was not found. */
     wallet: string;
     constructor({ wallet }: {
         wallet: string;
     });
 }
+/** Discriminated type for narrowing to `UnsupportedMethodError`. */
 type UnsupportedMethodErrorType = UnsupportedMethodError & {
     name: 'UnsupportedMethodError';
 };
+/** Thrown when a wallet does not support the requested RPC method (e.g. OKX + `stx_signStructuredMessage`). */
 declare class UnsupportedMethodError extends BaseError {
     name: string;
+    /** The SIP-030 method name that is not supported. */
     method: string;
+    /** The wallet that does not support the method. */
     wallet: string;
     constructor({ method, wallet }: {
         method: string;
         wallet: string;
     });
 }
+/** Discriminated type for narrowing to `WalletRequestError`. */
 type WalletRequestErrorType = WalletRequestError & {
     name: 'WalletRequestError';
 };
+/** Thrown when a wallet RPC request fails (user rejection, timeout, etc.). The original error is attached as `cause`. */
 declare class WalletRequestError extends BaseError {
     name: string;
+    /** The SIP-030 method name that failed. */
     method: string;
+    /** The wallet that returned the error. */
     wallet: string;
     constructor({ method, wallet, cause }: {
         method: string;
@@ -58,35 +98,68 @@ declare class WalletRequestError extends BaseError {
     });
 }
 
+/** All wallet IDs supported by `@satoshai/kit`. */
 declare const SUPPORTED_STACKS_WALLETS: readonly ["xverse", "leather", "asigna", "fordefi", "wallet-connect", "okx"];
+/** Union of supported wallet identifiers. */
 type SupportedStacksWallet = (typeof SUPPORTED_STACKS_WALLETS)[number];
 
+/** Stacks network identifier. */
 type StacksChain = 'mainnet' | 'testnet';
+/** Status of a mutation hook (`useConnect`, `useSignMessage`, etc.). */
 type MutationStatus = 'idle' | 'pending' | 'error' | 'success';
+/** Metadata passed to the WalletConnect relay for dApp identification. */
 interface WalletConnectMetadata {
     name: string;
     description: string;
     url: string;
     icons: string[];
 }
+/** Optional callbacks for {@link useConnect}. */
 interface ConnectOptions {
+    /** Called with the connected address and wallet ID on success. */
     onSuccess?: (address: string, provider: SupportedStacksWallet) => void;
+    /** Called when the connection fails or is rejected. */
     onError?: (error: Error) => void;
 }
+/** Props for the {@link StacksWalletProvider} component. */
 interface StacksWalletProviderProps {
     children: React.ReactNode;
+    /**
+     * Wallets to enable. Defaults to all supported wallets.
+     *
+     * **Tip:** Define this array outside your component or memoize it to keep
+     * the reference stable across renders.
+     */
     wallets?: SupportedStacksWallet[];
     /** Show @stacks/connect's built-in wallet selection modal when `connect()` is called without a `providerId`. Defaults to `true`. Set to `false` to manage wallet selection yourself (headless). */
     connectModal?: boolean;
+    /**
+     * WalletConnect configuration. Required when `wallets` includes `'wallet-connect'`.
+     *
+     * **Tip:** Define this object outside your component or memoize it to keep
+     * the reference stable across renders.
+     */
     walletConnect?: {
+        /** WalletConnect Cloud project ID from https://cloud.walletconnect.com. */
         projectId: string;
+        /** Override default dApp metadata shown in the wallet. */
         metadata?: Partial<WalletConnectMetadata>;
+        /** Stacks chains to request. Defaults to `['mainnet']`. */
         chains?: StacksChain[];
     };
+    /** Called after a wallet successfully connects. */
     onConnect?: (provider: SupportedStacksWallet, address: string) => void;
+    /** Called when the connected account changes (e.g. Xverse account switch, WalletConnect account change). */
     onAddressChange?: (newAddress: string) => void;
+    /** Called when the wallet disconnects (user-initiated or session expiry). */
     onDisconnect?: () => void;
 }
+/**
+ * Discriminated union representing the wallet connection state.
+ *
+ * When `status` is `'connected'`, `address` and `provider` are guaranteed
+ * to be defined.
+ */
 type WalletState = {
     status: 'disconnected';
     address: undefined;
@@ -100,20 +173,54 @@ type WalletState = {
     address: string;
     provider: SupportedStacksWallet;
 };
+/** Metadata for a single wallet returned by {@link useWallets}. */
 interface WalletInfo {
+    /** Wallet identifier used with `connect(id)`. */
     id: SupportedStacksWallet;
+    /** Human-readable wallet name. */
     name: string;
+    /** Wallet icon as a data URI. */
     icon: string;
+    /** URL to download/install the wallet extension. */
     webUrl: string;
+    /** `true` when the wallet extension is detected or WalletConnect is configured. */
     available: boolean;
 }
+/** Full context value exposed by `StacksWalletProvider`. Extends {@link WalletState} with actions and wallet list. */
 type WalletContextValue = WalletState & {
+    /** Connect to a wallet. Pass a wallet ID to bypass the modal, or call with no args to show the `@stacks/connect` modal. */
     connect: (providerId?: SupportedStacksWallet, options?: ConnectOptions) => Promise<void>;
+    /** Disconnect the current wallet and clear persisted state. */
     disconnect: (callback?: () => void) => void;
+    /** Reset a stuck connecting state back to idle. */
     reset: () => void;
+    /** All configured wallets with availability status. */
     wallets: WalletInfo[];
 };
 
+/**
+ * React context provider that manages wallet connection state for all `@satoshai/kit` hooks.
+ *
+ * Wrap your app (or the subtree that needs wallet access) with this provider.
+ * All hooks (`useConnect`, `useAddress`, `useWriteContract`, etc.) must be
+ * rendered inside this provider.
+ *
+ * @example
+ * ```tsx
+ * import { StacksWalletProvider } from '@satoshai/kit';
+ *
+ * const wallets = ['xverse', 'leather', 'wallet-connect'] as const;
+ * const wc = { projectId: 'YOUR_PROJECT_ID' };
+ *
+ * function App() {
+ *   return (
+ *     <StacksWalletProvider wallets={[...wallets]} walletConnect={wc}>
+ *       <YourApp />
+ *     </StacksWalletProvider>
+ *   );
+ * }
+ * ```
+ */
 declare const StacksWalletProvider: ({ children, wallets, connectModal, walletConnect, onConnect, onAddressChange, onDisconnect, }: StacksWalletProviderProps) => react_jsx_runtime.JSX.Element;
 
 type UseAddressReturn = {
@@ -129,8 +236,48 @@ type UseAddressReturn = {
     isDisconnected: false;
     provider: SupportedStacksWallet;
 };
+/**
+ * Read the connected wallet's address and connection status.
+ *
+ * Returns a discriminated union — when `isConnected` is `true`, `address`
+ * and `provider` are guaranteed to be defined (no null checks needed).
+ *
+ * @example
+ * ```ts
+ * const { address, isConnected, provider } = useAddress();
+ *
+ * if (isConnected) {
+ *   console.log(address);  // 'SP...' — narrowed to string
+ *   console.log(provider); // 'xverse' | 'leather' | ...
+ * }
+ * ```
+ */
 declare const useAddress: () => UseAddressReturn;
 
+/**
+ * Connect to a Stacks wallet.
+ *
+ * Returns a mutation-style object with `connect`, `reset`, and status flags.
+ * Call `connect()` with no args to open the `@stacks/connect` wallet modal,
+ * or pass a specific wallet ID (e.g. `connect('xverse')`) to connect directly.
+ *
+ * @example
+ * ```ts
+ * const { connect, reset, isPending, isSuccess, error } = useConnect();
+ *
+ * // Modal mode (default)
+ * await connect();
+ *
+ * // Direct mode
+ * await connect('leather', {
+ *   onSuccess: (address, provider) => console.log(address),
+ *   onError: (err) => console.error(err),
+ * });
+ *
+ * // Cancel a stuck connection (e.g. OKX popup dismissed)
+ * reset();
+ * ```
+ */
 declare const useConnect: () => {
     connect: (providerId?: SupportedStacksWallet, options?: ConnectOptions) => Promise<void>;
     reset: () => void;
@@ -142,6 +289,20 @@ declare const useConnect: () => {
     status: MutationStatus;
 };
 
+/**
+ * Disconnect the currently connected wallet.
+ *
+ * Clears wallet state, removes the persisted session from localStorage,
+ * and resets the provider context back to `disconnected`.
+ *
+ * @example
+ * ```ts
+ * const { disconnect, isSuccess } = useDisconnect();
+ *
+ * disconnect();
+ * disconnect(() => navigate('/'));
+ * ```
+ */
 declare const useDisconnect: () => {
     disconnect: (callback?: () => void) => void;
     reset: () => void;
@@ -153,19 +314,45 @@ declare const useDisconnect: () => {
     status: MutationStatus;
 };
 
+/** Variables for {@link useSignMessage}. */
 interface SignMessageVariables {
+    /** The plaintext message to sign. */
     message: string;
+    /** Optional public key hint for wallets that manage multiple keys. */
     publicKey?: string;
 }
+/** Successful result from {@link useSignMessage}. */
 interface SignMessageData {
+    /** The public key that produced the signature. */
     publicKey: string;
+    /** The hex-encoded signature. */
     signature: string;
 }
+/** Callback options for the fire-and-forget `signMessage()` variant. */
 interface SignMessageOptions {
     onSuccess?: (data: SignMessageData) => void;
     onError?: (error: Error) => void;
     onSettled?: (data: SignMessageData | undefined, error: Error | null) => void;
 }
+/**
+ * Sign an arbitrary plaintext message with the connected wallet.
+ *
+ * Provides both a callback-style `signMessage()` and a promise-based
+ * `signMessageAsync()`, plus mutation status flags.
+ *
+ * @example
+ * ```ts
+ * const { signMessageAsync, isPending } = useSignMessage();
+ *
+ * const { publicKey, signature } = await signMessageAsync({
+ *   message: 'Hello Stacks',
+ * });
+ * ```
+ *
+ * @throws {WalletNotConnectedError} If no wallet is connected.
+ * @throws {WalletNotFoundError} If OKX extension is not installed.
+ * @throws {WalletRequestError} If the wallet rejects or fails the request.
+ */
 declare const useSignMessage: () => {
     signMessage: (variables: SignMessageVariables, options?: SignMessageOptions) => void;
     signMessageAsync: (variables: SignMessageVariables) => Promise<SignMessageData>;
@@ -179,19 +366,46 @@ declare const useSignMessage: () => {
     status: MutationStatus;
 };
 
+/** Variables for {@link useSignStructuredMessage}. */
 interface SignStructuredMessageVariables {
+    /** The structured Clarity value to sign. */
     message: ClarityValue;
+    /** SIP-018 domain tuple (name, version, chain-id). */
     domain: TupleCV;
 }
+/** Successful result from {@link useSignStructuredMessage}. */
 interface SignStructuredMessageData {
     publicKey: string;
     signature: string;
 }
+/** Callback options for the fire-and-forget `signStructuredMessage()` variant. */
 interface SignStructuredMessageOptions {
     onSuccess?: (data: SignStructuredMessageData) => void;
     onError?: (error: Error) => void;
     onSettled?: (data: SignStructuredMessageData | undefined, error: Error | null) => void;
 }
+/**
+ * Sign SIP-018 structured data with the connected wallet.
+ *
+ * Structured messages include a typed domain separator and a Clarity value
+ * body, enabling verifiable off-chain signatures that are replay-safe.
+ *
+ * @example
+ * ```ts
+ * import { tupleCV, stringAsciiCV, uintCV } from '@stacks/transactions';
+ *
+ * const { signStructuredMessageAsync } = useSignStructuredMessage();
+ *
+ * const { signature } = await signStructuredMessageAsync({
+ *   domain: tupleCV({ name: stringAsciiCV('MyApp'), version: stringAsciiCV('1.0'), 'chain-id': uintCV(1) }),
+ *   message: tupleCV({ action: stringAsciiCV('authorize') }),
+ * });
+ * ```
+ *
+ * @throws {WalletNotConnectedError} If no wallet is connected.
+ * @throws {UnsupportedMethodError} If the wallet does not support structured signing (OKX).
+ * @throws {WalletRequestError} If the wallet rejects or fails the request.
+ */
 declare const useSignStructuredMessage: () => {
     signStructuredMessage: (variables: SignStructuredMessageVariables, options?: SignStructuredMessageOptions) => void;
     signStructuredMessageAsync: (variables: SignStructuredMessageVariables) => Promise<SignStructuredMessageData>;
@@ -205,19 +419,46 @@ declare const useSignStructuredMessage: () => {
     status: MutationStatus;
 };
 
+/** Variables for {@link useSignTransaction}. */
 interface SignTransactionVariables {
+    /** Hex-encoded serialized transaction to sign. */
     transaction: string;
+    /** Whether to broadcast the signed transaction. Defaults to the wallet's behavior. */
     broadcast?: boolean;
 }
+/** Successful result from {@link useSignTransaction}. */
 interface SignTransactionData {
+    /** The signed, hex-encoded transaction. */
     transaction: string;
+    /** Transaction ID, present when the wallet broadcasts it. */
     txid?: string;
 }
+/** Callback options for the fire-and-forget `signTransaction()` variant. */
 interface SignTransactionOptions {
     onSuccess?: (data: SignTransactionData) => void;
     onError?: (error: Error) => void;
     onSettled?: (data: SignTransactionData | undefined, error: Error | null) => void;
 }
+/**
+ * Sign a serialized Stacks transaction without automatic broadcast.
+ *
+ * Useful for sponsored transaction flows where a separate service pays the
+ * fee and broadcasts the transaction.
+ *
+ * @example
+ * ```ts
+ * const { signTransactionAsync } = useSignTransaction();
+ *
+ * const { transaction } = await signTransactionAsync({
+ *   transaction: '0x0100...',
+ *   broadcast: false,
+ * });
+ * ```
+ *
+ * @throws {WalletNotConnectedError} If no wallet is connected.
+ * @throws {UnsupportedMethodError} If the wallet does not support raw signing (OKX).
+ * @throws {WalletRequestError} If the wallet rejects or fails the request.
+ */
 declare const useSignTransaction: () => {
     signTransaction: (variables: SignTransactionVariables, options?: SignTransactionOptions) => void;
     signTransactionAsync: (variables: SignTransactionVariables) => Promise<SignTransactionData>;
@@ -231,18 +472,46 @@ declare const useSignTransaction: () => {
     status: MutationStatus;
 };
 
+/** Variables for {@link useTransferSTX}. */
 interface TransferSTXVariables {
+    /** Recipient Stacks address (`SP...` or `ST...`). */
     recipient: string;
+    /** Amount in microSTX. Accepts `bigint`, `number`, or numeric `string`. */
     amount: bigint | number | string;
+    /** Optional memo string attached to the transfer. */
     memo?: string;
+    /** Custom fee in microSTX. Omit to let the wallet estimate. */
     fee?: bigint | number | string;
+    /** Custom nonce. Omit to let the wallet manage. */
     nonce?: bigint | number | string;
 }
+/** Callback options for the fire-and-forget `transferSTX()` variant. */
 interface TransferSTXOptions {
     onSuccess?: (txid: string) => void;
     onError?: (error: Error) => void;
     onSettled?: (txid: string | undefined, error: Error | null) => void;
 }
+/**
+ * Transfer native STX tokens to a recipient address.
+ *
+ * Returns the broadcast transaction ID on success. Supports all 6 wallets
+ * (OKX uses its proprietary API internally).
+ *
+ * @example
+ * ```ts
+ * const { transferSTXAsync, isPending } = useTransferSTX();
+ *
+ * const txid = await transferSTXAsync({
+ *   recipient: 'SP2...',
+ *   amount: 1_000_000n, // 1 STX
+ *   memo: 'coffee',
+ * });
+ * ```
+ *
+ * @throws {WalletNotConnectedError} If no wallet is connected.
+ * @throws {WalletNotFoundError} If OKX extension is not installed.
+ * @throws {WalletRequestError} If the wallet rejects or fails the request.
+ */
 declare const useTransferSTX: () => {
     transferSTX: (variables: TransferSTXVariables, options?: TransferSTXOptions) => void;
     transferSTXAsync: (variables: TransferSTXVariables) => Promise<string>;
@@ -265,8 +534,11 @@ type PublicFunctionArgs<TAbi extends ClarityAbi, TFn extends ExtractAbiFunctionN
     [K in ExtractAbiFunction<TAbi, TFn, 'public'>['args'][number] as K['name']]: ClarityAbiArgToPrimitiveTypeValue<K>;
 }>;
 
+/** Post-condition configuration for contract calls and STX transfers. */
 interface PostConditionConfig {
+    /** Array of post-conditions that must be satisfied for the transaction to succeed. */
     postConditions: PostCondition[];
+    /** Whether to allow or deny any asset transfers not covered by `postConditions`. */
     mode: PostConditionMode;
 }
 /** Typed mode: ABI present, args is a named object with autocomplete. */
@@ -288,6 +560,7 @@ interface UntypedWriteContractVariables {
 }
 /** Backward-compatible alias for the untyped variant. */
 type WriteContractVariables = UntypedWriteContractVariables;
+/** Callback options for the fire-and-forget `writeContract()` variant. */
 interface WriteContractOptions {
     onSuccess?: (txHash: string) => void;
     onError?: (error: Error) => void;
@@ -304,6 +577,46 @@ interface WriteContractFn {
     (variables: UntypedWriteContractVariables, options?: WriteContractOptions): void;
 }
 
+/**
+ * Call a public function on a Clarity smart contract.
+ *
+ * Supports two modes:
+ * - **Typed** (with ABI) — pass an ABI object for autocomplete on `functionName` and `args`.
+ * - **Untyped** — pass `ClarityValue[]` directly as `args`.
+ *
+ * @example
+ * ```ts
+ * import { Pc, PostConditionMode } from '@stacks/transactions';
+ *
+ * const { writeContractAsync } = useWriteContract();
+ *
+ * // Untyped mode
+ * const txid = await writeContractAsync({
+ *   address: 'SP...',
+ *   contract: 'my-contract',
+ *   functionName: 'transfer',
+ *   args: [uintCV(100)],
+ *   pc: {
+ *     postConditions: [Pc.principal('SP...').willSendLte(100n).ustx()],
+ *     mode: PostConditionMode.Deny,
+ *   },
+ * });
+ *
+ * // Typed mode (with ABI — enables autocomplete)
+ * const txid = await writeContractAsync({
+ *   abi: myContractAbi,
+ *   address: 'SP...',
+ *   contract: 'my-contract',
+ *   functionName: 'transfer', // autocompleted from ABI
+ *   args: { amount: 100n },   // named args, type-checked
+ *   pc: { postConditions: [], mode: PostConditionMode.Deny },
+ * });
+ * ```
+ *
+ * @throws {WalletNotConnectedError} If no wallet is connected.
+ * @throws {WalletNotFoundError} If OKX extension is not installed.
+ * @throws {WalletRequestError} If the wallet rejects or fails the request.
+ */
 declare const useWriteContract: () => {
     writeContract: WriteContractFn;
     writeContractAsync: WriteContractAsyncFn;
@@ -317,29 +630,100 @@ declare const useWriteContract: () => {
     status: MutationStatus;
 };
 
+/**
+ * Resolve a BNS v2 primary name for a Stacks address.
+ *
+ * Returns `null` when no name is registered or the address is undefined.
+ * Automatically detects mainnet/testnet from the address prefix.
+ *
+ * @param address - Stacks address to resolve (`SP...` or `ST...`).
+ *
+ * @example
+ * ```ts
+ * const { bnsName, isLoading } = useBnsName('SP2...');
+ * // bnsName = 'satoshi.btc' | null
+ * ```
+ */
 declare const useBnsName: (address?: string) => {
     bnsName: string | null;
     isLoading: boolean;
 };
 
+/**
+ * List all configured wallets with availability status.
+ *
+ * Each wallet includes its `id`, display `name`, `icon` (data URI), `webUrl`
+ * (install link), and whether it's `available` (extension detected or
+ * WalletConnect configured).
+ *
+ * @example
+ * ```ts
+ * const { wallets } = useWallets();
+ *
+ * wallets.map(({ id, name, icon, available }) => (
+ *   <button key={id} onClick={() => connect(id)} disabled={!available}>
+ *     <img src={icon} alt={name} width={20} /> {name}
+ *   </button>
+ * ));
+ * ```
+ */
 declare const useWallets: () => {
     wallets: WalletInfo[];
 };
 
+/**
+ * Infer the Stacks network from an address prefix.
+ *
+ * @param address - A Stacks address starting with `SP`/`SM` (mainnet) or `ST`/`SN` (testnet).
+ * @returns `'mainnet'` or `'testnet'`.
+ * @throws If the address doesn't start with a known prefix.
+ */
 declare const getNetworkFromAddress: (address: string) => "mainnet" | "testnet";
 
+/**
+ * Read the persisted wallet session from localStorage.
+ *
+ * Returns `null` on the server, when no session is stored, or when the
+ * stored provider is not in the supported wallets list.
+ */
 declare const getLocalStorageWallet: () => {
     address: string;
     provider: SupportedStacksWallet;
 } | null;
 
+/** Result of {@link getStacksWallets}. */
 interface StacksWallets {
+    /** All wallets supported by `@satoshai/kit`. */
     supported: SupportedStacksWallet[];
+    /** Subset of `supported` whose browser extension is currently detected. */
     installed: SupportedStacksWallet[];
 }
+/**
+ * Detect which Stacks wallets are supported and installed.
+ *
+ * Safe to call on the server — `installed` will contain only `'wallet-connect'`
+ * when `window` is undefined.
+ */
 declare const getStacksWallets: () => StacksWallets;
 
-/** Pre-bind ABI + address + contract for reuse with useWriteContract. */
+/**
+ * Pre-bind ABI, address, and contract name for reuse with `useWriteContract`.
+ *
+ * Returns the config object as-is but preserves the `const` ABI type, enabling
+ * autocomplete on `functionName` and type-checked `args` when spread into
+ * `writeContract()`.
+ *
+ * @example
+ * ```ts
+ * const pool = createContractConfig({
+ *   abi: poolAbi,
+ *   address: 'SP...',
+ *   contract: 'pool-v1',
+ * });
+ *
+ * writeContract({ ...pool, functionName: 'deposit', args: { amount: 100n }, pc });
+ * ```
+ */
 declare function createContractConfig<const TAbi extends ClarityAbi>(config: {
     abi: TAbi;
     address: string;