@rhea-finance/cross-chain-aggregation-dex 0.2.0 → 0.2.2

package/dist/index.d.mts

@@ -6,6 +6,10 @@ interface TokenInfo {
     symbol: string;
     decimals: number;
     chain: string;
+    /** Optional: Intents assetId (e.g., nep245:..., nep141:...) provided by backend */
+    assetId?: string;
+    /** Optional: Platform identifier ("nearIntents" | "okx" | "bitget") */
+    platform?: string;
 }
 interface Route {
     pools: PoolInfo[];
@@ -425,6 +429,148 @@ interface EvmChainAdapter {
      */
     getSigner?(): Promise<any>;
 }
+/** OKX DEX Aggregator API Quote response. */
+interface OkxQuoteResponse {
+    code?: string | number;
+    msg?: string;
+    data?: Array<{
+        chainIndex?: string;
+        fromToken: {
+            tokenSymbol?: string;
+            decimal: string | number;
+            tokenAddress?: string;
+            isHoneyPot?: boolean;
+            taxRate?: string;
+            [key: string]: any;
+        };
+        toToken: {
+            tokenSymbol?: string;
+            decimal: string | number;
+            tokenAddress?: string;
+            isHoneyPot?: boolean;
+            taxRate?: string;
+            [key: string]: any;
+        };
+        fromTokenAmount: string;
+        toTokenAmount: string;
+        estimateGasFee?: string;
+        priceImpactPercent?: string;
+        dexRouterList?: any[];
+        router?: string;
+        swapMode?: string;
+        tradeFee?: string;
+        contextSlot?: number;
+        fromAmount?: string;
+        toAmount?: string;
+        minToAmount?: string;
+        estimatedGas?: string;
+        priceImpact?: string;
+        routes?: any[];
+        [key: string]: any;
+    }>;
+}
+/** OKX DEX Aggregator API Swap response. */
+interface OkxSwapResponse {
+    code?: string | number;
+    msg?: string;
+    data?: {
+        transaction?: {
+            data?: string;
+            to?: string;
+            value?: string;
+            gas?: string;
+            gasPrice?: string;
+            estimateRevert?: boolean;
+        };
+        tx?: string | {
+            data?: string;
+            to?: string;
+            value?: string;
+            gas?: string;
+            gasPrice?: string;
+            estimateRevert?: boolean;
+            [key: string]: any;
+        };
+        data?: string;
+        to?: string;
+        value?: string;
+        gas?: string;
+        gasPrice?: string;
+        txHash?: string;
+        explorerUrl?: string;
+        estimateRevert?: boolean;
+        [key: string]: any;
+    } | Array<{
+        tx?: string | {
+            data?: string;
+            to?: string;
+            value?: string;
+            gas?: string;
+            gasPrice?: string;
+            estimateRevert?: boolean;
+            [key: string]: any;
+        };
+        transaction?: {
+            data?: string;
+            to?: string;
+            value?: string;
+            gas?: string;
+            gasPrice?: string;
+            estimateRevert?: boolean;
+        };
+        [key: string]: any;
+    }>;
+}
+/** Adapter for OKX DEX Aggregator API. */
+interface OkxAdapter {
+    quote(params: {
+        chainId: number;
+        tokenIn: string;
+        tokenOut: string;
+        amountIn: string;
+        slippage: number;
+        userAddress: string;
+        tokenInSymbol?: string;
+        tokenInDecimals?: number;
+        tokenOutSymbol?: string;
+        tokenOutDecimals?: number;
+    }): Promise<OkxQuoteResponse>;
+    /**
+     * Get final calldata for swap execution
+     */
+    swap(params: {
+        chainId: number;
+        tokenIn: string;
+        tokenOut: string;
+        amountIn: string;
+        minAmountOut?: string;
+        slippage: number;
+        fromAddress: string;
+        toAddress: string;
+        tokenInSymbol?: string;
+        tokenInDecimals?: number;
+        tokenOutSymbol?: string;
+        tokenOutDecimals?: number;
+    }): Promise<OkxSwapResponse>;
+    /**
+     * Get OKX approve transaction data
+     * Reference: https://web3.okx.com/zh-hans/onchain-os/dev-docs/trade-api/dex-approve-transaction
+     */
+    getApproveTransaction(params: {
+        chainId: number;
+        tokenAddress: string;
+        approveAmount: string;
+    }): Promise<{
+        code: string | number;
+        msg?: string;
+        data?: {
+            data: string;
+            dexContractAddress: string;
+            gasLimit: string;
+            gasPrice: string;
+        };
+    }>;
+}
 
 declare const logger: {
     debug: (...args: any[]) => void;
@@ -437,36 +583,39 @@ declare const logger: {
  * Unified error messages for the SDK
  * All error messages should be defined here for consistency
  */
+declare const TRANSACTION_EXECUTION_ERROR_MESSAGE = "Transaction execution error occurred. Please contact support";
 declare const ErrorMessages: {
-    readonly MISSING_PARAMS: "Required parameters missing";
-    readonly MISSING_TOKEN_ADDRESS: "Token address required";
-    readonly INVALID_TOKEN_ADDRESS: "Invalid token address";
-    readonly MISSING_USER_ADDRESS: "User address required";
-    readonly INVALID_USER_ADDRESS: "Invalid user address";
     readonly QUOTE_FAILED: "Failed to get quote";
-    readonly QUOTE_INVALID: "Invalid quote";
-    readonly QUOTE_NO_ROUTE: "No route found";
-    readonly QUOTE_EXPIRED: "Quote expired, please refresh";
     readonly EXECUTE_FAILED: "Transaction failed";
-    readonly EXECUTE_INVALID_QUOTE: "Invalid quote, please refresh";
-    readonly EXECUTE_INSUFFICIENT_BALANCE: "Insufficient balance";
-    readonly EXECUTE_INSUFFICIENT_LIQUIDITY: "Insufficient liquidity";
-    readonly EXECUTE_SLIPPAGE_TOO_HIGH: "Price changed, please refresh";
-    readonly NETWORK_ERROR: "Network error, please try again";
-    readonly API_ERROR: "Service temporarily unavailable";
-    readonly GAS_ESTIMATE_FAILED: "Unable to estimate transaction fee";
-    readonly GAS_PRICE_FAILED: "Failed to get transaction fee";
-    readonly TRANSACTION_REVERTED: "Transaction would fail, please refresh";
 };
 /**
  * Get user-friendly error message
  * Prioritizes API error messages, falls back to standardized messages
  */
 declare function getErrorMessage(error: string | undefined | null, fallback?: string): string;
+/**
+ * Process error message to determine if it's a user action or system error
+ * Returns original message for user actions, unified message for system errors
+ */
+declare function processErrorMessage(errorMessage: string): string;
+/**
+ * Normalize error for Intents API only
+ */
+declare function normalizeErrorForIntents(error: string | undefined | null): string;
 /**
  * Normalize common error patterns
  */
 declare function normalizeError(error: string | undefined | null): string;
+/**
+ * Format error message for intents API errors
+ * Simplified version that preserves detailed error messages while applying common formatting rules
+ */
+declare function formatErrorMessage({ error, fallbackMessage, originAsset, friendly, }: {
+    error?: any;
+    fallbackMessage?: string;
+    originAsset?: string;
+    friendly?: boolean;
+}): string;
 
 /** Set the SDK-wide bluechip token config used for NearIntents compatibility and intermediate routing. */
 declare function setBluechipTokensConfig(config: BluechipTokensConfig): void;
@@ -620,6 +769,27 @@ declare class BitgetRouter implements DexRouter {
     private normalizeEvmAddress;
 }
 
+interface OkxRouterConfig {
+    okxAdapter: OkxAdapter;
+    evmChainAdapter: EvmChainAdapter;
+    chainId: number;
+}
+/**
+ * OKX Router implementation for EVM chains
+ */
+declare class OkxRouter implements DexRouter {
+    private okxAdapter;
+    private evmChainAdapter;
+    private chainId;
+    constructor(config: OkxRouterConfig);
+    getCapabilities(): RouterCapabilities;
+    getSupportedChain(): "evm";
+    getChainId(): number;
+    quote(params: QuoteParams): Promise<QuoteResult>;
+    executeSwap(params: ExecuteParams): Promise<ExecuteResult>;
+    private normalizeEvmAddress;
+}
+
 /** Composite quote: optional NEAR DEX pre-swap + NearIntents quote. */
 
 interface CompleteQuoteParams {
@@ -670,6 +840,13 @@ interface CompleteQuoteConfig {
     currentUserAddress?: string;
     /** Optional function to check if token supports Intents (beyond bluechip tokens) */
     isIntentsSupportedToken?: (token: TokenInfo) => boolean;
+    /** Optional function to format error messages (for consistency with frontend error handling) */
+    formatErrorMessage?: (params: {
+        error?: any;
+        fallbackMessage?: string;
+        originAsset?: string;
+        friendly?: boolean;
+    }) => string;
 }
 /**
  * Build a complete quote with optional pre-swap
@@ -699,4 +876,4 @@ interface QuoteSameChainSwapResult {
  */
 declare function quoteSameChainSwap(params: QuoteSameChainSwapParams, dexRouters: DexRouter[]): Promise<QuoteSameChainSwapResult>;
 
-export { AggregateDexRouter, type AggregateDexRouterConfig, type BaseExecuteParams, type BaseQuoteParams, type BitgetAdapter, type BitgetQuoteResponse, BitgetRouter, type BitgetRouterConfig, type BitgetSwapResponse, type BluechipTokenConfig, type BluechipTokensConfig, type CompleteQuoteConfig, type CompleteQuoteParams, type CompleteQuoteResult, type ConfigAdapter, type DexRouter, ErrorMessages, type EvmChainAdapter, type ExecuteParams, type ExecuteResult, type FindPathAdapter, type FindPathResponse, type IntentsQuotationAdapter, type IntentsQuoteResult, type NearChainAdapter, NearSmartRouter, type NearSmartRouterConfig, type PoolInfo, type QuoteParams, type QuoteResult, type QuoteSameChainSwapParams, type QuoteSameChainSwapResult, type RecipientExecuteParams, type RecipientQuoteParams, type Route, type RouterCapabilities, type SimpleQuoteParams, type SupportedChain, type SwapMultiDexPathAdapter, type SwapMultiDexPathResponse, type TokenInfo, completeQuote, convertSlippageToBasisPoints, findBestBluechipToken, findBestEvmBluechipToken, formatGasString, formatGasToTgas, getBluechipTokensConfig, getErrorMessage, isEvmIntentsSupportedToken, isNearIntentsSupportedToken, logger, normalizeDestinationAsset, normalizeError, normalizeEvmAddress, normalizeTokenId, quoteSameChainSwap, requiresRecipient, requiresRecipientInExecute, selectBestQuote, setBluechipTokensConfig };
+export { AggregateDexRouter, type AggregateDexRouterConfig, type BaseExecuteParams, type BaseQuoteParams, type BitgetAdapter, type BitgetQuoteResponse, BitgetRouter, type BitgetRouterConfig, type BitgetSwapResponse, type BluechipTokenConfig, type BluechipTokensConfig, type CompleteQuoteConfig, type CompleteQuoteParams, type CompleteQuoteResult, type ConfigAdapter, type DexRouter, ErrorMessages, type EvmChainAdapter, type ExecuteParams, type ExecuteResult, type FindPathAdapter, type FindPathResponse, type IntentsQuotationAdapter, type IntentsQuoteResult, type NearChainAdapter, NearSmartRouter, type NearSmartRouterConfig, type OkxAdapter, type OkxQuoteResponse, OkxRouter, type OkxRouterConfig, type OkxSwapResponse, type PoolInfo, type QuoteParams, type QuoteResult, type QuoteSameChainSwapParams, type QuoteSameChainSwapResult, type RecipientExecuteParams, type RecipientQuoteParams, type Route, type RouterCapabilities, type SimpleQuoteParams, type SupportedChain, type SwapMultiDexPathAdapter, type SwapMultiDexPathResponse, TRANSACTION_EXECUTION_ERROR_MESSAGE, type TokenInfo, completeQuote, convertSlippageToBasisPoints, findBestBluechipToken, findBestEvmBluechipToken, formatErrorMessage, formatGasString, formatGasToTgas, getBluechipTokensConfig, getErrorMessage, isEvmIntentsSupportedToken, isNearIntentsSupportedToken, logger, normalizeDestinationAsset, normalizeError, normalizeErrorForIntents, normalizeEvmAddress, normalizeTokenId, processErrorMessage, quoteSameChainSwap, requiresRecipient, requiresRecipientInExecute, selectBestQuote, setBluechipTokensConfig };

package/dist/index.d.ts

@@ -6,6 +6,10 @@ interface TokenInfo {
     symbol: string;
     decimals: number;
     chain: string;
+    /** Optional: Intents assetId (e.g., nep245:..., nep141:...) provided by backend */
+    assetId?: string;
+    /** Optional: Platform identifier ("nearIntents" | "okx" | "bitget") */
+    platform?: string;
 }
 interface Route {
     pools: PoolInfo[];
@@ -425,6 +429,148 @@ interface EvmChainAdapter {
      */
     getSigner?(): Promise<any>;
 }
+/** OKX DEX Aggregator API Quote response. */
+interface OkxQuoteResponse {
+    code?: string | number;
+    msg?: string;
+    data?: Array<{
+        chainIndex?: string;
+        fromToken: {
+            tokenSymbol?: string;
+            decimal: string | number;
+            tokenAddress?: string;
+            isHoneyPot?: boolean;
+            taxRate?: string;
+            [key: string]: any;
+        };
+        toToken: {
+            tokenSymbol?: string;
+            decimal: string | number;
+            tokenAddress?: string;
+            isHoneyPot?: boolean;
+            taxRate?: string;
+            [key: string]: any;
+        };
+        fromTokenAmount: string;
+        toTokenAmount: string;
+        estimateGasFee?: string;
+        priceImpactPercent?: string;
+        dexRouterList?: any[];
+        router?: string;
+        swapMode?: string;
+        tradeFee?: string;
+        contextSlot?: number;
+        fromAmount?: string;
+        toAmount?: string;
+        minToAmount?: string;
+        estimatedGas?: string;
+        priceImpact?: string;
+        routes?: any[];
+        [key: string]: any;
+    }>;
+}
+/** OKX DEX Aggregator API Swap response. */
+interface OkxSwapResponse {
+    code?: string | number;
+    msg?: string;
+    data?: {
+        transaction?: {
+            data?: string;
+            to?: string;
+            value?: string;
+            gas?: string;
+            gasPrice?: string;
+            estimateRevert?: boolean;
+        };
+        tx?: string | {
+            data?: string;
+            to?: string;
+            value?: string;
+            gas?: string;
+            gasPrice?: string;
+            estimateRevert?: boolean;
+            [key: string]: any;
+        };
+        data?: string;
+        to?: string;
+        value?: string;
+        gas?: string;
+        gasPrice?: string;
+        txHash?: string;
+        explorerUrl?: string;
+        estimateRevert?: boolean;
+        [key: string]: any;
+    } | Array<{
+        tx?: string | {
+            data?: string;
+            to?: string;
+            value?: string;
+            gas?: string;
+            gasPrice?: string;
+            estimateRevert?: boolean;
+            [key: string]: any;
+        };
+        transaction?: {
+            data?: string;
+            to?: string;
+            value?: string;
+            gas?: string;
+            gasPrice?: string;
+            estimateRevert?: boolean;
+        };
+        [key: string]: any;
+    }>;
+}
+/** Adapter for OKX DEX Aggregator API. */
+interface OkxAdapter {
+    quote(params: {
+        chainId: number;
+        tokenIn: string;
+        tokenOut: string;
+        amountIn: string;
+        slippage: number;
+        userAddress: string;
+        tokenInSymbol?: string;
+        tokenInDecimals?: number;
+        tokenOutSymbol?: string;
+        tokenOutDecimals?: number;
+    }): Promise<OkxQuoteResponse>;
+    /**
+     * Get final calldata for swap execution
+     */
+    swap(params: {
+        chainId: number;
+        tokenIn: string;
+        tokenOut: string;
+        amountIn: string;
+        minAmountOut?: string;
+        slippage: number;
+        fromAddress: string;
+        toAddress: string;
+        tokenInSymbol?: string;
+        tokenInDecimals?: number;
+        tokenOutSymbol?: string;
+        tokenOutDecimals?: number;
+    }): Promise<OkxSwapResponse>;
+    /**
+     * Get OKX approve transaction data
+     * Reference: https://web3.okx.com/zh-hans/onchain-os/dev-docs/trade-api/dex-approve-transaction
+     */
+    getApproveTransaction(params: {
+        chainId: number;
+        tokenAddress: string;
+        approveAmount: string;
+    }): Promise<{
+        code: string | number;
+        msg?: string;
+        data?: {
+            data: string;
+            dexContractAddress: string;
+            gasLimit: string;
+            gasPrice: string;
+        };
+    }>;
+}
 
 declare const logger: {
     debug: (...args: any[]) => void;
@@ -437,36 +583,39 @@ declare const logger: {
  * Unified error messages for the SDK
  * All error messages should be defined here for consistency
  */
+declare const TRANSACTION_EXECUTION_ERROR_MESSAGE = "Transaction execution error occurred. Please contact support";
 declare const ErrorMessages: {
-    readonly MISSING_PARAMS: "Required parameters missing";
-    readonly MISSING_TOKEN_ADDRESS: "Token address required";
-    readonly INVALID_TOKEN_ADDRESS: "Invalid token address";
-    readonly MISSING_USER_ADDRESS: "User address required";
-    readonly INVALID_USER_ADDRESS: "Invalid user address";
     readonly QUOTE_FAILED: "Failed to get quote";
-    readonly QUOTE_INVALID: "Invalid quote";
-    readonly QUOTE_NO_ROUTE: "No route found";
-    readonly QUOTE_EXPIRED: "Quote expired, please refresh";
     readonly EXECUTE_FAILED: "Transaction failed";
-    readonly EXECUTE_INVALID_QUOTE: "Invalid quote, please refresh";
-    readonly EXECUTE_INSUFFICIENT_BALANCE: "Insufficient balance";
-    readonly EXECUTE_INSUFFICIENT_LIQUIDITY: "Insufficient liquidity";
-    readonly EXECUTE_SLIPPAGE_TOO_HIGH: "Price changed, please refresh";
-    readonly NETWORK_ERROR: "Network error, please try again";
-    readonly API_ERROR: "Service temporarily unavailable";
-    readonly GAS_ESTIMATE_FAILED: "Unable to estimate transaction fee";
-    readonly GAS_PRICE_FAILED: "Failed to get transaction fee";
-    readonly TRANSACTION_REVERTED: "Transaction would fail, please refresh";
 };
 /**
  * Get user-friendly error message
  * Prioritizes API error messages, falls back to standardized messages
  */
 declare function getErrorMessage(error: string | undefined | null, fallback?: string): string;
+/**
+ * Process error message to determine if it's a user action or system error
+ * Returns original message for user actions, unified message for system errors
+ */
+declare function processErrorMessage(errorMessage: string): string;
+/**
+ * Normalize error for Intents API only
+ */
+declare function normalizeErrorForIntents(error: string | undefined | null): string;
 /**
  * Normalize common error patterns
  */
 declare function normalizeError(error: string | undefined | null): string;
+/**
+ * Format error message for intents API errors
+ * Simplified version that preserves detailed error messages while applying common formatting rules
+ */
+declare function formatErrorMessage({ error, fallbackMessage, originAsset, friendly, }: {
+    error?: any;
+    fallbackMessage?: string;
+    originAsset?: string;
+    friendly?: boolean;
+}): string;
 
 /** Set the SDK-wide bluechip token config used for NearIntents compatibility and intermediate routing. */
 declare function setBluechipTokensConfig(config: BluechipTokensConfig): void;
@@ -620,6 +769,27 @@ declare class BitgetRouter implements DexRouter {
     private normalizeEvmAddress;
 }
 
+interface OkxRouterConfig {
+    okxAdapter: OkxAdapter;
+    evmChainAdapter: EvmChainAdapter;
+    chainId: number;
+}
+/**
+ * OKX Router implementation for EVM chains
+ */
+declare class OkxRouter implements DexRouter {
+    private okxAdapter;
+    private evmChainAdapter;
+    private chainId;
+    constructor(config: OkxRouterConfig);
+    getCapabilities(): RouterCapabilities;
+    getSupportedChain(): "evm";
+    getChainId(): number;
+    quote(params: QuoteParams): Promise<QuoteResult>;
+    executeSwap(params: ExecuteParams): Promise<ExecuteResult>;
+    private normalizeEvmAddress;
+}
+
 /** Composite quote: optional NEAR DEX pre-swap + NearIntents quote. */
 
 interface CompleteQuoteParams {
@@ -670,6 +840,13 @@ interface CompleteQuoteConfig {
     currentUserAddress?: string;
     /** Optional function to check if token supports Intents (beyond bluechip tokens) */
     isIntentsSupportedToken?: (token: TokenInfo) => boolean;
+    /** Optional function to format error messages (for consistency with frontend error handling) */
+    formatErrorMessage?: (params: {
+        error?: any;
+        fallbackMessage?: string;
+        originAsset?: string;
+        friendly?: boolean;
+    }) => string;
 }
 /**
  * Build a complete quote with optional pre-swap
@@ -699,4 +876,4 @@ interface QuoteSameChainSwapResult {
  */
 declare function quoteSameChainSwap(params: QuoteSameChainSwapParams, dexRouters: DexRouter[]): Promise<QuoteSameChainSwapResult>;
 
-export { AggregateDexRouter, type AggregateDexRouterConfig, type BaseExecuteParams, type BaseQuoteParams, type BitgetAdapter, type BitgetQuoteResponse, BitgetRouter, type BitgetRouterConfig, type BitgetSwapResponse, type BluechipTokenConfig, type BluechipTokensConfig, type CompleteQuoteConfig, type CompleteQuoteParams, type CompleteQuoteResult, type ConfigAdapter, type DexRouter, ErrorMessages, type EvmChainAdapter, type ExecuteParams, type ExecuteResult, type FindPathAdapter, type FindPathResponse, type IntentsQuotationAdapter, type IntentsQuoteResult, type NearChainAdapter, NearSmartRouter, type NearSmartRouterConfig, type PoolInfo, type QuoteParams, type QuoteResult, type QuoteSameChainSwapParams, type QuoteSameChainSwapResult, type RecipientExecuteParams, type RecipientQuoteParams, type Route, type RouterCapabilities, type SimpleQuoteParams, type SupportedChain, type SwapMultiDexPathAdapter, type SwapMultiDexPathResponse, type TokenInfo, completeQuote, convertSlippageToBasisPoints, findBestBluechipToken, findBestEvmBluechipToken, formatGasString, formatGasToTgas, getBluechipTokensConfig, getErrorMessage, isEvmIntentsSupportedToken, isNearIntentsSupportedToken, logger, normalizeDestinationAsset, normalizeError, normalizeEvmAddress, normalizeTokenId, quoteSameChainSwap, requiresRecipient, requiresRecipientInExecute, selectBestQuote, setBluechipTokensConfig };
+export { AggregateDexRouter, type AggregateDexRouterConfig, type BaseExecuteParams, type BaseQuoteParams, type BitgetAdapter, type BitgetQuoteResponse, BitgetRouter, type BitgetRouterConfig, type BitgetSwapResponse, type BluechipTokenConfig, type BluechipTokensConfig, type CompleteQuoteConfig, type CompleteQuoteParams, type CompleteQuoteResult, type ConfigAdapter, type DexRouter, ErrorMessages, type EvmChainAdapter, type ExecuteParams, type ExecuteResult, type FindPathAdapter, type FindPathResponse, type IntentsQuotationAdapter, type IntentsQuoteResult, type NearChainAdapter, NearSmartRouter, type NearSmartRouterConfig, type OkxAdapter, type OkxQuoteResponse, OkxRouter, type OkxRouterConfig, type OkxSwapResponse, type PoolInfo, type QuoteParams, type QuoteResult, type QuoteSameChainSwapParams, type QuoteSameChainSwapResult, type RecipientExecuteParams, type RecipientQuoteParams, type Route, type RouterCapabilities, type SimpleQuoteParams, type SupportedChain, type SwapMultiDexPathAdapter, type SwapMultiDexPathResponse, TRANSACTION_EXECUTION_ERROR_MESSAGE, type TokenInfo, completeQuote, convertSlippageToBasisPoints, findBestBluechipToken, findBestEvmBluechipToken, formatErrorMessage, formatGasString, formatGasToTgas, getBluechipTokensConfig, getErrorMessage, isEvmIntentsSupportedToken, isNearIntentsSupportedToken, logger, normalizeDestinationAsset, normalizeError, normalizeErrorForIntents, normalizeEvmAddress, normalizeTokenId, processErrorMessage, quoteSameChainSwap, requiresRecipient, requiresRecipientInExecute, selectBestQuote, setBluechipTokensConfig };