@piprail/sdk 2.6.0 → 2.8.0

package/dist/index.d.cts

@@ -4741,6 +4741,8 @@ declare function getDirectoryInfo(source: DiscoverySource): DirectoryInfo;
 declare function decorateOutcome(o: RegisterOutcome): RegisterOutcome;
 /** Normalize an index's network field to CAIP-2 when we recognise the slug;
  *  pass a value that's already CAIP-2 (`namespace:reference`) through unchanged.
+ *  A legacy/superseded CAIP-2 id is mapped to its canonical replacement first
+ *  (so a colon-bearing legacy id like `ton:-239` still canonicalizes).
  *  An unknown slug returns unchanged (no `:`), which the client treats as
  *  "unresolved — don't hide it" rather than a confident mismatch. */
 declare function normalizeNetwork(network: string): string;
@@ -5044,6 +5046,14 @@ type PipRailEvent = {
 } | {
     kind: 'payment-failed';
     reason: string;
+    /** A machine-readable failure code when one is known. For a SERVER rejection it's the SAME
+     *  code the merchant's `onFailed` hook receives (a canonical {@link VerifyErrorCode} from a
+     *  PipRail gate, or a foreign facilitator's reason string); for a pre-send client DECLINE
+     *  (policy / budget / approval) it's that decline reason (e.g. `'BUDGET'`, `'APPROVAL'`).
+     *  Absent when no structured code was given. */
+    code?: string;
+    /** Human-readable detail, when present (e.g. `"Paid 40000, required 500000."`). */
+    detail?: string;
 };
 /**
  * Wallet for the chosen chain family. **One field, every chain: `{ key }`** — the
@@ -6463,6 +6473,28 @@ interface ExactRailOption {
      *  "just works". Force `'eip3009'` or `'permit2'` to pin one. Ignored on Solana (always SVM). */
     method?: 'eip3009' | 'permit2' | 'auto';
 }
+/**
+ * The merchant-side mirror of {@link PaidReceipt}: what an {@link RequirePaymentOptions.onFailed}
+ * hook receives when a SUBMITTED payment proof is REJECTED. It carries the SAME machine-readable
+ * `code` the buyer's client is given for that rejection, so both sides are notified of one
+ * consistent reason. (A rejection has no settlement, so — unlike a receipt — there is no tx hash
+ * or settled amount to report.)
+ */
+interface FailedPayment {
+    /** The canonical rejection reason — the same {@link VerifyErrorCode} surfaced to the buyer
+     *  (e.g. `amount_too_low`, `payment_expired`, `tx_already_used`, `transfer_not_found`). */
+    code: VerifyErrorCode;
+    /** Human-readable detail, e.g. `"Paid 40000, required 500000."`. */
+    detail: string;
+    /**
+     * `true` for a **transient** rejection (`tx_not_found` / `insufficient_confirmations`): the proof
+     * may still be settling and the buyer's client **retries automatically** — you'll get `onPaid` if
+     * it then succeeds. `false` for a **definitive** rejection the buyer must fix (wrong amount,
+     * expired, replayed, bad signature, wrong recipient). Alert on `!transient` to avoid false alarms
+     * on normal RPC lag; nothing is hidden — every rejected attempt still fires `onFailed`.
+     */
+    transient: boolean;
+}
 interface RequirePaymentOptions {
     /**
      * Single-chain form: which chain to accept payment on. EVM ('bnb'|'base'|…),
@@ -6535,6 +6567,37 @@ interface RequirePaymentOptions {
      * via `onPaidError`; it never turns a settled payment into a 402.
      */
     awaitOnPaid?: boolean;
+    /**
+     * The merchant-side mirror of `onPaid`: fired when a SUBMITTED payment proof is REJECTED — a
+     * `kind:'invalid'` verdict (wrong amount, expired, replayed, unknown asset, …). Receives a
+     * {@link FailedPayment} carrying the SAME machine `code` the buyer's client is given, so the
+     * merchant and the buyer are notified of the same failure with the same reason.
+     *
+     * Fires ONLY on a rejected attempt — NOT on a normal first-request 402 `challenge` (no proof
+     * yet), and NOT on a transient/settlement error that throws (an RPC blip, or a 5xx
+     * `SettlementError`): those aren't payment verdicts. Like `onPaid`, it may be **sync or async**
+     * and is fully isolated — a throw OR a rejected promise is caught and routed to `onFailedError`,
+     * so it can never break the request or crash the process. Fire-and-forget by default; set
+     * `awaitOnFailed` to run it before the 402 is returned.
+     *
+     * NOTE: a failure the merchant never receives a request for — the buyer can't afford it, an
+     * `onBeforePay`/`policy` declines it, or the buyer abandons before paying — cannot reach a
+     * backendless gate (only the buyer's client sees it). `onFailed` covers every rejection that
+     * DOES reach the gate.
+     */
+    onFailed?: (failure: FailedPayment) => void | Promise<void>;
+    /**
+     * Observe a failure inside `onFailed` (sync throw or async rejection) — the mirror of
+     * `onPaidError`. Without it, a throwing `onFailed` is swallowed silently. Its own throws are
+     * also swallowed (it can never break a request).
+     */
+    onFailedError?: (error: unknown, failure: FailedPayment) => void;
+    /**
+     * Await `onFailed` before the 402 rejection is returned (mirror of `awaitOnPaid`), so
+     * "failure recorded" is guaranteed before the caller is told. Default `false` (fire-and-forget).
+     * A rejection inside the hook is still isolated via `onFailedError`.
+     */
+    awaitOnFailed?: boolean;
     /**
      * ALSO advertise a standard x402 `exact` rail so any standard x402 client can pay this
      * gate — opt-in, EVM (EIP-3009/Permit2) + Solana (SVM). See {@link ExactRailOption}.
@@ -6639,15 +6702,6 @@ interface PaymentGate {
      */
     landingPage(challenge: X402Challenge): string;
 }
