@coinbase/agentkit 0.10.2 → 0.10.4

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

@@ -1,14 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DirectX402RequestSchema = exports.RetryWithX402Schema = exports.HttpRequestSchema = exports.ListX402ServicesSchema = void 0;
+exports.resolveFacilitatorUrl = resolveFacilitatorUrl;
 const zod_1 = require("zod");
+const constants_1 = require("./constants");
+/**
+ * Resolves a facilitator name or URL to the actual URL.
+ *
+ * @param facilitator - Either a known facilitator name ('cdp', 'payai') or a custom URL
+ * @returns The facilitator URL
+ */
+function resolveFacilitatorUrl(facilitator) {
+    if (facilitator in constants_1.KNOWN_FACILITATORS) {
+        return constants_1.KNOWN_FACILITATORS[facilitator];
+    }
+    return facilitator;
+}
 // Schema for listing x402 services
 exports.ListX402ServicesSchema = zod_1.z
     .object({
+    facilitator: zod_1.z
+        .union([zod_1.z.enum(["cdp", "payai"]), zod_1.z.string().url()])
+        .default(constants_1.DEFAULT_FACILITATOR)
+        .describe("Facilitator to query: 'cdp' (Coinbase CDP), 'payai' (PayAI Network), or a custom facilitator URL."),
     maxUsdcPrice: zod_1.z
         .number()
+        .positive()
+        .finite()
         .optional()
         .describe("Optional maximum price in USDC whole units (e.g., 0.1 for 0.10 USDC). Only USDC payment options will be considered when this filter is applied."),
+    x402Versions: zod_1.z
+        .array(zod_1.z.union([zod_1.z.literal(1), zod_1.z.literal(2)]))
+        .default([1, 2])
+        .describe("Filter by x402 protocol version (1 or 2). Defaults to accepting both versions."),
+    keyword: zod_1.z
+        .string()
+        .optional()
+        .describe("Optional keyword to filter services by description (case-insensitive). Example: 'weather' to find weather-related services."),
 })
     .strip()
     .describe("Parameters for listing x402 services with optional filtering");
@@ -29,14 +57,40 @@ exports.HttpRequestSchema = zod_1.z
         .optional()
         .nullable()
         .describe("Optional headers to include in the request"),
+    queryParams: zod_1.z
+        .record(zod_1.z.string())
+        .optional()
+        .nullable()
+        .describe("Query parameters to append to the URL as key-value string pairs. " +
+        "Use ONLY for GET/DELETE requests. " +
+        "For POST/PUT/PATCH, you must use the 'body' parameter instead. " +
+        "Example: {location: 'NYC', units: 'metric'} becomes ?location=NYC&units=metric"),
     body: zod_1.z
         .any()
         .optional()
         .nullable()
-        .describe("Optional request body for POST/PUT/PATCH requests"),
+        .describe("Request body - REQUIRED for POST/PUT/PATCH requests when sending data. " +
+        "Always prefer 'body' over 'queryParams' for POST/PUT/PATCH. " +
+        "Do NOT use for GET or DELETE, use queryParams instead."),
 })
     .strip()
     .describe("Instructions for making a basic HTTP request");
+// Payment option schema that supports both v1 and v2 formats
+const PaymentOptionSchema = zod_1.z
+    .object({
+    scheme: zod_1.z.string().describe("Payment scheme (e.g., 'exact')"),
+    network: zod_1.z
+        .string()
+        .describe("Network identifier (v1: 'base-sepolia' or v2 CAIP-2: 'eip155:84532')"),
+    asset: zod_1.z.string().describe("Asset address or identifier"),
+    // v1 format
+    maxAmountRequired: zod_1.z.string().optional().describe("Maximum amount required (v1 format)"),
+    // v2 format
+    amount: zod_1.z.string().optional().describe("Amount required (v2 format)"),
+    price: zod_1.z.string().optional().describe("Price (v2 format, e.g., '$0.01')"),
+    payTo: zod_1.z.string().optional().describe("Payment recipient address (v2 format)"),
+})
+    .describe("Payment option supporting both v1 and v2 x402 formats");
 // Schema for retrying a failed request with x402 payment
 exports.RetryWithX402Schema = zod_1.z
     .object({
@@ -50,15 +104,21 @@ exports.RetryWithX402Schema = zod_1.z
         .default("GET")
         .describe("The HTTP method to use for the request"),
     headers: zod_1.z.record(zod_1.z.string()).optional().describe("Optional headers to include in the request"),
-    body: zod_1.z.any().optional().describe("Optional request body for POST/PUT/PATCH requests"),
-    selectedPaymentOption: zod_1.z
-        .object({
-        scheme: zod_1.z.string(),
-        network: zod_1.z.string(),
-        maxAmountRequired: zod_1.z.string(),
-        asset: zod_1.z.string(),
-    })
-        .describe("The payment option to use for this request"),
+    queryParams: zod_1.z
+        .record(zod_1.z.string())
+        .optional()
+        .nullable()
+        .describe("Query parameters to append to the URL as key-value string pairs. " +
+        "Use ONLY for GET/DELETE requests. " +
+        "For POST/PUT/PATCH, you must use the 'body' parameter instead. " +
+        "Example: {location: 'NYC', units: 'metric'} becomes ?location=NYC&units=metric"),
+    body: zod_1.z
+        .any()
+        .optional()
+        .describe("Request body - REQUIRED for POST/PUT/PATCH requests when sending data. " +
+        "Always prefer 'body' over 'queryParams' for POST/PUT/PATCH. " +
+        "Do NOT use for GET or DELETE, use queryParams instead."),
+    selectedPaymentOption: PaymentOptionSchema.describe("The payment option to use for this request"),
 })
     .strip()
     .describe("Instructions for retrying a request with x402 payment after receiving a 402 response");
