@shogun-sdk/swap 0.0.2-test.25 → 0.0.2-test.27

package/dist/react.d.ts

@@ -1,124 +1,300 @@
-import { TokenSearchParams, TokenSearchResponse } from '@shogun-sdk/intents-sdk';
-export { ChainID, isEvmChain } from '@shogun-sdk/intents-sdk';
-import { a as SwapQuoteResponse, e as executeOrder, b as Stage, g as PollResult, S as SwapQuoteParams, B as BalanceRequestParams, c as BalanceResponse } from './execute-D2qcOzkI.js';
-export { P as PlaceOrderResult, Q as QuoteTokenInfo, T as TokenBalance, f as TokenInfo, d as TokenSearchResponse } from './execute-D2qcOzkI.js';
-import { A as AdaptedWallet } from './wallet-BhuMJ3K_.js';
+import React from 'react';
+import { S as SwapSDKConfig, a as SwapSDK, b as SwapQuoteParams, c as SwapQuoteResponse, E as ExecuteOrderParams, d as Stage, P as PlaceOrderResult, T as TokenInfo, B as BalanceRequestParams, e as BalanceResponse } from './index-Qoc6Q9XN.js';
+export { C as ChainId, O as OrderExecutionType, j as SupportedChain, g as SupportedChains, h as TokenBalance, f as buildQuoteParams, i as isEvmChain } from './index-Qoc6Q9XN.js';
 import { WalletClient } from 'viem';
-import '@mysten/sui/transactions';
+import { A as AdaptedWallet } from './wallet-B9bKceyN.js';
+import { ApiUserOrders } from '@shogun-sdk/intents-sdk';
 import '@solana/web3.js';
 
