@piprail/sdk 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ 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.15.0] — 2026-06-10 — the trusted agent wallet (budget-bound, time-boxed, asks-first)
+
+A minor, fully additive layer — defaults byte-identical, no new error code, protocol
+layer stays viem-free.
+
+### Added — a TIME dimension on `PaymentPolicy` (Mode A)
+- Four opt-in fields make the spend leash a *clock* too: `ttlSeconds` / `expiresAt` (a
+  session deadline — past it EVERY pay is refused with `reasonCode:'SESSION_EXPIRED'`,
+  TERMINAL) and `windowTotal` + `windowSeconds` (an optional rolling rate-limit, per
+  `(network, asset)`). All default off → behaviour unchanged. A half-armed window
+  (`windowTotal` without `windowSeconds`) or an unsafe `ttlSeconds` throws at construction.
+- `client.budget(): SessionBudget` and `PaymentPlan.session` surface the remaining money +
+  time leash so a headless agent can SEE it before paying. `client.remaining(): SpendRemaining[]`
+  gives the per-asset cap, ledger-scoped. All read-only, never throw, process-scoped (reset on restart).
+- `PolicyDecision` gains a typed `code` (`PolicyDenyCode`); `PayBlocker` gains `OUTSIDE_WINDOW`.
+
+### Added — agent ergonomics (the model-facing contract)
+- `PaymentDeclinedError.reasonCode` (`'POLICY' | 'BUDGET' | 'OUTSIDE_WINDOW' | 'SESSION_EXPIRED'
+  | 'APPROVAL'`) — a typed discriminator so an agent branches on the cause (and spots a TERMINAL
+  decline) without parsing prose. No new `.code`.
+- The `piprail_pay_request` tool now funnels EVERY `PipRailError` into a structured
+  `{ ok:false, code, reason, explain, ref?, reasonCode?, declined? }` — never an uncaught crash, so a
+  broadcast-but-unconfirmed timeout reaches the agent with its `.ref` and the never-re-pay rule.
+- New pure exports: `summarizePlan` / `explainDecline` / `formatSpendReport` (NL renderers, wired into
+  the tool outputs), `classifyChallenge` + `ChallengeTriage` (scheme/chain triage), and
+  `PIPRAIL_AGENT_GUIDE` / `agentGuide` (the cross-tool contract).
+- `paymentTools()` now returns **7** tools — the original 5, plus read-only `piprail_budget` and
+  `piprail_guide` appended last (the first five are byte-identical in name + order).
+
 ## [1.14.0] — 2026-06-10
 
 ### Added — pay the standard `exact` rail (opt-in, EVM + EIP-3009)
@@ -662,6 +691,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.15.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.14.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.13.1]: https://www.npmjs.com/package/@piprail/sdk
 [1.13.0]: https://www.npmjs.com/package/@piprail/sdk

package/ERRORS.md

@@ -114,9 +114,23 @@ the code. A consumer building a custom client may branch on it.
   `error — detail` (e.g. `… Last server rejection: amount_too_low — Paid 40000, required
   500000.`), and a `payment-failed` event carrying the same reason.
 - **Client refused to pay →** `PaymentDeclinedError` thrown *before* any on-chain send — the
-  quote exceeded the client's `policy`, or an `onBeforePay` hook returned false. Nothing moved.
+  quote exceeded the client's `policy` (amount/total/chain/token/host, or the session's **time
+  envelope**), or an `onBeforePay` hook returned false. Nothing moved. It carries an optional typed
+  `reasonCode` (`'POLICY' | 'BUDGET' | 'OUTSIDE_WINDOW' | 'SESSION_EXPIRED' | 'APPROVAL'`) so an agent
+  branches on the cause — and recognises a **TERMINAL** `SESSION_EXPIRED` / `APPROVAL` it must not
+  retry — without parsing the message. The session TTL (`SESSION_EXPIRED`) and rolling window
+  (`OUTSIDE_WINDOW`) reuse this EXISTING `PaymentDeclinedError` (`.code` stays `'PAYMENT_DECLINED'`):
+  **no new error class, no new `VerifyErrorCode`** — only the closed `PayBlocker` union gains `OUTSIDE_WINDOW`.
 - **Config / flow / wallet problem →** a thrown `PipRailError` with a stable `.code`.
 
