@piprail/sdk 1.22.0 → 1.23.0

package/dist/index.d.cts

@@ -5538,6 +5538,15 @@ declare function explainDecline(err: unknown): string;
  * convenience, not a durable ledger.
  */
 declare function formatSpendReport(summary: SpendSummary): string;
+/**
+ * One line a human or model can act on for a 402 challenge: what it is, the first
+ * rail's amount/token/chain + recipient, and how to pay it programmatically. Composes
+ * only shipped challenge fields (same `amountFormatted ?? amount` / `symbol ?? asset`
+ * convention as the renderers above) — pure, no I/O. Used as the human `instruction`
+ * inside the self-describe block and as a landing page's headline. An empty `accepts`
+ * (shouldn't happen for a valid v2 challenge) degrades to a generic pointer.
+ */
+declare function describeChallenge(challenge: X402Challenge): string;
 
 /**
  * The PipRail agent contract, distilled into one string an LLM can read once and
@@ -5550,7 +5559,7 @@ declare function formatSpendReport(summary: SpendSummary): string;
  * literally, so a wrong name or order actively misleads. A test pins the load-
  * bearing phrases.
  */
-declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Gasless \u2014 the exact rail (zero gas for you)\nA 402 may offer up to two rails; you don't choose per payment \u2014 the client does, automatically:\n- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas\n  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.\n- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose\n  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It\n  works on EVM + Solana, and the on-chain method (EIP-3009 / Permit2 / SVM) is picked automatically.\nWhen the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest\nsettleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is\nidentical. The exact scheme is OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact);\nyou can't enable it yourself, but you can report when a 402 needs it (see UNSUPPORTED_SCHEME below).\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless\n  exact rail `.ref` is the authorization NONCE, not a tx hash: re-present the SAME\n  signed authorization, never sign a fresh one (that would risk a double-spend).\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes\n  once (enable the exact scheme); report it, don't retry the same call blindly.\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left, per\n(network, asset), plus your spend so far. Read-only; moves no funds. Use it in\nMode A to self-check before paying.\n\n## Two modes\n- Mode A (headless, default): you run FREE inside a pre-set budget + time\n  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay\n  inside it; piprail_budget shows what's left.\n- Mode B (supervised): the host may ask a human to approve each payment. A\n  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014\n  do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Spend caps are PER (network, asset). There is no single cross-token dollar cap \u2014\n  budgets aren't summed across tokens (no price oracle).\n- Spend totals and the time envelope live IN-MEMORY for THIS process; they reset on restart\n  (a convenience, not a durable ledger).\n";
+declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## Landing cold \u2014 read the self-description\nEvery PipRail 402 self-describes. Read challenge.extensions.piprail for { name, what, pay[]\n(each rail's how-to-pay), sdk.install, mcp, docs } \u2014 never guess what an endpoint is. If your\ntooling can't pay a rail (e.g. a stock x402 client can't pay the onchain-proof scheme), the\nblock says how: install @piprail/sdk (npm i @piprail/sdk) or run the MCP (npx -y @piprail/mcp)\nand pay with the tools below.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Gasless \u2014 the exact rail (zero gas for you)\nA 402 may offer up to two rails; you don't choose per payment \u2014 the client does, automatically:\n- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas\n  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.\n- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose\n  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It\n  works on EVM + Solana, and the on-chain method (EIP-3009 / Permit2 / SVM) is picked automatically.\nWhen the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest\nsettleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is\nidentical. The exact scheme is OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact);\nyou can't enable it yourself, but you can report when a 402 needs it (see UNSUPPORTED_SCHEME below).\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless\n  exact rail `.ref` is the authorization NONCE, not a tx hash: re-present the SAME\n  signed authorization, never sign a fresh one (that would risk a double-spend).\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes\n  once (enable the exact scheme); report it, don't retry the same call blindly.\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left, per\n(network, asset), plus your spend so far. Read-only; moves no funds. Use it in\nMode A to self-check before paying.\n\n## Two modes\n- Mode A (headless, default): you run FREE inside a pre-set budget + time\n  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay\n  inside it; piprail_budget shows what's left.\n- Mode B (supervised): the host may ask a human to approve each payment. A\n  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014\n  do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Spend caps are PER (network, asset). There is no single cross-token dollar cap \u2014\n  budgets aren't summed across tokens (no price oracle).\n- Spend totals and the time envelope live IN-MEMORY for THIS process; they reset on restart\n  (a convenience, not a durable ledger).\n";
 /** Returns {@link PIPRAIL_AGENT_GUIDE} (a parity accessor for callers that prefer a function). */
 declare function agentGuide(): string;
 
