@piprail/sdk 1.22.1 → 1.24.0

package/CHANGELOG.md

@@ -4,6 +4,88 @@ All notable changes to `@piprail/sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [1.24.0] — 2026-06-14 — multi-chain buying (one buyer, a wallet per chain)
+
+### Added — pay a 402 on whichever chain it asks for
+
+- **`MultiChainPayer`** — a `PipRailClient` is bound to ONE chain + ONE wallet (an EVM key can't sign a
+  Solana tx). `MultiChainPayer.fromWallets({ wallets: { base: { privateKey }, solana: { secretKey }, … }, policy })`
+  carries one wallet per chain and exposes a single `fetch`/`get`/`post`/`planPayment`/`canAfford`/`quote`/
+  `discover`/`register`/`spent`/`budget`. On a 402 it surveys every funded chain and pays the FIRST chain
+  you listed that can actually settle — through each client's own spend policy, `onBeforePay`, retries, and
+  replay-protection. No price oracle, no backend, no custody; across coins the order you list the chains is
+  the preference (within a chain, the cheapest-gas rail). Also `new MultiChainPayer([...clients])` for full
+  control (e.g. custom-EVM viem `Chain`s). `schemes` (incl. the gasless `exact` rail) propagates to every
+  chain's client.
+- **`fetchAcross(clients, url, init?)`** — the EXECUTION counterpart to `planAcross`: plan across an array
+  of single-chain clients and pay, on its owning client, the rail `planAcross` reports as `best` (the first
+  funded chain that can settle). Throws `PaymentDeclinedError` with a merged, per-chain funding hint when
+  no chain can settle.
+- **`PayingClient`** — the shared read-+-pay interface `paymentTools` now accepts; both `PipRailClient` and
+  `MultiChainPayer` satisfy it, so the agent toolkit (and the MCP) wrap either unchanged.
+- **`piprail_register` agent tool** gains optional `network` + `asset` params, so a multi-chain agent can
+  advertise a listing on a specific chain instead of defaulting to the first wallet's chain.
+
+### Changed
+
+- **Cross-chain `best` selection is now your PREFERENCE order, not raw gas magnitude.** `planAcross` /
+  `fetchAcross` no longer compare gas fees across different native coins (base units aren't comparable —
+  e.g. EVM wei vs Solana lamports — and there's no oracle), which previously let a small-base-unit coin
+  win regardless of real cost. They now pay the FIRST chain you list that can settle (within a chain, the
+  cheapest-gas rail still wins) — matching the documented contract. Single-chain `PipRailClient` ranking is
+  unchanged.
+- **`planAcross` now propagates a TOTAL outage.** If EVERY client fails to reach the resource it throws
+  (like a single client) instead of returning `null` — so `canAfford`/`quote` can't report a false
+  "affordable"/"not-gated". A single chain being down still just drops that chain.
+- **Clearer multi-chain decline message.** When no funded chain can settle, `planAcross`'s `fundingHint`
+  (and the `PaymentDeclinedError` `fetchAcross` throws) now names EVERY funded chain's own blocker — "top up
+  X USDC on base · add ~Y POL gas on polygon" — instead of only the first. Chains the 402 never offered are
+  dropped as noise when another chain is close; if none of your chains are offered, it says where the 402
+  IS payable. Per-rail `blockers`/`warnings` stay machine-readable for agents that branch programmatically.
+
+Single-chain `PipRailClient` behaviour is byte-identical. Examples: `examples/multi-chain` (routing + a
+live gasless-`exact` BNB Permit2 settlement through `MultiChainPayer`).
+
+## [1.23.0] — 2026-06-14 — self-describing endpoints + discovery reach
+
+### Added — self-describing, more discoverable endpoints (discoverability plan: Phases 1, 2, 4, 5)
+
+- **Self-describing 402s, ON by default.** Every challenge a gate builds now carries an
+  `extensions.piprail` block — identity, per-rail how-to-pay, `npm i @piprail/sdk` + a paste-ready
+  snippet, the MCP command, and docs + discovery pointers — so any human, AI agent, or crawler that
+  lands on a gated endpoint (even the `onchain-proof` scheme a stock x402 client can't pay) knows what
+  it is and how to pay it. **Purely-additive** metadata in the spec-opaque `extensions` bag, and it
+  rides in the response **body** only — the base64 `payment-required` **header stays slim** (just
+  `accepts[]` + a small `bazaar`/rejection block), so the header, pay path, `accepts[]`, and status are
+  byte-identical (a rejection's `{code,detail}` are deep-merged as siblings and still win). Opt out with
+  `requirePayment({ selfDescribe: false })`. New exports: `buildSelfDescription`, `describeChallenge`, `BRAND`.
+- **Human landing page + HTTP pointers.** `gate.landingPage(challenge)` / `renderLandingPage()` render a
+  tiny, HTML-escaped 402 page for a browser (serve it on `Accept: text/html`; agents/crawlers keep the
+  JSON 402). It leads with **how to pay** and a clear **caution** that a manual send to the address won't
+  unlock the resource (pay via an x402 client — no custody, no manual-payment desk). `discoveryHeaders()`
+  + `POWERED_BY` emit a `Link` (rel `service-desc` / `x402-discovery`) + `x-powered-by` header bag to
+  spread on every response. The SDK serves nothing — the merchant does.
+- **Facilitator-coverage map.** `KNOWN_FACILITATORS` (+ `knownFacilitatorsFor` /
+  `firstKeylessFacilitator`) — shipped data of which keyless facilitators settle `exact` on which
+  networks (seeded: PayAI on Base + Solana, dated-verified). `facilitatorCoverage(url)` /
+  `parseFacilitatorSupported(body)` read a facilitator's live `GET /supported` (best-effort, never throw).
+- **Agent guide** gained a "landing cold — read the self-description" section (surfaced over the MCP).
+
+All of the above is additive + opt-in; the zero-config pay path is byte-identical to before. New pure
+modules (`selfdescribe.ts`, `landing.ts`, `facilitators.ts`) join the viem-free protocol-layer grep.
+
+### Removed
+- **`base-sepolia` (84532) testnet entry** from `EXACT_NETWORK_SLUGS` and the Permit2 proxy chain-id set
+  — mainnets only, no testnet presets (it was dead reference data; nothing settles on a testnet).
+
+### Fixed
+- **`x-powered-by` is now ASCII** (`PipRail x402 | https://piprail.com`) — the previous non-ASCII middot
+  mangled to `·` over Node's latin1 header transport. `GENERATOR` keeps its `·` (JSON body only).
+- **`renderLandingPage` never throws** on a rail missing `amount`/`asset` (matches the module's
+  never-throw contract).
+- **`fetchFacilitatorFeePayer` matches the network normalized** (CAIP-2 *or* slug) so a slug-reporting
+  facilitator's Solana exact fee-payer is found instead of silently dropped.
+
 ## [1.22.1] — 2026-06-13 — docs: community links + integrations signposting
 
 Docs-only patch — **no code change** (the SDK is byte-identical to 1.22.0). Refreshes the README:
