feat: add use-agently web (#57)

* feat: add `use-agently web`

* remove -d for get command

* always show help after error

* resolve comments + use bun api

* fix: use bun api

* chore: use fetch spy

* stream body to file

* remove global option from parent command

* fix tests

Author: kevzzsk

CLAUDE.md

@@ -152,6 +152,11 @@ use-agently a2a send --uri "uri/url" -m "message"    # Send a message via A2A pr
 use-agently a2a card --uri "uri/url"                 # Fetch and display the A2A agent card
 use-agently mcp tools --uri "uri/url"                # List tools on an MCP server
 use-agently mcp call "tool" ["args"] --uri "uri/url" # Call a tool on an MCP server
+use-agently web get <url>                            # HTTP GET with x402 payment support
+use-agently web post <url>                           # HTTP POST with x402 payment support
+use-agently web put <url>                            # HTTP PUT with x402 payment support
+use-agently web patch <url>                          # HTTP PATCH with x402 payment support
+use-agently web delete <url>                         # HTTP DELETE with x402 payment support
 ```
 
 ### Design Rules for New Commands

README.md

@@ -137,6 +137,21 @@ Resolve an ERC-8004 agent URI and display its details from the Agently marketpla
 use-agently erc-8004 --uri eip155:8453/erc-8004:0x1234/1
 ```
 
+### `web`
+
+Make raw HTTP requests with x402 payment support. Accepts curl-like flags.
+
+```bash
+# GET request with verbose output
+use-agently web get https://api.example.com/data -v
+
+# POST with JSON body
+use-agently web post https://api.example.com/data -d '{"key":"value"}' -H "Content-Type: application/json"
+
+# Dry-run shows cost if payment required; add --pay to authorize
+use-agently web get https://paid-api.example.com/resource
+```
+
 ## How It Works
 
 1. **Wallet** — `init` generates an EVM private key stored locally. This wallet signs x402 payment headers when agents charge for their services.

bun.lock

@@ -0,0 +1,62 @@
+// Custom server entrypoint — overrides the framework's auto-generated server.
+import { AixyzServer } from "aixyz/server";
+import { useA2A } from "aixyz/server/adapters/a2a";
+import { AixyzMCP } from "aixyz/server/adapters/mcp";
+import { facilitator } from "./accepts";
+import * as agent from "./agent";
+import * as freeEcho from "./agents/free-echo";
+import * as freeEcho10 from "./agents/free-echo-10";
+import * as paidEcho from "./agents/paid-echo";
+import * as echoTool from "./tools/echo";
+import * as paidEchoTool from "./tools/paid-echo-tool";
+import express from "express";
+
+const server = new AixyzServer(facilitator);
+await server.initialize();
+server.unstable_withIndexPage();
+
+// A2A agents
+useA2A(server, agent);
+useA2A(server, freeEcho, "free-echo");
+useA2A(server, freeEcho10, "free-echo-10");
+useA2A(server, paidEcho, "paid-echo");
+
+// MCP tools
+const mcp = new AixyzMCP(server);
+await mcp.register("echo", echoTool);
+await mcp.register("paid-echo-tool", paidEchoTool);
+await mcp.connect();
+
+// Plain HTTP test endpoints for `use-agently web` command tests
+server.express.use("/http", express.json());
+
+// Free endpoints
+server.express.get("/http/free", (_req, res) => {
+  res.json({ message: "free GET response" });
+});
+
+server.express.post("/http/free", (req, res) => {
+  res.json({ message: "free POST response", body: req.body });
+});
+
+server.express.put("/http/free", (req, res) => {
+  res.json({ message: "free PUT response", body: req.body });
+});
+
+server.express.delete("/http/free", (_req, res) => {
+  res.json({ message: "free DELETE response" });
+});
+
+// Paid endpoints (x402 $0.003)
+server.withX402Exact("GET /http/paid", { scheme: "exact", price: "$0.003" });
+server.withX402Exact("POST /http/paid", { scheme: "exact", price: "$0.003" });
+
+server.express.get("/http/paid", (_req, res) => {
+  res.json({ message: "paid GET response" });
+});
+
+server.express.post("/http/paid", (req, res) => {
+  res.json({ message: "paid POST response", body: req.body });
+});
+
+export default server;

packages/localhost-aixyz/app/server.ts

@@ -10,9 +10,11 @@
   "dependencies": {
     "ai": "^6",
     "aixyz": "^0",
+    "express": "^5",
     "zod": "^4"
   },
   "devDependencies": {
+    "@types/express": "^5",
     "x402-fl": "^0"
   }
 }