+> **The agent toolkit funnels all of this.** The `piprail_pay_request` tool catches **every**
+> `PipRailError` and returns a structured `{ ok:false, code, reason, explain, ref?, reasonCode?,
+> declined? }` instead of letting it crash the agent loop — so a broadcast-but-unconfirmed
+> `PAYMENT_TIMEOUT`/`MAX_RETRIES_EXCEEDED`/`CONFIRMATION_TIMEOUT` reaches the model with its `.ref` and
+> the never-re-pay rule (via `explainDecline`). Only a genuine non-`PipRailError` bug rethrows.
+> The pure renderers (`render.ts`) and `classifyChallenge` (`classify.ts`) are viem-free protocol-layer
+> modules; `render.ts`'s VALUE import of `errors.ts` is allowed (errors.ts is chain-agnostic).
+
 Observability hooks never change control flow: the gate wraps `onPaid`, and the client routes
 every event through a private `safeEmit()` that swallows handler throws — a logging bug can't
 abort a payment.

package/README.md

@@ -148,17 +148,53 @@ For **every rail the 402 offers on your chain**, the plan reads **token balance
 
 ```ts
 import { paymentTools } from '@piprail/sdk'
-const tools = paymentTools(client) // → [piprail_discover, piprail_quote_payment, piprail_plan_payment, piprail_pay_request, piprail_register]
+const tools = paymentTools(client)
+// → [piprail_discover, piprail_quote_payment, piprail_plan_payment,
+//    piprail_pay_request, piprail_register, piprail_budget, piprail_guide]
 ```
 
 Each descriptor also carries advisory **`annotations`** (MCP-style `ToolAnnotations` — `title`,
-`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`): the three reads are flagged
+`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`): the reads are flagged
 **read-only**, `piprail_pay_request` is flagged **value-moving** (the one tool that spends), and
 `piprail_register` is non-destructive — so an MCP client can render the right consent. They're hints,
 not the boundary; the spend policy is. `@piprail/mcp` advertises them on the wire.
 
 See [`examples/agent-tools.mjs`](../examples/agent-tools.mjs) for MCP / AI-SDK wiring.
 
