@x402jp/safe-buy 0.0.0-stage → 0.1.0

package/dist/safe-buy.js

@@ -0,0 +1,357 @@
+// safeBuy / checkSeller: buy one call from an x402 seller, stage by stage, stopping
+// before any money moves when something looks wrong.
+import { createHash } from "node:crypto";
+import { checkBaseTransfer, findBasePayment, getBaseReceipt } from "./chains/base.js";
+import { checkSolanaTransfer, findSolanaPayment, getSolanaTx } from "./chains/solana.js";
+import { DEFAULT_FIND_TIMEOUT_MS, DEFAULT_PROBE_URL, DEFAULT_RPC, REQUEST_TIMEOUT_MS, USER_AGENT, } from "./constants.js";
+import { makePayer, payerFromClient, refuseReason, settleFrom, signFor } from "./pay.js";
+import { atomicToUsd, usdToAtomic } from "./price.js";
+import { BAD_LAST_PAID, hostOf, lookupProbe } from "./probe.js";
+import { RECEIPT_HEADER, checkReceipt, fetchReceiptKeys } from "./receipt.js";
+import { buildReport, sendReport } from "./report.js";
+import { encodeReceipt, refetch as refetchCore } from "@x402jp/delivery-receipt-verify";
+import { inputRequirement, parse402, selectAccept, x402Error } from "./x402.js";
+function buildRequest(url, input) {
+    const u = new URL(url);
+    for (const [k, v] of Object.entries(input?.query ?? {}))
+        u.searchParams.set(k, String(v));
+    const headers = { "user-agent": USER_AGENT, accept: "application/json, */*", ...(input?.headers ?? {}) };
+    let body;
+    if (input?.body !== undefined) {
+        if (typeof input.body === "string")
+            body = input.body;
+        else if (input.body instanceof Uint8Array)
+            body = new Uint8Array(input.body);
+        else {
+            body = JSON.stringify(input.body);
+            if (!Object.keys(headers).some((h) => h.toLowerCase() === "content-type"))
+                headers["content-type"] = "application/json";
+        }
+    }
+    const method = (input?.method ?? (body !== undefined ? "POST" : "GET")).toUpperCase();
+    return { url: u.toString(), init: { method, headers, ...(body !== undefined && method !== "GET" && method !== "HEAD" ? { body } : {}) } };
+}
+const errMsg = (e) => (e?.name === "TimeoutError" ? "timeout" : `${e?.message ?? e}`);
+/** Stages 1–3. `usable` limits chain "any" to chains the payer can sign for. */
+async function prepare(url, opts, usable) {
+    const stages = [];
+    let host;
+    try {
+        host = hostOf(url);
+    }
+    catch {
+        throw new TypeError(`invalid url ${JSON.stringify(url)}`);
+    }
+    const out = {
+        ok: false, stopped_at: null, reason: null, stages, host, probe: { status: "unavailable", doc: null },
+        offer: null, input_requirement: null, parsed: null, accept: null, request: buildRequest(url, opts.input),
+    };
+    const stop = (name, reason) => {
+        stages.push({ name, ok: false, detail: reason });
+        return Object.assign(out, { ok: false, stopped_at: name, reason });
+    };
+    // 1. probe
+    const lk = await lookupProbe(opts.probeUrl ?? DEFAULT_PROBE_URL, host);
+    out.probe = { status: lk.status, doc: lk.status === "found" ? lk.doc : null };
+    const doc = lk.status === "found" ? lk.doc : null;
+    if (doc) {
+        const lp = doc.last_paid;
+        if (lp?.outcome && BAD_LAST_PAID.includes(lp.outcome)) {
+            return stop("probe", `probe: last paid purchase (${lp.date ?? lp.ts?.slice(0, 10) ?? "date unknown"}) was ${lp.outcome}`);
+        }
+        if (doc.buyable_without_input === false && !opts.input) {
+            return stop("probe", `probe: not buyable without input${doc.requires_input_reason?.reason ? ` (${doc.requires_input_reason.reason})` : ""}; pass input`);
+        }
+        stages.push({
+            name: "probe",
+            ok: true,
+            detail: `score ${doc.score ?? "n/a"}, last paid ${lp?.outcome ?? "none"}${lp?.date ? ` (${lp.date})` : ""}, buyable_without_input ${doc.buyable_without_input ?? "n/a"}`,
+        });
+    }
+    else {
+        stages.push({ name: "probe", ok: true, detail: lk.status === "no_data" ? "no data" : `unavailable (${lk.error})` });
+    }
+    // 2. 402
+    let res;
+    let text;
+    try {
+        res = await fetch(out.request.url, { ...out.request.init, signal: AbortSignal.timeout(opts.requestTimeoutMs ?? REQUEST_TIMEOUT_MS), redirect: "follow" });
+        text = await res.text();
+    }
+    catch (e) {
+        return stop("402", `unreachable: ${errMsg(e)}`);
+    }
+    if (res.status !== 402)
+        return stop("402", `expected 402, got HTTP ${res.status}`);
+    const parsed = parse402((n) => res.headers.get(n), text);
+    out.parsed = parsed;
+    if (parsed.error && !parsed.accepts.length)
+        return stop("402", `unreadable 402: ${parsed.error}`);
+    const need = inputRequirement(parsed);
+    out.input_requirement = need;
+    if (need.requires && !opts.input)
+        return stop("402", `requires_input: ${need.reason} (from ${need.source}); pass input`);
+    const chain = opts.chain ?? "any";
+    const a = selectAccept(parsed, chain, usable);
+    const refuse = refuseReason(a);
+    if (refuse || !a) {
+        const offered = parsed.accepts.map((x) => `${x.scheme}/${x.network}/${x.asset}`).join(", ") || "none";
+        return stop("402", `${refuse} (chain ${chain}${usable ? `, signable: ${usable.join("/")}` : ""}; offered: ${offered})`);
+    }
+    out.accept = a;
+    out.offer = {
+        spec_version: parsed.spec_version, scheme: a.scheme, network: a.network, chain: a.chain, amount: a.amount,
+        amount_usd: atomicToUsd(a.amount), asset: a.asset, pay_to: a.payTo, resource: a.resource ?? null, max_timeout_seconds: a.maxTimeoutSeconds ?? null,
+    };
+    stages.push({ name: "402", ok: true, detail: `${parsed.spec_version} ${a.scheme} ${a.network} ${out.offer.amount_usd} USDC to ${a.payTo}${need.requires ? ` (input given for: ${need.reason})` : ""}` });
+    // 3. price
+    const amount = BigInt(a.amount);
+    const notes = [];
+    if (opts.maxPrice !== undefined) {
+        const max = usdToAtomic(opts.maxPrice);
+        if (amount > max)
+            return stop("price", `price ${atomicToUsd(amount)} > maxPrice ${atomicToUsd(max)}`);
+        notes.push(`${atomicToUsd(amount)} <= maxPrice ${atomicToUsd(max)}`);
+    }
+    else
+        notes.push(`${atomicToUsd(amount)} (no maxPrice given)`);
+    const cat = doc?.catalog;
+    if (cat?.url && sameUrl(cat.url, url) && typeof cat.price_usd === "number") {
+        const catAtomic = usdToAtomic(cat.price_usd);
+        if (catAtomic !== amount) {
+            const reason = `price_mismatch (catalog ${atomicToUsd(catAtomic)}, 402 ${atomicToUsd(amount)})`;
+            if (!opts.allowCatalogMismatch)
+                return stop("price", reason);
+            notes.push(`${reason}, allowed by allowCatalogMismatch`);
+        }
+        else
+            notes.push("matches catalog");
+    }
+    stages.push({ name: "price", ok: true, detail: notes.join("; ") });
+    out.ok = true;
+    return out;
+}
+const sameUrl = (a, b) => {
+    try {
+        const x = new URL(a);
+        const y = new URL(b);
+        return x.origin === y.origin && x.pathname.replace(/\/+$/, "") === y.pathname.replace(/\/+$/, "") && x.search === y.search;
+    }
+    catch {
+        return a === b;
+    }
+};
+const publicCheck = ({ parsed: _p, accept: _a, request: _r, ...c }) => c;
+/** Stages 1–3 only: Probe record, the 402 offer and the price checks. Nothing is signed or paid. */
+export async function checkSeller(url, opts = {}) {
+    return publicCheck(await prepare(url, opts));
+}
+const sha256 = (b) => createHash("sha256").update(b).digest("hex");
+/** Buy one call from an x402 seller. See README for the stages. */
+export async function safeBuy(url, opts) {
+    if (opts?.maxPrice === undefined || opts.maxPrice === null)
+        throw new TypeError("safeBuy: opts.maxPrice is required (USD, e.g. 0.01 or \"$0.01\")");
+    const maxAtomic = usdToAtomic(opts.maxPrice);
+    const rpcUrls = {
+        base: opts.rpc?.base || process.env.BASE_RPC_URL || DEFAULT_RPC.base,
+        solana: opts.rpc?.solana || process.env.SOLANA_RPC_URL || DEFAULT_RPC.solana,
+    };
+    const base = (p) => ({
+        ok: false, outcome: "refused", stopped_at: null, reason: null, status: null, body: null, body_sha256: null, content_type: null,
+        tx: null, tx_source: null, network: null, amount: null, transferred: null, payer_key: null, receipt: null, refetched: false,
+        latency_ms: null, offer: null, ...p,
+    });
+    // The payer is built first so chain "any" only picks a chain we can sign for.
+    let payer;
+    try {
+        payer = opts.client ? payerFromClient(opts.client) : await makePayer(opts.signer ?? {}, maxAtomic, rpcUrls);
+    }
+    catch (e) {
+        const reason = `signer: ${errMsg(e)}`;
+        return base({ stopped_at: "pay", reason, stages: [{ name: "pay", ok: false, detail: reason }], probe: { status: "unavailable", doc: null } });
+    }
+    const prep = await prepare(url, opts, payer.chains ?? undefined);
+    const { stages } = prep;
+    if (!prep.ok || !prep.accept || !prep.offer || !prep.parsed) {
+        return base({ stopped_at: prep.stopped_at, reason: prep.reason, stages, probe: prep.probe, offer: prep.offer });
+    }
+    const a = prep.accept;
+    const offer = prep.offer;
+    const amount = BigInt(offer.amount);
+    const stopAtPay = (reason) => {
+        stages.push({ name: "pay", ok: false, detail: reason });
+        return base({ stopped_at: "pay", reason, stages, probe: prep.probe, offer, network: offer.network, amount: offer.amount });
+    };
+    // 4. pay: sign, hand the payer-side identifier to the caller, then send.
+    let signed;
+    try {
+        signed = await signFor(payer, prep.parsed, a);
+    }
+    catch (e) {
+        return stopAtPay(`could not sign: ${errMsg(e)}`);
+    }
+    const payer_key = signed.payer_key;
+    const record = {
+        ts: new Date().toISOString(), url: prep.request.url, host: prep.host, network: offer.network, chain: offer.chain,
+        amount: offer.amount, pay_to: offer.pay_to, payer_key,
+    };
+    try {
+        await opts.onAttempt?.(record);
+    }
+    catch (e) {
+        return { ...stopAtPay(`onAttempt failed, payment not sent: ${errMsg(e)}`), payer_key };
+    }
+    stages.push({
+        name: "pay",
+        ok: true,
+        detail: `signed ${offer.amount_usd} on ${offer.network} as ${payer_key.payer}${signed.eip712_filled ? " (EIP-712 domain filled: USD Coin / 2)" : ""}`,
+    });
+    // 5. reconcile: paid request, settlement header, then the chain.
+    const headers = { ...prep.request.init.headers, ...signed.headers };
+    let status = 0;
+    let body = new Uint8Array(0);
+    let contentType = null;
+    let getHeader = () => null;
+    let requestError = null;
+    const tReq = Date.now();
+    try {
+        const r = await fetch(prep.request.url, { ...prep.request.init, headers, signal: AbortSignal.timeout(opts.requestTimeoutMs ?? REQUEST_TIMEOUT_MS), redirect: "follow" });
+        status = r.status;
+        body = new Uint8Array(await r.arrayBuffer());
+        contentType = r.headers.get("content-type");
+        getHeader = (n) => r.headers.get(n);
+    }
+    catch (e) {
+        requestError = errMsg(e);
+    }
+    const latency_ms = Date.now() - tReq;
+    const settle = settleFrom(payer.http, getHeader);
+    const search = { rpcUrl: rpcUrls[offer.chain], timeoutMs: opts.findTimeoutMs ?? DEFAULT_FIND_TIMEOUT_MS, pollMs: opts.pollIntervalMs ?? 5000 };
+    const want = { payer: payer_key.payer, payTo: offer.pay_to, amount };
+    let tx = null;
+    let tx_source = null;
+    let check = null;
+    if (settle?.transaction) {
+        tx = settle.transaction;
+        tx_source = "settle_header";
+        check = offer.chain === "solana"
+            ? checkSolanaTransfer(await getSolanaTx(tx, search), want)
+            : checkBaseTransfer(await getBaseReceipt(tx, search), want);
+    }
+    else {
+        // No settlement tx in a header (even on a 200): look for our own payment on chain.
+        const found = payer_key.chain === "solana"
+            ? await findSolanaPayment(payer_key.payer, payer_key.payer_signature, search).then((f) => f && { tx: f.signature, check: checkSolanaTransfer(f.tx, want) })
+            : await findBasePayment(payer_key.payer, payer_key.authorization_nonce, search).then((f) => f && { tx: f.hash, check: checkBaseTransfer(f.receipt, want) });
+        if (found) {
+            tx = found.tx;
+            tx_source = "onchain_search";
+            check = found.check;
+        }
+    }
+    const onchain_found = !!check && check.transferred !== null;
+    const transferred = check?.transferred ?? null;
+    stages.push({
+        name: "reconcile",
+        ok: !!check?.ok,
+        detail: [
+            `HTTP ${status || `error (${requestError})`}`,
+            settle ? `settlement header ${settle.success ? "success" : `failure${settle.error ? ` (${settle.error})` : ""}`}${settle.transaction ? ` tx ${settle.transaction}` : ""}` : "no settlement header",
+            tx ? `tx ${tx} (${tx_source}): ${check?.reason}` : `no payment found on chain within ${search.timeoutMs} ms`,
+            transferred !== null ? `transferred ${atomicToUsd(transferred)}` : null,
+        ].filter(Boolean).join("; "),
+    });
+    // Id the seller's receipt carries: Solana = tx signature, Base = authorization nonce.
+    const paymentId = payer_key.chain === "base" ? payer_key.authorization_nonce : tx;
+    let delivered = status === 200 && body.length > 0;
+    let refetched = false;
+    let receipt = null;
+    // 6. refetch: paid but nothing came back, and the seller keeps receipts.
+    if (tx && !delivered && paymentId) {
+        const wk = await fetchReceiptKeys(prep.request.url);
+        if (!wk.advertised || !wk.wellKnown) {
+            stages.push({ name: "refetch", ok: false, detail: `seller publishes no receipt keys (${wk.error ?? "no keys"}); not refetched` });
+        }
+        else {
+            const init = prep.request.init;
+            const r = await refetchCore({
+                url: prep.request.url,
+                paymentHeaders: signed.headers,
+                paymentId,
+                wellKnown: wk.wellKnown,
+                headers: init.headers,
+                // Re-send with the original method and body (the vendored helper always uses GET).
+                fetch: (u, i) => fetch(u, { ...i, method: init.method, ...(init.body !== undefined ? { body: init.body } : {}), signal: AbortSignal.timeout(opts.requestTimeoutMs ?? REQUEST_TIMEOUT_MS) }),
+            });
+            if (r.ok) {
+                refetched = true;
+                delivered = r.body.length > 0;
+                status = r.status;
+                body = r.body;
+                // The helper returns the verified receipt; it is re-encoded (canonical JSON) as the header value.
+                receipt = { header: encodeReceipt(r.receipt), ok: true, reason: null };
+                stages.push({ name: "refetch", ok: true, detail: `refetched with ${paymentId}: HTTP 200, ${r.body.length} bytes, receipt verified (key ${r.receipt.key_id})` });
+            }
+            else {
+                stages.push({ name: "refetch", ok: false, detail: `refetch failed: ${r.reason}${r.status ? ` (HTTP ${r.status})` : ""}${r.detail ? `: ${r.detail}` : ""}` });
+            }
+        }
+    }
+    // 7. receipt on a first-delivery 200
+    if (!refetched && status === 200) {
+        const h = getHeader(RECEIPT_HEADER);
+        if (h) {
+            const wk = await fetchReceiptKeys(prep.request.url);
+            receipt = checkReceipt(h, body, wk.wellKnown, paymentId);
+            stages.push({ name: "receipt", ok: receipt.ok, detail: receipt.ok ? "X-Delivery-Receipt verified" : `X-Delivery-Receipt invalid: ${receipt.reason}` });
+        }
+    }
+    let outcome;
+    if (tx && transferred !== null && BigInt(transferred) > amount)
+        outcome = "overcharged";
+    else if (tx && transferred !== null && check && !check.ok && BigInt(transferred) !== amount)
+        outcome = "amount_mismatch";
+    else if (tx)
+        outcome = delivered ? "delivered" : "not_delivered";
+    else if (delivered)
+        outcome = "delivered_unsettled";
+    else
+        outcome = status === 0 ? "failed" : "rejected";
+    const result = base({
+        ok: outcome === "delivered" || outcome === "delivered_unsettled",
+        outcome,
+        reason: outcome === "rejected" ? `HTTP ${status}${x402Reason(status, getHeader, body)}` : outcome === "failed" ? requestError : outcome === "overcharged" || outcome === "amount_mismatch" ? check?.reason ?? null : null,
+        status: status || null,
+        body,
+        body_sha256: sha256(body),
+        content_type: contentType,
+        tx,
+        tx_source,
+        network: offer.network,
+        amount: offer.amount,
+        transferred,
+        payer_key,
+        receipt,
+        refetched,
+        latency_ms,
+        offer,
+        probe: prep.probe,
+        stages,
+    });
+    // 8. report (opt-in, anonymized; never fails the purchase)
+    if (opts.report === true) {
+        const rep = buildReport({
+            host: prep.host, url: prep.request.url, network: offer.network, amount: offer.amount, outcome,
+            http_status: status || null, latency_ms, settled_header: !!settle, onchain_found, receipt_ok: receipt ? receipt.ok : null, refetched,
+        });
+        const s = await sendReport(opts.probeUrl ?? DEFAULT_PROBE_URL, rep);
+        stages.push({ name: "report", ok: s.ok, detail: s.ok ? `reported (${s.detail})` : `report failed (${s.detail}); purchase unaffected` });
+    }
+    return result;
+}
+function x402Reason(status, getHeader, body) {
+    if (status !== 402)
+        return "";
+    const e = x402Error(parse402(getHeader, Buffer.from(body).toString("utf8")));
+    return e ? `: ${e}` : "";
+}

