@cowprotocol/sdk-bridging 0.3.0-beta.0 → 0.3.0

package/README.md

@@ -149,6 +149,271 @@ if (confirm(`You will get at least: ${buyAmount}, ok?`)) {
 }
 ```
 
+## Multi-Provider Quote Comparison
+
+The `getMultiQuotes()` method allows you to get quotes from multiple bridge providers simultaneously, with support for progressive results as each provider responds.
+
+### Basic Multi-Quote Usage
+
+```typescript
+import { MultiQuoteRequest } from '@cowprotocol/sdk-bridging'
+
+const multiQuoteRequest: MultiQuoteRequest = {
+  quoteBridgeRequest: parameters, // Same parameters as above
+  providerDappIds: ['provider1', 'provider2'], // Optional: specify which providers to query
+  advancedSettings: {
+    slippageBps: 100, // 1% slippage tolerance
+  },
+  options: {
+    totalTimeout: 15000,        // 15 seconds total timeout
+    providerTimeout: 8000, // 8 seconds per provider timeout
+  }
+}
+
+// Get quotes from all providers
+const results = await sdk.bridging.getMultiQuotes(multiQuoteRequest)
+
+results.forEach((result) => {
+  if (result.quote) {
+    console.log(`Quote from ${result.providerDappId}:`, result.quote)
+  } else {
+    console.log(`Error from ${result.providerDappId}:`, result.error?.message)
+  }
+})
+```
+
+### Progressive Quote Results
+
+For better user experience, you can receive quotes progressively as each provider responds:
+
+```typescript
+const progressiveResults: MultiQuoteResult[] = []
+
+const multiQuoteRequest: MultiQuoteRequest = {
+  quoteBridgeRequest: parameters,
+  options: {
+    // Receive quotes as they arrive
+    onQuoteResult: (result) => {
+      progressiveResults.push(result)
+
+      if (result.quote) {
+        console.log(`✅ Quote received from ${result.providerDappId}`)
+        // Update UI immediately with the new quote
+        displayQuoteInUI(result)
+      } else {
+        console.log(`❌ Error from ${result.providerDappId}: ${result.error?.message}`)
+      }
+    },
+    totalTimeout: 20000,       // 20 seconds total timeout
+    providerTimeout: 5000 // 5 seconds per provider timeout
+  }
+}
+
+// This will return all results once completed (or timed out)
+const finalResults = await sdk.bridging.getMultiQuotes(multiQuoteRequest)
+
+console.log(`Received ${finalResults.filter(r => r.quote).length} successful quotes out of ${finalResults.length} providers`)
+```
+
+### Advanced Multi-Quote Example
+
+```typescript
+// Example with React state management
+const [quotes, setQuotes] = useState<MultiQuoteResult[]>([])
+const [isLoading, setIsLoading] = useState(false)
+
+const fetchQuotes = async () => {
+  setIsLoading(true)
+  setQuotes([])
+
+  try {
+    const results = await sdk.bridging.getMultiQuotes({
+      quoteBridgeRequest: parameters,
+      options: {
+        onQuoteResult: (result) => {
+          // Add quote to state as it arrives
+          setQuotes(prev => [...prev, result])
+
+          if (result.quote) {
+            // Optional: Auto-select best quote
+            if (isBestQuote(result)) {
+              selectQuote(result)
+            }
+          } else {
+            // Handle errors
+            console.error(`Provider ${result.providerDappId} failed:`, result.error?.message)
+            // Update UI to show provider is unavailable
+            setProviderStatus(prev => ({
+              ...prev,
+              [result.providerDappId]: 'error'
+            }))
+          }
+        },
+        totalTimeout: 30000,       // 30 seconds total timeout
+        providerTimeout: 10000 // 10 seconds per provider timeout
+      }
+    })
+
+    console.log('All quotes completed:', results)
+  } catch (error) {
+    console.error('Multi-quote failed:', error)
+  } finally {
+    setIsLoading(false)
+  }
+}
+
+// Helper function to determine best quote
+const isBestQuote = (result: MultiQuoteResult): boolean => {
+  if (!result.quote) return false
+
+  const currentBest = quotes.find(q => q.quote)
+  if (!currentBest?.quote) return true
+
+  // Compare buy amounts after slippage
+  return result.quote.bridge.amountsAndCosts.afterSlippage.buyAmount >
+         currentBest.quote.bridge.amountsAndCosts.afterSlippage.buyAmount
+}
+```
+
+### Timeout Configuration
+
+The `getMultiQuotes()` method supports two types of timeouts for fine-grained control:
+
+```typescript
+const results = await sdk.bridging.getMultiQuotes({
+  quoteBridgeRequest: parameters,
+  options: {
+    // Global timeout: Maximum time to wait for all providers to complete
+    totalTimeout: 30000,        // 30 seconds (default)
+
+    // Individual provider timeout: Maximum time each provider has to respond
+    providerTimeout: 15000, // 15 seconds (default)
+
+    onQuoteResult: (result) => {
+      // Handle progressive results
+      console.log(`Received result from ${result.providerDappId}`);
+    }
+  }
+});
+```
+
+**How timeouts work:**
+- `providerTimeout`: Each provider has this amount of time to complete their quote request. If exceeded, that provider returns a timeout error.
+- `totalTimeout`: The total time to wait for all providers. After this time, any remaining providers are marked as timed out.
+- Providers that complete within their individual timeout but after the global timeout will still be included in the final results.
+
+## Best Quote Selection
+
+The `getBestQuote()` method provides an optimized way to get only the best quote from multiple providers, with progressive updates as better quotes are found. This is perfect for applications that only need the single best result.
+
+### Basic Best Quote Usage
+
+```typescript
+import { MultiQuoteRequest } from '@cowprotocol/sdk-bridging'
+
+// Get the best quote from all available providers
+const bestQuote = await sdk.bridging.getBestQuote({
+  quoteBridgeRequest: parameters, // Same parameters as above
+  providerDappIds: ['provider1', 'provider2'], // Optional: specify which providers to query
+  advancedSettings: {
+    slippageBps: 100, // 1% slippage tolerance
+  },
+  options: {
+    totalTimeout: 15000,       // 15 seconds total timeout
+    providerTimeout: 8000,     // 8 seconds per provider timeout
+  }
+})
+
+if (bestQuote?.quote) {
+  console.log(`Best quote from ${bestQuote.providerDappId}:`, bestQuote.quote)
+  const { buyAmount } = bestQuote.quote.bridge.amountsAndCosts.afterSlippage
+  console.log(`You will receive: ${buyAmount} tokens`)
+} else if (bestQuote?.error) {
+  console.log('All providers failed, first error:', bestQuote.error.message)
+} else {
+  console.log('No quotes available')
+}
+```
+
+### Progressive Best Quote Updates
+
+For real-time updates, you can receive notifications each time a better quote is found:
+
+```typescript
+let currentBest: MultiQuoteResult | null = null
+
+const bestQuote = await sdk.bridging.getBestQuote({
+  quoteBridgeRequest: parameters,
+  options: {
+    // Called whenever a better quote is found
+    onQuoteResult: (result) => {
+      currentBest = result
+      console.log(`🚀 New best quote from ${result.providerDappId}!`)
+
+      if (result.quote) {
+        const buyAmount = result.quote.bridge.amountsAndCosts.afterSlippage.buyAmount
+        console.log(`Better quote found: ${buyAmount} tokens`)
+
+        // Update UI immediately with the new best quote
+        updateBestQuoteInUI(result)
+      }
+    },
+    totalTimeout: 20000,      // 20 seconds total timeout
+    providerTimeout: 5000     // 5 seconds per provider timeout
+  }
+})
+
+console.log('Final best quote:', bestQuote)
+```
+
+### Error Handling with Best Quote
+
+When all providers fail, `getBestQuote()` returns the first provider's error:
+
+```typescript
+const bestQuote = await sdk.bridging.getBestQuote({
+  quoteBridgeRequest: parameters,
+  options: {
+    onQuoteResult: (result) => {
+      // Only called for successful quotes that are better than current best
+      console.log(`✅ Better quote from ${result.providerDappId}`)
+    }
+  }
+})
+
+if (bestQuote?.quote) {
+  // Success: we have the best available quote
+  console.log('Best quote found:', bestQuote.quote)
+} else if (bestQuote?.error) {
+  // All providers failed, this is the first error encountered
+  console.error('All providers failed:', bestQuote.error.message)
+  console.log('Failed provider:', bestQuote.providerDappId)
+} else {
+  // This should never happen, but good to handle
+  console.log('No quote or error returned')
+}
+```
+
+### Comparison: getBestQuote vs getMultiQuotes
+
+| Feature | `getBestQuote()` | `getMultiQuotes()` |
+|---------|------------------|-------------------|
+| **Returns** | Single best result | Array of all results |
+| **Progressive Callbacks** | Only for better quotes | For all results (success & error) |
+| **Error Handling** | Returns first error if all fail | Returns all errors in array |
+| **Performance** | Optimized for best result only | Returns complete data set |
+| **Use Case** | When you only need the best quote | When you need to compare all options |
+
+Choose `getBestQuote()` when:
+- You only need the single best quote
+- You want real-time updates as better quotes are found
+- You want to minimize callback overhead (only called for improvements)
+
+Choose `getMultiQuotes()` when:
+- You need to display all available options to users
+- You want to analyze all provider responses
+- You need to show provider-specific errors or statuses
+
 ## Supported Bridge Providers
 
 - Additional bridge providers are being integrated

package/dist/index.d.mts

@@ -5,6 +5,29 @@ import { QuoterParameters, TraderParameters, TradeOptionalParameters, QuoteAndPo
 import { AccountAddress, SignerLike, AbstractProviderAdapter } from '@cowprotocol/sdk-common';
 import { CowShedSdk, CowShedSdkOptions } from '@cowprotocol/sdk-cow-shed';
 
+declare enum BridgeQuoteErrors {
+    NO_INTERMEDIATE_TOKENS = "NO_INTERMEDIATE_TOKENS",
+    API_ERROR = "API_ERROR",
+    INVALID_API_JSON_RESPONSE = "INVALID_API_JSON_RESPONSE",
+    ONLY_SELL_ORDER_SUPPORTED = "ONLY_SELL_ORDER_SUPPORTED",
+    TX_BUILD_ERROR = "TX_BUILD_ERROR",
+    QUOTE_ERROR = "QUOTE_ERROR",
+    NO_ROUTES = "NO_ROUTES",
+    INVALID_BRIDGE = "INVALID_BRIDGE"
+}
+declare class BridgeProviderQuoteError extends Error {
+    readonly context?: unknown | undefined;
+    constructor(message: BridgeQuoteErrors, context?: unknown | undefined);
+}
+declare class BridgeProviderError extends Error {
+    readonly context: unknown;
+    constructor(message: string, context: unknown);
+}
+declare class BridgeOrderParsingError extends Error {
+    readonly context?: unknown | undefined;
+    constructor(message: string, context?: unknown | undefined);
+}
+
 interface BridgeProviderInfo {
     name: string;
     logoUrl: string;
@@ -327,28 +350,64 @@ interface CrossChainOrder {
     tradeTxHash: string;
     explorerUrl?: string;
 }
-
-declare enum BridgeQuoteErrors {
-    NO_INTERMEDIATE_TOKENS = "NO_INTERMEDIATE_TOKENS",
-    API_ERROR = "API_ERROR",
-    INVALID_API_JSON_RESPONSE = "INVALID_API_JSON_RESPONSE",
-    ONLY_SELL_ORDER_SUPPORTED = "ONLY_SELL_ORDER_SUPPORTED",
-    TX_BUILD_ERROR = "TX_BUILD_ERROR",
-    QUOTE_ERROR = "QUOTE_ERROR",
-    NO_ROUTES = "NO_ROUTES",
-    INVALID_BRIDGE = "INVALID_BRIDGE"
+interface MultiQuoteResult {
+    providerDappId: string;
+    quote: BridgeQuoteAndPost | null;
+    error?: BridgeProviderError;
 }
-declare class BridgeProviderQuoteError extends Error {
-    readonly context?: unknown | undefined;
-    constructor(message: BridgeQuoteErrors, context?: unknown | undefined);
+/**
+ * Callback function called when a quote result is available from a provider
+ */
+type MultiQuoteProgressCallback = (result: MultiQuoteResult) => void;
+/**
+ * Callback function called when a better quote is found
+ */
+type BestQuoteProgressCallback = (result: MultiQuoteResult) => void;
+/**
+ * Options for controlling the behavior of getMultiQuotes
+ */
+interface MultiQuoteOptions {
+    /**
+     * Callback function called as soon as each provider returns a result
+     * Allows for progressive display of quotes without waiting for all providers
+     */
+    onQuoteResult?: MultiQuoteProgressCallback;
+    /**
+     * Maximum time to wait for all providers to respond (in milliseconds)
+     * Default: 40000 (40 seconds)
+     */
+    totalTimeout?: number;
+    /**
+     * Maximum time to wait for each individual provider to respond (in milliseconds)
+     * If a provider takes longer than this, it will be considered timed out
+     * Default: 20000 (20 seconds)
+     */
+    providerTimeout?: number;
 }
-declare class BridgeProviderError extends Error {
-    readonly context: unknown;
-    constructor(message: string, context: unknown);
+interface MultiQuoteRequest {
+    quoteBridgeRequest: QuoteBridgeRequest;
+    providerDappIds?: string[];
+    advancedSettings?: SwapAdvancedSettings;
+    options?: MultiQuoteOptions;
 }
-declare class BridgeOrderParsingError extends Error {
-    readonly context?: unknown | undefined;
-    constructor(message: string, context?: unknown | undefined);
+interface MultiQuoteContext {
+    provider: BridgeProvider<BridgeQuoteResult>;
+    quoteBridgeRequest: QuoteBridgeRequest;
+    advancedSettings: SwapAdvancedSettings | undefined;
+    providerTimeout: number;
+    onQuoteResult: MultiQuoteProgressCallback | undefined;
+}
+interface ProviderQuoteContext extends MultiQuoteContext {
+    results: MultiQuoteResult[];
+    index: number;
+}
+interface BestQuoteProviderContext extends MultiQuoteContext {
+    bestResult: {
+        current: MultiQuoteResult | null;
+    };
+    firstError: {
+        current: MultiQuoteResult | null;
+    };
 }
 
 declare function isBridgeQuoteAndPost(quote: CrossChainQuoteAndPost): quote is BridgeQuoteAndPost;
@@ -358,6 +417,24 @@ declare function assertIsQuoteAndPost(quote: CrossChainQuoteAndPost): asserts qu
 declare function getPostHooks(fullAppData?: string): cowAppDataLatestScheme.CoWHook[];
 declare function isAppDoc(appData: unknown): appData is cowAppDataLatestScheme.AppDataRootSchema;
 
+/**
+ * Parameters for the `getOrder` method.
+ */
+interface GetOrderParams {
+    /**
+     * Id of a network where order was settled
+     */
+    chainId: SupportedChainId;
+    /**
+     * The unique identifier of the order.
+     */
+    orderId: string;
+    /**
+     * The environment of the order
+     */
+    env?: CowEnv;
+}
+
 interface BridgingSdkOptions {
     /**
      * Providers for the bridging.
@@ -376,23 +453,6 @@ interface BridgingSdkOptions {
      */
     enableLogging?: boolean;
 }
-/**
- * Parameters for the `getOrder` method.
- */
-interface GetOrderParams {
-    /**
-     * Id of a network where order was settled
-     */
-    chainId: SupportedChainId;
-    /**
-     * The unique identifier of the order.
-     */
-    orderId: string;
-    /**
-     * The environment of the order
-     */
-    env?: CowEnv;
-}
 type BridgingSdkConfig = Required<Omit<BridgingSdkOptions, 'enableLogging'>>;
 /**
  * SDK for bridging for swapping tokens between different chains.
@@ -436,9 +496,42 @@ declare class BridgingSdk {
      * @throws Error if no path is found
      */
     getQuote(quoteBridgeRequest: QuoteBridgeRequest, advancedSettings?: SwapAdvancedSettings): Promise<CrossChainQuoteAndPost>;
+    /**
+     * Get quotes from multiple bridge providers in parallel with progressive results.
+     *
+     * This method is specifically for cross-chain bridging quotes. For single-chain swaps, use getQuote() instead.
+     *
+     * Features:
+     * - Progressive results: Use the `onQuoteResult` callback to receive quotes as soon as each provider responds
+     * - Timeout support: Configure maximum wait time for all providers and individual provider timeouts
+     * - Parallel execution: All providers are queried simultaneously for best performance
+     *
+     * @param request - The multi-quote request containing quote parameters, provider dappIds, and options
+     * @returns Array of results, one for each provider (successful quotes or errors)
+     * @throws Error if the request is for a single-chain swap (sellTokenChainId === buyTokenChainId)
+     * ```
+     */
+    getMultiQuotes(request: MultiQuoteRequest): Promise<MultiQuoteResult[]>;
+    /**
+     * Get the best quote from multiple bridge providers with progressive updates.
+     *
+     * This method is specifically for cross-chain bridging quotes. For single-chain swaps, use getQuote() instead.
+     *
+     * Features:
+     * - Returns only the best quote based on buyAmount after slippage
+     * - Progressive updates: Use the `onQuoteResult` callback to receive updates whenever a better quote is found
+     * - Timeout support: Configure maximum wait time for all providers and individual provider timeouts
+     * - Parallel execution: All providers are queried simultaneously for best performance
+     *
+     * @param request - The best quote request containing quote parameters, provider dappIds, and options
+     * @returns The best quote result found, or null if no successful quotes were obtained
+     * @throws Error if the request is for a single-chain swap (sellTokenChainId === buyTokenChainId)
+     */
+    getBestQuote(request: MultiQuoteRequest): Promise<MultiQuoteResult | null>;
     getOrder(params: GetOrderParams): Promise<CrossChainOrder | null>;
     getOrderBridgingStatus(bridgingId: string, originChainId: SupportedChainId): Promise<BridgeStatusResult>;
     getProviderFromAppData(fullAppData: string): BridgeProvider<BridgeQuoteResult> | undefined;