-/**
- * Framework-agnostic core. Build one gate per gated resource and reuse it
- * — its in-memory used-tx set is what stops the same proof being redeemed
- * twice. Wrap it for Express with `requirePayment`, or call it directly
- * from Hono / Fastify / Adonis / Workers / etc.
- *
- * The chain's driver is resolved lazily on first `challenge()`/`verify()`,
- * which is what lets Solana (and future families) auto-mount with no setup.
- */
 declare function createPaymentGate(options: RequirePaymentOptions): PaymentGate;
 interface ExpressLikeRequest {
     headers: Record<string, string | string[] | undefined>;
@@ -7527,4 +7581,4 @@ declare const PERMIT2_WITNESS_TYPES: {
  */
 declare function renderLandingPage(sd: SelfDescription): string;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, BRAND, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, buildBazaarExtension, buildChallengeHeader, buildEndpointInfo, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSelfDescription, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, knownFacilitatorsFor, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseFacilitatorSupported, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, BRAND, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, type FailedPayment, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, buildBazaarExtension, buildChallengeHeader, buildEndpointInfo, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSelfDescription, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, knownFacilitatorsFor, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseFacilitatorSupported, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };

package/dist/index.d.ts

@@ -4741,6 +4741,8 @@ declare function getDirectoryInfo(source: DiscoverySource): DirectoryInfo;
 declare function decorateOutcome(o: RegisterOutcome): RegisterOutcome;
 /** Normalize an index's network field to CAIP-2 when we recognise the slug;
  *  pass a value that's already CAIP-2 (`namespace:reference`) through unchanged.
+ *  A legacy/superseded CAIP-2 id is mapped to its canonical replacement first
+ *  (so a colon-bearing legacy id like `ton:-239` still canonicalizes).
  *  An unknown slug returns unchanged (no `:`), which the client treats as
  *  "unresolved — don't hide it" rather than a confident mismatch. */
 declare function normalizeNetwork(network: string): string;
@@ -5044,6 +5046,14 @@ type PipRailEvent = {
 } | {
     kind: 'payment-failed';
     reason: string;
+    /** A machine-readable failure code when one is known. For a SERVER rejection it's the SAME
+     *  code the merchant's `onFailed` hook receives (a canonical {@link VerifyErrorCode} from a
+     *  PipRail gate, or a foreign facilitator's reason string); for a pre-send client DECLINE
+     *  (policy / budget / approval) it's that decline reason (e.g. `'BUDGET'`, `'APPROVAL'`).
+     *  Absent when no structured code was given. */
+    code?: string;
+    /** Human-readable detail, when present (e.g. `"Paid 40000, required 500000."`). */
+    detail?: string;
 };
 /**
  * Wallet for the chosen chain family. **One field, every chain: `{ key }`** — the
@@ -6463,6 +6473,28 @@ interface ExactRailOption {
      *  "just works". Force `'eip3009'` or `'permit2'` to pin one. Ignored on Solana (always SVM). */
     method?: 'eip3009' | 'permit2' | 'auto';
 }
