@piprail/sdk 1.0.0 → 1.1.1

package/dist/index.d.cts

@@ -155,7 +155,7 @@ declare function pickAccept(challenge: X402Challenge, matches: (network: string)
  * Chains are a parameter, and the popular ones are built in.
  *
  * The easy path — name a built-in chain:
- *   requirePayment({ chain: 'base', amount: '0.05', payTo })   // USDC on Base
+ *   requirePayment({ chain: 'base', token: 'USDC', amount: '0.05', payTo })   // USDC on Base
  *
  * The exotic path — ANY EVM chain we don't ship, by viem `Chain` or a bare
  * `{ id, rpcUrl }`, plus the token you want paid in:
@@ -812,7 +812,7 @@ declare const CHAINS: {
                         maxPriorityFeePerGas?: undefined | undefined;
                         isSystemTx?: undefined | undefined;
                         mint?: undefined | undefined;
-                        sourceHash? /** Display name. Defaults to `EVM <id>`. */: undefined | undefined;
+                        sourceHash?: undefined | undefined;
                     } | {
                         blockHash: `0x${string}` | null;
                         blockNumber: bigint | null;
@@ -1580,13 +1580,11 @@ declare const CHAINS: {
                         yParity: number;
                         accessList: viem.AccessList;
                         authorizationList?: undefined | undefined;
-                        blobVersionedHashes?: undefined | undefined;
+                        blobVersionedHashes? /** EVM chain id, e.g. 5000 for Mantle. */: undefined | undefined;
                         chainId: number;
                         type: "eip1559";
                         gasPrice?: undefined | undefined;
-                        maxFeePerBlobGas
-                        /** Native coin metadata. Defaults to 18-decimal ETH. */
-                        ? /** Native coin metadata. Defaults to 18-decimal ETH. */: undefined | undefined;
+                        maxFeePerBlobGas?: undefined | undefined;
                         maxFeePerGas: bigint;
                         maxPriorityFeePerGas: bigint;
                         feeCurrency: abitype.Address | null;
@@ -2984,7 +2982,7 @@ declare const CHAINS: {
                     } | {
                         blockHash: `0x${string}` | null;
                         blockNumber: bigint | null;
-                        blockTimestamp?: bigint | undefined;
+                        blockTimestamp? /** JSON-RPC endpoint. */: bigint | undefined;
                         from: abitype.Address;
                         gas: bigint;
                         hash: viem.Hash;
@@ -3318,10 +3316,8 @@ declare const CHAINS: {
                         yParity?: undefined | undefined;
                         type: "legacy";
                         gasPrice: bigint;
-                        maxFeePerBlobGas
-                        /** JSON-RPC endpoint. */
-                        ? /** JSON-RPC endpoint. */: undefined | undefined;
-                        maxFeePerGas? /** Display name. Defaults to `EVM <id>`. */: undefined | undefined;
+                        maxFeePerBlobGas?: undefined | undefined;
+                        maxFeePerGas?: undefined | undefined;
                         maxPriorityFeePerGas?: undefined | undefined;
                         isSystemTx?: undefined | undefined;
                         mint?: undefined | undefined;
@@ -3931,6 +3927,18 @@ type PipRailEvent = {
     kind: 'payment-confirmed';
     ref: string;
     blockNumber: bigint;
+}
+/**
+ * Broadcast succeeded (we hold `ref`) but LOCAL confirmation timed out — the
+ * RPC was likely lagging/throttled while the tx is in fact on-chain. The proof
+ * is NOT discarded: the client submits it to the server (whose own on-chain
+ * verify is the authority) instead of throwing, so a real payment is never
+ * orphaned into a double-pay. `reason` is the confirm error's message.
+ */
+ | {
+    kind: 'payment-unconfirmed';
+    ref: string;
+    reason: string;
 } | {
     kind: 'payment-settled';
     receipt: X402Receipt | null;
@@ -4049,7 +4057,13 @@ interface PipRailClientOptions {
      * giving up. Default 3, with a short backoff between attempts — this
      * absorbs RPC propagation lag (the server's node briefly trailing the
      * client's, so it hasn't seen the confirmation yet). If the server still
-     * returns 402 on the last attempt the SDK throws `MaxRetriesExceededError`.
+     * returns 402 on the last attempt the SDK throws `MaxRetriesExceededError`
+     * (which carries `.ref` — re-verify, never re-pay).
+     *
+     * If the broadcast succeeded but the client's OWN confirmation timed out
+     * (a throttled RPC), the proof is NOT discarded: the client submits it
+     * anyway and automatically uses MORE patient retries (a floor of 6, longer
+     * backoff), since the on-chain tx may still be settling.
      */
     maxPaymentRetries?: number;
     /** Timeout (ms) for the retry leg after broadcast. Default 30_000. */
@@ -4159,7 +4173,7 @@ declare function paymentTools(client: PipRailClient): AgentTool[];
  *   import { requirePayment } from '@piprail/sdk'
  *
  *   app.get('/report',
- *     requirePayment({ chain: 'base', amount: '0.05', payTo: '0xMerchant…' }),
+ *     requirePayment({ chain: 'base', token: 'USDC', amount: '0.05', payTo: '0xMerchant…' }),
  *     (req, res) => res.json({ secret: 42 })
  *   )
  *
@@ -4357,6 +4371,26 @@ declare abstract class PipRailError extends Error {
 declare class InsufficientFundsError extends PipRailError {
     readonly code = "INSUFFICIENT_FUNDS";
 }
+/**
+ * The payment can't be delivered because the RECIPIENT (`payTo`) isn't set up to
+ * receive on this chain yet — a chain-level *state* requirement, NOT the payer's
+ * balance. It's deliberately distinct from {@link InsufficientFundsError} so a
+ * caller (especially an AI agent) can tell the two fixes apart:
+ *
+ *   - `INSUFFICIENT_FUNDS`  → fund the **payer** (more token, native gas, or reserve).
+ *   - `RECIPIENT_NOT_READY` → set up the **recipient**, e.g.
+ *       · XRPL    — activate the account (it must hold ≥1 XRP base reserve to exist);
+ *       · Stellar — the account must exist (≥1 XLM reserve) and hold a trustline for the asset;
+ *       · NEAR    — `storage_deposit`-register the recipient on the NEP-141 token (~0.00125 NEAR).
+ *
+ * The message states the requirement and the fix in plain language **and echoes
+ * the raw chain code** (e.g. `(XRPL: tecNO_DST_INSUF_XRP)`), while the untouched
+ * chain error is preserved on `.cause` for deeper debugging. Chains with no
+ * receive prerequisite (EVM, Solana, Sui, Tron, and native TON/NEAR) never throw it.
+ */
+declare class RecipientNotReadyError extends PipRailError {
+    readonly code = "RECIPIENT_NOT_READY";
+}
 /**
  * Best-effort: turn a chain library's "wallet can't afford it" error into the
  * SDK's typed {@link InsufficientFundsError}, by matching its message. Drivers
@@ -4378,15 +4412,39 @@ declare class WrongChainError extends PipRailError {
 }
 /**
  * Broadcast confirmed on-chain but server didn't return 200 within timeout.
- * The user got their tokens debited but the gated content is unreachable —
- * retry manually with the receipt nonce.
+ * The user got their tokens debited but the gated content is unreachable.
+ *
+ * `.ref` is the on-chain proof (tx hash / signature / locator) that was already
+ * broadcast. **Re-verify or re-submit `ref` — never re-pay** (a fresh payment
+ * would double-spend). The same proof stays valid until the server's
+ * `maxTimeoutSeconds` recency window elapses (default 600s).
  */
 declare class PaymentTimeoutError extends PipRailError {
     readonly code = "PAYMENT_TIMEOUT";
+    /** The already-broadcast proof ref — recover with it, don't re-pay. */
+    readonly ref?: string;
+    constructor(message: string, options?: ErrorOptions & {
+        ref?: string;
+    });
 }
-/** Paid, retried, still got 402. Means the server rejected our proof. */
+/**
+ * Paid, retried, still got 402 — the server rejected our proof on every attempt.
+ *
+ * `.ref` is the on-chain proof that was broadcast. The rejection may be transient
+ * (the server's RPC node lagging/throttled and not yet seeing the tx) — so
+ * **re-verify or re-submit `ref` before doing anything else; never re-pay**, or
+ * you risk a double payment. The proof stays redeemable until the server's
+ * `maxTimeoutSeconds` recency window elapses (default 600s). A persistent
+ * rejection with a definitive code (`amount_too_low`, `wrong_recipient`, …)
+ * means the proof genuinely doesn't satisfy the challenge.
+ */
 declare class MaxRetriesExceededError extends PipRailError {
     readonly code = "MAX_RETRIES_EXCEEDED";
+    /** The already-broadcast proof ref — recover with it, don't re-pay. */
+    readonly ref?: string;
+    constructor(message: string, options?: ErrorOptions & {
+        ref?: string;
+    });
 }
 /**
  * The client refused to pay BEFORE any on-chain send — the quoted payment
@@ -4575,4 +4633,4 @@ declare function encodeXPaymentHeader(input: {
     x402Version?: number;
 }): string;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, InsufficientFundsError, InvalidEnvelopeError, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPolicy, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletHandle, type WalletInput, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildReceiptHeader, buildSignatureHeader, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, registerDriver, requirePayment, resolveChain, toInsufficientFundsError, toInvalidBody };
+export { type AcceptOption, type AddressId, type AgentTool, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, InsufficientFundsError, InvalidEnvelopeError, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPolicy, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletHandle, type WalletInput, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildReceiptHeader, buildSignatureHeader, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, registerDriver, requirePayment, resolveChain, toInsufficientFundsError, toInvalidBody };

package/dist/index.d.ts

@@ -155,7 +155,7 @@ declare function pickAccept(challenge: X402Challenge, matches: (network: string)
  * Chains are a parameter, and the popular ones are built in.
  *
  * The easy path — name a built-in chain:
- *   requirePayment({ chain: 'base', amount: '0.05', payTo })   // USDC on Base
+ *   requirePayment({ chain: 'base', token: 'USDC', amount: '0.05', payTo })   // USDC on Base
  *
  * The exotic path — ANY EVM chain we don't ship, by viem `Chain` or a bare
  * `{ id, rpcUrl }`, plus the token you want paid in:
@@ -812,7 +812,7 @@ declare const CHAINS: {
                         maxPriorityFeePerGas?: undefined | undefined;
                         isSystemTx?: undefined | undefined;
                         mint?: undefined | undefined;
-                        sourceHash? /** Display name. Defaults to `EVM <id>`. */: undefined | undefined;
+                        sourceHash?: undefined | undefined;
                     } | {
                         blockHash: `0x${string}` | null;
                         blockNumber: bigint | null;
@@ -1580,13 +1580,11 @@ declare const CHAINS: {
                         yParity: number;
                         accessList: viem.AccessList;
                         authorizationList?: undefined | undefined;
-                        blobVersionedHashes?: undefined | undefined;
+                        blobVersionedHashes? /** EVM chain id, e.g. 5000 for Mantle. */: undefined | undefined;
                         chainId: number;
                         type: "eip1559";
                         gasPrice?: undefined | undefined;
-                        maxFeePerBlobGas
-                        /** Native coin metadata. Defaults to 18-decimal ETH. */
-                        ? /** Native coin metadata. Defaults to 18-decimal ETH. */: undefined | undefined;
+                        maxFeePerBlobGas?: undefined | undefined;
                         maxFeePerGas: bigint;
                         maxPriorityFeePerGas: bigint;
                         feeCurrency: abitype.Address | null;
@@ -2984,7 +2982,7 @@ declare const CHAINS: {
                     } | {
                         blockHash: `0x${string}` | null;
                         blockNumber: bigint | null;
-                        blockTimestamp?: bigint | undefined;
+                        blockTimestamp? /** JSON-RPC endpoint. */: bigint | undefined;
                         from: abitype.Address;
                         gas: bigint;
                         hash: viem.Hash;
@@ -3318,10 +3316,8 @@ declare const CHAINS: {
                         yParity?: undefined | undefined;
                         type: "legacy";
                         gasPrice: bigint;
-                        maxFeePerBlobGas
-                        /** JSON-RPC endpoint. */
-                        ? /** JSON-RPC endpoint. */: undefined | undefined;
-                        maxFeePerGas? /** Display name. Defaults to `EVM <id>`. */: undefined | undefined;
+                        maxFeePerBlobGas?: undefined | undefined;
+                        maxFeePerGas?: undefined | undefined;
                         maxPriorityFeePerGas?: undefined | undefined;
                         isSystemTx?: undefined | undefined;
                         mint?: undefined | undefined;
@@ -3931,6 +3927,18 @@ type PipRailEvent = {
     kind: 'payment-confirmed';
     ref: string;
     blockNumber: bigint;
+}
+/**
+ * Broadcast succeeded (we hold `ref`) but LOCAL confirmation timed out — the
+ * RPC was likely lagging/throttled while the tx is in fact on-chain. The proof
+ * is NOT discarded: the client submits it to the server (whose own on-chain
+ * verify is the authority) instead of throwing, so a real payment is never
+ * orphaned into a double-pay. `reason` is the confirm error's message.
+ */
+ | {
+    kind: 'payment-unconfirmed';
+    ref: string;
+    reason: string;
 } | {
     kind: 'payment-settled';
     receipt: X402Receipt | null;
@@ -4049,7 +4057,13 @@ interface PipRailClientOptions {
      * giving up. Default 3, with a short backoff between attempts — this
      * absorbs RPC propagation lag (the server's node briefly trailing the
      * client's, so it hasn't seen the confirmation yet). If the server still
-     * returns 402 on the last attempt the SDK throws `MaxRetriesExceededError`.
+     * returns 402 on the last attempt the SDK throws `MaxRetriesExceededError`
+     * (which carries `.ref` — re-verify, never re-pay).
+     *
+     * If the broadcast succeeded but the client's OWN confirmation timed out
+     * (a throttled RPC), the proof is NOT discarded: the client submits it
+     * anyway and automatically uses MORE patient retries (a floor of 6, longer
+     * backoff), since the on-chain tx may still be settling.
      */
     maxPaymentRetries?: number;
     /** Timeout (ms) for the retry leg after broadcast. Default 30_000. */
@@ -4159,7 +4173,7 @@ declare function paymentTools(client: PipRailClient): AgentTool[];
  *   import { requirePayment } from '@piprail/sdk'
  *
  *   app.get('/report',
- *     requirePayment({ chain: 'base', amount: '0.05', payTo: '0xMerchant…' }),
+ *     requirePayment({ chain: 'base', token: 'USDC', amount: '0.05', payTo: '0xMerchant…' }),
  *     (req, res) => res.json({ secret: 42 })
  *   )
  *
@@ -4357,6 +4371,26 @@ declare abstract class PipRailError extends Error {
 declare class InsufficientFundsError extends PipRailError {
     readonly code = "INSUFFICIENT_FUNDS";
 }
+/**
+ * The payment can't be delivered because the RECIPIENT (`payTo`) isn't set up to
+ * receive on this chain yet — a chain-level *state* requirement, NOT the payer's
+ * balance. It's deliberately distinct from {@link InsufficientFundsError} so a
+ * caller (especially an AI agent) can tell the two fixes apart:
+ *
+ *   - `INSUFFICIENT_FUNDS`  → fund the **payer** (more token, native gas, or reserve).
+ *   - `RECIPIENT_NOT_READY` → set up the **recipient**, e.g.
+ *       · XRPL    — activate the account (it must hold ≥1 XRP base reserve to exist);
+ *       · Stellar — the account must exist (≥1 XLM reserve) and hold a trustline for the asset;
+ *       · NEAR    — `storage_deposit`-register the recipient on the NEP-141 token (~0.00125 NEAR).
+ *
+ * The message states the requirement and the fix in plain language **and echoes
+ * the raw chain code** (e.g. `(XRPL: tecNO_DST_INSUF_XRP)`), while the untouched
+ * chain error is preserved on `.cause` for deeper debugging. Chains with no
+ * receive prerequisite (EVM, Solana, Sui, Tron, and native TON/NEAR) never throw it.
+ */
+declare class RecipientNotReadyError extends PipRailError {
+    readonly code = "RECIPIENT_NOT_READY";
+}
 /**
  * Best-effort: turn a chain library's "wallet can't afford it" error into the
  * SDK's typed {@link InsufficientFundsError}, by matching its message. Drivers
@@ -4378,15 +4412,39 @@ declare class WrongChainError extends PipRailError {
 }
 /**
  * Broadcast confirmed on-chain but server didn't return 200 within timeout.
- * The user got their tokens debited but the gated content is unreachable —
- * retry manually with the receipt nonce.
+ * The user got their tokens debited but the gated content is unreachable.
+ *
+ * `.ref` is the on-chain proof (tx hash / signature / locator) that was already
+ * broadcast. **Re-verify or re-submit `ref` — never re-pay** (a fresh payment
+ * would double-spend). The same proof stays valid until the server's
+ * `maxTimeoutSeconds` recency window elapses (default 600s).
  */
 declare class PaymentTimeoutError extends PipRailError {
     readonly code = "PAYMENT_TIMEOUT";
+    /** The already-broadcast proof ref — recover with it, don't re-pay. */
+    readonly ref?: string;
+    constructor(message: string, options?: ErrorOptions & {
+        ref?: string;
+    });
 }
-/** Paid, retried, still got 402. Means the server rejected our proof. */
+/**
+ * Paid, retried, still got 402 — the server rejected our proof on every attempt.
+ *
+ * `.ref` is the on-chain proof that was broadcast. The rejection may be transient
+ * (the server's RPC node lagging/throttled and not yet seeing the tx) — so
+ * **re-verify or re-submit `ref` before doing anything else; never re-pay**, or
+ * you risk a double payment. The proof stays redeemable until the server's
+ * `maxTimeoutSeconds` recency window elapses (default 600s). A persistent
+ * rejection with a definitive code (`amount_too_low`, `wrong_recipient`, …)
+ * means the proof genuinely doesn't satisfy the challenge.
+ */
 declare class MaxRetriesExceededError extends PipRailError {
     readonly code = "MAX_RETRIES_EXCEEDED";
+    /** The already-broadcast proof ref — recover with it, don't re-pay. */
+    readonly ref?: string;
+    constructor(message: string, options?: ErrorOptions & {
+        ref?: string;
+    });
 }
 /**
  * The client refused to pay BEFORE any on-chain send — the quoted payment
@@ -4575,4 +4633,4 @@ declare function encodeXPaymentHeader(input: {
     x402Version?: number;
 }): string;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, InsufficientFundsError, InvalidEnvelopeError, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPolicy, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletHandle, type WalletInput, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildReceiptHeader, buildSignatureHeader, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, registerDriver, requirePayment, resolveChain, toInsufficientFundsError, toInvalidBody };
+export { type AcceptOption, type AddressId, type AgentTool, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, InsufficientFundsError, InvalidEnvelopeError, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPolicy, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletHandle, type WalletInput, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildReceiptHeader, buildSignatureHeader, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, registerDriver, requirePayment, resolveChain, toInsufficientFundsError, toInvalidBody };

package/dist/index.js

@@ -9,6 +9,7 @@ import {
   PaymentDeclinedError,
   PaymentTimeoutError,
   PipRailError,
+  RecipientNotReadyError,
   UnknownTokenError,
   UnsupportedNetworkError,
   WrongChainError,
@@ -19,7 +20,7 @@ import {
   parseUnits,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-3TQJJ4SQ.js";
+} from "./chunk-DTIJYDG6.js";
 
 // src/drivers/registry.ts
 var byFamily = /* @__PURE__ */ new Map();
@@ -712,7 +713,7 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await import("./solana-7PZG3CDO.js");
+      mod = await import("./solana-USZHRZFN.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Solana selected, but its packages aren't installed. Run: npm install @solana/web3.js @solana/spl-token bs58`,
@@ -724,7 +725,7 @@ var loaders = {
   ton: async () => {
     let mod;
     try {
-      mod = await import("./ton-EFZKQAAK.js");
+      mod = await import("./ton-2N74GKNB.js");
     } catch (cause) {
       throw new MissingDriverError(
         `TON selected, but its packages aren't installed. Run: npm install @ton/ton @ton/core @ton/crypto`,
@@ -736,7 +737,7 @@ var loaders = {
   stellar: async () => {
     let mod;
     try {
-      mod = await import("./stellar-PAZ352JL.js");
+      mod = await import("./stellar-JZBVCLNV.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Stellar selected, but its package isn't installed. Run: npm install @stellar/stellar-sdk`,
@@ -748,7 +749,7 @@ var loaders = {
   xrpl: async () => {
     let mod;
     try {
-      mod = await import("./xrpl-7GWXDAVZ.js");
+      mod = await import("./xrpl-RTT3UOLX.js");
     } catch (cause) {
       throw new MissingDriverError(
         `XRPL selected, but its package isn't installed. Run: npm install xrpl`,
@@ -760,7 +761,7 @@ var loaders = {
   tron: async () => {
     let mod;
     try {
-      mod = await import("./tron-243DT6PF.js");
+      mod = await import("./tron-N3EAAKU7.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Tron selected, but its package isn't installed. Run: npm install tronweb`,
@@ -772,7 +773,7 @@ var loaders = {
   sui: async () => {
     let mod;
     try {
-      mod = await import("./sui-6N4ZPAGD.js");
+      mod = await import("./sui-UBDATSQV.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Sui selected, but its package isn't installed. Run: npm install @mysten/sui`,
@@ -784,7 +785,7 @@ var loaders = {
   near: async () => {
     let mod;
     try {
-      mod = await import("./near-RVXGF7TW.js");
+      mod = await import("./near-RJUETWY3.js");
     } catch (cause) {
       throw new MissingDriverError(
         `NEAR selected, but its package isn't installed. Run: npm install near-api-js`,
@@ -1055,8 +1056,8 @@ var PipRailClient = class {
     );
     this.safeEmit({ kind: "payment-required", challenge, accept });
     await this.authorize(quote);
-    const ref = await this.payAndConfirm(net, wallet, accept);
-    const response = await this.retryWithProof(url, init, accept, ref);
+    const { ref, confirmed } = await this.payAndConfirm(net, wallet, accept);
+    const response = await this.retryWithProof(url, init, accept, ref, confirmed);
     this.recordSpend(quote, ref);
     return response;
   }
@@ -1187,15 +1188,24 @@ var PipRailClient = class {
     }
     const ref = await net.send(wallet, accept);
     this.safeEmit({ kind: "payment-broadcast", ref });
-    const { height } = await net.confirm(ref, accept.extra.minConfirmations ?? 1);
-    this.safeEmit({
-      kind: "payment-confirmed",
-      ref,
-      blockNumber: BigInt(height)
-    });
-    return ref;
+    try {
+      const { height } = await net.confirm(ref, accept.extra.minConfirmations ?? 1);
+      this.safeEmit({
+        kind: "payment-confirmed",
+        ref,
+        blockNumber: BigInt(height)
+      });
+      return { ref, confirmed: true };
+    } catch (err) {
+      this.safeEmit({
+        kind: "payment-unconfirmed",
+        ref,
+        reason: err instanceof Error ? err.message : String(err)
+      });
+      return { ref, confirmed: false };
+    }
   }
-  async retryWithProof(url, originalInit, accept, ref) {
+  async retryWithProof(url, originalInit, accept, ref, confirmed) {
     const signature = {
       x402Version: 2,
       accepted: accept,
@@ -1205,9 +1215,11 @@ var PipRailClient = class {
     headers.set(HEADER_SIGNATURE, buildSignatureHeader(signature));
     let lastResponse = null;
     let lastReason = null;
-    for (let attempt = 0; attempt < this.maxRetries; attempt += 1) {
+    const attempts = confirmed ? this.maxRetries : Math.max(this.maxRetries, 6);
+    const backoffCap = confirmed ? 2e3 : 5e3;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
       if (attempt > 0) {
-        await new Promise((r) => setTimeout(r, Math.min(2e3, 400 * 2 ** (attempt - 1))));
+        await new Promise((r) => setTimeout(r, Math.min(backoffCap, 400 * 2 ** (attempt - 1))));
       }
       const timeoutController = new AbortController();
       const timeoutId = setTimeout(
@@ -1224,8 +1236,8 @@ var PipRailClient = class {
       } catch (err) {
         if (timeoutController.signal.aborted) {
           throw new PaymentTimeoutError(
-            `Server did not respond within ${this.retryTimeoutMs}ms after on-chain payment ${ref} confirmed.`,
-            { cause: err }
+            `Server did not respond within ${this.retryTimeoutMs}ms after broadcasting payment ${ref}. Re-verify or re-submit ref=${ref} \u2014 do NOT re-pay.`,
+            { cause: err, ref }
           );
         }
         throw err;
@@ -1240,12 +1252,14 @@ var PipRailClient = class {
       lastReason = await readInvalidReason(lastResponse) ?? lastReason;
     }
     const why = lastReason ? `${lastReason.error}${lastReason.detail ? ` \u2014 ${lastReason.detail}` : ""}` : "server gave no reason";
+    const unconfirmedNote = confirmed ? "" : " (broadcast but NOT locally confirmed \u2014 it may still have settled on-chain)";
     this.safeEmit({
       kind: "payment-failed",
-      reason: `server returned 402 after on-chain payment ${ref} confirmed (${why})`
+      reason: `server returned 402 after broadcasting payment ${ref}${unconfirmedNote} (${why})`
     });
     throw new MaxRetriesExceededError(
-      `Server still returned 402 after ${this.maxRetries} retry attempt(s) with on-chain proof ref=${ref}. Last server rejection: ${why}.`
+      `Server still returned 402 after ${attempts} attempt(s) with on-chain proof ref=${ref}${unconfirmedNote}. Last server rejection: ${why}. Re-verify or re-submit ref=${ref} before retrying \u2014 never re-pay (it would double-spend).`,
+      { ref }
     );
   }
 };
@@ -1655,6 +1669,7 @@ export {
   PaymentTimeoutError,
   PipRailClient,
   PipRailError,
+  RecipientNotReadyError,
   UnknownTokenError,
   UnsupportedNetworkError,
   WrongChainError,