@piprail/sdk 3.0.0 → 3.1.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as Caip2, X as X402AcceptEntry, y as X402AnyAccept, B as X402ExactAcceptEntry, e as ExactPaymentPayloadAny, q as SignedReceipt, x as VerifyResult, J as X402UptoAcceptEntry, o as Permit2UptoPaymentPayload, w as SpendSummary, z as X402Challenge, G as X402Receipt, S as SettleOutcome, v as SpendStore, t as SpendLedger, u as SpendRecord, p as PipRailReceipt, V as VerifyErrorCode, a as AssetId, A as AddressId, P as PaidReceipt } from './ledger-Crc1bZox.cjs';
-export { D as DEFAULT_EXACT_TRANSFER_METHOD, E as EXT_OFFER_RECEIPT, b as EXT_PAYMENT_IDENTIFIER, c as ExactAuthorizationWire, d as ExactPaymentPayload, H as HEADER_REQUIRED, f as HEADER_RESPONSE, g as HEADER_RESPONSE_V1, h as HEADER_SIGNATURE, i as HEADER_SIGNATURE_V1, K as KNOWN_EXACT_TRANSFER_METHODS, j as ParsedExactPayment, k as ParsedUptoPayment, l as Permit2Authorization, m as Permit2PaymentPayload, n as Permit2UptoAuthorization, r as SpendAssetTotal, s as SpendDenomTotal, F as X402PaymentSignature, I as X402ResourceObject, L as buildChallengeHeader, M as buildExactSignatureHeader, N as buildPaymentIdentifierAdvertisement, O as buildReceiptExtension, Q as buildReceiptHeader, R as buildSignatureHeader, T as buildUptoSignatureHeader, U as buildV1PaymentHeader, W as decodeBase64Json, Y as exactTransferMethod, Z as isSettleableExactMethod, _ as memorySpendStore, $ as normalizeV1Challenge, a0 as parseChallenge, a1 as parseExactObject, a2 as parseExactPaymentHeader, a3 as parseReceipt, a4 as parseReceiptExtension, a5 as parseSettleResponse, a6 as parseSignatureHeader, a7 as parseSignatureObject, a8 as parseUptoObject, a9 as parseUptoPaymentHeader, aa as pickAccept, ab as readPaymentIdentifier } from './ledger-Crc1bZox.cjs';
+import { C as Caip2, X as X402AcceptEntry, y as X402AnyAccept, B as X402ExactAcceptEntry, e as ExactPaymentPayloadAny, q as SignedReceipt, x as VerifyResult, J as X402UptoAcceptEntry, o as Permit2UptoPaymentPayload, w as SpendSummary, z as X402Challenge, G as X402Receipt, S as SettleOutcome, v as SpendStore, t as SpendLedger, u as SpendRecord, p as PipRailReceipt, V as VerifyErrorCode, a as AssetId, A as AddressId, P as PaidReceipt } from './ledger-DkHUORUe.cjs';
+export { D as DEFAULT_EXACT_TRANSFER_METHOD, E as EXT_OFFER_RECEIPT, b as EXT_PAYMENT_IDENTIFIER, c as ExactAuthorizationWire, d as ExactPaymentPayload, H as HEADER_REQUIRED, f as HEADER_RESPONSE, g as HEADER_RESPONSE_V1, h as HEADER_SIGNATURE, i as HEADER_SIGNATURE_V1, K as KNOWN_EXACT_TRANSFER_METHODS, j as ParsedExactPayment, k as ParsedUptoPayment, l as Permit2Authorization, m as Permit2PaymentPayload, n as Permit2UptoAuthorization, r as SpendAssetTotal, s as SpendDenomTotal, F as X402PaymentSignature, I as X402ResourceObject, L as buildChallengeHeader, M as buildExactSignatureHeader, N as buildPaymentIdentifierAdvertisement, O as buildReceiptExtension, Q as buildReceiptHeader, R as buildSignatureHeader, T as buildUptoSignatureHeader, U as buildV1PaymentHeader, W as decodeBase64Json, Y as exactTransferMethod, Z as isSettleableExactMethod, _ as memorySpendStore, $ as normalizeV1Challenge, a0 as parseChallenge, a1 as parseExactObject, a2 as parseExactPaymentHeader, a3 as parseReceipt, a4 as parseReceiptExtension, a5 as parseSettleResponse, a6 as parseSignatureHeader, a7 as parseSignatureObject, a8 as parseUptoObject, a9 as parseUptoPaymentHeader, aa as pickAccept, ab as readPaymentIdentifier } from './ledger-DkHUORUe.cjs';
 import * as viem_zksync from 'viem/zksync';
 import * as abitype from 'abitype';
 import * as viem_chains from 'viem/chains';