package/dist/x402.d.ts

@@ -0,0 +1,45 @@
+import { type Chain, type ChainChoice } from "./constants.js";
+export type Accept = {
+    scheme?: string;
+    network?: string;
+    chain: Chain | null;
+    /** Atomic units: v2 `amount`, v1 `maxAmountRequired`. */
+    amount?: string;
+    asset?: string;
+    payTo?: string;
+    /** v2: top-level resource.url; v1: per-accept resource. */
+    resource?: string;
+    maxTimeoutSeconds?: number;
+    extra?: Record<string, unknown>;
+    raw: Record<string, unknown>;
+};
+export type Parsed402 = {
+    spec_version: "v1" | "v2" | null;
+    /** Where the requirements were read from. */
+    source: "header" | "body" | null;
+    accepts: Accept[];
+    raw: unknown;
+    error?: string;
+};
+export declare function parse402(getHeader: (n: string) => string | null, bodyText: string): Parsed402;
+export declare const isOfficialUsdc: (a: Accept) => boolean;
+/** Probe's rule: the first Solana/Base `exact` accept in official USDC, else the first Solana/Base accept. */
+export declare function primaryAccept(p: Parsed402): Accept | undefined;
+/**
+ * The accept safe-buy pays: `exact`, official USDC, on the requested chain. For "any",
+ * the first payable accept in CHAIN_PREFERENCE order (Base, then Solana), limited to
+ * `usable` chains when the caller knows which chains it can sign for.
+ */
+export declare function selectAccept(p: Parsed402, chain: ChainChoice, usable?: Chain[]): Accept | undefined;
+/** The 402's own `error` text, if any. */
+export declare function x402Error(p: Parsed402 | null): string | null;
+export type InputRequirement = {
+    requires: boolean;
+    reason: string | null;
+    source: "bazaar" | "outputSchema" | null;
+};
+/**
+ * Does buying this endpoint with a bare GET need input? Read only from the 402's own
+ * schemas (bazaar extension, v1 outputSchema); no schema means "no known input".
+ */
+export declare function inputRequirement(p: Parsed402 | null): InputRequirement;