@@ -79,11 +139,21 @@ exports.DirectX402RequestSchema = zod_1.z
         .optional()
         .nullable()
         .describe("Optional headers to include in the request"),
+    queryParams: zod_1.z
+        .record(zod_1.z.string())
+        .optional()
+        .nullable()
+        .describe("Query parameters to append to the URL as key-value string pairs. " +
+        "Use ONLY for GET/DELETE requests. " +
+        "For POST/PUT/PATCH, use the 'body' parameter instead. " +
+        "Example: {location: 'NYC', units: 'metric'} becomes ?location=NYC&units=metric"),
     body: zod_1.z
         .any()
         .optional()
         .nullable()
-        .describe("Optional request body for POST/PUT/PATCH requests"),
+        .describe("Request body - REQUIRED for POST/PUT/PATCH requests when sending data. " +
+        "Always prefer 'body' over 'queryParams' for POST/PUT/PATCH. " +
+        "Do NOT use for GET or DELETE, use queryParams instead."),
 })
     .strip()
     .describe("Instructions for making an HTTP request with automatic x402 payment handling. WARNING: This bypasses user confirmation - only use when explicitly told to skip confirmation!");

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

@@ -1,26 +1,93 @@
 import { Network } from "../../network";
-import { AxiosError } from "axios";
-import { EvmWalletProvider } from "../../wallet-providers";
+import { WalletProvider } from "../../wallet-providers";
+import { type DiscoveryResource, type SimplifiedResource, type X402Version } from "./constants";
 /**
- * Supported network types for x402 protocol
+ * 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
+ */
+export declare function getX402Networks(network: Network): string[];
+/**
+ * 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
+ */
+export declare function getNetworkId(network: string): string;
+/**
+ * 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
+ */
+export declare function fetchAllDiscoveryResources(discoveryUrl: string, pageSize?: number): Promise<DiscoveryResource[]>;
+/**
+ * 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
+ */
+export declare function filterByNetwork(resources: DiscoveryResource[], walletNetworks: string[]): DiscoveryResource[];
+/**
+ * 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
  */
-export type X402Network = "base" | "base-sepolia" | "solana" | "solana-devnet";
+export declare function filterByDescription(resources: DiscoveryResource[]): DiscoveryResource[];
 /**
- * Converts the internal network ID to the format expected by the x402 protocol.
+ * Filters resources by x402 protocol version.
+ * Uses the x402Version field on the resource.
  *
- * @param network - The network to convert
- * @returns The network ID in x402 format
- * @throws Error if the network is not supported
+ * @param resources - Array of discovery resources
+ * @param allowedVersions - Array of allowed versions (default: [1, 2])
+ * @returns Filtered array of resources matching the allowed versions
  */
-export declare function getX402Network(network: Network): X402Network | string | undefined;
+export declare function filterByX402Version(resources: DiscoveryResource[], allowedVersions?: X402Version[]): DiscoveryResource[];
+/**
+ * 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
+ */
+export declare function filterByKeyword(resources: DiscoveryResource[], keyword: string): DiscoveryResource[];
+/**
+ * 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
+ */
+export declare function filterByMaxPrice(resources: DiscoveryResource[], maxUsdcPrice: number, walletProvider: WalletProvider, walletNetworks: string[]): Promise<DiscoveryResource[]>;
+/**
+ * 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
+ */
+export declare function formatSimplifiedResources(resources: DiscoveryResource[], walletNetworks: string[], walletProvider: WalletProvider): Promise<SimplifiedResource[]>;
 /**
  * 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
  */
-export declare function handleHttpError(error: AxiosError, url: string): string;
+export declare function handleHttpError(error: unknown, url: string): string;
 /**
  * Formats a payment option into a human-readable string.
  *
@@ -35,7 +102,7 @@ export declare function formatPaymentOption(option: {
     asset: string;
     maxAmountRequired: string;
     network: string;
-}, walletProvider: EvmWalletProvider): Promise<string>;
+}, walletProvider: WalletProvider): Promise<string>;
 /**
  * Checks if an asset is USDC on any supported network.
  *
@@ -43,7 +110,7 @@ export declare function formatPaymentOption(option: {
  * @param walletProvider - The wallet provider for network context
  * @returns True if the asset is USDC, false otherwise
  */
-export declare function isUsdcAsset(asset: string, walletProvider: EvmWalletProvider): boolean;
+export declare function isUsdcAsset(asset: string, walletProvider: WalletProvider): boolean;
 /**
  * Converts whole units to atomic units for a given asset.
  *
@@ -52,4 +119,12 @@ export declare function isUsdcAsset(asset: string, walletProvider: EvmWalletProv
  * @param walletProvider - The wallet provider for token details lookup
  * @returns The amount in atomic units as a string, or null if conversion fails
  */
-export declare function convertWholeUnitsToAtomic(wholeUnits: number, asset: string, walletProvider: EvmWalletProvider): Promise<string | null>;
+export declare function convertWholeUnitsToAtomic(wholeUnits: number, asset: string, walletProvider: WalletProvider): Promise<string | null>;
+/**
+ * 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
+ */
+export declare function buildUrlWithParams(baseUrl: string, queryParams?: Record<string, string> | null): string;