@routedock/routedock 0.2.0 → 0.3.0

package/dist/MppSessionHandler-Bq4S-JTE.d.ts

@@ -0,0 +1,215 @@
+import { g as RouteDockLogger, h as RouteDockManifest } from './logger-D8_Q2ytp.js';
+import { RequestHandler } from 'express';
+import { Store } from 'mppx';
+
+/**
+ * Idempotency store for payment settlement.
+ *
+ * `x402Handler` and `MppChargeHandler` settle on every request carrying a
+ * payment header. An agent that retries after a post-settlement network
+ * timeout resends the *same* signed payment, which would settle a second time
+ * and invoke `onSettled` twice — double-counting in billing.
+ *
+ * Before settling, a handler derives an idempotency key from the inbound
+ * payment header(s) *together with the resource being paid for* and checks
+ * this store. On a hit it replays the cached settlement response and skips
+ * both the on-chain settle and `onSettled`. A hit older than
+ * {@link SETTLEMENT_REPLAY_WINDOW_MS}, or one replayed more than
+ * {@link MAX_SETTLEMENT_REPLAYS} times, is rejected instead of replayed so a
+ * leaked header cannot buy unlimited requests.
+ *
+ * `claimReplay` and {@link SettlementRecord.createdAt} are optional so a
+ * custom store written against the original two-method (`get`/`set`) contract
+ * keeps compiling. See {@link checkSettlementReplay} for how a store that
+ * supplies neither bounds a replay.
+ *
+ * The default {@link InMemorySeenTxStore} is per-handler and per-process. For
+ * multi-instance deployments, supply a shared implementation backed by Redis,
+ * Supabase, etc.
+ */
+/** The resource a settlement idempotency key is scoped to. */
+interface SettlementScope {
+    /** HTTP method of the paid request (e.g. `GET`). */
+    method: string;
+    /** Path of the paid request, without query string (e.g. `/price`). */
+    path: string;
+    /** Charge amount as declared by the route's requirements. */
+    amount: string;
+    /** Payee address the route settles to. */
+    payTo: string;
+}
+/** Cached outcome of a settlement, replayed on a duplicate payment. */
+interface SettlementRecord {
+    /** On-chain transaction hash (or settlement reference), if known. */
+    txHash: string | null;
+    /** Response headers to re-apply on a replay (e.g. `X-Payment-Response`). */
+    headers?: Record<string, string>;
+    /**
+     * Epoch milliseconds at which the settlement was recorded. Optional for
+     * backwards compatibility with custom stores that predate the replay bound;
+     * a record without it can only be bounded by the replay count.
+     */
+    createdAt?: number;
+}
+interface SeenTxStore {
+    /** Returns the cached settlement for a key, or `undefined` if unseen. */
+    get(key: string): Promise<SettlementRecord | undefined> | SettlementRecord | undefined;
+    /** Records the settlement outcome for a key. */
+    set(key: string, record: SettlementRecord): Promise<void> | void;
+    /**
+     * Optionally, atomically record one replay of `key` and return the new
+     * replay count. Returns `Infinity` when the key is unknown (e.g. evicted
+     * between a `get` and this call), so the caller treats the payment as spent
+     * rather than replaying an unbounded number of times.
+     *
+     * Optional so a custom store written against the original two-method
+     * (`get`/`set`) contract keeps compiling. A store that omits it is still
+     * bounded by {@link SETTLEMENT_REPLAY_WINDOW_MS} when its records carry
+     * {@link SettlementRecord.createdAt}.
+     */
+    claimReplay?(key: string): Promise<number> | number;
+}
+interface InMemorySeenTxStoreOptions {
+    /** Maximum number of entries before FIFO eviction. Defaults to 10,000. */
+    maxEntries?: number;
+    /** 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;
+}
+/**
+ * How long after a settlement a byte-identical retry may still replay the
+ * cached response. Matches the `maxTimeoutSeconds: 60` both x402 requirement
+ * objects declare, so past this point the payment is expired anyway.
+ */
+declare const SETTLEMENT_REPLAY_WINDOW_MS = 60000;
+/**
+ * How many times one settled payment may be replayed beyond the original
+ * settlement. The SDK's own clients never resend a byte-identical header —
+ * they re-sign on every retry — so a tight limit costs nothing while stopping
+ * a leaked header from buying unlimited requests.
+ */
+declare const MAX_SETTLEMENT_REPLAYS = 1;
+/** Outcome of checking whether an idempotency key may replay a settlement. */
+type SettlementReplayCheck = {
+    kind: 'miss';
+} | {
+    kind: 'replay';
+    record: SettlementRecord;
+} | {
+    kind: 'spent';
+};
+/**
+ * Decide what a payment bearing `key` should do.
+ *
+ * - `miss`  — no cached settlement; fall through to decode and settle.
+ * - `replay`— a fresh settlement within the replay window and under the replay
+ *             limit; re-apply the recorded headers and skip settling.
+ * - `spent` — the settlement is older than the replay window, or has already
+ *             been replayed the maximum number of times; respond 402 without
+ *             decoding, settling, or invoking callbacks.
+ *
+ * The age check runs first so an expired record never touches the replay
+ * counter.
+ *
+ * Custom stores may predate this function and implement only `get`/`set`:
+ *
+ * - a record that carries `createdAt` but a store without `claimReplay` is
+ *   bounded by {@link SETTLEMENT_REPLAY_WINDOW_MS} alone;
+ * - a record without `createdAt` offers no window to check, so a store's own
+ *   `claimReplay` is the only bound available; a store that supplies neither
+ *   replays as it did before this function existed.
+ */
+declare function checkSettlementReplay(store: SeenTxStore, key: string, now?: number): Promise<SettlementReplayCheck>;
+/**
+ * Default in-memory {@link SeenTxStore}. Bounded by `maxEntries` with FIFO
+ * eviction so a long-running process cannot grow without limit.
+ *
+ * **Not durable.** On serverless/edge runtimes each request may land on a
+ * fresh isolate with an empty cache, which causes duplicate settlements.
+ * Supply a persistent implementation (Supabase, Redis, …) in production.
+ */
+declare class InMemorySeenTxStore implements SeenTxStore {
+    private readonly map;
+    private readonly replayCounts;
+    private readonly order;
+    constructor(maxEntriesOrOptions?: number | InMemorySeenTxStoreOptions);
+    private readonly maxEntries;
+    get(key: string): SettlementRecord | undefined;
+    set(key: string, record: SettlementRecord): void;
+    claimReplay(key: string): number;
+}
+/**
+ * Derive a collision-resistant idempotency key from the inbound
+ * payment-bearing headers, scoped to the resource being paid for. Uses
+ * SHA-256 instead of 32-bit FNV-1a (which has a 2^32 keyspace — birthday
+ * collisions become likely well before the 10_000-entry default store is
+ * full).
+ *
+ * x402 clients send the signed payment in `payment-signature` / `x-payment`;
+ * mppx clients send it in `authorization` (the `Payment` scheme). A retry
+ * resends byte-identical headers, so hashing the first present one yields a
+ * stable key.
+ *
+ * The `scope` (method, path, amount, payTo) is hashed alongside the header so
+ * a payment settled for one route can never replay against another route,
+ * even when the same store is shared across routes. Returns `null` when no
+ * payment header is present (nothing to dedupe — e.g. the initial 402
+ * challenge request).
+ */
+declare function paymentIdempotencyKey(getHeader: (name: string) => string | undefined, scope: SettlementScope): Promise<string | null>;
+
+/** Store shape extended with optional atomic update operation. */
+type ChannelStore = Store.Store & {
+    update?: (key: string, fn: (prev: unknown) => unknown) => Promise<unknown>;
+};
+/** Expected payload shape for voucher cumulative amount entries. */
+interface VoucherStoreValue {
+    amount: string;
+    [key: string]: unknown;
+}
+/** Validates that a stored store value is an object containing a numeric string amount. */
+declare function isVoucherStoreValue(value: unknown): value is VoucherStoreValue;
+type Network = 'testnet' | 'mainnet';
+/** Why a live session was flagged as orphaned (never cleanly closed). */
+type OrphanReason = 'connection-closed' | 'idle-timeout';
+/** Latest signed state of an orphaned session, enough for the reconciler to settle. */
+interface OrphanedSessionInfo {
+    /** Cumulative amount of the highest voucher seen (human-readable, 7 dp). */
+    cumulativeAmount: string;
+    /** Hex-encoded signature of the highest voucher seen. */
+    lastSignature: string;
+    /** Number of vouchers received before teardown. */
+    voucherCount: number;
+    /** What triggered the orphan flag. */
+    reason: OrphanReason;
+}
+interface MppSessionHandlerOptions {
+    payeeSecretKey: string;
+    network: Network;
+    channelFactory: string;
+    rate: string;
+    assetContract?: string;
+    manifest: RouteDockManifest;
+    commitmentPublicKey: string;
+    onSettled?: (txHash: string, totalPaid: string, mode: string, payer: string | null) => Promise<void>;
+    onSessionOpen?: (channelId: string, payer: string | null) => Promise<void>;
+    onVoucher?: (channelId: string, voucherIndex: number, cumulativeAmount: string, signature: string) => Promise<void>;
+    onCallbackError?: (err: unknown, cb: string) => void;
+    /**
+     * Called when the client connection drops mid-session or the session goes
+     * idle, before a clean close. Persist the session as `closing` so the
+     * SessionReconciler can settle it with the latest signed voucher.
+     */
+    onOrphaned?: (channelId: string, info: OrphanedSessionInfo) => Promise<void>;
+    /**
+     * Flag the session orphaned after this many milliseconds with no voucher
+     * activity. Disabled when unset.
+     */
+    idleTimeoutMs?: number;
+    /** Log sink for internal error paths. Defaults to a console-backed logger. */
+    logger?: RouteDockLogger;
+}
+declare function createMppSessionHandler(opts: MppSessionHandlerOptions): RequestHandler;
+
+export { type ChannelStore as C, InMemorySeenTxStore as I, MAX_SETTLEMENT_REPLAYS as M, type OrphanedSessionInfo as O, type SeenTxStore as S, type VoucherStoreValue as V, type SettlementRecord as a, type InMemorySeenTxStoreOptions as b, type MppSessionHandlerOptions as c, type OrphanReason as d, SETTLEMENT_REPLAY_WINDOW_MS as e, type SettlementReplayCheck as f, type SettlementScope as g, checkSettlementReplay as h, createMppSessionHandler as i, isVoucherStoreValue as j, paymentIdempotencyKey as p };

package/dist/{ProviderRegistry-C50nyhaF.d.ts → ProviderRegistry-CA_TdREG.d.ts}

@@ -1,7 +1,7 @@
 import { usdcToStroops } from '@routedock/nulth-sdk';
-import { m as SpendStore, a as DailySpend, R as RetryPolicy } from './RouteDockClient-BbkqjhMG.js';
+import { l as SpendStore, a as DailySpend, R as RetryPolicy } from './RouteDockClient-Bh86bVly.js';
 import { ClientStellarSigner } from '@x402/stellar';
-import { R as RouteDockManifest, c as PaymentResult } from './types-DmhmfLzP.js';
+import { h as RouteDockManifest, c as PaymentResult } from './logger-D8_Q2ytp.js';
 import { Keypair } from '@stellar/stellar-sdk';
 import { SupabaseClient } from '@supabase/supabase-js';
 

package/dist/{ProviderRegistry-BJ9oJLVz.d.cts → ProviderRegistry-D-0rqK0N.d.cts}

@@ -1,7 +1,7 @@
 import { usdcToStroops } from '@routedock/nulth-sdk';
-import { m as SpendStore, a as DailySpend, R as RetryPolicy } from './RouteDockClient-B1roCa8h.cjs';
+import { l as SpendStore, a as DailySpend, R as RetryPolicy } from './RouteDockClient-go9aopfF.cjs';
 import { ClientStellarSigner } from '@x402/stellar';
-import { R as RouteDockManifest, c as PaymentResult } from './types-DmhmfLzP.cjs';
+import { h as RouteDockManifest, c as PaymentResult } from './logger-D8_Q2ytp.cjs';
 import { Keypair } from '@stellar/stellar-sdk';
 import { SupabaseClient } from '@supabase/supabase-js';
 

package/dist/{RouteDockClient-B1roCa8h.d.cts → RouteDockClient-Bh86bVly.d.ts}

@@ -1,5 +1,5 @@
 import { Keypair } from '@stellar/stellar-sdk';
-import { P as PaymentMode, R as RouteDockManifest, d as PreflightResult, c as PaymentResult, b as EstimateCostResult, k as SessionOptions, j as SessionHandle } from './types-DmhmfLzP.cjs';
+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.js';
 import { ClientStellarSigner } from '@x402/stellar';
 import { SignAuthEntry } from '@stellar/stellar-sdk/contract';
 import { usdcToStroops } from '@routedock/nulth-sdk';
@@ -18,8 +18,13 @@ interface RetryPolicy {
      * aborting the retry loop.
      */
     onRetry?: (attempt: number, error: Error, nextDelayMs: number) => void | Promise<void>;
+    /**
+     * Log sink for internal diagnostics (an `onRetry` hook that throws).
+     * Defaults to a console-backed logger.
+     */
+    logger?: RouteDockLogger;
 }
-declare const DEFAULT_RETRY_POLICY: Required<Omit<RetryPolicy, 'onRetry'>>;
+declare const DEFAULT_RETRY_POLICY: Required<Omit<RetryPolicy, 'onRetry' | 'logger'>>;
 /**
  * Full jitter exponential backoff delay.
  * Delay range: 0..min(maxDelayMs, baseDelayMs * 2 ** attempt).
@@ -42,7 +47,10 @@ declare function withRetry<T>(fn: () => Promise<T>, policy?: RetryPolicy): Promi
 declare function assertEndpointActive(manifest: RouteDockManifest, url: string, logger?: RouteDockLogger): void;
 /**
  * Validate semantic constraints for manifest fields beyond JSON schema syntax.
- * Enforces that all keys in `latency_hints` must be a subset of declared `regions`.
+ * 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`.
  */
 declare function assertManifestValid(manifest: RouteDockManifest, baseUrl?: string): void;
 /**
@@ -62,7 +70,7 @@ declare function configureManifestCache(maxSize: number): void;
  * to the origin before calling this.
  */
 declare function invalidateManifest(baseUrl: string): void;
-type RouteDockLogger = (message: string) => void;
+
 interface ModeSelectOptions {
     /** Force mpp-session if the provider supports it */
     sustained?: boolean;
@@ -153,6 +161,8 @@ interface NulthClientConfig {
     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';
@@ -235,6 +245,8 @@ interface SpendStore {
 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
@@ -274,7 +286,7 @@ interface RouteDockClientConfig {
     /** Stellar keypair or raw secret key (S...) — fee payer / fallback signer */
     wallet: Keypair | string;
     network: 'testnet' | 'mainnet';
-    /** Optional local daily spend cap — checked before every payment (local-key vault only) */
+    /** Optional local daily spend cap — checked before every payment, nulth vault payments included */
     spendCap?: SpendCap;
     /**
      * Ed25519 secret key (S...) for signing channel commitments. Required for mpp-session.
@@ -367,7 +379,7 @@ declare class RouteDockClient {
      * call before committing to a payment — for approval gates and manual
      * trustline remediation.
      */
-    preflight(manifest: RouteDockManifest): Promise<PreflightResult>;
+    preflight(manifest: RouteDockManifest, mode?: PaymentMode, endpoint?: string): Promise<PreflightResult>;
     /**
      * Verify via Horizon that the payer account has a trustline for the
      * payment asset declared in the manifest. Throws RouteDockTrustlineError
@@ -380,8 +392,10 @@ declare class RouteDockClient {
      * Pay for one request at `url`. Fetches manifest, selects payment mode,
      * runs trustline preflight, reserves local spend cap BEFORE executing the
      * payment, then commits the spend record on success. Rolls back the
-     * reservation if the on-chain payment fails. Concurrent pay() calls are
-     * serialized through a per-instance mutex to prevent spend-cap overrun.
+     * reservation if the on-chain payment fails, and also when the call
+     * completes without paying anything (an x402 endpoint answering a plain
+     * 200 with no challenge). Concurrent pay() calls are serialized through a
+     * per-instance mutex to prevent spend-cap overrun.
      */
     pay(url: string, options?: ModeSelectOptions): Promise<PaymentResult>;
     /** Nulth ZK vault path — proof built off-chain, attached as auth signature */
@@ -452,4 +466,4 @@ declare class RouteDockClient {
     private _rollbackSpend;
 }
 
-export { rankProvidersByLatency as A, selectMode as B, setNulthPaymentContext as C, DEFAULT_RETRY_POLICY as D, usdcToMicros as E, withRetry as F, 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 RouteDockLogger as l, type SpendStore as m, assertEndpointActive as n, assertManifestValid as o, assertNulthVaultManifest as p, backoffDelayMs as q, configureManifestCache as r, createNulthSigner as s, createPolicyState as t, decodeAuthSignature as u, fetchLedgerSequence as v, fetchManifest as w, invalidateManifest as x, paymentContextFromManifest as y, prepareNulthSigner as z };
+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 };

package/dist/{RouteDockClient-BbkqjhMG.d.ts → RouteDockClient-go9aopfF.d.cts}

@@ -1,5 +1,5 @@
 import { Keypair } from '@stellar/stellar-sdk';
-import { P as PaymentMode, R as RouteDockManifest, d as PreflightResult, c as PaymentResult, b as EstimateCostResult, k as SessionOptions, j as SessionHandle } from './types-DmhmfLzP.js';
+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 { ClientStellarSigner } from '@x402/stellar';
 import { SignAuthEntry } from '@stellar/stellar-sdk/contract';
 import { usdcToStroops } from '@routedock/nulth-sdk';
@@ -18,8 +18,13 @@ interface RetryPolicy {
      * aborting the retry loop.
      */
     onRetry?: (attempt: number, error: Error, nextDelayMs: number) => void | Promise<void>;
+    /**
+     * Log sink for internal diagnostics (an `onRetry` hook that throws).
+     * Defaults to a console-backed logger.
+     */
+    logger?: RouteDockLogger;
 }
-declare const DEFAULT_RETRY_POLICY: Required<Omit<RetryPolicy, 'onRetry'>>;
+declare const DEFAULT_RETRY_POLICY: Required<Omit<RetryPolicy, 'onRetry' | 'logger'>>;
 /**
  * Full jitter exponential backoff delay.
  * Delay range: 0..min(maxDelayMs, baseDelayMs * 2 ** attempt).
@@ -42,7 +47,10 @@ declare function withRetry<T>(fn: () => Promise<T>, policy?: RetryPolicy): Promi
 declare function assertEndpointActive(manifest: RouteDockManifest, url: string, logger?: RouteDockLogger): void;
 /**
  * Validate semantic constraints for manifest fields beyond JSON schema syntax.
- * Enforces that all keys in `latency_hints` must be a subset of declared `regions`.
+ * 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`.
  */
 declare function assertManifestValid(manifest: RouteDockManifest, baseUrl?: string): void;
 /**
@@ -62,7 +70,7 @@ declare function configureManifestCache(maxSize: number): void;
  * to the origin before calling this.
  */
 declare function invalidateManifest(baseUrl: string): void;
-type RouteDockLogger = (message: string) => void;
+
 interface ModeSelectOptions {
     /** Force mpp-session if the provider supports it */
     sustained?: boolean;
@@ -153,6 +161,8 @@ interface NulthClientConfig {
     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';
@@ -235,6 +245,8 @@ interface SpendStore {
 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
@@ -274,7 +286,7 @@ interface RouteDockClientConfig {
     /** Stellar keypair or raw secret key (S...) — fee payer / fallback signer */
     wallet: Keypair | string;
     network: 'testnet' | 'mainnet';
-    /** Optional local daily spend cap — checked before every payment (local-key vault only) */
+    /** Optional local daily spend cap — checked before every payment, nulth vault payments included */
     spendCap?: SpendCap;
     /**
      * Ed25519 secret key (S...) for signing channel commitments. Required for mpp-session.
@@ -367,7 +379,7 @@ declare class RouteDockClient {
      * call before committing to a payment — for approval gates and manual
      * trustline remediation.
      */
-    preflight(manifest: RouteDockManifest): Promise<PreflightResult>;
+    preflight(manifest: RouteDockManifest, mode?: PaymentMode, endpoint?: string): Promise<PreflightResult>;
     /**
      * Verify via Horizon that the payer account has a trustline for the
      * payment asset declared in the manifest. Throws RouteDockTrustlineError
@@ -380,8 +392,10 @@ declare class RouteDockClient {
      * Pay for one request at `url`. Fetches manifest, selects payment mode,
      * runs trustline preflight, reserves local spend cap BEFORE executing the
      * payment, then commits the spend record on success. Rolls back the
-     * reservation if the on-chain payment fails. Concurrent pay() calls are
-     * serialized through a per-instance mutex to prevent spend-cap overrun.
+     * reservation if the on-chain payment fails, and also when the call
+     * completes without paying anything (an x402 endpoint answering a plain
+     * 200 with no challenge). Concurrent pay() calls are serialized through a
+     * per-instance mutex to prevent spend-cap overrun.
      */
     pay(url: string, options?: ModeSelectOptions): Promise<PaymentResult>;
     /** Nulth ZK vault path — proof built off-chain, attached as auth signature */
@@ -452,4 +466,4 @@ declare class RouteDockClient {
     private _rollbackSpend;
 }
 
-export { rankProvidersByLatency as A, selectMode as B, setNulthPaymentContext as C, DEFAULT_RETRY_POLICY as D, usdcToMicros as E, withRetry as F, 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 RouteDockLogger as l, type SpendStore as m, assertEndpointActive as n, assertManifestValid as o, assertNulthVaultManifest as p, backoffDelayMs as q, configureManifestCache as r, createNulthSigner as s, createPolicyState as t, decodeAuthSignature as u, fetchLedgerSequence as v, fetchManifest as w, invalidateManifest as x, paymentContextFromManifest as y, prepareNulthSigner as z };
+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 };

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

@@ -1,6 +1,6 @@
 import { SupabaseClient } from '@supabase/supabase-js';
-import { S as SeenTxStore, a as SettlementRecord } from './MppSessionHandler-CLB5SzgN.js';
-import { R as RouteDockManifest } from './types-DmhmfLzP.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 { Keypair } from '@stellar/stellar-sdk';
 
 /**
@@ -16,7 +16,9 @@ import { Keypair } from '@stellar/stellar-sdk';
  * would not, since a retry can outrun propagation and reintroduce the double
  * settle.
  *
- * Requires the `settlements` table from migration `003_settlement_idempotency`:
+ * Requires the `settlements` table from migration `003_settlement_idempotency`
+ * and the `claim_settlement_replay` function from migration
+ * `006_settlement_replay_limit`:
  *
  * ```sql
  * CREATE TABLE settlements (
@@ -29,7 +31,7 @@ import { Keypair } from '@stellar/stellar-sdk';
  *
  * @example
  * ```ts
- * import { SupabaseSeenTxStore } from '@routedock/routedock/store'
+ * import { SupabaseSeenTxStore } from '@routedock/routedock/provider/hono'
  * import { createClient } from '@supabase/supabase-js'
  *
  * const supabase = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_KEY!)
@@ -43,6 +45,13 @@ declare class SupabaseSeenTxStore implements SeenTxStore {
     constructor(supabase: SupabaseClient);
     get(key: string): Promise<SettlementRecord | undefined>;
     set(key: string, record: SettlementRecord): Promise<void>;
+    /**
+     * Atomically increment the settlement's replay counter through the
+     * `claim_settlement_replay` Postgres function (migration 006). The UPDATE's
+     * row lock gives concurrent claims distinct counts. Returns `Infinity` when
+     * the key no longer exists, so the caller treats it as spent.
+     */
+    claimReplay(key: string): Promise<number>;
 }
 
 interface RegisterProviderOptions {
@@ -120,6 +129,6 @@ declare function reconcileAbandonedSessions(opts: SessionReconcilerOptions): Pro
  * Run reconciliation on provider startup.
  * Logs results and recovers orphaned sessions before accepting new connections.
  */
-declare function runStartupReconciliation(opts: SessionReconcilerOptions, logger?: (msg: string) => void): Promise<void>;
+declare function runStartupReconciliation(opts: SessionReconcilerOptions, logger?: RouteDockLogger): Promise<void>;
 
 export { type ReconciliationStats as R, type SessionReconcilerOptions as S, type RegisterProviderOptions as a, SupabaseSeenTxStore as b, registerProvider as c, decimalToStroops as d, runStartupReconciliation as e, reconcileAbandonedSessions as r };

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

@@ -1,6 +1,6 @@
 import { SupabaseClient } from '@supabase/supabase-js';
-import { S as SeenTxStore, a as SettlementRecord } from './MppSessionHandler-B4TyD7Xg.cjs';
-import { R as RouteDockManifest } from './types-DmhmfLzP.cjs';
+import { S as SeenTxStore, a as SettlementRecord } from './MppSessionHandler-1EL8QBAn.cjs';
+import { h as RouteDockManifest, g as RouteDockLogger } from './logger-D8_Q2ytp.cjs';
 import { Keypair } from '@stellar/stellar-sdk';
 
 /**
@@ -16,7 +16,9 @@ import { Keypair } from '@stellar/stellar-sdk';
  * would not, since a retry can outrun propagation and reintroduce the double
  * settle.
  *
- * Requires the `settlements` table from migration `003_settlement_idempotency`:
+ * Requires the `settlements` table from migration `003_settlement_idempotency`
+ * and the `claim_settlement_replay` function from migration
+ * `006_settlement_replay_limit`:
  *
  * ```sql
  * CREATE TABLE settlements (
@@ -29,7 +31,7 @@ import { Keypair } from '@stellar/stellar-sdk';
  *
  * @example
  * ```ts
- * import { SupabaseSeenTxStore } from '@routedock/routedock/store'
+ * import { SupabaseSeenTxStore } from '@routedock/routedock/provider/hono'
  * import { createClient } from '@supabase/supabase-js'
  *
  * const supabase = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_KEY!)
@@ -43,6 +45,13 @@ declare class SupabaseSeenTxStore implements SeenTxStore {
     constructor(supabase: SupabaseClient);
     get(key: string): Promise<SettlementRecord | undefined>;
     set(key: string, record: SettlementRecord): Promise<void>;
+    /**
+     * Atomically increment the settlement's replay counter through the
+     * `claim_settlement_replay` Postgres function (migration 006). The UPDATE's
+     * row lock gives concurrent claims distinct counts. Returns `Infinity` when
+     * the key no longer exists, so the caller treats it as spent.
+     */
+    claimReplay(key: string): Promise<number>;
 }
 
 interface RegisterProviderOptions {
@@ -120,6 +129,6 @@ declare function reconcileAbandonedSessions(opts: SessionReconcilerOptions): Pro
  * Run reconciliation on provider startup.
  * Logs results and recovers orphaned sessions before accepting new connections.
  */
-declare function runStartupReconciliation(opts: SessionReconcilerOptions, logger?: (msg: string) => void): Promise<void>;
+declare function runStartupReconciliation(opts: SessionReconcilerOptions, logger?: RouteDockLogger): Promise<void>;
 
 export { type ReconciliationStats as R, type SessionReconcilerOptions as S, type RegisterProviderOptions as a, SupabaseSeenTxStore as b, registerProvider as c, decimalToStroops as d, runStartupReconciliation as e, reconcileAbandonedSessions as r };

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

@@ -1,5 +1,5 @@
+import { h as RouteDockManifest, P as PaymentMode, A as AssetConfig, p as SessionState } from './logger-D8_Q2ytp.cjs';
 import { SupabaseClient } from '@supabase/supabase-js';
-import { m as SessionState } from './types-DmhmfLzP.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';
@@ -90,6 +90,38 @@ declare function parseRetryAfterMs(response: Response): number | undefined;
 declare function httpStatusToError(message: string, status: number, response?: Response): RouteDockError;
 /** Wrap a low-level fetch failure; preserves existing RouteDockErrors. */
 declare function wrapFetchError(err: unknown, context: string): RouteDockError;
+/**
+ * Wrap an mppx failure; differentiates network transport errors from signing/credential errors.
+ * Real transport failures (fetch TypeError, AbortError, TimeoutError) are wrapped as retryable
+ * RouteDockNetworkError, while signing and challenge failures are wrapped as non-retryable
+ * RouteDockSignatureError.
+ */
+declare function wrapMppError(err: unknown, context: string): RouteDockError;
+
+/**
+ * Normalizes a manifest to always have an assets array.
+ * Handles backward compatibility with root asset/asset_contract fields.
+ */
+declare function normalizeManifestAssets(manifest: RouteDockManifest): AssetConfig[];
+/**
+ * Finds eligible assets for a given mode and optional endpoint.
+ * Returns all assets that match the criteria.
+ */
+declare function getEligibleAssets(manifest: RouteDockManifest, mode: PaymentMode, endpoint?: string): AssetConfig[];
+/**
+ * Resolves the asset contract for a mode and optional endpoint.
+ * Honors manifest.assets when defined; falls back to explicitContract or root asset_contract.
+ */
+declare function resolveAssetContract(manifest: RouteDockManifest, mode: PaymentMode, endpoint?: string, explicitContract?: string): string;
+/**
+ * Selects a single asset for payment, given a mode and optional endpoint.
+ * Returns the first eligible asset, or throws if none are available.
+ */
+declare function selectAsset(manifest: RouteDockManifest, mode: PaymentMode, endpoint?: string): AssetConfig;
+/**
+ * Checks if a specific asset (by ticker or contract address) is eligible for a mode/endpoint.
+ */
+declare function isAssetEligible(manifest: RouteDockManifest, assetIdentifier: string, mode: PaymentMode, endpoint?: string): boolean;
 
 interface SessionStore {
     get(channelId: string): Promise<SessionState | null>;
@@ -108,4 +140,4 @@ declare class SupabaseSessionStore implements SessionStore {
     close(channelId: string): Promise<void>;
 }
 
-export { 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, httpStatusToError as t, parseRetryAfterMs as u, wrapFetchError as w };
+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 };

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

@@ -1,5 +1,5 @@
+import { h as RouteDockManifest, P as PaymentMode, A as AssetConfig, p as SessionState } from './logger-D8_Q2ytp.js';
 import { SupabaseClient } from '@supabase/supabase-js';
-import { m as SessionState } from './types-DmhmfLzP.cjs';
 
 /** 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';
@@ -90,6 +90,38 @@ declare function parseRetryAfterMs(response: Response): number | undefined;
 declare function httpStatusToError(message: string, status: number, response?: Response): RouteDockError;
 /** Wrap a low-level fetch failure; preserves existing RouteDockErrors. */
 declare function wrapFetchError(err: unknown, context: string): RouteDockError;
+/**
+ * Wrap an mppx failure; differentiates network transport errors from signing/credential errors.
+ * Real transport failures (fetch TypeError, AbortError, TimeoutError) are wrapped as retryable
+ * RouteDockNetworkError, while signing and challenge failures are wrapped as non-retryable
+ * RouteDockSignatureError.
+ */
+declare function wrapMppError(err: unknown, context: string): RouteDockError;
+
+/**
+ * Normalizes a manifest to always have an assets array.
+ * Handles backward compatibility with root asset/asset_contract fields.
+ */
+declare function normalizeManifestAssets(manifest: RouteDockManifest): AssetConfig[];
+/**
+ * Finds eligible assets for a given mode and optional endpoint.
+ * Returns all assets that match the criteria.
+ */
+declare function getEligibleAssets(manifest: RouteDockManifest, mode: PaymentMode, endpoint?: string): AssetConfig[];
+/**
+ * Resolves the asset contract for a mode and optional endpoint.
+ * Honors manifest.assets when defined; falls back to explicitContract or root asset_contract.
+ */
+declare function resolveAssetContract(manifest: RouteDockManifest, mode: PaymentMode, endpoint?: string, explicitContract?: string): string;
+/**
+ * Selects a single asset for payment, given a mode and optional endpoint.
+ * Returns the first eligible asset, or throws if none are available.
+ */
+declare function selectAsset(manifest: RouteDockManifest, mode: PaymentMode, endpoint?: string): AssetConfig;
+/**
+ * Checks if a specific asset (by ticker or contract address) is eligible for a mode/endpoint.
+ */
+declare function isAssetEligible(manifest: RouteDockManifest, assetIdentifier: string, mode: PaymentMode, endpoint?: string): boolean;
 
 interface SessionStore {
     get(channelId: string): Promise<SessionState | null>;
@@ -108,4 +140,4 @@ declare class SupabaseSessionStore implements SessionStore {
     close(channelId: string): Promise<void>;
 }
 
-export { 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, httpStatusToError as t, parseRetryAfterMs as u, wrapFetchError as w };
+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 };