-declare function useTokenList(params: TokenSearchParams & {
-    debounceMs?: number;
-}): {
-    /** Current fetched data (cached when possible) */
-    data: TokenSearchResponse | null;
-    /** Whether a request is in progress */
+/**
+ * @fileoverview React provider for Swap SDK
+ *
+ * This provider initializes a single instance of `SwapSDK` and
+ * makes it available to all child components via React context.
+ *
+ * Usage:
+ * ```tsx
+ * <SwapProvider config={{ apiKey: "your-api-key" }}>
+ *   <App />
+ * </SwapProvider>
+ * ```
+ *
+ * Then, access it anywhere:
+ * ```tsx
+ * const sdk = useSwap();
+ * const quote = await sdk.getQuote({ ... });
+ * ```
+ */
+
+/**
+ * Provides a `SwapSDK` instance to React components.
+ */
+declare const SwapProvider: React.FC<React.PropsWithChildren<{
+    config: SwapSDKConfig;
+}>>;
+/**
+ * Hook to access the initialized `SwapSDK` instance.
+ *
+ * Must be used within a `<SwapProvider>` context.
+ *
+ * @throws Will throw if called outside of `<SwapProvider>`.
+ */
+declare const useSwap: () => SwapSDK;
+
+/**
+ * Augment globalThis to safely hold a shared quote params reference.
+ */
+declare global {
+    var __QUOTE_PARAMS_REF__: {
+        current: SwapQuoteParams | null;
+    } | undefined;
+}
+/**
+ * Centralized SWR-powered hook for fetching swap quotes.
+ *
+ * This hook provides:
+ * - A globally shared quote state (via SWR global cache)
+ * - Abort-safe refetching logic
+ * - Consistent parameters shared across multiple components
+ * - Easy revalidation triggers
+ *
+ * @param initialParams Optional initial quote parameters.
+ * @returns Object containing quote data, loading state, refetch and setParams methods.
+ *
+ * @example
+ * ```tsx
+ * const { data, loading, error, refetch, setParams } = useQuote({
+ *   tokenIn: "0x123...",
+ *   tokenOut: "0xabc...",
+ *   amount: "1000000000000000000",
+ *   srcChainId: 1,
+ *   destChainId: 8453,
+ * });
+ * ```
+ */
+declare function useQuote(initialParams?: SwapQuoteParams | null): {
+    data: SwapQuoteResponse | null | undefined;
     loading: boolean;
-    /** Error object if a request failed */
-    error: Error | null;
-    /** Manually refetch the token list */
+    error: string | null;
     refetch: () => Promise<void>;
-    /** Clear all cached token results (shared across hook instances) */
-    clearCache: () => void;
+    setParams: (next: SwapQuoteParams | null) => void;
+    readonly activeParams: SwapQuoteParams | null;
 };
 
-/** Infers the exact return type from executeOrder() */
-type ExecuteOrderResult = Awaited<ReturnType<typeof executeOrder>>;
 /**
- * React hook for executing swap orders via the Shogun SDK with
- * built-in stage tracking, loading states, and error handling.
+ * `useExecuteTransaction`
+ *
+ * React hook to execute a swap transaction (EVM or Solana) using the Swap SDK.
+ * It provides live transaction status updates through stage-based tracking.
  *
  * ---
- * ## Example
+ * ## Features
+ * - Handles the full swap lifecycle: token approval → execution → confirmation
+ * - Tracks execution stage and status messages in real time
+ * - Automatically refreshes balances and latest quote data after completion
+ * - Supports both EVM and Solana (SVM) wallets
+ * - Works seamlessly with market and limit orders
+ *
+ * @example
  * ```tsx
- * import { useExecuteOrder } from "@shogun-sdk/swap/react"
- *
- * export function SwapButton({ quote, accountAddress, wallet }) {
- *   const { execute, status, message, loading } = useExecuteOrder()
- *
- *   const handleClick = async () => {
- *     await execute({
- *       quote,
- *       accountAddress,
- *       wallet,
- *       // Optional: custom 10-minute deadline
- *       deadline: Math.floor(Date.now() / 1000) + 10 * 60,
- *     })
- *   }
- *
- *   return (
- *     <button disabled={loading} onClick={handleClick}>
- *       {loading ? message ?? "Processing..." : "Execute Swap"}
- *     </button>
- *   )
- * }
+ * const { execute, isLoading, stage, message, result, error } = useExecuteTransaction();
+ *
+ * * Example: Market order
+ * await execute({
+ *   quote,
+ *   accountAddress: "0x123...",
+ *   wallet,
+ *   orderType: OrderExecutionType.MARKET,
+ *   options: { deadline: 1800 },
+ * });
+ *
+ * * Example: Limit order
+ * await execute({
+ *   quote,
+ *   accountAddress: "0x123...",
+ *   wallet,
+ *   orderType: OrderExecutionType.LIMIT,
+ *   options: { executionPrice: "0.0021", deadline: 3600 },
+ * });
  * ```
  */
-declare function useExecuteOrder(): {
-    /** Executes the swap order. */
-    execute: ({ quote, accountAddress, recipientAddress, wallet, deadline, }: {
+declare function useExecuteTransaction(): {
+    execute: ({ quote, accountAddress, recipientAddress, wallet, orderType, options, }: {
         quote: SwapQuoteResponse;
         accountAddress: string;
-        recipientAddress?: string;
+        recipientAddress: string;
         wallet: AdaptedWallet | WalletClient;
-        deadline?: number;
-    }) => Promise<ExecuteOrderResult>;
-    /** Current execution stage. */
-    status: Stage;
-    /** Human-readable status message. */
-    message: string | null;
-    /** Whether execution is ongoing. */
-    loading: boolean;
-    /** Raw SDK response data. */
-    data: {
+    } & ExecuteOrderParams) => Promise<{
         status: boolean;
         orderId: string;
         chainId: number;
-        finalStatus: PollResult;
-        stage: Stage;
+        finalStatus: string;
+        stage: string;
     } | {
         status: boolean;
         message: string;
         stage: string;
-    } | null;
-    /** Captured error (if execution failed). */
-    error: Error | null;
+    }>;
+    isLoading: boolean;
+    stage: Stage | null;
+    message: string | null;
+    error: string | null;
+    result: PlaceOrderResult | null;
 };
 
 /**
- * useQuote — React hook for fetching live swap quotes.
+ * React hook for searching and paginating verified tokens using the Swap SDK.
+ *
+ * ## Features
+ * - Optional `networkId` for chain-specific or global search
+ * - Caches results per query and page to minimize redundant API calls
+ * - Supports infinite scroll-style pagination
+ * - Provides loading, error, and `hasMore` state tracking
+ *
+ * @example
+ * ```tsx
+ * const { tokens, loadTokens, hasMore, loading } = useTokenList();
+ *
+ * useEffect(() => {
+ *   loadTokens({ q: "USDC", networkId: 1, reset: true });
+ * }, []);
+ * ```
  */
-declare function useQuote(params: SwapQuoteParams | null, options?: {
-    debounceMs?: number;
-    autoRefreshMs?: number;
-}): {
-    data: SwapQuoteResponse | null;
+declare function useTokenList(): {
+    tokens: TokenInfo[];
+    loading: boolean;
+    error: string | null;
+    hasMore: boolean;
+    page: number;
+    lastQuery: {
+        q?: string;
+        networkId?: number;
+    };
+    loadTokens: (params: {
+        q?: string;
+        networkId?: number;
+        reset?: boolean;
+    }) => Promise<void>;
+    resetTokens: () => void;
+};
+
+/**
+ * Augment globalThis to safely hold a shared params reference.
+ */
+declare global {
+    var __BALANCES_PARAMS_REF__: {
+        current: BalanceRequestParams | null;
+    } | undefined;
+}
+/**
+ * SWR-powered, centralized balance fetching hook.
+ *
+ * ## Features
+ * - Shared global cache across all components (SWR)
+ * - Strongly typed params and responses
+ * - Abort-safe concurrent refetch
+ * - Centralized params sync using `globalThis`
+ * - Keeps previous data during refetch (no reset)
+ * - Auto-refetch when initialParams change (svm_address or evm_address)
+ */
+declare function useBalances(initialParams?: BalanceRequestParams | null): {
+    data: BalanceResponse | null | undefined;
     loading: boolean;
     error: Error | null;
-    warning: string | null;
     refetch: () => Promise<void>;
+    setParams: (next: BalanceRequestParams | null) => void;
+    readonly activeParams: BalanceRequestParams | null;
 };
 
 /**
- * React hook for fetching wallet token balances across EVM + SVM chains.
+ * React hook to fetch metadata and price for one or multiple tokens using the Swap SDK.
  *
  * ---
- * ## Example
+ * ## Features
+ * - Automatically fetches token metadata and price info
+ * - Handles loading and error states
+ * - Works with both EVM and SVM tokens
+ *
+ * @param addresses - List of token contract addresses to fetch.
+ *
+ * @example
  * ```tsx
- * const { data, loading, error, refetch } = useBalances({
- *   addresses: { evm: evmAddress, svm: svmAddress },
- * })
+ * const { data, loading, error } = useTokensData([
+ *   "0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
+ *   "0xC02aaa39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+ * ]);
  * ```
  */
-declare function useBalances(params: BalanceRequestParams | null): {
-    /** Latest fetched balance data */
-    data: BalanceResponse | null;
-    /** Whether the hook is currently fetching */
+declare function useTokensData(addresses: string[]): {
+    data: TokenInfo[];
     loading: boolean;
-    /** Error object if fetching failed */
     error: Error | null;
-    /** Manually trigger a refresh */
-    refetch: () => Promise<BalanceResponse | undefined>;
 };
 
-export { BalanceRequestParams, BalanceResponse, Stage, SwapQuoteParams, SwapQuoteResponse, useBalances, useExecuteOrder, useQuote, useTokenList };
+/**
+ * @fileoverview Centralized SWR hook for fetching user orders via the Swap SDK.
+ *
+ * ## Features
+ * - Shared global cache via SWR
+ * - Abort-safe concurrent requests
+ * - Accepts addresses via params or setAddresses()
+ * - No auto-refresh (manual control)
+ */
+
+/**
+ * Augment globalThis to safely hold a shared address ref.
+ */
+declare global {
+    var __ORDERS_ADDR_REF__: {
+        current: {
+            evmAddress?: string | null;
+            solAddress?: string | null;
+            suiAddress?: string | null;
+        } | null;
+    } | undefined;
+}
+/**
+ * Centralized SWR-powered hook for fetching user orders.
+ *
+ * ---
+ * ### Features
+ * - Shared global cache via SWR (no auto revalidation)
+ * - Manual `refetch()` support
+ * - Pass addresses directly or set later with `setAddresses()`
+ * - Safe abort for concurrent requests
+ *
+ * @example
+ * ```tsx
+ * const { data, loading, error, setAddresses, refetch } = useOrders();
+ *
+ * // Later, you can set addresses manually:
+ * useEffect(() => {
+ *   setAddresses({ evmAddress: "0x123..." });
+ * }, []);
+ *
+ * // Or pass them directly:
+ * const { data } = useOrders({ evmAddress: "0x123..." });
+ * ```
+ */
+declare function useOrders(initialAddresses?: {
+    evmAddress?: string | null;
+    solAddress?: string | null;
+    suiAddress?: string | null;
+}): {
+    data: ApiUserOrders | null | undefined;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+    setAddresses: (next: {
+        evmAddress?: string | null;
+        solAddress?: string | null;
+        suiAddress?: string | null;
+    }) => void;
+    readonly activeAddresses: {
+        evmAddress?: string | null;
+        solAddress?: string | null;
+        suiAddress?: string | null;
+    } | null;
+};
+
+export { BalanceRequestParams, BalanceResponse, SwapProvider, SwapQuoteParams, SwapQuoteResponse, useBalances, useExecuteTransaction, useOrders, useQuote, useSwap, useTokenList, useTokensData };