agent402-client 0.6.11 → 0.8.0

package/README.md

@@ -2,17 +2,17 @@
 
 A tiny buyer-side client for [Agent402](https://agent402.tools) (and any Agent402
 instance) - the buy side of [Agentic Finance](https://agent402.tools/agentic-finance),
-agents paying per request over x402 or MPP. **Resolve a task to a tool, then call it — with payment handled for
+agents paying per request over x402 or MPP. **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.
+dependencies); wallet-only tools settle via an x402- or MPP-wrapped fetch you
+provide, or by card through a prepaid credits key. Results are cached, and
+retries reuse an `Idempotency-Key` so a lost response never double-charges.
 
 ```bash
 npm install agent402-client
 ```
 
-Runnable copy of the free-tier quickstart below: [`examples/hello-agent402.js`](https://github.com/MikeyPetrillo/Agent402/blob/main/examples/hello-agent402.js) — discover a tool and call it in ~15 lines, no wallet.
+Runnable copy of the free-tier quickstart below: [`examples/hello-agent402.js`](https://github.com/MikeyPetrillo/Agent402/blob/main/examples/hello-agent402.js) - discover a tool and call it in ~15 lines, no wallet.
 
 ## Free tier (proof-of-work, no wallet)
 
@@ -25,7 +25,7 @@ const a = new Agent402();                       // → https://agent402.tools
 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.
+// 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);
 ```
@@ -69,6 +69,26 @@ const a = new Agent402({ fetch: payFetch });
 const article = await a.call("extract", { url: "https://example.com/article" });
 ```
 
+## Pay by card instead of a wallet (prepaid credits)
+
+Buy a credits pack ($20 / $50 / $100) at https://agent402.tools/credits, claim the
+`a402_...` key once, and pass it as `creditsKey`. The SDK then sends
+`Authorization: Bearer a402_...` on wallet-only calls; the server authorizes
+against the key's balance before the handler runs and debits the list price only
+on a successful (200) response (the `X-Credits-Balance` header carries what is
+left; credits never expire). A refused call throws with the balance and a top-up
+link; nothing is debited.
+
+```js
+const client = new Agent402({ creditsKey: "a402_..." });
+await client.call("whois", { domain: "example.com" }); // debited per successful call
+```
+
+The same `maxPerCallUsd` / `dailyLimitUsd` / `maxPerHostUsd` caps apply (a
+credits call reserves its price like a wallet call). A payment `fetch` still wins
+when both are given, and free pure-CPU tools keep settling with proof-of-work.
+The same Bearer header also reads the balance directly, e.g. `curl -H "Authorization: Bearer a402_..." https://agent402.tools/api/credits/balance`.
+
 ## Retries never double-charge
 
 Every paid call the SDK makes carries an `Idempotency-Key`, so a retry of a
@@ -80,8 +100,8 @@ same id is a new payment).
 
 ## Workflows (skill packs)
 
-For jobs that no single tool covers — e.g. "audit a domain", "build a stock
-brief" — Agent402 ships curated multi-tool **skill packs**: 5–7 catalog tools
+For jobs that no single tool covers - e.g. "audit a domain", "build a stock
+brief" - Agent402 ships curated multi-tool **skill packs**: 5–7 catalog tools
 composed into a Claude-ready task template. Discover them the same way you'd
 discover a tool:
 
@@ -96,7 +116,7 @@ const { messages } = await a.getWorkflowPrompt("security-audit", { domain: "stri
 
 ## Discover the live x402 economy
 
-Want to see who's actually getting paid on x402 right now — not just what tools
+Want to see who's actually getting paid on x402 right now - not just what tools
 this service exposes? `topSellers()` returns the live leaderboard of sellers
 settling USDC (primarily on Base) in the last ~24h, derived from on-chain transfers. Free
 to call (no payment, no proof-of-work):
@@ -113,21 +133,41 @@ await a.topSellers({ sort: "calls", include: "all" });
 
 | Method | What |
 |---|---|
-| `new Agent402({ baseUrl?, fetch?, cache?, fetchImpl?, maxPerCallUsd?, dailyLimitUsd?, maxPerHostUsd? })` | `fetch` is your x402-wrapped fetch for paid tools (optional); `cache` (default `true`) memoizes deterministic results; the three USD caps set optional spending limits (see below) |
+| `new Agent402({ baseUrl?, fetch?, creditsKey?, cache?, fetchImpl?, maxPerCallUsd?, dailyLimitUsd?, maxPerHostUsd?, maxResponseBytes? })` | `fetch` is your x402- or MPP-wrapped fetch for paid tools (optional); `creditsKey` is a prepaid card-credits key (`a402_...`) used for paid tools when no `fetch` is given; `cache` (default `true`) memoizes deterministic results; the three USD caps set optional spending limits (see below); `maxResponseBytes` (default 32MB, `null` to disable) refuses an oversized response body before it is parsed |
 | `await a.find(task, { k = 5 })` | Resolve a plain-language task to the best-matching tools (route, price, schema, example) |
 | `await a.findWorkflows(task, { k = 2 })` | Resolve a task to matching multi-tool workflow templates (skill packs) |
 | `await a.getWorkflowPrompt(slug, args)` | Fetch the rendered prompt messages for a skill pack with arguments substituted in |
 | `await a.topSellers({ limit?, sort?, include? })` | Live x402 leaderboard: which sellers are settling the most USDC (primarily on Base) in the last ~24h (free, no payment) |
-| `await a.call(slug, params, { idempotencyKey?, cache? })` | Call a tool; auto-pays (PoW for free tools, x402 for wallet-only); returns the JSON result |
+| `await a.call(slug, params, { idempotencyKey?, cache?, maxResponseBytes? })` | Call a tool; auto-pays (PoW for free tools; your payment `fetch` or the credits key for wallet-only); returns the JSON result |
 | `Agent402.solvePow(pow)` | Solve a proof-of-work challenge object → an `X-Pow-Solution` value |
 | `a.spendingSummary()` | Rolling-24h paid spend so far: `{ dailyUsd, calls, byHost, limits }` |
 | `a.clearCache()` | Drop the in-memory result cache |
 
+## Response size ceiling
+
+You are calling strangers and paying them, and the seller chooses the response.
+By the time `r.json()` resolves, a multi-gigabyte body is already in your
+agent's memory, so this is one of the few checks that cannot be done after the
+fact in your own code.
+
+Every call is capped at 32MB by default. The declared `content-length` is
+refused before a byte is read, and the stream is counted as it arrives, because
+`content-length` is the seller's claim about their own body.
+
+```js
+const a = new Agent402({ maxResponseBytes: 1_000_000 });   // 1MB everywhere
+await a.call("hash", { text: "x" }, { maxResponseBytes: null });  // or per call
+```
+
+An oversized body throws `ResponseTooLargeError` carrying `size`, `cap`,
+`source` and `paid`. Check `paid`: on a wallet-only tool the money moved before
+the body arrived, so a refused response is still a spend you made.
+
 ## Spending caps (never overpay)
 
 By default the client pays whatever a tool costs. Set optional hard ceilings and a
 call that would exceed one is **refused before any payment is signed** (it throws
-`SpendingLimitError` — no funds move):
+`SpendingLimitError` - no funds move):
 
 ```js
 import { Agent402, SpendingLimitError } from "agent402-client";
@@ -146,29 +186,29 @@ try {
 }
 ```
 
-Only **settled** paid calls count against the rolling window — a blocked or failed
+Only **settled** paid calls count against the rolling window - a blocked or failed
 call never consumes budget. Free proof-of-work calls are never counted. Omit a cap
 (or leave it `null`) for no limit; with none set, behavior is unchanged.
 
 **What the caps check.** When a cap is set, the client preflights the `402` and
 checks the ceiling against the **larger** of the advertised price (from the
-seller's `/api/pricing`) and the amount the `402` challenge actually quotes — so a
+seller's `/api/pricing`) and the amount the `402` challenge actually quotes - so a
 server that under-advertises and then quotes more in the `402` is refused *before*
 your wallet fetch signs anything. If the `402` can't be read (FREE_MODE, or an
 unrecognized challenge shape) it falls back to the advertised price rather than
 block a legitimate payment. Caps hold under **concurrency** too: each call reserves
 its amount synchronously, so N simultaneous calls can't each pass against the same
-pre-commit total. (The `402` amount is derived assuming stablecoin settlement —
-`atomic / 10^decimals ≈ USD` — which matches x402's USDC/USDG rails.)
+pre-commit total. (The `402` amount is derived assuming stablecoin settlement -
+`atomic / 10^decimals ≈ USD` - which matches x402's USDC/USDG rails.)
 
 - **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.
+- **Non-custodial:** paid settlement is your `@x402/fetch` / `mppx` fetch + wallet (or a prepaid credits key you bought); this client never sees a private key.
 - MIT licensed. Part of [Agent402](https://github.com/MikeyPetrillo/Agent402).
 
 ## Pick the settlement chain (`withNetworkPreference`)
 
 Multi-chain sellers list Base first, so an unmodified x402 client effectively
-always settles there. To pin a chain — e.g. **USDG on Robinhood Chain** —
+always settles there. To pin a chain - e.g. **USDG on Robinhood Chain** -
 wrap your client before building the fetch:
 
 ```js

package/index.js

@@ -18,8 +18,13 @@ import { createHash } from "node:crypto";
 // `User-Agent: agent402-client/<version>` — a standard header, no extra
 // network calls — so a seller can attribute traffic (and settled payments)
 // to this SDK. Product token only; nothing about the caller rides along.
-const VERSION = "0.6.1";
+const VERSION = "0.7.0";
 const USER_AGENT = `agent402-client/${VERSION}`;
+// 32MB: about a hundred times any realistic response from this catalog (the
+// largest is a base64 image at a few MB), so it cannot break a legitimate
+// caller, while still stopping the class it exists for. A ceiling that is off
+// by default protects nobody, so this one is on; pass null to disable it.
+const DEFAULT_MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
 
 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; };
 
@@ -33,9 +38,15 @@ export class Agent402 {
    * @param {number} [opts.maxPerCallUsd]    hard ceiling on a single paid call (USD); over → SpendingLimitError before paying
    * @param {number} [opts.dailyLimitUsd]    hard ceiling on rolling-24h paid spend (USD)
    * @param {number} [opts.maxPerHostUsd]    hard ceiling on rolling-24h paid spend to one seller host (USD)
+   * @param {string} [opts.creditsKey]       a prepaid card-credits key (a402_...) from agent402.tools/credits -
+   *                                         pays wallet-only tools by card when no payFetch is given
+   * @param {number|null} [opts.maxResponseBytes=33554432]
+   *        Hard ceiling on a response body, enforced BEFORE it is parsed. null disables it.
    */
   constructor({ baseUrl = "https://agent402.tools", fetch: payFetch, cache = true, fetchImpl = globalThis.fetch,
-    maxPerCallUsd = null, dailyLimitUsd = null, maxPerHostUsd = null } = {}) {
+    maxPerCallUsd = null, dailyLimitUsd = null, maxPerHostUsd = null, creditsKey = null,
+    maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES } = {}) {
+    this.creditsKey = typeof creditsKey === "string" && /^a402_[A-Za-z0-9_-]{32,64}$/.test(creditsKey) ? creditsKey : null;
     if (typeof fetchImpl !== "function") throw new Error("No fetch available — pass { fetchImpl } on Node < 18");
     this.baseUrl = String(baseUrl).replace(/\/$/, "");
     this.payFetch = payFetch || null;
@@ -56,6 +67,65 @@ export class Agent402 {
       perHost: numOrNull(maxPerHostUsd),
       log: [], // [{ ts, host, usd }] — settled paid calls in the last 24h
     };
+    // A response-size ceiling, enforced before parsing. See _readJson.
+    this.maxResponseBytes = maxResponseBytes === null ? null : (numOrNull(maxResponseBytes) ?? DEFAULT_MAX_RESPONSE_BYTES);
+  }
+
+  /**
+   * Read a JSON body with a hard byte ceiling.
+   *
+   * WHY THIS LIVES IN THE SDK. Almost everything a buyer might want to check
+   * about a response, they can check themselves in their own code once they
+   * hold it. Not this one: by the time `r.json()` has resolved, a hostile or
+   * broken seller's multi-gigabyte body is already in the agent's memory. The
+   * SDK owns the fetch, so it is the only place the check can happen in time.
+   *
+   * That matters here more than in an ordinary HTTP client, because this SDK
+   * calls STRANGERS and pays them. The seller chooses the response.
+   *
+   * Two gates: the declared content-length is refused before a byte is read,
+   * and the actual stream is counted as it arrives, because content-length is
+   * the seller's claim about their own body and a missing or lying header must
+   * not be the thing standing between an agent and an OOM.
+   */
+  async _readJson(r, { maxBytes, slug, paid = false } = {}) {
+    const cap = maxBytes === undefined ? this.maxResponseBytes : (maxBytes === null ? null : numOrNull(maxBytes));
+    if (cap == null) return r.json();
+
+    const declared = Number(r.headers?.get?.("content-length"));
+    if (Number.isFinite(declared) && declared > cap) {
+      throw new ResponseTooLargeError(declared, cap, { slug, paid, source: "content-length" });
+    }
+    // A response object we cannot measure at all - no stream and no text() -
+    // is a caller-supplied stub or an exotic runtime, never a hostile seller
+    // over a real fetch (a real Response has both). Degrade to an unbounded
+    // read rather than turning "I could not measure this" into a failure of a
+    // call the caller may have already paid for.
+    if ((!r.body || typeof r.body.getReader !== "function") && typeof r.text !== "function") return r.json();
+    // No readable stream but text() is available: bound the PARSE, even though
+    // the bytes have already arrived.
+    if (!r.body || typeof r.body.getReader !== "function") {
+      const text = await r.text();
+      const size = Buffer.byteLength(text, "utf8");
+      if (size > cap) throw new ResponseTooLargeError(size, cap, { slug, paid, source: "body" });
+      return JSON.parse(text);
+    }
+    const reader = r.body.getReader();
+    const chunks = [];
+    let received = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      received += value.length;
+      if (received > cap) {
+        // Stop pulling immediately. Reading the rest to "see how big it is" is
+        // the failure this exists to prevent.
+        try { await reader.cancel(); } catch { /* already gone */ }
+        throw new ResponseTooLargeError(received, cap, { slug, paid, source: "stream" });
+      }
+      chunks.push(value);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
   }
 
   async _loadCatalog() {
@@ -166,7 +236,7 @@ export class Agent402 {
    * 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 } = {}) {
+  async call(slug, params = {}, { idempotencyKey, cache = true, maxResponseBytes } = {}) {
     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`);
@@ -221,15 +291,33 @@ export class Agent402 {
           const r = await send({}, this.payFetch);
           if (!r.ok) throw new Error(`call "${slug}" failed: HTTP ${r.status}`);
           this._spendSettle(reservation); // confirm the reservation as settled spend
-          return this._store(cacheKey, await r.json(), cache);
+          return this._store(cacheKey, await this._readJson(r, { maxBytes: maxResponseBytes, slug, paid: true }), cache);
         } catch (e) {
           this._spendRelease(reservation); // roll back — nothing settled
           throw e;
         }
       }
+      if (this.creditsKey) {
+        // Prepaid card credits: the server authorizes against the key's balance
+        // before the handler and debits only on a 200 (X-Credits-Balance tells
+        // what is left). The same spend caps apply as on the wallet path.
+        const host = hostOf(this.baseUrl);
+        const usd = parseUsd(tool.price);
+        const reservation = this._spendReserve(host, usd, slug);
+        try {
+          const r = await send({ Authorization: `Bearer ${this.creditsKey}` });
+          if (r.status === 402) {
+            const body = await r.json().catch(() => ({}));
+            throw new Error(`call "${slug}" refused by credits: ${body.error || "payment required"}${body.balanceUsd != null ? ` (balance $${body.balanceUsd})` : ""} - top up at ${body.topup || `${this.baseUrl}/credits`}`);
+          }
+          if (!r.ok) throw new Error(`call "${slug}" failed: HTTP ${r.status}`);
+          this._spendSettle(reservation);
+          return this._store(cacheKey, await this._readJson(r, { maxBytes: maxResponseBytes, slug, paid: true }), cache);
+        } catch (e) { this._spendRelease(reservation); throw e; }
+      }
       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)`);
+      if (r.ok) return this._store(cacheKey, await this._readJson(r, { maxBytes: maxResponseBytes, slug, paid: false }), cache);
+      throw new Error(`call "${slug}" failed: HTTP ${r.status} — wallet-only tool; construct with { fetch: payFetch } (an @x402/fetch-wrapped fetch) or { creditsKey } (prepaid card credits from ${this.baseUrl}/credits)`);
     }
 
     // Free (compute-payable) tool: succeeds plainly on a FREE_MODE instance,
@@ -241,7 +329,7 @@ export class Agent402 {
       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);
+    return this._store(cacheKey, await this._readJson(r, { maxBytes: maxResponseBytes, slug, paid: false }), cache);
   }
 
   async _powChallenge(slug) {
@@ -326,6 +414,20 @@ export class Agent402 {
 
 /** Thrown when a paid call would exceed a configured spending ceiling. The call
  *  is refused BEFORE any payment is signed, so no funds move. */
+/** A response body over the ceiling, refused BEFORE it was parsed.
+ *
+ *  `paid` matters: on a wallet-only tool the money has already moved by the
+ *  time the body arrives, so a caller must be able to tell "I was charged and
+ *  the seller sent something unusable" from "nothing happened". Losing that
+ *  distinction would turn a refused response into a silently forgotten spend. */
+export class ResponseTooLargeError extends Error {
+  constructor(size, cap, { slug, paid, source } = {}) {
+    super(`response for "${slug}" is ${size} bytes, over the ${cap}-byte ceiling (${source}) - refused before parsing${paid ? "; this call WAS paid" : ""}`);
+    this.name = "ResponseTooLargeError";
+    Object.assign(this, { size, cap, slug, paid: Boolean(paid), source });
+  }
+}
+
 export class SpendingLimitError extends Error {
   constructor(message, details = {}) {
     super(message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-client",
-  "version": "0.6.11",
+  "version": "0.8.0",
   "description": "Agent402 buyer SDK: resolve a task to a tool across 500+ pay-per-call endpoints and call it with payment handled - free via proof-of-work, or over x402 or MPP (a stock mppx fetch works) with a wallet you keep; the buy side of Agentic Finance. Caching, idempotent retries (Idempotency-Key), non-custodial, zero dependencies.",
   "type": "module",
   "main": "index.js",