@url2md-io/mcp 0.1.0

package/dist/client.js

@@ -0,0 +1,611 @@
+import { decodePaymentRequiredHeader, decodePaymentResponseHeader, encodePaymentSignatureHeader } from "@x402/core/http";
+import { ExactEvmScheme, toClientEvmSigner } from "@x402/evm";
+import { x402Client } from "@x402/core/client";
+import { privateKeyToAccount } from "viem/accounts";
+import { readFileSync } from "node:fs";
+/**
+ * The paying half of the MCP server: everything that talks to url2md, with no MCP in it.
+ *
+ * The wallet is the caller's. This process signs USDC transfer authorizations with a key the user
+ * put in the environment; it holds no account with url2md and url2md holds no balance for anyone.
+ * That is also why the server is local stdio rather than a hosted remote MCP: a remote server would
+ * have to pay from *its* wallet, which means it would have to bill the caller some other way, and
+ * the whole point of x402 is that there is no other way to bill.
+ *
+ * Two payment rounds, never more. The first 402 is url2md's own price. When the requested page is
+ * itself behind an x402 toll, url2md answers the paid request with a *second* 402 — a quote for
+ * base + toll + margin, carrying a signed quote token it expects back — and that retry is the last
+ * one. A third 402 is a refusal, not something to keep paying into.
+ */
+export const DEFAULT_BASE_URL = "https://url2md.io";
+/**
+ * Per-call ceiling in USD, before anything is signed. url2md's own price is $0.005 and the most a
+ * tolled call can cost is base + the $0.05 toll cap + 25 % ≈ $0.068, so $0.10 clears every honest
+ * call and still refuses a service that answers with a surprising number. Raise it with
+ * URL2MD_MAX_PRICE_USD; there is no way to switch it off.
+ */
+export const DEFAULT_MAX_PRICE_USD = "0.10";
+/**
+ * The longest a signed authorization may stay redeemable, in seconds. The server names it
+ * (`maxTimeoutSeconds`) and it becomes the EIP-3009 `validBefore`; url2md asks for 120. An hour is
+ * generous for a request that times out in 90 seconds, and it bounds what a failed call leaves behind.
+ */
+export const MAX_AUTHORIZATION_SECONDS = 3600;
+/**
+ * How much one process will commit in total, in USD, before it refuses to sign anything more. The
+ * per-call ceiling does not bound a loop: an agent retrying at the service's 60 requests a minute
+ * commits about $18 an hour with no limit at all. Raise it with URL2MD_MAX_SPEND_USD.
+ */
+export const DEFAULT_MAX_SPEND_USD = "1.00";
+export const RENDER_MODES = ["auto", "static", "browser"];
+/** Every failure this module raises, in the shape the tool hands back to the model. */
+export class Url2mdToolError extends Error {
+    code;
+    httpStatus;
+    retryable;
+    details;
+    constructor(code, message, opts = {}) {
+        super(message);
+        this.name = "Url2mdToolError";
+        this.code = code;
+        this.httpStatus = opts.httpStatus ?? null;
+        this.retryable = opts.retryable ?? false;
+        this.details = opts.details ?? {};
+    }
+}
+/**
+ * The configuration, read once at startup so a missing key is a startup failure rather than a tool
+ * call that looks like a network problem. The key is validated by deriving its address, which is
+ * also the only thing about it that is ever shown.
+ */
+export function readConfig(env, readFile = defaultReadFile) {
+    const keyPath = (env["URL2MD_PRIVATE_KEY_FILE"] ?? "").trim();
+    let key = (env["URL2MD_PRIVATE_KEY"] ?? "").trim();
+    if (keyPath) {
+        // Preferred over the variable: an MCP client stores its `env` block in a config file in the
+        // clear, and every `--env KEY=0x…` snippet puts the key in shell history and in `ps aux`.
+        // A path is not a secret; the file it names can be chmod 600 and can stay out of both.
+        try {
+            key = readFile(keyPath).trim();
+        }
+        catch (e) {
+            throw new Url2mdToolError("CONFIG_BAD_KEY_FILE", `URL2MD_PRIVATE_KEY_FILE points at ${keyPath}, which could not be read: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (!key && keyPath) {
+        throw new Url2mdToolError("CONFIG_BAD_KEY_FILE", `URL2MD_PRIVATE_KEY_FILE points at ${keyPath}, which is empty. Put the 0x-prefixed private key of a wallet holding USDC on Base in that file.`);
+    }
+    if (!key) {
+        throw new Url2mdToolError("CONFIG_MISSING_KEY", "Neither URL2MD_PRIVATE_KEY_FILE nor URL2MD_PRIVATE_KEY is set. url2md is paid per call over x402: the server signs USDC payments with your own key and never holds a balance for you. Put a 0x-prefixed private key of a wallet holding USDC on Base in a file and name that file in URL2MD_PRIVATE_KEY_FILE (preferred), or put the key itself in URL2MD_PRIVATE_KEY.");
+    }
+    if (!/^0x[0-9a-fA-F]{64}$/.test(key)) {
+        // The value is never echoed, here or anywhere: only its shape is described.
+        throw new Url2mdToolError("CONFIG_BAD_KEY", "The value given is not a private key: it must be 0x followed by 64 hex characters.");
+    }
+    // The shape is not enough: a 64-hex string can still be zero or above the curve order, and viem's
+    // rejection message quotes the number it was given — which is the key, in decimal. That message
+    // must never reach stderr, so the check happens here and only our own fixed wording escapes.
+    try {
+        privateKeyToAccount(key);
+    }
+    catch {
+        throw new Url2mdToolError("CONFIG_BAD_KEY", "The value given is the right shape but is not a valid secp256k1 private key (it is zero, or at or above the curve order). Generate a new wallet.");
+    }
+    const maxPriceUsd = (env["URL2MD_MAX_PRICE_USD"] ?? "").trim() || DEFAULT_MAX_PRICE_USD;
+    if (!/^\d+(\.\d{1,6})?$/.test(maxPriceUsd)) {
+        throw new Url2mdToolError("CONFIG_BAD_LIMIT", `URL2MD_MAX_PRICE_USD must be a plain USD amount such as "0.10"; got ${JSON.stringify(maxPriceUsd)}.`);
+    }
+    const maxSpendUsd = (env["URL2MD_MAX_SPEND_USD"] ?? "").trim() || DEFAULT_MAX_SPEND_USD;
+    if (!/^\d+(\.\d{1,6})?$/.test(maxSpendUsd)) {
+        throw new Url2mdToolError("CONFIG_BAD_LIMIT", `URL2MD_MAX_SPEND_USD must be a plain USD amount such as "1.00"; got ${JSON.stringify(maxSpendUsd)}.`);
+    }
+    if (usdToAtomic(maxSpendUsd) < usdToAtomic(maxPriceUsd)) {
+        throw new Url2mdToolError("CONFIG_BAD_LIMIT", `URL2MD_MAX_SPEND_USD ($${maxSpendUsd}) is below URL2MD_MAX_PRICE_USD ($${maxPriceUsd}), so no call could ever be made.`);
+    }
+    const baseUrl = ((env["URL2MD_BASE_URL"] ?? "").trim() || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    let parsedBase;
+    try {
+        parsedBase = new URL(baseUrl);
+    }
+    catch {
+        throw new Url2mdToolError("CONFIG_BAD_BASE_URL", `URL2MD_BASE_URL must be an http(s) URL; got ${JSON.stringify(baseUrl)}.`);
+    }
+    if (parsedBase.protocol !== "https:" && parsedBase.protocol !== "http:") {
+        throw new Url2mdToolError("CONFIG_BAD_BASE_URL", `URL2MD_BASE_URL must be an http(s) URL; got ${JSON.stringify(baseUrl)}.`);
+    }
+    // This URL is the whole trust anchor: every 402 is checked against the pricing *it* publishes, so
+    // a service reached over plain http can be rewritten in flight by anyone on the path — including
+    // the pricing the checks are made against. Loopback is exempt because there is no path to sit on.
+    if (parsedBase.protocol === "http:" && !LOOPBACK_HOSTS.has(parsedBase.hostname)) {
+        throw new Url2mdToolError("CONFIG_BAD_BASE_URL", `URL2MD_BASE_URL must be https:// (got ${JSON.stringify(baseUrl)}). This URL is what every 402 is checked against, so anyone who can rewrite the traffic can rewrite the terms this client verifies. Only a loopback address may be plain http.`);
+    }
+    const timeoutRaw = (env["URL2MD_TIMEOUT_MS"] ?? "").trim();
+    const timeoutMs = timeoutRaw ? Number(timeoutRaw) : 90_000;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new Url2mdToolError("CONFIG_BAD_TIMEOUT", `URL2MD_TIMEOUT_MS must be a positive number of milliseconds; got ${JSON.stringify(timeoutRaw)}.`);
+    }
+    return { baseUrl, privateKey: key, maxPriceUsd, maxSpendUsd, timeoutMs };
+}
+/** Hosts where plain http is not a downgrade: nothing can sit between a process and itself. */
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+/** Reads the key file. Its own function so `readConfig` stays testable without touching a disk. */
+function defaultReadFile(path) {
+    // A dynamic require would be erased by Node's type stripping; a static import of node:fs is fine.
+    return readFileSync(path, "utf8");
+}
+/**
+ * A ceiling far above anything this service charges. Not enforced — it is the user's wallet and
+ * their number — but a ceiling of $50 is almost always a typo or a copied example, and saying so
+ * once at startup costs nothing. The README used to claim the limit could not be switched off;
+ * it can be raised arbitrarily, and pretending otherwise is worse than warning.
+ */
+export const CEILING_WORTH_MENTIONING_USD = "1";
+export function ceilingLooksWrong(maxPriceUsd) {
+    try {
+        return usdToAtomic(maxPriceUsd) > usdToAtomic(CEILING_WORTH_MENTIONING_USD);
+    }
+    catch {
+        return false;
+    }
+}
+/** The public address of the configured key. The only thing derived from it that anything is allowed to show. */
+export function payerAddress(config) {
+    return privateKeyToAccount(config.privateKey).address;
+}
+/** What `GET /` says about payment. Free (unpaid), so it costs nothing to ask and it settles which network to register. */
+export async function discoverPricing(config, fetchImpl) {
+    let res;
+    try {
+        res = await fetchImpl(`${config.baseUrl}/`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(config.timeoutMs) });
+    }
+    catch (e) {
+        throw new Url2mdToolError("SERVICE_UNREACHABLE", `${config.baseUrl} could not be reached: ${e instanceof Error ? e.message : String(e)}`, { retryable: true });
+    }
+    if (!res.ok)
+        throw new Url2mdToolError("SERVICE_UNREACHABLE", `${config.baseUrl}/ answered ${res.status}`, { httpStatus: res.status, retryable: true });
+    const body = (await res.json().catch(() => null));
+    const p = body?.pricing;
+    if (!p || typeof p.model !== "string")
+        throw new Url2mdToolError("SERVICE_UNREACHABLE", `${config.baseUrl}/ did not describe its pricing`, { retryable: true });
+    return { model: p.model, network: p.network ?? null, priceAtomic: p.priceAtomic ?? null, payTo: p.payTo ?? null, asset: p.asset ?? null, assetAddress: p.assetAddress ?? null };
+}
+/** USD with up to six decimals as atomic USDC. */
+export function usdToAtomic(usd) {
+    const m = /^(\d+)(?:\.(\d{1,6}))?$/.exec(usd.trim());
+    if (!m)
+        throw new Url2mdToolError("BAD_RESPONSE", `not a USD amount: ${usd}`);
+    return BigInt(m[1]) * 1000000n + BigInt((m[2] ?? "").padEnd(6, "0"));
+}
+export function atomicToUsd(atomic) {
+    const frac = (atomic % 1000000n).toString().padStart(6, "0").replace(/0+$/, "");
+    return `${atomic / 1000000n}${frac ? `.${frac}` : ""}`;
+}
+/** The x402 client for one network, with the caller's own per-payment ceiling on top of the SDK's default. */
+export function clientFor(config, network) {
+    const account = privateKeyToAccount(config.privateKey);
+    const signer = toClientEvmSigner({ address: account.address, signTypedData: (a) => account.signTypedData(a) });
+    return new x402Client()
+        .register(network, new ExactEvmScheme(signer))
+        .setSpendControls({ maxAmountPerPayment: `$${config.maxPriceUsd}` });
+}
+const EXPLORER = {
+    "eip155:8453": "https://basescan.org/tx/",
+    "eip155:84532": "https://sepolia.basescan.org/tx/",
+};
+const sameAddress = (a, b) => (a ?? "").toLowerCase() === (b ?? "").toLowerCase();
+/**
+ * The terms, checked before anything is signed — against what the service **published**, not only
+ * against what this 402 says about itself.
+ *
+ * A 402 is just a response header. Whoever answers the request writes it, and a compromised or
+ * impersonated deployment can put any address and any amount in it. Cross-checking `payTo`, the
+ * asset and the network against the `GET /` a separate, unpaid request fetched is what makes the
+ * ceiling a second line of defence rather than the only one: without it the worst case is not
+ * "you overpaid", it is "you paid a stranger" (rule 13 of the service repository's CLAUDE.md). The amount is checked against
+ * the ceiling and not against the published price, because a toll quote is legitimately higher.
+ */
+function checkTerms(required, config, pricing, committedAtomic) {
+    // Fail closed. A check written as "if the service published a payTo, it must match" defends
+    // against nothing in its own threat model: the attacker who writes the 402 also writes `GET /`,
+    // and can simply publish nothing. Terms that cannot be checked are terms that are not signed.
+    for (const [field, value] of [
+        ["payTo", pricing.payTo],
+        ["assetAddress", pricing.assetAddress],
+        ["network", pricing.network],
+    ]) {
+        if (!value) {
+            throw new Url2mdToolError("UNPUBLISHED_TERMS", `${config.baseUrl} asks for payment but publishes no ${field} at GET /, so there is nothing to check its 402 against. Nothing was signed.`, {
+                httpStatus: 402,
+                details: { missing: field },
+            });
+        }
+    }
+    const accepts = required.accepts?.[0];
+    if (!accepts)
+        throw new Url2mdToolError("UNSUPPORTED_PAYMENT_TERMS", "the 402 offered no payment options", { httpStatus: 402, details: { x402Version: required.x402Version } });
+    if (accepts.scheme !== "exact") {
+        throw new Url2mdToolError("UNSUPPORTED_PAYMENT_TERMS", `this client only pays the "exact" scheme; the service asked for "${accepts.scheme}"`, { httpStatus: 402, details: { scheme: accepts.scheme } });
+    }
+    if (accepts.network !== pricing.network) {
+        // A 402 on a network the service did not publish is not a price change, it is a different service.
+        throw new Url2mdToolError("UNSUPPORTED_PAYMENT_TERMS", `the 402 asks for payment on ${accepts.network}, but ${config.baseUrl} publishes ${pricing.network}`, { httpStatus: 402, details: { asked: accepts.network, published: pricing.network } });
+    }
+    if (!sameAddress(accepts.payTo, pricing.payTo)) {
+        throw new Url2mdToolError("PAYTO_MISMATCH", `the 402 asks you to pay ${accepts.payTo}, but ${config.baseUrl} publishes ${pricing.payTo} as its receiving address. Nothing was signed.`, {
+            httpStatus: 402,
+            details: { asked: accepts.payTo, published: pricing.payTo, amountUsd: safeUsd(accepts.amount) },
+        });
+    }
+    if (!sameAddress(accepts.asset, pricing.assetAddress)) {
+        // The ceiling is arithmetic in USDC's six decimals; another token makes that arithmetic meaningless.
+        throw new Url2mdToolError("UNSUPPORTED_PAYMENT_TERMS", `the 402 asks for a payment in ${accepts.asset}, but ${config.baseUrl} publishes ${pricing.asset ?? "its asset"} at ${pricing.assetAddress}. Nothing was signed.`, {
+            httpStatus: 402,
+            details: { asked: accepts.asset, published: pricing.assetAddress },
+        });
+    }
+    // An authorization stays redeemable until `validBefore`, which the server picks. The honest
+    // deployment asks for two minutes; a hostile one asked for ten years in review, and a failed call
+    // leaves the signature behind. Anything beyond an hour is refused.
+    // Coerced, not type-checked: the same ten-year lifetime sent as a *string* skipped a
+    // `typeof === "number"` guard in review and only viem's own arithmetic stopped it, with an
+    // INTERNAL error no agent could branch on. A value that is not a number at all is refused too.
+    // A lifetime that is absent, zero or unreadable is refused too: the field decides how long the
+    // signature stays redeemable, and signing one whose expiry cannot be stated is signing blind.
+    const lifetime = Number(accepts.maxTimeoutSeconds);
+    if (!Number.isFinite(lifetime) || lifetime <= 0 || lifetime > MAX_AUTHORIZATION_SECONDS) {
+        throw new Url2mdToolError("UNSUPPORTED_PAYMENT_TERMS", `the 402 wants an authorization valid for ${accepts.maxTimeoutSeconds} seconds; this client signs nothing redeemable for longer than ${MAX_AUTHORIZATION_SECONDS}. Nothing was signed.`, {
+            httpStatus: 402,
+            details: { maxTimeoutSeconds: accepts.maxTimeoutSeconds, limit: MAX_AUTHORIZATION_SECONDS },
+        });
+    }
+    let amount;
+    try {
+        amount = BigInt(accepts.amount);
+    }
+    catch {
+        throw new Url2mdToolError("UNSUPPORTED_PAYMENT_TERMS", `the 402 asks for ${JSON.stringify(accepts.amount)}, which is not an amount. Nothing was signed.`, { httpStatus: 402, details: { amount: accepts.amount } });
+    }
+    // A negative amount passes every "is it above the ceiling" test ever written, and would have
+    // *credited* the session budget on its way through. Only viem refused it, one layer down.
+    if (amount <= 0n) {
+        throw new Url2mdToolError("UNSUPPORTED_PAYMENT_TERMS", `the 402 asks for an amount of ${accepts.amount}, which is not a payment. Nothing was signed.`, { httpStatus: 402, details: { amount: accepts.amount } });
+    }
+    const max = usdToAtomic(config.maxPriceUsd);
+    // The ceiling bounds the **call**, not each payment in it. A tolled page is two rounds, and two
+    // rounds under a per-payment ceiling commit twice the number the user was shown.
+    const wouldTotal = committedAtomic + amount;
+    if (wouldTotal > max) {
+        const already = committedAtomic > 0n ? ` (this call has already committed $${atomicToUsd(committedAtomic)})` : "";
+        throw new Url2mdToolError("PRICE_ABOVE_LIMIT", `the call would cost $${atomicToUsd(wouldTotal)} in total${already}, above the $${config.maxPriceUsd} per-call limit. Raise URL2MD_MAX_PRICE_USD to allow it.`, {
+            httpStatus: 402,
+            details: { priceUsd: atomicToUsd(amount), totalUsd: atomicToUsd(wouldTotal), committedUsd: atomicToUsd(committedAtomic), limitUsd: config.maxPriceUsd, network: accepts.network, payTo: accepts.payTo },
+        });
+    }
+    return { amountAtomic: amount, network: accepts.network, payTo: accepts.payTo, asset: accepts.asset };
+}
+const safeUsd = (atomic) => {
+    try {
+        return atomicToUsd(BigInt(atomic));
+    }
+    catch {
+        return atomic;
+    }
+};
+/** The error the service answered with, carried through unchanged so the model sees url2md's own code and details. */
+async function serviceError(res, body) {
+    let parsed = null;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        parsed = null;
+    }
+    const err = parsed?.error;
+    const details = { ...(err?.details ?? {}) };
+    // A charge that produced nothing is the one thing a caller must not have to dig for.
+    const ledgerId = res.headers.get("x-url2md-ledger-id");
+    if (res.headers.get("x-url2md-caller-charged") === "true")
+        details["callerCharged"] = true;
+    if (ledgerId)
+        details["ledgerId"] = ledgerId;
+    const receipt = res.headers.get("payment-response");
+    if (receipt) {
+        try {
+            details["receipt"] = decodePaymentResponseHeader(receipt);
+        }
+        catch {
+            /* a receipt we cannot decode is not worth failing over; the ledger id is the handle */
+        }
+    }
+    return new Url2mdToolError(err?.code ?? `HTTP_${res.status}`, err?.message ?? `${res.status} from ${new URL(res.url || "https://url2md.invalid").pathname}: ${body.slice(0, 400)}`, {
+        httpStatus: res.status,
+        retryable: err?.retryable ?? res.status >= 500,
+        details,
+    });
+}
+/** How many redirects the paid request will follow, all of them on the service's own origin. */
+const MAX_REDIRECTS = 3;
+/** Two hosts that differ only by a leading `www.` — url2md itself redirects www to the apex. */
+function sameService(a, b) {
+    const bare = (h) => h.replace(/^www\./, "");
+    if (bare(a.hostname) !== bare(b.hostname) || a.port !== b.port)
+        return false;
+    // https must not become http: a downgrade puts the signed authorization on the open wire.
+    return !(a.protocol === "https:" && b.protocol !== "https:");
+}
+/**
+ * A request pinned to the service's own origin. `fetch` follows redirects by default and re-sends
+ * every header, so a service that answers the *paid* request with a 302 hands the signed
+ * authorization — a redeemable USDC transfer — to whatever host it names. Found in review: a third
+ * party received the signature, wrote the markdown and wrote the settlement receipt, and the client
+ * reported success with no warning. Redirects are followed by hand, on this service only.
+ */
+async function fetchPinned(url, init, config, fetchImpl) {
+    const base = new URL(config.baseUrl);
+    let current = url;
+    for (let hop = 0;; hop++) {
+        const res = await fetchImpl(current, { ...init, redirect: "manual" });
+        const location = res.status >= 300 && res.status < 400 ? res.headers.get("location") : null;
+        if (!location)
+            return res;
+        if (hop >= MAX_REDIRECTS) {
+            throw new Url2mdToolError("TOO_MANY_REDIRECTS", `${config.baseUrl} redirected more than ${MAX_REDIRECTS} times.`, { httpStatus: res.status, details: { lastUrl: current } });
+        }
+        let next;
+        try {
+            next = new URL(location, current);
+        }
+        catch {
+            throw new Url2mdToolError("BAD_RESPONSE", `${config.baseUrl} answered ${res.status} with a Location this client could not read.`, { httpStatus: res.status, details: { location } });
+        }
+        if (!sameService(base, next)) {
+            throw new Url2mdToolError("REDIRECT_REFUSED", `${config.baseUrl} tried to redirect this request to ${next.origin}, which is not the service this client was configured for. The request was not followed there${init.headers && "payment-signature" in init.headers ? ", so the signed payment authorization was not handed to it" : ""}.`, {
+                httpStatus: res.status,
+                details: { redirectedTo: next.origin, expected: base.origin },
+            });
+        }
+        current = next.href;
+    }
+}
+/**
+ * One conversion, paid for. The unpaid request comes first on purpose: it is one round trip, it is
+ * how the price is learned rather than assumed, and it is what makes a tolled page's quote reachable.
+ */
+export async function convert(input, config, pricing, fetchImpl, budget) {
+    const target = `${config.baseUrl}/v1/md?url=${encodeURIComponent(input.url)}&render=${input.render}&format=json`;
+    const client = pricing.model === "x402" && pricing.network ? clientFor(config, pricing.network) : null;
+    let signature = null;
+    let rounds = 0;
+    // Every authorization this call put on the wire, in the order it signed them. Not a log: it is
+    // what the caller is told on **every** exit, success or failure. A signature that left this
+    // process is money the caller has committed, whatever the service does next (rule 13 of the service repository's CLAUDE.md).
+    const signed = [];
+    // Notes this client raises itself, kept apart from the service's own warnings until they are merged.
+    const ours = [];
+    const committed = () => signed.reduce((t, a) => t + BigInt(a.amountAtomic), 0n);
+    // The terms actually signed. A settlement receipt for the "exact" scheme need not restate the
+    // amount, and on a tolled call the base price is not what was paid — the accepted offer is.
+    let paid = null;
+    /** Anything thrown from here on carries what was already committed; nothing exits silently. */
+    const withSigned = (e) => signed.length === 0 ? e : new Url2mdToolError(e.code, e.message, { httpStatus: e.httpStatus, retryable: e.retryable, details: { ...e.details, ...signedDetails(signed) } });
+    let res;
+    try {
+        for (;;) {
+            try {
+                res = await fetchPinned(target, { headers: { accept: "application/json", ...(signature ? { "payment-signature": signature } : {}) }, signal: AbortSignal.timeout(config.timeoutMs) }, config, fetchImpl);
+            }
+            catch (e) {
+                if (e instanceof Url2mdToolError)
+                    throw e;
+                const aborted = e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError");
+                throw new Url2mdToolError(aborted ? "TIMEOUT" : "SERVICE_UNREACHABLE", aborted ? `no answer from ${config.baseUrl} within ${config.timeoutMs} ms` : `${config.baseUrl} could not be reached: ${e instanceof Error ? e.message : String(e)}`, { retryable: true });
+            }
+            if (res.status !== 402)
+                break;
+            // Two rounds and no more: the second 402 is the toll quote, and there is no third thing to pay.
+            if (rounds >= 2) {
+                const again = res.headers.get("payment-required");
+                throw new Url2mdToolError("PAYMENT_NOT_ACCEPTED", `${config.baseUrl} answered 402 a third time. It already holds ${signed.length} signed authorization${signed.length === 1 ? "" : "s"} from this call, totalling $${atomicToUsd(committed())}, which it can still redeem. No further payment was signed.`, {
+                    httpStatus: 402,
+                    details: { rounds, reason: again ? safeDecode(again)?.error : (await res.text()).slice(0, 300) },
+                });
+            }
+            if (pricing.model === "x402" && !pricing.network) {
+                // Without a published network there is nothing to check the 402's network against, and the
+                // old message ("cannot pay it") named the pricing model rather than the missing field.
+                throw new Url2mdToolError("UNPUBLISHED_TERMS", `${config.baseUrl} asks for payment but publishes no network at GET /, so there is nothing to check its 402 against. Nothing was signed.`, { httpStatus: 402, details: { missing: "network" } });
+            }
+            if (!client) {
+                throw new Url2mdToolError("PAYMENT_REQUIRED", `${config.baseUrl} asks for payment but publishes pricing.model=${pricing.model}, so this client cannot pay it.`, { httpStatus: 402, details: { pricingModel: pricing.model } });
+            }
+            const header = res.headers.get("payment-required");
+            if (!header)
+                throw new Url2mdToolError("BAD_RESPONSE", "the 402 carried no PAYMENT-REQUIRED header", { httpStatus: 402 });
+            const required = safeDecode(header);
+            if (!required)
+                throw new Url2mdToolError("BAD_RESPONSE", "the PAYMENT-REQUIRED header could not be decoded", { httpStatus: 402 });
+            paid = checkTerms(required, config, pricing, committed());
+            // The first 402 is the service's own price, and it is published. A toll quote is legitimately
+            // higher — the second round — but a first round above the published price is the service
+            // charging something other than what it advertises, and staying under the ceiling makes it
+            // silent. It is the caller's wallet and their ceiling, so this is said, not refused.
+            if (rounds === 0 && pricing.priceAtomic && /^\d+$/.test(pricing.priceAtomic) && paid.amountAtomic > BigInt(pricing.priceAtomic)) {
+                ours.push(`${config.baseUrl} publishes a price of $${atomicToUsd(BigInt(pricing.priceAtomic))} at GET / but its 402 asked for $${atomicToUsd(paid.amountAtomic)} — ${(Number(paid.amountAtomic) / Number(BigInt(pricing.priceAtomic))).toFixed(1)}× the published price. It was within your $${config.maxPriceUsd} per-call limit, so it was paid.`);
+            }
+            budget?.reserve(paid.amountAtomic, config);
+            let payload;
+            try {
+                // createPaymentPayload echoes accepts[0] verbatim, which is what carries the signed quote token
+                // back on the tolled retry; nothing here needs to know the token exists.
+                payload = await client.createPaymentPayload(required);
+            }
+            catch (e) {
+                throw new Url2mdToolError("PAYMENT_NOT_SIGNED", `the payment could not be signed: ${e instanceof Error ? e.message : String(e)}`, { httpStatus: 402, details: { network: required.accepts?.[0]?.network ?? null } });
+            }
+            signature = encodePaymentSignatureHeader(payload);
+            signed.push(describeAuthorization(payload, paid));
+            budget?.commit(paid.amountAtomic);
+            rounds++;
+        }
+        const body = await res.text();
+        if (!res.ok)
+            throw await serviceError(res, body);
+        let result;
+        try {
+            result = JSON.parse(body);
+        }
+        catch {
+            throw new Url2mdToolError("BAD_RESPONSE", `the answer was ${res.status} but not JSON: ${body.slice(0, 200)}`, { httpStatus: res.status });
+        }
+        const warnings = [...(result.warnings ?? []), ...ours];
+        const receipt = receiptFrom(res, paid, config, warnings);
+        const committedAtomic = committed();
+        // On a tolled call two authorizations were signed and only the second is settled: reporting the
+        // settled one alone understates what the caller committed, and reporting their sum overstates
+        // what was charged. Both numbers are given, and the difference is said in words.
+        if (signed.length > 1) {
+            warnings.push(`This call signed ${signed.length} payment authorizations totalling $${atomicToUsd(committedAtomic)}: the page charged a toll of its own, so the first authorization was replaced by a quote. \`payment\` is the one the service settled ($${atomicToUsd(paid?.amountAtomic ?? 0n)}); the rest are listed in \`signed\` with their nonces, and the service could still redeem them.`);
+        }
+        return { result, payment: receipt, toll: tollFrom(res, result, paid?.network ?? null, warnings), paymentRounds: rounds, warnings, signed, committedUsd: atomicToUsd(committedAtomic) };
+    }
+    catch (e) {
+        throw withSigned(e instanceof Url2mdToolError ? e : new Url2mdToolError("INTERNAL", e instanceof Error ? e.message : String(e)));
+    }
+}
+function describeAuthorization(payload, paid) {
+    const auth = (payload.payload?.authorization ?? {});
+    const validBefore = auth.validBefore && /^\d+$/.test(String(auth.validBefore)) ? new Date(Number(auth.validBefore) * 1000).toISOString() : null;
+    return {
+        amountUsd: atomicToUsd(paid.amountAtomic),
+        amountAtomic: paid.amountAtomic.toString(),
+        network: paid.network,
+        payTo: paid.payTo,
+        payer: auth.from ?? "",
+        nonce: auth.nonce ?? null,
+        validBefore,
+    };
+}
+/**
+ * What every failure after a signature says. A caller that cannot see this has to read the chain to
+ * find out whether the call cost anything — and would not know which nonce to look for.
+ */
+function signedDetails(signed) {
+    const total = signed.reduce((t, a) => t + BigInt(a.amountAtomic), 0n);
+    return {
+        signedButUnconfirmed: true,
+        committedUsd: atomicToUsd(total),
+        signed,
+        note: `This call signed ${signed.length} payment authorization${signed.length === 1 ? "" : "s"} totalling $${atomicToUsd(total)} before it failed. The service may or may not have redeemed ${signed.length === 1 ? "it" : "them"}; the nonces above are what USDC emits as AuthorizationUsed when one is spent.`,
+    };
+}
+function safeDecode(header) {
+    try {
+        return decodePaymentRequiredHeader(header);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The receipt for a payment this client signed. Built from the terms it accepted, then filled in
+ * from the service's settlement if one came back — never the other way round, so a missing or
+ * unreadable `PAYMENT-RESPONSE` downgrades the receipt instead of erasing it.
+ */
+function receiptFrom(res, paid, config, warnings) {
+    if (!paid)
+        return null;
+    const header = res.headers.get("payment-response");
+    let decoded = null;
+    let corrupt = false;
+    if (header) {
+        try {
+            decoded = decodePaymentResponseHeader(header);
+        }
+        catch {
+            corrupt = true;
+        }
+    }
+    // The amount, the network and the recipient are what THIS CLIENT SIGNED. They are not read from
+    // the service's receipt: a receipt is the counterparty's word, and one that claimed 1 atomic unit
+    // on mainnet for a payment of 5000 on testnet was reported verbatim in review, with a mainnet
+    // explorer link and no warning. Where the receipt disagrees, ours stands and the difference is
+    // said out loud (rule 13 of the service repository's CLAUDE.md).
+    const network = paid.network;
+    const amountAtomic = paid.amountAtomic.toString();
+    const payer = privateKeyToAccount(config.privateKey).address;
+    if (decoded) {
+        if (decoded.network && decoded.network !== network)
+            warnings.push(`The settlement receipt claims network ${decoded.network}, but this client signed on ${network}. The payment reported here is what was signed.`);
+        if (decoded.amount && decoded.amount !== amountAtomic)
+            warnings.push(`The settlement receipt claims ${decoded.amount} atomic units, but this client signed ${amountAtomic}. The payment reported here is what was signed.`);
+        if (decoded.payer && !sameAddress(decoded.payer, payer))
+            warnings.push(`The settlement receipt names ${decoded.payer} as the payer, which is not this wallet. The payment reported here is what was signed.`);
+    }
+    const settled = decoded !== null && Boolean(decoded.transaction);
+    if (!settled) {
+        warnings.push(corrupt
+            ? `You were charged $${atomicToUsd(paid.amountAtomic)} and ${config.baseUrl} returned a settlement receipt this client could not decode. The amount and recipient reported here are what was signed. Check the payer wallet on-chain before calling again.`
+            : `You were charged $${atomicToUsd(paid.amountAtomic)} but ${config.baseUrl} returned no settlement receipt at all. The amount and recipient reported here are what this client signed, not what the service confirmed. Check the payer wallet on-chain before calling again.`);
+    }
+    return {
+        amountUsd: atomicToUsd(paid.amountAtomic),
+        amountAtomic,
+        network,
+        payTo: paid.payTo,
+        settled,
+        payer,
+        transaction: decoded?.transaction || null,
+        // Built from the network this client signed on, never the one the receipt names.
+        explorerUrl: decoded?.transaction && EXPLORER[network] ? `${EXPLORER[network]}${decoded.transaction}` : null,
+        ledgerId: res.headers.get("x-url2md-ledger-id"),
+    };
+}
+/**
+ * How much this process has committed, across every call. The per-call ceiling bounds one call; an
+ * agent in a retry loop makes many. Kept as an object rather than a module variable so a test, and a
+ * second server in one process, each get their own.
+ */
+export class Budget {
+    spentAtomic = 0n;
+    maxAtomic;
+    constructor(maxUsd) {
+        this.maxAtomic = usdToAtomic(maxUsd);
+    }
+    /** Refuses before anything is signed. */
+    reserve(amountAtomic, config) {
+        if (this.spentAtomic + amountAtomic > this.maxAtomic) {
+            throw new Url2mdToolError("SPEND_LIMIT_REACHED", `This server has already committed $${atomicToUsd(this.spentAtomic)} of its $${atomicToUsd(this.maxAtomic)} session limit, and this call would take it to $${atomicToUsd(this.spentAtomic + amountAtomic)}. Nothing was signed. Raise URL2MD_MAX_SPEND_USD and restart to allow more.`, { httpStatus: 402, details: { committedUsd: atomicToUsd(this.spentAtomic), wouldCommitUsd: atomicToUsd(amountAtomic), limitUsd: atomicToUsd(this.maxAtomic), baseUrl: config.baseUrl } });
+        }
+    }
+    commit(amountAtomic) {
+        this.spentAtomic += amountAtomic;
+    }
+    get spentUsd() {
+        return atomicToUsd(this.spentAtomic);
+    }
+    get limitUsd() {
+        return atomicToUsd(this.maxAtomic);
+    }
+}
+/**
+ * What the service says it paid the origin. Every field here is the service's word — this client
+ * signed nothing to the origin and settled nothing with it — so the explorer link is built from the
+ * network *this client signed on*, never from the network the service names beside the hash. A
+ * testnet call whose body claimed `eip155:8453` produced a mainnet explorer link in review.
+ */
+function tollFrom(res, result, signedNetwork, warnings) {
+    const amountUsd = res.headers.get("x-url2md-upstream-toll");
+    if (!amountUsd)
+        return null;
+    const up = (result["upstreamPayment"] ?? null);
+    const network = signedNetwork ?? "";
+    if (up?.network && signedNetwork && up.network !== signedNetwork) {
+        warnings.push(`The service says it paid the page's toll on ${up.network}, but this call was made on ${signedNetwork}. The toll link below points at ${signedNetwork}.`);
+    }
+    return {
+        amountUsd,
+        payTo: up?.payTo ?? null,
+        transaction: up?.transaction ?? null,
+        explorerUrl: up?.transaction && EXPLORER[network] ? `${EXPLORER[network]}${up.transaction}` : null,
+    };
+}