x402-safe-fetch 0.3.1 → 0.5.0

package/README.md

@@ -58,10 +58,45 @@ Solana works the same way: `network: "solana"` and register an `ExactSvmScheme`
 | `cacheMs` | 10 minutes | How long a verdict is reused per method and URL |
 | `verifyReceipts` | `"require"` | Check Doctor's signed receipt on every preflight; `"off"` skips it |
 | `doctorSigners` | Doctor's published signer | Accepted signer addresses (for a self-hosted Doctor) |
+| `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 (see below) |
+| `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.
 
+## 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.
+
+```js
+import { createSafeFetch, diagnosisOf } from "x402-safe-fetch";
+
+const safeFetch = createSafeFetch({ register, maxUsd: 0.05, diagnoseOnFailure: true });
+
+const res = await safeFetch("https://api.example.com/paid");
+if (res.status === 402) {
+  const report = diagnosisOf(res); // { overall: "fail", checks: [{ id, status, message }, …] }
+  console.log(report?.checks.filter((c) => c.status === "fail").map((c) => c.message));
+}
+// When paying throws, the error carries it: err.diagnosis
+```
+
+- One diagnosis per endpoint per `cacheMs`, capped at $0.02 and paid with the same schemes.
+- Like the preflight, the diagnosis must carry Doctor's signed receipt for exactly this endpoint; an unsigned or forged one is dropped, never shown.
+- A diagnosis that fails never changes the outcome: you get the original response or error.
+- Off by default: nothing extra is paid unless you turn it on.
+
+Doctor's requests carry `user-agent: x402-safe-fetch/<version>` so the service can count how often the package is used; nothing about your agent or wallet is sent beyond the payment itself.
+
+## Helping the preflight learn
+
+With `shareOutcomes: true`, safe-fetch tells x402 Doctor what happened after it paid an endpoint that a preflight approved: `paid_ok` (2xx), `paid_failed` (402 again: the payment was not accepted) or `paid_error` (another error). Doctor counts these reports per endpoint over 30 days, from every agent that shares them. When most payments to an endpoint failed, reported by at least three different wallets, later preflights for it answer `caution` (`payments_fail_after_preflight`), so the next agent does not pay into the same wall.
+
+- What is sent: the outcome, the HTTP status, the signed preflight you already received and its query (endpoint, method, budget, network). No keys, no response content.
+- A report only counts with a real, paid preflight for that endpoint, once per preflight, so reports cannot be made up for free.
+- It is sent after the answer and never delays or changes it. Off by default.
+
 ## Signed verdicts
 
 x402 Doctor signs every paid preflight (EIP-191 over canonical JSON, with the request inside the signed body; see [Signed verdicts](https://github.com/Fizzl13/x402-doctor#signed-verdicts)). safe-fetch checks that signature before it acts on a verdict:
@@ -77,6 +112,7 @@ x402 Doctor signs every paid preflight (EIP-191 over canonical JSON, with the re
 ## Costs and limits
 
 - $0.001 per preflight (once per endpoint per 10 minutes), plus the endpoint's own price.
+- With `diagnoseOnFailure`: $0.01 per diagnosis, only when a payment fails (once per endpoint per 10 minutes).
 - 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`).
 - The preflight checks whether a payment can succeed and is sensible; it does not guarantee what the service delivers after payment.

package/index.d.ts

@@ -2,6 +2,8 @@ import type { x402Client } from "@x402/fetch";
 
 export declare const DOCTOR_URL: string;
 export declare const PREFLIGHT_CAP: string;
+export declare const DIAGNOSE_CAP: string;
+export declare const VERSION: string;
 export declare const BASE: "eip155:8453";
 export declare const SOLANA: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
 
@@ -14,10 +16,19 @@ export interface Preflight {
   [key: string]: unknown;
 }
 
+/** The x402 Doctor diagnosis of an endpoint: every check with a fix hint (GET /api/v1/diagnose). */
+export interface Diagnosis {
+  overall: "pass" | "warn" | "fail";
+  checks: Array<{ id: string; status: "pass" | "warn" | "fail" | "info"; message: string; [key: string]: unknown }>;
+  [key: string]: unknown;
+}
+
 export declare class SafePayError extends Error {
   code: "no_go" | "caution" | "preflight_failed" | "bad_receipt" | "no_option";
   preflight: Preflight | null;
   url: string | null;
+  /** Set when diagnoseOnFailure diagnosed a payment that failed. */
+  diagnosis?: Diagnosis;
 }
 
 export interface SafeFetchOptions {
@@ -41,6 +52,11 @@ export interface SafeFetchOptions {
   doctorSigners?: string[];
   /** Wallet whose certificates (receipt.cert) also make a signer trusted, so a rotated Doctor key keeps working. Default: the Fizzl payout wallet; null accepts only doctorSigners. */
   authority?: string | null;
+  /** When a payment still fails (402 again, or paying throws), buy a $0.01 Doctor diagnosis of why. Default false. */
+  diagnoseOnFailure?: boolean;
+  onDiagnosis?: (report: Diagnosis, info: { url: string; method: string; status: number | null; error: Error | null }) => void;
+  /** After paying, tell Doctor whether the payment worked (with the signed preflight as proof), so later preflights learn from it. Default false. */
+  shareOutcomes?: boolean;
   fetch?: typeof globalThis.fetch;
   /** Advanced/testing: a paying fetch capped at `cap` (e.g. "$0.05"). */
   createPayingFetch?: (cap: string) => typeof globalThis.fetch;
@@ -50,6 +66,9 @@ export interface SafeFetchOptions {
 export declare function createSafeFetch(options: SafeFetchOptions): (input: string | URL, init?: RequestInit) => Promise<Response>;
 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;
+/** The Doctor diagnosis attached to a response whose payment failed (diagnoseOnFailure), or null. */
+export declare function diagnosisOf(response: Response): Diagnosis | null;
 export declare function receiptOf(response: Response): { transaction?: string; network?: string; success?: boolean; [key: string]: unknown } | null;
 
 export declare const DOCTOR_SIGNERS: string[];

package/index.js

@@ -9,6 +9,13 @@
 //             function that decides (e.g. ask the user)
 //   go      → pays the endpoint, never more than maxUsd
 // Trusted hosts skip the preflight; a verdict is reused for 10 minutes.
+// With diagnoseOnFailure, a payment that still fails (the endpoint answers 402
+// again, or paying throws) gets a $0.01 Doctor diagnosis that says why and how
+// to fix it: onDiagnosis(report), diagnosisOf(response) or error.diagnosis.
+// With shareOutcomes, after paying it tells Doctor what happened (paid_ok,
+// paid_failed, paid_error), with the signed preflight as proof, so later
+// preflights for that endpoint learn from what agents ran into. Off by
+// default; no keys, amounts or response content are sent.
 // 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).
@@ -23,6 +30,10 @@ 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.5.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";
 export const SOLANA = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
 const NETWORK_ALIASES = { base: BASE, solana: SOLANA };
@@ -45,6 +56,17 @@ export function usdCap(maxUsd) {
   return `$${Number(n.toFixed(6))}`;
 }
 
+export function diagnoseUrl(target, { method = "GET", doctorUrl = DOCTOR_URL } = {}) {
+  const q = new URLSearchParams({ url: target, method });
+  return `${doctorUrl.replace(/\/$/, "")}/api/v1/diagnose?${q}`;
+}
+
+// The Doctor diagnosis attached to a response whose payment failed, or null.
+const diagnoses = new WeakMap();
+export function diagnosisOf(response) {
+  return (response && diagnoses.get(response)) || null;
+}
+
 export function preflightUrl(target, { method = "GET", maxUsd, network, doctorUrl = DOCTOR_URL } = {}) {
   const q = new URLSearchParams({ url: target, method });
   if (maxUsd !== undefined) q.set("max_usd", String(maxUsd).replace(/^\$/, ""));
@@ -96,6 +118,9 @@ function requestOf(input, init) {
  * @param {string[]} [options.doctorSigners]  accepted Doctor signer addresses (default: the published signer)
  * @param {string|null} [options.authority]  wallet whose certificates also make a signer trusted (default: the Fizzl payout wallet; null to accept only doctorSigners)
  * @param {typeof fetch} [options.fetch]  the underlying fetch (default globalThis.fetch)
+ * @param {boolean} [options.diagnoseOnFailure]  when a payment still fails, buy a $0.01 Doctor diagnosis of why (default false)
+ * @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 {(cap: string) => typeof fetch} [options.createPayingFetch]  advanced/testing: a paying fetch capped at `cap`
  * @param {() => number} [options.now]
  */
@@ -111,6 +136,9 @@ export function createSafeFetch({
   verifyReceipts = "require",
   doctorSigners = DOCTOR_SIGNERS,
   authority = AUTHORITY,
+  diagnoseOnFailure = false,
+  onDiagnosis,
+  shareOutcomes = false,
   fetch: baseFetch = globalThis.fetch,
   createPayingFetch,
   now = Date.now,
@@ -137,7 +165,9 @@ export function createSafeFetch({
   });
   let preflightFetch;
   let endpointFetch;
+  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);
 
   const verdicts = new Map();
@@ -146,7 +176,7 @@ export function createSafeFetch({
     const hit = verdicts.get(key);
     if (hit && hit.expires > now()) return { preflight: hit.preflight, cached: true };
     const pfUrl = preflightUrl(url, { method, maxUsd: budget, network: payNetwork, doctorUrl });
-    const res = await payPreflight(pfUrl, { headers: { accept: "application/json" } });
+    const res = await payPreflight(pfUrl, { headers: DOCTOR_HEADERS });
     const preflight = await res.json().catch(() => null);
     if (!res.ok || !preflight?.verdict) {
       throw new SafePayError(`preflight failed (HTTP ${res.status}); the endpoint was not paid`, { code: "preflight_failed", preflight, url });
@@ -162,15 +192,89 @@ export function createSafeFetch({
     return { preflight, cached: false };
   }
 
+  // Why did a payment fail? One paid diagnosis per method and URL per cacheMs;
+  // a diagnosis that fails or is not signed by Doctor is dropped, never thrown.
+  const diagnosed = new Map();
+  async function diagnoseFor(url, method) {
+    const key = `${method} ${url}`;
+    const hit = diagnosed.get(key);
+    if (hit && hit.expires > now()) return hit.report;
+    let report = null;
+    try {
+      const dUrl = diagnoseUrl(url, { method, doctorUrl });
+      const res = await payDiagnose(dUrl, { headers: DOCTOR_HEADERS });
+      const body = await res.json().catch(() => null);
+      if (res.ok && body?.checks) {
+        const input = Object.fromEntries(new URL(dUrl).searchParams);
+        const check = verifyReceipts === "require" ? verifyReceipt(body, { signers: doctorSigners, route: "GET /api/v1/diagnose", input, authority, service: "x402-doctor" }) : { valid: true };
+        if (check.valid) report = body;
+      }
+    } catch {
+      // the original outcome stands; no diagnosis
+    }
+    diagnosed.set(key, { report, expires: now() + cacheMs });
+    if (diagnosed.size > 1000) diagnosed.delete(diagnosed.keys().next().value);
+    return report;
+  }
+
+  // One outcome report per paid preflight: Doctor counts it once anyway.
+  const reported = new Set();
+  function reportOutcome(url, method, preflight, res) {
+    if (!shareOutcomes || !preflight?.receipt?.request_id || reported.has(preflight.receipt.request_id)) return;
+    const outcome = res.ok ? "paid_ok" : res.status === 402 ? "paid_failed" : res.status >= 400 ? "paid_error" : null;
+    if (!outcome) return;
+    reported.add(preflight.receipt.request_id);
+    if (reported.size > 1000) reported.delete(reported.values().next().value);
+    const query = Object.fromEntries(new URL(preflightUrl(url, { method, maxUsd: budget, network: payNetwork, doctorUrl })).searchParams);
+    // Fire and forget: the report never delays or changes the answer.
+    Promise.resolve()
+      .then(() => baseFetch(`${doctorUrl.replace(/\/$/, "")}/api/v1/outcome`, {
+        method: "POST",
+        headers: { ...DOCTOR_HEADERS, "content-type": "application/json" },
+        body: JSON.stringify({ outcome, status: res.status, preflight, query }),
+      }))
+      .then((r) => r?.body?.cancel?.())
+      .catch(() => {});
+  }
+
+  async function payAndCheck(url, init, method) {
+    if (!diagnoseOnFailure) return payEndpoint(url, init);
+    let res;
+    try {
+      res = await payEndpoint(url, init);
+    } catch (error) {
+      if (error instanceof SafePayError && error.code !== "no_option") throw error;
+      const report = await diagnoseFor(url, method);
+      if (report) {
+        try { error.diagnosis = report; } catch { /* frozen error */ }
+        onDiagnosis?.(report, { url, method, status: null, error });
+      }
+      throw error;
+    }
+    if (res.status === 402) {
+      const report = await diagnoseFor(url, method);
+      if (report) {
+        diagnoses.set(res, report);
+        onDiagnosis?.(report, { url, method, status: 402, error: null });
+      }
+    }
+    return res;
+  }
+
   return async function safeFetch(input, init = {}) {
     const { url, method } = requestOf(input, init);
     const probe = await baseFetch(url, init);
     if (probe.status !== 402) return probe;
     try { await probe.body?.cancel(); } catch { /* already consumed */ }
 
-    if (trustedHosts.has(hostOf(url))) return payEndpoint(url, init);
+    if (trustedHosts.has(hostOf(url))) return payAndCheck(url, init, method);
 
     const { preflight, cached } = await preflightFor(url, method);
+    const payAfterPreflight = async () => {
+      const res = await payAndCheck(url, init, method);
+      reportOutcome(url, method, preflight, res);
+      return res;
+    };
     onPreflight?.(preflight, { url, method, cached });
     const why = preflight.summary || preflight.verdict;
     if (preflight.verdict === "no_go") throw new SafePayError(`not paid: ${why}`, { code: "no_go", preflight, url });
@@ -180,6 +284,6 @@ export function createSafeFetch({
     } else if (preflight.verdict !== "go") {
       throw new SafePayError(`not paid: unknown verdict ${preflight.verdict}`, { code: "preflight_failed", preflight, url });
     }
-    return payEndpoint(url, init);
+    return payAfterPreflight();
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-safe-fetch",
-  "version": "0.3.1",
+  "version": "0.5.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": {