@piprail/sdk 2.0.0 → 2.0.1

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/).
 
+## [2.0.1] — 2026-06-15 — clearer typed errors (robustness; no API change)
+
+A patch release hardening error reporting at every wrong-input boundary — found by a
+repo-wide adversarial fuzzing pass. **No behaviour change for correct input**, no API change;
+every fix turns a raw/cryptic library error into a typed `PipRailError` per [`ERRORS.md`](ERRORS.md).
+
+### Fixed
+
+- **Wallet `{ key }` validation is now uniform + typed.** A malformed or wrong-family key throws a
+  clear `WrongFamilyError` instead of leaking a library error:
+  - **EVM** — a non-`0x…`/short/garbage key (e.g. a base58 secret, or one missing `0x`) →
+    `WrongFamilyError` (was viem's raw `invalid private key, expected hex or 32 bytes`).
+  - **Solana** — a `0x…` EVM key or non-base58 secret → `WrongFamilyError` (was `Non-base58 character`).
+  - **TON** — an invalid/typo'd mnemonic → `WrongFamilyError` at use (was a silent **wrong-wallet**
+    derivation that only failed later as an opaque network error); now validated via `mnemonicValidate`.
+- **A malformed 402 challenge yields a typed `InvalidEnvelopeError`, never a raw `TypeError`.** An
+  `accepts[]` entry missing its `extra` block (on an unrecognised token), or a non-string `amount`,
+  is now rejected cleanly across `quote` / `estimateCost` / `planPayment` / `canAfford` / `fetch`
+  (a recognised token still prices gracefully from the SDK's own decimals).
+- **Read-only agent tools funnel expected errors into a structured result.** `piprail_quote_payment`,
+  `piprail_plan_payment`, `piprail_discover`, `piprail_register`, and `piprail_budget` now return
+  `{ ok:false, code, reason, explain }` for a typed SDK error (e.g. `WALLET_REQUIRED` on a read-only
+  client) — mirroring `piprail_pay_request` — instead of an opaque error; a genuine non-SDK error is
+  still re-thrown.
+- **A no-gas wallet's settlement failure maps to `InsufficientFundsError`.** viem's gas-estimation
+  shortfall phrasing (`gas required exceeds allowance`) is now classified as `INSUFFICIENT_FUNDS`
+  (was a raw multi-line viem dump); an ERC-20 `insufficient allowance` (approve) is deliberately NOT
+  mis-classified.
+
 ## [2.0.0] — 2026-06-15 — one wallet field: `key` (BREAKING)
 
 ### Changed — the wallet secret is a single `key` field on every chain (BREAKING)
@@ -1102,6 +1131,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.0.1]: https://www.npmjs.com/package/@piprail/sdk
 [2.0.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.25.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.24.0]: https://www.npmjs.com/package/@piprail/sdk

package/dist/{algorand-RJ4DRWHV.js → algorand-GSFVZTBF.js}

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

package/dist/{algorand-RUDF55XY.cjs → algorand-HZS43N4P.cjs}

@@ -8,7 +8,7 @@
 
 
 
-var _chunkDKQXW454cjs = require('./chunk-DKQXW454.cjs');
+var _chunkJG6KRAW6cjs = require('./chunk-JG6KRAW6.cjs');
 
 // src/drivers/algorand/index.ts
 var _algosdk = require('algosdk'); var _algosdk2 = _interopRequireDefault(_algosdk);
@@ -56,13 +56,13 @@ async function payAlgorand(params) {
   } catch (err) {
     const mapped = mapAlgorandError(err, accept.payTo);
     if (mapped) throw mapped;
-    throw _nullishCoalesce(_chunkDKQXW454cjs.toInsufficientFundsError.call(void 0, err), () => ( err));
+    throw _nullishCoalesce(_chunkJG6KRAW6cjs.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, _chunkDKQXW454cjs.RecipientNotReadyError)(
+    return new (0, _chunkJG6KRAW6cjs.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 }
     );
@@ -70,7 +70,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, _chunkDKQXW454cjs.InsufficientFundsError)(
+    return new (0, _chunkJG6KRAW6cjs.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 }
     );