packages/localhost-aixyz/package.json

@@ -7,6 +7,7 @@ import { searchCommand } from "./commands/search";
 import { a2aCommand } from "./commands/a2a";
 import { mcpCommand } from "./commands/mcp";
 import { erc8004Command } from "./commands/erc8004";
+import { webCommand } from "./commands/web";
 import { doctorCommand } from "./commands/doctor";
 import { updateCommand } from "./commands/update";
 
@@ -38,6 +39,7 @@ cli.addCommand(searchCommand.helpGroup("Discovery"));
 cli.addCommand(a2aCommand.helpGroup("Protocols"));
 cli.addCommand(mcpCommand.helpGroup("Protocols"));
 cli.addCommand(erc8004Command.helpGroup("Protocols"));
+cli.addCommand(webCommand.helpGroup("Protocols"));
 
 // Lifecycle
 cli.addCommand(initCommand.helpGroup("Lifecycle"));

packages/use-agently/src/cli.ts

@@ -36,7 +36,7 @@ describe("DryRunPaymentRequired", () => {
   test("uses fallback message when requirements are empty", () => {
     const err = new DryRunPaymentRequired([]);
     expect(err.message).toBe(
-      "This request requires payment of an unknown amount.\nRun the same command with --pay to authorize the transaction and proceed.",
+      "This request requires payment, but the amount could not be determined.\nInspect the endpoint manually before running with --pay.",
     );
   });
 

packages/use-agently/src/client.test.ts

@@ -1,6 +1,7 @@
 import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
 import { wrapMCPClientWithPaymentFromConfig } from "@x402/mcp";
 import { ClientFactory, JsonRpcTransportFactory, RestTransportFactory } from "@a2a-js/sdk/client";
+import boxen from "boxen";
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { Wallet } from "./wallets/wallet.js";
 
@@ -16,10 +17,11 @@ export class DryRunPaymentRequired extends Error {
   readonly requirements: PaymentRequirementsInfo[];
   constructor(requirements: PaymentRequirementsInfo[]) {
     const req = requirements[0];
-    const amount = req ? formatPaymentAmount(req) : "an unknown amount";
-    super(
-      `This request requires payment of ${amount}.\nRun the same command with --pay to authorize the transaction and proceed.`,
-    );
+    const amount = req ? formatPaymentAmount(req) : null;
+    const payLine = amount
+      ? `This request requires payment of ${amount}.\nRun the same command with --pay to authorize the transaction and proceed.`
+      : `This request requires payment, but the amount could not be determined.\nInspect the endpoint manually before running with --pay.`;
+    super(payLine);
     this.name = "DryRunPaymentRequired";
     this.requirements = requirements;
   }
@@ -47,8 +49,8 @@ export function createDryRunFetch(): typeof fetch {
         try {
           const decoded = JSON.parse(Buffer.from(header, "base64").toString("utf-8"));
           requirements = (decoded.accepts as PaymentRequirementsInfo[]) ?? [];
-        } catch {
-          // ignore parse errors — we still throw DryRunPaymentRequired with empty requirements
+        } catch (e) {
+          if (!(e instanceof SyntaxError)) throw e;
         }
       } else {
         // Attempt to parse x402v1 body format
@@ -57,8 +59,8 @@ export function createDryRunFetch(): typeof fetch {
           if (body?.accepts) {
             requirements = body.accepts as PaymentRequirementsInfo[];
           }
-        } catch {
-          // ignore
+        } catch (e) {
+          if (!(e instanceof SyntaxError)) throw e;
         }
       }
       throw new DryRunPaymentRequired(requirements);
@@ -73,6 +75,31 @@ export function createPaymentFetch(wallet: Wallet) {
   });
 }
 
+/** Resolve the fetch implementation based on the --pay flag. */
+export async function resolveFetch(pay?: boolean): Promise<typeof fetch> {
+  if (pay) {
+    const { getConfigOrThrow } = await import("./config.js");
+    const { loadWallet } = await import("./wallets/wallet.js");
+    const config = await getConfigOrThrow();
+    const wallet = loadWallet(config.wallet);
+    return createPaymentFetch(wallet) as typeof fetch;
+  }
+  return createDryRunFetch();
+}
+
+/** Display a DryRunPaymentRequired error in a boxed format and exit. */
+export function handleDryRunError(err: DryRunPaymentRequired): never {
+  console.error(
+    boxen(err.message, {
+      title: "Payment Required",
+      titleAlignment: "center",
+      borderColor: "yellow",
+      padding: 1,
+    }),
+  );
+  process.exit(1);
+}
+
 export function createMcpPaymentClient(mcpClient: Client, wallet: Wallet) {
   return wrapMCPClientWithPaymentFromConfig(mcpClient, {
     schemes: wallet.getX402Schemes(),

packages/use-agently/src/client.ts

@@ -1,10 +1,7 @@
 import { Command } from "commander";
 import { randomUUID } from "node:crypto";
 import { DefaultAgentCardResolver } from "@a2a-js/sdk/client";
-import boxen from "boxen";
-import { getConfigOrThrow } from "../config.js";
-import { loadWallet } from "../wallets/wallet.js";
-import { createPaymentFetch, createA2AClient, createDryRunFetch, DryRunPaymentRequired } from "../client.js";
+import { resolveFetch, createA2AClient, handleDryRunError, DryRunPaymentRequired } from "../client.js";
 import { output } from "../output.js";
 
 function extractTextFromParts(parts: any[]): string {
@@ -87,14 +84,7 @@ const a2aSendCommand = new Command("send")
     const agentInput = resolveUriOption(options, "a2a send");
     const agentUrl = resolveAgentUrl(agentInput);
 
-    let fetchImpl: typeof fetch;
-    if (options.pay) {
-      const config = await getConfigOrThrow();
-      const wallet = loadWallet(config.wallet);
-      fetchImpl = createPaymentFetch(wallet) as typeof fetch;
-    } else {
-      fetchImpl = createDryRunFetch();
-    }
+    const fetchImpl = await resolveFetch(options.pay);
 
     try {
       const client = await createA2AClient(agentUrl, fetchImpl);
@@ -125,17 +115,7 @@ const a2aSendCommand = new Command("send")
         console.log(extractAgentText(lastResult));
       }
     } catch (err) {
-      if (err instanceof DryRunPaymentRequired) {
-        console.error(
-          boxen(err.message, {
-            title: "Payment Required",
-            titleAlignment: "center",
-            borderColor: "yellow",
-            padding: 1,
-          }),
-        );
-        process.exit(1);
-      }
+      if (err instanceof DryRunPaymentRequired) handleDryRunError(err);
       throw err;
     }
   });

packages/use-agently/src/commands/a2a.ts

@@ -1,11 +1,10 @@
 import { Command } from "commander";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import boxen from "boxen";
 import { output } from "../output.js";
 import { loadConfig } from "../config.js";
 import { loadWallet } from "../wallets/wallet.js";
-import { createMcpPaymentClient, DryRunPaymentRequired } from "../client.js";
+import { createMcpPaymentClient, handleDryRunError, DryRunPaymentRequired } from "../client.js";
 import pkg from "../../package.json" with { type: "json" };
 
 function resolveMcpUrl(input: string): string {
@@ -110,17 +109,7 @@ const mcpCallCommand = new Command("call")
           output(command, result);
         }
       } catch (err) {
-        if (err instanceof DryRunPaymentRequired) {
-          console.error(
-            boxen(err.message, {
-              title: "Payment Required",
-              titleAlignment: "center",
-              borderColor: "yellow",
-              padding: 1,
-            }),
-          );
-          process.exit(1);
-        }
+        if (err instanceof DryRunPaymentRequired) handleDryRunError(err);
         throw err;
       } finally {
         await client.close();