+    getProviderByDappId(dappId: string): BridgeProvider<BridgeQuoteResult> | undefined;
 }
 
 declare const RAW_PROVIDERS_FILES_PATH = "https://raw.githubusercontent.com/cowprotocol/cow-sdk/refs/heads/main/src/bridging/providers";
@@ -949,14 +1042,18 @@ interface AcrossStatusAPIResponse {
     };
 }
 type AcrossStatus = AcrossStatusAPIResponse['status'];
-
-interface BungeeApiOptions {
-    apiBaseUrl?: string;
-    manualApiBaseUrl?: string;
-    eventsApiBaseUrl?: string;
-    acrossApiBaseUrl?: string;
+interface BungeeApiUrlOptions {
+    apiBaseUrl: string;
+    manualApiBaseUrl: string;
+    eventsApiBaseUrl: string;
+    acrossApiBaseUrl: string;
+}
+interface BungeeApiOptions extends Partial<BungeeApiUrlOptions> {
     includeBridges?: SupportedBridge[];
     affiliate?: string;
+    fallbackTimeoutMs?: number;
+    apiKey?: string;
+    customApiBaseUrl?: string;
 }
 interface IntermediateTokensParams {
     fromChainId: SupportedChainId;
@@ -964,8 +1061,11 @@ interface IntermediateTokensParams {
     toTokenAddress: string;
     includeBridges?: SupportedBridge[];
 }
+
 declare class BungeeApi {
     private readonly options;
+    private fallbackStates;
+    private readonly fallbackTimeoutMs;
     constructor(options?: BungeeApiOptions);
     validateBridges(includeBridges: SupportedBridge[]): void;
     getBuyTokens(params: BuyTokensParams, bridgeParams?: {
@@ -1011,6 +1111,10 @@ declare class BungeeApi {
     }): Promise<BungeeEvent[]>;
     getAcrossStatus(depositTxHash: string): Promise<AcrossStatus>;
     private getSupportedBridges;
+    private isBungeeApi;
+    private shouldAddApiKey;
+    private shouldUseFallback;
+    private enableFallback;
     private shouldAddAffiliate;
     private makeApiCall;
 }
@@ -1048,4 +1152,4 @@ declare class BungeeBridgeProvider implements BridgeProvider<BungeeQuoteResult>
     private isExtraGasRequired;
 }
 
-export { AcrossBridgeProvider, type AcrossBridgeProviderOptions, type AcrossQuoteResult, type BridgeCallDetails, type BridgeCosts, type BridgeDeposit, type BridgeHook, BridgeOrderParsingError, type BridgeProvider, BridgeProviderError, type BridgeProviderInfo, BridgeProviderQuoteError, type BridgeQuoteAmountsAndCosts, type BridgeQuoteAndPost, BridgeQuoteErrors, type BridgeQuoteResult, type BridgeQuoteResults, BridgeStatus, type BridgeStatusResult, type BridgingDepositParams, BridgingSdk, type BridgingSdkConfig, type BridgingSdkOptions, BungeeBridgeProvider, type BungeeBridgeProviderOptions, type BungeeQuoteResult, type BuyTokensParams, COW_SHED_PROXY_CREATION_GAS, type CrossChainOrder, type CrossChainQuoteAndPost, DEFAULT_EXTRA_GAS_FOR_HOOK_ESTIMATION, DEFAULT_EXTRA_GAS_PROXY_CREATION, DEFAULT_GAS_COST_FOR_HOOK_ESTIMATION, type GetOrderParams, type GetProviderBuyTokens, HOOK_DAPP_BRIDGE_PROVIDER_PREFIX, type QuoteBridgeRequest, type QuoteBridgeRequestWithoutAmount, RAW_PROVIDERS_FILES_PATH, assertIsBridgeQuoteAndPost, assertIsQuoteAndPost, getCrossChainOrder, getPostHooks, isAppDoc, isBridgeQuoteAndPost, isQuoteAndPost };
+export { AcrossBridgeProvider, type AcrossBridgeProviderOptions, type AcrossQuoteResult, type BestQuoteProgressCallback, type BestQuoteProviderContext, type BridgeCallDetails, type BridgeCosts, type BridgeDeposit, type BridgeHook, BridgeOrderParsingError, type BridgeProvider, BridgeProviderError, type BridgeProviderInfo, BridgeProviderQuoteError, type BridgeQuoteAmountsAndCosts, type BridgeQuoteAndPost, BridgeQuoteErrors, type BridgeQuoteResult, type BridgeQuoteResults, BridgeStatus, type BridgeStatusResult, type BridgingDepositParams, BridgingSdk, type BridgingSdkConfig, type BridgingSdkOptions, BungeeBridgeProvider, type BungeeBridgeProviderOptions, type BungeeQuoteResult, type BuyTokensParams, COW_SHED_PROXY_CREATION_GAS, type CrossChainOrder, type CrossChainQuoteAndPost, DEFAULT_EXTRA_GAS_FOR_HOOK_ESTIMATION, DEFAULT_EXTRA_GAS_PROXY_CREATION, DEFAULT_GAS_COST_FOR_HOOK_ESTIMATION, type GetProviderBuyTokens, HOOK_DAPP_BRIDGE_PROVIDER_PREFIX, type MultiQuoteOptions, type MultiQuoteProgressCallback, type MultiQuoteRequest, type MultiQuoteResult, type ProviderQuoteContext, type QuoteBridgeRequest, type QuoteBridgeRequestWithoutAmount, RAW_PROVIDERS_FILES_PATH, assertIsBridgeQuoteAndPost, assertIsQuoteAndPost, getCrossChainOrder, getPostHooks, isAppDoc, isBridgeQuoteAndPost, isQuoteAndPost };