@rialo/frost 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,504 @@
+import { FrostConfig, WalletEntity, AccountEntity, RialoClientConfig, RialoClient, ConnectionStatus, ConnectResult, ConnectOptions, SignMessageResult, SignMessageOptions, SendTransactionResult, SignAndSendTransactionResult, SignTransactionResult, SendTransactionType, SignAndSendTransactionOptions, SignTransactionOptions } from '@rialo/frost-core';
+export * from '@rialo/frost-core';
+import { QueryClient, UseMutationResult } from '@tanstack/react-query';
+import { ReactNode, CSSProperties } from 'react';
+
+interface FrostProviderProps {
+    children: ReactNode;
+    /**
+     * Frost configuration object created with `createConfig()`.
+     *
+     * **Important:** Create the config outside of React components to ensure
+     * it's only created once and remains stable across re-renders.
+     *
+     * @example
+     * ```tsx
+     * // config.ts
+     * import { createConfig, getDefaultRialoClientConfig } from '@rialo/frost-core';
+     *
+     * export const config = createConfig({
+     *   clientConfig: getDefaultRialoClientConfig('devnet'),
+     * });
+     *
+     * // App.tsx
+     * import { FrostProvider } from '@rialo/frost';
+     * import { config } from './config';
+     *
+     * function App() {
+     *   return (
+     *     <FrostProvider config={config}>
+     *       <YourApp />
+     *     </FrostProvider>
+     *   );
+     * }
+     * ```
+     */
+    config: FrostConfig;
+    /** Optional external QueryClient (for sharing with app) */
+    queryClient?: QueryClient;
+}
+/**
+ * Provider component for Frost.
+ * Initializes wallet discovery, event handling, and provides config to hooks.
+ */
+declare function FrostProvider({ children, config, queryClient: externalQueryClient, }: Readonly<FrostProviderProps>): ReactNode;
+/**
+ * Hook to access the DappKit config.
+ * Must be used within a FrostProvider.
+ */
+declare function useFrostConfig(): FrostConfig;
+
+/** biome-ignore-all lint/nursery/useExplicitType: <mouse events> */
+
+interface ConnectButtonProps {
+    /** Label shown when disconnected */
+    label?: string;
+    /** Label shown while connecting */
+    connectingLabel?: string;
+    /** Label or formatter for connected state */
+    connectedLabel?: string | ((address: string, walletName: string) => string);
+    /** Callback when wallet successfully connects */
+    onConnect?: (walletName: string, address: string) => void;
+    /** Callback when wallet disconnects */
+    onDisconnect?: () => void;
+    /** Callback when connection fails */
+    onError?: (error: Error) => void;
+    /** Additional class name for the button */
+    className?: string;
+    /** Additional styles for the button */
+    style?: CSSProperties;
+    /** Whether the button is disabled */
+    disabled?: boolean;
+    /** Title for the wallet selection modal */
+    modalTitle?: string;
+    /** Whether to show the connected dropdown menu @default true */
+    showDropdown?: boolean;
+    /** Additional class for the dropdown menu */
+    dropdownClassName?: string;
+}
+declare function ConnectButton({ label, connectingLabel, connectedLabel, onConnect, onDisconnect, onError, className, style, disabled, modalTitle, showDropdown, dropdownClassName, }: ConnectButtonProps): ReactNode;
+
+interface WalletModalProps {
+    /** Whether the modal is open */
+    open: boolean;
+    /** Callback when modal should close */
+    onClose: () => void;
+    /** Callback when wallet connection succeeds */
+    onConnect?: (walletName: string, address: string) => void;
+    /** Callback when wallet connection fails */
+    onError?: (error: Error, walletName: string) => void;
+    /** Modal title */
+    title?: string;
+    /** Additional class name for the modal overlay */
+    className?: string;
+    /** Additional class name for the modal content */
+    contentClassName?: string;
+    /** Custom styles for the modal */
+    style?: CSSProperties;
+    /** Render prop for custom wallet item rendering */
+    renderWallet?: (wallet: WalletEntity, connect: () => void, isConnecting: boolean) => ReactNode;
+}
+declare function WalletModal({ open, onClose, onConnect, onError, title, className, contentClassName, style, renderWallet, }: WalletModalProps): ReactNode;
+
+/**
+ * Hook to get all known accounts.
+ *
+ * @returns Array of account entities (memoized)
+ *
+ * @example
+ * ```tsx
+ * function AccountList() {
+ *   const accounts = useAccounts();
+ *
+ *   return (
+ *     <ul>
+ *       {accounts.map(acc => (
+ *         <li key={acc.address}>{acc.address}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useAccounts(): AccountEntity[];
+
+/**
+ * Hook to get the currently active account.
+ *
+ * @returns Active account or null if not connected
+ *
+ * @example
+ * ```tsx
+ * function AccountInfo() {
+ *   const account = useActiveAccount();
+ *
+ *   if (!account) return <div>Not connected</div>;
+ *   return <div>Address: {account.address}</div>;
+ * }
+ * ```
+ */
+declare function useActiveAccount(): AccountEntity | null;
+
+/**
+ * Hook to get the currently active wallet.
+ *
+ * @returns Active wallet or null if not connected
+ *
+ * @example
+ * ```tsx
+ * function WalletInfo() {
+ *   const wallet = useActiveWallet();
+ *
+ *   if (!wallet) return <div>No wallet connected</div>;
+ *   return <div>Connected to: {wallet.name}</div>;
+ * }
+ * ```
+ */
+declare function useActiveWallet(): WalletEntity | null;
+
+interface UseSwitchChainOptions {
+    onSuccess?: () => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Hook to switch to a different chain/network.
+ *
+ * @example
+ * ```tsx
+ * import { getDefaultRialoClientConfig } from '@rialo/ts-cdk';
+ *
+ * function NetworkSwitcher() {
+ *   const switchChain = useSwitchChain();
+ *
+ *   return (
+ *     <button
+ *       onClick={() => switchChain(getDefaultRialoClientConfig('mainnet'))}
+ *     >
+ *       Switch to Mainnet
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useSwitchChain(): (clientConfig: RialoClientConfig) => void;
+/**
+ * Hook to get the current chain ID.
+ * Reactively updates when chain changes.
+ *
+ * The selector is stable (defined at module level) to prevent
+ * unnecessary re-subscriptions.
+ *
+ * @example
+ * ```tsx
+ * function NetworkDisplay() {
+ *   const chainId = useChainId();
+ *   return <div>Connected to: {chainId}</div>;
+ * }
+ * ```
+ */
+declare function useChainId(): string;
+
+/**
+ * Hook to access the RialoClient instance.
+ *
+ * The client can be used for blockchain queries and transactions:
+ * - Query balances and account info
+ * - Get transaction details
+ * - Send signed transactions directly
+ * - Request airdrops (devnet/testnet)
+ *
+ * @example
+ * ```tsx
+ * function BalanceDisplay({ address }: { address: string }) {
+ *   const client = useClient();
+ *   const [balance, setBalance] = useState<bigint | null>(null);
+ *
+ *   useEffect(() => {
+ *     client.getBalance(PublicKey.fromString(address))
+ *       .then(setBalance);
+ *   }, [client, address]);
+ *
+ *   return <div>Balance: {balance?.toString() ?? 'Loading...'}</div>;
+ * }
+ * ```
+ */
+declare function useClient(): RialoClient;
+
+/**
+ * Hook to get the current connection status.
+ *
+ * @returns Connection status: "disconnected" | "connecting" | "connected" | "reconnecting"
+ *
+ * @example
+ * ```tsx
+ * function StatusIndicator() {
+ *   const status = useConnectionStatus();
+ *   return <div>Status: {status}</div>;
+ * }
+ * ```
+ */
+declare function useConnectionStatus(): ConnectionStatus;
+/**
+ * Hook to check if currently connected.
+ *
+ * @returns True if a wallet is connected
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const isConnected = useIsConnected();
+ *   return isConnected ? <Dashboard /> : <ConnectPrompt />;
+ * }
+ * ```
+ */
+declare function useIsConnected(): boolean;
+
+interface UseConnectWalletOptions {
+    onSuccess?: (result: ConnectResult) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Hook to connect to a wallet.
+ *
+ * @param options - Callbacks for success/error handling
+ * @returns Mutation to trigger wallet connection
+ *
+ * @example
+ * ```tsx
+ * function ConnectButton() {
+ *   const { mutate: connect, isPending } = useConnectWallet({
+ *     onSuccess: () => console.log('Connected!'),
+ *   });
+ *
+ *   return (
+ *     <button onClick={() => connect({ walletName: 'Rialo' })} disabled={isPending}>
+ *       Connect
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useConnectWallet(options?: UseConnectWalletOptions): UseMutationResult<ConnectResult, Error, ConnectOptions>;
+interface UseDisconnectWalletOptions {
+    onSuccess?: () => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Hook to disconnect the current wallet.
+ *
+ * @param options - Callbacks for success/error handling
+ * @returns Mutation to trigger wallet disconnection
+ *
+ * @example
+ * ```tsx
+ * function DisconnectButton() {
+ *   const { mutate: disconnect } = useDisconnectWallet();
+ *   return <button onClick={() => disconnect()}>Disconnect</button>;
+ * }
+ * ```
+ */
+declare function useDisconnectWallet(options?: UseDisconnectWalletOptions): UseMutationResult<void, Error, void>;
+
+interface UseNativeBalanceOptions {
+    /**
+     * Address to query balance for.
+     * Defaults to the active account address if not provided.
+     */
+    address?: string;
+    /**
+     * Number of decimal places for the native token.
+     * Used for formatting the balance.
+     * @default 9 (standard for Solana-based chains)
+     */
+    decimals?: number;
+}
+interface UseNativeBalanceResult {
+    /** Raw balance in lamports/smallest unit */
+    balance: bigint | undefined;
+    /** Human-readable formatted balance (e.g., "1.5") */
+    formatted: string | undefined;
+    /** Whether the query is currently loading */
+    isLoading: boolean;
+    /** Whether the query is fetching (initial or refetch) */
+    isFetching: boolean;
+    /** Whether the query encountered an error */
+    isError: boolean;
+    /** Error object if query failed */
+    error: Error | null;
+    /** Manually trigger a refetch */
+    refetch: () => void;
+}
+/**
+ * Hook to query the native token balance for an address.
+ *
+ * @example
+ * ```tsx
+ * function MyBalance() {
+ *   const { balance, formatted, isLoading } = useNativeBalance();
+ *   if (isLoading) return <div>Loading...</div>;
+ *   return <div>Balance: {formatted} RIA</div>;
+ * }
+ * ```
+ */
+declare function useNativeBalance(options?: UseNativeBalanceOptions): UseNativeBalanceResult;
+
+interface UseSignMessageOptions {
+    onSuccess?: (result: SignMessageResult) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Hook to sign an arbitrary message.
+ *
+ * @param options - Callbacks for success/error handling
+ * @returns Mutation to trigger message signing
+ *
+ * @example
+ * ```tsx
+ * function SignButton() {
+ *   const { mutate: sign, isPending } = useSignMessage({
+ *     onSuccess: (result) => console.log('Signature:', result.signature),
+ *   });
+ *
+ *   return (
+ *     <button onClick={() => sign({ message: 'Hello World' })} disabled={isPending}>
+ *       Sign Message
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useSignMessage(options?: UseSignMessageOptions): UseMutationResult<SignMessageResult, Error, SignMessageOptions>;
+
+interface UseSignTransactionOptions {
+    onSuccess?: (result: SignTransactionResult) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Hook to sign a transaction without sending.
+ *
+ * @param options - Callbacks for success/error handling
+ * @returns Mutation to trigger transaction signing
+ *
+ * @example
+ * ```tsx
+ * function SignTxButton({ transaction }: { transaction: Uint8Array }) {
+ *   const { mutate: sign, isPending } = useSignTransaction();
+ *
+ *   return (
+ *     <button onClick={() => sign({ transaction })} disabled={isPending}>
+ *       Sign Transaction
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useSignTransaction(options?: UseSignTransactionOptions): UseMutationResult<SignTransactionResult, Error, SignTransactionOptions>;
+interface UseSendTransactionOptions {
+    onSuccess?: (result: SendTransactionResult) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Hook to sign and send a transaction using the wallet's built-in send feature.
+ *
+ * @param options - Callbacks for success/error handling
+ * @returns Mutation to trigger transaction signing and sending
+ *
+ * @example
+ * ```tsx
+ * function SendTxButton({ transaction }: { transaction: Uint8Array }) {
+ *   const { mutate: send, isPending } = useSendTransaction();
+ *
+ *   return (
+ *     <button onClick={() => send({ transaction })} disabled={isPending}>
+ *       Send Transaction
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useSendTransaction(options?: UseSendTransactionOptions): UseMutationResult<SendTransactionResult, Error, SendTransactionType>;
+interface UseSignAndSendTransactionOptions {
+    onSuccess?: (result: SignAndSendTransactionResult) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Hook to sign a transaction with the wallet, send it via Frost's RPC client,
+ * and wait for confirmation.
+ *
+ * This provides more control over transaction submission compared to useSendTransaction,
+ * as it uses Frost's own RPC client instead of the wallet's built-in send.
+ * This is useful when you want to:
+ * - Use a custom RPC URL (configured via ChainDefinition.rpcUrl)
+ * - Have more control over retry logic and confirmation
+ * - Not rely on the wallet's send implementation
+ *
+ * @returns Mutation that resolves with confirmed transaction details (signature, executed)
+ * @throws {TransactionFailedError} If the transaction is confirmed but execution failed on-chain
+ *
+ * @example
+ * ```tsx
+ * function SendButton() {
+ *   const { mutate: signAndSend, isPending } = useSignAndSendTransaction({
+ *     onSuccess: (result) => {
+ *       console.log('Confirmed and executed:', result.signature);
+ *     },
+ *     onError: (error) => {
+ *       if (error instanceof TransactionFailedError) {
+ *         console.error('Transaction failed on-chain:', error.reason);
+ *       }
+ *     },
+ *   });
+ *
+ *   const handleSend = () => {
+ *     signAndSend({
+ *       transaction: myTransaction,
+ *       sendOptions: { skipPreflight: false, maxRetries: 3 },
+ *     });
+ *   };
+ *
+ *   return <button onClick={handleSend} disabled={isPending}>Send</button>;
+ * }
+ * ```
+ */
+declare function useSignAndSendTransaction(options?: UseSignAndSendTransactionOptions): UseMutationResult<SignAndSendTransactionResult, Error, SignAndSendTransactionOptions>;
+
+/**
+ * Hook to get sorted wallets list.
+ * Wallets are sorted by priority (higher first) then by last connected time.
+ *
+ * @returns Sorted array of wallet entities (memoized)
+ *
+ * @example
+ * ```tsx
+ * function WalletList() {
+ *   const wallets = useWallets();
+ *
+ *   return (
+ *     <ul>
+ *       {wallets.map(w => (
+ *         <li key={w.name}>{w.name}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useWallets(): WalletEntity[];
+/**
+ * Hook to check if wallets have been discovered.
+ *
+ * @returns True if at least one wallet has been discovered
+ *
+ * @example
+ * ```tsx
+ * function ConnectButton() {
+ *   const walletsReady = useWalletsReady();
+ *
+ *   if (!walletsReady) return <div>Searching for wallets...</div>;
+ *   return <button>Connect Wallet</button>;
+ * }
+ * ```
+ */
+declare function useWalletsReady(): boolean;
+
+export { ConnectButton, type ConnectButtonProps, FrostProvider, type FrostProviderProps, type UseConnectWalletOptions, type UseDisconnectWalletOptions, type UseNativeBalanceOptions, type UseNativeBalanceResult, type UseSendTransactionOptions, type UseSignAndSendTransactionOptions, type UseSignMessageOptions, type UseSignTransactionOptions, type UseSwitchChainOptions, WalletModal, type WalletModalProps, useAccounts, useActiveAccount, useActiveWallet, useChainId, useClient, useConnectWallet, useConnectionStatus, useDisconnectWallet, useFrostConfig, useIsConnected, useNativeBalance, useSendTransaction, useSignAndSendTransaction, useSignMessage, useSignTransaction, useSwitchChain, useWallets, useWalletsReady };