@piprail/sdk 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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.5.0] — 2026-06-04
+
+**The killer agent feature — `client.planPayment(url)`.** A read-only call that surveys a 402
+across every rail it offers *on your chain* against your wallet's OWN holdings — **token balance +
+native gas + recipient-readiness** (trustline / ATA / storage_deposit / ASA opt-in / activation) —
+and tells you, crystal-clear, whether it's settleable, on which rail, and if not, exactly what to
+top up. It completes the trio the SDK already ships: **`quote()` (what it costs) → `estimateCost()`
+(the gas) → `planPayment()` (can I actually settle, and where).** Fully backward-compatible and
+opt-in; defaults are unchanged. The official x402 client picks `accepts[0]` blind; PipRail is the
+only backendless SDK that can answer "can I actually pay this?" across 28 chains with pure RPC
+reads, no oracle/facilitator/bridge. Live-proven on Algorand mainnet (ready / recipient-not-ready /
+insufficient / multi-rail-rank, 4/4).
+
+### Added
+- **`client.planPayment(url, init?)` → `PaymentPlan | null`.** Never throws for a read problem (a
+  transient/RPC failure surfaces as a rail in `state: 'unknown'` + a warning, never a false
+  "unaffordable"); returns `null` when the URL isn't 402-gated; and when the 402 offers no rail on
+  your chain it EXPLAINS that (status `blocked` + a hint) instead of throwing. The plan carries:
+  `payable` + `best` (the cheapest settleable rail), `options[]` (every rail with typed `blockers`
+  — `INSUFFICIENT_TOKEN`/`INSUFFICIENT_GAS`/`RECIPIENT_NOT_READY`/`OUTSIDE_POLICY` — plus soft
+  `warnings`, a `shortfall`, live `balance`, and `recipient.fix`), and a one-sentence `fundingHint`.
+- **`client.canAfford(url)` → `boolean`** — convenience over the above.
+- **`fetch(url, { autoRoute: true })` / `new PipRailClient({ autoRoute: true })`** — opt-in:
+  `fetch` pays the cheapest rail the wallet can ACTUALLY settle (not the first policy-passing one),
+  or throws `PaymentDeclinedError` carrying the funding hint before any send. **Default off** —
+  the zero-config path is byte-identical.
+- **`planAcross(clients, url)`** — the cross-chain brain: give it one client per chain you fund and
+  it merges their plans, payable-first (no oracle, so the cross-coin tiebreak is your client order).
+- **`piprail_plan_payment`** agent tool (budget-bound; `paymentTools(client)` now returns 3 tools).
+- **Driver contract:** `balanceOf(wallet, asset)` + `recipientReady(payTo, asset)` on every family
+  (10/10), RPC-read-only and NEVER-throw (transient ⇒ `null`/`'unknown'`, per ERRORS.md §5). Real
+  receive-prerequisite probes on NEAR (`storage_balance_of`), Stellar/XRPL (trustline presence),
+  Algorand (ASA opt-in); truthful `'n/a'` on EVM/Solana/TON/Tron/Sui/Aptos (no prerequisite).
+- New exported types: `PaymentPlan`, `PayOption`, `PayBlocker`, `PayWarning`, `RecipientReason`,
+  `WalletBalance` (and the previously-missing `AptosToken`/`AlgorandToken`).
+
 ## [1.4.0] — 2026-06-04
 
 A new chain **family** — **Algorand** — the **10th driver family**, bringing the built-in count to

package/ERRORS.md

@@ -149,6 +149,17 @@ Every `PaymentDriver` / `ResolvedNetwork` method has a fixed error behaviour:
 | `send(wallet, accept)` | wrap the broadcast; map **sender** affordability → `InsufficientFundsError` (§6) and **recipient** setup → `RecipientNotReadyError` (§6.1); **rethrow everything else unchanged** (never swallow). Every mapped throw carries `{ cause }` = the raw chain error. |
 | `verify(ref, accept)` | **return** a `VerifyResult` with a canonical `VerifyErrorCode`. **Guard every RPC read** so a transient failure returns `tx_not_found` — `verify()` must not throw for an RPC hiccup. Re-derive the watched account from the trusted `accept`, never the client ref. |
 | `confirm(ref, n)` | broadcast-but-not-confirmed / timeout → `ConfirmationTimeoutError`. |
