x402-safe-fetch 0.13.0 → 0.14.0

package/README.md

@@ -129,11 +129,29 @@ The hook can't see your request, only the 402, so Doctor checks the endpoint wit
 | `diagnoseOnFailure` | `false` | When a payment still fails, buy a $0.01 Doctor diagnosis of why (see below) |
 | `shareOutcomes` | `false` | After paying, tell Doctor whether the payment worked, so its later preflights learn from it; when not paying, tell it why (see below) |
 | `tellSellers` | `false` | When not paying, tell the seller itself why, if its 402 takes refusals (draft refusal extension, see below) |
+| `onPaidError` | `"stop"` | The same request was paid before and answered without delivering: `"stop"` throws code `paid_no_delivery`, `"pay"` pays again, or a function decides (see below) |
+| `paidErrorMs` | 30 minutes | How long such a request stays blocked |
 | `onDiagnosis` | | `(report, { url, method, status, error }) => void`, e.g. for logging or alerting |
 | `authority` | the Fizzl payout wallet | Wallet whose certificates also make a signer trusted (key rotation); `null` accepts only `doctorSigners` |
 
 The preflight itself is capped at $0.002 and paid with the same schemes. `receiptOf(response)` returns the payment receipt (transaction hash) of a paid response.
 
+## Never paid twice for nothing
+
+A seller can take the payment and still answer with an error: a 405, a 500, or another 402 asking to pay again. Paying the same request again then usually costs a second payment for nothing. In the agent exam at [exam.fizzl.eu](https://exam.fizzl.eu) this was the most common loss: every model we examined did it at least once, with or without a preflight, because a preflight only sees the 402 before paying.
+
+So safe-fetch remembers each paid request (method, URL and body) whose paid answer was not a success. Calling that same request again within 30 minutes throws `SafePayError` with code `paid_no_delivery` (and `error.earlier`: when it was paid and what it was answered with), without paying and without buying another preflight. A different request is not affected, and a success clears it.
+
+```js
+const safeFetch = createSafeFetch({
+  register,
+  onPaidError: "stop", // default; "pay" pays again, or a function (earlier, { url, method }) => boolean decides
+  paidErrorMs: 30 * 60 * 1000, // how long such a request stays blocked
+});
+```
+
+The guard is also exported on its own (`createPaidGuard`, no dependencies) for agents that pay through another client.
+
 ## 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.

package/index.d.ts

@@ -41,9 +41,11 @@ export interface Diagnosis {
 }
 
 export declare class SafePayError extends Error {
-  code: "no_go" | "caution" | "incomplete" | "preflight_failed" | "bad_receipt" | "no_option";
+  code: "no_go" | "caution" | "incomplete" | "preflight_failed" | "bad_receipt" | "no_option" | "paid_no_delivery";
   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 };
   /** Set when diagnoseOnFailure diagnosed a payment that failed. */
   diagnosis?: Diagnosis;
 }