@@ -982,6 +1064,7 @@ straight into your wallet. The API is small and self-contained.
   to your wallet; PipRail never holds funds.
 - `viem ^2.21` is a peer dependency. Node 20+ or a modern browser.
 
+[1.24.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.15.1]: https://www.npmjs.com/package/@piprail/sdk
 [1.15.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.14.0]: https://www.npmjs.com/package/@piprail/sdk

package/README.md

@@ -36,6 +36,33 @@ const client = new PipRailClient({ chain: 'base', wallet: { privateKey: process.
 const res = await client.fetch('https://api.example.com/report') // hits the 402, pays it, retries with proof
 ```
 
+## Pay across chains — one buyer, a wallet per chain
+
+A client is bound to one chain (an EVM key can't sign a Solana tx). To pay a 402
+on **whatever chain it asks for**, give a `MultiChainPayer` one wallet per chain —
+it surveys every chain you hold and pays the **first one you listed** that can settle
+(your preference; within a chain, the cheapest-gas rail — there's no oracle to compare
+gas across coins):
+
+```ts
+import { MultiChainPayer } from '@piprail/sdk'
+
+const payer = MultiChainPayer.fromWallets({
+  wallets: {
+    base:   { privateKey: process.env.EVM_KEY },     // one EVM key works on every EVM chain
+    solana: { secretKey:  process.env.SOLANA_KEY },
+    xrpl:   { seed:       process.env.XRPL_SEED },
+  },
+  policy: { maxAmount: '1.00', maxTotal: '10.00', tokens: ['USDC', 'USDT'] }, // one budget, every chain
+})
+
+await payer.planPayment(url) // read-only: every chain ranked, payable-first in your listed order
+const res = await payer.get(url) // pays on the first chain that can settle — same spend policy, no manual routing
+```
+
+Built on `planAcross` / `fetchAcross` (the same composable primitives, for when you
+already hold an array of clients). See [`examples/multi-chain`](../examples/multi-chain).
+
 The same app can **take** payments and **make** them. → [Making payments](https://docs.piprail.com/making-payments/piprail-client/)
 
 ---
@@ -46,7 +73,7 @@ The same app can **take** payments and **make** them. → [Making payments](http
 |---|---|
 | **[Getting started](https://docs.piprail.com/getting-started/introduction/)** | Install · quickstart · how it works |
 | **[Accepting payments](https://docs.piprail.com/accepting-payments/require-payment-and-gate/)** | `requirePayment` · `createPaymentGate` · the `exact` rail |
-| **[Making payments](https://docs.piprail.com/making-payments/piprail-client/)** | `PipRailClient` · `quote` · `estimateCost` · `planPayment` · auto-route |
+| **[Making payments](https://docs.piprail.com/making-payments/piprail-client/)** | `PipRailClient` · `quote` · `estimateCost` · `planPayment` · auto-route · `MultiChainPayer` |
 | **[Spend controls](https://docs.piprail.com/spend-controls/payment-policy/)** | Budgets · time envelope · the spend ledger |
 | **[Agent toolkit](https://docs.piprail.com/agent-toolkit/payment-tools/)** | `paymentTools` · the agent guide · NL renderers |
 | **[Discovery](https://docs.piprail.com/discovery/discover-and-register/)** | Find & be found on the open x402 indexes ($0, no backend) |