x402-safe-fetch 0.14.0 → 0.15.1

package/README.md

@@ -119,6 +119,8 @@ The hook can't see your request, only the 402, so Doctor checks the endpoint wit
 | `register` | required | `(client) => client.register(network, scheme)`: your payment schemes; your keys stay in your code |
 | `network` | `"base"` | `"base"`, `"solana"`, `"algorand"` (USDC), `"xrpl"` (RLUSD), `"stellar"` (USDC), `"xlayer"` (USD₮0 or USDC), their `-testnet` forms, or a CAIP-2 id; the preflight checks the option on this network |
 | `maxUsd` | `0.05` | Budget per endpoint call; the payment is capped at it and the preflight says `no_go` above it |
+| `maxTotalUsd` | none | Budget for every payment this safeFetch makes together; make one per task or session (see below) |
+| `maxPerSellerUsd` | none | The same per seller (the endpoint's host) |
 | `onCaution` | `"stop"` | `"stop"`, `"pay"` or `async (preflight) => boolean` |
 | `onIncomplete` | `"pay"` | A `go` whose `checks_complete` is `false` (a check that applies couldn't run this time, named in `not_checked`): `"pay"`, `"stop"` (throws code `incomplete`; not reported to the seller as a refusal) or `async (preflight) => boolean`. Such a verdict is reused for at most 10 minutes |
 | `trusted` | `[]` | Hosts paid without a preflight |
@@ -152,6 +154,22 @@ const safeFetch = createSafeFetch({
 
 The guard is also exported on its own (`createPaidGuard`, no dependencies) for agents that pay through another client.
 
+## A budget for the whole task
+
+`maxUsd` caps each payment. A seller that splits its answer over many cheap calls (2 cents a page, "call again for the next page") stays under that cap on every call and still runs up the bill. In the agent exam this is the `page-drip` task. Give safe-fetch a total, a budget per seller, or both:
+
+```js
+const safeFetch = createSafeFetch({
+  register,
+  maxUsd: 0.05,          // each payment
+  maxTotalUsd: 0.10,     // every payment of this safeFetch together
+  maxPerSellerUsd: 0.10, // every payment to one host
+});
+safeFetch.spent(); // { totalUsd: 0.06, bySeller: { "api.example.com": 0.06 } }
+```
+
+A payment that would go past either one throws `SafePayError` with code `over_total_budget` or `over_seller_budget` (and `error.spent`), before the preflight is bought. Near the end, x402's own cap on the next payment shrinks to what is left. The price comes from the seller's 402; when it can't be read, a payment counts as the most it may cost. A payment answered with another 402 isn't counted; a paid error is (the money is gone). Doctor's preflights and diagnoses are not counted. The totals live as long as the safeFetch: make one per task, user or session.
+
 ## When a payment still fails
 
 Sometimes the preflight says `go` and the payment still fails: the endpoint answers 402 again, or paying throws (a facilitator that rejects it, a wrong network). With `diagnoseOnFailure: true`, safe-fetch then buys one **$0.01** [x402 Doctor diagnosis](https://github.com/Fizzl13/x402-doctor#paid-api-for-agents-x402) of that endpoint: every check of its payment flow, with what is wrong and how to fix it.
@@ -211,6 +229,7 @@ x402 Doctor signs every paid preflight (EIP-191 over canonical JSON, with the re
 - With `diagnoseOnFailure`: $0.01 per diagnosis, only when a payment fails (once per endpoint per `cacheMs`).
 - Bodies must be strings, Buffers or `URLSearchParams`: the request is sent once unpaid (to see the 402) and once paid.
 - If Doctor is unreachable, nothing is paid (`SafePayError` with code `preflight_failed`).
+- Bitcoin Lightning (`lnbtc`) isn't paid: its price is in BTC, so the dollar budget can't hold. `createSafeFetch({ network: "lnbtc:…" })` throws, and a Lightning option is never picked. x402 Doctor does check Lightning 402s (the invoice's amount, network, expiry, signer and request hash).
 - The preflight checks whether a payment can succeed and is sensible; it does not guarantee what the service delivers after payment.
 
 Try it without code first: [safe-pay](../safe-pay) is a runnable script with the same logic. MIT licensed.

package/index.d.ts

@@ -41,11 +41,13 @@ export interface Diagnosis {
 }
 
 export declare class SafePayError extends Error {
-  code: "no_go" | "caution" | "incomplete" | "preflight_failed" | "bad_receipt" | "no_option" | "paid_no_delivery";
+  code: "no_go" | "caution" | "incomplete" | "preflight_failed" | "bad_receipt" | "no_option" | "paid_no_delivery" | "over_total_budget" | "over_seller_budget";
   preflight: Preflight | null;
   url: string | null;
   /** With code "paid_no_delivery": when the same request was paid before, and what it was answered with. */
   earlier?: { at: number; status: number };
+  /** With code "over_total_budget" or "over_seller_budget": what this safeFetch had paid. */
+  spent?: SpentUsd;
   /** Set when diagnoseOnFailure diagnosed a payment that failed. */
   diagnosis?: Diagnosis;
 }
@@ -57,6 +59,10 @@ export interface SafeFetchOptions {
   network?: string;
   /** Budget per endpoint call in USD. Default 0.05. */
   maxUsd?: number | string;
+  /** Budget in USD for every payment this safeFetch makes together (make one per task or session). Past it: code "over_total_budget". Default none. */
+  maxTotalUsd?: number | string;
+  /** Budget in USD per seller (the endpoint's host). Past it: code "over_seller_budget". Default none. */
+  maxPerSellerUsd?: number | string;
   /** What to do on a caution verdict. Default "stop". */
   onCaution?: "stop" | "pay" | ((preflight: Preflight) => boolean | Promise<boolean>);
   /** What to do on a "go" whose checks_complete is false (a check that applies couldn't run). Default "pay"; "stop" throws code "incomplete". */
@@ -90,7 +96,22 @@ export interface SafeFetchOptions {
   now?: () => number;
 }
 
-export declare function createSafeFetch(options: SafeFetchOptions): (input: string | URL, init?: RequestInit) => Promise<Response>;
+/** What a safeFetch paid to sellers, in USD (Doctor's preflights and diagnoses not included). */
+export interface SpentUsd {
+  totalUsd: number;
+  bySeller: Record<string, number>;
+}
+export interface SafeFetch {
+  (input: string | URL, init?: RequestInit): Promise<Response>;
+  /** What this safeFetch paid to sellers so far. */
+  spent(): SpentUsd;
+}
+export declare function createSafeFetch(options: SafeFetchOptions): SafeFetch;
+/** What an option costs in USD on `network` (USDC and USD₮0: 6 decimals; Stellar USDC: 7; RLUSD: decimal dollars), or null. */
+/** Why createSafeFetch refuses a Bitcoin Lightning (lnbtc) network: its price is in BTC, so the dollar budget can't hold. */
+export declare const LIGHTNING_UNSUPPORTED: string;
+/** What an option costs in USD on `network` (Lightning: null). */
+export declare function usdOfOption(option: { amount?: unknown; maxAmountRequired?: unknown }, network: string): number | null;
 export declare function usdCap(maxUsd: number | string): string;
 export declare function preflightUrl(target: string, options?: { method?: string; maxUsd?: number | string; network?: string; doctorUrl?: string }): string;
 export declare function diagnoseUrl(target: string, options?: { method?: string; doctorUrl?: string }): string;

package/index.js

@@ -47,7 +47,7 @@ export { verifyReceipt, recoverSigner, canonicalJson, inputHash, certMessage, DO
 export const DOCTOR_URL = "https://x402-doctor.fizzl.eu";
 export const PREFLIGHT_CAP = "$0.002"; // the preflight costs $0.001; never more than twice that
 export const DIAGNOSE_CAP = "$0.02"; // the diagnosis costs $0.01; never more than twice that
-export const VERSION = "0.14.0";
+export const VERSION = "0.15.1";
 // Doctor sees which calls come from this package (in its usage counts), nothing more.
 const DOCTOR_HEADERS = { accept: "application/json", "user-agent": `x402-safe-fetch/${VERSION}` };
 export const BASE = "eip155:8453";
@@ -98,6 +98,10 @@ export function anyAlgorandId(scheme) {
 // (not extra: invoices and nonces change per request). null when there is no x402 challenge to read (e.g. an
 // MPP-only 402). Reads and consumes the response body.
 export async function offerFingerprint(res) {
+  return (await readOffer(res)).fingerprint;
+}
+// The 402's x402 options and their fingerprint (see offerFingerprint). Reads and consumes the response body.
+export async function readOffer(res) {
   let challenge = null;
   const header = res?.headers?.get?.("payment-required");
   if (header) {
@@ -106,14 +110,32 @@ export async function offerFingerprint(res) {
   } else {
     try { challenge = JSON.parse(await res.text()); } catch { /* not JSON */ }
   }
-  if (!Array.isArray(challenge?.accepts)) return null;
+  if (!Array.isArray(challenge?.accepts)) return { fingerprint: null, accepts: null };
   const parts = challenge.accepts.map((a) => JSON.stringify([a?.scheme ?? null, a?.network ?? null, String(a?.asset ?? ""), String(a?.amount ?? a?.maxAmountRequired ?? ""), String(a?.payTo ?? "")]));
-  return JSON.stringify(parts.sort());
+  return { fingerprint: JSON.stringify(parts.sort()), accepts: challenge.accepts };
+}
+
+// What an option paid on `network` costs in US dollars, or null when it can't be read: RLUSD amounts are decimal
+// dollars, Circle's USDC on Stellar has 7 decimals, and every other token safe-fetch pays (USDC, USD₮0) has 6.
+export function usdOfOption(option, network) {
+  if (isLightning(network) || isLightning(option?.network)) return null; // millisatoshis: a BTC price, not dollars
+  const raw = String(option?.amount ?? option?.maxAmountRequired ?? "");
+  if (RLUSD_ISSUER[network]) return /^\d+(\.\d+)?$/.test(raw) ? Number(raw) : null;
+  if (!/^\d+$/.test(raw)) return null;
+  return Number(raw) / (STELLAR_USDC[network] ? 1e7 : 1e6);
 }
 // Without an offer to compare (no readable x402 challenge), a verdict is reused for at most 10 minutes.
 const UNREAD_OFFER_MS = 10 * 60 * 1000;
 
+// Bitcoin Lightning (x402 "exact" on lnbtc: a BOLT11 invoice, priced in millisatoshis). Not paid by safe-fetch: the
+// budget is in dollars and x402's spend controls have no dollar token there, so neither cap would hold.
+export const LIGHTNING_UNSUPPORTED = "Bitcoin Lightning (lnbtc) isn't paid by x402-safe-fetch: its price is in BTC, so the dollar budget can't hold. Pay a USDC option on another network, or check the endpoint with x402 Doctor (it checks Lightning invoices) and pay with your Lightning client.";
+function isLightning(network) {
+  return String(network ?? "").startsWith("lnbtc:");
+}
+
 export function payableOption(accepts, network, maxUsd) {
+  if (isLightning(network)) return null;
   const cap = Number(String(maxUsd).replace(/^\$/, ""));
   const on = (accepts ?? []).filter((a) => algorandId(a?.network) === algorandId(network));
   const usdc = ALGORAND_USDC[algorandId(network)];
@@ -147,14 +169,15 @@ export function refusalReason(preflight) {
 }
 
 export class SafePayError extends Error {
-  /** code: "no_go" | "caution" | "incomplete" | "preflight_failed" | "bad_receipt" | "no_option" | "paid_no_delivery" */
-  constructor(message, { code, preflight = null, url = null, earlier } = {}) {
+  /** code: "no_go" | "caution" | "incomplete" | "preflight_failed" | "bad_receipt" | "no_option" | "paid_no_delivery" | "over_total_budget" | "over_seller_budget" */
+  constructor(message, { code, preflight = null, url = null, earlier, spent } = {}) {
     super(message);
     this.name = "SafePayError";
     this.code = code;
     this.preflight = preflight;
     this.url = url;
     if (earlier) this.earlier = earlier;
+    if (spent) this.spent = spent;
   }
 }
 
@@ -236,6 +259,9 @@ function sameSite(a, b) {
  * @param {(client: x402Client) => unknown} options.register  registers your payment schemes on a client
  * @param {string} [options.network]  the network you pay on: "base", "solana", "algorand", "xrpl", "stellar" or a CAIP-2 id (default Base)
  * @param {number|string} [options.maxUsd]  budget per endpoint call (default 0.05)
+ * @param {number|string} [options.maxTotalUsd]  budget for every endpoint payment this safeFetch makes together (make
+ *   one per task or session); a payment that would pass it is refused with code "over_total_budget" (default: none)
+ * @param {number|string} [options.maxPerSellerUsd]  the same per seller (the endpoint's host); code "over_seller_budget"
  * @param {"stop"|"pay"|((preflight: object) => boolean|Promise<boolean>)} [options.onCaution]
  * @param {"pay"|"stop"|((preflight: object) => boolean|Promise<boolean>)} [options.onIncomplete]  a "go" whose checks_complete
  *   is false (a check that applies couldn't run): "pay" (default), "stop" throws code "incomplete", a function decides
@@ -262,6 +288,8 @@ export function createSafeFetch({
   register,
   network = BASE,
   maxUsd = 0.05,
+  maxTotalUsd,
+  maxPerSellerUsd,
   onCaution = "stop",
   onIncomplete = "pay",
   trusted = [],
@@ -282,7 +310,12 @@ export function createSafeFetch({
   now = Date.now,
 } = {}) {
   const payNetwork = NETWORK_ALIASES[network] ?? network;
+  if (isLightning(payNetwork)) throw new TypeError(LIGHTNING_UNSUPPORTED);
   const budget = usdCap(maxUsd);
+  const perCall = Number(budget.slice(1));
+  const totalCap = maxTotalUsd === undefined || maxTotalUsd === null ? null : Number(usdCap(maxTotalUsd).slice(1));
+  const sellerCap = maxPerSellerUsd === undefined || maxPerSellerUsd === null ? null : Number(usdCap(maxPerSellerUsd).slice(1));
+  const limited = totalCap !== null || sellerCap !== null;
   if (!createPayingFetch && typeof register !== "function") {
     throw new TypeError("register is required: (client) => client.register(network, scheme)");
   }
@@ -326,7 +359,47 @@ export function createSafeFetch({
   let diagnoseFetch;
   const payPreflight = (...args) => (preflightFetch ??= makePayingFetch(PREFLIGHT_CAP))(...args);
   const payDiagnose = (...args) => (diagnoseFetch ??= makePayingFetch(DIAGNOSE_CAP))(...args);
-  const payEndpoint = (...args) => (endpointFetch ??= makePayingFetch(budget))(...args);
+  // With a total or per-seller budget, a payment is capped at what is left of it (x402's spend controls): a paying
+  // fetch per cap, kept for the caps in use.
+  const cappedFetches = new Map();
+  const payEndpoint = (url, init, cap = budget) => {
+    if (cap === budget) return (endpointFetch ??= makePayingFetch(budget))(url, init);
+    if (!cappedFetches.has(cap)) {
+      if (cappedFetches.size >= 50) cappedFetches.delete(cappedFetches.keys().next().value);
+      cappedFetches.set(cap, makePayingFetch(cap));
+    }
+    return cappedFetches.get(cap)(url, init);
+  };
+
+  // What was paid (or is being paid) to sellers, for maxTotalUsd and maxPerSellerUsd, in dollars.
+  const spend = { total: 0, bySeller: new Map() };
+  const round6 = (n) => Math.round(n * 1e6) / 1e6;
+  const spentAt = (host) => spend.bySeller.get(host) ?? 0;
+  function addSpend(host, usd) {
+    spend.total = round6(spend.total + usd);
+    spend.bySeller.set(host, round6(spentAt(host) + usd));
+  }
+  const spentNow = () => ({ totalUsd: spend.total, bySeller: Object.fromEntries(spend.bySeller) });
+  // What one more payment to `host` may cost: the per-call budget, or less when the total or the seller's budget is
+  // nearly spent. Throws when nothing is left of either, or when the price (if it can be read) is over what is left.
+  // A price over the per-call budget alone is left to Doctor's preflight (over_budget) and x402's cap, as before.
+  function allowance(url, host, price) {
+    const totalLeft = totalCap === null ? Infinity : round6(totalCap - spend.total);
+    const sellerLeft = sellerCap === null ? Infinity : round6(sellerCap - spentAt(host));
+    const cap = Math.min(perCall, totalLeft, sellerLeft);
+    const short = Math.min(totalLeft, sellerLeft);
+    const over = short <= 0 || (price !== null && price > short + 1e-9);
+    if (over) {
+      const byTotal = totalLeft <= sellerLeft;
+      const which = byTotal ? `the total budget ($${totalCap})` : `the budget for ${host} ($${sellerCap})`;
+      const asks = price === null ? "" : `; the endpoint asks $${round6(price)}`;
+      const paid = byTotal ? spend.total : spentAt(host);
+      throw new SafePayError(`not paid: ${which} has $${Math.max(0, short)} left${asks} (already paid $${paid})`, {
+        code: byTotal ? "over_total_budget" : "over_seller_budget", url, spent: spentNow(),
+      });
+    }
+    return { cap, price };
+  }
 
   const verdicts = new Map();
   async function preflightFor(url, method, offer) {
@@ -440,16 +513,36 @@ export function createSafeFetch({
   }
 
   // Every endpoint payment goes through here: what it was answered with is remembered for the paid-twice guard.
-  async function payAndCheck(url, init, method) {
-    const res = await payAndDiagnose(url, init, method);
+  // With a total or per-seller budget, the payment is capped at what is left and counted as it starts (so parallel
+  // calls can't both spend the rest), and taken back when nothing was paid (402 again, or paying threw).
+  async function payAndCheck(url, init, method, offer) {
+    let host = null;
+    let counted = 0;
+    let cap = budget;
+    if (limited) {
+      host = hostOf(url);
+      const option = offer?.accepts ? payableOption(offer.accepts, payNetwork, budget) : null;
+      const allowed = allowance(url, host, option ? usdOfOption(option, payNetwork) : null);
+      counted = allowed.price ?? allowed.cap; // an unreadable price counts as the most it may cost
+      if (allowed.cap < perCall) cap = usdCap(allowed.cap);
+      addSpend(host, counted);
+    }
+    let res;
+    try {
+      res = await payAndDiagnose(url, init, method, cap);
+    } catch (error) {
+      if (limited) addSpend(host, -counted);
+      throw error;
+    }
+    if (limited && res.status === 402) addSpend(host, -counted);
     paidGuard.record(url, { method, body: init.body }, res.status);
     return res;
   }
-  async function payAndDiagnose(url, init, method) {
-    if (!diagnoseOnFailure) return payEndpoint(url, init);
+  async function payAndDiagnose(url, init, method, cap) {
+    if (!diagnoseOnFailure) return payEndpoint(url, init, cap);
     let res;
     try {
-      res = await payEndpoint(url, init);
+      res = await payEndpoint(url, init, cap);
     } catch (error) {
       if (error instanceof SafePayError && error.code !== "no_option") throw error;
       const report = await diagnoseFor(url, method);
@@ -469,7 +562,7 @@ export function createSafeFetch({
     return res;
   }
 
-  return async function safeFetch(input, init = {}) {
+  async function safeFetch(input, init = {}) {
     const { url, method } = requestOf(input, init);
     const probe = await baseFetch(url, init);
     if (probe.status !== 402) return probe;
@@ -484,14 +577,18 @@ export function createSafeFetch({
       }
     }
 
-    if (trustedHosts.has(hostOf(url))) {
-      try { await probe.body?.cancel(); } catch { /* already consumed */ }
-      return payAndCheck(url, init, method);
+    const offer = await readOffer(probe);
+    // Already over the total or the seller's budget: refused before the preflight, so nothing is spent on it.
+    if (limited) {
+      const option = offer.accepts ? payableOption(offer.accepts, payNetwork, budget) : null;
+      allowance(url, hostOf(url), option ? usdOfOption(option, payNetwork) : null);
     }
 
-    const { preflight, cached } = await preflightFor(url, method, await offerFingerprint(probe));
+    if (trustedHosts.has(hostOf(url))) return payAndCheck(url, init, method, offer);
+
+    const { preflight, cached } = await preflightFor(url, method, offer.fingerprint);
     const payAfterPreflight = async () => {
-      const res = await payAndCheck(url, init, method);
+      const res = await payAndCheck(url, init, method, offer);
       reportOutcome(url, method, preflight, res);
       return res;
     };
@@ -517,5 +614,8 @@ export function createSafeFetch({
       if (!ok) throw new SafePayError(`not paid: go, but not every check ran (${missing}); try again in a few minutes`, { code: "incomplete", preflight, url });
     }
     return payAfterPreflight();
-  };
+  }
+  // What this safeFetch paid to sellers so far, in US dollars (Doctor's preflights and diagnoses not included).
+  safeFetch.spent = spentNow;
+  return safeFetch;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-safe-fetch",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "A fetch for AI agents that checks an unknown x402 endpoint ($0.001 x402 Doctor preflight) before paying it, and never pays above your budget.",
   "type": "module",
   "exports": {