@coinbase/agentkit 0.10.3 → 0.10.4

package/dist/action-providers/x402/utils.js

@@ -1,59 +1,308 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getX402Network = getX402Network;
+exports.getX402Networks = getX402Networks;
+exports.getNetworkId = getNetworkId;
+exports.fetchAllDiscoveryResources = fetchAllDiscoveryResources;
+exports.filterByNetwork = filterByNetwork;
+exports.filterByDescription = filterByDescription;
+exports.filterByX402Version = filterByX402Version;
+exports.filterByKeyword = filterByKeyword;
+exports.filterByMaxPrice = filterByMaxPrice;
+exports.formatSimplifiedResources = formatSimplifiedResources;
 exports.handleHttpError = handleHttpError;
 exports.formatPaymentOption = formatPaymentOption;
 exports.isUsdcAsset = isUsdcAsset;
 exports.convertWholeUnitsToAtomic = convertWholeUnitsToAtomic;
+exports.buildUrlWithParams = buildUrlWithParams;
 const utils_1 = require("../erc20/utils");
 const constants_1 = require("../erc20/constants");
 const viem_1 = require("viem");
 const wallet_providers_1 = require("../../wallet-providers");
+const constants_2 = require("./constants");
 /**
- * USDC token addresses for Solana networks
+ * Returns array of matching network identifiers (both v1 and v2 CAIP-2 formats).
+ * Used for filtering discovery results that may contain either format.
+ *
+ * @param network - The network object
+ * @returns Array of network identifiers that match the wallet's network
+ */
+function getX402Networks(network) {
+    const networkId = network.networkId;
+    if (!networkId) {
+        return [];
+    }
+    return constants_2.NETWORK_MAPPINGS[networkId] ?? [networkId];
+}
+/**
+ * Gets network ID from a CAIP-2 or v1 network identifier.
+ *
+ * @param network - The x402 network identifier (e.g., "eip155:8453" for v2 or "base" for v1)
+ * @returns The network ID (e.g., "base-mainnet") or the original if not found
+ */
+function getNetworkId(network) {
+    for (const [agentKitId, formats] of Object.entries(constants_2.NETWORK_MAPPINGS)) {
+        if (formats.includes(network)) {
+            return agentKitId;
+        }
+    }
+    return network;
+}
+/**
+ * Fetches a URL with retry logic and exponential backoff for rate limiting.
+ *
+ * @param url - The URL to fetch
+ * @param maxRetries - Maximum number of retries (default 3)
+ * @param initialDelayMs - Initial delay in milliseconds (default 1000)
+ * @returns The fetch Response
+ */
+async function fetchWithRetry(url, maxRetries = 3, initialDelayMs = 1000) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const response = await fetch(url);
+        if (response.ok) {
+            return response;
+        }
+        if (response.status === 429 && attempt < maxRetries) {
+            const delayMs = initialDelayMs * Math.pow(2, attempt);
+            await new Promise(resolve => setTimeout(resolve, delayMs));
+            continue;
+        }
+        lastError = new Error(`Discovery API error: ${response.status} ${response.statusText}`);
+        break;
+    }
+    throw lastError ?? new Error("Failed to fetch after retries");
+}
+/**
+ * Fetches all resources from the discovery API with pagination.
+ *
+ * @param discoveryUrl - The base URL for discovery
+ * @param pageSize - Number of resources per page (default 100)
+ * @returns Array of all discovered resources
+ */
+async function fetchAllDiscoveryResources(discoveryUrl, pageSize = 1000) {
+    const allResources = [];
+    let offset = 0;
+    let hasMore = true;
+    while (hasMore) {
+        const url = new URL(discoveryUrl);
+        url.searchParams.set("limit", pageSize.toString());
+        url.searchParams.set("offset", offset.toString());
+        const response = await fetchWithRetry(url.toString());
+        const data = await response.json();
+        const resources = data.resources ?? data.items ?? [];
+        if (resources.length === 0) {
+            hasMore = false;
+        }
+        else {
+            allResources.push(...resources);
+            offset += resources.length;
+            // Stop when getting fewer resources than requested (last page)
+            if (resources.length < pageSize) {
+                hasMore = false;
+            }
+        }
+    }
+    return allResources;
+}
+/**
+ * Filters resources by network compatibility.
+ * Matches resources that accept any of the wallet's network identifiers (v1 or v2 format).
+ *
+ * @param resources - Array of discovery resources
+ * @param walletNetworks - Array of network identifiers to match
+ * @returns Filtered array of resources
  */
