@piprail/sdk 1.22.1 → 1.24.0

package/dist/index.js

@@ -511,7 +511,6 @@ import {
 var EXACT_NETWORK_SLUGS = {
   ethereum: 1,
   base: 8453,
-  "base-sepolia": 84532,
   arbitrum: 42161,
   optimism: 10,
   polygon: 137,
@@ -983,8 +982,6 @@ var PERMIT2_PROXY_CHAIN_IDS = /* @__PURE__ */ new Set([
   // Ethereum
   8453,
   // Base
-  84532,
-  // Base Sepolia
   42161,
   // Arbitrum
   10,
@@ -3496,6 +3493,33 @@ function rankOptions(options) {
     return 0;
   });
 }
+function rankAcross(plans) {
+  const rank = { payable: 0, unknown: 1, blocked: 2 };
+  return plans.flatMap((p) => p.options).sort((a, b) => rank[a.state] - rank[b.state]);
+}
+async function planEachClient(clients, url, init) {
+  const settled = await Promise.allSettled(clients.map((c) => c.planPayment(url, init)));
+  const live = [];
+  let anyReached = false;
+  let firstError;
+  settled.forEach((s, i) => {
+    if (s.status === "fulfilled") {
+      anyReached = true;
+      if (s.value != null) live.push({ client: clients[i], plan: s.value });
+    } else if (firstError === void 0) {
+      firstError = s.reason;
+    }
+  });
+  if (live.length === 0 && !anyReached) {
+    throw firstError ?? new Error("planAcross: every client failed to reach the resource.");
+  }
+  return live;
+}
+function mergeDeclineHint(plans) {
+  const actionable = plans.filter((p) => p.options.length > 0 && p.fundingHint).map((p) => p.fundingHint);
+  const chosen = actionable.length ? actionable : plans.map((p) => p.fundingHint).filter(Boolean);
+  return chosen.length ? [...new Set(chosen)].join(" \xB7 ") : null;
+}
 function buildFundingHint(options, chainLabel) {
   if (options.length === 0) return null;
   const target = [...options].sort((a, b) => a.blockers.length - b.blockers.length)[0];
@@ -3522,10 +3546,10 @@ function buildFundingHint(options, chainLabel) {
   return parts.length ? `Can't settle on ${chainLabel}: ${parts.join(" and ")} (to pay ${target.quote.amountFormatted} ${sym}).` : `Can't settle on ${chainLabel} for ${target.quote.amountFormatted} ${sym}.`;
 }
 async function planAcross(clients, url, init) {
-  const plans = await Promise.all(clients.map((c) => c.planPayment(url, init).catch(() => null)));
-  const live = plans.filter((p) => p != null);
+  if (clients.length === 0) return null;
+  const live = (await planEachClient(clients, url, init)).map((p) => p.plan);
   if (live.length === 0) return null;
-  const options = rankOptions(live.flatMap((p) => p.options));
+  const options = rankAcross(live);
   const best = options.find((o) => o.state === "payable") ?? null;
   const status = best ? "ready" : options.some((o) => o.state === "unknown") ? "unknown" : "blocked";
   return {
@@ -3535,10 +3559,25 @@ async function planAcross(clients, url, init) {
     payable: best !== null,
     best,
     options,
-    // First non-null hint across clients — each already names its chain.
-    fundingHint: best ? null : live.map((p) => p.fundingHint).find(Boolean) ?? null
+    // Merge EVERY funded chain's blocker into one clear sentence (not just the first) —
+    // see mergeDeclineHint. `null` when a rail is payable.
+    fundingHint: best ? null : mergeDeclineHint(live)
   };
 }
+async function fetchAcross(clients, url, init) {
+  if (clients.length === 0) {
+    throw new TypeError("fetchAcross needs at least one PipRailClient.");
+  }
+  const live = await planEachClient(clients, url, init);
+  if (live.length === 0) return clients[0].fetch(url, init);
+  const best = rankAcross(live.map((p) => p.plan)).find((o) => o.state === "payable");
+  if (!best) {
+    const hint = mergeDeclineHint(live.map((p) => p.plan));
+    throw new PaymentDeclinedError(hint || "No funded chain can settle this payment right now.");
+  }
+  const owner = live.find((p) => p.plan.options.includes(best)).client;
+  return owner.fetch(url, { ...init ?? {}, autoRoute: true });
+}
 function railOnNetwork(rail, matches) {
   const n = normalizeNetwork(rail.network);
   return !n.includes(":") || matches(n);
@@ -3604,6 +3643,229 @@ async function readInvalidReason(response) {
   return null;
 }
 
+// src/payer.ts
+var MultiChainPayer = class _MultiChainPayer {
+  _clients;
+  /**
+   * Wrap an explicit, ordered set of single-chain clients — use this when a client
+   * needs full control (e.g. a custom EVM chain configured by a viem `Chain`). The
+   * ORDER is your chain preference: across chains the first that can settle wins. Pass
+   * at MOST one client per chain — two clients on the SAME network would double-count in
+   * `spent()`/`budget()` and waste a plan round-trip (`fromWallets` can't produce this).
+   * For the common case, prefer {@link MultiChainPayer.fromWallets}.
+   */
+  constructor(clients) {
+    if (clients.length === 0) {
+      throw new TypeError("MultiChainPayer needs at least one PipRailClient.");
+    }
+    this._clients = [...clients];
+  }
+  /**
+   * Build one client per funded chain from a `{ chain → wallet }` map — the
+   * ergonomic path. The shared `policy`/`schemes`/`onBeforePay`/`onEvent` apply to
+   * every client; `rpcUrls` are matched per chain. Iteration order of `wallets` is
+   * the chain preference.
+   *
+   * ```ts
+   * const payer = MultiChainPayer.fromWallets({
+   *   wallets: {
+   *     base:    { privateKey: process.env.EVM_KEY! },
+   *     solana:  { secretKey:  process.env.SOLANA_SECRET! },
+   *     xrpl:    { seed:       process.env.XRPL_SEED! },
+   *   },
+   *   policy: { maxAmount: '1.00', maxTotal: '20.00', tokens: ['USDC', 'USDT'] },
+   * })
+   * const res = await payer.get('https://api.example.com/paid')  // pays on the first funded chain that can settle
+   * ```
+   */
+  static fromWallets(opts) {
+    const entries = Object.entries(opts.wallets);
+    if (entries.length === 0) {
+      throw new TypeError("MultiChainPayer.fromWallets needs at least one wallet.");
+    }
+    const clients = entries.map(
+      ([chain, wallet]) => new PipRailClient({
+        chain,
+        wallet,
+        ...opts.policy ? { policy: opts.policy } : {},
+        ...opts.schemes ? { schemes: opts.schemes } : {},
+        ...opts.rpcUrls?.[chain] ? { rpcUrl: opts.rpcUrls[chain] } : {},
+        ...opts.onBeforePay ? { onBeforePay: opts.onBeforePay } : {},
+        ...opts.onEvent ? { onEvent: opts.onEvent } : {},
+        ...opts.maxPaymentRetries != null ? { maxPaymentRetries: opts.maxPaymentRetries } : {},
+        ...opts.retryTimeoutMs != null ? { retryTimeoutMs: opts.retryTimeoutMs } : {}
+      })
+    );
+    return new _MultiChainPayer(clients);
+  }
+  /** The underlying single-chain clients, in preference order. Reach for one of
+   *  these for chain-specific reads (`estimateCost`, `discoverySigner`, per-chain
+   *  `budget()`) that don't make sense merged. */
+  get clients() {
+    return this._clients;
+  }
+  /** Plan a 402 across every funded chain — merged + ranked payable-first. `null`
+   *  when the URL needs no payment. (Delegates to {@link planAcross}.) */
+  planPayment(url, init) {
+    return planAcross(this._clients, url, init);
+  }
+  /** Can ANY funded chain settle this URL right now? (A free resource is trivially
+   *  "affordable".) No funds move. */
+  async canAfford(url, init) {
+    const plan = await this.planPayment(url, init);
+    return plan == null ? true : plan.payable;
+  }
+  /** Price a gated URL across funded chains — the chosen rail's quote (the first
+   *  funded chain that can settle), else the first offered rail's. `null` when the URL
+   *  needs no payment. When it IS
+   *  gated but none of your chains are offered, surfaces the same informative
+   *  `NoCompatibleAcceptError` a single client would (it names the chains the 402 is
+   *  payable on) rather than a misleading `null`. No funds move. */
+  async quote(url, init) {
+    const plan = await this.planPayment(url, init);
+    if (plan == null) return null;
+    const opt = plan.best ?? plan.options[0];
+    if (opt) return opt.quote;
+    return this._clients[0].quote(url, init);
+  }
+  /** Pay the first funded chain (in your listed order) that can settle this URL.
+   *  Delegates to {@link fetchAcross} — full policy / approval / retry / replay path on
+   *  the owning client. The owner re-reads balances at pay time, so the rail paid is the
+   *  surfaced `best` on a best-effort basis (it can pick another rail on the SAME chain,
+   *  or decline, if balances shift between plan and pay). PROBES the URL with `init`
+   *  (method + body) per client — prefer GET / idempotent requests. */
+  fetch(url, init) {
+    return fetchAcross(this._clients, url, init);
+  }
+  /** GET that auto-pays across chains. */
+  get(url, init) {
+    return this.fetch(url, { ...init ?? {}, method: "GET" });
+  }
+  /**
+   * POST that auto-pays across chains. `body` is a string/FormData/URLSearchParams/
+   * ArrayBuffer/Blob (sent as-is) or a plain object (serialised as JSON) — mirrors
+   * {@link PipRailClient.post}.
+   */
+  post(url, body, init) {
+    const headers = new Headers(init?.headers);
+    let payload;
+    if (body === void 0 || body === null) {
+      payload = void 0;
+    } else if (isBodyInit(body)) {
+      payload = body;
+    } else if (typeof body === "object") {
+      payload = JSON.stringify(body);
+      if (!headers.has("content-type")) headers.set("content-type", "application/json");
+    } else {
+      payload = String(body);
+    }
+    return this.fetch(url, { ...init ?? {}, method: "POST", headers, body: payload });
+  }
+  /**
+   * Find payable resources across every funded chain. With the default
+   * `network: 'self'`, each chain's own results are merged + deduped by URL (so
+   * "self" means "any chain I can pay"). A network-scoped query (a CAIP-2 id or
+   * `'any'`) is chain-independent, so one client answers it. Never throws for a
+   * read problem; moves no funds.
+   */
+  async discover(opts = {}) {
+    if (opts.network && opts.network !== "self") {
+      return this._clients[0].discover(opts);
+    }
+    const perChain = await Promise.all(
+      this._clients.map((c) => c.discover({ ...opts, network: "self" }).catch(() => []))
+    );
+    const seen = /* @__PURE__ */ new Set();
+    const merged = [];
+    for (const r of perChain.flat()) {
+      if (seen.has(r.resource)) continue;
+      seen.add(r.resource);
+      merged.push(r);
+    }
+    return merged;
+  }
+  /** List a resource YOU run on the open indexes. Registration is a merchant action
+   *  independent of which chain you pay FROM, so it goes through your first chain's
+   *  client; pass `opts.network` to advertise a specific chain. Moves no funds. */
+  register(url, opts = {}) {
+    return this._clients[0].register(url, opts);
+  }
+  /** Aggregate spend across every chain — counts summed; per-(network,asset) rows
+   *  and records concatenated (no cross-chain collisions, never a cross-token sum). */
+  spent() {
+    const summaries = this._clients.map((c) => c.spent());
+    return {
+      count: summaries.reduce((n, s) => n + s.count, 0),
+      byAsset: summaries.flatMap((s) => s.byAsset),
+      records: summaries.flatMap((s) => s.records)
+    };
+  }
+  /** A merged budget view: every chain's per-(network,asset) remaining rows, plus the
+   *  MOST-RESTRICTIVE session time envelope across chains (the soonest deadline wins).
+   *  Mirrors {@link PipRailClient.budget}'s shape so the agent toolkit reads it
+   *  unchanged; per-chain session detail is on each `clients[i].budget()`. */
+  budget() {
+    const budgets = this._clients.map((c) => c.budget());
+    const session = budgets.map((b) => b.session).reduce((soonest, s) => {
+      if (soonest.secondsRemaining == null) return s;
+      if (s.secondsRemaining == null) return soonest;
+      return s.secondsRemaining < soonest.secondsRemaining ? s : soonest;
+    });
+    return { session, byAsset: budgets.flatMap((b) => b.byAsset) };
+  }
+};
+function isBodyInit(value) {
+  if (typeof value === "string") return true;
+  if (value instanceof ArrayBuffer) return true;
+  if (ArrayBuffer.isView(value)) return true;
+  if (typeof URLSearchParams !== "undefined" && value instanceof URLSearchParams) return true;
+  if (typeof FormData !== "undefined" && value instanceof FormData) return true;
+  if (typeof Blob !== "undefined" && value instanceof Blob) return true;
+  return false;
+}
+
+// src/selfdescribe.ts
+var BRAND = {
+  name: "PipRail",
+  home: "https://piprail.com",
+  docs: "https://docs.piprail.com",
+  payDocs: "https://docs.piprail.com/paying",
+  sdkInstall: "npm i @piprail/sdk",
+  sdkSnippet: "import { PipRailClient } from '@piprail/sdk'\nconst client = new PipRailClient({ chain: '<your-chain>', wallet })\nawait client.fetch('<this-url>')",
+  mcpRun: "npx -y @piprail/mcp"
+};
+var WHAT = 'This is an x402 "402 Payment Required" endpoint. Pay one of the offered rails to access it.';
+function howFor(scheme) {
+  return scheme === "exact" ? "Standard x402 exact rail \u2014 sign an EIP-3009 / Permit2 / SVM authorization; any stock x402 client (e.g. @x402/fetch) can pay this." : "Pay this amount on-chain to payTo, then resubmit with a payment-signature header carrying the proof ref + nonce. Easiest with @piprail/sdk (see sdk.install).";
+}
+function railOf(a) {
+  const extra = a.extra ?? {};
+  return {
+    scheme: a.scheme,
+    network: a.network,
+    asset: a.asset,
+    payTo: a.payTo,
+    amount: a.amount,
+    ...extra.amountFormatted ? { amountFormatted: extra.amountFormatted } : {},
+    ...extra.symbol ? { symbol: extra.symbol } : {},
+    how: howFor(a.scheme)
+  };
+}
+function buildSelfDescription(input) {
+  return {
+    name: "PipRail",
+    protocol: "x402",
+    version: "2",
+    what: WHAT,
+    pay: input.accepts.map(railOf),
+    sdk: { install: BRAND.sdkInstall, snippet: BRAND.sdkSnippet },
+    mcp: { run: BRAND.mcpRun, tool: "piprail_pay_request" },
+    docs: { home: BRAND.home, agents: BRAND.docs, pay: BRAND.payDocs },
+    discovery: { openapi: "/openapi.json", wellKnown: "/.well-known/x402" },
+    ...input.instruction ? { instruction: input.instruction } : {}
+  };
+}
+
 // src/render.ts
 function summarizePlan(plan) {
   if (plan == null) return "No payment required \u2014 the URL is not payment-gated.";
@@ -3644,6 +3906,18 @@ function formatSpendReport(summary) {
     (a) => `${a.totalFormatted} ${a.symbol ?? a.asset} on ${a.network} (${a.count} payment${a.count === 1 ? "" : "s"})`
   ).join("; ");
 }
+function describeChallenge(challenge) {
+  const first = challenge.accepts[0];
+  if (!first) {
+    return `${BRAND.name} x402 payment endpoint. Pay with @piprail/sdk (${BRAND.sdkInstall}). Docs: ${BRAND.home}.`;
+  }
+  const extra = first.extra ?? {};
+  const amount = extra.amountFormatted ?? first.amount;
+  const token = extra.symbol ?? first.asset;
+  const hasExact = challenge.accepts.some((a) => a.scheme === "exact");
+  const standard = hasExact ? "; or any standard x402 client (an exact rail is offered)" : "";
+  return `${BRAND.name} x402 payment endpoint \u2014 pay ${amount} ${token} on ${first.network} to ${first.payTo}. Programmatic: ${BRAND.sdkInstall} then client.fetch(url)${standard}. Docs: ${BRAND.home}.`;
+}
 
 // src/agentGuide.ts
 var PIPRAIL_AGENT_GUIDE = `# Paying with PipRail \u2014 the agent contract
@@ -3651,6 +3925,13 @@ var PIPRAIL_AGENT_GUIDE = `# Paying with PipRail \u2014 the agent contract
 You can pay for x402 "402 Payment Required" resources autonomously. Money moves
 straight from your wallet to the server; PipRail custodies nothing. Follow this.
 
+## Landing cold \u2014 read the self-description
+Every PipRail 402 self-describes. Read challenge.extensions.piprail for { name, what, pay[]
+(each rail's how-to-pay), sdk.install, mcp, docs } \u2014 never guess what an endpoint is. If your
+tooling can't pay a rail (e.g. a stock x402 client can't pay the onchain-proof scheme), the
+block says how: install @piprail/sdk (npm i @piprail/sdk) or run the MCP (npx -y @piprail/mcp)
+and pay with the tools below.
+
 ## The loop: quote \u2192 plan \u2192 pay
 1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and
    whether it is within your spend policy. No funds move. Use it to decide if a
@@ -3945,7 +4226,12 @@ function paymentTools(client) {
           url: { type: "string", description: "Full URL of the resource to list." },
           name: { type: "string", description: "Display name (defaults to the host)." },
           description: { type: "string", description: "What the resource offers." },
-          priceUsd: { type: "number", description: "Advertised price in USD (metadata)." }
+          priceUsd: { type: "number", description: "Advertised price in USD (metadata)." },
+          network: {
+            type: "string",
+            description: "Network slug to advertise, e.g. 'base' (defaults to the paying chain). Set it when registering from a multi-chain wallet so the listing names the right chain."
+          },
+          asset: { type: "string", description: "Payment asset symbol, e.g. 'USDC' (metadata)." }
         },
         required: ["url"],
         additionalProperties: false
@@ -3955,6 +4241,8 @@ function paymentTools(client) {
         if (typeof args.name === "string") opts.name = args.name;
         if (typeof args.description === "string") opts.description = args.description;
         if (typeof args.priceUsd === "number") opts.priceUsd = args.priceUsd;
+        if (typeof args.network === "string") opts.network = args.network;
+        if (typeof args.asset === "string") opts.asset = args.asset;
         const outcomes = await client.register(String(args.url), opts);
         return { outcomes };
       }
@@ -4011,6 +4299,13 @@ function classifyChallenge(challenge, opts) {
 
 // src/discovery.ts
 var GENERATOR = "@piprail/sdk \xB7 https://piprail.com";
+var POWERED_BY = "PipRail x402 | https://piprail.com";
+function discoveryHeaders(opts = {}) {
+  return {
+    link: '</openapi.json>; rel="service-desc", </.well-known/x402>; rel="x402-discovery"',
+    ...opts.attribution === false ? {} : { "x-powered-by": POWERED_BY }
+  };
+}
 function buildBazaarExtension(descriptor = {}) {
   const method = (descriptor.method ?? "GET").toUpperCase();
   const queryParams = descriptor.queryParams ?? {};
@@ -4090,6 +4385,57 @@ function buildX402DnsTxt(input) {
   };
 }
 
+// src/landing.ts
+function esc(s) {
+  return String(s ?? "").replace(
+    /[&<>"']/g,
+    (c) => c === "&" ? "&amp;" : c === "<" ? "&lt;" : c === ">" ? "&gt;" : c === '"' ? "&quot;" : "&#39;"
+  );
+}
+var STYLE = `:root{color-scheme:dark}
+*{box-sizing:border-box}
+body{margin:0;background:#0a0e0f;color:#e6edf0;font:16px/1.6 ui-sans-serif,system-ui,-apple-system,Inter,sans-serif}
+main{max-width:680px;margin:0 auto;padding:48px 24px}
+h1{font-size:1.6rem;margin:0 0 .25rem}
+.lede{color:#9fb0b5;margin:.25rem 0 2rem}
+h2{font-size:1rem;text-transform:uppercase;letter-spacing:.05em;color:#34d399;margin:2rem 0 .75rem}
+table{width:100%;border-collapse:collapse;font-size:.92rem}
+th,td{text-align:left;padding:.5rem .6rem;border-bottom:1px solid #1c2426;vertical-align:top}
+th{color:#9fb0b5;font-weight:600}
+code,pre{font-family:ui-monospace,JetBrains Mono,monospace;font-size:.85rem}
+pre{background:#11181a;border:1px solid #1c2426;border-radius:8px;padding:14px;overflow-x:auto;color:#cfe9df}
+a{color:#34d399}
+.mono{font-family:ui-monospace,monospace;word-break:break-all}
+.warn{margin:0 0 2rem;padding:14px 16px;border:1px solid #5a4a1f;background:#17130a;border-radius:8px;color:#e8d9a8;font-size:.92rem;line-height:1.55}
+.warn strong{color:#f5d77a}
+.muted{color:#5b6b6f;font-weight:400;text-transform:none;letter-spacing:0;font-size:.8rem}
+footer{margin-top:2.5rem;color:#5b6b6f;font-size:.8rem}`;
+function renderLandingPage(sd) {
+  const lede = esc(sd.instruction ?? sd.what);
+  const rows = sd.pay.map(
+    (r) => `<tr><td><code>${esc(r.scheme)}</code></td><td>${esc(r.network)}</td><td>${esc(r.amountFormatted ?? r.amount)} ${esc(r.symbol ?? r.asset)}</td><td class="mono">${esc(r.payTo)}</td></tr>`
+  ).join("");
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${esc(sd.name)} \xB7 x402 payment required</title>
+<style>${STYLE}</style>
+</head><body><main>
+<h1>402 \u2014 Payment Required</h1>
+<p class="lede">${lede}</p>
+<div class="warn"><strong>Pay with an x402 client \u2014 not by hand.</strong> This endpoint is paid programmatically: an x402 client (the ${esc(sd.name)} SDK or MCP below, or any x402-compatible wallet) makes the payment <em>and proves it</em>, which is what unlocks the resource. Sending funds straight to the address below from an ordinary wallet will reach the merchant but <strong>will NOT unlock this resource and won't be matched to your request</strong> \u2014 there is no custody and no manual-payment desk. Use one of the methods below.</div>
+<h2>How to pay</h2>
+<pre>${esc(sd.sdk.install)}</pre>
+<pre>${esc(sd.sdk.snippet)}</pre>
+<p>For AI agents (MCP): <code>${esc(sd.mcp.run)}</code> &rarr; tool <code>${esc(sd.mcp.tool)}</code></p>
+<h2>Payment details <span class="muted">\u2014 what the client pays, NOT a manual-send address</span></h2>
+<table><thead><tr><th>Scheme</th><th>Chain</th><th>Amount</th><th>Settles to</th></tr></thead>
+<tbody>${rows}</tbody></table>
+<p>Docs: <a href="${esc(sd.docs.pay)}">paying</a> &middot; <a href="${esc(sd.docs.home)}">${esc(sd.docs.home)}</a> &middot; <a href="${esc(sd.discovery.openapi)}">${esc(sd.discovery.openapi)}</a></p>
+<footer>Powered by ${esc(sd.name)} &middot; x402 &middot; no backend, no fee, settled straight to the merchant's wallet (no custody).</footer>
+</main></body></html>`;
+}
+
 // src/facilitator.ts
 async function fetchFacilitatorFeePayer(url, network, timeoutMs = 8e3) {
   const base2 = url.replace(/\/+$/, "");
@@ -4100,7 +4446,8 @@ async function fetchFacilitatorFeePayer(url, network, timeoutMs = 8e3) {
     if (!res.ok) return void 0;
     const body = await res.json();
     const kinds = Array.isArray(body?.kinds) ? body.kinds : [];
-    const kind = kinds.find((k) => k?.scheme === "exact" && k?.network === network);
+    const want = normalizeNetwork(network);
+    const kind = kinds.find((k) => k?.scheme === "exact" && normalizeNetwork(String(k?.network ?? "")) === want);
     const fp = kind?.extra?.feePayer;
     return typeof fp === "string" ? fp : void 0;
   } catch {
@@ -4109,6 +4456,33 @@ async function fetchFacilitatorFeePayer(url, network, timeoutMs = 8e3) {
     clearTimeout(timer);
   }
 }
+function parseFacilitatorSupported(body) {
+  const kinds = body?.kinds;
+  if (!Array.isArray(kinds)) return [];
+  const out = [];
+  for (const k of kinds) {
+    if (!k || typeof k !== "object") continue;
+    const o = k;
+    if (typeof o.scheme !== "string" || typeof o.network !== "string") continue;
+    const fp = o.extra?.feePayer;
+    out.push({ scheme: o.scheme, network: o.network, ...typeof fp === "string" ? { feePayer: fp } : {} });
+  }
+  return out;
+}
+async function facilitatorCoverage(url, timeoutMs = 8e3) {
+  const base2 = url.replace(/\/+$/, "");
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${base2}/supported`, { signal: ctrl.signal });
+    if (!res.ok) return [];
+    return parseFacilitatorSupported(await res.json());
+  } catch {
+    return [];
+  } finally {
+    clearTimeout(timer);
+  }
+}
 function safeStringify(value) {
   return JSON.stringify(value, (_k, v) => typeof v === "bigint" ? v.toString() : v);
 }
@@ -4386,22 +4760,47 @@ function createPaymentGate(options) {
     const specs = await ready();
     const nonce = genNonce();
     const bazaar = options.discovery ? { bazaar: buildBazaarExtension(options.discovery === true ? {} : options.discovery) } : void 0;
-    const extensions = { ...bazaar, ...opts?.extensions };
+    const accepts = buildAccepts(specs, nonce);
+    const selfDescribe = options.selfDescribe === false ? void 0 : buildSelfDescription({
+      accepts,
+      instruction: describeChallenge({ x402Version: 2, resource: { url: resourceUrl }, accepts })
+    });
+    const rejectionExt = opts?.extensions ?? {};
+    const rejectionPiprail = rejectionExt.piprail ?? {};
+    const bodyPiprail = { ...selfDescribe ?? {}, ...rejectionPiprail };
+    const bodyExtensions = {
+      ...bazaar,
+      ...rejectionExt,
+      ...Object.keys(bodyPiprail).length > 0 ? { piprail: bodyPiprail } : {}
+    };
+    const headerExtensions = {
+      ...bazaar,
+      ...Object.keys(rejectionPiprail).length > 0 ? { piprail: rejectionPiprail } : {}
+    };
     const challenge2 = {
       x402Version: 2,
       resource: {
         url: resourceUrl,
         ...options.description ? { description: options.description } : {}
       },
-      accepts: buildAccepts(specs, nonce),
+      accepts,
       ...opts?.error ? { error: opts.error } : {},
-      ...Object.keys(extensions).length > 0 ? { extensions } : {}
+      ...Object.keys(bodyExtensions).length > 0 ? { extensions: bodyExtensions } : {}
+    };
+    const headerChallenge = {
+      ...challenge2,
+      ...Object.keys(headerExtensions).length > 0 ? { extensions: headerExtensions } : { extensions: void 0 }
     };
-    return { challenge: challenge2, requiredHeader: buildChallengeHeader(challenge2) };
+    return { challenge: challenge2, requiredHeader: buildChallengeHeader(headerChallenge) };
   }
   async function challenge(resourceUrl = "") {
     return makeChallenge(resourceUrl);
   }
+  function landingPage(ch) {
+    return renderLandingPage(
+      buildSelfDescription({ accepts: ch.accepts, instruction: describeChallenge(ch) })
+    );
+  }
   async function asChallenge() {
     const { challenge: c, requiredHeader } = await makeChallenge("");
     return { kind: "challenge", challenge: c, requiredHeader, statusCode: 402 };
@@ -4597,7 +4996,7 @@ function createPaymentGate(options) {
     if (exact) return verifyExact(exact);
     return asChallenge();
   }
-  return { challenge, verify, describe };
+  return { challenge, verify, describe, landingPage };
 }
 function requirePayment(options) {
   const gate = createPaymentGate(options);
@@ -4637,6 +5036,39 @@ function normaliseHeader(value) {
   return value;
 }
 
+// src/facilitators.ts
+var KNOWN_FACILITATORS = {
+  // PayAI — keyless (no API key), sponsors the gas. Verified 2026-06-14 against
+  // https://facilitator.payai.network/supported (exact · eip155:8453) + the live demo.
+  "eip155:8453": [
+    {
+      url: "https://facilitator.payai.network",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["eip3009"],
+      note: "PayAI \u2014 keyless, sponsors gas (Base USDC EIP-3009)"
+    }
+  ],
+  // PayAI on Solana — keyless fee-payer sponsor for the SVM exact rail. Verified 2026-06-14.
+  "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": [
+    {
+      url: "https://facilitator.payai.network",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["svm"],
+      note: "PayAI \u2014 keyless fee-payer sponsor (Solana SPL SVM)"
+    }
+  ]
+};
+function knownFacilitatorsFor(network) {
+  return KNOWN_FACILITATORS[network] ?? [];
+}
+function firstKeylessFacilitator(network, method) {
+  return knownFacilitatorsFor(network).find(
+    (f) => f.keyless && f.schemes.includes("exact") && (method === void 0 || f.settles.includes(method))
+  );
+}
+
 // src/receipts.ts
 var DEFAULT_RETRIES = 5;
 var DEFAULT_TIMEOUT_MS = 1e4;
@@ -4741,6 +5173,7 @@ async function deliverReceipt(receipt, options) {
   };
 }
 export {
+  BRAND,
   CHAINS,
   ConfirmationTimeoutError,
   DIRECTORY_INFO,
@@ -4754,14 +5187,17 @@ export {
   HEADER_SIGNATURE_V1,
   InsufficientFundsError,
   InvalidEnvelopeError,
+  KNOWN_FACILITATORS,
   MaxRetriesExceededError,
   MissingDriverError,
+  MultiChainPayer,
   NoCompatibleAcceptError,
   NonReplayableBodyError,
   PERMIT2_ADDRESS,
   PERMIT2_PROXY_CHAIN_IDS,
   PERMIT2_WITNESS_TYPES,
   PIPRAIL_AGENT_GUIDE,
+  POWERED_BY,
   PaymentDeclinedError,
   PaymentTimeoutError,
   PipRailClient,
@@ -4784,6 +5220,7 @@ export {
   buildExactSignatureHeader,
   buildOpenApi,
   buildReceiptHeader,
+  buildSelfDescription,
   buildSignatureHeader,
   buildWellKnownX402,
   buildX402DnsTxt,
@@ -4793,17 +5230,24 @@ export {
   createPaymentGate,
   decorateOutcome,
   deliverReceipt,
+  describeChallenge,
+  discoveryHeaders,
   eip3009Abi,
   encodeXPaymentHeader,
   evaluatePolicy,
   explainDecline,
+  facilitatorCoverage,
+  fetchAcross,
+  firstKeylessFacilitator,
   formatSpendReport,
   getDirectoryInfo,
   isPermit2ProxyChain,
+  knownFacilitatorsFor,
   normalizeNetwork,
   parseChallenge,
   parseExactPaymentHeader,
   parseExactRequirements,
+  parseFacilitatorSupported,
   parseReceipt,
   parseSettleResponse,
   parseSignatureHeader,
@@ -4814,6 +5258,7 @@ export {
   register402Index,
   registerDriver,
   registerX402Scan,
+  renderLandingPage,
   requirePayment,
   resolveChain,
   searchOpenIndexes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "1.22.1",
+  "version": "1.24.0",
   "description": "Accept x402 crypto payments across 29 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & XRPL — in a couple of lines. No backend, no database, no fee; payments settle straight to your wallet.",
   "type": "module",
   "main": "./dist/index.cjs",