package/dist/x402.js

@@ -0,0 +1,125 @@
+// Parsing a 402 Payment Required response (x402 v1 or v2) and choosing what to pay.
+// Pure functions. Ported from kato9292929/seller-probe src/x402.ts.
+import { CHAIN_PREFERENCE, USDC, chainOf } from "./constants.js";
+function b64json(s) {
+    return JSON.parse(Buffer.from(s.trim(), "base64").toString("utf8"));
+}
+const str = (v) => (typeof v === "string" && v.length ? v : typeof v === "number" ? String(v) : undefined);
+export function parse402(getHeader, bodyText) {
+    let doc = null;
+    let source = null;
+    const h = getHeader("payment-required");
+    if (h) {
+        try {
+            doc = b64json(h);
+            source = "header";
+        }
+        catch {
+            return { spec_version: null, source: "header", accepts: [], raw: h.slice(0, 500), error: "PAYMENT-REQUIRED header is not base64 JSON" };
+        }
+    }
+    else {
+        try {
+            doc = JSON.parse(bodyText);
+            source = "body";
+        }
+        catch {
+            return { spec_version: null, source: null, accepts: [], raw: bodyText.slice(0, 500), error: "no PAYMENT-REQUIRED header and body is not JSON" };
+        }
+    }
+    const v = doc?.x402Version;
+    const spec_version = v === 2 ? "v2" : v === 1 ? "v1" : null;
+    const topResource = typeof doc?.resource === "object" ? doc?.resource?.url : undefined;
+    const accepts = (Array.isArray(doc?.accepts) ? doc.accepts : []).map((a) => ({
+        scheme: str(a?.scheme),
+        network: str(a?.network),
+        chain: chainOf(str(a?.network)),
+        amount: str(a?.amount ?? a?.maxAmountRequired),
+        asset: str(a?.asset),
+        payTo: str(a?.payTo),
+        resource: str(spec_version === "v2" ? (topResource ?? a?.resource ?? a?.extra?.resource) : (a?.resource ?? topResource)),
+        maxTimeoutSeconds: typeof a?.maxTimeoutSeconds === "number" ? a.maxTimeoutSeconds : undefined,
+        extra: a?.extra && typeof a.extra === "object" ? a.extra : undefined,
+        raw: a ?? {},
+    }));
+    return { spec_version, source, accepts, raw: doc, ...(spec_version ? {} : { error: `unknown x402Version ${JSON.stringify(v)}` }) };
+}
+export const isOfficialUsdc = (a) => !!a.chain && !!a.asset && (a.chain === "base" ? a.asset.toLowerCase() === USDC.base.toLowerCase() : a.asset === USDC.solana);
+/** Probe's rule: the first Solana/Base `exact` accept in official USDC, else the first Solana/Base accept. */
+export function primaryAccept(p) {
+    const onChain = p.accepts.filter((a) => a.chain);
+    return onChain.find((a) => a.scheme === "exact" && isOfficialUsdc(a)) ?? onChain[0];
+}
+/**
+ * The accept safe-buy pays: `exact`, official USDC, on the requested chain. For "any",
+ * the first payable accept in CHAIN_PREFERENCE order (Base, then Solana), limited to
+ * `usable` chains when the caller knows which chains it can sign for.
+ */
+export function selectAccept(p, chain, usable) {
+    const order = chain === "any" ? CHAIN_PREFERENCE.filter((c) => !usable || usable.includes(c)) : [chain];
+    for (const c of order) {
+        const hit = p.accepts.find((a) => a.chain === c && a.scheme === "exact" && isOfficialUsdc(a));
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+/** The 402's own `error` text, if any. */
+export function x402Error(p) {
+    const e = p?.raw?.error;
+    return typeof e === "string" && e ? e.slice(0, 300) : null;
+}
+const READ_METHODS = ["GET", "HEAD"];
+const nonEmpty = (v) => (Array.isArray(v) ? v.length > 0 : !!v && typeof v === "object" && Object.keys(v).length > 0);
+/** JSON-Schema form: { properties: { method, body, queryParams }, required } (bazaar `schema.properties.input`). */
+function fromInputSchema(s) {
+    const props = s?.properties ?? {};
+    const m = props.method;
+    const methods = Array.isArray(m?.enum) ? m.enum : typeof m?.const === "string" ? [m.const] : null;
+    if (methods && !methods.some((x) => typeof x === "string" && READ_METHODS.includes(x.toUpperCase())))
+        return `method ${methods.join("/")}`;
+    if (Array.isArray(props.body?.required) && props.body.required.length)
+        return `body: ${props.body.required.join(", ")}`;
+    if (Array.isArray(s?.required) && s.required.includes("body"))
+        return "body required";
+    if (Array.isArray(props.queryParams?.required) && props.queryParams.required.length)
+        return `query: ${props.queryParams.required.join(", ")}`;
+    return null;
+}
+/** Example/description form: { method, queryParams, body, bodyFields } (bazaar `info.input`, x402 v1 `outputSchema.input`). */
+function fromInputInfo(i) {
+    if (!i || typeof i !== "object")
+        return null;
+    if (typeof i.method === "string" && !READ_METHODS.includes(i.method.toUpperCase()))
+        return `method ${i.method}`;
+    if (nonEmpty(i.body))
+        return "body";
+    const requiredNames = (fields) => fields && typeof fields === "object" && !Array.isArray(fields)
+        ? Object.entries(fields).filter(([, v]) => v?.required === true).map(([k]) => k)
+        : [];
+    const q = requiredNames(i.queryParams);
+    if (q.length)
+        return `query: ${q.join(", ")}`;
+    const b = requiredNames(i.bodyFields);
+    if (b.length)
+        return `body: ${b.join(", ")}`;
+    return null;
+}
+/**
+ * Does buying this endpoint with a bare GET need input? Read only from the 402's own
+ * schemas (bazaar extension, v1 outputSchema); no schema means "no known input".
+ */
+export function inputRequirement(p) {
+    const doc = p?.raw;
+    const bazaar = doc?.extensions?.bazaar;
+    const r1 = fromInputSchema(bazaar?.schema?.properties?.input) ?? fromInputInfo(bazaar?.info?.input);
+    if (r1)
+        return { requires: true, reason: r1, source: "bazaar" };
+    for (const a of p?.accepts ?? []) {
+        const os = a.raw?.outputSchema;
+        const r2 = fromInputSchema(os?.input?.type === "object" ? os.input : null) ?? fromInputInfo(os?.input);
+        if (r2)
+            return { requires: true, reason: r2, source: "outputSchema" };
+    }
+    return { requires: false, reason: null, source: bazaar ? "bazaar" : null };
+}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@x402jp/safe-buy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Buy from an x402 (HTTP 402, USDC) seller safely: Probe check, price cap, payment reconciliation, refetch and Delivery Receipt verification. Also an MCP server.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "x402-safe-buy-mcp": "dist/mcp-bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "x402",
+    "usdc",
+    "mcp",
+    "base",
+    "solana",
+    "payments",
+    "agent"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/mcp-bin.js",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test --import tsx test/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "try": "tsx scripts/try.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "@solana/kit": "^8.6.0",
+    "@x402/core": "^2.29.0",
+    "@x402/evm": "^2.29.0",
+    "@x402/extensions": "^2.29.0",
+    "@x402/svm": "^2.29.0",
+    "@x402jp/delivery-receipt-verify": "^0.1.0",
+    "bs58": "^6.0.0",
+    "viem": "^2.57.14",
+    "zod": "^4.6.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kato9292929/x402-safe-buy.git"
+  },
+  "homepage": "https://github.com/kato9292929/x402-safe-buy#readme"
+}