x402-safe-fetch 0.8.0 → 0.10.0

package/README.md

@@ -45,7 +45,7 @@ try {
 
 Solana works the same way: `network: "solana"` and register an `ExactSvmScheme` from `@x402/svm/exact/client` with a `@solana/kit` signer.
 
-Algorand and the XRP Ledger work the same way, and only their dollar stablecoin is ever paid. On Algorand that is USDC (ASA 31566704), never ALGO or another ASA. On the XRP Ledger it is RLUSD from Ripple's issuer, never XRP or a look-alike token. RLUSD prices are decimal dollars, so the budget is checked in dollars. The Doctor preflight is paid on the same network.
+Algorand and the XRP Ledger work the same way, and only their dollar stablecoin is ever paid. On Algorand that is USDC (ASA 31566704), never ALGO or another ASA. Sellers name Algorand mainnet either by the whole genesis hash or by its CAIP-2 id (`algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k`); both are paid, also with `@x402/avm` 2.29.0, which on its own accepts only the short id. On the XRP Ledger it is RLUSD from Ripple's issuer, never XRP or a look-alike token. RLUSD prices are decimal dollars, so the budget is checked in dollars. The Doctor preflight is paid on the same network.
 
 ```js
 import { toClientAvmSigner } from "@x402/avm";
@@ -65,6 +65,27 @@ const safeFetch = createSafeFetch({
 // facilitator (PayAI) pays the gas.
 ```
 
+### Escrowed payments (auth-capture)
+
+Some sellers on Base take payment through Coinbase's escrow instead of a direct transfer: the x402 scheme
+`auth-capture`. Your wallet signs once, the USDC is held, and the seller captures it only after it has delivered
+(Atom's domain checkout, for instance, captures once the domain is registered, and releases it if registration
+fails). Register that scheme next to the exact one to pay such sellers (`@x402/evm` 2.27 or later):
+
+```js
+import { AuthCaptureEvmScheme } from "@x402/evm/auth-capture/client";
+
+const safeFetch = createSafeFetch({
+  register: (client) => {
+    client.register("eip155:8453", new ExactEvmScheme(account));
+    client.register("eip155:8453", new AuthCaptureEvmScheme(account));
+  },
+  maxUsd: 25, // the budget caps the most that can be captured
+});
+```
+
+When a seller offers both, the exact option is paid. The preflight and the budget apply the same way.
+
 ## Options
 
 | Option | Default | |
@@ -79,7 +100,7 @@ const safeFetch = createSafeFetch({
 | `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` |
 
@@ -117,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

@@ -16,6 +16,8 @@ export declare const XLAYER: "eip155:196";
 /** The option paid on `network`: on Algorand only USDC, on Stellar only Circle's USDC contract within maxUsd, on X Layer only USD₮0 or USDC within maxUsd, on the XRP Ledger only RLUSD from Ripple's issuer within maxUsd (in dollars); null when there is none. */
 /** What a 402 offers (per x402 option: scheme, network, asset, amount, payTo) as a stable string; null without a readable x402 challenge. Consumes the body. */
 export declare function offerFingerprint(res: Response): Promise<string | null>;
+/** Wraps an Algorand scheme (e.g. @x402/avm's ExactAvmScheme) so it pays sellers that name Algorand by the whole genesis hash as well as by the CAIP-2 id. createSafeFetch does this for you. */
+export declare function anyAlgorandId<S extends object>(scheme: S): S;
 export declare function payableOption<A extends { network: string; asset?: unknown; amount?: unknown; extra?: Record<string, unknown> }>(accepts: A[], network: string, maxUsd: number | string): A | null;
 
 /** The x402 Doctor preflight: see https://x402-doctor.fizzl.eu/openapi.json */
@@ -66,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"). */
@@ -89,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.8.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";
@@ -50,7 +53,7 @@ const NETWORK_ALIASES = { base: BASE, solana: SOLANA, algorand: ALGORAND, "algor
 
 // On Algorand and the XRP Ledger only the dollar stablecoin is paid: USDC (an ASA) on Algorand, RLUSD from
 // Ripple's issuer on the XRP Ledger. Never ALGO, XRP or another token, so the dollar budget always holds.
-const ALGORAND_USDC = { [ALGORAND]: "31566704", [ALGORAND_TESTNET]: "10458941" };
+const ALGORAND_USDC = { [algorandId(ALGORAND)]: "31566704", [algorandId(ALGORAND_TESTNET)]: "10458941" };
 const RLUSD_HEX = "524C555344000000000000000000000000000000";
 const RLUSD_ISSUER = { [XRPL]: "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De", [XRPL_TESTNET]: "rQhWct2fv4Vc4KRjRgMrxa8xPN9Zx9iLKV" };
 // On Stellar only Circle's USDC token contract (7 decimals), never XLM or another token named USDC.
@@ -62,6 +65,23 @@ const XLAYER_DOLLARS = {
   [XLAYER]: ["0x779ded0c9e1022225f8e0630b35a9b54be713736", "0x74b7f16337b8972027f6196a17a631ac6de26d22"],
 };
 
+// Algorand by its CAIP-2 id: the first 32 characters of the genesis hash. Sellers name it either way (the whole hash,
+// or since @x402/avm 2.29.0 only the short id), so networks are compared by this.
+function algorandId(network) {
+  return typeof network === "string" && network.startsWith("algorand:") ? network.slice(0, 41) : network;
+}
+
+// @x402/avm 2.29.0's ExactAvmScheme refuses the whole-hash form, which most Algorand sellers still use (2.28.0 took
+// both). This hands the scheme the short id; the payment still names the seller's own network (x402 puts the
+// seller's option in `accepted`), so either kind of seller can be paid. createSafeFetch wraps Algorand schemes in it.
+export function anyAlgorandId(scheme) {
+  return Object.assign(Object.create(scheme), {
+    createPaymentPayload: (version, requirements, context) =>
+      scheme.createPaymentPayload(version, { ...requirements, network: algorandId(requirements.network) }, context),
+    ...(typeof scheme.findDefaultAsset === "function" && { findDefaultAsset: (asset, network) => scheme.findDefaultAsset(asset, algorandId(network)) }),
+  });
+}
+
 // The option to pay on `network`, or null. RLUSD prices are decimal dollars ("0.001", and "2" is two dollars),
 // which x402's spend controls would read as base units, so the budget is checked here in dollars.
 // What a 402 offers, as a stable string: per x402 option its scheme, network, asset, amount and payout address
@@ -85,8 +105,9 @@ const UNREAD_OFFER_MS = 10 * 60 * 1000;
 
 export function payableOption(accepts, network, maxUsd) {
   const cap = Number(String(maxUsd).replace(/^\$/, ""));
-  const on = (accepts ?? []).filter((a) => a?.network === network);
-  if (ALGORAND_USDC[network]) return on.find((a) => String(a.asset) === ALGORAND_USDC[network]) ?? null;
+  const on = (accepts ?? []).filter((a) => algorandId(a?.network) === algorandId(network));
+  const usdc = ALGORAND_USDC[algorandId(network)];
+  if (usdc) return on.find((a) => String(a.asset) === usdc) ?? null;
   // x402's spend controls cap Stellar USDC too; the budget is checked here as well, in dollars.
   if (STELLAR_USDC[network]) {
     return on.find((a) => a.asset === STELLAR_USDC[network] && /^\d+$/.test(String(a.amount)) && Number(a.amount) > 0 && Number(a.amount) / 1e7 <= cap) ?? null;
@@ -99,7 +120,20 @@ export function payableOption(accepts, network, maxUsd) {
     return on.find((a) => String(a.asset ?? "").toUpperCase() === RLUSD_HEX && a.extra?.issuer === RLUSD_ISSUER[network]
       && /^\d+(\.\d+)?$/.test(String(a.amount)) && Number(a.amount) > 0 && Number(a.amount) <= cap) ?? null;
   }
-  return on[0] ?? null;
+  // Base and other EVM chains: "exact" first (what most clients register), then "auth-capture" (Coinbase's escrow:
+  // the buyer signs once, the USDC is held and only captured when the seller delivers, e.g. Atom's domain checkout).
+  // Either is paid only if your register() added its scheme, and both stay within the budget (x402's spend controls
+  // read the amount, which for auth-capture is the most that can be captured).
+  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 {
@@ -228,10 +262,23 @@ export function createSafeFetch({
   const makePayingFetch = createPayingFetch ?? ((cap) => {
     const client = new x402Client((_version, accepts) => {
       const pick = payableOption(accepts, payNetwork, cap);
-      if (!pick) throw new SafePayError(`no payment option on ${payNetwork}${ALGORAND_USDC[payNetwork] ? " in USDC" : STELLAR_USDC[payNetwork] ? ` in USDC within ${cap}` : XLAYER_DOLLARS[payNetwork] ? ` in USD₮0 or USDC within ${cap}` : RLUSD_ISSUER[payNetwork] ? ` in RLUSD within ${cap}` : ""}`, { code: "no_option" });
+      if (!pick) throw new SafePayError(`no payment option on ${payNetwork}${ALGORAND_USDC[algorandId(payNetwork)] ? " in USDC" : STELLAR_USDC[payNetwork] ? ` in USDC within ${cap}` : XLAYER_DOLLARS[payNetwork] ? ` in USD₮0 or USDC within ${cap}` : RLUSD_ISSUER[payNetwork] ? ` in RLUSD within ${cap}` : ""}`, { code: "no_option" });
       return pick;
     }).setSpendControls({ maxAmountPerPayment: cap, ...xlayerAllowance(payNetwork, cap) });
-    register(client);
+    // Algorand schemes get anyAlgorandId, so sellers with either network id can be paid.
+    const registering = new Proxy(client, {
+      get(target, prop) {
+        if (prop === "register") {
+          return (network, scheme) => {
+            target.register(network, String(network).startsWith("algorand:") ? anyAlgorandId(scheme) : scheme);
+            return registering;
+          };
+        }
+        const value = Reflect.get(target, prop);
+        return typeof value === "function" ? value.bind(target) : value;
+      },
+    });
+    register(registering);
     return wrapFetchWithPayment(baseFetch, client);
   });
   let preflightFetch;
@@ -291,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);
@@ -303,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);
@@ -351,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.8.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": {
@@ -29,7 +29,7 @@
   },
   "devDependencies": {
     "@algorandfoundation/algokit-utils": "^10.0.0-alpha.46",
-    "@x402/avm": "^2.28.0",
+    "@x402/avm": "^2.29.0",
     "@x402/evm": "^2.27.0",
     "@x402/fetch": "^2.27.0",
     "@x402/stellar": "^2.28.0",