@routedock/routedock 0.3.1 → 0.4.0

package/dist/{RouteDockClient-CXvWXix5.d.cts → RouteDockClient-CnAkxwrW.d.ts}

@@ -1,15 +1,22 @@
 import { Keypair } from '@stellar/stellar-sdk';
-import { g as RouteDockLogger, P as PaymentMode, h as RouteDockManifest, d as PreflightResult, c as PaymentResult, b as EstimateCostResult, n as SessionOptions, m as SessionHandle } from './logger-D8_Q2ytp.cjs';
+import { P as PaymentMode, c as PaymentRequest, R as RouteDockManifest, d as PaymentResult, U as UrlPreflightResult, g as PreflightResult, b as EstimateCostResult, n as SessionOptions, m as SessionHandle } from './types-DXaS5Wip.js';
+import { b as RouteDockLogger } from './logger-DVa7VT4c.js';
 import { ClientStellarSigner } from '@x402/stellar';
-import { SignAuthEntry } from '@stellar/stellar-sdk/contract';
-import { usdcToStroops } from '@routedock/nulth-sdk';
+import { PaymentRequirements } from '@x402/core/types';
+import { NulthSignerConfig, NulthStellarSigner, usdcToStroops } from '@routedock/nulth-sdk';
+import { S as SpendStore } from './SpendStore-BUclV02i.js';
 
 interface RetryPolicy {
     /** Total attempts including the first call. Default: 4 (3 retries). */
     maxAttempts?: number;
     /** Base delay for exponential backoff in ms. Default: 250. */
     baseDelayMs?: number;
-    /** Maximum jittered backoff delay in ms. Default: 30000. */
+    /**
+     * Maximum delay of any single retry sleep, in ms. Default: 30000. Caps both
+     * the jittered backoff and a server `Retry-After` hint, so a provider that
+     * asks for a longer wait is waited on for at most this long. The error's
+     * own `retryAfterMs` still carries the raw server value.
+     */
     maxDelayMs?: number;
     /** Called before each retry with the attempt number, error, and upcoming delay. */
     /**
@@ -32,27 +39,25 @@ declare const DEFAULT_RETRY_POLICY: Required<Omit<RetryPolicy, 'onRetry' | 'logg
 declare function backoffDelayMs(attempt: number, baseDelayMs: number, maxDelayMs?: number): number;
 /**
  * Execute `fn` with exponential backoff on retryable RouteDockErrors.
- * Honors `retryAfterMs` from facilitator 429/503 responses when present.
+ * Honors `retryAfterMs` from facilitator 429/503 responses when present, but
+ * never sleeps longer than `maxDelayMs`: a larger server hint is clamped.
  */
 declare function withRetry<T>(fn: () => Promise<T>, policy?: RetryPolicy): Promise<T>;
 
 /**
  * Enforce the per-endpoint `deprecated` and `sunset_at` metadata for the URL
- * being paid. `pay()` never learns the HTTP method, so a path shared by more
- * than one descriptor (e.g. GET and POST on `/infer`) is refused only when
- * every matching descriptor has sunset. Paths the manifest does not list keep
- * today's behavior. Query strings and hashes are ignored because only
- * `URL.pathname` is compared.
- */
-declare function assertEndpointActive(manifest: RouteDockManifest, url: string, logger?: RouteDockLogger): void;
-/**
- * Validate semantic constraints for manifest fields beyond JSON schema syntax.
- * Enforces:
- * - All keys in `latency_hints` must be a subset of declared `regions`.
- * - If `assets` is defined, it must be a non-empty array whose first entry
- *   (`assets[0]`) matches the root-level `asset` and `asset_contract`.
+ * being paid.
+ *
+ * When the caller's HTTP method is known (`method`), only descriptors for that
+ * method can speak for the request, so a sunset GET `/infer` no longer blocks
+ * an active POST `/infer` (and vice versa). Without a method — `estimateCost()`
+ * before a request is chosen, or `openSession()` — a shared path is refused
+ * only when every matching descriptor has sunset. Paths the manifest does not
+ * list, and (method-known) method/path pairs it does not declare, keep today's
+ * behavior. Query strings and hashes are ignored because only `URL.pathname`
+ * is compared.
  */
-declare function assertManifestValid(manifest: RouteDockManifest, baseUrl?: string): void;
+declare function assertEndpointActive(manifest: RouteDockManifest, url: string, logger?: RouteDockLogger, method?: string): void;
 /**
  * Override the manifest cache's max size (default 512). Affects the shared,
  * process-wide cache used by all RouteDockClient instances.
@@ -94,6 +99,24 @@ interface ModeSelectOptions {
     forceMode?: PaymentMode;
     /** Structured logger for mode selection events. Defaults to no-op. */
     logger?: RouteDockLogger;
+    /**
+     * HTTP request replayed to the provider. Use it for POST endpoints:
+     *
+     * ```ts
+     * await client.pay(url, {
+     *   request: {
+     *     method: 'POST',
+     *     headers: { 'content-type': 'application/json' },
+     *     body: JSON.stringify(input),
+     *   },
+     * })
+     * ```
+     *
+     * The method/headers/body are sent on the unpaid probe, the paid request and
+     * every retry; SDK payment headers always override caller headers. The method
+     * also scopes the per-endpoint sunset check.
+     */
+    request?: PaymentRequest;
 }
 /**
  * Fetch, validate, and cache a RouteDock manifest from `baseUrl`.
@@ -104,6 +127,12 @@ interface ModeSelectOptions {
  * Callers that obtained a payee from a registry/pinned allowlist MUST pass it;
  * without it the self-signed signature alone proves nothing about who served
  * the manifest.
+ *
+ * Concurrent calls that miss the cache for the same `baseUrl` share one
+ * in-flight HTTP request instead of fanning out (the cache is process-wide,
+ * so this also holds across `RouteDockClient` instances). The first caller's
+ * `retryPolicy` and `manifestTimeoutMs` govern the shared request; the
+ * per-caller checks above still run for every caller after it settles.
  */
 declare function fetchManifest(baseUrl: string, retryPolicy?: RetryPolicy, manifestTimeoutMs?: number, expectedPayee?: string): Promise<RouteDockManifest>;
 /**
@@ -123,81 +152,45 @@ declare function selectMode(manifest: RouteDockManifest, options?: ModeSelectOpt
  */
 declare function rankProvidersByLatency(manifests: RouteDockManifest[], targetRegion: string): RouteDockManifest[];
 
