x402-safe-fetch 0.3.1 → 0.4.0

package/README.md

@@ -58,10 +58,36 @@ 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) |
+| `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.
+
 ## 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 +103,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,9 @@ 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;
   fetch?: typeof globalThis.fetch;
   /** Advanced/testing: a paying fetch capped at `cap` (e.g. "$0.05"). */
   createPayingFetch?: (cap: string) => typeof globalThis.fetch;
@@ -50,6 +64,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,9 @@
 //             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.
 // 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 +26,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.4.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 +52,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 +114,8 @@ 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 {(cap: string) => typeof fetch} [options.createPayingFetch]  advanced/testing: a paying fetch capped at `cap`
  * @param {() => number} [options.now]
  */
@@ -111,6 +131,8 @@ export function createSafeFetch({
   verifyReceipts = "require",
   doctorSigners = DOCTOR_SIGNERS,
   authority = AUTHORITY,
+  diagnoseOnFailure = false,
+  onDiagnosis,
   fetch: baseFetch = globalThis.fetch,
   createPayingFetch,
   now = Date.now,
@@ -137,7 +159,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 +170,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,13 +186,62 @@ 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;
+  }
+
+  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);
     onPreflight?.(preflight, { url, method, cached });
@@ -180,6 +253,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 payAndCheck(url, init, method);
   };
 }

package/package.json

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