x402-safe-fetch 0.9.0 → 0.11.0

package/README.md

@@ -100,7 +100,8 @@ 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) |
+| `tellSellers` | `false` | When not paying, tell the seller itself why, if its 402 takes refusals (draft refusal extension, 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 +139,15 @@ 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.
+
+With `tellSellers: true`, a refusal also goes straight to the seller, when its 402 names a refusal url on its own site (the draft refusal extension, [x402-foundation/x402#4087](https://github.com/x402-foundation/x402/issues/4087)). safe-fetch posts the ready report from Doctor's preflight:
+- the reason code (for example `screening_hit` or `price_above_limit`);
+- the sha256 of the refused offer;
+- the endpoint without its query.
+
+No keys, no amounts from your wallet, nothing about you. It goes only to the endpoint's own site, with redirects refused, at most once a day per endpoint and reason, and never delays the error you get. It works with or without `shareOutcomes`.
+
 ## 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,8 +68,10 @@ 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;
+  /** 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;
   fetch?: typeof globalThis.fetch;
   /** Advanced/testing: a paying fetch capped at `cap` (e.g. "$0.05"). */
   createPayingFetch?: (cap: string) => typeof globalThis.fetch;
@@ -91,3 +93,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,15 @@
 // 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.
+// With tellSellers, a refusal also goes to the seller itself when its 402 names a refusal url on its own site (the
+// 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), once a day per endpoint and reason. Off by
+// default.
 // 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 +41,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.11.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 +131,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 } = {}) {
@@ -197,6 +213,17 @@ function requestOf(input, init) {
   return { url: String(input), method: String(init?.method ?? "GET").toUpperCase() };
 }
 
+// Same site: the same host, or the same last two host labels except on shared hosting and two-label country
+// suffixes, where only the exact host counts (as x402 Doctor's lib/refusal.js).
+const SHARED_HOSTING = new Set(["onrender.com", "vercel.app", "netlify.app", "herokuapp.com", "workers.dev", "pages.dev", "github.io", "fly.dev", "railway.app", "replit.app", "repl.co", "web.app", "firebaseapp.com", "appspot.com", "deno.dev", "azurewebsites.net", "cloudfront.net", "amazonaws.com", "ngrok-free.app", "ngrok.io", "trycloudflare.com", "glitch.me", "koyeb.app", "co.uk", "org.uk", "com.au", "co.jp", "com.br", "co.nz", "co.za", "com.cn", "co.in"]);
+function sameSite(a, b) {
+  const x = a.toLowerCase();
+  const y = b.toLowerCase();
+  if (x === y) return true;
+  const base = (h) => h.split(".").slice(-2).join(".");
+  return base(x) === base(y) && !SHARED_HOSTING.has(base(x));
+}
+
 /**
  * @param {object} options
  * @param {(client: x402Client) => unknown} options.register  registers your payment schemes on a client
@@ -214,6 +241,7 @@ function requestOf(input, init) {
  * @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 {boolean} [options.tellSellers]  when not paying, tell the seller why if its 402 takes refusals (default false)
  * @param {(cap: string) => typeof fetch} [options.createPayingFetch]  advanced/testing: a paying fetch capped at `cap`
  * @param {() => number} [options.now]
  */
@@ -232,6 +260,7 @@ export function createSafeFetch({
   diagnoseOnFailure = false,
   onDiagnosis,
   shareOutcomes = false,
+  tellSellers = false,
   fetch: baseFetch = globalThis.fetch,
   createPayingFetch,
   now = Date.now,
@@ -326,10 +355,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 +365,51 @@ 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 });
+  }
+  // The seller's own refusal url (tellSellers): only on the endpoint's own site, only a report about this endpoint,
+  // redirects refused, once a day per endpoint and reason, fire and forget.
+  const toldSellers = new Map();
+  function tellSeller(url, preflight) {
+    const refusal = preflight?.refusal;
+    if (!tellSellers || !refusal?.url || !refusal.report) return;
+    let target;
+    let endpoint;
+    try {
+      target = new URL(refusal.url);
+      endpoint = new URL(url);
+    } catch {
+      return;
+    }
+    if (target.protocol !== "https:" && !["localhost", "127.0.0.1"].includes(target.hostname)) return;
+    if (!sameSite(target.hostname, endpoint.hostname)) return;
+    if (refusal.report.resource !== `${endpoint.origin}${endpoint.pathname}`) return;
+    const key = `${refusal.report.resource} ${refusal.report.reason}`;
+    if (now() - (toldSellers.get(key) ?? -Infinity) < 24 * 60 * 60 * 1000) return;
+    toldSellers.set(key, now());
+    if (toldSellers.size > 1000) toldSellers.delete(toldSellers.keys().next().value);
+    Promise.resolve()
+      .then(() => baseFetch(target.href, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ ...refusal.report, by: `x402-safe-fetch/${VERSION}` }),
+        redirect: "error",
+      }))
+      .then((r) => r?.body?.cancel?.())
+      .catch(() => {});
+  }
+  // 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" });
+    tellSeller(url, preflight);
+  }
 
   async function payAndCheck(url, init, method) {
     if (!diagnoseOnFailure) return payEndpoint(url, init);
@@ -386,10 +453,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.11.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": {