+| `estimateCost(accept, opts?)` | **never throw** — guard the RPC read and fall back to a `'heuristic'` constant; always return a valid `CostEstimate`. |
+| `balanceOf(wallet, asset)` | **never throw** — RPC-read-only. A field whose read was unavailable (transient/rate-limit) returns `null`, NOT `0` (a false 0 reads as "broke"). For `asset==='native'`, `token === native`. |
+| `recipientReady(payTo, asset)` | **never throw** — report the receive prerequisite: `{ ready:'n/a' }` (no prerequisite on this family/native), `{ ready:true }`, `{ ready:false, reason }` (a `RecipientReason`), or `{ ready:'unknown' }` on a transient read. `'n/a'` must be TRUTHFUL — never a stand-in for "didn't check". |
+
+> **`planPayment` is a RETURN-channel feature.** The client's `planPayment`/`canAfford` compose
+> `balanceOf` + `recipientReady` + `estimateCost` + the policy verdict into a `PaymentPlan` — and,
+> like `verify()`, they **return** the outcome rather than throwing: a transient read becomes a rail
+> in `state:'unknown'` (+ a warning), an unsettleable rail carries typed `blockers`, and a 402 with
+> no rail on the client's chain is *explained* in the plan. The only throw is `InvalidEnvelopeError`
+> on an unparseable challenge. (`fetch({ autoRoute:true })` is the one place a plan turns into a
+> THROWN `PaymentDeclinedError` — refusing before any send when nothing is settleable.)
 
 ### 6. Affordability converges on one error, by two mechanisms
 

package/README.md

@@ -77,13 +77,41 @@ client.spent() // → { count, byAsset: [{ symbol:'USDC', totalFormatted:'0.05',
 
 **Know the gas before you pay.** `client.estimateCost(url)` returns the quote **and** a `CostEstimate` — the network fee in the chain's **native coin** (you pay in USDC but burn ETH / SOL / TON / XLM / XRP / TRX on gas, a separate balance the agent must keep topped up). It's best-effort and labelled (`cost.basis`): a live-RPC read where cheap (`'estimated'` — EVM gas price, XRPL fee), a typical-cost constant otherwise (`'heuristic'`), and it never throws. Most valuable on **Tron**, where a USD₮ transfer can cost real TRX. So an agent can budget the *total* — payment **+** gas — before any funds move. Every driver implements it; the math is extracted per-chain and shaped uniformly by one shared `nativeCost()` helper.
 
+### Plan before you pay — `planPayment()` (never fumble a payment)
+
+`quote()` tells you the price and `estimateCost()` the gas — **`planPayment(url)`** closes the loop: **one read-only call** that checks, against your wallet's *own* holdings, whether a 402 will actually go through — and if not, exactly what to fix. No funds move.
+
+```ts
+const plan = await client.planPayment(url)
+
+if (plan?.payable) {
+  await client.fetch(url, { autoRoute: true })   // pays plan.best — the cheapest rail you can settle
+} else {
+  console.log(plan?.fundingHint)
+  // "Have the USDC, but need ~0.000021 ETH for gas on base (have 0)."
+  // "Recipient 2OT6…GC5E4 can't receive on algorand yet — must opt into the USDC ASA."
+  // "Top up 0.04 USDC on base (have 0.01)."
+}
+```
+
+For **every rail the 402 offers on your chain**, the plan reads **token balance + native-coin gas + recipient-readiness** (trustline / ATA / `storage_deposit` / ASA opt-in / activation) and returns:
+- **`payable`** + **`best`** — the cheapest rail you can actually settle (recipient confirmed able to receive);
+- **`options[]`** — each rail with typed **`blockers`** (`INSUFFICIENT_TOKEN` · `INSUFFICIENT_GAS` · `RECIPIENT_NOT_READY` · `OUTSIDE_POLICY`), soft **`warnings`** (`SYMBOL_MISMATCH`, `THIN_GAS_MARGIN`, `BALANCE_UNREADABLE`, …), a **`shortfall`**, the live **`balance`**, and **`recipient.fix`**;
+- **`fundingHint`** — one human sentence on exactly what to top up.
+
+**Why it's the agent unlock.** The official x402 client picks `accepts[0]` blind and learns it can't pay only when the broadcast reverts (no token, no gas) or the transfer silently strands (recipient not set up to receive). `planPayment` turns those runtime failures into a pre-checked decision — and on the no-facilitator path *you* pay your own gas, so "I hold USDC but no ETH" is a first-class answer, not a crash. It **never throws for a read hiccup** (a throttled RPC surfaces as `state: 'unknown'` + a warning, never a false "broke"), returns `null` when the URL isn't gated, and *explains* "this is offered on solana, base — you're on xrpl" instead of erroring. `client.canAfford(url)` is the one-boolean convenience.
+
+**Auto-route (opt-in).** `new PipRailClient({ autoRoute: true })` (or `fetch(url, { autoRoute: true })`) makes `fetch` pay the cheapest *settleable* rail instead of the first policy-passing one — refusing with `PaymentDeclinedError` + the funding hint before any send. **Default off; the zero-config path is unchanged.**
+
+**Across chains.** A client is bound to one chain; **`planAcross([baseClient, solanaClient, …], url)`** runs each plan in parallel and merges them payable-first, so an agent holding funds on several chains learns which to use. (No price oracle — cross-coin ties break on the order you list the clients.)
+
 ### Hand an LLM a budget-bound wallet
 
 `paymentTools(client)` returns framework-agnostic tool descriptors (name + description + JSON Schema + `invoke`) — drop them into MCP, the Vercel AI SDK, OpenAI/Anthropic function-calling, or LangChain in a couple of lines. The budget rides on the client, so the model can't overspend.
 
 ```ts
 import { paymentTools } from '@piprail/sdk'
-const tools = paymentTools(client) // → [piprail_quote_payment, piprail_pay_request]
+const tools = paymentTools(client) // → [piprail_quote_payment, piprail_plan_payment, piprail_pay_request]
 ```
 
 See [`examples/agent-tools.mjs`](../examples/agent-tools.mjs) for MCP / AI-SDK wiring.
