@wheelx-widget/widget 0.1.11 → 0.1.13

package/README.md

@@ -10,6 +10,7 @@ An open-source, framework-agnostic React widget for cross-chain token swaps and
 - ⚛️ **Framework Agnostic** — Works with any React framework (Next.js, Vite, Create React App, etc.)
 - 📦 **Tree-shakeable** — ESM + CJS builds with TypeScript declarations
 - 🔌 **Configurable Default Tokens** — Set default from/to chains and tokens
+- 📱 **Deep Link Support** — Wallet app launch support in WebView (React Native) — see [Deep Link Guide](./DEEP_LINK_GUIDE.md)
 
 ## Installation
 
@@ -105,6 +106,45 @@ Customize 14 visual tokens:
 </WheelXProvider>
 ```
 
+### API Base URL
+
+Override the default WheelX API endpoint. Useful for testing against a staging or development environment.
+
+```tsx
+<WheelXProvider config={{
+  apiBaseUrl: 'https://dev-api.wheelx.fi'  // Default: 'https://api.wheelx.fi'
+}}>
+  <WheelXWidget />
+</WheelXProvider>
+```
+
+### Fixed Recipient Address (Different Address)
+
+Configure fixed recipient addresses for EVM or Solana chains. When set, the widget will:
+
+- **Display the configured address** in the To field instead of showing "Connect Wallet"
+- **Query the token balance** of the configured address
+- **Skip wallet connection** for the target chain (only the source chain wallet is required for signing)
+- **Show GetGas** when the configured address has insufficient native token balance
+
+This is useful for exchange or merchant scenarios where funds should always be sent to a specific address regardless of which wallet the user connects.
+
+**Priority order for recipient address:**
+1. Configured fixed address (`evmDifferentAddress` / `solanaDifferentAddress`)
+2. User manually entered different address (via Different Address dialog)
+3. Connected wallet address
+
+```tsx
+<WheelXProvider config={{
+  evmDifferentAddress: '0xAbCdEf1234567890...',  // Fixed recipient for EVM chains (0x format)
+  solanaDifferentAddress: '9zQX...'               // Fixed recipient for Solana chains (base58 format)
+}}>
+  <WheelXWidget />
+</WheelXProvider>
+```
+
+> **Note:** You can configure one, both, or neither. The widget will only use the relevant one based on the selected To chain.
+
 ## API Reference
 
 ### `<WheelXProvider>`
@@ -129,6 +169,10 @@ The main trading widget component.
 ```typescript
 interface WidgetConfig {
   theme?: Partial<WidgetTheme>
+
+  /** API base URL. Default 'https://api.wheelx.fi' */
+  apiBaseUrl?: string
+
   from?: {
     chains?: number[]
     defaultChainId?: number
@@ -147,6 +191,12 @@ interface WidgetConfig {
     getCurrentPathname?: () => string
   }
   dynamicEnvironmentId?: string
+  onDeepLink?: (url: string) => void  // See Deep Link Guide for WebView environments
+
+  /** Fixed recipient address for EVM chains (0x format). Takes priority over wallet address and manual different address */
+  evmDifferentAddress?: string
+  /** Fixed recipient address for Solana chains (base58 format). Takes priority over wallet address and manual different address */
+  solanaDifferentAddress?: string
 }
 ```
 
@@ -168,6 +218,8 @@ interface WidgetTheme {
   normalButtonText: string
   disabledButtonBg: string
   disabledButtonText: string
+  /** Color palette for the GetGas switch component. e.g. 'purple', 'blue', 'green'. Default: 'purple' */
+  getGasSwitchColorPalette?: string
 }
 ```
 
@@ -179,6 +231,17 @@ A demo `https://widget.wheelx.fi`
 
 This widget connects to the WheelX API at `https://api.wheelx.fi`. The API domain is not configurable.
 
+## React Native / WebView Integration
+
+If you embed the Widget into a React Native WebView, additional configuration is required to properly launch wallet apps.
+
+Please refer to: **[Mobile Wallet Launch Guide (DEEP_LINK_GUIDE.md)](./DEEP_LINK_GUIDE.md)**
+
+In short, three things are required:
+1. Add `onMessage` listener in the WebView
+2. Configure `<queries>` declaration in Android's `AndroidManifest.xml`
+3. Configure `LSApplicationQueriesSchemes` in iOS's `Info.plist`
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -27,9 +27,17 @@ interface WidgetTheme {
     normalButtonText: string;
     disabledButtonBg: string;
     disabledButtonText: string;
+    /**
+     * GetGas Switch colorPalette — accepts Chakra UI color palette names
+     * e.g. 'gray', 'red', 'orange', 'yellow', 'green', 'teal', 'cyan', 'blue', 'purple', 'pink'
+     * @default 'purple'
+     */
+    getGasSwitchColorPalette?: string;
 }
 interface WidgetConfig {
     theme?: Partial<WidgetTheme>;
+    /** API base URL. Default 'https://api.wheelx.fi' */
+    apiBaseUrl?: string;
     from?: {
         chains?: number[];
         defaultChainId?: number;
@@ -54,6 +62,18 @@ interface WidgetConfig {
         getCurrentPathname?: () => string;
     };
     dynamicEnvironmentId?: string;
+    /**
+     * 深度链接处理器。当 widget 在 WebView 中运行时，用于将钱包的 deep link URL
+     * 传递给宿主 App 处理（如通过 Linking.openURL 打开钱包 App）。
+     *
+     * 如果不提供此回调，widget 会自动尝试通过 ReactNativeWebView.postMessage
+     * 或自定义 DOM 事件进行通信。
+     */
+    onDeepLink?: (url: string) => void;
+    /** EVM链固定收款异地址（0x格式）。配置后，to网络为EVM链时优先使用此地址 */
+    evmDifferentAddress?: string;
+    /** Solana链固定收款异地址（base58格式）。配置后，to网络为Solana链时优先使用此地址 */
+    solanaDifferentAddress?: string;
 }
 
 interface WheelXProviderProps {
@@ -101,6 +121,7 @@ interface QuoteRequest {
     amount: string;
     slippage?: number;
     to_platform_id: number;
+    sponsor_gas?: boolean;
 }
 type QuoteErrorType = 'business_error' | 'http_error' | 'network_error' | 'timeout' | 'unknown_error';
 interface QuoteMutationError extends Error {
@@ -147,6 +168,7 @@ type ChainInfo = {
     inbound: boolean;
     is_testnet?: boolean;
     platform_id?: number;
+    support_sponsor_gas?: boolean;
 };
 interface Prediction {
     chains: ChainInfo[];
@@ -160,6 +182,7 @@ interface SlippagePolicy {
     min_slippage: number;
     max_slippage: number;
     refresh_interval: number;
+    /** Number of quote rounds after which to show a transaction-failure warning. Defaults to 2. */
     notice_rounds?: number;
 }
 interface ChainsAndTokens {
@@ -312,19 +335,61 @@ declare const useChainsStore: zustand.UseBoundStore<zustand.StoreApi<ChainsStore
 declare const useTokensStore: zustand.UseBoundStore<zustand.StoreApi<TokenStore>>;
 
 /**
- * Hook to get EVM wallet address with fallback to saved address.
+ * Hook to get EVM wallet address with fallback to saved address
+ * This ensures that when a user first connects an EVM wallet (e.g., OKX),
+ * then connects a Solana wallet (e.g., MetaMask), the EVM address remains
+ * consistent with the first connected wallet.
  *
- * Priority: saved evmWalletAddress > current wagmi address (only when store says connected).
+ * @returns The EVM wallet address (saved address or current wagmi address)
+ */
+declare const useEvmAddress: () => `0x${string}` | undefined;
+
+/**
+ * Platform detection utilities for WebView environments.
+ * Used to detect and intercept deep links when the widget runs inside
+ * a WebView (e.g., React Native, Android WebView, WKWebView).
+ */
+/** Check if running inside a React Native WebView */
+declare const isReactNativeWebView: () => boolean;
+/** Check if running in any WebView (Android/iOS) */
+declare const isWebView: () => boolean;
+/** Check if running on mobile device */
+declare const isMobileDevice: () => boolean;
+/**
+ * Check if we should intercept deep links.
  *
- * CRITICAL: The store is the single source of truth for connection state.
- * After user disconnects, even if wagmi briefly shows connected (e.g. due to
- * DynamicWagmiConnector reconnecting), we must NOT use wagmi's address as
- * fallback — otherwise the UI will continue to show address/balance info
- * after the user has explicitly disconnected.
+ * We ONLY intercept in React Native WebView because that's the only WebView
+ * environment where we have a reliable forwarding mechanism (postMessage).
  *
- * @returns The EVM wallet address, or undefined if not connected.
+ * Regular browsers (Chrome, Safari) handle deep links natively — we must not
+ * interfere there. Generic Android/iOS WebViews may or may not handle deep
+ * links depending on host app configuration, so we leave them alone.
  */
-declare const useEvmAddress: () => `0x${string}` | undefined;
+declare const shouldInterceptDeepLinks: () => boolean;
+/** Check if URL is a deep link (non-http/https scheme) */
+declare const isDeepLinkUrl: (url: string) => boolean;
+/**
+ * Known wallet universal link (https) domains.
+ * Wallet libraries (e.g. Dynamic SDK) may prefer universal links over
+ * custom URL schemes. These https:// URLs look like normal web pages but
+ * are designed to open wallet apps via OS-level app link resolution.
+ * In WebView environments, we must intercept them too.
+ */
+declare const KNOWN_WALLET_UNIVERSAL_LINKS: Record<string, string>;
+/**
+ * Convert a wallet universal link to its corresponding deep-link scheme
+ * so that `Linking.openURL()` on React Native opens the wallet app
+ * directly instead of routing through the system browser.
+ *
+ * For example:
+ *   https://phantom.app/ul/v1/connect?...  →  phantom://ul/v1/connect?...
+ */
+declare const convertToDeepLink: (url: string) => string;
+/**
+ * Check if URL is a deep link (non-http/https scheme) OR a known wallet
+ * universal link that should be intercepted and forwarded to native.
+ */
+declare const isWalletRelatedUrl: (url: string) => boolean;
 
 interface WalletStore {
     isEthWalletConnected: boolean;
@@ -343,10 +408,8 @@ interface WalletStore {
     setIsEvmWalletMetamask: (isEvmWalletMetamask: boolean) => void;
     isLoggingOut: boolean;
     setIsLoggingOut: (isLoggingOut: boolean) => void;
-    /** Timestamp (ms) of the most recent manual disconnect. Used to guard
-     *  against DynamicWagmiConnector auto-reconnecting right after logout. */
     lastDisconnectTimestamp: number;
-    setLastDisconnectTimestamp: (ts: number) => void;
+    setLastDisconnectTimestamp: (timestamp: number) => void;
 }
 declare const useWalletConnectedStore: zustand.UseBoundStore<zustand.StoreApi<WalletStore>>;
 
@@ -360,4 +423,4 @@ declare const useDifferentAddressStore: zustand.UseBoundStore<zustand.StoreApi<D
 
 declare const useSyncWalletConnectedStore: () => void;
 
-export { type ChainInfo, type ChainsAndTokens, type FeeLevel, type QuoteErrorType, type QuoteInfo, type QuoteMutationError, type QuoteRequest, type QuoteRequestWithToTokenDecimals, type RefetchQuoteParams, type SlippagePolicy, type TokenConfig, type TokenInfo, type TxInfoProps, WheelXProvider, type WheelXProviderProps, WheelXWidget, type WheelXWidgetProps, type WidgetConfig, type WidgetTheme, WidgetThemeProvider, defaultTheme, getChainsAndTokens, initialQuoteInfo, mergeTokensWithCompositeKey, useChainsAndTokens, useChainsStore, useDifferentAddressStore, useEvmAddress, useGuardChain, useInitSwapAndBridgeState, useRefreshLoading, useResetSwapAndBridgeState, useSwapAndBridgeContextStore, useSyncWalletConnectedStore, useTokenBalance, useTokensStore, useTxStateContextStore, useWalletConnectedStore, useWidgetTheme };
+export { type ChainInfo, type ChainsAndTokens, type FeeLevel, KNOWN_WALLET_UNIVERSAL_LINKS, type QuoteErrorType, type QuoteInfo, type QuoteMutationError, type QuoteRequest, type QuoteRequestWithToTokenDecimals, type RefetchQuoteParams, type SlippagePolicy, type TokenConfig, type TokenInfo, type TxInfoProps, WheelXProvider, type WheelXProviderProps, WheelXWidget, type WheelXWidgetProps, type WidgetConfig, type WidgetTheme, WidgetThemeProvider, convertToDeepLink, defaultTheme, getChainsAndTokens, initialQuoteInfo, isDeepLinkUrl, isMobileDevice, isReactNativeWebView, isWalletRelatedUrl, isWebView, mergeTokensWithCompositeKey, shouldInterceptDeepLinks, useChainsAndTokens, useChainsStore, useDifferentAddressStore, useEvmAddress, useGuardChain, useInitSwapAndBridgeState, useRefreshLoading, useResetSwapAndBridgeState, useSwapAndBridgeContextStore, useSyncWalletConnectedStore, useTokenBalance, useTokensStore, useTxStateContextStore, useWalletConnectedStore, useWidgetTheme };

package/dist/index.d.ts

@@ -27,9 +27,17 @@ interface WidgetTheme {
     normalButtonText: string;
     disabledButtonBg: string;
     disabledButtonText: string;
+    /**
+     * GetGas Switch colorPalette — accepts Chakra UI color palette names
+     * e.g. 'gray', 'red', 'orange', 'yellow', 'green', 'teal', 'cyan', 'blue', 'purple', 'pink'
+     * @default 'purple'
+     */
+    getGasSwitchColorPalette?: string;
 }
 interface WidgetConfig {
     theme?: Partial<WidgetTheme>;
+    /** API base URL. Default 'https://api.wheelx.fi' */
+    apiBaseUrl?: string;
     from?: {
         chains?: number[];
         defaultChainId?: number;
@@ -54,6 +62,18 @@ interface WidgetConfig {
         getCurrentPathname?: () => string;
     };
     dynamicEnvironmentId?: string;
+    /**
+     * 深度链接处理器。当 widget 在 WebView 中运行时，用于将钱包的 deep link URL
+     * 传递给宿主 App 处理（如通过 Linking.openURL 打开钱包 App）。
+     *
+     * 如果不提供此回调，widget 会自动尝试通过 ReactNativeWebView.postMessage
+     * 或自定义 DOM 事件进行通信。
+     */
+    onDeepLink?: (url: string) => void;
+    /** EVM链固定收款异地址（0x格式）。配置后，to网络为EVM链时优先使用此地址 */
+    evmDifferentAddress?: string;
+    /** Solana链固定收款异地址（base58格式）。配置后，to网络为Solana链时优先使用此地址 */
+    solanaDifferentAddress?: string;
 }
 
 interface WheelXProviderProps {
@@ -101,6 +121,7 @@ interface QuoteRequest {
     amount: string;
     slippage?: number;
     to_platform_id: number;
+    sponsor_gas?: boolean;
 }
 type QuoteErrorType = 'business_error' | 'http_error' | 'network_error' | 'timeout' | 'unknown_error';
 interface QuoteMutationError extends Error {
@@ -147,6 +168,7 @@ type ChainInfo = {
     inbound: boolean;
     is_testnet?: boolean;
     platform_id?: number;
+    support_sponsor_gas?: boolean;
 };
 interface Prediction {
     chains: ChainInfo[];
@@ -160,6 +182,7 @@ interface SlippagePolicy {
     min_slippage: number;
     max_slippage: number;
     refresh_interval: number;
+    /** Number of quote rounds after which to show a transaction-failure warning. Defaults to 2. */
     notice_rounds?: number;
 }
 interface ChainsAndTokens {
@@ -312,19 +335,61 @@ declare const useChainsStore: zustand.UseBoundStore<zustand.StoreApi<ChainsStore
 declare const useTokensStore: zustand.UseBoundStore<zustand.StoreApi<TokenStore>>;
 
 /**
- * Hook to get EVM wallet address with fallback to saved address.
+ * Hook to get EVM wallet address with fallback to saved address
+ * This ensures that when a user first connects an EVM wallet (e.g., OKX),
+ * then connects a Solana wallet (e.g., MetaMask), the EVM address remains
+ * consistent with the first connected wallet.
  *
- * Priority: saved evmWalletAddress > current wagmi address (only when store says connected).
+ * @returns The EVM wallet address (saved address or current wagmi address)
+ */
+declare const useEvmAddress: () => `0x${string}` | undefined;
+
+/**
+ * Platform detection utilities for WebView environments.
+ * Used to detect and intercept deep links when the widget runs inside
+ * a WebView (e.g., React Native, Android WebView, WKWebView).
+ */
+/** Check if running inside a React Native WebView */
+declare const isReactNativeWebView: () => boolean;
+/** Check if running in any WebView (Android/iOS) */
+declare const isWebView: () => boolean;
+/** Check if running on mobile device */
+declare const isMobileDevice: () => boolean;
+/**
+ * Check if we should intercept deep links.
  *
- * CRITICAL: The store is the single source of truth for connection state.
- * After user disconnects, even if wagmi briefly shows connected (e.g. due to
- * DynamicWagmiConnector reconnecting), we must NOT use wagmi's address as
- * fallback — otherwise the UI will continue to show address/balance info
- * after the user has explicitly disconnected.
+ * We ONLY intercept in React Native WebView because that's the only WebView
+ * environment where we have a reliable forwarding mechanism (postMessage).
  *
- * @returns The EVM wallet address, or undefined if not connected.
+ * Regular browsers (Chrome, Safari) handle deep links natively — we must not
+ * interfere there. Generic Android/iOS WebViews may or may not handle deep
+ * links depending on host app configuration, so we leave them alone.
  */
-declare const useEvmAddress: () => `0x${string}` | undefined;
+declare const shouldInterceptDeepLinks: () => boolean;
+/** Check if URL is a deep link (non-http/https scheme) */
+declare const isDeepLinkUrl: (url: string) => boolean;
+/**
+ * Known wallet universal link (https) domains.
+ * Wallet libraries (e.g. Dynamic SDK) may prefer universal links over
+ * custom URL schemes. These https:// URLs look like normal web pages but
+ * are designed to open wallet apps via OS-level app link resolution.
+ * In WebView environments, we must intercept them too.
+ */
+declare const KNOWN_WALLET_UNIVERSAL_LINKS: Record<string, string>;
+/**
+ * Convert a wallet universal link to its corresponding deep-link scheme
+ * so that `Linking.openURL()` on React Native opens the wallet app
+ * directly instead of routing through the system browser.
+ *
+ * For example:
+ *   https://phantom.app/ul/v1/connect?...  →  phantom://ul/v1/connect?...
+ */
+declare const convertToDeepLink: (url: string) => string;
+/**
+ * Check if URL is a deep link (non-http/https scheme) OR a known wallet
+ * universal link that should be intercepted and forwarded to native.
+ */
+declare const isWalletRelatedUrl: (url: string) => boolean;
 
 interface WalletStore {
     isEthWalletConnected: boolean;
@@ -343,10 +408,8 @@ interface WalletStore {
     setIsEvmWalletMetamask: (isEvmWalletMetamask: boolean) => void;
     isLoggingOut: boolean;
     setIsLoggingOut: (isLoggingOut: boolean) => void;
-    /** Timestamp (ms) of the most recent manual disconnect. Used to guard
-     *  against DynamicWagmiConnector auto-reconnecting right after logout. */
     lastDisconnectTimestamp: number;
-    setLastDisconnectTimestamp: (ts: number) => void;
+    setLastDisconnectTimestamp: (timestamp: number) => void;
 }
 declare const useWalletConnectedStore: zustand.UseBoundStore<zustand.StoreApi<WalletStore>>;
 
@@ -360,4 +423,4 @@ declare const useDifferentAddressStore: zustand.UseBoundStore<zustand.StoreApi<D
 
 declare const useSyncWalletConnectedStore: () => void;
 
-export { type ChainInfo, type ChainsAndTokens, type FeeLevel, type QuoteErrorType, type QuoteInfo, type QuoteMutationError, type QuoteRequest, type QuoteRequestWithToTokenDecimals, type RefetchQuoteParams, type SlippagePolicy, type TokenConfig, type TokenInfo, type TxInfoProps, WheelXProvider, type WheelXProviderProps, WheelXWidget, type WheelXWidgetProps, type WidgetConfig, type WidgetTheme, WidgetThemeProvider, defaultTheme, getChainsAndTokens, initialQuoteInfo, mergeTokensWithCompositeKey, useChainsAndTokens, useChainsStore, useDifferentAddressStore, useEvmAddress, useGuardChain, useInitSwapAndBridgeState, useRefreshLoading, useResetSwapAndBridgeState, useSwapAndBridgeContextStore, useSyncWalletConnectedStore, useTokenBalance, useTokensStore, useTxStateContextStore, useWalletConnectedStore, useWidgetTheme };
+export { type ChainInfo, type ChainsAndTokens, type FeeLevel, KNOWN_WALLET_UNIVERSAL_LINKS, type QuoteErrorType, type QuoteInfo, type QuoteMutationError, type QuoteRequest, type QuoteRequestWithToTokenDecimals, type RefetchQuoteParams, type SlippagePolicy, type TokenConfig, type TokenInfo, type TxInfoProps, WheelXProvider, type WheelXProviderProps, WheelXWidget, type WheelXWidgetProps, type WidgetConfig, type WidgetTheme, WidgetThemeProvider, convertToDeepLink, defaultTheme, getChainsAndTokens, initialQuoteInfo, isDeepLinkUrl, isMobileDevice, isReactNativeWebView, isWalletRelatedUrl, isWebView, mergeTokensWithCompositeKey, shouldInterceptDeepLinks, useChainsAndTokens, useChainsStore, useDifferentAddressStore, useEvmAddress, useGuardChain, useInitSwapAndBridgeState, useRefreshLoading, useResetSwapAndBridgeState, useSwapAndBridgeContextStore, useSyncWalletConnectedStore, useTokenBalance, useTokensStore, useTxStateContextStore, useWalletConnectedStore, useWidgetTheme };