@@ -78,6 +80,10 @@ export interface SafeFetchOptions {
   shareOutcomes?: boolean;
   /** When not paying, tell the seller why if its 402 names a refusal url on its own site (draft x402-foundation/x402#4087). Default false. */
   tellSellers?: boolean;
+  /** The same request (method, URL, body) was paid before and answered without delivering (an error, or another 402): "stop" (default) throws code "paid_no_delivery" without paying, "pay" pays again, a function decides. */
+  onPaidError?: "stop" | "pay" | ((earlier: { at: number; status: number }, info: { url: string; method: string }) => boolean | Promise<boolean>);
+  /** How long such a request stays blocked, in ms. Default 30 minutes. A success clears it. */
+  paidErrorMs?: number;
   fetch?: typeof globalThis.fetch;
   /** Advanced/testing: a paying fetch capped at `cap` (e.g. "$0.05"). */
   createPayingFetch?: (cap: string) => typeof globalThis.fetch;
@@ -102,3 +108,13 @@ export declare function verifyReceipt(body: unknown, options?: { signers?: strin
 
 /** The reason code reported with a refused outcome: the preflight's first reason at its verdict's level. */
 export function refusalReason(preflight: { verdict?: string; reasons?: { level?: string; code?: string }[] }): string;
+
+/** Remembers paid requests that weren't delivered, so the same request isn't paid again (used by createSafeFetch; usable on its own). */
+export declare function createPaidGuard(options?: { windowMs?: number; now?: () => number }): {
+  blocked(url: string, init?: { method?: string; body?: unknown }): { at: number; status: number } | null;
+  record(url: string, init: { method?: string; body?: unknown } | undefined, status: number): void;
+  clear(url: string, init?: { method?: string; body?: unknown }): void;
+};
+export declare function purchaseKey(url: string, init?: { method?: string; body?: unknown }): string;
+export declare function paidTwiceMessage(url: string, earlier: { at: number; status: number }): string;
+export declare const PAID_ERROR_MS: number;

package/index.js

@@ -24,6 +24,10 @@
 // draft refusal extension, x402-foundation/x402#4087): the ready report from Doctor's preflight (reason code and the
 // hash of the refused offer; no query, no keys, nothing about the buyer or this client), once a day per endpoint and
 // reason. A screening_hit isn't sent: the draft takes it only signed. Off by default.
+// A paid request answered without delivery (an error, or another 402) is never paid again on its own: the same
+// method, URL and body within paidErrorMs throws SafePayError code "paid_no_delivery" (onPaidError "stop", the
+// default). The most common loss in the agent exam (exam.fizzl.eu) was paying again after a seller took the payment
+// and answered with an error; a preflight can't see that, it only reads the 402 before paying (paid-guard.js).
 // Every preflight must carry Doctor's signed receipt for exactly this request
 // (endpoint, method, budget, network), checked against Doctor's pinned signer:
 // a missing, changed or forged verdict is never a payment (receipt.js).
@@ -35,13 +39,15 @@
 
 import { wrapFetchWithPayment, x402Client, decodePaymentResponseHeader } from "@x402/fetch";
 import { verifyReceipt, DOCTOR_SIGNERS, AUTHORITY } from "./receipt.js";
+import { createPaidGuard, paidTwiceMessage, PAID_ERROR_MS } from "./paid-guard.js";
 
+export { createPaidGuard, purchaseKey, paidTwiceMessage, PAID_ERROR_MS } from "./paid-guard.js";
 export { verifyReceipt, recoverSigner, canonicalJson, inputHash, certMessage, DOCTOR_SIGNERS, AUTHORITY } from "./receipt.js";
 
 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.13.0";
+export const VERSION = "0.14.0";
 // 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";
@@ -141,13 +147,14 @@ export function refusalReason(preflight) {
 }
 
 export class SafePayError extends Error {
-  /** code: "no_go" | "caution" | "preflight_failed" | "bad_receipt" | "no_option" */
-  constructor(message, { code, preflight = null, url = null } = {}) {
+  /** code: "no_go" | "caution" | "incomplete" | "preflight_failed" | "bad_receipt" | "no_option" | "paid_no_delivery" */
+  constructor(message, { code, preflight = null, url = null, earlier } = {}) {
     super(message);
     this.name = "SafePayError";
     this.code = code;
     this.preflight = preflight;
     this.url = url;
+    if (earlier) this.earlier = earlier;
   }
 }
 
@@ -244,6 +251,10 @@ function sameSite(a, b) {
  * @param {(report: object, info: {url: string, method: string, status: number|null, error: Error|null}) => void} [options.onDiagnosis]
  * @param {boolean} [options.shareOutcomes]  after paying, tell Doctor whether the payment worked (default false)
  * @param {boolean} [options.tellSellers]  when not paying, tell the seller why if its 402 takes refusals (default false)
+ * @param {"stop"|"pay"|((earlier: {at: number, status: number}, info: {url: string, method: string}) => boolean|Promise<boolean>)} [options.onPaidError]
+ *   the same request was paid before and answered without delivering: "stop" (default) throws code "paid_no_delivery",
+ *   "pay" pays again, a function decides
+ * @param {number} [options.paidErrorMs]  how long such a request stays blocked (default 30 minutes)
  * @param {(cap: string) => typeof fetch} [options.createPayingFetch]  advanced/testing: a paying fetch capped at `cap`
  * @param {() => number} [options.now]
  */
@@ -264,6 +275,8 @@ export function createSafeFetch({
   onDiagnosis,
   shareOutcomes = false,
   tellSellers = false,
+  onPaidError = "stop",
+  paidErrorMs = PAID_ERROR_MS,
   fetch: baseFetch = globalThis.fetch,
   createPayingFetch,
   now = Date.now,
@@ -279,6 +292,10 @@ export function createSafeFetch({
   if (!["pay", "stop"].includes(onIncomplete) && typeof onIncomplete !== "function") {
     throw new TypeError('onIncomplete must be "pay", "stop" or a function');
   }
+  if (!["stop", "pay"].includes(onPaidError) && typeof onPaidError !== "function") {
+    throw new TypeError('onPaidError must be "stop", "pay" or a function');
+  }
+  const paidGuard = createPaidGuard({ windowMs: paidErrorMs, now });
   if (!["require", "off"].includes(verifyReceipts)) throw new TypeError('verifyReceipts must be "require" or "off"');
   const trustedHosts = new Set(trusted.map(hostOf).filter(Boolean));
 
@@ -422,7 +439,13 @@ export function createSafeFetch({
     tellSeller(url, preflight);
   }
 
+  // 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);
+    paidGuard.record(url, { method, body: init.body }, res.status);
+    return res;
+  }
+  async function payAndDiagnose(url, init, method) {
     if (!diagnoseOnFailure) return payEndpoint(url, init);
     let res;
     try {
@@ -451,6 +474,16 @@ export function createSafeFetch({
     const probe = await baseFetch(url, init);
     if (probe.status !== 402) return probe;
 
+    // Paid before and not delivered: not paid again (and no preflight bought) unless onPaidError says so.
+    const earlier = paidGuard.blocked(url, { method, body: init.body });
+    if (earlier && onPaidError !== "pay") {
+      const again = typeof onPaidError === "function" && (await onPaidError(earlier, { url, method })) === true;
+      if (!again) {
+        try { await probe.body?.cancel(); } catch { /* already consumed */ }
+        throw new SafePayError(paidTwiceMessage(url, earlier), { code: "paid_no_delivery", url, earlier });
+      }
+    }
+
     if (trustedHosts.has(hostOf(url))) {
       try { await probe.body?.cancel(); } catch { /* already consumed */ }
       return payAndCheck(url, init, method);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-safe-fetch",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "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": {
@@ -18,6 +18,7 @@
   "files": [
     "index.js",
     "receipt.js",
+    "paid-guard.js",
     "hook.js",
     "index.d.ts",
     "hook.d.ts",

package/paid-guard.js

@@ -0,0 +1,64 @@
+// Never pay twice for one purchase that wasn't delivered.
+//
+// The costliest mistake in the agent exam (exam.fizzl.eu): a seller takes the payment, then answers with an error
+// (a 405, a 500, or another 402 asking to pay again), and the agent pays the same request again, and again. Every
+// model we examined did it at least once, with or without a preflight: the preflight only sees the 402 before paying.
+//
+// The guard remembers each paid request (method, URL and body) whose paid answer was not a success. Paying that same
+// request again within the window is refused, so the loss stops at one payment. A success clears it. A different
+// request (another URL, method or body) is not affected. No dependencies: it runs anywhere fetch does.
+
+export const PAID_ERROR_MS = 30 * 60 * 1000;
+
+// A short, stable fingerprint of the body (FNV-1a, 32 bit): the key holds no request content.
+function bodyKey(body) {
+  if (body === undefined || body === null) return "";
+  const text = typeof body === "string" ? body : body instanceof URLSearchParams ? body.toString() : ArrayBuffer.isView(body) ? new TextDecoder().decode(body) : body instanceof ArrayBuffer ? new TextDecoder().decode(new Uint8Array(body)) : String(body);
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return `${text.length}:${h.toString(16)}`;
+}
+
+/** The request as the guard sees it: method, URL and a fingerprint of the body. */
+export function purchaseKey(url, { method = "GET", body } = {}) {
+  return `${String(method).toUpperCase()} ${String(url)} ${bodyKey(body)}`;
+}
+
+/**
+ * @param {object} [options]
+ * @param {number} [options.windowMs]  how long a paid request that wasn't delivered stays blocked (default 30 minutes)
+ * @param {() => number} [options.now]
+ */
+export function createPaidGuard({ windowMs = PAID_ERROR_MS, now = Date.now } = {}) {
+  const failed = new Map(); // purchase key → { at, status }
+  const prune = () => {
+    const t = now();
+    for (const [k, v] of failed) if (t - v.at >= windowMs) failed.delete(k);
+    while (failed.size > 1000) failed.delete(failed.keys().next().value);
+  };
+  return {
+    /** The earlier paid answer that wasn't delivered ({ at, status }), while it blocks this request; else null. */
+    blocked(url, init = {}) {
+      prune();
+      return failed.get(purchaseKey(url, init)) ?? null;
+    },
+    /** After paying: what the paid request was answered with. */
+    record(url, init = {}, status) {
+      const key = purchaseKey(url, init);
+      if (status >= 200 && status < 300) failed.delete(key);
+      else failed.set(key, { at: now(), status });
+    },
+    /** Forget a request (e.g. the owner said to pay it again). */
+    clear(url, init = {}) {
+      failed.delete(purchaseKey(url, init));
+    },
+  };
+}
+
+/** The refusal text, for an error or a tool answer. */
+export function paidTwiceMessage(url, earlier) {
+  return `not paid again: ${url} was already paid at ${new Date(earlier.at).toISOString()} and answered HTTP ${earlier.status} without delivering. Paying the same request again would most likely be charged again for nothing; ask the seller, or try a different request.`;
+}