@@ -477,7 +505,7 @@ The SDK is browser-clean (no Node-only globals in the protocol layer), so a plai
 Two layers, one contract. Worth knowing if you're extending the SDK or auditing it.
 
 - **The protocol layer is chain-agnostic.** `server.ts` (`requirePayment`/`createPaymentGate`), `client.ts` (`PipRailClient`), `x402.ts` (wire envelopes), `policy.ts`, `ledger.ts`, and `agent.ts` depend **only** on the `PaymentDriver` contract in `drivers/types.ts` — zero `viem`, zero `@solana/web3.js`, zero chain SDK. The chain is data the caller passes, not an allowlist the SDK ships.
-- **The `PaymentDriver` contract.** `resolve(chain)` → a bound `ResolvedNetwork` exposing `resolveToken` · `describeAsset` · `assertValidPayTo` · `bindWallet` · `send` · `confirm` · `estimateCost` · `verify`. That's the entire boundary every family implements and the protocol layer ever sees.
+- **The `PaymentDriver` contract.** `resolve(chain)` → a bound `ResolvedNetwork` exposing `resolveToken` · `describeAsset` · `assertValidPayTo` · `bindWallet` · `send` · `confirm` · `estimateCost` · `balanceOf` · `recipientReady` · `verify`. That's the entire boundary every family implements and the protocol layer ever sees.
 - **Families mirror each other file-for-file.** Each lives in `drivers/<family>/` as `chains` · `wallet` · `pay` · `verify` · `index`, with family-suffixed functions (`payEvm`/`paySui`/…, `verifyEvm`/`verifyNear`/…). Ten today: `evm`, `solana`, `ton`, `stellar`, `xrpl`, `tron`, `near`, `sui`, `aptos`, `algorand`. Adding one = copy the five files, implement the contract, `registerDriver` — the protocol layer never changes.
 - **Routing + lazy auto-mount.** `registry.ts` maps a `chain` value to its family synchronously (`familyForChain`). EVM is always present (viem is a hard peer); every non-EVM family **loads itself on first use** via one dynamic `import()`, so a pure-EVM install never downloads `@solana`/`@ton`/`@stellar`/`xrpl`/`tronweb`/`near-api-js`/`@mysten/sui`/`@aptos-labs/ts-sdk`/`algosdk`. A build-time invariant asserts the main bundle has **zero** static imports of those libs — only per-family lazy chunks.
 - **Two verification templates.** *Template A (memo-bound)* — Stellar, XRPL, TON, NEAR, Algorand — carries the challenge nonce inside the transfer (memo / tag / comment / note), so the proof is cryptographically bound to its challenge. *Template B (digest-bound)* — EVM, Solana, Tron, Sui, Aptos — binds via a single-use proof set + recipient + amount + a tight recency window (use a persistent `isUsed`/`markUsed` store in production).