-const SOLANA_USDC_ADDRESSES = {
-    "solana-devnet": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
-    "solana-mainnet": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
-};
+function filterByNetwork(resources, walletNetworks) {
+    return resources.filter(resource => {
+        const accepts = resource.accepts ?? [];
+        return accepts.some(option => walletNetworks.includes(option.network));
+    });
+}
 /**
- * Converts the internal network ID to the format expected by the x402 protocol.
+ * Extracts description from a resource based on its x402 version.
+ * - v1: description is in accepts[].description
+ * - v2: description is in metadata.description
  *
- * @param network - The network to convert
- * @returns The network ID in x402 format
- * @throws Error if the network is not supported
+ * @param resource - The discovery resource
+ * @returns The description string or empty string if not found
  */
-function getX402Network(network) {
-    switch (network.networkId) {
-        case "base-mainnet":
-            return "base";
-        case "base-sepolia":
-            return "base-sepolia";
-        case "solana-mainnet":
-            return "solana";
-        case "solana-devnet":
-            return "solana-devnet";
-        default:
-            return network.networkId;
+function getResourceDescription(resource) {
+    if (resource.x402Version === 2) {
+        const metadataDesc = resource.metadata?.description;
+        return typeof metadataDesc === "string" ? metadataDesc : "";
+    }
+    // v1: look in accepts[].description
+    const accepts = resource.accepts ?? [];
+    for (const option of accepts) {
+        if (option.description?.trim()) {
+            return option.description;
+        }
     }
+    return "";
+}
+/**
+ * Filters resources by having a valid description.
+ * Removes resources with empty or default descriptions.
+ * Supports both v1 (accepts[].description) and v2 (metadata.description) formats.
+ *
+ * @param resources - Array of discovery resources
+ * @returns Filtered array of resources with valid descriptions
+ */
+function filterByDescription(resources) {
+    return resources.filter(resource => {
+        const desc = getResourceDescription(resource).trim();
+        return desc && desc !== "" && desc !== "Access to protected content";
+    });
+}
+/**
+ * Filters resources by x402 protocol version.
+ * Uses the x402Version field on the resource.
+ *
+ * @param resources - Array of discovery resources
+ * @param allowedVersions - Array of allowed versions (default: [1, 2])
+ * @returns Filtered array of resources matching the allowed versions
+ */
+function filterByX402Version(resources, allowedVersions = [1, 2]) {
+    return resources.filter(resource => {
+        const version = resource.x402Version;
+        if (version === undefined) {
+            return true; // Include resources without version info
+        }
+        return allowedVersions.includes(version);
+    });
+}
+/**
+ * Filters resources by keyword appearing in description or URL.
+ * Case-insensitive search.
+ * Supports both v1 (accepts[].description) and v2 (metadata.description) formats.
+ *
+ * @param resources - Array of discovery resources
+ * @param keyword - The keyword to search for in descriptions and URLs
+ * @returns Filtered array of resources with matching descriptions or URLs
+ */
+function filterByKeyword(resources, keyword) {
+    const lowerKeyword = keyword.toLowerCase();
+    return resources.filter(resource => {
+        // Check description (version-aware)
+        const desc = getResourceDescription(resource).toLowerCase();
+        if (desc.includes(lowerKeyword)) {
+            return true;
+        }
+        // Also check the URL for keyword matches
+        const url = (resource.resource ?? resource.url ?? "").toLowerCase();
+        if (url.includes(lowerKeyword)) {
+            return true;
+        }
+        return false;
+    });
+}
+/**
+ * Filters resources by maximum USDC price.
+ *
+ * @param resources - Array of discovery resources
+ * @param maxUsdcPrice - Maximum price in whole USDC units
+ * @param walletProvider - Wallet provider for asset identification
+ * @param walletNetworks - Array of network identifiers to match
+ * @returns Filtered array of resources within price limit
+ */
+async function filterByMaxPrice(resources, maxUsdcPrice, walletProvider, walletNetworks) {
+    const filtered = [];
+    for (const resource of resources) {
+        const accepts = resource.accepts ?? [];
+        let shouldInclude = false;
+        for (const option of accepts) {
+            if (!walletNetworks.includes(option.network)) {
+                continue;
+            }
+            if (!option.asset) {
+                continue;
+            }
+            // Check if this is a USDC asset
+            if (!isUsdcAsset(option.asset, walletProvider)) {
+                continue;
+            }
+            // Get the amount (supports both v1 maxAmountRequired and v2 amount/price)
+            const amountStr = option.maxAmountRequired ?? option.amount ?? option.price;
+            if (!amountStr) {
+                continue;
+            }
+            try {
+                const maxUsdcPriceAtomic = await convertWholeUnitsToAtomic(maxUsdcPrice, option.asset, walletProvider);
+                if (maxUsdcPriceAtomic) {
+                    const resourceAmount = BigInt(amountStr);
+                    const maxAmount = BigInt(maxUsdcPriceAtomic);
+                    if (resourceAmount <= maxAmount) {
+                        shouldInclude = true;
+                        break;
+                    }
+                }
+            }
+            catch {
+                // Skip if conversion fails
+                continue;
+            }
+        }
+        if (shouldInclude) {
+            filtered.push(resource);
+        }
+    }
+    return filtered;
+}
+/**
+ * Formats resources into simplified output for LLM consumption.
+ *
+ * @param resources - Array of discovery resources
+ * @param walletNetworks - Array of network identifiers to match for price extraction
+ * @param walletProvider - Wallet provider for formatting
+ * @returns Array of simplified resources with url, price, description
+ */
+async function formatSimplifiedResources(resources, walletNetworks, walletProvider) {
+    const simplified = [];
+    for (const resource of resources) {
+        const accepts = resource.accepts ?? [];
+        const matchingOption = accepts.find(opt => walletNetworks.includes(opt.network));
+        if (!matchingOption) {
+            continue;
+        }
+        // Extract URL: v1 and v2 both use resource.resource, but v2 docs show resource.url
+        const url = resource.resource ?? resource.url ?? "";
+        // Extract description (version-aware via helper)
+        const description = getResourceDescription(resource);
+        let price = "Unknown";
+        // Get the amount (supports both v1 and v2 formats)
+        const amountStr = matchingOption.maxAmountRequired ?? matchingOption.amount ?? matchingOption.price;
+        if (amountStr && matchingOption.asset) {
+            price = await formatPaymentOption({
+                asset: matchingOption.asset,
+                maxAmountRequired: amountStr,
+                network: matchingOption.network,
+            }, walletProvider);
+        }
+        simplified.push({
+            url,
+            price,
+            description,
+        });
+    }
+    return simplified;
 }
 /**
  * Helper method to handle HTTP errors consistently.
  *
- * @param error - The axios error to handle
+ * @param error - The error to handle
  * @param url - The URL that was being accessed when the error occurred
  * @returns A JSON string containing formatted error details
  */
 function handleHttpError(error, url) {
-    if (error.response) {
+    if (error instanceof Response) {
         return JSON.stringify({
             error: true,
-            message: `HTTP ${error.response.status} error when accessing ${url}`,
-            details: error.response.data?.error || error.response.statusText,
+            message: `HTTP ${error.status} error when accessing ${url}`,
+            details: error.statusText,
             suggestion: "Check if the URL is correct and the API is available.",
         }, null, 2);
     }
-    if (error.request) {
+    if (error instanceof TypeError && error.message.includes("fetch")) {
         return JSON.stringify({
             error: true,
             message: `Network error when accessing ${url}`,
@@ -61,10 +310,11 @@ function handleHttpError(error, url) {
             suggestion: "Check your internet connection and verify the API endpoint is accessible.",
         }, null, 2);
     }
+    const message = error instanceof Error ? error.message : String(error);
     return JSON.stringify({
         error: true,
         message: `Error making request to ${url}`,
-        details: error.message,
+        details: message,
         suggestion: "Please check the request parameters and try again.",
     }, null, 2);
 }
@@ -92,7 +342,7 @@ async function formatPaymentOption(option, walletProvider) {
                 if (asset.toLowerCase() === address.toLowerCase()) {
                     const decimals = symbol === "USDC" || symbol === "EURC" ? 6 : 18;
                     const formattedAmount = (0, viem_1.formatUnits)(BigInt(maxAmountRequired), decimals);
-                    return `${formattedAmount} ${symbol} on ${network} network`;
+                    return `${formattedAmount} ${symbol} on ${getNetworkId(network)}`;
                 }
             }
         }
@@ -101,7 +351,7 @@ async function formatPaymentOption(option, walletProvider) {
             const tokenDetails = await (0, utils_1.getTokenDetails)(walletProvider, asset);
             if (tokenDetails) {
                 const formattedAmount = (0, viem_1.formatUnits)(BigInt(maxAmountRequired), tokenDetails.decimals);
-                return `${formattedAmount} ${tokenDetails.name} on ${network} network`;
+                return `${formattedAmount} ${tokenDetails.name} on ${getNetworkId(network)}`;
             }
         }
         catch {
@@ -111,15 +361,15 @@ async function formatPaymentOption(option, walletProvider) {
     if (isSvmNetwork && walletProvider instanceof wallet_providers_1.SvmWalletProvider) {
         // Check if the asset is USDC on Solana networks
         const networkId = walletNetwork.networkId;
-        const usdcAddress = SOLANA_USDC_ADDRESSES[networkId];
+        const usdcAddress = constants_2.SOLANA_USDC_ADDRESSES[networkId];
         if (usdcAddress && asset === usdcAddress) {
             // USDC has 6 decimals on Solana
             const formattedAmount = (0, viem_1.formatUnits)(BigInt(maxAmountRequired), 6);
-            return `${formattedAmount} USDC on ${network} network`;
+            return `${formattedAmount} USDC on ${getNetworkId(network)}`;
         }
     }
     // Fallback to original format for non-EVM/SVM networks or when token details can't be fetched
-    return `${asset} ${maxAmountRequired} on ${network} network`;
+    return `${asset} ${maxAmountRequired} on ${getNetworkId(network)}`;
 }
 /**
  * Checks if an asset is USDC on any supported network.
@@ -141,7 +391,7 @@ function isUsdcAsset(asset, walletProvider) {
     }
     if (isSvmNetwork && walletProvider instanceof wallet_providers_1.SvmWalletProvider) {
         const networkId = walletNetwork.networkId;
-        const usdcAddress = SOLANA_USDC_ADDRESSES[networkId];
+        const usdcAddress = constants_2.SOLANA_USDC_ADDRESSES[networkId];
         if (usdcAddress) {
             return asset === usdcAddress;
         }
@@ -186,7 +436,7 @@ async function convertWholeUnitsToAtomic(wholeUnits, asset, walletProvider) {
     if (isSvmNetwork && walletProvider instanceof wallet_providers_1.SvmWalletProvider) {
         // Check if the asset is USDC on Solana networks
         const networkId = walletNetwork.networkId;
-        const usdcAddress = SOLANA_USDC_ADDRESSES[networkId];
+        const usdcAddress = constants_2.SOLANA_USDC_ADDRESSES[networkId];
         if (usdcAddress && asset === usdcAddress) {
             // USDC has 6 decimals on Solana
             return (0, viem_1.parseUnits)(wholeUnits.toString(), 6).toString();
@@ -195,3 +445,20 @@ async function convertWholeUnitsToAtomic(wholeUnits, asset, walletProvider) {
     // Fallback to 18 decimals for unknown tokens or non-EVM/SVM networks
     return (0, viem_1.parseUnits)(wholeUnits.toString(), 18).toString();
 }
+/**
+ * Builds a URL with query parameters appended.
+ *
+ * @param baseUrl - The base URL
+ * @param queryParams - Optional query parameters to append
+ * @returns URL string with query parameters
+ */
+function buildUrlWithParams(baseUrl, queryParams) {
+    if (!queryParams || Object.keys(queryParams).length === 0) {
+        return baseUrl;
+    }
+    const url = new URL(baseUrl);
+    Object.entries(queryParams).forEach(([key, value]) => {
+        url.searchParams.append(key, value);
+    });
+    return url.toString();
+}

package/dist/action-providers/x402/x402ActionProvider.d.ts

@@ -16,7 +16,7 @@ export declare class X402ActionProvider extends ActionProvider<WalletProvider> {
      * Discovers available x402 services with optional filtering.
      *
      * @param walletProvider - The wallet provider to use for network filtering
-     * @param args - Optional filters: maxUsdcPrice
+     * @param args - Optional filters: discoveryUrl, maxUsdcPrice
      * @returns JSON string with the list of services (filtered by network and description)
      */
     discoverX402Services(walletProvider: WalletProvider, args: z.infer<typeof ListX402ServicesSchema>): Promise<string>;
@@ -51,5 +51,19 @@ export declare class X402ActionProvider extends ActionProvider<WalletProvider> {
      * @returns True if the network is supported, false otherwise
      */
     supportsNetwork: (network: Network) => boolean;
+    /**
+     * Creates an x402 client configured for the given wallet provider.
+     *
+     * @param walletProvider - The wallet provider to configure the client for
+     * @returns Configured x402Client
+     */
+    private createX402Client;
+    /**
+     * Parses response data based on content type.
+     *
+     * @param response - The fetch Response object
+     * @returns Parsed response data
+     */
+    private parseResponseData;
 }
 export declare const x402ActionProvider: () => X402ActionProvider;