@piprail/sdk 1.25.0 → 2.0.1

package/dist/index.d.cts

@@ -4878,44 +4878,42 @@ type PipRailEvent = {
     reason: string;
 };
 /**
- * Wallet for the chosen chain family (the `chain` selector routes; each driver
- * validates its own key format):
- *   - EVM     → `{ privateKey }` (0x… hex) or a viem `{ walletClient }`
- *   - Tron    → `{ privateKey }` (32-byte hex — secp256k1, like EVM)
- *   - Sui     → `{ privateKey }` (suiprivkey1… bech32) or a ready `{ keypair }`
- *   - Solana  → `{ secretKey }` (Uint8Array | base58) or `{ signer }`
- *   - TON     → `{ mnemonic }` (24 words) or a ready `{ keyPair }`
- *   - Stellar → `{ secret }` (S… seed) or a ready `{ keypair }`
- *   - XRPL    → `{ seed }` (s… seed) or a ready `{ wallet }`
- *   - NEAR    → `{ accountId, privateKey }` (privateKey = ed25519:… secret)
- *   - Aptos   → `{ privateKey }` (AIP-80 `ed25519-priv-0x…` / raw `0x…` hex) or `{ account }`
- *   - Algorand→ `{ mnemonic }` (25 words) or a ready `{ account }`
+ * Wallet for the chosen chain family. **One field, every chain: `{ key }`** — the
+ * chain's secret as a string (the `chain` selector routes; each driver validates the
+ * format). NEAR also needs `{ accountId }`. What `key` is, per chain:
+ *   - EVM / Tron     → a 0x… hex private key (secp256k1)
+ *   - Sui            → a `suiprivkey1…` bech32 secret
+ *   - Aptos          → an AIP-80 `ed25519-priv-0x…` (or raw `0x…`) secret
+ *   - Solana         → a base58 secret key (or a `Uint8Array`)
+ *   - TON            → a 24-word mnemonic  (optional `version: 'v4' | 'v5r1'`, default v4)
+ *   - Algorand       → a 25-word mnemonic
+ *   - Stellar        → an `S…` secret seed
+ *   - XRPL           → an `s…` secret seed
+ *   - NEAR           → `{ accountId, key }`, where `key` is an `ed25519:…` secret
+ *
+ * Advanced (bring your own native signer object — type-specific): EVM `{ walletClient }`,
+ * Solana `{ signer }`, TON `{ keyPair }`, Stellar/Sui `{ keypair }`, XRPL `{ wallet }`,
+ * Aptos/Algorand `{ account }`.
  */
 type WalletInput = {
-    privateKey: string;
+    key: string;
+    version?: 'v4' | 'v5r1';
 } | {
-    walletClient: unknown;
+    accountId: string;
+    key: string;
 } | {
-    secretKey: Uint8Array | string;
+    walletClient: unknown;
 } | {
     signer: unknown;
-} | {
-    mnemonic: string | string[];
-    version?: 'v4' | 'v5r1';
 } | {
     keyPair: unknown;
     version?: 'v4' | 'v5r1';
-} | {
-    secret: string;
 } | {
     keypair: unknown;
-} | {
-    seed: string;
 } | {
     wallet: unknown;
 } | {
-    accountId: string;
-    privateKey: string;
+    account: unknown;
 };
 /**
  * A priced payment requirement — what `client.quote(url)` returns and what an
@@ -5228,6 +5226,15 @@ declare class PipRailClient {
     private readonly ledger;
     private bound?;
     constructor(opts: PipRailClientOptions);
+    /**
+     * Fail LOUDLY at construction on a malformed amount cap — a security boundary
+     * must never silently half-arm, and a misconfigured cap is a programmer error
+     * (→ `TypeError`, no new SDK code). Each cap (`maxAmount` / `maxTotal` /
+     * `windowTotal`) must be a non-negative decimal STRING (the same grammar
+     * {@link floorUnits} accepts), so a typo like `'0.01abc'` fails fast here instead
+     * of lazily throwing a raw `floorUnits` error out of the never-throw read methods.
+     */
+    private assertPolicyAmountCaps;
     /**
      * Fail LOUDLY at construction on a misconfigured time policy — a security
      * boundary must never silently half-arm. Two invariants (a misconfiguration is
@@ -5540,8 +5547,8 @@ declare function fetchAcross(clients: PipRailClient[], url: string, init?: Reque
  * `'solana'|'ton'|'tron'|'near'|'sui'|'aptos'|'algorand'|'stellar'|'xrpl'`); the
  * VALUE is that family's {@link WalletInput}:
  *
- *   base/bnb/… → { privateKey }   solana → { secretKey }   ton/algorand → { mnemonic }
- *   stellar → { secret }   xrpl → { seed }   near → { accountId, privateKey }
+ *   every chain → { key }   ·   near → { accountId, key }
+ *   (`key` is that chain's secret string — see {@link WalletInput} for the per-chain format)
  *
  * One key per family — this map is how a single buyer carries the keys for every
  * chain it's willing to pay on. (For a CUSTOM EVM chain configured by a viem
@@ -5588,9 +5595,9 @@ declare class MultiChainPayer implements PayingClient {
      * ```ts
      * const payer = MultiChainPayer.fromWallets({
      *   wallets: {
-     *     base:    { privateKey: process.env.EVM_KEY! },
-     *     solana:  { secretKey:  process.env.SOLANA_SECRET! },
-     *     xrpl:    { seed:       process.env.XRPL_SEED! },
+     *     base:    { key: process.env.EVM_KEY! },
+     *     solana:  { key: process.env.SOLANA_SECRET! },
+     *     xrpl:    { key: process.env.XRPL_SEED! },
      *   },
      *   policy: { maxAmount: '1.00', maxTotal: '20.00', tokens: ['USDC', 'USDT'] },
      * })
@@ -5952,7 +5959,8 @@ interface ManifestInput {
      * Optional ownership proofs — each a signature of the BARE ORIGIN STRING by a
      * `payTo` key (EVM: eip191 hex). A trust badge on indexes that verify it
      * (x402scan: `recoverMessageAddress(origin, sig) === payTo`); never required to
-     * be listed. Produce one with the driver's `signMessage(wallet, origin)`.
+     * be listed. Produce one via `client.discoverySigner()`, then `signer.signMessage(origin)`
+     * (single-arg — it signs the bare origin string).
      */
     ownershipProofs?: string[];
     /** OpenAPI `info.title`. Default 'PipRail x402 resources'. */
