@piprail/sdk 2.1.1 → 2.2.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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/).
 
+## [2.2.0] — 2026-06-16 — broader x402 ecosystem interoperability
+
+Both changes are additive and backward-compatible — defaults and the zero-config 402 stay
+byte-identical; only previously-skipped cases become newly handled.
+
+### Changed
+
+- **The `exact` buyer matches a rail's network whether it's a CAIP-2 id _or_ a chain slug.** The pay
+  path now normalizes the offered network (`eip155:8453`, `base`, `bsc`, `56`, …) before matching it to
+  the bound chain — the same normalization discovery already used — so a PipRail client interoperates
+  with any x402 server or facilitator regardless of how it labels the network. Strictly additive: a
+  CAIP-2 label behaves exactly as before; only a chain slug that resolves to the **bound** chain becomes
+  newly payable (a different-chain or unrecognized label is never selected, and the trusted EIP-712
+  domain still fixes the chain id at signing). Fixes `exact` rails that some facilitators label by slug
+  being silently unpayable.
+
+### Added
+
+- **`facilitatorCoverage()` / `parseFacilitatorSupported()` surface two optional per-kind fields** —
+  `x402Version` and `assetTransferMethod` (`'eip3009' | 'permit2'`) — when a facilitator's `GET
+  /supported` advertises them, so coverage can tell a v1 rail from a v2 rail and an EIP-3009 kind from a
+  Permit2 one. Omitted entirely when absent (no `undefined` keys), so a facilitator reporting neither
+  parses exactly as before.
+
 ## [2.1.1] — 2026-06-15 — discoverability polish (post-2.1.0 audit)
 
 A consistency patch from a deep docs↔source audit of the 2.1.0 discoverability surface. No
@@ -1196,6 +1220,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.
 
+[2.2.0]: https://www.npmjs.com/package/@piprail/sdk
 [2.1.1]: https://www.npmjs.com/package/@piprail/sdk
 [2.1.0]: https://www.npmjs.com/package/@piprail/sdk
 [2.0.2]: https://www.npmjs.com/package/@piprail/sdk

package/dist/index.cjs

@@ -3220,7 +3220,7 @@ var PipRailClient = (_class2 = class {
     const candidates = this.gatherCandidates(net, challenge, schemes);
     if (candidates.length === 0) {
       const exactOnNet = challenge.accepts.some(
-        (a) => a.scheme === "exact" && net.supports(a.network)
+        (a) => a.scheme === "exact" && this.supportsNetwork(net, a.network)
       );
       if (schemes.includes("exact") && exactOnNet && typeof net.payExact !== "function") {
         throw new (0, _chunkJG6KRAW6cjs.UnsupportedSchemeError)(
@@ -3229,7 +3229,7 @@ var PipRailClient = (_class2 = class {
       }
       if (!schemes.includes("exact") && exactOnNet && typeof net.payExact === "function") {
         const payable = challenge.accepts.some(
-          (a) => a.scheme === "exact" && net.supports(a.network) && net.describeAsset(a.asset) != null
+          (a) => a.scheme === "exact" && this.supportsNetwork(net, a.network) && net.describeAsset(a.asset) != null
         );
         if (payable) {
           throw new (0, _chunkJG6KRAW6cjs.NoCompatibleAcceptError)(
@@ -3249,6 +3249,17 @@ var PipRailClient = (_class2 = class {
     const chosen = _nullishCoalesce(priced.find((p) => p.quote.withinPolicy), () => ( priced[0]));
     return { net, wallet, accept: chosen.accept, challenge, quote: chosen.quote };
   }
+  /** Match a foreign-supplied network string against the bound driver, tolerating a
+   *  SLUG ('bsc', 'base', '56') the SAME way discovery's `railOnNetwork` already does —
+   *  normalize to CAIP-2 first, since a foreign/AEON/community 402 may label the network
+   *  with a slug (AEON serves v1 duplicate kinds '56'/'bsc'). ADDITIVE: a value that's
+   *  already CAIP-2 passes through `normalizeNetwork` UNCHANGED, so every existing
+   *  exact-CAIP-2 match is byte-identical; only slugs resolving to the bound chain become
+   *  newly matchable (an unknown slug stays unresolved → still unmatched; a different
+   *  chain's slug resolves elsewhere → still unmatched). */
+  supportsNetwork(net, network) {
+    return net.supports(normalizeNetwork(network));
+  }
   /** The candidate accepts this client could pay, on the bound network. Always the
    *  backendless `onchain-proof` rails; PLUS standard `exact` rails when `schemes`
    *  enables them AND the driver can settle them (EVM `payExact` + a recognised
@@ -3259,14 +3270,14 @@ var PipRailClient = (_class2 = class {
     if (schemes.includes("onchain-proof")) {
       out.push(
         ...challenge.accepts.filter(
-          (a) => a.scheme === "onchain-proof" && net.supports(a.network)
+          (a) => a.scheme === "onchain-proof" && this.supportsNetwork(net, a.network)
         )
       );
     }
     if (schemes.includes("exact")) {
       out.push(
         ...challenge.accepts.filter(
-          (a) => a.scheme === "exact" && net.supports(a.network) && typeof net.payExact === "function" && net.describeAsset(a.asset) != null && // a foreign rail's maxTimeoutSeconds must be a usable positive integer, or
+          (a) => a.scheme === "exact" && this.supportsNetwork(net, a.network) && typeof net.payExact === "function" && net.describeAsset(a.asset) != null && // a foreign rail's maxTimeoutSeconds must be a usable positive integer, or
           // signing it would build a NaN/garbage validBefore — drop it silently
           // (symmetric with an unrecognised token) rather than leak a raw SyntaxError.
           Number.isInteger(a.maxTimeoutSeconds) && a.maxTimeoutSeconds > 0
@@ -3508,7 +3519,7 @@ var PipRailClient = (_class2 = class {
     );
   }
   async payAndConfirm(net, wallet, accept) {
-    if (!net.supports(accept.network)) {
+    if (!this.supportsNetwork(net, accept.network)) {
       throw new (0, _chunkJG6KRAW6cjs.WrongChainError)(
         `Challenge expects ${accept.network} but client is on ${net.network}.`
       );
@@ -4761,7 +4772,15 @@ function parseFacilitatorSupported(body) {
     const o = k;
     if (typeof o.scheme !== "string" || typeof o.network !== "string") continue;
     const fp = _optionalChain([o, 'access', _77 => _77.extra, 'optionalAccess', _78 => _78.feePayer]);
-    out.push({ scheme: o.scheme, network: o.network, ...typeof fp === "string" ? { feePayer: fp } : {} });
+    const ver = o.x402Version;
+    const method = _optionalChain([o, 'access', _79 => _79.extra, 'optionalAccess', _80 => _80.assetTransferMethod]);
+    out.push({
+      scheme: o.scheme,
+      network: o.network,
+      ...typeof fp === "string" ? { feePayer: fp } : {},
+      ...typeof ver === "number" ? { x402Version: ver } : {},
+      ...typeof method === "string" ? { assetTransferMethod: method } : {}
+    });
   }
   return out;
 }
@@ -5067,7 +5086,7 @@ function createPaymentGate(options) {
       instruction: describeChallenge({ x402Version: 2, resource: { url: resourceUrl }, accepts }),
       ...endpointInfo ? { endpoint: endpointInfo } : {}
     });
-    const rejectionExt = _nullishCoalesce(_optionalChain([opts, 'optionalAccess', _79 => _79.extensions]), () => ( {}));
+    const rejectionExt = _nullishCoalesce(_optionalChain([opts, 'optionalAccess', _81 => _81.extensions]), () => ( {}));
     const rejectionPiprail = _nullishCoalesce(rejectionExt.piprail, () => ( {}));
     const bodyPiprail = { ..._nullishCoalesce(selfDescribe, () => ( {})), ...rejectionPiprail };
     const bodyExtensions = {
@@ -5087,7 +5106,7 @@ function createPaymentGate(options) {
         ...options.mimeType ? { mimeType: options.mimeType } : {}
       },
       accepts,
-      ..._optionalChain([opts, 'optionalAccess', _80 => _80.error]) ? { error: opts.error } : {},
+      ..._optionalChain([opts, 'optionalAccess', _82 => _82.error]) ? { error: opts.error } : {},
       ...Object.keys(bodyExtensions).length > 0 ? { extensions: bodyExtensions } : {}
     };
     const headerChallenge = {
@@ -5409,7 +5428,7 @@ function isRetryableStatus(status) {
 }
 var sleep = (ms) => ms > 0 ? new Promise((resolve) => setTimeout(resolve, ms)) : Promise.resolve();
 async function signBody(secret, body) {
-  const subtle = _optionalChain([globalThis, 'access', _81 => _81.crypto, 'optionalAccess', _82 => _82.subtle]);
+  const subtle = _optionalChain([globalThis, 'access', _83 => _83.crypto, 'optionalAccess', _84 => _84.subtle]);
   if (!subtle) return null;
   try {
     const enc = new TextEncoder();
@@ -5479,7 +5498,7 @@ async function deliverReceipt(receipt, options) {
     const retryable = status === void 0 ? true : isRetryableStatus(status);
     const willRetry = !ok && retryable && attempt < maxAttempts;
     try {
-      _optionalChain([onAttempt, 'optionalCall', _83 => _83({ attempt, ok, ...status !== void 0 ? { status } : {}, ...error ? { error } : {}, willRetry })]);
+      _optionalChain([onAttempt, 'optionalCall', _85 => _85({ attempt, ok, ...status !== void 0 ? { status } : {}, ...error ? { error } : {}, willRetry })]);
     } catch (e40) {
     }
     if (ok) return { delivered: true, attempts: attempt, status };

package/dist/index.d.cts

@@ -5562,6 +5562,15 @@ declare class PipRailClient {
      * `quote()` (read-only) and `fetch()` (which then authorises + pays).
      */
     private resolveChallenge;
+    /** Match a foreign-supplied network string against the bound driver, tolerating a
+     *  SLUG ('bsc', 'base', '56') the SAME way discovery's `railOnNetwork` already does —
+     *  normalize to CAIP-2 first, since a foreign/AEON/community 402 may label the network
+     *  with a slug (AEON serves v1 duplicate kinds '56'/'bsc'). ADDITIVE: a value that's
+     *  already CAIP-2 passes through `normalizeNetwork` UNCHANGED, so every existing
+     *  exact-CAIP-2 match is byte-identical; only slugs resolving to the bound chain become
+     *  newly matchable (an unknown slug stays unresolved → still unmatched; a different
+     *  chain's slug resolves elsewhere → still unmatched). */
+    private supportsNetwork;
     /** The candidate accepts this client could pay, on the bound network. Always the
      *  backendless `onchain-proof` rails; PLUS standard `exact` rails when `schemes`
      *  enables them AND the driver can settle them (EVM `payExact` + a recognised
@@ -6611,6 +6620,14 @@ interface FacilitatorSupportedKind {
     network: string;
     /** The fee-payer pubkey when the kind carries one (SVM rails). */
     feePayer?: string;
+    /** The kind's x402 envelope version when the facilitator reports it per-kind — e.g.
+     *  AEON's `/supported` serves `{ x402Version, scheme, network }`, letting a reader tell
+     *  a v1 from a v2 BNB rail. Optional — absent when the facilitator doesn't advertise it. */
+    x402Version?: number;
+    /** The EVM exact transfer method (`eip3009` / `permit2`) when the facilitator advertises
+     *  it in the kind's `extra` — so coverage can tell whether a BNB exact kind is gasless
+     *  EIP-3009 or Permit2. Optional — most facilitators (AEON included) omit it. */
+    assetTransferMethod?: string;
 }
 /**
  * Parse a facilitator `/supported` body into its advertised (scheme, network) kinds.

package/dist/index.d.ts

@@ -5562,6 +5562,15 @@ declare class PipRailClient {
      * `quote()` (read-only) and `fetch()` (which then authorises + pays).
      */
     private resolveChallenge;
+    /** Match a foreign-supplied network string against the bound driver, tolerating a
+     *  SLUG ('bsc', 'base', '56') the SAME way discovery's `railOnNetwork` already does —
+     *  normalize to CAIP-2 first, since a foreign/AEON/community 402 may label the network
+     *  with a slug (AEON serves v1 duplicate kinds '56'/'bsc'). ADDITIVE: a value that's
+     *  already CAIP-2 passes through `normalizeNetwork` UNCHANGED, so every existing
+     *  exact-CAIP-2 match is byte-identical; only slugs resolving to the bound chain become
+     *  newly matchable (an unknown slug stays unresolved → still unmatched; a different
+     *  chain's slug resolves elsewhere → still unmatched). */
+    private supportsNetwork;
     /** The candidate accepts this client could pay, on the bound network. Always the
      *  backendless `onchain-proof` rails; PLUS standard `exact` rails when `schemes`
      *  enables them AND the driver can settle them (EVM `payExact` + a recognised
@@ -6611,6 +6620,14 @@ interface FacilitatorSupportedKind {
     network: string;
     /** The fee-payer pubkey when the kind carries one (SVM rails). */
     feePayer?: string;
+    /** The kind's x402 envelope version when the facilitator reports it per-kind — e.g.
+     *  AEON's `/supported` serves `{ x402Version, scheme, network }`, letting a reader tell
+     *  a v1 from a v2 BNB rail. Optional — absent when the facilitator doesn't advertise it. */
+    x402Version?: number;
+    /** The EVM exact transfer method (`eip3009` / `permit2`) when the facilitator advertises
+     *  it in the kind's `extra` — so coverage can tell whether a BNB exact kind is gasless
+     *  EIP-3009 or Permit2. Optional — most facilitators (AEON included) omit it. */
+    assetTransferMethod?: string;
 }
 /**
  * Parse a facilitator `/supported` body into its advertised (scheme, network) kinds.

package/dist/index.js

@@ -3220,7 +3220,7 @@ var PipRailClient = class {
     const candidates = this.gatherCandidates(net, challenge, schemes);
     if (candidates.length === 0) {
       const exactOnNet = challenge.accepts.some(
-        (a) => a.scheme === "exact" && net.supports(a.network)
+        (a) => a.scheme === "exact" && this.supportsNetwork(net, a.network)
       );
       if (schemes.includes("exact") && exactOnNet && typeof net.payExact !== "function") {
         throw new UnsupportedSchemeError(
@@ -3229,7 +3229,7 @@ var PipRailClient = class {
       }
       if (!schemes.includes("exact") && exactOnNet && typeof net.payExact === "function") {
         const payable = challenge.accepts.some(
-          (a) => a.scheme === "exact" && net.supports(a.network) && net.describeAsset(a.asset) != null
+          (a) => a.scheme === "exact" && this.supportsNetwork(net, a.network) && net.describeAsset(a.asset) != null
         );
         if (payable) {
           throw new NoCompatibleAcceptError(
@@ -3249,6 +3249,17 @@ var PipRailClient = class {
     const chosen = priced.find((p) => p.quote.withinPolicy) ?? priced[0];
     return { net, wallet, accept: chosen.accept, challenge, quote: chosen.quote };
   }
+  /** Match a foreign-supplied network string against the bound driver, tolerating a
+   *  SLUG ('bsc', 'base', '56') the SAME way discovery's `railOnNetwork` already does —
+   *  normalize to CAIP-2 first, since a foreign/AEON/community 402 may label the network
+   *  with a slug (AEON serves v1 duplicate kinds '56'/'bsc'). ADDITIVE: a value that's
+   *  already CAIP-2 passes through `normalizeNetwork` UNCHANGED, so every existing
+   *  exact-CAIP-2 match is byte-identical; only slugs resolving to the bound chain become
+   *  newly matchable (an unknown slug stays unresolved → still unmatched; a different
+   *  chain's slug resolves elsewhere → still unmatched). */
+  supportsNetwork(net, network) {
+    return net.supports(normalizeNetwork(network));
+  }
   /** The candidate accepts this client could pay, on the bound network. Always the
    *  backendless `onchain-proof` rails; PLUS standard `exact` rails when `schemes`
    *  enables them AND the driver can settle them (EVM `payExact` + a recognised
@@ -3259,14 +3270,14 @@ var PipRailClient = class {
     if (schemes.includes("onchain-proof")) {
       out.push(
         ...challenge.accepts.filter(
-          (a) => a.scheme === "onchain-proof" && net.supports(a.network)
+          (a) => a.scheme === "onchain-proof" && this.supportsNetwork(net, a.network)
         )
       );
     }
     if (schemes.includes("exact")) {
       out.push(
         ...challenge.accepts.filter(
-          (a) => a.scheme === "exact" && net.supports(a.network) && typeof net.payExact === "function" && net.describeAsset(a.asset) != null && // a foreign rail's maxTimeoutSeconds must be a usable positive integer, or
+          (a) => a.scheme === "exact" && this.supportsNetwork(net, a.network) && typeof net.payExact === "function" && net.describeAsset(a.asset) != null && // a foreign rail's maxTimeoutSeconds must be a usable positive integer, or
           // signing it would build a NaN/garbage validBefore — drop it silently
           // (symmetric with an unrecognised token) rather than leak a raw SyntaxError.
           Number.isInteger(a.maxTimeoutSeconds) && a.maxTimeoutSeconds > 0
@@ -3508,7 +3519,7 @@ var PipRailClient = class {
     );
   }
   async payAndConfirm(net, wallet, accept) {
-    if (!net.supports(accept.network)) {
+    if (!this.supportsNetwork(net, accept.network)) {
       throw new WrongChainError(
         `Challenge expects ${accept.network} but client is on ${net.network}.`
       );
@@ -4761,7 +4772,15 @@ function parseFacilitatorSupported(body) {
     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 } : {} });
+    const ver = o.x402Version;
+    const method = o.extra?.assetTransferMethod;
+    out.push({
+      scheme: o.scheme,
+      network: o.network,
+      ...typeof fp === "string" ? { feePayer: fp } : {},
+      ...typeof ver === "number" ? { x402Version: ver } : {},
+      ...typeof method === "string" ? { assetTransferMethod: method } : {}
+    });
   }
   return out;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "2.1.1",
+  "version": "2.2.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",