+/**
+ * The merchant-side mirror of {@link PaidReceipt}: what an {@link RequirePaymentOptions.onFailed}
+ * hook receives when a SUBMITTED payment proof is REJECTED. It carries the SAME machine-readable
+ * `code` the buyer's client is given for that rejection, so both sides are notified of one
+ * consistent reason. (A rejection has no settlement, so — unlike a receipt — there is no tx hash
+ * or settled amount to report.)
+ */
+interface FailedPayment {
+    /** The canonical rejection reason — the same {@link VerifyErrorCode} surfaced to the buyer
+     *  (e.g. `amount_too_low`, `payment_expired`, `tx_already_used`, `transfer_not_found`). */
+    code: VerifyErrorCode;
+    /** Human-readable detail, e.g. `"Paid 40000, required 500000."`. */
+    detail: string;
+    /**
+     * `true` for a **transient** rejection (`tx_not_found` / `insufficient_confirmations`): the proof
+     * may still be settling and the buyer's client **retries automatically** — you'll get `onPaid` if
+     * it then succeeds. `false` for a **definitive** rejection the buyer must fix (wrong amount,
+     * expired, replayed, bad signature, wrong recipient). Alert on `!transient` to avoid false alarms
+     * on normal RPC lag; nothing is hidden — every rejected attempt still fires `onFailed`.
+     */
+    transient: boolean;
+}
 interface RequirePaymentOptions {
     /**
      * Single-chain form: which chain to accept payment on. EVM ('bnb'|'base'|…),
@@ -6535,6 +6567,37 @@ interface RequirePaymentOptions {
      * via `onPaidError`; it never turns a settled payment into a 402.
      */
     awaitOnPaid?: boolean;
+    /**
+     * The merchant-side mirror of `onPaid`: fired when a SUBMITTED payment proof is REJECTED — a
+     * `kind:'invalid'` verdict (wrong amount, expired, replayed, unknown asset, …). Receives a
+     * {@link FailedPayment} carrying the SAME machine `code` the buyer's client is given, so the
+     * merchant and the buyer are notified of the same failure with the same reason.
+     *
+     * Fires ONLY on a rejected attempt — NOT on a normal first-request 402 `challenge` (no proof
+     * yet), and NOT on a transient/settlement error that throws (an RPC blip, or a 5xx
+     * `SettlementError`): those aren't payment verdicts. Like `onPaid`, it may be **sync or async**
+     * and is fully isolated — a throw OR a rejected promise is caught and routed to `onFailedError`,
+     * so it can never break the request or crash the process. Fire-and-forget by default; set
+     * `awaitOnFailed` to run it before the 402 is returned.
+     *
+     * NOTE: a failure the merchant never receives a request for — the buyer can't afford it, an
+     * `onBeforePay`/`policy` declines it, or the buyer abandons before paying — cannot reach a
+     * backendless gate (only the buyer's client sees it). `onFailed` covers every rejection that
+     * DOES reach the gate.
+     */
+    onFailed?: (failure: FailedPayment) => void | Promise<void>;
+    /**
+     * Observe a failure inside `onFailed` (sync throw or async rejection) — the mirror of
+     * `onPaidError`. Without it, a throwing `onFailed` is swallowed silently. Its own throws are
+     * also swallowed (it can never break a request).
+     */
+    onFailedError?: (error: unknown, failure: FailedPayment) => void;
+    /**
+     * Await `onFailed` before the 402 rejection is returned (mirror of `awaitOnPaid`), so
+     * "failure recorded" is guaranteed before the caller is told. Default `false` (fire-and-forget).
+     * A rejection inside the hook is still isolated via `onFailedError`.
+     */
+    awaitOnFailed?: boolean;
     /**
      * ALSO advertise a standard x402 `exact` rail so any standard x402 client can pay this
      * gate — opt-in, EVM (EIP-3009/Permit2) + Solana (SVM). See {@link ExactRailOption}.
@@ -6639,15 +6702,6 @@ interface PaymentGate {
      */
     landingPage(challenge: X402Challenge): string;
 }