+### A budget that's also a clock — the time envelope (Mode A)
+
+The spend policy already caps *amount* and *total*; it can also bound *time*, so a headless agent
+runs free **inside** a budget **and** time envelope and the policy *is* the consent — no per-pay ask.
+All opt-in; omit them and behaviour is byte-identical.
+
+```ts
+const client = new PipRailClient({
+  chain: 'base', wallet,
+  policy: {
+    maxAmount: '0.10', maxTotal: '5.00', tokens: ['USDC'],
+    ttlSeconds: 3600,             // the whole session expires in 1h — then EVERY pay is refused
+    windowTotal: '1.00', windowSeconds: 600,  // …and ≤ $1 of USDC in any rolling 10-minute window
+  },
+})
+
+client.budget()    // → { session: { expiresAt, secondsRemaining }, byAsset: [...] } — read the leash before paying
+client.remaining() // → per-(network,asset) remaining cap (ledger-scoped)
+```
+
+A pay past the deadline throws `PaymentDeclinedError` with **`reasonCode: 'SESSION_EXPIRED'`** (TERMINAL
+— don't retry); a window breach is `'OUTSIDE_WINDOW'`. The window needs **both** `windowTotal` and
+`windowSeconds` (one alone throws at construction — a leash can't be half-armed). State is in-memory and
+**resets on restart** (the session *is* the process); durable limits are the caller's pluggable concern.
+
+### Legible to the model — the decline contract + the guide
+
+`piprail_pay_request` funnels **every** failure into a structured `{ ok:false, code, reason, explain,
+ref?, reasonCode?, declined? }` — never an uncaught crash — so a broadcast-but-unconfirmed timeout
+reaches the agent with its `.ref` and the **never-re-pay** rule, not a double-spend. Pure helpers make
+the rest legible: `summarizePlan` / `explainDecline` / `formatSpendReport` (one-line English),
+`classifyChallenge` (wrong-chain vs unpayable-scheme), and `PIPRAIL_AGENT_GUIDE` (the whole contract,
+distilled for an LLM). `piprail_budget` lets the agent self-check its leash; `piprail_guide` returns the contract.
+
 ## Be discoverable — find and be found ($0, no backend)
 
 A 402 endpoint is payable, but nobody can *find* it. PipRail closes that gap by building on the

package/STANDARDS.md

@@ -109,8 +109,10 @@ npm test                 # full Vitest suite
 npm run build            # tsup build succeeds
 # lazy-chunk invariant — the EVM bundle pulls in no non-EVM chain lib:
 grep -E "from ?['\"]@(solana|ton|stellar)" dist/index.js   # → expect NO matches
-# viem-free protocol layer — the chain-agnostic core never imports a chain SDK:
-grep -lE "from ['\"]viem" src/client.ts src/x402.ts src/policy.ts src/ledger.ts src/server.ts src/agent.ts  # → expect NO matches
+# viem-free protocol layer — the chain-agnostic core never imports a chain SDK
+# (includes the pure agent-ergonomics modules render/classify/agentGuide; render.ts's
+#  VALUE import of errors.ts is allowed — errors.ts is chain-agnostic, the grep targets viem):
+grep -lE "from ['\"]viem" src/client.ts src/x402.ts src/policy.ts src/ledger.ts src/server.ts src/agent.ts src/render.ts src/classify.ts src/agentGuide.ts  # → expect NO matches
 ```
 
 `prepublishOnly` runs build + test + both typechecks. Never ship with any of these red.

package/dist/{algorand-OIHGJN5S.cjs → algorand-EJ3S2V7E.cjs}

@@ -7,7 +7,7 @@
 
 
 
-var _chunkFTKVCP6Kcjs = require('./chunk-FTKVCP6K.cjs');
+var _chunkPA6YD3HLcjs = require('./chunk-PA6YD3HL.cjs');
 
 // src/drivers/algorand/index.ts
 var _algosdk = require('algosdk'); var _algosdk2 = _interopRequireDefault(_algosdk);
@@ -55,13 +55,13 @@ async function payAlgorand(params) {
   } catch (err) {
     const mapped = mapAlgorandError(err, accept.payTo);
     if (mapped) throw mapped;
-    throw _nullishCoalesce(_chunkFTKVCP6Kcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
+    throw _nullishCoalesce(_chunkPA6YD3HLcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
   }
 }
 function mapAlgorandError(err, payTo) {
   const m = err instanceof Error ? err.message : String(err);
   if (/must optin/i.test(m) || /missing from/i.test(m) && m.includes(payTo)) {
-    return new (0, _chunkFTKVCP6Kcjs.RecipientNotReadyError)(
+    return new (0, _chunkPA6YD3HLcjs.RecipientNotReadyError)(
       `Algorand recipient ${payTo} hasn't opted into this asset \u2014 it must opt in (a 0-amount asset transfer to itself) before it can receive. (Algorand: ${firstLine(m)})`,
       { cause: err }
     );
@@ -69,7 +69,7 @@ function mapAlgorandError(err, payTo) {
   if (/overspend|below min|min(imum)? balance|tried to spend|balance \d+ below|asset \d+ missing from|insufficient|underflow/i.test(
     m
   )) {
-    return new (0, _chunkFTKVCP6Kcjs.InsufficientFundsError)(
+    return new (0, _chunkPA6YD3HLcjs.InsufficientFundsError)(
       `Algorand payment failed: the sender can't cover it \u2014 token balance, ALGO for fees, the 0.1-ALGO minimum balance, or a missing asset opt-in on the sender. (Algorand: ${firstLine(m)})`,
       { cause: err }
     );
@@ -157,22 +157,22 @@ function rpcFailed(nonce) {
 
 function assertAlgorandWallet(wallet, network) {
   if (typeof wallet !== "object" || wallet === null) {
-    throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Algorand; wallet must be { mnemonic } (25 words) or { account }.`
     );
   }
   if ("privateKey" in wallet || "walletClient" in wallet) {
-    throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Algorand; an EVM/Aptos wallet can't be used \u2014 pass { mnemonic } (25 words) or { account }.`
     );
   }
   if ("secretKey" in wallet || "signer" in wallet || "secret" in wallet || "keypair" in wallet || "keyPair" in wallet || "seed" in wallet || "accountId" in wallet) {
-    throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Algorand; that looks like another family's wallet \u2014 pass { mnemonic } (25 words) or { account }.`
     );
   }
   if (!("mnemonic" in wallet) && !("account" in wallet)) {
-    throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Algorand; wallet must be { mnemonic } (25 words) or { account }.`
     );
   }
@@ -187,13 +187,13 @@ function resolveAlgorandWallet(config) {
       const { addr, sk } = _algosdk2.default.mnemonicToSecretKey(config.mnemonic);
       return { addr: addr.toString(), sk };
     } catch (cause) {
-      throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)(
+      throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
         "Algorand wallet { mnemonic } is not a valid 25-word Algorand mnemonic.",
         { cause }
       );
     }
   }
-  throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)("Algorand wallet needs { mnemonic } (25 words) or { account }.");
+  throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)("Algorand wallet needs { mnemonic } (25 words) or { account }.");
 }
 
 // src/drivers/algorand/index.ts
@@ -248,16 +248,16 @@ function makeAlgorandNetwork(preset, algodUrl) {
         const info = preset.tokens[token.toUpperCase()];
         if (!info) {
           const known = Object.keys(preset.tokens).join(", ") || "(none built in)";
-          throw new (0, _chunkFTKVCP6Kcjs.UnknownTokenError)(
+          throw new (0, _chunkPA6YD3HLcjs.UnknownTokenError)(
             `token "${token}" isn't built in for Algorand (known: ${known}). Pass { assetId, decimals } for a custom ASA, or use 'native'.`
           );
         }
         return { asset: algorandAssetId(info.assetId), decimals: info.decimals, symbol: info.symbol };
       }
-      _chunkFTKVCP6Kcjs.rejectForeignToken.call(void 0, token, "algorand", network);
+      _chunkPA6YD3HLcjs.rejectForeignToken.call(void 0, token, "algorand", network);
       const t = token;
       if (typeof t.assetId !== "number" || typeof t.decimals !== "number") {
-        throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)(
+        throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
           `chain ${network} is Algorand; a custom token must be { assetId, decimals }.`
         );
       }
@@ -278,12 +278,12 @@ function makeAlgorandNetwork(preset, algodUrl) {
     },
     assertValidPayTo(payTo) {
       if (payTo.startsWith("0x")) {
-        throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)(
+        throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
           `chain ${network} is Algorand, but payTo "${payTo}" looks like an EVM address.`
         );
       }
       if (!_algosdk2.default.isValidAddress(payTo)) {
-        throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)(
+        throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
           `chain ${network} is Algorand, but payTo "${payTo}" is not a valid Algorand address.`
         );
       }