@@ -4140,10 +4140,21 @@ type RecipientReason = 'NO_TRUSTLINE' | 'NOT_REGISTERED' | 'NOT_OPTED_IN' | 'INA
 /** What {@link ResolvedNetwork.balanceOf} returns — base-unit balances, or null per
  *  field when that read was unavailable (transient/RPC), never a false 0. */
 interface WalletBalance {
-    /** The payment token's balance in base units, or null if the read was unavailable. */
+    /**
+     * The payment token's SPENDABLE balance in base units, or null if the read was unavailable.
+     *
+     * For `asset === 'native'` this is what the holder may actually send, which is not always
+     * what it holds: a chain may require an account to retain a minimum it can never spend
+     * (Solana's rent exemption, XRPL's base reserve). Report the reserve DEDUCTED here, and the
+     * true balance in {@link WalletBalance.native}. `planPayment` measures affordability against
+     * this field, so a driver that reports the raw balance instead will call a payment affordable
+     * that the chain then refuses after signing — the one thing the pre-flight check exists to
+     * prevent. Where a family has no such reserve the two fields are simply equal.
+     */
     token: bigint | null;
-    /** The native gas coin's balance in base units, or null if unavailable. For
-     *  `asset === 'native'`, this equals `token`. */
+    /** The native gas coin's TRUE balance in base units, or null if unavailable — what gas is
+     *  judged against. For `asset === 'native'` this is the raw balance, which may exceed
+     *  {@link WalletBalance.token} by the chain's retained reserve. */
     native: bigint | null;
 }
 interface ConfirmInfo {
@@ -6026,6 +6037,21 @@ declare class PipRailClient {
     private bound?;
     private lastReceiptValue;
     constructor(opts: PipRailClientOptions);
+    /**
+     * Pin the three authority accessors to THIS instance, non-writable and non-configurable.
+     *
+     * `paymentTools()` decides which tools a model is handed by calling `canAgentSell()` /
+     * `canAgentSwap()`, which read `mode()`. Those were plain prototype methods, so any code
+     * holding the client could reassign one — `client.mode = () => 'sovereign'` turned a
+     * budgeted client's eight tools into sovereign's fourteen.
+     *
+     * A MODEL could never do that (it sends JSON tool arguments; it does not hold the object),
+     * so this is not a path a model can walk. It is defence in depth for the case where a
+     * client passes through code that is not the operator's own: an agent framework, a plugin,
+     * some middleware that wraps or proxies objects. Authority is set once, by whoever
+     * provisioned the key, and nothing downstream gets to revise it.
+     */
+    private sealAuthority;
     /**
      * 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
@@ -7506,10 +7532,28 @@ interface RequirePaymentOptions {
     maxTimeoutSeconds?: number;
     /** Nonce generator. Default `crypto.randomUUID()`. */
     generateNonce?: () => string;
-    /** Replay hook — return true if this proof was already redeemed. */
+    /**
+     * Replay hook — return true if this proof was already redeemed.
+     *
+     * For a MULTI-PROCESS deployment make this an atomic **check-and-reserve** (Redis
+     * `SET NX`, which returns null when the key already exists) rather than a plain read:
+     * the gate consults this before an `await`ed verification and records after it, so a
+     * separate `exists()` then `set()` lets two instances redeem one proof. A reserving
+     * `isUsed` should be paired with {@link RequirePaymentOptions.releaseUsed}, or a
+     * transient verify failure will permanently burn an otherwise-valid payment.
+     */
     isUsed?: (ref: string) => boolean | Promise<boolean>;
-    /** Replay hook — record a redeemed proof. */
+    /** Replay hook — record a redeemed proof. Fires only on a SETTLED payment. */
     markUsed?: (ref: string) => void | Promise<void>;
+    /**
+     * Replay hook — release a reservation this gate made but could not settle (a transient
+     * RPC failure, a rejected proof). Optional, and only meaningful when `isUsed` RESERVES
+     * (the `SET NX` shape above): without it that reservation outlives the failed attempt and
+     * the buyer's still-valid proof can never be redeemed — they paid and get nothing. The
+     * built-in store has always released on failure; this is how a custom store does the same.
+     * Never throws into the request: a failure here is swallowed (a stale key expires on its own).
+     */
+    releaseUsed?: (ref: string) => void | Promise<void>;
     /**
      * Fired when a payment verifies successfully, with the enriched {@link PaidReceipt}.
      * May be **sync or async** — a throw OR a rejected promise is isolated (routed to
@@ -8054,7 +8098,9 @@ declare function parseFacilitatorSupported(body: unknown): FacilitatorSupportedK
  * {@link fetchFacilitatorFeePayer}). Lets an operator/agent ask "does this facilitator
  * cover my network?" before wiring a gate. Pure `fetch`, no chain libraries (STANDARDS §1).
  */
-declare function facilitatorCoverage(url: string, timeoutMs?: number): Promise<FacilitatorSupportedKind[]>;
+declare function facilitatorCoverage(url: string, 
+/** Cold-start sized, for the same reason as {@link fetchFacilitatorFeePayer}. */
+timeoutMs?: number): Promise<FacilitatorSupportedKind[]>;
 /** A merchant-chosen facilitator: its base URL + optional per-request auth headers. */
 interface FacilitatorConfig {
     /** Base URL, e.g. 'https://x402.org/facilitator' (trailing slash stripped). */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as Caip2, X as X402AcceptEntry, y as X402AnyAccept, B as X402ExactAcceptEntry, e as ExactPaymentPayloadAny, q as SignedReceipt, x as VerifyResult, J as X402UptoAcceptEntry, o as Permit2UptoPaymentPayload, w as SpendSummary, z as X402Challenge, G as X402Receipt, S as SettleOutcome, v as SpendStore, t as SpendLedger, u as SpendRecord, p as PipRailReceipt, V as VerifyErrorCode, a as AssetId, A as AddressId, P as PaidReceipt } from './ledger-Crc1bZox.js';
-export { D as DEFAULT_EXACT_TRANSFER_METHOD, E as EXT_OFFER_RECEIPT, b as EXT_PAYMENT_IDENTIFIER, c as ExactAuthorizationWire, d as ExactPaymentPayload, H as HEADER_REQUIRED, f as HEADER_RESPONSE, g as HEADER_RESPONSE_V1, h as HEADER_SIGNATURE, i as HEADER_SIGNATURE_V1, K as KNOWN_EXACT_TRANSFER_METHODS, j as ParsedExactPayment, k as ParsedUptoPayment, l as Permit2Authorization, m as Permit2PaymentPayload, n as Permit2UptoAuthorization, r as SpendAssetTotal, s as SpendDenomTotal, F as X402PaymentSignature, I as X402ResourceObject, L as buildChallengeHeader, M as buildExactSignatureHeader, N as buildPaymentIdentifierAdvertisement, O as buildReceiptExtension, Q as buildReceiptHeader, R as buildSignatureHeader, T as buildUptoSignatureHeader, U as buildV1PaymentHeader, W as decodeBase64Json, Y as exactTransferMethod, Z as isSettleableExactMethod, _ as memorySpendStore, $ as normalizeV1Challenge, a0 as parseChallenge, a1 as parseExactObject, a2 as parseExactPaymentHeader, a3 as parseReceipt, a4 as parseReceiptExtension, a5 as parseSettleResponse, a6 as parseSignatureHeader, a7 as parseSignatureObject, a8 as parseUptoObject, a9 as parseUptoPaymentHeader, aa as pickAccept, ab as readPaymentIdentifier } from './ledger-Crc1bZox.js';
+import { C as Caip2, X as X402AcceptEntry, y as X402AnyAccept, B as X402ExactAcceptEntry, e as ExactPaymentPayloadAny, q as SignedReceipt, x as VerifyResult, J as X402UptoAcceptEntry, o as Permit2UptoPaymentPayload, w as SpendSummary, z as X402Challenge, G as X402Receipt, S as SettleOutcome, v as SpendStore, t as SpendLedger, u as SpendRecord, p as PipRailReceipt, V as VerifyErrorCode, a as AssetId, A as AddressId, P as PaidReceipt } from './ledger-DkHUORUe.js';
+export { D as DEFAULT_EXACT_TRANSFER_METHOD, E as EXT_OFFER_RECEIPT, b as EXT_PAYMENT_IDENTIFIER, c as ExactAuthorizationWire, d as ExactPaymentPayload, H as HEADER_REQUIRED, f as HEADER_RESPONSE, g as HEADER_RESPONSE_V1, h as HEADER_SIGNATURE, i as HEADER_SIGNATURE_V1, K as KNOWN_EXACT_TRANSFER_METHODS, j as ParsedExactPayment, k as ParsedUptoPayment, l as Permit2Authorization, m as Permit2PaymentPayload, n as Permit2UptoAuthorization, r as SpendAssetTotal, s as SpendDenomTotal, F as X402PaymentSignature, I as X402ResourceObject, L as buildChallengeHeader, M as buildExactSignatureHeader, N as buildPaymentIdentifierAdvertisement, O as buildReceiptExtension, Q as buildReceiptHeader, R as buildSignatureHeader, T as buildUptoSignatureHeader, U as buildV1PaymentHeader, W as decodeBase64Json, Y as exactTransferMethod, Z as isSettleableExactMethod, _ as memorySpendStore, $ as normalizeV1Challenge, a0 as parseChallenge, a1 as parseExactObject, a2 as parseExactPaymentHeader, a3 as parseReceipt, a4 as parseReceiptExtension, a5 as parseSettleResponse, a6 as parseSignatureHeader, a7 as parseSignatureObject, a8 as parseUptoObject, a9 as parseUptoPaymentHeader, aa as pickAccept, ab as readPaymentIdentifier } from './ledger-DkHUORUe.js';
 import * as viem_zksync from 'viem/zksync';
 import * as abitype from 'abitype';
 import * as viem_chains from 'viem/chains';
@@ -4140,10 +4140,21 @@ type RecipientReason = 'NO_TRUSTLINE' | 'NOT_REGISTERED' | 'NOT_OPTED_IN' | 'INA
 /** What {@link ResolvedNetwork.balanceOf} returns — base-unit balances, or null per
  *  field when that read was unavailable (transient/RPC), never a false 0. */
 interface WalletBalance {
-    /** The payment token's balance in base units, or null if the read was unavailable. */
+    /**
+     * The payment token's SPENDABLE balance in base units, or null if the read was unavailable.
+     *
+     * For `asset === 'native'` this is what the holder may actually send, which is not always
+     * what it holds: a chain may require an account to retain a minimum it can never spend
+     * (Solana's rent exemption, XRPL's base reserve). Report the reserve DEDUCTED here, and the
+     * true balance in {@link WalletBalance.native}. `planPayment` measures affordability against
+     * this field, so a driver that reports the raw balance instead will call a payment affordable
+     * that the chain then refuses after signing — the one thing the pre-flight check exists to
+     * prevent. Where a family has no such reserve the two fields are simply equal.
+     */
     token: bigint | null;
-    /** The native gas coin's balance in base units, or null if unavailable. For
-     *  `asset === 'native'`, this equals `token`. */
+    /** The native gas coin's TRUE balance in base units, or null if unavailable — what gas is
+     *  judged against. For `asset === 'native'` this is the raw balance, which may exceed
+     *  {@link WalletBalance.token} by the chain's retained reserve. */
     native: bigint | null;
 }
 interface ConfirmInfo {
@@ -6026,6 +6037,21 @@ declare class PipRailClient {
     private bound?;
     private lastReceiptValue;
     constructor(opts: PipRailClientOptions);
+    /**
+     * Pin the three authority accessors to THIS instance, non-writable and non-configurable.
+     *
+     * `paymentTools()` decides which tools a model is handed by calling `canAgentSell()` /
+     * `canAgentSwap()`, which read `mode()`. Those were plain prototype methods, so any code
+     * holding the client could reassign one — `client.mode = () => 'sovereign'` turned a
+     * budgeted client's eight tools into sovereign's fourteen.
+     *
+     * A MODEL could never do that (it sends JSON tool arguments; it does not hold the object),
+     * so this is not a path a model can walk. It is defence in depth for the case where a
+     * client passes through code that is not the operator's own: an agent framework, a plugin,
+     * some middleware that wraps or proxies objects. Authority is set once, by whoever
+     * provisioned the key, and nothing downstream gets to revise it.
+     */
+    private sealAuthority;
     /**
      * 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
@@ -7506,10 +7532,28 @@ interface RequirePaymentOptions {
     maxTimeoutSeconds?: number;
     /** Nonce generator. Default `crypto.randomUUID()`. */
     generateNonce?: () => string;
-    /** Replay hook — return true if this proof was already redeemed. */
+    /**
+     * Replay hook — return true if this proof was already redeemed.
+     *
+     * For a MULTI-PROCESS deployment make this an atomic **check-and-reserve** (Redis
+     * `SET NX`, which returns null when the key already exists) rather than a plain read:
+     * the gate consults this before an `await`ed verification and records after it, so a
+     * separate `exists()` then `set()` lets two instances redeem one proof. A reserving
+     * `isUsed` should be paired with {@link RequirePaymentOptions.releaseUsed}, or a
+     * transient verify failure will permanently burn an otherwise-valid payment.
+     */
     isUsed?: (ref: string) => boolean | Promise<boolean>;
-    /** Replay hook — record a redeemed proof. */
+    /** Replay hook — record a redeemed proof. Fires only on a SETTLED payment. */
     markUsed?: (ref: string) => void | Promise<void>;
+    /**
+     * Replay hook — release a reservation this gate made but could not settle (a transient
+     * RPC failure, a rejected proof). Optional, and only meaningful when `isUsed` RESERVES
+     * (the `SET NX` shape above): without it that reservation outlives the failed attempt and
+     * the buyer's still-valid proof can never be redeemed — they paid and get nothing. The
+     * built-in store has always released on failure; this is how a custom store does the same.
+     * Never throws into the request: a failure here is swallowed (a stale key expires on its own).
+     */
+    releaseUsed?: (ref: string) => void | Promise<void>;
     /**
      * Fired when a payment verifies successfully, with the enriched {@link PaidReceipt}.
      * May be **sync or async** — a throw OR a rejected promise is isolated (routed to
@@ -8054,7 +8098,9 @@ declare function parseFacilitatorSupported(body: unknown): FacilitatorSupportedK
  * {@link fetchFacilitatorFeePayer}). Lets an operator/agent ask "does this facilitator
  * cover my network?" before wiring a gate. Pure `fetch`, no chain libraries (STANDARDS §1).
  */
-declare function facilitatorCoverage(url: string, timeoutMs?: number): Promise<FacilitatorSupportedKind[]>;
+declare function facilitatorCoverage(url: string, 
+/** Cold-start sized, for the same reason as {@link fetchFacilitatorFeePayer}. */
+timeoutMs?: number): Promise<FacilitatorSupportedKind[]>;
 /** A merchant-chosen facilitator: its base URL + optional per-request auth headers. */
 interface FacilitatorConfig {
     /** Base URL, e.g. 'https://x402.org/facilitator' (trailing slash stripped). */