@@ -5588,6 +5597,104 @@ declare function classifyChallenge(challenge: X402Challenge, opts: {
     schemes: readonly PaymentScheme[];
 }): ChallengeTriage;
 
+/**
+ * Self-description — make a PipRail 402 announce WHAT it is and HOW to pay it, to
+ * humans, AI agents, and crawlers alike, on BOTH schemes. PURE: a builder that turns
+ * the `accepts[]` a gate already resolved into an inert, additive metadata block; it
+ * does NO I/O and imports NO chain library (protocol layer — STANDARDS §1, viem-free).
+ *
+ * The block rides at `challenge.extensions.piprail`, ALONGSIDE the rejection
+ * `{ code, detail }` (the gate deep-merges so neither clobbers the other). x402 v2
+ * treats `extensions` as an opaque bag a standard client ignores, so this is
+ * purely-additive: the pay path, `accepts[]`, headers, and status stay byte-identical.
+ *
+ * Its whole point: even an `onchain-proof`-only endpoint that a stock x402 client
+ * CANNOT pay is no longer invisible — a stranger reads `sdk.install`, runs
+ * `npm i @piprail/sdk`, pastes the snippet, and pays. For the non-EVM families that
+ * have NO standard `exact` rail, this block is the ENTIRE interop story, so the
+ * `onchain-proof` instruction is deliberately chain-agnostic.
+ *
+ * NOT WIRED here — this is the pure builder (discoverability plan, Phase 1). The gate
+ * wires it into every challenge in Phase 5 (default-on, with a `selfDescribe:false`
+ * opt-out that restores the byte-identical default).
+ */
+
+/**
+ * The canonical PipRail brand strings — the SINGLE source of truth for the install
+ * command, the paste-ready snippet, and the docs links, read by the self-describe
+ * block here, and (later phases) the landing page, the `llms.txt` entry, and the
+ * agent guide. `<your-chain>` / `<this-url>` are deliberate placeholders — never guess
+ * the reader's chain or URL.
+ */
+declare const BRAND: {
+    readonly name: "PipRail";
+    readonly home: "https://piprail.com";
+    readonly docs: "https://docs.piprail.com";
+    readonly payDocs: "https://docs.piprail.com/paying";
+    readonly sdkInstall: "npm i @piprail/sdk";
+    readonly sdkSnippet: string;
+    readonly mcpRun: "npx -y @piprail/mcp";
+};
+/**
+ * One payable rail as the self-describe block presents it — the static, agent- and
+ * human-readable view of an `accepts[]` entry (no nonce; this is long-lived metadata).
+ */
+interface SelfDescribeRail {
+    scheme: 'onchain-proof' | 'exact';
+    network: string;
+    asset: string;
+    payTo: string;
+    /** Amount in the token's base units (already scaled by decimals). */
+    amount: string;
+    /** Human-readable amount, e.g. "0.01", when the gate resolved one. */
+    amountFormatted?: string;
+    symbol?: string;
+    /** A one-line instruction for paying THIS rail — chain-agnostic for `onchain-proof`. */
+    how: string;
+}
+/** The `extensions.piprail` self-description block. Inert, purely-additive metadata. */
+interface SelfDescription {
+    name: 'PipRail';
+    protocol: 'x402';
+    version: '2';
+    /** One sentence: what this endpoint is. */
+    what: string;
+    /** Every rail the 402 offers, in the same order as `accepts[]`. */
+    pay: SelfDescribeRail[];
+    /** How to pay programmatically with the SDK. */
+    sdk: {
+        install: string;
+        snippet: string;
+    };
+    /** How to pay via the MCP server (for AI agents). */
+    mcp: {
+        run: string;
+        tool: string;
+    };
+    docs: {
+        home: string;
+        agents: string;
+        pay: string;
+    };
+    /** Where the open discovery artifacts live on this origin. */
+    discovery: {
+        openapi: string;
+        wellKnown: string;
+    };
+    /** A one-line human summary (the gate sets it from `describeChallenge`). */
+    instruction?: string;
+}
+/**
+ * Build the `extensions.piprail` self-describe block from a challenge's resolved
+ * `accepts[]`. PURE — every rail is derived from data the gate already has (no new
+ * data, no I/O). `instruction` is the optional one-line human summary the gate computes
+ * via `describeChallenge` (in `render.ts`) and passes in.
+ */
+declare function buildSelfDescription(input: {
+    accepts: X402AnyAccept[];
+    instruction?: string;
+}): SelfDescription;
+
 /**
  * Discovery — make a gated resource FINDABLE, by emitting the open-standard
  * artifacts a crawler/index reads. PURE: this file turns the config a gate
@@ -5670,6 +5777,28 @@ interface ManifestInput {
 }
 /** What `x-generator` stamps when attribution is on — see {@link ManifestInput.attribution}. */
 declare const GENERATOR = "@piprail/sdk \u00B7 https://piprail.com";
