agent402-client 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# agent402-client
+
+A tiny buyer-side client for [Agent402](https://agent402.tools) (and any Agent402
+instance). **Resolve a task to a tool, then call it — with payment handled for
+you.** Free pure-CPU tools settle with a built-in proof-of-work (no wallet, zero
+dependencies); wallet-only tools settle via an x402-wrapped fetch you provide.
+Results are cached, and retries reuse an `Idempotency-Key` so a lost response
+never double-charges.
+
+```bash
+npm install agent402-client
+```
+
+## Free tier (proof-of-work, no wallet)
+
+```js
+import { Agent402 } from "agent402-client";
+
+const a = new Agent402();                       // → https://agent402.tools
+
+// Don't know the slug? Resolve a task in one call.
+const matches = await a.find("extract the article from a url");
+// → [{ slug: "extract", route, price, inputSchema, example, … }]
+
+// Call it — proof-of-work is solved automatically for free tools.
+const out = await a.call("hash", { text: "hello world", algo: "sha256" });
+console.log(out.hex);
+```
+
+## Paid tools (USDC via x402)
+
+Wallet-only tools (live search, headless browser, PDFs, durable memory) settle
+in USDC. Pass an [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch)-wrapped
+fetch — your wallet signs, the client never touches your key:
+
+```js
+import { wrapFetchWithPayment } from "@x402/fetch";
+import { x402Client } from "@x402/core/client";
+import { registerExactEvmScheme } from "@x402/evm/exact/client";
+import { privateKeyToAccount } from "viem/accounts";
+
+const client = new x402Client();
+registerExactEvmScheme(client, { signer: privateKeyToAccount(process.env.AGENT_KEY) });
+const payFetch = wrapFetchWithPayment(fetch, client);
+
+const a = new Agent402({ fetch: payFetch });
+const article = await a.call("extract", { url: "https://example.com/article" });
+```
+
+## API
+
+| Method | What |
+|---|---|
+| `new Agent402({ baseUrl?, fetch?, cache?, fetchImpl? })` | `fetch` is your x402-wrapped fetch for paid tools (optional); `cache` (default `true`) memoizes deterministic results |
+| `await a.find(task, { k = 5 })` | Resolve a plain-language task to the best-matching tools (route, price, schema, example) |
+| `await a.call(slug, params, { idempotencyKey?, cache? })` | Call a tool; auto-pays (PoW for free tools, x402 for wallet-only); returns the JSON result |
+| `Agent402.solvePow(pow)` | Solve a proof-of-work challenge object → an `X-Pow-Solution` value |
+| `a.clearCache()` | Drop the in-memory result cache |
+
+- **Zero dependencies** for the free/proof-of-work path (uses `node:crypto`).
+- **Non-custodial:** paid settlement is your `@x402/fetch` + wallet; this client never sees your key.
+- MIT licensed. Part of [Agent402](https://github.com/MikeyPetrillo/Agent402).

package/index.js

@@ -0,0 +1,122 @@
+// agent402-client — a tiny buyer-side client for agent402.tools (or any Agent402
+// instance). Resolve a task to a tool, then call it with payment handled for you:
+//   - free pure-CPU tools settle with a built-in proof-of-work (no wallet, zero deps),
+//   - wallet-only tools settle via an x402-wrapped fetch you provide (@x402/fetch),
+// results are cached (tools are deterministic), and retries reuse an
+// Idempotency-Key so a lost response never double-charges.
+//
+//   import { Agent402 } from "agent402-client";
+//   const a = new Agent402();                       // free tier, proof-of-work
+//   const [best] = await a.find("extract the article from a url");
+//   const out = await a.call("extract", { url: "https://example.com/article" });
+//
+//   // paid tools: pass an x402-wrapped fetch (your wallet signs)
+//   const a = new Agent402({ fetch: payFetch });
+import { createHash } from "node:crypto";
+
+const leadingZeroBits = (buf) => { let n = 0; for (const b of buf) { if (b === 0) { n += 8; continue; } n += Math.clz32(b) - 24; break; } return n; };
+
+export class Agent402 {
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.baseUrl="https://agent402.tools"]
+   * @param {typeof fetch} [opts.fetch]      an x402-wrapped fetch for wallet-only tools (optional)
+   * @param {boolean} [opts.cache=true]      cache results in memory (deterministic tools)
+   * @param {typeof fetch} [opts.fetchImpl]  plain fetch (defaults to global fetch)
+   */
+  constructor({ baseUrl = "https://agent402.tools", fetch: payFetch, cache = true, fetchImpl = globalThis.fetch } = {}) {
+    if (typeof fetchImpl !== "function") throw new Error("No fetch available — pass { fetchImpl } on Node < 18");
+    this.baseUrl = String(baseUrl).replace(/\/$/, "");
+    this.payFetch = payFetch || null;
+    this.f = fetchImpl;
+    this._catalog = null;
+    this._cache = cache ? new Map() : null;
+  }
+
+  async _loadCatalog() {
+    if (this._catalog) return this._catalog;
+    const r = await this.f(`${this.baseUrl}/api/pricing`);
+    if (!r.ok) throw new Error(`could not load catalog: HTTP ${r.status}`);
+    const j = await r.json();
+    const m = new Map();
+    for (const e of j.endpoints || []) m.set(e.slug, { method: e.method, path: e.path, computePayable: e.computePayable, price: e.price });
+    this._catalog = m;
+    return m;
+  }
+
+  /** Resolve a plain-language task to the best-matching tools (route, price, schema, example). */
+  async find(task, { k = 5 } = {}) {
+    const r = await this.f(`${this.baseUrl}/api/find?q=${encodeURIComponent(task)}&k=${k}`);
+    if (!r.ok) throw new Error(`find failed: HTTP ${r.status}`);
+    return (await r.json()).results || [];
+  }
+
+  /** Solve a proof-of-work challenge object (from a 402 body) into an X-Pow-Solution value. */
+  static solvePow(pow) {
+    let n = 0;
+    while (leadingZeroBits(createHash("sha256").update(`${pow.challenge}:${n}`).digest()) < pow.difficulty) n++;
+    return `${pow.token}:${n}`;
+  }
+
+  /**
+   * Call a tool by slug; pays automatically (PoW for free tools, x402 for
+   * wallet-only) and returns the parsed JSON result.
+   */
+  async call(slug, params = {}, { idempotencyKey, cache = true } = {}) {
+    const cat = await this._loadCatalog();
+    const tool = cat.get(slug);
+    if (!tool) throw new Error(`unknown tool "${slug}" — use client.find(task) to discover one`);
+
+    const cacheKey = `${slug}:${JSON.stringify(params)}`;
+    if (this._cache && cache && this._cache.has(cacheKey)) return this._cache.get(cacheKey);
+
+    const idem = idempotencyKey || `a402-${createHash("sha256").update(`${cacheKey}:${Date.now()}:${Math.random()}`).digest("hex").slice(0, 24)}`;
+    const send = (extraHeaders = {}, useFetch = this.f) => {
+      const headers = { "Idempotency-Key": idem, ...extraHeaders };
+      let url = `${this.baseUrl}${tool.path}`;
+      const init = { method: tool.method, headers };
+      if (tool.method === "GET") {
+        const qs = new URLSearchParams(Object.entries(params).map(([k, v]) => [k, typeof v === "object" ? JSON.stringify(v) : String(v)])).toString();
+        if (qs) url += `?${qs}`;
+      } else {
+        headers["Content-Type"] = "application/json";
+        init.body = JSON.stringify(params);
+      }
+      return useFetch(url, init);
+    };
+
+    // Wallet-only tool → settle in USDC via the provided x402 fetch.
+    if (!tool.computePayable) {
+      if (this.payFetch) {
+        const r = await send({}, this.payFetch);
+        if (!r.ok) throw new Error(`call "${slug}" failed: HTTP ${r.status}`);
+        return this._store(cacheKey, await r.json(), cache);
+      }
+      const r = await send(); // no wallet — succeeds only on a FREE_MODE instance
+      if (r.ok) return this._store(cacheKey, await r.json(), cache);
+      throw new Error(`call "${slug}" failed: HTTP ${r.status} — wallet-only tool; construct with { fetch: payFetch } (an @x402/fetch-wrapped fetch)`);
+    }
+
+    // Free (compute-payable) tool: succeeds plainly on a FREE_MODE instance,
+    // otherwise pay with a proof-of-work (fetched from /api/pow/challenge — the
+    // Agent402 server signals it via the X-Pow-Challenge header, not the 402 body).
+    let r = await send();
+    if (!r.ok) {
+      const chal = await this._powChallenge(slug);
+      r = await send({ "X-Pow-Solution": Agent402.solvePow(chal) });
+    }
+    if (!r.ok) throw new Error(`call "${slug}" failed after proof-of-work: HTTP ${r.status}`);
+    return this._store(cacheKey, await r.json(), cache);
+  }
+
+  async _powChallenge(slug) {
+    const r = await this.f(`${this.baseUrl}/api/pow/challenge?slug=${encodeURIComponent(slug)}`);
+    if (!r.ok) throw new Error(`proof-of-work challenge for "${slug}" failed: HTTP ${r.status}`);
+    return r.json();
+  }
+
+  _store(key, val, cache) { if (this._cache && cache) this._cache.set(key, val); return val; }
+  clearCache() { this._cache?.clear(); }
+}
+
+export default Agent402;

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "agent402-client",
+  "version": "0.1.0",
+  "description": "Tiny buyer-side client for Agent402 (x402): resolve a task to a tool and call it with payment handled for you — free tools settle via built-in proof-of-work (no wallet), wallet-only tools via your x402 fetch. Caching + idempotent retries.",
+  "type": "module",
+  "main": "index.js",
+  "exports": { ".": "./index.js" },
+  "files": ["index.js", "README.md"],
+  "engines": { "node": ">=18" },
+  "scripts": { "test": "node test.js" },
+  "keywords": [
+    "x402", "ai-agents", "agent-tools", "llm-tools", "usdc", "base",
+    "proof-of-work", "http-402", "micropayments", "mcp", "client", "sdk"
+  ],
+  "author": "Mikey Petrillo (https://github.com/MikeyPetrillo)",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/MikeyPetrillo/Agent402.git", "directory": "client" },
+  "homepage": "https://github.com/MikeyPetrillo/Agent402/tree/main/client"
+}