@provable-games/ekubo-sdk 0.1.0 → 0.1.9

package/dist/react.d.ts

@@ -0,0 +1,403 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { b as EkuboClientConfig, E as EkuboClient, S as SwapQuote, s as SwapCallsResult, A as ApiTokenInfo, O as OverviewStats, P as PairStats, l as PriceDataPoint } from './client-DPSUVYSv.js';
+
+interface EkuboProviderProps {
+    children: ReactNode;
+    /** Client configuration */
+    config?: EkuboClientConfig;
+    /** Pre-created client instance (alternative to config) */
+    client?: EkuboClient;
+}
+/**
+ * Provider component for EkuboClient
+ *
+ * @example
+ * ```tsx
+ * import { EkuboProvider } from '@provable-games/ekubo-sdk/react';
+ *
+ * function App() {
+ *   return (
+ *     <EkuboProvider config={{ chain: 'mainnet' }}>
+ *       <YourApp />
+ *     </EkuboProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function EkuboProvider({ children, config, client: providedClient, }: EkuboProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the EkuboClient from context
+ *
+ * @throws Error if used outside of EkuboProvider
+ */
+declare function useEkuboClient(): EkuboClient;
+/**
+ * Hook to optionally access the EkuboClient from context
+ * Returns null if used outside of EkuboProvider
+ */
+declare function useOptionalEkuboClient(): EkuboClient | null;
+
+interface UseEkuboSwapState {
+    /** Current swap quote */
+    quote: SwapQuote | null;
+    /** Whether a quote is being fetched */
+    loading: boolean;
+    /** Error from the last quote fetch */
+    error: Error | null;
+    /** Price impact percentage */
+    priceImpact: number | null;
+    /** Whether there's insufficient liquidity for this swap */
+    insufficientLiquidity: boolean;
+}
+interface UseEkuboSwapResult {
+    /** Current state */
+    state: UseEkuboSwapState;
+    /** Generate swap calls from the current quote */
+    generateCalls: (slippagePercent?: bigint, minimumReceived?: bigint) => SwapCallsResult | null;
+    /** Manually trigger a quote refetch */
+    refetch: () => void;
+}
+interface UseEkuboSwapProps {
+    /** Token being sold (address or symbol) */
+    sellToken: string | null;
+    /** Token being bought (address or symbol) */
+    buyToken: string | null;
+    /** Amount to swap (positive for exact input, negative for exact output) */
+    amount: bigint;
+    /** Whether to enable quote polling (default: true when tokens are valid) */
+    enabled?: boolean;
+    /** Polling interval in ms (default: 5000) */
+    pollingInterval?: number;
+    /** Default slippage percent (default: 5n = 5%) */
+    defaultSlippagePercent?: bigint;
+    /** Client config (optional if using EkuboProvider) */
+    config?: EkuboClientConfig;
+}
+/**
+ * Hook for fetching swap quotes with automatic polling
+ *
+ * Uses EkuboProvider client if available, otherwise creates a singleton client.
+ *
+ * @example
+ * ```tsx
+ * import { useEkuboSwap } from '@provable-games/ekubo-sdk/react';
+ *
+ * function SwapForm() {
+ *   const { state, generateCalls, refetch } = useEkuboSwap({
+ *     sellToken: 'ETH',
+ *     buyToken: 'USDC',
+ *     amount: 1000000000000000000n, // 1 ETH
+ *   });
+ *
+ *   if (state.loading) return <div>Loading quote...</div>;
+ *   if (state.error) return <div>Error: {state.error.message}</div>;
+ *   if (state.insufficientLiquidity) return <div>Insufficient liquidity</div>;
+ *
+ *   const handleSwap = () => {
+ *     const calls = generateCalls(5n); // 5% slippage
+ *     if (calls) {
+ *       // Execute calls with your wallet
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <p>You will receive: {state.quote?.total}</p>
+ *       <button onClick={handleSwap}>Swap</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useEkuboSwap({ sellToken, buyToken, amount, enabled, pollingInterval, defaultSlippagePercent, config, }: UseEkuboSwapProps): UseEkuboSwapResult;
+
+interface TokenPrices {
+    [address: string]: number | undefined;
+}
+interface UseEkuboPricesResult {
+    /** Map of token addresses to USD prices */
+    prices: TokenPrices;
+    /** Whether any prices are still loading */
+    isLoading: boolean;
+    /** Check if a specific token is still loading */
+    isTokenLoading: (tokenAddress: string) => boolean;
+    /** Check if a specific token had an error */
+    hasTokenError: (tokenAddress: string) => boolean;
+    /** Check if a token has a valid price (loaded, no error) */
+    isTokenAvailable: (tokenAddress: string) => boolean;
+    /** Get a token's price (returns undefined if not available) */
+    getPrice: (tokenAddress: string) => number | undefined;
+    /** Manually refetch all prices */
+    refetch: () => void;
+}
+interface UseEkuboPricesProps {
+    /** Array of token addresses to fetch prices for */
+    tokens: string[];
+    /** Timeout for each price fetch in ms (default: 10000) */
+    timeoutMs?: number;
+    /** Client config (optional if using EkuboProvider) */
+    config?: EkuboClientConfig;
+    /** Whether to enable price fetching (default: true) */
+    enabled?: boolean;
+    /** Standard amount for price calculation (default: 1e18 - 1 token with 18 decimals) */
+    standardAmount?: bigint;
+}
+/**
+ * Hook for fetching USD prices for multiple tokens
+ *
+ * Uses EkuboProvider client if available, otherwise creates a singleton client.
+ *
+ * @example
+ * ```tsx
+ * import { useEkuboPrices } from '@provable-games/ekubo-sdk/react';
+ *
+ * function TokenPrices() {
+ *   const {
+ *     prices,
+ *     isLoading,
+ *     getPrice,
+ *     isTokenAvailable
+ *   } = useEkuboPrices({
+ *     tokens: [ETH_ADDRESS, STRK_ADDRESS]
+ *   });
+ *
+ *   if (isLoading) return <div>Loading prices...</div>;
+ *
+ *   return (
+ *     <div>
+ *       <p>ETH: ${isTokenAvailable(ETH_ADDRESS) ? getPrice(ETH_ADDRESS) : 'N/A'}</p>
+ *       <p>STRK: ${isTokenAvailable(STRK_ADDRESS) ? getPrice(STRK_ADDRESS) : 'N/A'}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useEkuboPrices({ tokens, timeoutMs, config, enabled, standardAmount, }: UseEkuboPricesProps): UseEkuboPricesResult;
+
+interface UseEkuboTokensResult {
+    /** Array of tokens from the API */
+    tokens: ApiTokenInfo[];
+    /** Whether tokens are loading */
+    isLoading: boolean;
+    /** Error from fetching tokens */
+    error: Error | null;
+    /** Manually refetch tokens */
+    refetch: () => void;
+    /** Get a token by address */
+    getToken: (address: string) => ApiTokenInfo | undefined;
+    /** Get a token by symbol */
+    getTokenBySymbol: (symbol: string) => ApiTokenInfo | undefined;
+}
+interface UseEkuboTokensProps {
+    /** Client config (optional if using EkuboProvider) */
+    config?: EkuboClientConfig;
+    /** Whether to enable token fetching (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Hook for fetching the list of available tokens from Ekubo API
+ *
+ * @example
+ * ```tsx
+ * import { useEkuboTokens } from '@provable-games/ekubo-sdk/react';
+ *
+ * function TokenList() {
+ *   const { tokens, isLoading, getTokenBySymbol } = useEkuboTokens();
+ *
+ *   if (isLoading) return <div>Loading tokens...</div>;
+ *
+ *   const eth = getTokenBySymbol('ETH');
+ *
+ *   return (
+ *     <ul>
+ *       {tokens.map(token => (
+ *         <li key={token.address}>{token.symbol}: {token.name}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useEkuboTokens({ config, enabled, }?: UseEkuboTokensProps): UseEkuboTokensResult;
+
+interface UseEkuboStatsResult {
+    /** Protocol TVL statistics */
+    tvl: OverviewStats | null;
+    /** Protocol volume statistics */
+    volume: OverviewStats | null;
+    /** Top trading pairs */
+    topPairs: PairStats[];
+    /** Whether stats are loading */
+    isLoading: boolean;
+    /** Error from fetching stats */
+    error: Error | null;
+    /** Manually refetch stats */
+    refetch: () => void;
+}
+interface UseEkuboStatsProps {
+    /** Client config (optional if using EkuboProvider) */
+    config?: EkuboClientConfig;
+    /** Whether to enable stats fetching (default: true) */
+    enabled?: boolean;
+    /** Whether to fetch TVL (default: true) */
+    fetchTvl?: boolean;
+    /** Whether to fetch volume (default: true) */
+    fetchVolume?: boolean;
+    /** Whether to fetch top pairs (default: true) */
+    fetchTopPairs?: boolean;
+}
+/**
+ * Hook for fetching Ekubo protocol statistics (TVL, volume, top pairs)
+ *
+ * @example
+ * ```tsx
+ * import { useEkuboStats } from '@provable-games/ekubo-sdk/react';
+ *
+ * function ProtocolStats() {
+ *   const { tvl, volume, topPairs, isLoading } = useEkuboStats();
+ *
+ *   if (isLoading) return <div>Loading stats...</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h2>Protocol Statistics</h2>
+ *       {tvl && <p>TVL: ${tvl.total.toLocaleString()}</p>}
+ *       {volume && <p>24h Volume: ${volume.total.toLocaleString()}</p>}
+ *       <h3>Top Pairs</h3>
+ *       <ul>
+ *         {topPairs.slice(0, 5).map((pair, i) => (
+ *           <li key={i}>{pair.token0Symbol}/{pair.token1Symbol}</li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useEkuboStats({ config, enabled, fetchTvl, fetchVolume, fetchTopPairs, }?: UseEkuboStatsProps): UseEkuboStatsResult;
+
+interface UseEkuboPriceHistoryResult {
+    /** Array of price data points */
+    data: PriceDataPoint[];
+    /** Whether price history is loading */
+    isLoading: boolean;
+    /** Error from fetching price history */
+    error: Error | null;
+    /** Manually refetch price history */
+    refetch: () => void;
+}
+interface UseEkuboPriceHistoryProps {
+    /** Token to get price for (address or symbol) */
+    token: string;
+    /** Quote token (address or symbol, e.g., 'USDC') */
+    quoteToken: string;
+    /** Time interval in seconds (default: 7000) */
+    interval?: number;
+    /** Client config (optional if using EkuboProvider) */
+    config?: EkuboClientConfig;
+    /** Whether to enable price history fetching (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Hook for fetching historical price data for a token pair
+ *
+ * @example
+ * ```tsx
+ * import { useEkuboPriceHistory } from '@provable-games/ekubo-sdk/react';
+ *
+ * function PriceChart() {
+ *   const { data, isLoading } = useEkuboPriceHistory({
+ *     token: 'ETH',
+ *     quoteToken: 'USDC',
+ *     interval: 3600, // 1 hour intervals
+ *   });
+ *
+ *   if (isLoading) return <div>Loading price history...</div>;
+ *
+ *   return (
+ *     <div>
+ *       {data.map((point) => (
+ *         <div key={point.timestamp}>
+ *           {new Date(point.timestamp * 1000).toLocaleDateString()}: ${point.price}
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useEkuboPriceHistory({ token, quoteToken, interval, config, enabled, }: UseEkuboPriceHistoryProps): UseEkuboPriceHistoryResult;
+
+interface QuoteResult {
+    /** The swap quote */
+    quote: SwapQuote | null;
+    /** Whether this quote is loading */
+    loading: boolean;
+    /** Error from fetching this quote */
+    error: Error | null;
+    /** Whether there's insufficient liquidity */
+    insufficientLiquidity: boolean;
+}
+interface QuotesMap {
+    [sellToken: string]: QuoteResult;
+}
+interface UseEkuboQuotesResult {
+    /** Map of sellToken address to quote result */
+    quotes: QuotesMap;
+    /** Whether any quotes are still loading */
+    isLoading: boolean;
+    /** Get quote for a specific sell token */
+    getQuote: (sellToken: string) => QuoteResult | undefined;
+    /** Manually refetch all quotes */
+    refetch: () => void;
+}
+interface UseEkuboQuotesProps {
+    /** Array of tokens that can be sold (addresses or symbols) */
+    sellTokens: string[];
+    /** Token being bought (address or symbol) */
+    buyToken: string | null;
+    /** Amount to swap (positive for exact input, negative for exact output) */
+    amount: bigint;
+    /** Whether to enable quote fetching (default: true) */
+    enabled?: boolean;
+    /** Polling interval in ms (default: 30000 - 30 seconds) */
+    pollingInterval?: number;
+    /** Client config (optional if using EkuboProvider) */
+    config?: EkuboClientConfig;
+}
+/**
+ * Hook for fetching swap quotes for multiple sell tokens at once.
+ *
+ * Useful when you want to show users multiple payment options with
+ * their costs upfront, allowing instant switching between options.
+ *
+ * @example
+ * ```tsx
+ * import { useEkuboQuotes } from '@provable-games/ekubo-sdk/react';
+ *
+ * function PaymentSelector() {
+ *   const { quotes, isLoading, getQuote } = useEkuboQuotes({
+ *     sellTokens: [ETH_ADDRESS, STRK_ADDRESS, USDC_ADDRESS],
+ *     buyToken: ENTRY_TOKEN,
+ *     amount: entryFeeAmount,
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {sellTokens.map(token => {
+ *         const result = getQuote(token);
+ *         return (
+ *           <button key={token} onClick={() => setSelectedToken(token)}>
+ *             Pay with {token}: {result?.quote?.total ?? 'Loading...'}
+ *           </button>
+ *         );
+ *       })}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useEkuboQuotes({ sellTokens, buyToken, amount, enabled, pollingInterval, config, }: UseEkuboQuotesProps): UseEkuboQuotesResult;
+
+export { EkuboProvider, type EkuboProviderProps, type QuoteResult, type QuotesMap, type TokenPrices, type UseEkuboPriceHistoryProps, type UseEkuboPriceHistoryResult, type UseEkuboPricesProps, type UseEkuboPricesResult, type UseEkuboQuotesProps, type UseEkuboQuotesResult, type UseEkuboStatsProps, type UseEkuboStatsResult, type UseEkuboSwapProps, type UseEkuboSwapResult, type UseEkuboSwapState, type UseEkuboTokensProps, type UseEkuboTokensResult, useEkuboClient, useEkuboPriceHistory, useEkuboPrices, useEkuboQuotes, useEkuboStats, useEkuboSwap, useEkuboTokens, useOptionalEkuboClient };