+/**
+ * The "powered by" marker for the `x-powered-by` HTTP header — the response-side twin of the
+ * `/openapi.json` {@link GENERATOR} stamp. Inert metadata; opt out with `attribution:false`.
+ * **ASCII-only on purpose:** this is an HTTP header value, and Node's `setHeader` writes header
+ * values as latin1 — a non-ASCII separator (e.g. `·` U+00B7) would arrive mangled (`·`) and is
+ * RFC-7230-discouraged. {@link GENERATOR} keeps its `·` because it only lands in UTF-8 JSON bodies.
+ */
+declare const POWERED_BY = "PipRail x402 | https://piprail.com";
+/**
+ * Machine-readable discovery pointers for a gated endpoint's HTTP responses — a `Link` header
+ * (RFC 8288) pointing crawlers/agents at the discovery docs, plus a tasteful `x-powered-by`
+ * marker. Spread the result into BOTH the 402 challenge response AND the 200 settlement
+ * response, so a payer / agent / crawler learns what served them on every hit (this is also
+ * how the 200 "receipt" self-advertises — no change to the `X402Receipt` body needed). PURE —
+ * returns a header bag the merchant sets; the SDK serves nothing. `attribution:false` omits
+ * `x-powered-by` (parity with the `x-generator` opt-out on the OpenAPI doc). If you already set
+ * a `Link` header, comma-merge it with this one rather than blindly spreading (object spread
+ * would replace it).
+ */
+declare function discoveryHeaders(opts?: {
+    attribution?: boolean;
+}): Record<string, string>;
 /** A minimal, valid OpenAPI 3.1 document carrying `x-payment-info` per paid op. */
 interface OpenApiDocument {
     openapi: '3.1.0';
@@ -5940,6 +6069,17 @@ interface RequirePaymentOptions {
      * challenge byte-identical to before.
      */
     discovery?: boolean | DiscoveryDescriptor;
+    /**
+     * Self-describe every 402 — stamp an `extensions.piprail` block (identity · per-rail
+     * how-to-pay · `npm i @piprail/sdk` + snippet · MCP · docs + discovery pointers) so the
+     * instant any human, AI agent, or crawler lands on this endpoint — even the default
+     * `onchain-proof` scheme a stock x402 client can't pay — it knows what it is and how to
+     * pay it. **Default `true`.** It is purely-additive metadata a standard client ignores
+     * (the spec treats `extensions` as opaque), so the pay path, `accepts[]`, headers, and
+     * status are byte-identical. Set `false` to omit the block entirely (the literal
+     * byte-identical default of before this feature). See {@link buildSelfDescription}.
+     */
+    selfDescribe?: boolean;
 }
 type VerifyPaymentResult = {
     kind: 'paid';
@@ -6003,6 +6143,13 @@ interface PaymentGate {
      * discovery metadata is long-lived. Read-only — moves nothing on-chain.
      */
     describe(resourceUrl?: string): Promise<ResourceDescription>;
+    /**
+     * Render a self-describing HTML page for a challenge — for the HUMAN who opens the gated
+     * URL in a browser. Pass the challenge you already built with {@link PaymentGate.challenge};
+     * serve the result with `content-type: text/html` when the request's `Accept` is `text/html`.
+     * The SDK never serves it itself (headless by charter). Agents/crawlers keep the JSON 402.
+     */
+    landingPage(challenge: X402Challenge): string;
 }
 /**
  * Framework-agnostic core. Build one gate per gated resource and reuse it
@@ -6062,6 +6209,28 @@ interface FacilitatorPaymentRequirements {
     maxTimeoutSeconds: number;
     extra: Record<string, unknown>;
 }
+/** One (scheme, network) pair a facilitator's `GET /supported` advertises. */
+interface FacilitatorSupportedKind {
+    scheme: string;
+    /** As the facilitator reports it — a CAIP-2 id or a slug. */
+    network: string;
+    /** The fee-payer pubkey when the kind carries one (SVM rails). */
+    feePayer?: string;
+}
+/**
+ * Parse a facilitator `/supported` body into its advertised (scheme, network) kinds.
+ * PURE + tolerant: a malformed body yields `[]`. Mirrors the `{ kinds: [...] }` shape
+ * {@link fetchFacilitatorFeePayer} reads. Useful for verifying coverage before wiring a gate,
+ * and for generating the coverage doc from live reads.
+ */
+declare function parseFacilitatorSupported(body: unknown): FacilitatorSupportedKind[];
+/**
+ * Read a facilitator's LIVE coverage from `GET /supported`. Best-effort + bounded (an
+ * `AbortController` timeout): NEVER throws — returns `[]` on any failure (same posture as
+ * {@link fetchFacilitatorFeePayer}). Lets an operator/agent ask "does this facilitator
+ * cover my network?" before wiring a gate. Pure `fetch`, no chain libraries (STANDARDS §1).
+ */
+declare function facilitatorCoverage(url: string, timeoutMs?: number): Promise<FacilitatorSupportedKind[]>;
 /** A merchant-chosen facilitator: its base URL + optional per-request auth headers. */
 interface FacilitatorConfig {
     /** Base URL, e.g. 'https://x402.org/facilitator' (trailing slash stripped). */
@@ -6094,6 +6263,51 @@ interface SettleViaFacilitatorInput extends FacilitatorConfig {
  */
 declare function settleViaFacilitator(input: SettleViaFacilitatorInput): Promise<VerifyResult>;
 
+/**
+ * Facilitator coverage — the honest, chain-agnostic DATA map of which third-party x402
+ * facilitators settle the `exact` scheme on which networks. PURE DATA: imports only the
+ * `Caip2` type from `x402.ts` — zero chain libraries (protocol layer, STANDARDS §1).
+ *
+ * Why it exists: the `exact: true` shorthand (discoverability plan, Phase 7) and an
+ * operator picking a facilitator both need to know "is there a known KEYLESS facilitator
+ * for my chain?" — WITHOUT a hosted registry (charter: no backend). This map is the SEED;
+ * the live truth is `facilitatorCoverage(url)` in `facilitator.ts`, which reads a
+ * facilitator's `GET /supported`. The map is grown ONLY from a verified `/supported`
+ * read — every entry carries a dated verification comment, never a guess.
+ */
+
+/** One facilitator known to settle `exact` on a given network. */
+interface KnownFacilitator {
+    /** Base URL (no trailing slash), e.g. `https://facilitator.payai.network`. */
+    url: string;
+    /** True when it needs NO API key — buyer AND merchant pay zero gas (the facilitator sponsors it). */
+    keyless: boolean;
+    /** The x402 schemes it settles (today only `exact`). */
+    schemes: ReadonlyArray<'exact'>;
+    /** The exact transfer methods it can settle on this network. */
+    settles: ReadonlyArray<'eip3009' | 'permit2' | 'svm'>;
+    /** A short human note (who it is / caveat). */
+    note?: string;
+}
+/**
+ * Seed map: CAIP-2 network → facilitators that settle `exact` there. Deliberately
+ * CONSERVATIVE — only endpoint-verified entries. Extend it only after a live
+ * `facilitatorCoverage()` read confirms a new (facilitator, network) pair. A merchant on
+ * a network not listed here passes an explicit `exact: { settle: { facilitator } }`.
+ *
+ * NOTE: `x402.org/facilitator` is intentionally ABSENT — it is a Base **Sepolia** testnet
+ * facilitator (verified), not a mainnet rail; seeding it would be a false coverage claim.
+ */
+declare const KNOWN_FACILITATORS: Readonly<Record<Caip2, ReadonlyArray<KnownFacilitator>>>;
+/** Known facilitators for a network — an empty array when none is seeded. */
+declare function knownFacilitatorsFor(network: Caip2): ReadonlyArray<KnownFacilitator>;
+/**
+ * The first KEYLESS facilitator that settles `exact` on `network` (optionally for a
+ * specific transfer `method`). Returns `undefined` when none is known — the `exact: true`
+ * shorthand branches on that to throw a coverage-specific guidance error.
+ */
+declare function firstKeylessFacilitator(network: Caip2, method?: 'eip3009' | 'permit2' | 'svm'): KnownFacilitator | undefined;
+
 /**
  * Reliable receipt delivery — the durable webhook a stateless gate can't be.
  *
@@ -6793,4 +7007,28 @@ declare const PERMIT2_WITNESS_TYPES: {
     }];
 };
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+/**
+ * Landing page — a tiny, self-contained HTML representation of a 402, for the HUMAN
+ * who opens a gated URL in a browser (agents/crawlers still get the unchanged JSON 402).
+ * PURE string templating; imports only the `SelfDescription` type — zero I/O, zero chain
+ * libraries (protocol layer, STANDARDS §1).
+ *
+ * The SDK NEVER serves this itself (it's headless by charter). The merchant opts in by
+ * branching on the request's `Accept` header in their own handler and returning this
+ * string with `content-type: text/html`. See `gate.landingPage(challenge)`.
+ *
+ * SECURITY: every interpolated field is HTML-escaped (a `payTo` / instruction can be
+ * merchant- or rail-influenced) — global rule: escape all user-/data-influenced content.
+ */
+
+/**
+ * Render a self-describing HTML 402 landing page from a {@link SelfDescription}. Leads with the
+ * one-line instruction and a prominent CAUTION — payment must go through an x402 client; a manual
+ * send to the address won't unlock the resource and isn't matched to the request (it lands in the
+ * merchant's wallet uncredited). Then the primary "How to pay" (the `npm i @piprail/sdk` install +
+ * paste-ready snippet + MCP command), and finally the per-rail "Payment details" table (scheme ·
+ * chain · amount · settles-to) for transparency. Fully static — no script, no external asset.
+ */
+declare function renderLandingPage(sd: SelfDescription): string;
+
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, BRAND, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeRail, type SelfDescription, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSelfDescription, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, firstKeylessFacilitator, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, knownFacilitatorsFor, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseFacilitatorSupported, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };