x402-safe-fetch 0.11.0 → 0.12.0

package/README.md

@@ -6,7 +6,7 @@ A free endpoint is answered as is. For a paid one (HTTP 402), your agent first p
 
 | Preflight | What `safeFetch` does |
 |---|---|
-| `go` | Pays the endpoint, never more than `maxUsd` |
+| `go` | Pays the endpoint, never more than `maxUsd`; with `onIncomplete: "stop"`, not when Doctor says a check couldn't run (`checks_complete: false`) |
 | `caution` | `onCaution`: `"stop"` (default, throws), `"pay"`, or your own function (e.g. ask the user) |
 | `no_go` | Throws `SafePayError`; the endpoint is not paid |
 
@@ -94,6 +94,7 @@ When a seller offers both, the exact option is paid. The preflight and the budge
 | `network` | `"base"` | `"base"`, `"solana"`, `"algorand"` (USDC), `"xrpl"` (RLUSD), `"stellar"` (USDC), `"xlayer"` (USD₮0 or USDC), their `-testnet` forms, or a CAIP-2 id; the preflight checks the option on this network |
 | `maxUsd` | `0.05` | Budget per endpoint call; the payment is capped at it and the preflight says `no_go` above it |
 | `onCaution` | `"stop"` | `"stop"`, `"pay"` or `async (preflight) => boolean` |
+| `onIncomplete` | `"pay"` | A `go` whose `checks_complete` is `false` (a check that applies couldn't run this time, named in `not_checked`): `"pay"`, `"stop"` (throws code `incomplete`; not reported to the seller as a refusal) or `async (preflight) => boolean`. Such a verdict is reused for at most 10 minutes |
 | `trusted` | `[]` | Hosts paid without a preflight |
 | `onPreflight` | | `(preflight, { url, method, cached }) => void`, e.g. for logging |
 | `cacheMs` | 1 hour | How long a verdict is reused per method and URL while the 402 offers the same thing (at most 10 minutes when the offer can't be read); any change in price, payout address, token or network means a new preflight |
@@ -142,11 +143,11 @@ With `shareOutcomes: true`, safe-fetch tells x402 Doctor what happened after it
 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 reason code (for example `price_above_limit`, `network_unsupported` or `trust_low`);
 - 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`.
+No keys, no amounts from your wallet, nothing about you, and no `by` naming safe-fetch, so buyers aren't grouped by the client they use. A `screening_hit` (sanctioned payout address) isn't sent: the draft takes it only signed, and safe-fetch holds no key to sign with. 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
 

package/index.d.ts

@@ -26,6 +26,10 @@ export interface Preflight {
   summary?: string;
   reasons?: Array<{ level: string; code?: string; message: string }>;
   signals?: Record<string, unknown>;
+  checked?: Array<{ check: string; what: string }>;
+  not_checked?: Array<{ check: string; because: "unavailable" | "no_data" | "not_sent" | "out_of_scope"; why: string; send?: string }>;
+  /** false when a check that applies couldn't run this time */
+  checks_complete?: boolean;
   [key: string]: unknown;
 }
 
@@ -37,7 +41,7 @@ export interface Diagnosis {
 }
 
 export declare class SafePayError extends Error {
-  code: "no_go" | "caution" | "preflight_failed" | "bad_receipt" | "no_option";
+  code: "no_go" | "caution" | "incomplete" | "preflight_failed" | "bad_receipt" | "no_option";
   preflight: Preflight | null;
   url: string | null;
   /** Set when diagnoseOnFailure diagnosed a payment that failed. */
@@ -53,6 +57,8 @@ export interface SafeFetchOptions {
   maxUsd?: number | string;
   /** What to do on a caution verdict. Default "stop". */
   onCaution?: "stop" | "pay" | ((preflight: Preflight) => boolean | Promise<boolean>);
+  /** What to do on a "go" whose checks_complete is false (a check that applies couldn't run). Default "pay"; "stop" throws code "incomplete". */
+  onIncomplete?: "pay" | "stop" | ((preflight: Preflight) => boolean | Promise<boolean>);
   /** Hosts you already trust: paid without a preflight. */
   trusted?: string[];
   onPreflight?: (preflight: Preflight, info: { url: string; method: string; cached: boolean }) => void;

package/index.js

@@ -22,8 +22,8 @@
 // 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.
+// 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.
 // 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).
@@ -41,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.11.0";
+export const VERSION = "0.12.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";
@@ -230,6 +230,8 @@ function sameSite(a, b) {
  * @param {string} [options.network]  the network you pay on: "base", "solana", "algorand", "xrpl", "stellar" or a CAIP-2 id (default Base)
  * @param {number|string} [options.maxUsd]  budget per endpoint call (default 0.05)
  * @param {"stop"|"pay"|((preflight: object) => boolean|Promise<boolean>)} [options.onCaution]
+ * @param {"pay"|"stop"|((preflight: object) => boolean|Promise<boolean>)} [options.onIncomplete]  a "go" whose checks_complete
+ *   is false (a check that applies couldn't run): "pay" (default), "stop" throws code "incomplete", a function decides
  * @param {string[]} [options.trusted]  hosts you already trust: paid without a preflight
  * @param {(preflight: object, info: {url: string, method: string, cached: boolean}) => void} [options.onPreflight]
  * @param {number} [options.cacheMs]  how long a verdict is reused while the 402 offers the same thing (default 1 hour; at most 10 minutes when the offer can't be read)
@@ -250,6 +252,7 @@ export function createSafeFetch({
   network = BASE,
   maxUsd = 0.05,
   onCaution = "stop",
+  onIncomplete = "pay",
   trusted = [],
   onPreflight,
   cacheMs = 60 * 60 * 1000,
@@ -273,6 +276,9 @@ export function createSafeFetch({
   if (!["stop", "pay"].includes(onCaution) && typeof onCaution !== "function") {
     throw new TypeError('onCaution must be "stop", "pay" or a function');
   }
+  if (!["pay", "stop"].includes(onIncomplete) && typeof onIncomplete !== "function") {
+    throw new TypeError('onIncomplete must be "pay", "stop" or a function');
+  }
   if (!["require", "off"].includes(verifyReceipts)) throw new TypeError('verifyReceipts must be "require" or "off"');
   const trustedHosts = new Set(trusted.map(hostOf).filter(Boolean));
 
@@ -309,7 +315,9 @@ export function createSafeFetch({
   async function preflightFor(url, method, offer) {
     const key = `${method} ${url}`;
     const hit = verdicts.get(key);
-    const ttl = offer === null ? Math.min(cacheMs, UNREAD_OFFER_MS) : cacheMs;
+    // An unreadable offer, or a verdict on less than usual (checks_complete false), is reused for at most 10 minutes.
+    const short = offer === null || hit?.preflight?.checks_complete === false;
+    const ttl = short ? Math.min(cacheMs, UNREAD_OFFER_MS) : cacheMs;
     if (hit && hit.offer === offer && hit.at + ttl > now()) return { preflight: hit.preflight, cached: true };
     const pfUrl = preflightUrl(url, { method, maxUsd: budget, network: payNetwork, doctorUrl });
     const res = await payPreflight(pfUrl, { headers: DOCTOR_HEADERS });
@@ -391,6 +399,8 @@ export function createSafeFetch({
     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;
+    // The draft takes a screening_hit only signed, and this client holds no key to sign with.
+    if (refusal.signature_required || (refusal.report.reason === "screening_hit" && !refusal.report.signature)) return;
     const key = `${refusal.report.resource} ${refusal.report.reason}`;
     if (now() - (toldSellers.get(key) ?? -Infinity) < 24 * 60 * 60 * 1000) return;
     toldSellers.set(key, now());
@@ -399,7 +409,8 @@ export function createSafeFetch({
       .then(() => baseFetch(target.href, {
         method: "POST",
         headers: { "content-type": "application/json" },
-        body: JSON.stringify({ ...refusal.report, by: `x402-safe-fetch/${VERSION}` }),
+        // No "by": buyers aren't grouped by the client they use.
+        body: JSON.stringify(refusal.report),
         redirect: "error",
       }))
       .then((r) => r?.body?.cancel?.())
@@ -465,6 +476,12 @@ export function createSafeFetch({
       }
     } else if (preflight.verdict !== "go") {
       throw new SafePayError(`not paid: unknown verdict ${preflight.verdict}`, { code: "preflight_failed", preflight, url });
+    } else if (preflight.checks_complete === false && onIncomplete !== "pay") {
+      // "go" on less than usual: a check that applies couldn't run (Doctor's not_checked says which). Not the seller's
+      // doing, so no refusal is reported to it.
+      const ok = typeof onIncomplete === "function" && (await onIncomplete(preflight)) === true;
+      const missing = (preflight.not_checked || []).filter((n) => n?.because === "unavailable").map((n) => n.check).join(", ") || "unknown";
+      if (!ok) throw new SafePayError(`not paid: go, but not every check ran (${missing}); try again in a few minutes`, { code: "incomplete", preflight, url });
     }
     return payAfterPreflight();
   };

package/package.json

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