@routedock/routedock 0.3.1 → 0.4.0

package/dist/{RouteDockClient-CjM2VyOd.d.ts → RouteDockClient-6rmgkbYb.d.cts}

@@ -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.js';
+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.cjs';
+import { b as RouteDockLogger } from './logger-DVa7VT4c.cjs';
 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-s_dfcemj.cjs';
 
 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 };