x402-safe-fetch 0.9.0 → 0.10.0

package/README.md

@@ -100,7 +100,7 @@ When a seller offers both, the exact option is paid. The preflight and the budge
 | `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) |
+| `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) |
 | `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` |
 
@@ -138,6 +138,8 @@ With `shareOutcomes: true`, safe-fetch tells x402 Doctor what happened after it
 - 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.
 
+When safe-fetch does **not** pay (a `no_go`, or a `caution` that `onCaution` stops), it reports `refused` with the reason code that stopped it (for example `payto_changed`, `price_changed` or `payee_mismatch`). That is the seller's signal back: Doctor shows sellers how often agents refused to pay their endpoint and why (in the free web check and `GET https://x402-doctor.fizzl.eu/api/v1/refusals?url=…`), as counts only, never who.
+
 ## 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:

package/index.d.ts

@@ -68,7 +68,7 @@ export interface SafeFetchOptions {
   /** 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. */
+  /** After paying, tell Doctor whether the payment worked (with the signed preflight as proof), so later preflights learn from it; when it does not pay (no_go, or a caution it stops at), report "refused" with the reason code, so the seller learns why. Default false. */
   shareOutcomes?: boolean;
   fetch?: typeof globalThis.fetch;
   /** Advanced/testing: a paying fetch capped at `cap` (e.g. "$0.05"). */
@@ -91,3 +91,6 @@ export declare function recoverSigner(message: string, signature: string): strin
 export declare const AUTHORITY: string;
 export declare function certMessage(cert: { service: string; signer: string; valid_from: string }): string;
 export declare function verifyReceipt(body: unknown, options?: { signers?: string[]; route?: string; input?: unknown; authority?: string | null; service?: string }): { valid: boolean; signer?: string; reason?: string };
+
+/** 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;

package/index.js

@@ -15,8 +15,11 @@
 // 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.
+// preflights for that endpoint learn from what agents ran into. When it does
+// not pay (no_go, or a caution it stops at), it reports "refused" with the
+// preflight's reason code, so the seller learns why nobody pays (Doctor shows
+// sellers the counts per reason, never who). 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).
@@ -34,7 +37,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.9.0";
+export const VERSION = "0.10.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";
@@ -124,6 +127,15 @@ export function payableOption(accepts, network, maxUsd) {
   return on.find((a) => a?.scheme === "exact") ?? on.find((a) => a?.scheme === "auth-capture") ?? on[0] ?? null;
 }
 
+// The code that stopped the payment: the preflight's first reason at its verdict's level (no_go, then caution), as
+// Doctor accepts it (a-z, 0-9, _); the verdict itself when there is none.
+export function refusalReason(preflight) {
+  const reasons = Array.isArray(preflight?.reasons) ? preflight.reasons : [];
+  const pick = reasons.find((r) => r?.level === preflight?.verdict) || reasons.find((r) => r?.level === "no_go" || r?.level === "caution");
+  const code = String(pick?.code || preflight?.verdict || "refused").toLowerCase().replace(/[^a-z0-9_]/g, "_").slice(0, 48);
+  return /^[a-z][a-z0-9_]{1,47}$/.test(code) ? code : "refused";
+}
+
 export class SafePayError extends Error {
   /** code: "no_go" | "caution" | "preflight_failed" | "bad_receipt" | "no_option" */
   constructor(message, { code, preflight = null, url = null } = {}) {
@@ -326,10 +338,8 @@ export function createSafeFetch({
 
   // One outcome report per paid preflight: Doctor counts it once anyway.
   const reported = new Set();
-  function reportOutcome(url, method, preflight, res) {
+  function sendOutcome(url, method, preflight, report) {
     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);
@@ -338,11 +348,19 @@ export function createSafeFetch({
       .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 }),
+        body: JSON.stringify({ ...report, preflight, query }),
       }))
       .then((r) => r?.body?.cancel?.())
       .catch(() => {});
   }
+  function reportOutcome(url, method, preflight, res) {
+    const outcome = res.ok ? "paid_ok" : res.status === 402 ? "paid_failed" : res.status >= 400 ? "paid_error" : null;
+    if (outcome) sendOutcome(url, method, preflight, { outcome, status: res.status });
+  }
+  // Not paid after a preflight: "refused", with the reason that stopped it (the first reason at the verdict's level).
+  function reportRefusal(url, method, preflight) {
+    sendOutcome(url, method, preflight, { outcome: "refused", reason: refusalReason(preflight), source: "doctor" });
+  }
 
   async function payAndCheck(url, init, method) {
     if (!diagnoseOnFailure) return payEndpoint(url, init);
@@ -386,10 +404,16 @@ export function createSafeFetch({
     };
     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 });
+    if (preflight.verdict === "no_go") {
+      reportRefusal(url, method, preflight);
+      throw new SafePayError(`not paid: ${why}`, { code: "no_go", preflight, url });
+    }
     if (preflight.verdict === "caution") {
       const ok = onCaution === "pay" || (typeof onCaution === "function" && (await onCaution(preflight)) === true);
-      if (!ok) throw new SafePayError(`not paid (caution): ${why}`, { code: "caution", preflight, url });
+      if (!ok) {
+        reportRefusal(url, method, preflight);
+        throw new SafePayError(`not paid (caution): ${why}`, { code: "caution", preflight, url });
+      }
     } else if (preflight.verdict !== "go") {
       throw new SafePayError(`not paid: unknown verdict ${preflight.verdict}`, { code: "preflight_failed", preflight, url });
     }

package/package.json

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