@@ -556,7 +584,7 @@ Provide **either** `chain` + `token` + `amount` (single) **or** a non-empty `acc
 | `retryTimeoutMs` | `30000` | Timeout for the retry leg after broadcast |
 | `onEvent` | — | `(event) => void` observability: `payment-required` · `payment-broadcast` · `payment-confirmed` · `payment-unconfirmed` (broadcast OK, local confirm timed out → deferring to server) · `payment-settled` · `payment-failed` |
 
-Methods: `fetch` · `get` · `post` (return the gated `Response` after settlement) · **`quote(url)`** (price without paying → `PipRailQuote \| null`) · **`estimateCost(url)`** (price **+** native-coin gas estimate → `PipRailCostQuote \| null`) · **`spent()`** (per-asset ledger snapshot).
+Methods: `fetch` · `get` · `post` (return the gated `Response` after settlement) · **`quote(url)`** (price without paying → `PipRailQuote \| null`) · **`estimateCost(url)`** (price **+** native-coin gas estimate → `PipRailCostQuote \| null`) · **`planPayment(url)`** (affordability + recipient-readiness across the offered rails → `PaymentPlan \| null`) · **`canAfford(url)`** (→ `boolean`) · **`spent()`** (per-asset ledger snapshot). Pass `{ autoRoute: true }` to `fetch` (or set it on the client) to pay the cheapest *settleable* rail. Module-level **`planAcross(clients, url)`** plans across chains.
 
 **Wallets by family** — the `chain` selector routes; each driver validates its own key format (a mismatch throws `WrongFamilyError`):
 

package/dist/{algorand-XJ5OVWQB.js → algorand-B67G4335.js}

@@ -314,6 +314,40 @@ function makeAlgorandNetwork(preset, algodUrl) {
         detail: "min fee 1000 \xB5Algos (1 transaction)"
       });
     },
+    async balanceOf(wallet, asset) {
+      let owner;
+      try {
+        owner = resolveAlgorandWallet(wallet._native).addr;
+      } catch {
+        return { token: null, native: null };
+      }
+      let info;
+      try {
+        info = await algod.accountInformation(owner).do();
+      } catch {
+        return { token: null, native: null };
+      }
+      const native = info.amount != null ? BigInt(info.amount) : null;
+      if (asset === "native") return { token: native, native };
+      const assetId = parseAlgorandAssetId(asset);
+      const holding = (info.assets ?? []).find((a) => Number(a.assetId) === assetId);
+      return { token: holding ? BigInt(holding.amount) : 0n, native };
+    },
+    async recipientReady(payTo, asset) {
+      if (asset === "native") return { ready: "n/a" };
+      const assetId = parseAlgorandAssetId(asset);
+      if (assetId == null) return { ready: "unknown" };
+      try {
+        const info = await algod.accountInformation(payTo).do();
+        const optedIn = (info.assets ?? []).some((a) => Number(a.assetId) === assetId);
+        return optedIn ? { ready: true } : { ready: false, reason: "NOT_OPTED_IN" };
+      } catch (e) {
+        if (/does not exist|no accounts found|404|account not found/i.test(String(e?.message ?? e))) {
+          return { ready: false, reason: "NOT_OPTED_IN" };
+        }
+        return { ready: "unknown" };
+      }
+    },
     async verify(_ref, accept) {
       return verifyAlgorand({ reader, accept });
     }

package/dist/{algorand-IDFUG5CI.cjs → algorand-IJJKE35X.cjs}

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
 
 
@@ -89,7 +89,7 @@ async function verifyAlgorand(params) {
   let txs;
   try {
     txs = await reader.transactionsForAccount(accept.payTo, 50);
-  } catch (e) {
+  } catch (e2) {
     return rpcFailed(nonce);
   }
   const tx = txs.find((t) => typeof t.note === "string" && t.note === nonce);
@@ -117,7 +117,7 @@ async function verifyAlgorand(params) {
   let paid = 0n;
   try {
     paid = tx.amount ? BigInt(tx.amount) : 0n;
-  } catch (e2) {
+  } catch (e3) {
     paid = 0n;
   }
   if (paid < required) {
@@ -314,6 +314,40 @@ function makeAlgorandNetwork(preset, algodUrl) {
         detail: "min fee 1000 \xB5Algos (1 transaction)"
       });
     },
+    async balanceOf(wallet, asset) {
+      let owner;
+      try {
+        owner = resolveAlgorandWallet(wallet._native).addr;
+      } catch (e4) {
+        return { token: null, native: null };
+      }
+      let info;
+      try {
+        info = await algod.accountInformation(owner).do();
+      } catch (e5) {
+        return { token: null, native: null };
+      }
+      const native = info.amount != null ? BigInt(info.amount) : null;
+      if (asset === "native") return { token: native, native };
+      const assetId = parseAlgorandAssetId(asset);
+      const holding = (_nullishCoalesce(info.assets, () => ( []))).find((a) => Number(a.assetId) === assetId);
+      return { token: holding ? BigInt(holding.amount) : 0n, native };
+    },
+    async recipientReady(payTo, asset) {
+      if (asset === "native") return { ready: "n/a" };
+      const assetId = parseAlgorandAssetId(asset);
+      if (assetId == null) return { ready: "unknown" };
+      try {
+        const info = await algod.accountInformation(payTo).do();
+        const optedIn = (_nullishCoalesce(info.assets, () => ( []))).some((a) => Number(a.assetId) === assetId);
+        return optedIn ? { ready: true } : { ready: false, reason: "NOT_OPTED_IN" };
+      } catch (e) {
+        if (/does not exist|no accounts found|404|account not found/i.test(String(_nullishCoalesce(_optionalChain([e, 'optionalAccess', _ => _.message]), () => ( e))))) {
+          return { ready: false, reason: "NOT_OPTED_IN" };
+        }
+        return { ready: "unknown" };
+      }
+    },
     async verify(_ref, accept) {
       return verifyAlgorand({ reader, accept });
     }
@@ -354,7 +388,7 @@ function adaptTxn(raw) {
 function decodeNote(bytes) {
   try {
     return new TextDecoder().decode(bytes);
-  } catch (e3) {
+  } catch (e6) {
     return void 0;
   }
 }

package/dist/{aptos-TPSOQ2VL.cjs → aptos-X3G2UBYW.cjs}

@@ -322,6 +322,34 @@ function makeAptosNetwork(preset, rpcUrl) {
         detail: "\u22480.001 APT (a simple Fungible-Asset transfer; Aptos gas is sub-cent)"
       });
     },
+    async balanceOf(wallet, asset) {
+      let owner;
+      try {
+        owner = resolveAptosAccount(wallet._native).accountAddress.toString();
+      } catch (e7) {
+        return { token: null, native: null };
+      }
+      const native = await aptos.getAccountAPTAmount({ accountAddress: owner }).then((n) => BigInt(n)).catch(() => null);
+      if (asset === "native") return { token: native, native };
+      let token = null;
+      try {
+        const [bal] = await aptos.view({
+          payload: {
+            function: "0x1::primary_fungible_store::balance",
+            typeArguments: ["0x1::fungible_asset::Metadata"],
+            functionArguments: [owner, asset]
+          }
+        });
+        token = BigInt(String(bal));
+      } catch (e8) {
+        token = null;
+      }
+      return { token, native };
+    },
+    // No receive prerequisite — the recipient's primary FA store auto-creates on receipt.
+    async recipientReady() {
+      return { ready: "n/a" };
+    },
     async verify(ref, accept) {
       return verifyAptos({ reader, hash: ref, accept });
     }

package/dist/{aptos-AWWSCPDH.js → aptos-YQWTGFRZ.js}

@@ -322,6 +322,34 @@ function makeAptosNetwork(preset, rpcUrl) {
         detail: "\u22480.001 APT (a simple Fungible-Asset transfer; Aptos gas is sub-cent)"
       });
     },
+    async balanceOf(wallet, asset) {
+      let owner;
+      try {
+        owner = resolveAptosAccount(wallet._native).accountAddress.toString();
+      } catch {
+        return { token: null, native: null };
+      }
+      const native = await aptos.getAccountAPTAmount({ accountAddress: owner }).then((n) => BigInt(n)).catch(() => null);
+      if (asset === "native") return { token: native, native };
+      let token = null;
+      try {
+        const [bal] = await aptos.view({
+          payload: {
+            function: "0x1::primary_fungible_store::balance",
+            typeArguments: ["0x1::fungible_asset::Metadata"],
+            functionArguments: [owner, asset]
+          }
+        });
+        token = BigInt(String(bal));
+      } catch {
+        token = null;
+      }
+      return { token, native };
+    },
+    // No receive prerequisite — the recipient's primary FA store auto-creates on receipt.
+    async recipientReady() {
+      return { ready: "n/a" };
+    },
     async verify(ref, accept) {
       return verifyAptos({ reader, hash: ref, accept });
     }