@@ -158,13 +158,13 @@ function rpcFailed(nonce) {
 
 function assertAlgorandWallet(wallet, network) {
   if (typeof wallet !== "object" || wallet === null) {
-    throw new (0, _chunkDKQXW454cjs.WrongFamilyError)(
+    throw new (0, _chunkJG6KRAW6cjs.WrongFamilyError)(
       `chain ${network} is Algorand; wallet must be { key } (25-word mnemonic) or { account }.`
     );
   }
-  _chunkDKQXW454cjs.assertNoLegacyWalletKey.call(void 0, wallet, "Algorand");
+  _chunkJG6KRAW6cjs.assertNoLegacyWalletKey.call(void 0, wallet, "Algorand");
   if (!("key" in wallet) && !("account" in wallet)) {
-    throw new (0, _chunkDKQXW454cjs.WrongFamilyError)(
+    throw new (0, _chunkJG6KRAW6cjs.WrongFamilyError)(
       `chain ${network} is Algorand; wallet must be { key } (25-word mnemonic) or { account }.`
     );
   }
@@ -179,13 +179,13 @@ function resolveAlgorandWallet(config) {
       const { addr, sk } = _algosdk2.default.mnemonicToSecretKey(config.key);
       return { addr: addr.toString(), sk };
     } catch (cause) {
-      throw new (0, _chunkDKQXW454cjs.WrongFamilyError)(
+      throw new (0, _chunkJG6KRAW6cjs.WrongFamilyError)(
         "Algorand wallet { key } is not a valid 25-word Algorand mnemonic.",
         { cause }
       );
     }
   }
-  throw new (0, _chunkDKQXW454cjs.WrongFamilyError)("Algorand wallet needs { key } (25-word mnemonic) or { account }.");
+  throw new (0, _chunkJG6KRAW6cjs.WrongFamilyError)("Algorand wallet needs { key } (25-word mnemonic) or { account }.");
 }
 
 // src/drivers/algorand/index.ts
@@ -240,16 +240,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, _chunkDKQXW454cjs.UnknownTokenError)(
+          throw new (0, _chunkJG6KRAW6cjs.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 };
       }
-      _chunkDKQXW454cjs.rejectForeignToken.call(void 0, token, "algorand", network);
+      _chunkJG6KRAW6cjs.rejectForeignToken.call(void 0, token, "algorand", network);
       const t = token;
       if (typeof t.assetId !== "number" || typeof t.decimals !== "number") {
-        throw new (0, _chunkDKQXW454cjs.WrongFamilyError)(
+        throw new (0, _chunkJG6KRAW6cjs.WrongFamilyError)(
           `chain ${network} is Algorand; a custom token must be { assetId, decimals }.`
         );
       }
@@ -270,12 +270,12 @@ function makeAlgorandNetwork(preset, algodUrl) {
     },
     assertValidPayTo(payTo) {
       if (payTo.startsWith("0x")) {
-        throw new (0, _chunkDKQXW454cjs.WrongFamilyError)(
+        throw new (0, _chunkJG6KRAW6cjs.WrongFamilyError)(
           `chain ${network} is Algorand, but payTo "${payTo}" looks like an EVM address.`
         );
       }
       if (!_algosdk2.default.isValidAddress(payTo)) {
-        throw new (0, _chunkDKQXW454cjs.WrongFamilyError)(
+        throw new (0, _chunkJG6KRAW6cjs.WrongFamilyError)(
           `chain ${network} is Algorand, but payTo "${payTo}" is not a valid Algorand address.`
         );
       }
@@ -292,13 +292,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, _chunkDKQXW454cjs.ConfirmationTimeoutError)(`Algorand tx ${ref} did not confirm in time.`, {
+        throw new (0, _chunkJG6KRAW6cjs.ConfirmationTimeoutError)(`Algorand tx ${ref} did not confirm in time.`, {
           cause: err
         });
       }
     },
     async estimateCost() {
-      return _chunkDKQXW454cjs.nativeCost.call(void 0, {
+      return _chunkJG6KRAW6cjs.nativeCost.call(void 0, {
         symbol: ALGO_SYMBOL,
         decimals: ALGO_DECIMALS,
         fee: 1000n,

package/dist/{aptos-SMEQXIYJ.js → aptos-RIL56C7L.js}

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

package/dist/{aptos-PESRG2EQ.cjs → aptos-TRCCJRZA.cjs}

@@ -7,7 +7,7 @@
 
 
 
-var _chunkDKQXW454cjs = require('./chunk-DKQXW454.cjs');
+var _chunkJG6KRAW6cjs = require('./chunk-JG6KRAW6.cjs');
 
 // src/drivers/aptos/index.ts
 var _tssdk = require('@aptos-labs/ts-sdk');
@@ -56,14 +56,14 @@ async function payAptos(params) {
     const res = await client.signSubmit({ signer, transaction });
     return res.hash;
   } catch (err) {
-    if (err instanceof _chunkDKQXW454cjs.InsufficientFundsError) throw err;
+    if (err instanceof _chunkJG6KRAW6cjs.InsufficientFundsError) throw err;
     if (isAptosAffordability(err)) {
-      throw new (0, _chunkDKQXW454cjs.InsufficientFundsError)(
+      throw new (0, _chunkJG6KRAW6cjs.InsufficientFundsError)(
         err instanceof Error ? err.message : "Insufficient APT/token balance for the payment.",
         { cause: err }
       );
     }
-    throw _nullishCoalesce(_chunkDKQXW454cjs.toInsufficientFundsError.call(void 0, err), () => ( err));
+    throw _nullishCoalesce(_chunkJG6KRAW6cjs.toInsufficientFundsError.call(void 0, err), () => ( err));
   }
 }
 function isAptosAffordability(err) {
@@ -147,13 +147,13 @@ function txNotFound(hash) {
 
 function assertAptosWallet(wallet, network) {
   if (typeof wallet !== "object" || wallet === null) {
-    throw new (0, _chunkDKQXW454cjs.WrongFamilyError)(
+    throw new (0, _chunkJG6KRAW6cjs.WrongFamilyError)(
       `chain ${network} is Aptos; wallet must be { key } (ed25519-priv-0x\u2026) or { account }.`
     );
   }
-  _chunkDKQXW454cjs.assertNoLegacyWalletKey.call(void 0, wallet, "Aptos");
+  _chunkJG6KRAW6cjs.assertNoLegacyWalletKey.call(void 0, wallet, "Aptos");
   if (!("key" in wallet) && !("account" in wallet)) {
-    throw new (0, _chunkDKQXW454cjs.WrongFamilyError)(
+    throw new (0, _chunkJG6KRAW6cjs.WrongFamilyError)(
       `chain ${network} is Aptos; wallet must be { key } (ed25519-priv-0x\u2026) or { account }.`
     );
   }
@@ -165,13 +165,13 @@ function resolveAptosAccount(config) {
     try {
       return _tssdk.Account.fromPrivateKey({ privateKey: new (0, _tssdk.Ed25519PrivateKey)(config.key) });
     } catch (cause) {
-      throw new (0, _chunkDKQXW454cjs.WrongFamilyError)(
+      throw new (0, _chunkJG6KRAW6cjs.WrongFamilyError)(
         "Aptos wallet { key } is not a valid ed25519 secret (ed25519-priv-0x\u2026 or 0x\u2026 hex).",
         { cause }
       );
     }
   }
-  throw new (0, _chunkDKQXW454cjs.WrongFamilyError)("Aptos wallet needs { key } (ed25519-priv-0x\u2026) or { account }.");
+  throw new (0, _chunkJG6KRAW6cjs.WrongFamilyError)("Aptos wallet needs { key } (ed25519-priv-0x\u2026) or { account }.");
 }
 
 // src/drivers/aptos/index.ts
@@ -243,16 +243,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, _chunkDKQXW454cjs.UnknownTokenError)(
+          throw new (0, _chunkJG6KRAW6cjs.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 };
       }
-      _chunkDKQXW454cjs.rejectForeignToken.call(void 0, token, "aptos", network);
+      _chunkJG6KRAW6cjs.rejectForeignToken.call(void 0, token, "aptos", network);
       const t = token;
       if (!t.metadata || typeof t.decimals !== "number") {
-        throw new (0, _chunkDKQXW454cjs.WrongFamilyError)(
+        throw new (0, _chunkJG6KRAW6cjs.WrongFamilyError)(
           `chain ${network} is Aptos; a custom token must be { metadata, decimals }.`
         );
       }
@@ -279,7 +279,7 @@ function makeAptosNetwork(preset, rpcUrl) {
         valid = false;
       }
       if (!valid || evmLike) {
-        throw new (0, _chunkDKQXW454cjs.WrongFamilyError)(
+        throw new (0, _chunkJG6KRAW6cjs.WrongFamilyError)(
           `chain ${network} is Aptos, but payTo "${payTo}" is not a valid Aptos address (0x + 32 bytes).`
         );
       }
@@ -301,11 +301,11 @@ function makeAptosNetwork(preset, rpcUrl) {
         const tx = await aptos.waitForTransaction({ transactionHash: ref });
         return { height: String(_nullishCoalesce(tx.version, () => ( "0"))) };
       } catch (err) {
-        throw new (0, _chunkDKQXW454cjs.ConfirmationTimeoutError)(`Aptos tx ${ref} did not finalize in time.`, { cause: err });
+        throw new (0, _chunkJG6KRAW6cjs.ConfirmationTimeoutError)(`Aptos tx ${ref} did not finalize in time.`, { cause: err });
       }
     },
     async estimateCost() {
-      return _chunkDKQXW454cjs.nativeCost.call(void 0, {
+      return _chunkJG6KRAW6cjs.nativeCost.call(void 0, {
         symbol: APT_SYMBOL,
         decimals: APT_DECIMALS,
         fee: 100000n,

package/dist/{chunk-47VEOHZN.js → chunk-7XK22JSQ.js}

@@ -13,7 +13,7 @@ var RecipientNotReadyError = class extends PipRailError {
 };
 function toInsufficientFundsError(err) {
   const message = err instanceof Error ? err.message : String(err);
-  if (/insufficient (funds|balance|lamports|fee)|not enough|exceeds (the )?balance|underfunded|low[_ ]?reserve|debit the account/i.test(
+  if (/insufficient (funds|balance|lamports|fee)|not enough|exceeds (the )?balance|underfunded|low[_ ]?reserve|debit the account|gas required exceeds (the )?allowance/i.test(
     message
   )) {
     return new InsufficientFundsError(

package/dist/{chunk-DKQXW454.cjs → chunk-JG6KRAW6.cjs}

@@ -13,7 +13,7 @@ var RecipientNotReadyError = (_class2 = class extends PipRailError {constructor(
 }, _class2);
 function toInsufficientFundsError(err) {
   const message = err instanceof Error ? err.message : String(err);
-  if (/insufficient (funds|balance|lamports|fee)|not enough|exceeds (the )?balance|underfunded|low[_ ]?reserve|debit the account/i.test(
+  if (/insufficient (funds|balance|lamports|fee)|not enough|exceeds (the )?balance|underfunded|low[_ ]?reserve|debit the account|gas required exceeds (the )?allowance/i.test(
     message
   )) {
     return new InsufficientFundsError(