-/**
- * Framework-agnostic core. Build one gate per gated resource and reuse it
- * — its in-memory used-tx set is what stops the same proof being redeemed
- * twice. Wrap it for Express with `requirePayment`, or call it directly
- * from Hono / Fastify / Adonis / Workers / etc.
- *
- * The chain's driver is resolved lazily on first `challenge()`/`verify()`,
- * which is what lets Solana (and future families) auto-mount with no setup.
- */
 declare function createPaymentGate(options: RequirePaymentOptions): PaymentGate;
 interface ExpressLikeRequest {
     headers: Record<string, string | string[] | undefined>;
@@ -7527,4 +7581,4 @@ declare const PERMIT2_WITNESS_TYPES: {
  */
 declare function renderLandingPage(sd: SelfDescription): string;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, BRAND, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, buildBazaarExtension, buildChallengeHeader, buildEndpointInfo, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSelfDescription, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, knownFacilitatorsFor, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseFacilitatorSupported, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, BRAND, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, type FailedPayment, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, buildBazaarExtension, buildChallengeHeader, buildEndpointInfo, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSelfDescription, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, knownFacilitatorsFor, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseFacilitatorSupported, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };

package/dist/index.js

@@ -24,7 +24,7 @@ import {
   parseUnits,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-7XK22JSQ.js";
+} from "./chunk-W3HOMXOF.js";
 
 // src/drivers/registry.ts
 var byFamily = /* @__PURE__ */ new Map();
@@ -1840,7 +1840,7 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await import("./solana-3FMCWSEE.js");
+      mod = await import("./solana-Z34OWXMO.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Solana selected, but its packages aren't installed. Run: npm install @solana/web3.js @solana/spl-token bs58`,
@@ -1852,7 +1852,7 @@ var loaders = {
   ton: async () => {
     let mod;
     try {
-      mod = await import("./ton-5ZPT5PSP.js");
+      mod = await import("./ton-N7KSPSAR.js");
     } catch (cause) {
       throw new MissingDriverError(
         `TON selected, but its packages aren't installed. Run: npm install @ton/ton @ton/core @ton/crypto`,
@@ -1864,7 +1864,7 @@ var loaders = {
   stellar: async () => {
     let mod;
     try {
-      mod = await import("./stellar-U5NCRIOJ.js");
+      mod = await import("./stellar-PWC4LETJ.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Stellar selected, but its package isn't installed. Run: npm install @stellar/stellar-sdk`,
@@ -1876,7 +1876,7 @@ var loaders = {
   xrpl: async () => {
     let mod;
     try {
-      mod = await import("./xrpl-2MZEOIFY.js");
+      mod = await import("./xrpl-6B4IYRWI.js");
     } catch (cause) {
       throw new MissingDriverError(
         `XRPL selected, but its package isn't installed. Run: npm install xrpl`,
@@ -1888,7 +1888,7 @@ var loaders = {
   tron: async () => {
     let mod;
     try {
-      mod = await import("./tron-WYS4X2I5.js");
+      mod = await import("./tron-WKDUQVZR.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Tron selected, but its package isn't installed. Run: npm install tronweb`,
@@ -1900,7 +1900,7 @@ var loaders = {
   sui: async () => {
     let mod;
     try {
-      mod = await import("./sui-Y53M4GUM.js");
+      mod = await import("./sui-VEOGHBYE.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Sui selected, but its package isn't installed. Run: npm install @mysten/sui`,
@@ -1912,7 +1912,7 @@ var loaders = {
   near: async () => {
     let mod;
     try {
-      mod = await import("./near-OTPQD6BI.js");
+      mod = await import("./near-QV4IOZNX.js");
     } catch (cause) {
       throw new MissingDriverError(
         `NEAR selected, but its package isn't installed. Run: npm install near-api-js`,
@@ -1924,7 +1924,7 @@ var loaders = {
   aptos: async () => {
     let mod;
     try {
-      mod = await import("./aptos-QAAXIUY3.js");
+      mod = await import("./aptos-WMPFEASY.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Aptos selected, but its package isn't installed. Run: npm install @aptos-labs/ts-sdk`,
@@ -1936,7 +1936,7 @@ var loaders = {
   algorand: async () => {
     let mod;
     try {
-      mod = await import("./algorand-WB6PBJU4.js");
+      mod = await import("./algorand-WJL6VRXW.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Algorand selected, but its package isn't installed. Run: npm install algosdk`,
@@ -2027,7 +2027,7 @@ var SLUG_TO_CAIP2 = {
   bsc: "eip155:56",
   // non-EVM families — values mirror each driver's bound caip2 exactly
   solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
-  ton: "ton:-239",
+  ton: "tvm:-239",
   tron: "tron:mainnet",
   near: "near:mainnet",
   sui: "sui:mainnet",
@@ -2036,7 +2036,12 @@ var SLUG_TO_CAIP2 = {
   stellar: "stellar:pubnet",
   xrpl: "xrpl:0"
 };
+var LEGACY_CAIP2_ALIAS = {
+  "ton:-239": "tvm:-239"
+};
 function normalizeNetwork(network) {
+  const legacy = LEGACY_CAIP2_ALIAS[network];
+  if (legacy) return legacy;
   if (network.includes(":")) return network;
   return SLUG_TO_CAIP2[network.toLowerCase()] ?? network;
 }
@@ -3212,7 +3217,9 @@ var PipRailClient = class {
     if (autoRoute) {
       const plan = await this.planFromChallenge(net, wallet, challenge, url, schemes);
       if (!plan.best) {
-        throw new PaymentDeclinedError(plan.fundingHint ?? "No rail is settleable for this payment.");
+        const reason = plan.fundingHint ?? "No rail is settleable for this payment.";
+        this.safeEmit({ kind: "payment-failed", reason });
+        throw new PaymentDeclinedError(reason);
       }
       accept = plan.best.accept;
       quote = plan.best.quote;
@@ -3502,10 +3509,10 @@ var PipRailClient = class {
    *  TERMINAL expiry/approval decline it must not retry) without parsing prose. */
   async authorize(quote) {
     if (!quote.withinPolicy) {
-      throw new PaymentDeclinedError(
-        `Payment refused by policy: ${quote.policyReason ?? "not allowed"}`,
-        { reasonCode: reasonCodeForPolicy(quote.policyCode) }
-      );
+      const reason = `Payment refused by policy: ${quote.policyReason ?? "not allowed"}`;
+      const reasonCode = reasonCodeForPolicy(quote.policyCode);
+      this.safeEmit({ kind: "payment-failed", reason, code: reasonCode });
+      throw new PaymentDeclinedError(reason, { reasonCode });
     }
     const hook = this.opts.onBeforePay;
     if (!hook) return;
@@ -3513,16 +3520,14 @@ var PipRailClient = class {
     try {
       approved = await hook(quote);
     } catch (err) {
-      throw new PaymentDeclinedError("onBeforePay threw \u2014 refusing to pay.", {
-        cause: err,
-        reasonCode: "APPROVAL"
-      });
+      const reason = "onBeforePay threw \u2014 refusing to pay.";
+      this.safeEmit({ kind: "payment-failed", reason, code: "APPROVAL" });
+      throw new PaymentDeclinedError(reason, { cause: err, reasonCode: "APPROVAL" });
     }
     if (!approved) {
-      throw new PaymentDeclinedError(
-        `onBeforePay declined ${quote.amountFormatted} ${quote.symbol ?? ""}`.trimEnd() + ` on ${quote.network}.`,
-        { reasonCode: "APPROVAL" }
-      );
+      const reason = `onBeforePay declined ${quote.amountFormatted} ${quote.symbol ?? ""}`.trimEnd() + ` on ${quote.network}.`;
+      this.safeEmit({ kind: "payment-failed", reason, code: "APPROVAL" });
+      throw new PaymentDeclinedError(reason, { reasonCode: "APPROVAL" });
     }
   }
   /** Record a settled payment in the ledger (true decimals for the running total). */
@@ -3617,7 +3622,8 @@ var PipRailClient = class {
     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 broadcasting payment ${ref}${unconfirmedNote} (${why})`
+      reason: `server returned 402 after broadcasting payment ${ref}${unconfirmedNote} (${why})`,
+      ...lastReason ? { code: lastReason.error, detail: lastReason.detail } : {}
     });
     throw new MaxRetriesExceededError(
       `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).`,
@@ -3652,7 +3658,7 @@ var PipRailClient = class {
     const headers = new Headers(init?.headers);
     headers.set(HEADER_SIGNATURE, buildExactSignatureHeader({ accepted, payload }));
     const rejectDefinitive = (why2) => {
-      this.safeEmit({ kind: "payment-failed", reason: `exact: facilitator rejected nonce=${nonce} (${why2})` });
+      this.safeEmit({ kind: "payment-failed", reason: `exact: facilitator rejected nonce=${nonce} (${why2})`, code: why2 });
       throw new MaxRetriesExceededError(
         `exact: the facilitator rejected the payment (${why2}). Fix the cause, then re-present the SAME signed authorization (nonce=${nonce}) \u2014 do NOT re-sign a fresh nonce. ref=${nonce}.`,
         { ref: nonce }
@@ -3707,7 +3713,8 @@ var PipRailClient = class {
     const why = lastReason ? `${lastReason.error}${lastReason.detail ? ` \u2014 ${lastReason.detail}` : ""}` : "server gave no reason";
     this.safeEmit({
       kind: "payment-failed",
-      reason: `exact: 402 after submitting authorization nonce=${nonce} (${why})`
+      reason: `exact: 402 after submitting authorization nonce=${nonce} (${why})`,
+      ...lastReason ? { code: lastReason.error, detail: lastReason.detail } : {}
     });
     throw new MaxRetriesExceededError(
       `exact: server still returned 402 after submitting the signed authorization (nonce=${nonce}). Last rejection: ${why}. Re-present the SAME authorization \u2014 do NOT re-sign a fresh nonce; verify authorizationState(${payerFrom}, ${nonce}) first. ref=${nonce}.`,
@@ -5260,6 +5267,7 @@ function normaliseExactOption(exact) {
   if (exact === true) return { settle: "keyless" };
   return exact;
 }
+var TRANSIENT_VERIFY_CODES = /* @__PURE__ */ new Set(["tx_not_found", "insufficient_confirmations"]);
 function createPaymentGate(options) {
   const minConfirmations = options.minConfirmations ?? 1;
   const maxTimeoutSeconds = options.maxTimeoutSeconds ?? 600;
@@ -5544,6 +5552,32 @@ function createPaymentGate(options) {
     if (options.awaitOnPaid) await fireOnPaid(paid);
     else void fireOnPaid(paid);
   }
+  function reportOnFailedError(error, failure) {
+    if (!options.onFailedError) return;
+    try {
+      options.onFailedError(error, failure);
+    } catch {
+    }
+  }
+  function fireOnFailed(failure) {
+    if (!options.onFailed) return;
+    let outcome;
+    try {
+      outcome = options.onFailed(failure);
+    } catch (err) {
+      reportOnFailedError(err, failure);
+      return;
+    }
+    if (outcome != null && typeof outcome.then === "function") {
+      return Promise.resolve(outcome).catch((err) => reportOnFailedError(err, failure));
+    }
+  }
+  async function deliverOnFailed(result) {
+    const code = result.error;
+    const failure = { code, detail: result.detail, transient: TRANSIENT_VERIFY_CODES.has(code) };
+    if (options.awaitOnFailed) await fireOnFailed(failure);
+    else void fireOnFailed(failure);
+  }
   async function describe(resourceUrl = "") {
     const specs = await ready();
     const accepts = [];
@@ -5707,6 +5741,11 @@ function createPaymentGate(options) {
     return { kind: "paid", receipt: result.receipt, receiptHeader: buildReceiptHeader(result.receipt) };
   }
   async function verify(paymentSignature) {
+    const result = await resolveVerdict(paymentSignature);
+    if (result.kind === "invalid") await deliverOnFailed(result);
+    return result;
+  }
+  async function resolveVerdict(paymentSignature) {
     const raw = normaliseHeader(paymentSignature);
     if (!raw) return asChallenge();
     const sig = parseSignatureHeader(raw);