@x402jp/safe-buy 0.0.0-stage → 0.1.0

package/dist/pay.d.ts

@@ -0,0 +1,58 @@
+import { x402Client, x402HTTPClient } from "@x402/core/client";
+import { type Chain } from "./constants.js";
+import { type Accept, type Parsed402 } from "./x402.js";
+export type Signer = {
+    evmPrivateKey?: string;
+    solanaSecretKey?: string;
+};
+export type Payer = {
+    http: x402HTTPClient;
+    chains: Chain[] | null;
+};
+/**
+ * Payer-side identifier of a payment, known before it is sent. Solana: our own signature
+ * inside the tx. Base: the EIP-3009 nonce and the SHA-256 of the signature (the raw
+ * signature is never exposed: with it anyone could submit the transfer).
+ */
+export type PayerKey = {
+    chain: "solana";
+    payer: string;
+    payer_signature: string;
+    payment_identifier?: string;
+} | {
+    chain: "base";
+    payer: string;
+    authorization_nonce: string;
+    authorization_signature_sha256: string;
+    payment_identifier?: string;
+};
+/** Build a paying client from caller-supplied keys; the library spend cap is set to maxAtomic. */
+export declare function makePayer(signer: Signer, maxAtomic: bigint, rpc: Record<Chain, string>): Promise<Payer>;
+/** Wrap a caller-built x402Client (its own policies/caps apply in addition to ours). */
+export declare function payerFromClient(client: x402Client): Payer;
+/** Why this accept cannot be paid by safe-buy, or null. Price is checked separately. */
+export declare function refuseReason(a: Accept | undefined): string | null;
+/** EIP-712 domain of official USDC on Base (name() / version() of 0x8335…2913). */
+export declare const BASE_USDC_EIP712: {
+    readonly name: "USD Coin";
+    readonly version: "2";
+};
+/** Domain fill for official Base USDC when the 402's `extra` lacks name/version. Never for other assets. */
+export declare function eip712Fill(a: Accept): Record<string, string> | null;
+export type Signed = {
+    /** Headers to send with the paid request (PAYMENT-SIGNATURE or X-PAYMENT). Never logged. */
+    headers: Record<string, string>;
+    payer_key: PayerKey;
+    /** The 402 named official Base USDC without EIP-712 name/version; the known values were filled in. */
+    eip712_filled: boolean;
+};
+/** Sign a payment for exactly this accept (the seller's other options are dropped). */
+export declare function signFor(payer: Payer, parsed: Parsed402, a: Accept): Promise<Signed>;
+export type Settlement = {
+    success: boolean;
+    transaction: string | null;
+    network: string | null;
+    error: string | null;
+};
+/** The seller's PAYMENT-RESPONSE / X-PAYMENT-RESPONSE header, decoded; null when absent or unreadable. */
+export declare function settleFrom(http: x402HTTPClient, getHeader: (n: string) => string | null): Settlement | null;

package/dist/pay.js