@@ -6171,8 +6179,8 @@ interface ExactRailOption {
          *  discovers it automatically (e.g. PayAI). Ignored on EVM. */
         feePayer?: string;
     };
-    /** Required for `settle: 'self'` — the gas-paying relayer wallet: EVM `{ privateKey }` /
-     *  `{ walletClient }`, or Solana `{ secretKey }` / `{ signer }`. (Distinct from `payTo`, the
+    /** Required for `settle: 'self'` — the gas-paying relayer wallet: a `{ key }` (or a
+     *  bring-your-own EVM `{ walletClient }` / Solana `{ signer }`). (Distinct from `payTo`, the
      *  receive address — on Solana they MUST be different keys, a scheme MUST-rule.) */
     relayer?: unknown;
     /** Which exact transfer method to advertise (EVM). `'auto'` (default) uses EIP-3009 when the

package/dist/index.d.ts

@@ -4878,44 +4878,42 @@ type PipRailEvent = {
     reason: string;
 };
 /**
- * Wallet for the chosen chain family (the `chain` selector routes; each driver
- * validates its own key format):
- *   - EVM     → `{ privateKey }` (0x… hex) or a viem `{ walletClient }`
- *   - Tron    → `{ privateKey }` (32-byte hex — secp256k1, like EVM)
- *   - Sui     → `{ privateKey }` (suiprivkey1… bech32) or a ready `{ keypair }`
- *   - Solana  → `{ secretKey }` (Uint8Array | base58) or `{ signer }`
- *   - TON     → `{ mnemonic }` (24 words) or a ready `{ keyPair }`
- *   - Stellar → `{ secret }` (S… seed) or a ready `{ keypair }`
- *   - XRPL    → `{ seed }` (s… seed) or a ready `{ wallet }`
- *   - NEAR    → `{ accountId, privateKey }` (privateKey = ed25519:… secret)
- *   - Aptos   → `{ privateKey }` (AIP-80 `ed25519-priv-0x…` / raw `0x…` hex) or `{ account }`
- *   - Algorand→ `{ mnemonic }` (25 words) or a ready `{ account }`
+ * Wallet for the chosen chain family. **One field, every chain: `{ key }`** — the
+ * chain's secret as a string (the `chain` selector routes; each driver validates the
+ * format). NEAR also needs `{ accountId }`. What `key` is, per chain:
+ *   - EVM / Tron     → a 0x… hex private key (secp256k1)
+ *   - Sui            → a `suiprivkey1…` bech32 secret
+ *   - Aptos          → an AIP-80 `ed25519-priv-0x…` (or raw `0x…`) secret
+ *   - Solana         → a base58 secret key (or a `Uint8Array`)
+ *   - TON            → a 24-word mnemonic  (optional `version: 'v4' | 'v5r1'`, default v4)
+ *   - Algorand       → a 25-word mnemonic
+ *   - Stellar        → an `S…` secret seed
+ *   - XRPL           → an `s…` secret seed
+ *   - NEAR           → `{ accountId, key }`, where `key` is an `ed25519:…` secret
+ *
+ * Advanced (bring your own native signer object — type-specific): EVM `{ walletClient }`,
+ * Solana `{ signer }`, TON `{ keyPair }`, Stellar/Sui `{ keypair }`, XRPL `{ wallet }`,
+ * Aptos/Algorand `{ account }`.
  */
 type WalletInput = {
-    privateKey: string;
+    key: string;
+    version?: 'v4' | 'v5r1';
 } | {
-    walletClient: unknown;
+    accountId: string;
+    key: string;
 } | {
-    secretKey: Uint8Array | string;
+    walletClient: unknown;
 } | {
     signer: unknown;
-} | {
-    mnemonic: string | string[];
-    version?: 'v4' | 'v5r1';
 } | {
     keyPair: unknown;
     version?: 'v4' | 'v5r1';
-} | {
-    secret: string;
 } | {
     keypair: unknown;
-} | {
-    seed: string;
 } | {
     wallet: unknown;
 } | {
-    accountId: string;
-    privateKey: string;
+    account: unknown;
 };
 /**
  * A priced payment requirement — what `client.quote(url)` returns and what an
@@ -5228,6 +5226,15 @@ declare class PipRailClient {
     private readonly ledger;
     private bound?;
     constructor(opts: PipRailClientOptions);
+    /**
+     * Fail LOUDLY at construction on a malformed amount cap — a security boundary
+     * must never silently half-arm, and a misconfigured cap is a programmer error
+     * (→ `TypeError`, no new SDK code). Each cap (`maxAmount` / `maxTotal` /
+     * `windowTotal`) must be a non-negative decimal STRING (the same grammar
+     * {@link floorUnits} accepts), so a typo like `'0.01abc'` fails fast here instead
+     * of lazily throwing a raw `floorUnits` error out of the never-throw read methods.
+     */
+    private assertPolicyAmountCaps;
     /**
      * Fail LOUDLY at construction on a misconfigured time policy — a security
      * boundary must never silently half-arm. Two invariants (a misconfiguration is
@@ -5540,8 +5547,8 @@ declare function fetchAcross(clients: PipRailClient[], url: string, init?: Reque
  * `'solana'|'ton'|'tron'|'near'|'sui'|'aptos'|'algorand'|'stellar'|'xrpl'`); the
  * VALUE is that family's {@link WalletInput}:
  *
- *   base/bnb/… → { privateKey }   solana → { secretKey }   ton/algorand → { mnemonic }
- *   stellar → { secret }   xrpl → { seed }   near → { accountId, privateKey }
+ *   every chain → { key }   ·   near → { accountId, key }
+ *   (`key` is that chain's secret string — see {@link WalletInput} for the per-chain format)
  *
  * One key per family — this map is how a single buyer carries the keys for every
  * chain it's willing to pay on. (For a CUSTOM EVM chain configured by a viem
@@ -5588,9 +5595,9 @@ declare class MultiChainPayer implements PayingClient {
      * ```ts
      * const payer = MultiChainPayer.fromWallets({
      *   wallets: {
-     *     base:    { privateKey: process.env.EVM_KEY! },
-     *     solana:  { secretKey:  process.env.SOLANA_SECRET! },
-     *     xrpl:    { seed:       process.env.XRPL_SEED! },
+     *     base:    { key: process.env.EVM_KEY! },
+     *     solana:  { key: process.env.SOLANA_SECRET! },
+     *     xrpl:    { key: process.env.XRPL_SEED! },
      *   },
      *   policy: { maxAmount: '1.00', maxTotal: '20.00', tokens: ['USDC', 'USDT'] },
      * })
@@ -5952,7 +5959,8 @@ interface ManifestInput {
      * Optional ownership proofs — each a signature of the BARE ORIGIN STRING by a
      * `payTo` key (EVM: eip191 hex). A trust badge on indexes that verify it
      * (x402scan: `recoverMessageAddress(origin, sig) === payTo`); never required to
-     * be listed. Produce one with the driver's `signMessage(wallet, origin)`.
+     * be listed. Produce one via `client.discoverySigner()`, then `signer.signMessage(origin)`
+     * (single-arg — it signs the bare origin string).
      */
     ownershipProofs?: string[];
     /** OpenAPI `info.title`. Default 'PipRail x402 resources'. */
@@ -6171,8 +6179,8 @@ interface ExactRailOption {
          *  discovers it automatically (e.g. PayAI). Ignored on EVM. */
         feePayer?: string;
     };
-    /** Required for `settle: 'self'` — the gas-paying relayer wallet: EVM `{ privateKey }` /
-     *  `{ walletClient }`, or Solana `{ secretKey }` / `{ signer }`. (Distinct from `payTo`, the
+    /** Required for `settle: 'self'` — the gas-paying relayer wallet: a `{ key }` (or a
+     *  bring-your-own EVM `{ walletClient }` / Solana `{ signer }`). (Distinct from `payTo`, the
      *  receive address — on Solana they MUST be different keys, a scheme MUST-rule.) */
     relayer?: unknown;
     /** Which exact transfer method to advertise (EVM). `'auto'` (default) uses EIP-3009 when the