@@ -300,13 +300,13 @@ function makeAlgorandNetwork(preset, algodUrl) {
         const info = await _algosdk2.default.waitForConfirmation(algod, ref, 10);
         return { height: String(_nullishCoalesce(info.confirmedRound, () => ( 0))) };
       } catch (err) {
-        throw new (0, _chunkFTKVCP6Kcjs.ConfirmationTimeoutError)(`Algorand tx ${ref} did not confirm in time.`, {
+        throw new (0, _chunkPA6YD3HLcjs.ConfirmationTimeoutError)(`Algorand tx ${ref} did not confirm in time.`, {
           cause: err
         });
       }
     },
     async estimateCost() {
-      return _chunkFTKVCP6Kcjs.nativeCost.call(void 0, {
+      return _chunkPA6YD3HLcjs.nativeCost.call(void 0, {
         symbol: ALGO_SYMBOL,
         decimals: ALGO_DECIMALS,
         fee: 1000n,

package/dist/{algorand-7EUZYL2Z.js → algorand-F3OYB534.js}

@@ -7,7 +7,7 @@ import {
   nativeCost,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-H3A4KWLJ.js";
+} from "./chunk-ILPABTI2.js";
 
 // src/drivers/algorand/index.ts
 import algosdk2 from "algosdk";

package/dist/{aptos-WDWZOU25.cjs → aptos-GJGIZHNI.cjs}

@@ -6,7 +6,7 @@
 
 
 
-var _chunkFTKVCP6Kcjs = require('./chunk-FTKVCP6K.cjs');
+var _chunkPA6YD3HLcjs = require('./chunk-PA6YD3HL.cjs');
 
 // src/drivers/aptos/index.ts
 var _tssdk = require('@aptos-labs/ts-sdk');
@@ -55,14 +55,14 @@ async function payAptos(params) {
     const res = await client.signSubmit({ signer, transaction });
     return res.hash;
   } catch (err) {
-    if (err instanceof _chunkFTKVCP6Kcjs.InsufficientFundsError) throw err;
+    if (err instanceof _chunkPA6YD3HLcjs.InsufficientFundsError) throw err;
     if (isAptosAffordability(err)) {
-      throw new (0, _chunkFTKVCP6Kcjs.InsufficientFundsError)(
+      throw new (0, _chunkPA6YD3HLcjs.InsufficientFundsError)(
         err instanceof Error ? err.message : "Insufficient APT/token balance for the payment.",
         { cause: err }
       );
     }
-    throw _nullishCoalesce(_chunkFTKVCP6Kcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
+    throw _nullishCoalesce(_chunkPA6YD3HLcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
   }
 }
 function isAptosAffordability(err) {
@@ -146,22 +146,22 @@ function txNotFound(hash) {
 
 function assertAptosWallet(wallet, network) {
   if (typeof wallet !== "object" || wallet === null) {
-    throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Aptos; wallet must be { privateKey } (ed25519-priv-0x\u2026) or { account }.`
     );
   }
   if ("walletClient" in wallet) {
-    throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Aptos; a viem { walletClient } can't be used \u2014 pass { privateKey } (ed25519-priv-0x\u2026) or { account }.`
     );
   }
   if ("secretKey" in wallet || "signer" in wallet || "mnemonic" in wallet || "keypair" in wallet || "keyPair" in wallet || "secret" in wallet || "seed" in wallet || "accountId" in wallet) {
-    throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Aptos; that looks like another family's wallet \u2014 pass { privateKey } (ed25519-priv-0x\u2026) or { account }.`
     );
   }
   if (!("privateKey" in wallet) && !("account" in wallet)) {
-    throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)(
+    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
       `chain ${network} is Aptos; wallet must be { privateKey } (ed25519-priv-0x\u2026) or { account }.`
     );
   }
@@ -173,13 +173,13 @@ function resolveAptosAccount(config) {
     try {
       return _tssdk.Account.fromPrivateKey({ privateKey: new (0, _tssdk.Ed25519PrivateKey)(config.privateKey) });
     } catch (cause) {
-      throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)(
+      throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
         "Aptos wallet { privateKey } is not a valid ed25519 secret (ed25519-priv-0x\u2026 or 0x\u2026 hex).",
         { cause }
       );
     }
   }
-  throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)("Aptos wallet needs { privateKey } (ed25519-priv-0x\u2026) or { account }.");
+  throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)("Aptos wallet needs { privateKey } (ed25519-priv-0x\u2026) or { account }.");
 }
 
 // src/drivers/aptos/index.ts
@@ -251,16 +251,16 @@ function makeAptosNetwork(preset, rpcUrl) {
         const info = preset.tokens[token.toUpperCase()];
         if (!info) {
           const known = Object.keys(preset.tokens).join(", ") || "(none built in)";
-          throw new (0, _chunkFTKVCP6Kcjs.UnknownTokenError)(
+          throw new (0, _chunkPA6YD3HLcjs.UnknownTokenError)(
             `token "${token}" isn't built in for Aptos (known: ${known}). Pass { metadata, decimals } for a custom Fungible Asset, or use 'native'.`
           );
         }
         return { asset: info.metadata, decimals: info.decimals, symbol: info.symbol };
       }
-      _chunkFTKVCP6Kcjs.rejectForeignToken.call(void 0, token, "aptos", network);
+      _chunkPA6YD3HLcjs.rejectForeignToken.call(void 0, token, "aptos", network);
       const t = token;
       if (!t.metadata || typeof t.decimals !== "number") {
-        throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)(
+        throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
           `chain ${network} is Aptos; a custom token must be { metadata, decimals }.`
         );
       }
@@ -287,7 +287,7 @@ function makeAptosNetwork(preset, rpcUrl) {
         valid = false;
       }
       if (!valid || evmLike) {
-        throw new (0, _chunkFTKVCP6Kcjs.WrongFamilyError)(
+        throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
           `chain ${network} is Aptos, but payTo "${payTo}" is not a valid Aptos address (0x + 32 bytes).`
         );
       }
@@ -309,11 +309,11 @@ function makeAptosNetwork(preset, rpcUrl) {
         const tx = await aptos.waitForTransaction({ transactionHash: ref });
         return { height: String(_nullishCoalesce(tx.version, () => ( "0"))) };
       } catch (err) {
-        throw new (0, _chunkFTKVCP6Kcjs.ConfirmationTimeoutError)(`Aptos tx ${ref} did not finalize in time.`, { cause: err });
+        throw new (0, _chunkPA6YD3HLcjs.ConfirmationTimeoutError)(`Aptos tx ${ref} did not finalize in time.`, { cause: err });
       }
     },
     async estimateCost() {
-      return _chunkFTKVCP6Kcjs.nativeCost.call(void 0, {
+      return _chunkPA6YD3HLcjs.nativeCost.call(void 0, {
         symbol: APT_SYMBOL,
         decimals: APT_DECIMALS,
         fee: 100000n,

package/dist/{aptos-CDEYDDM5.js → aptos-SUXOVP7B.js}

@@ -6,7 +6,7 @@ import {
   nativeCost,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-H3A4KWLJ.js";
+} from "./chunk-ILPABTI2.js";
 
 // src/drivers/aptos/index.ts
 import { Aptos, AptosConfig, Network, AccountAddress } from "@aptos-labs/ts-sdk";

package/dist/{chunk-H3A4KWLJ.js → chunk-ILPABTI2.js}

@@ -53,6 +53,12 @@ var MaxRetriesExceededError = class extends PipRailError {
 };
 var PaymentDeclinedError = class extends PipRailError {
   code = "PAYMENT_DECLINED";
+  /** Why it was declined, as a typed enum (a hint; `.code` is the reliable channel). */
+  reasonCode;
+  constructor(message, options) {
+    super(message, options);
+    this.reasonCode = options?.reasonCode;
+  }
 };
 var ConfirmationTimeoutError = class extends PipRailError {
   code = "CONFIRMATION_TIMEOUT";

package/dist/{chunk-FTKVCP6K.cjs → chunk-PA6YD3HL.cjs}

@@ -51,37 +51,43 @@ var MaxRetriesExceededError = (_class5 = class extends PipRailError {
     this.ref = _optionalChain([options, 'optionalAccess', _2 => _2.ref]);
   }
 }, _class5);
-var PaymentDeclinedError = (_class6 = class extends PipRailError {constructor(...args4) { super(...args4); _class6.prototype.__init6.call(this); }
+var PaymentDeclinedError = (_class6 = class extends PipRailError {
   __init6() {this.code = "PAYMENT_DECLINED"}
+  /** Why it was declined, as a typed enum (a hint; `.code` is the reliable channel). */
+  
+  constructor(message, options) {
+    super(message, options);_class6.prototype.__init6.call(this);;
+    this.reasonCode = _optionalChain([options, 'optionalAccess', _3 => _3.reasonCode]);
+  }
 }, _class6);
-var ConfirmationTimeoutError = (_class7 = class extends PipRailError {constructor(...args5) { super(...args5); _class7.prototype.__init7.call(this); }
+var ConfirmationTimeoutError = (_class7 = class extends PipRailError {constructor(...args4) { super(...args4); _class7.prototype.__init7.call(this); }
   __init7() {this.code = "CONFIRMATION_TIMEOUT"}
 }, _class7);
-var SettlementError = (_class8 = class extends PipRailError {constructor(...args6) { super(...args6); _class8.prototype.__init8.call(this); }
+var SettlementError = (_class8 = class extends PipRailError {constructor(...args5) { super(...args5); _class8.prototype.__init8.call(this); }
   __init8() {this.code = "SETTLEMENT_FAILED"}
 }, _class8);
-var InvalidEnvelopeError = (_class9 = class extends PipRailError {constructor(...args7) { super(...args7); _class9.prototype.__init9.call(this); }
+var InvalidEnvelopeError = (_class9 = class extends PipRailError {constructor(...args6) { super(...args6); _class9.prototype.__init9.call(this); }
   __init9() {this.code = "INVALID_ENVELOPE"}
 }, _class9);
-var NoCompatibleAcceptError = (_class10 = class extends PipRailError {constructor(...args8) { super(...args8); _class10.prototype.__init10.call(this); }
+var NoCompatibleAcceptError = (_class10 = class extends PipRailError {constructor(...args7) { super(...args7); _class10.prototype.__init10.call(this); }
   __init10() {this.code = "NO_COMPATIBLE_ACCEPT"}
 }, _class10);
-var UnsupportedSchemeError = (_class11 = class extends PipRailError {constructor(...args9) { super(...args9); _class11.prototype.__init11.call(this); }
+var UnsupportedSchemeError = (_class11 = class extends PipRailError {constructor(...args8) { super(...args8); _class11.prototype.__init11.call(this); }
   __init11() {this.code = "UNSUPPORTED_SCHEME"}
 }, _class11);
-var NonReplayableBodyError = (_class12 = class extends PipRailError {constructor(...args10) { super(...args10); _class12.prototype.__init12.call(this); }
+var NonReplayableBodyError = (_class12 = class extends PipRailError {constructor(...args9) { super(...args9); _class12.prototype.__init12.call(this); }
   __init12() {this.code = "NON_REPLAYABLE_BODY"}
 }, _class12);
-var WrongFamilyError = (_class13 = class extends PipRailError {constructor(...args11) { super(...args11); _class13.prototype.__init13.call(this); }
+var WrongFamilyError = (_class13 = class extends PipRailError {constructor(...args10) { super(...args10); _class13.prototype.__init13.call(this); }
   __init13() {this.code = "WRONG_FAMILY"}
 }, _class13);
-var UnknownTokenError = (_class14 = class extends PipRailError {constructor(...args12) { super(...args12); _class14.prototype.__init14.call(this); }
+var UnknownTokenError = (_class14 = class extends PipRailError {constructor(...args11) { super(...args11); _class14.prototype.__init14.call(this); }
   __init14() {this.code = "UNKNOWN_TOKEN"}
 }, _class14);
-var MissingDriverError = (_class15 = class extends PipRailError {constructor(...args13) { super(...args13); _class15.prototype.__init15.call(this); }
+var MissingDriverError = (_class15 = class extends PipRailError {constructor(...args12) { super(...args12); _class15.prototype.__init15.call(this); }
   __init15() {this.code = "MISSING_DRIVER"}
 }, _class15);
-var UnsupportedNetworkError = (_class16 = class extends PipRailError {constructor(...args14) { super(...args14); _class16.prototype.__init16.call(this); }
+var UnsupportedNetworkError = (_class16 = class extends PipRailError {constructor(...args13) { super(...args13); _class16.prototype.__init16.call(this); }
   __init16() {this.code = "UNSUPPORTED_NETWORK"}
 }, _class16);