@@ -0,0 +1,123 @@
+// Signing an x402 payment with the official x402 client libraries. Keys are supplied by
+// the caller and only handed to the scheme signers; they are never stored or logged here.
+// Ported from seller-probe src/pay.ts.
+import { createHash } from "node:crypto";
+import { x402Client, x402HTTPClient } from "@x402/core/client";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { ExactEvmSchemeV1 } from "@x402/evm/v1";
+import { PAYMENT_IDENTIFIER, appendPaymentIdentifierToExtensions } from "@x402/extensions/payment-identifier";
+import { ExactSvmScheme } from "@x402/svm/exact/client";
+import { ExactSvmSchemeV1 } from "@x402/svm/v1";
+import { privateKeyToAccount } from "viem/accounts";
+import { evmAuthorization } from "./chains/base.js";
+import { payerSignature, solanaSignerFrom } from "./chains/solana.js";
+import { NETWORKS } from "./constants.js";
+import { atomicToUsd } from "./price.js";
+import { isOfficialUsdc } from "./x402.js";
+/** Build a paying client from caller-supplied keys; the library spend cap is set to maxAtomic. */
+export async function makePayer(signer, maxAtomic, rpc) {
+    const client = x402Client.fromConfig({
+        schemes: [],
+        // Library-side cap as a second fence; safe-buy's own price check runs first.
+        spendControls: { maxAmountPerPayment: atomicToUsd(maxAtomic) },
+    });
+    const chains = [];
+    if (signer.evmPrivateKey) {
+        const key = signer.evmPrivateKey.trim();
+        if (!/^0x[0-9a-fA-F]{64}$/.test(key))
+            throw new Error("evmPrivateKey must be a 0x-prefixed 32-byte hex key");
+        const account = privateKeyToAccount(key);
+        client.register(NETWORKS.base.caip2, new ExactEvmScheme(account, { rpcUrl: rpc.base }));
+        for (const n of NETWORKS.base.v1)
+            client.registerV1(n, new ExactEvmSchemeV1(account));
+        chains.push("base");
+    }
+    if (signer.solanaSecretKey) {
+        const s = await solanaSignerFrom(signer.solanaSecretKey);
+        client.register(NETWORKS.solana.caip2, new ExactSvmScheme(s, { rpcUrl: rpc.solana }));
+        for (const n of NETWORKS.solana.v1)
+            client.registerV1(n, new ExactSvmSchemeV1(s, { rpcUrl: rpc.solana }));
+        chains.push("solana");
+    }
+    if (!chains.length)
+        throw new Error("no signer key given (signer.evmPrivateKey / signer.solanaSecretKey)");
+    return { http: new x402HTTPClient(client), chains };
+}
+/** Wrap a caller-built x402Client (its own policies/caps apply in addition to ours). */
+export function payerFromClient(client) {
+    return { http: new x402HTTPClient(client), chains: null };
+}
+/** Why this accept cannot be paid by safe-buy, or null. Price is checked separately. */
+export function refuseReason(a) {
+    if (!a)
+        return "no exact official-USDC accept on the requested chain";
+    if (a.scheme !== "exact")
+        return `scheme ${a.scheme} (only exact)`;
+    if (!a.chain)
+        return `network ${a.network}`;
+    if (!isOfficialUsdc(a))
+        return `asset ${a.asset} is not official USDC`;
+    if (!a.amount || !/^\d+$/.test(a.amount))
+        return `bad amount ${a.amount}`;
+    if (BigInt(a.amount) <= 0n)
+        return `amount ${a.amount} (nothing to buy)`;
+    if (!a.payTo)
+        return "payTo missing";
+    if (a.chain === "base" && a.extra?.assetTransferMethod && a.extra.assetTransferMethod !== "eip3009")
+        return `asset transfer method ${String(a.extra.assetTransferMethod)} (only EIP-3009)`;
+    return null;
+}
+/** EIP-712 domain of official USDC on Base (name() / version() of 0x8335…2913). */
+export const BASE_USDC_EIP712 = { name: "USD Coin", version: "2" };
+/** Domain fill for official Base USDC when the 402's `extra` lacks name/version. Never for other assets. */
+export function eip712Fill(a) {
+    if (a.chain !== "base" || !isOfficialUsdc(a))
+        return null;
+    const extra = a.raw?.extra ?? {};
+    if (extra.name && extra.version)
+        return null;
+    return { name: extra.name || BASE_USDC_EIP712.name, version: extra.version || BASE_USDC_EIP712.version };
+}
+/** Sign a payment for exactly this accept (the seller's other options are dropped). */
+export async function signFor(payer, parsed, a) {
+    const doc = parsed.raw;
+    const fill = eip712Fill(a);
+    const raw = fill ? { ...a.raw, extra: { ...(a.raw?.extra ?? {}), ...fill } } : a.raw;
+    const payload = await payer.http.createPaymentPayload({ ...doc, accepts: [raw] });
+    // x402 `payment-identifier` extension: when the seller declares it, send a fresh id.
+    let payment_identifier;
+    const pid = doc?.extensions?.[PAYMENT_IDENTIFIER];
+    if (pid) {
+        const ext = { ...(payload.extensions ?? {}), [PAYMENT_IDENTIFIER]: payload.extensions?.[PAYMENT_IDENTIFIER] ?? pid };
+        appendPaymentIdentifierToExtensions(ext);
+        payload.extensions = ext;
+        payment_identifier = ext[PAYMENT_IDENTIFIER]?.info?.id ?? undefined;
+    }
+    let payer_key;
+    if (a.chain === "solana") {
+        const ps = payerSignature(payload);
+        payer_key = { chain: "solana", payer: ps.payer, payer_signature: ps.signature };
+    }
+    else {
+        const auth = evmAuthorization(payload);
+        payer_key = {
+            chain: "base",
+            payer: auth.from,
+            authorization_nonce: auth.nonce,
+            authorization_signature_sha256: createHash("sha256").update(auth.signature).digest("hex"),
+        };
+    }
+    if (payment_identifier)
+        payer_key.payment_identifier = payment_identifier;
+    return { headers: payer.http.encodePaymentSignatureHeader(payload), payer_key, eip712_filled: !!fill };
+}
+/** The seller's PAYMENT-RESPONSE / X-PAYMENT-RESPONSE header, decoded; null when absent or unreadable. */
+export function settleFrom(http, getHeader) {
+    try {
+        const s = http.getPaymentSettleResponse(getHeader);
+        return { success: !!s.success, transaction: s.transaction || null, network: s.network ?? null, error: s.errorReason ?? null };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/price.d.ts

@@ -0,0 +1,8 @@
+export type Price = number | string;
+/**
+ * Parse a USD price (`0.01`, `"0.01"`, `"$0.01"`) into USDC atomic units. Digits past the
+ * 6th decimal are truncated (a cap never rounds up). Throws on anything else.
+ */
+export declare function usdToAtomic(price: Price): bigint;
+/** Atomic USDC units -> "$0.01" (trailing zeros trimmed, at least 2 decimals). */
+export declare function atomicToUsd(atomic: bigint | string): string;

package/dist/price.js

@@ -0,0 +1,35 @@
+// USD <-> USDC atomic units (6 decimals). Decimal string math only, no floats.
+/**
+ * Parse a USD price (`0.01`, `"0.01"`, `"$0.01"`) into USDC atomic units. Digits past the
+ * 6th decimal are truncated (a cap never rounds up). Throws on anything else.
+ */
+export function usdToAtomic(price) {
+    let s;
+    if (typeof price === "number") {
+        if (!Number.isFinite(price) || price < 0)
+            throw new Error(`invalid price ${price}`);
+        s = price.toFixed(10);
+    }
+    else if (typeof price === "string") {
+        s = price.trim().replace(/^\$/, "").trim();
+    }
+    else {
+        throw new Error("price must be a number or a string like \"$0.01\"");
+    }
+    const m = /^(\d+)(?:\.(\d*))?$/.exec(s);
+    if (!m)
+        throw new Error(`invalid price ${JSON.stringify(price)}`);
+    const frac = (m[2] ?? "").padEnd(6, "0").slice(0, 6);
+    return BigInt(m[1]) * 1000000n + BigInt(frac);
+}
+/** Atomic USDC units -> "$0.01" (trailing zeros trimmed, at least 2 decimals). */
+export function atomicToUsd(atomic) {
+    const v = BigInt(atomic);
+    const neg = v < 0n;
+    const a = neg ? -v : v;
+    const whole = a / 1000000n;
+    let frac = (a % 1000000n).toString().padStart(6, "0").replace(/0+$/, "");
+    if (frac.length < 2)
+        frac = frac.padEnd(2, "0");
+    return `${neg ? "-" : ""}$${whole}.${frac}`;
+}

package/dist/probe.d.ts

@@ -0,0 +1,36 @@
+/** Fields of the Probe's host document that safe-buy uses (others are ignored). */
+export type ProbeDoc = {
+    host?: string;
+    score?: number | null;
+    coverage?: string | null;
+    buyable_without_input?: boolean | null;
+    requires_input_reason?: {
+        source?: string;
+        reason?: string;
+    } | null;
+    last_paid?: {
+        date?: string;
+        ts?: string;
+        outcome?: string | null;
+        price_usd?: number | null;
+        network?: string | null;
+    } | null;
+    catalog?: {
+        url?: string;
+        price_usd?: number | null;
+    } | null;
+};
+export type ProbeLookup = {
+    status: "found";
+    doc: ProbeDoc;
+} | {
+    status: "no_data";
+} | {
+    status: "unavailable";
+    error: string;
+};
+/** Lowercase hostname without a leading "www.". */
+export declare const hostOf: (url: string) => string;
+export declare function lookupProbe(probeUrl: string, host: string, timeoutMs?: number): Promise<ProbeLookup>;
+/** Last-purchase outcomes that make safe-buy refuse to pay. */
+export declare const BAD_LAST_PAID: string[];

package/dist/probe.js

@@ -0,0 +1,46 @@
+// Stage 1: the seller's public record at the x402 Seller Probe (GET {probeUrl}/scores/{host}).
+import { PROBE_TIMEOUT_MS, USER_AGENT } from "./constants.js";
+/** Lowercase hostname without a leading "www.". */
+export const hostOf = (url) => new URL(url).hostname.toLowerCase().replace(/^www\./, "");
+export async function lookupProbe(probeUrl, host, timeoutMs = PROBE_TIMEOUT_MS) {
+    let res;
+    try {
+        res = await fetch(`${probeUrl.replace(/\/+$/, "")}/scores/${encodeURIComponent(host)}`, {
+            headers: { accept: "application/json", "user-agent": USER_AGENT },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (e) {
+        return { status: "unavailable", error: e?.name === "TimeoutError" ? "timeout" : String(e?.message ?? e) };
+    }
+    if (res.status === 404) {
+        await res.body?.cancel().catch(() => { });
+        return { status: "no_data" };
+    }
+    if (!res.ok) {
+        await res.body?.cancel().catch(() => { });
+        return { status: "unavailable", error: `HTTP ${res.status}` };
+    }
+    try {
+        const doc = await res.json();
+        if (!doc || typeof doc !== "object")
+            return { status: "unavailable", error: "not a JSON object" };
+        return { status: "found", doc: pickDoc(doc) };
+    }
+    catch {
+        return { status: "unavailable", error: "invalid JSON" };
+    }
+}
+function pickDoc(d) {
+    return {
+        host: d.host,
+        score: d.score ?? null,
+        coverage: d.coverage ?? null,
+        buyable_without_input: typeof d.buyable_without_input === "boolean" ? d.buyable_without_input : null,
+        requires_input_reason: d.requires_input_reason ?? null,
+        last_paid: d.last_paid ?? null,
+        catalog: d.catalog && typeof d.catalog === "object" ? { url: d.catalog.url, price_usd: d.catalog.price_usd ?? null } : null,
+    };
+}
+/** Last-purchase outcomes that make safe-buy refuse to pay. */
+export const BAD_LAST_PAID = ["not_delivered", "overcharged"];

package/dist/receipt.d.ts

@@ -0,0 +1,30 @@
+import { RECEIPT_HEADER, REFETCH_HEADER, WELL_KNOWN_PATH, type WellKnown } from "@x402jp/delivery-receipt-verify";
+export { RECEIPT_HEADER, REFETCH_HEADER, WELL_KNOWN_PATH, type WellKnown };
+export type WellKnownLookup = {
+    advertised: boolean;
+    wellKnown: WellKnown | null;
+    error: string | null;
+};
+/** Fetch `<origin>/.well-known/x402-receipt.json`. advertised = valid document with at least one key. */
+export declare function fetchReceiptKeys(url: string, timeoutMs?: number): Promise<WellKnownLookup>;
+export type ReceiptCheck = {
+    header: string;
+    ok: boolean;
+    reason: string | null;
+};
+/** Verify a receipt header against body bytes with a known key document. */
+export declare function checkReceipt(header: string, body: Uint8Array, wellKnown: WellKnown | null, paymentId: string | null): ReceiptCheck;
+export type VerifyReceiptArgs = {
+    /** The paid resource URL (its origin serves the key document). */
+    url: string;
+    /** Raw X-Delivery-Receipt header value. */
+    header: string;
+    /** Exact response body bytes. */
+    body: Uint8Array;
+    /** Expected payment_id: Solana tx signature, Base EIP-3009 nonce. */
+    paymentId?: string | null;
+};
+/** Fetch the seller's key document and verify a receipt. */
+export declare function verifyReceipt(args: VerifyReceiptArgs): Promise<ReceiptCheck & {
+    key_document: string | null;
+}>;

package/dist/receipt.js

@@ -0,0 +1,44 @@
+// Delivery Receipts (kato9292929/delivery-receipt): the seller's key document and
+// verification of a receipt against the exact body bytes.
+import { USER_AGENT } from "./constants.js";
+import { RECEIPT_HEADER, REFETCH_HEADER, WELL_KNOWN_PATH, parseWellKnown, verifyReceipt as verifyReceiptCore, } from "@x402jp/delivery-receipt-verify";
+export { RECEIPT_HEADER, REFETCH_HEADER, WELL_KNOWN_PATH };
+/** Fetch `<origin>/.well-known/x402-receipt.json`. advertised = valid document with at least one key. */
+export async function fetchReceiptKeys(url, timeoutMs = 5000) {
+    let res;
+    try {
+        res = await fetch(new URL(WELL_KNOWN_PATH, new URL(url).origin), {
+            headers: { accept: "application/json", "user-agent": USER_AGENT },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (e) {
+        return { advertised: false, wellKnown: null, error: e?.name === "TimeoutError" ? "timeout" : String(e?.message ?? e) };
+    }
+    if (!res.ok) {
+        await res.body?.cancel().catch(() => { });
+        return { advertised: false, wellKnown: null, error: `HTTP ${res.status}` };
+    }
+    try {
+        const wk = parseWellKnown(await res.json());
+        return { advertised: wk.keys.length > 0, wellKnown: wk, error: null };
+    }
+    catch (e) {
+        return { advertised: false, wellKnown: null, error: `invalid ${WELL_KNOWN_PATH}: ${e?.message ?? e}` };
+    }
+}
+/** Verify a receipt header against body bytes with a known key document. */
+export function checkReceipt(header, body, wellKnown, paymentId) {
+    if (!wellKnown)
+        return { header, ok: false, reason: `receipt_key_unknown (no usable ${WELL_KNOWN_PATH})` };
+    const v = verifyReceiptCore({ header, body, wellKnown, expect: paymentId ? { payment_id: paymentId } : undefined });
+    return v.ok ? { header, ok: true, reason: null } : { header, ok: false, reason: v.detail ? `${v.reason}: ${v.detail}` : v.reason };
+}
+/** Fetch the seller's key document and verify a receipt. */
+export async function verifyReceipt(args) {
+    const wk = await fetchReceiptKeys(args.url);
+    const r = wk.wellKnown
+        ? checkReceipt(args.header, args.body, wk.wellKnown, args.paymentId ?? null)
+        : { header: args.header, ok: false, reason: `receipt_key_unknown (${WELL_KNOWN_PATH}: ${wk.error})` };
+    return { ...r, key_document: wk.wellKnown ? new URL(WELL_KNOWN_PATH, new URL(args.url).origin).toString() : null };
+}

package/dist/report.d.ts

@@ -0,0 +1,26 @@
+export type Report = {
+    v: 1;
+    host: string;
+    /** origin + path only (no query, no fragment). */
+    url: string;
+    network: string | null;
+    amount: string | null;
+    outcome: string;
+    http_status: number | null;
+    latency_ms: number | null;
+    settled_header: boolean;
+    onchain_found: boolean;
+    receipt_ok: boolean | null;
+    refetched: boolean;
+    sdk: string;
+    ts: string;
+};
+export declare function buildReport(r: Omit<Report, "v" | "sdk" | "url" | "ts"> & {
+    url: string;
+    ts?: Date;
+}): Report;
+/** POST the report. Never throws: a failed report never fails the purchase. */
+export declare function sendReport(probeUrl: string, report: Report, timeoutMs?: number): Promise<{
+    ok: boolean;
+    detail: string;
+}>;

package/dist/report.js

@@ -0,0 +1,38 @@
+// Stage 8 (opt-in): an anonymized purchase report to the Probe. It never contains the
+// payer address, the tx, payer-side identifiers, the body or any query string.
+import { SDK_ID, USER_AGENT } from "./constants.js";
+export function buildReport(r) {
+    const u = new URL(r.url);
+    return {
+        v: 1,
+        host: r.host,
+        url: u.origin + u.pathname,
+        network: r.network,
+        amount: r.amount,
+        outcome: r.outcome,
+        http_status: r.http_status,
+        latency_ms: r.latency_ms,
+        settled_header: r.settled_header,
+        onchain_found: r.onchain_found,
+        receipt_ok: r.receipt_ok,
+        refetched: r.refetched,
+        sdk: SDK_ID,
+        ts: (r.ts ?? new Date()).toISOString(),
+    };
+}
+/** POST the report. Never throws: a failed report never fails the purchase. */
+export async function sendReport(probeUrl, report, timeoutMs = 5000) {
+    try {
+        const res = await fetch(`${probeUrl.replace(/\/+$/, "")}/reports`, {
+            method: "POST",
+            headers: { "content-type": "application/json", "user-agent": USER_AGENT },
+            body: JSON.stringify(report),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        await res.body?.cancel().catch(() => { });
+        return { ok: res.ok, detail: `HTTP ${res.status}` };
+    }
+    catch (e) {
+        return { ok: false, detail: e?.name === "TimeoutError" ? "timeout" : String(e?.message ?? e) };
+    }
+}

package/dist/safe-buy.d.ts

@@ -0,0 +1,122 @@
+import type { x402Client } from "@x402/core/client";
+import { type Chain, type ChainChoice } from "./constants.js";
+import { type PayerKey, type Signer } from "./pay.js";
+import { type Price } from "./price.js";
+import { type ProbeDoc } from "./probe.js";
+import { type ReceiptCheck } from "./receipt.js";
+import { type InputRequirement } from "./x402.js";
+export type StageName = "probe" | "402" | "price" | "pay" | "reconcile" | "refetch" | "receipt" | "report";
+export type Stage = {
+    name: StageName;
+    ok: boolean;
+    detail: string;
+};
+/** Request input for endpoints that need more than a bare GET. */
+export type BuyInput = {
+    /** Defaults to GET, or POST when `body` is given. */
+    method?: string;
+    query?: Record<string, string | number | boolean>;
+    /** Object/array → JSON; string/Uint8Array → sent as is. */
+    body?: unknown;
+    headers?: Record<string, string>;
+};
+/** The accept that would be (or was) paid. */
+export type Offer = {
+    spec_version: "v1" | "v2" | null;
+    scheme: string;
+    network: string;
+    chain: Chain;
+    /** Atomic USDC (6 decimals). */
+    amount: string;
+    amount_usd: string;
+    asset: string;
+    pay_to: string;
+    resource: string | null;
+    max_timeout_seconds: number | null;
+};
+export type ProbeInfo = {
+    status: "found" | "no_data" | "unavailable";
+    doc: ProbeDoc | null;
+};
+export type CheckOptions = {
+    /** Default https://probe.x402jp.com. */
+    probeUrl?: string;
+    /** Default "any" (Base preferred, then Solana). */
+    chain?: ChainChoice;
+    /** USD cap, e.g. 0.01 or "$0.01". Optional for checkSeller, required for safeBuy. */
+    maxPrice?: Price;
+    input?: BuyInput;
+    /** Pay even when the 402 price differs from the Probe catalog price. */
+    allowCatalogMismatch?: boolean;
+    /** Timeout of the unpaid and paid requests to the seller (default 60 s). */
+    requestTimeoutMs?: number;
+};
+/** What onAttempt receives: everything needed to find the payment later. No key material. */
+export type AttemptRecord = {
+    ts: string;
+    url: string;
+    host: string;
+    network: string;
+    chain: Chain;
+    amount: string;
+    pay_to: string;
+    payer_key: PayerKey;
+};
+export type SafeBuyOptions = CheckOptions & {
+    maxPrice: Price;
+    /** Keys used only to sign this payment; never stored or logged. */
+    signer?: Signer;
+    /** Alternatively a prebuilt x402Client with schemes registered. */
+    client?: x402Client;
+    /** Called after signing and BEFORE the payment is sent (e.g. to persist a ledger row). If it throws, nothing is sent. */
+    onAttempt?: (record: AttemptRecord) => void | Promise<void>;
+    /** RPC URLs for the chain search (default: env BASE_RPC_URL / SOLANA_RPC_URL, then public endpoints). */
+    rpc?: {
+        base?: string;
+        solana?: string;
+    };
+    /** How long to look on chain for our payment (default 90 s). */
+    findTimeoutMs?: number;
+    /** Poll interval of the chain search (default 5 s). */
+    pollIntervalMs?: number;
+    /** Send an anonymized report to the Probe (default false). */
+    report?: boolean;
+};
+export type Outcome = "delivered" | "delivered_unsettled" | "not_delivered" | "overcharged" | "amount_mismatch" | "rejected" | "failed" | "refused";
+export type CheckResult = {
+    ok: boolean;
+    stopped_at: StageName | null;
+    reason: string | null;
+    stages: Stage[];
+    host: string;
+    probe: ProbeInfo;
+    offer: Offer | null;
+    input_requirement: InputRequirement | null;
+};
+export type SafeBuyResult = {
+    ok: boolean;
+    outcome: Outcome;
+    stopped_at: StageName | null;
+    reason: string | null;
+    status: number | null;
+    body: Uint8Array | null;
+    body_sha256: string | null;
+    content_type: string | null;
+    tx: string | null;
+    tx_source: "settle_header" | "onchain_search" | null;
+    network: string | null;
+    amount: string | null;
+    /** USDC that actually left the payer in the tx (atomic), when it could be read on chain. */
+    transferred: string | null;
+    payer_key: PayerKey | null;
+    receipt: ReceiptCheck | null;
+    refetched: boolean;
+    latency_ms: number | null;
+    offer: Offer | null;
+    probe: ProbeInfo;
+    stages: Stage[];
+};
+/** Stages 1–3 only: Probe record, the 402 offer and the price checks. Nothing is signed or paid. */
+export declare function checkSeller(url: string, opts?: CheckOptions): Promise<CheckResult>;
+/** Buy one call from an x402 seller. See README for the stages. */
+export declare function safeBuy(url: string, opts: SafeBuyOptions): Promise<SafeBuyResult>;