-interface NulthPolicyState {
-    dailyCapStroops: bigint;
-    allowlistCommitment: string;
-    allowedPayees: readonly string[];
-    dailySpendStroops: bigint;
-    dayBucket: number;
-    witnessSecret: string;
-    expiryLedger?: number;
-}
-interface PaymentAuthContext {
-    authEntry: string;
-    payee: string;
-    amountStroops: bigint;
-    assetContract: string;
-    ledgerSequence: number;
+type Network = 'testnet' | 'mainnet';
+/** What an {@link X402PreSignHook} sees: the payment about to be signed. */
+interface X402PreSignContext {
+    /** The resource being paid for. */
+    readonly url: string;
+    /** The signed manifest the challenge was already bound to. */
+    readonly manifest: RouteDockManifest;
+    /** The challenge entries that passed manifest binding — the signer picks from these. */
+    readonly accepts: readonly PaymentRequirements[];
 }
-interface NulthProof {
-    version: 1;
-    proof: string;
-    publicInputs: {
-        authDigest: string;
-        allowlistCommitment: string;
-        capCommitment: string;
-        payeeHash: string;
-        amountStroops: string;
-        dayBucket: string;
-    };
-}
-interface NulthAuthSignature {
-    nulth: 'zk-v1';
-    proof: NulthProof;
-}
-interface NulthClientConfig {
-    nulthAccount: string;
-    network: 'testnet' | 'mainnet';
-    prover?: 'mock';
-    policy: NulthPolicyState;
-    verifierContract?: string;
-    /** Log sink for the mock-prover warning. Defaults to a console-backed logger. */
-    logger?: RouteDockLogger;
-}
-declare class NulthPolicyError extends Error {
-    readonly code: 'payee_not_allowed' | 'daily_cap_exceeded' | 'session_expired' | 'auth_entry_mismatch';
-    constructor(code: NulthPolicyError['code'], message: string);
-}
-interface NulthStellarSigner {
-    address: string;
-    signAuthEntry: SignAuthEntry;
-}
-interface NulthSignerConfig extends NulthClientConfig {
-    paymentContext?: Omit<PaymentAuthContext, 'authEntry'>;
+/** Verdict returned by an {@link X402PreSignHook}. */
+type X402PreSignDecision = {
+    approve: true;
+} | {
+    approve: false;
+    reason?: string;
+};
+/**
+ * Optional guard run once per `pay()`, after the 402 challenge has been bound to
+ * the manifest and immediately before anything is signed. Use it to plug in an
+ * external or custom audit. Rejecting — or throwing — aborts before signing
+ * (fail closed) with `RouteDockPolicyRejectError`.
+ */
+type X402PreSignHook = (ctx: X402PreSignContext) => X402PreSignDecision | Promise<X402PreSignDecision>;
+declare class X402Client {
+    private readonly network;
+    private readonly retryPolicy?;
+    private readonly preSignHook?;
+    private readonly httpClient;
+    private readonly signer;
+    private readonly logger;
+    constructor(secretKeyOrSigner: string | ClientStellarSigner, network: Network, retryPolicy?: RetryPolicy | undefined, preSignHook?: X402PreSignHook | undefined, logger?: RouteDockLogger);
+    /** Replace signer (e.g. swap to Nulth ZK account payer before pay) */
+    withSigner(signer: ClientStellarSigner): X402Client;
+    pay(url: string, manifest: RouteDockManifest, request?: PaymentRequest): Promise<PaymentResult>;
 }
+
+/** Preserve RouteDock's logger default and configuration error contract. */
 declare function createNulthSigner(config: NulthSignerConfig): NulthStellarSigner;
-declare function setNulthPaymentContext(config: NulthSignerConfig, context: Omit<PaymentAuthContext, 'authEntry'>): void;
-declare function paymentContextFromManifest(manifest: {
-    payee: string;
-    asset_contract: string;
-    pricing: {
-        x402?: {
-            amount: string;
-            payee?: string;
-        };
-        'mpp-charge'?: {
-            amount: string;
-            payee?: string;
-        };
-    };
-}, mode: 'x402' | 'mpp-charge', ledgerSequence: number): Omit<PaymentAuthContext, 'authEntry'>;
-declare function createPolicyState(input: {
-    dailyCapUsdc: string;
-    allowedPayees: readonly string[];
-    witnessSecret: string;
-    expiryLedger?: number;
-    ledgerSequence?: number;
-}): NulthPolicyState;
 interface NulthVaultConfig {
     mode: 'nulth';
     nulthAccount: string;
@@ -215,56 +208,21 @@ declare function prepareNulthSigner(vault: NulthVaultConfig, manifest: RouteDock
     config: NulthSignerConfig;
 }>;
 
-declare function decodeAuthSignature(encoded: string): NulthAuthSignature;
-
-/**
- * Daily spend accumulator, keyed by an ISO date (YYYY-MM-DD).
- *
- * Totals are decimal strings of integer microUSDC (1 USDC = 10^7 units) so
- * the record stays JSON-serializable with no floating point precision loss.
- */
-interface DailySpend {
-    date: string;
-    /** Global accumulated spend for the day, in microUSDC (e.g. "5000000") */
-    totalMicros: string;
-    /** Per-endpoint accumulated spend for the day, keyed by origin URL, in microUSDC */
-    endpoints: Record<string, string>;
-}
-/**
- * Durable backing store for the client's local daily spend cap.
- *
- * The spend cap is a financial safety control: if its accumulator lives only in
- * heap memory, any crash, OOM kill, or container restart silently resets it to
- * zero and the cap can be bypassed. Inject a persistent implementation
- * (Redis, SQL, Supabase, a file, …) so the counter survives restarts.
- */
-interface SpendStore {
-    /** Return the persisted accumulator, or null if none has been written yet. */
-    read(): Promise<DailySpend | null>;
-    /** Persist the accumulator. */
-    write(state: DailySpend): Promise<void>;
-}
-interface InMemorySpendStoreOptions {
-    /** Log a startup warning about non-durability. Defaults to true. */
-    warn?: boolean;
-    /** Log sink for the non-durability warning. Defaults to a console-backed logger. */
-    logger?: RouteDockLogger;
-}
-/**
- * Default, non-durable {@link SpendStore}. Holds the accumulator on the heap, so
- * it resets on every process restart. Logs a startup warning unless silenced.
- * Use this only for development; inject a persistent store in production.
- */
-declare class InMemorySpendStore implements SpendStore {
-    private state;
-    constructor(options?: InMemorySpendStoreOptions);
-    read(): Promise<DailySpend | null>;
-    write(state: DailySpend): Promise<void>;
-}
-
 interface SpendCap {
-    /** Maximum total USDC spend per day (decimal string, e.g. "1.00") */
+    /**
+     * Maximum total spend per day (decimal string, e.g. "1.00"), denominated in
+     * `asset`.
+     *
+     * The accumulator is a single USDC number, so the cap only ever counts USDC.
+     * When a cap is configured, a payment whose selected asset (see
+     * `selectAsset`) is anything other than `asset` is rejected before any
+     * trustline check, network call or on-chain deposit with
+     * `RouteDockPolicyRejectError('local_cap_asset_mismatch')`. Amounts in other
+     * assets are never added to the USDC total, since 5 XLM is not 5 USDC.
+     * Manifests that only price in USDC behave exactly as before.
+     */
     daily: string;
+    /** The only asset this cap can account for. */
     asset: 'USDC';
     /**
      * Optional per-endpoint daily spend caps, keyed by endpoint origin URL
@@ -300,6 +258,11 @@ interface RouteDockClientConfig {
     commitmentSecret?: string | undefined;
     /** Retry policy for transient failures (network, facilitator 5xx). */
     retryPolicy?: RetryPolicy;
+    /**
+     * Optional guard run before an x402 payment is signed. Rejecting or throwing
+     * aborts the payment with `RouteDockPolicyRejectError`. x402 mode only.
+     */
+    preSignHook?: X402PreSignHook;
     /**
      * Durable backing store for the daily spend cap accumulator. Defaults to a
      * non-durable in-memory store that resets on restart (with a startup warning).
@@ -376,12 +339,24 @@ declare class RouteDockClient {
      */
     private _withSpendMutex;
     /**
-     * Check that the payer has a trustline for the payment asset and surface
-     * manifest metadata (regions, latency hints, capabilities). Safe to
-     * call before committing to a payment — for approval gates and manual
-     * trustline remediation.
+     * Check a provider before committing to a payment. Neither form submits a
+     * transaction or moves money.
+     *
+     * - `preflight(url)` fetches and validates the provider's manifest and
+     *   returns the supported modes, the estimated cost per mode, and
+     *   deprecation/sunset flags. It does not check the payer's trustline.
+     *   Throws the same manifest errors as `pay()` / `estimateCost()` when the
+     *   manifest is unreachable, invalid, unsupported by this SDK version, or
+     *   sunset (including a sunset endpoint matching the URL path).
+     * - `preflight(manifest, mode?, endpoint?)` checks that the payer has a
+     *   trustline for the payment asset and surfaces manifest metadata
+     *   (regions, latency hints, capabilities). For approval gates and manual
+     *   trustline remediation.
      */
+    preflight(url: string): Promise<UrlPreflightResult>;
     preflight(manifest: RouteDockManifest, mode?: PaymentMode, endpoint?: string): Promise<PreflightResult>;
+    /** Manifest-only preflight for a URL — no trustline check, no payment. */
+    private _preflightUrl;
     /**
      * Verify via Horizon that the payer account has a trustline for the
      * payment asset declared in the manifest. Throws RouteDockTrustlineError
@@ -417,6 +392,11 @@ declare class RouteDockClient {
      * disable via `options.maxDurationMs`.
      */
     openSession(url: string, options?: SessionOptions): Promise<SessionHandle>;
+    /**
+     * The local cap accumulates one USDC total. Refuse to count any other asset
+     * against it (or let it through uncounted) when a cap is configured.
+     */
+    private _assertCapAsset;
     /**
      * Record spend for an MPP session voucher. Called before each voucher
      * fetch in stream(). Enforces the same local daily and per-endpoint caps
@@ -468,4 +448,4 @@ declare class RouteDockClient {
     private _rollbackSpend;
 }
 
-export { selectMode as A, setNulthPaymentContext as B, usdcToMicros as C, DEFAULT_RETRY_POLICY as D, withRetry as E, InMemorySpendStore as I, type ModeSelectOptions as M, type NulthAuthSignature as N, type PaymentAuthContext as P, type RetryPolicy as R, type SpendCap as S, type VaultConfig as V, type DailySpend as a, type InMemorySpendStoreOptions as b, type NulthClientConfig as c, NulthPolicyError as d, type NulthPolicyState as e, type NulthProof as f, type NulthSignerConfig as g, type NulthStellarSigner as h, type NulthVaultConfig as i, RouteDockClient as j, type RouteDockClientConfig as k, type SpendStore as l, assertEndpointActive as m, assertManifestValid as n, assertNulthVaultManifest as o, backoffDelayMs as p, configureManifestCache as q, createNulthSigner as r, createPolicyState as s, decodeAuthSignature as t, fetchLedgerSequence as u, fetchManifest as v, invalidateManifest as w, paymentContextFromManifest as x, prepareNulthSigner as y, rankProvidersByLatency as z };
+export { DEFAULT_RETRY_POLICY as D, type ModeSelectOptions as M, type NulthVaultConfig as N, type RetryPolicy as R, type SpendCap as S, type VaultConfig as V, X402Client as X, RouteDockClient as a, type RouteDockClientConfig as b, type X402PreSignContext as c, type X402PreSignDecision as d, type X402PreSignHook as e, assertEndpointActive as f, assertNulthVaultManifest as g, backoffDelayMs as h, configureManifestCache as i, createNulthSigner as j, fetchLedgerSequence as k, fetchManifest as l, invalidateManifest as m, prepareNulthSigner as p, rankProvidersByLatency as r, selectMode as s, usdcToMicros as u, withRetry as w };

package/dist/{SessionReconciler-Bw-PoBVl.d.ts → SessionReconciler-Cce9MXO1.d.ts}

@@ -1,7 +1,8 @@
 import { SupabaseClient } from '@supabase/supabase-js';
-import { S as SeenTxStore, a as SettlementRecord } from './MppSessionHandler-Bq4S-JTE.js';
-import { h as RouteDockManifest, g as RouteDockLogger } from './logger-D8_Q2ytp.js';
+import { S as SeenTxStore, a as SettlementRecord } from './MppSessionHandler-3QfCHI5x.js';
+import { R as RouteDockManifest } from './types-DXaS5Wip.js';
 import { Keypair } from '@stellar/stellar-sdk';
+import { b as RouteDockLogger } from './logger-DVa7VT4c.js';
 
 /**
  * Settlement idempotency backed by Postgres via Supabase.
@@ -95,7 +96,7 @@ type Network = 'testnet' | 'mainnet';
 type ChannelCloseFn = (args: {
     channel: string;
     amount: bigint;
-    signature: Buffer;
+    signature: Uint8Array;
     feePayer: {
         envelopeSigner: Keypair;
     };
@@ -108,12 +109,18 @@ interface SessionReconcilerOptions {
     onRecovered?: (channelId: string, txHash: string, totalPaid: string) => Promise<void>;
     /** Injectable for testing. Defaults to @stellar/mpp/channel/server close() */
     channelClose?: ChannelCloseFn;
+    /** Failed close attempts before a row is moved to the terminal `failed` status. Default 5. */
+    maxReconcileAttempts?: number;
 }
 interface ReconciliationStats {
     orphanedCount: number;
     recoveredCount: number;
     skippedCount: number;
     failedCount: number;
+    /** Rows whose channel was already closed on-chain; marked `closed` without a new close. */
+    alreadyClosedCount: number;
+    /** Rows moved to the terminal `failed` status this run (attempt limit reached). */
+    terminalCount: number;
     errors: Array<{
         channelId: string;
         reason: string;

package/dist/{SessionReconciler-Cz2nuOlJ.d.cts → SessionReconciler-Dpe9qXdD.d.cts}

@@ -1,7 +1,8 @@
 import { SupabaseClient } from '@supabase/supabase-js';
-import { S as SeenTxStore, a as SettlementRecord } from './MppSessionHandler-1EL8QBAn.cjs';
-import { h as RouteDockManifest, g as RouteDockLogger } from './logger-D8_Q2ytp.cjs';
+import { S as SeenTxStore, a as SettlementRecord } from './MppSessionHandler-xu4Kxu6N.cjs';
+import { R as RouteDockManifest } from './types-DXaS5Wip.cjs';
 import { Keypair } from '@stellar/stellar-sdk';
+import { b as RouteDockLogger } from './logger-DVa7VT4c.cjs';
 
 /**
  * Settlement idempotency backed by Postgres via Supabase.
@@ -95,7 +96,7 @@ type Network = 'testnet' | 'mainnet';
 type ChannelCloseFn = (args: {
     channel: string;
     amount: bigint;
-    signature: Buffer;
+    signature: Uint8Array;
     feePayer: {
         envelopeSigner: Keypair;
     };
@@ -108,12 +109,18 @@ interface SessionReconcilerOptions {
     onRecovered?: (channelId: string, txHash: string, totalPaid: string) => Promise<void>;
     /** Injectable for testing. Defaults to @stellar/mpp/channel/server close() */
     channelClose?: ChannelCloseFn;
+    /** Failed close attempts before a row is moved to the terminal `failed` status. Default 5. */
+    maxReconcileAttempts?: number;
 }
 interface ReconciliationStats {
     orphanedCount: number;
     recoveredCount: number;
     skippedCount: number;
     failedCount: number;
+    /** Rows whose channel was already closed on-chain; marked `closed` without a new close. */
+    alreadyClosedCount: number;
+    /** Rows moved to the terminal `failed` status this run (attempt limit reached). */
+    terminalCount: number;
     errors: Array<{
         channelId: string;
         reason: string;

package/dist/{SessionStore-BaYiegP0.d.ts → SessionStore-DkLBxFQu.d.cts}

@@ -1,8 +1,8 @@
-import { h as RouteDockManifest, P as PaymentMode, A as AssetConfig, p as SessionState } from './logger-D8_Q2ytp.js';
+import { R as RouteDockManifest, P as PaymentMode, A as AssetConfig, p as SessionState } from './types-DXaS5Wip.cjs';
 import { SupabaseClient } from '@supabase/supabase-js';
 
 /** Stable error codes for programmatic handling. */
-type RouteDockErrorCode = 'MANIFEST' | 'MANIFEST_TIMEOUT' | 'MANIFEST_SUNSET' | 'NO_SUPPORTED_MODE' | 'FACILITATOR' | 'NETWORK' | 'SIGNATURE' | 'VOUCHER_MONOTONICITY' | 'POLICY_REJECT' | 'CHANNEL_STATE' | 'DISPUTE' | 'REFUND_WINDOW' | 'CLIENT_VERSION_TOO_OLD' | 'TRUSTLINE';
+type RouteDockErrorCode = 'MANIFEST' | 'MANIFEST_TIMEOUT' | 'MANIFEST_SUNSET' | 'NO_SUPPORTED_MODE' | 'FACILITATOR' | 'NETWORK' | 'SIGNATURE' | 'VOUCHER_MONOTONICITY' | 'POLICY_REJECT' | 'PAYMENT_REJECTED' | 'CHANNEL_STATE' | 'DISPUTE' | 'REFUND_WINDOW' | 'CLIENT_VERSION_TOO_OLD' | 'TRUSTLINE';
 interface RouteDockErrorOptions {
     cause?: unknown;
     /** Milliseconds to wait before retry (e.g. from Retry-After header). */
@@ -68,6 +68,24 @@ declare class RouteDockPolicyRejectError extends RouteDockError {
     readonly reason: string;
     constructor(reason: string, options?: RouteDockErrorOptions);
 }
+/**
+ * The provider refused a signed, paid request (HTTP 4xx such as 401/402).
+ * Not a manifest problem and not a local policy rejection: `status` is the HTTP
+ * status and `reason` is the provider's own explanation when it sent one
+ * (e.g. the facilitator's `invalidReason`). Not retryable — the same signed
+ * payment would be refused again.
+ */
+declare class RouteDockPaymentRejectedError extends RouteDockError {
+    readonly status: number;
+    /** The provider's `reason` field, if its response body was JSON and had one. */
+    readonly reason?: string;
+    /** The provider's `error` field (short summary), if present. */
+    readonly providerError?: string;
+    constructor(message: string, status: number, details?: {
+        reason?: string;
+        providerError?: string;
+    }, options?: RouteDockErrorOptions);
+}
 /** Channel lifecycle failure (open, simulate, close, missing settlement fields). */
 declare class RouteDockChannelStateError extends RouteDockError {
     constructor(message: string, options?: RouteDockErrorOptions);
@@ -88,6 +106,13 @@ declare const RouteDockSessionError: typeof RouteDockVoucherMonotonicityError;
 declare function parseRetryAfterMs(response: Response): number | undefined;
 /** Map an HTTP status to a typed, retryable-aware RouteDock error. */
 declare function httpStatusToError(message: string, status: number, response?: Response): RouteDockError;
+/**
+ * Build a {@link RouteDockPaymentRejectedError} from a rejected paid response.
+ * Reads the JSON body best-effort (a missing, non-JSON or oversized body just
+ * means no `reason`; the provider is untrusted, so the read is bounded and the
+ * fields are length-capped), and never throws.
+ */
+declare function paymentRejectedError(label: string, status: number, response: Response): Promise<RouteDockPaymentRejectedError>;
 /** Wrap a low-level fetch failure; preserves existing RouteDockErrors. */
 declare function wrapFetchError(err: unknown, context: string): RouteDockError;
 /**
@@ -140,4 +165,4 @@ declare class SupabaseSessionStore implements SessionStore {
     close(channelId: string): Promise<void>;
 }
 
-export { wrapFetchError as A, wrapMppError as B, RouteDockChannelStateError as R, type SessionStore as S, RouteDockClientVersionError as a, RouteDockDisputeError as b, RouteDockError as c, type RouteDockErrorCode as d, type RouteDockErrorOptions as e, RouteDockFacilitatorError as f, RouteDockManifestError as g, RouteDockManifestSunsetError as h, RouteDockManifestTimeoutError as i, RouteDockNetworkError as j, RouteDockNoSupportedModeError as k, RouteDockPolicyRejectError as l, RouteDockPolicyRejectedError as m, RouteDockRefundWindowError as n, RouteDockSessionError as o, RouteDockSignatureError as p, RouteDockTrustlineError as q, RouteDockVoucherMonotonicityError as r, SupabaseSessionStore as s, getEligibleAssets as t, httpStatusToError as u, isAssetEligible as v, normalizeManifestAssets as w, parseRetryAfterMs as x, resolveAssetContract as y, selectAsset as z };
+export { resolveAssetContract as A, selectAsset as B, wrapFetchError as C, wrapMppError as D, RouteDockChannelStateError as R, type SessionStore as S, RouteDockClientVersionError as a, RouteDockDisputeError as b, RouteDockError as c, type RouteDockErrorCode as d, type RouteDockErrorOptions as e, RouteDockFacilitatorError as f, RouteDockManifestError as g, RouteDockManifestSunsetError as h, RouteDockManifestTimeoutError as i, RouteDockNetworkError as j, RouteDockNoSupportedModeError as k, RouteDockPaymentRejectedError as l, RouteDockPolicyRejectError as m, RouteDockPolicyRejectedError as n, RouteDockRefundWindowError as o, RouteDockSessionError as p, RouteDockSignatureError as q, RouteDockTrustlineError as r, RouteDockVoucherMonotonicityError as s, SupabaseSessionStore as t, getEligibleAssets as u, httpStatusToError as v, isAssetEligible as w, normalizeManifestAssets as x, parseRetryAfterMs as y, paymentRejectedError as z };

package/dist/{SessionStore-B4-Hi4H8.d.cts → SessionStore-_ZkoBzFY.d.ts}

@@ -1,8 +1,8 @@
-import { h as RouteDockManifest, P as PaymentMode, A as AssetConfig, p as SessionState } from './logger-D8_Q2ytp.cjs';
+import { R as RouteDockManifest, P as PaymentMode, A as AssetConfig, p as SessionState } from './types-DXaS5Wip.js';
 import { SupabaseClient } from '@supabase/supabase-js';
 
 /** Stable error codes for programmatic handling. */
-type RouteDockErrorCode = 'MANIFEST' | 'MANIFEST_TIMEOUT' | 'MANIFEST_SUNSET' | 'NO_SUPPORTED_MODE' | 'FACILITATOR' | 'NETWORK' | 'SIGNATURE' | 'VOUCHER_MONOTONICITY' | 'POLICY_REJECT' | 'CHANNEL_STATE' | 'DISPUTE' | 'REFUND_WINDOW' | 'CLIENT_VERSION_TOO_OLD' | 'TRUSTLINE';
+type RouteDockErrorCode = 'MANIFEST' | 'MANIFEST_TIMEOUT' | 'MANIFEST_SUNSET' | 'NO_SUPPORTED_MODE' | 'FACILITATOR' | 'NETWORK' | 'SIGNATURE' | 'VOUCHER_MONOTONICITY' | 'POLICY_REJECT' | 'PAYMENT_REJECTED' | 'CHANNEL_STATE' | 'DISPUTE' | 'REFUND_WINDOW' | 'CLIENT_VERSION_TOO_OLD' | 'TRUSTLINE';
 interface RouteDockErrorOptions {
     cause?: unknown;
     /** Milliseconds to wait before retry (e.g. from Retry-After header). */
@@ -68,6 +68,24 @@ declare class RouteDockPolicyRejectError extends RouteDockError {
     readonly reason: string;
     constructor(reason: string, options?: RouteDockErrorOptions);
 }
+/**
+ * The provider refused a signed, paid request (HTTP 4xx such as 401/402).
+ * Not a manifest problem and not a local policy rejection: `status` is the HTTP
+ * status and `reason` is the provider's own explanation when it sent one
+ * (e.g. the facilitator's `invalidReason`). Not retryable — the same signed
+ * payment would be refused again.
+ */
+declare class RouteDockPaymentRejectedError extends RouteDockError {
+    readonly status: number;
+    /** The provider's `reason` field, if its response body was JSON and had one. */
+    readonly reason?: string;
+    /** The provider's `error` field (short summary), if present. */
+    readonly providerError?: string;
+    constructor(message: string, status: number, details?: {
+        reason?: string;
+        providerError?: string;
+    }, options?: RouteDockErrorOptions);
+}
 /** Channel lifecycle failure (open, simulate, close, missing settlement fields). */
 declare class RouteDockChannelStateError extends RouteDockError {
     constructor(message: string, options?: RouteDockErrorOptions);
@@ -88,6 +106,13 @@ declare const RouteDockSessionError: typeof RouteDockVoucherMonotonicityError;
 declare function parseRetryAfterMs(response: Response): number | undefined;
 /** Map an HTTP status to a typed, retryable-aware RouteDock error. */
 declare function httpStatusToError(message: string, status: number, response?: Response): RouteDockError;
+/**
+ * Build a {@link RouteDockPaymentRejectedError} from a rejected paid response.
+ * Reads the JSON body best-effort (a missing, non-JSON or oversized body just
+ * means no `reason`; the provider is untrusted, so the read is bounded and the
+ * fields are length-capped), and never throws.
+ */
+declare function paymentRejectedError(label: string, status: number, response: Response): Promise<RouteDockPaymentRejectedError>;
 /** Wrap a low-level fetch failure; preserves existing RouteDockErrors. */
 declare function wrapFetchError(err: unknown, context: string): RouteDockError;
 /**
@@ -140,4 +165,4 @@ declare class SupabaseSessionStore implements SessionStore {
     close(channelId: string): Promise<void>;
 }
 
-export { wrapFetchError as A, wrapMppError as B, RouteDockChannelStateError as R, type SessionStore as S, RouteDockClientVersionError as a, RouteDockDisputeError as b, RouteDockError as c, type RouteDockErrorCode as d, type RouteDockErrorOptions as e, RouteDockFacilitatorError as f, RouteDockManifestError as g, RouteDockManifestSunsetError as h, RouteDockManifestTimeoutError as i, RouteDockNetworkError as j, RouteDockNoSupportedModeError as k, RouteDockPolicyRejectError as l, RouteDockPolicyRejectedError as m, RouteDockRefundWindowError as n, RouteDockSessionError as o, RouteDockSignatureError as p, RouteDockTrustlineError as q, RouteDockVoucherMonotonicityError as r, SupabaseSessionStore as s, getEligibleAssets as t, httpStatusToError as u, isAssetEligible as v, normalizeManifestAssets as w, parseRetryAfterMs as x, resolveAssetContract as y, selectAsset as z };
+export { resolveAssetContract as A, selectAsset as B, wrapFetchError as C, wrapMppError as D, RouteDockChannelStateError as R, type SessionStore as S, RouteDockClientVersionError as a, RouteDockDisputeError as b, RouteDockError as c, type RouteDockErrorCode as d, type RouteDockErrorOptions as e, RouteDockFacilitatorError as f, RouteDockManifestError as g, RouteDockManifestSunsetError as h, RouteDockManifestTimeoutError as i, RouteDockNetworkError as j, RouteDockNoSupportedModeError as k, RouteDockPaymentRejectedError as l, RouteDockPolicyRejectError as m, RouteDockPolicyRejectedError as n, RouteDockRefundWindowError as o, RouteDockSessionError as p, RouteDockSignatureError as q, RouteDockTrustlineError as r, RouteDockVoucherMonotonicityError as s, SupabaseSessionStore as t, getEligibleAssets as u, httpStatusToError as v, isAssetEligible as w, normalizeManifestAssets as x, parseRetryAfterMs as y, paymentRejectedError as z };

package/dist/SpendStore-BUclV02i.d.ts

@@ -0,0 +1,73 @@
+import { b as RouteDockLogger } from './logger-DVa7VT4c.js';
+
+/**
+ * Daily spend accumulator, keyed by an ISO date (YYYY-MM-DD).
+ *
+ * Totals are decimal strings of integer microUSDC (1 USDC = 10^7 units) so
+ * the record stays JSON-serializable with no floating point precision loss.
+ */
+interface DailySpend {
+    date: string;
+    /** Global accumulated spend for the day, in microUSDC (e.g. "5000000") */
+    totalMicros: string;
+    /** Per-endpoint accumulated spend for the day, keyed by origin URL, in microUSDC */
+    endpoints: Record<string, string>;
+}
+/**
+ * Durable backing store for the client's local daily spend cap.
+ *
+ * The spend cap is a financial safety control: if its accumulator lives only in
+ * heap memory, any crash, OOM kill, or container restart silently resets it to
+ * zero and the cap can be bypassed. Inject a persistent implementation
+ * (Redis, SQL, Supabase, a file, …) so the counter survives restarts.
+ *
+ * ### Sharing a store between processes
+ * The client serializes its own read → check → write with an in-memory mutex,
+ * but that only protects one `RouteDockClient` instance. If more than one
+ * process (or client) can use the same backing store — the MCP server and the
+ * E2E agent share `~/.routedock/spend.json` by default — a plain `read()` /
+ * `write()` pair is a lost-update race: two writers both read total X, both
+ * pass the cap check, and both write X + amount, so a payment vanishes from the
+ * accumulator and the cap can be exceeded. A store that is shared across
+ * processes MUST implement {@link SpendStore.update}, which the client uses
+ * instead of `read()` + `write()` whenever it is present.
+ */
+interface SpendStore {
+    /** Return the persisted accumulator, or null if none has been written yet. */
+    read(): Promise<DailySpend | null>;
+    /** Persist the accumulator. */
+    write(state: DailySpend): Promise<void>;
+    /**
+     * Atomically read-modify-write the accumulator. Optional, but required for
+     * stores shared across processes (see above).
+     *
+     * Implementations must guarantee that no other writer can change the state
+     * between the read that produces `prev` and the write of `fn`'s result:
+     * `fn` receives the current state (or `null`), and returns the new state to
+     * persist, or `undefined` to leave the state unchanged (no write). If `fn`
+     * throws, nothing is written and the error propagates. `fn` is synchronous
+     * in spirit — keep it fast and free of side effects, because an
+     * implementation backed by optimistic concurrency (compare-and-swap) may
+     * call it more than once. Resolves to the state after the update.
+     */
+    update?(fn: (prev: DailySpend | null) => DailySpend | undefined): Promise<DailySpend | null>;
+}
+interface InMemorySpendStoreOptions {
+    /** Log a startup warning about non-durability. Defaults to true. */
+    warn?: boolean;
+    /** Log sink for the non-durability warning. Defaults to a console-backed logger. */
+    logger?: RouteDockLogger;
+}
+/**
+ * Default, non-durable {@link SpendStore}. Holds the accumulator on the heap, so
+ * it resets on every process restart. Logs a startup warning unless silenced.
+ * Use this only for development; inject a persistent store in production.
+ */
+declare class InMemorySpendStore implements SpendStore {
+    private state;
+    constructor(options?: InMemorySpendStoreOptions);
+    read(): Promise<DailySpend | null>;
+    write(state: DailySpend): Promise<void>;
+}
+
+export { type DailySpend as D, InMemorySpendStore as I, type SpendStore as S, type InMemorySpendStoreOptions as a };