@routedock/routedock 0.3.0 → 0.4.0

package/README.md

@@ -1,17 +1,21 @@
-# @routedock/sdk
+# @routedock/routedock
 
 Unified payment execution layer for autonomous agents on Stellar. One SDK for x402, MPP charge, and MPP session — mode selected automatically from the provider's `routedock.json` manifest.
 
+## Requirements
+
+Node.js **22 or newer**, matching the supported runtime of all RouteDock npm packages.
+
 ## Install
 
 ```bash
-npm install @routedock/sdk
+npm install @routedock/routedock
 ```
 
 ## Agent Usage
 
 ```ts
-import { RouteDockClient } from '@routedock/sdk/client'
+import { RouteDockClient } from '@routedock/routedock/client'
 import { Keypair } from '@stellar/stellar-sdk'
 
 const client = new RouteDockClient({
@@ -35,6 +39,47 @@ for await (const update of session.stream()) {
 await session.close() // triggers on-chain settlement
 ```
 
+### POST endpoints and custom headers
+
+`pay()` sends a `GET` with no body by default. For endpoints that take input,
+pass `request` with the method, headers and body to send:
+
+```ts
+const result = await client.pay('https://provider.example.com/infer', {
+  request: {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-trace-id': 'trace-123' },
+    body: JSON.stringify({ prompt: 'Explain MPP charge in one sentence' }),
+  },
+})
+```
+
+The same request is replayed on the unpaid 402 probe, the paid request and any
+retry, so the body is buffered once (streams are drained up front). Payment
+headers set by the SDK — `PAYMENT-SIGNATURE`/`X-PAYMENT` for x402 and
+`Authorization` for MPP — always win over a caller header with the same name.
+The method also scopes the per-endpoint sunset check, so a sunset `GET /infer`
+no longer blocks an active `POST /infer`.
+
+Sessions accept the same field per stream:
+
+```ts
+for await (const update of session.stream({
+  request: { method: 'POST', body: JSON.stringify({ channel: 'XLM/USDC' }) },
+})) {
+  console.log(update)
+}
+```
+
+### Spend cap and other assets
+
+The cap is a single USDC total. If the asset selected for a payment is not
+`spendCap.asset` (for example a provider that prices in XLM), `pay()` and
+`openSession()` throw `RouteDockPolicyRejectError` with reason
+`local_cap_asset_mismatch` before anything is paid, and nothing is added to the
+USDC total. USDC-only providers are unaffected. See
+`docs/MULTI_ASSET_SUPPORT.md`.
+
 ### Durable spend cap
 
 The `spendCap` is enforced via a pluggable `SpendStore` (`read()` / `write()`).
@@ -44,7 +89,7 @@ production, inject a persistent implementation so a crash or restart can't reset
 the accumulator and bypass the cap:
 
 ```ts
-import { RouteDockClient, type SpendStore, type DailySpend } from '@routedock/sdk/client'
+import { RouteDockClient, type SpendStore, type DailySpend } from '@routedock/routedock/client'
 
 const redisSpendStore: SpendStore = {
   async read(): Promise<DailySpend | null> {
@@ -64,11 +109,42 @@ const client = new RouteDockClient({
 })
 ```
 
+On Node you can use the file-backed store instead. It depends on `node:fs`, so it
+lives in a Node-only entry point and is **not** exported from `/client`:
+
+```ts
+import { RouteDockClient } from '@routedock/routedock/client'
+import { FileSpendStore } from '@routedock/routedock/node' // Node only (node:fs)
+
+const client = new RouteDockClient({
+  // ...
+  spendStore: new FileSpendStore('~/.routedock/spend.json'),
+})
+```
+
+**Sharing one store between processes.** The client serializes its own
+read → check → write, but that only protects one `RouteDockClient`. If two
+processes can use the same store (the MCP server and the example agent both
+default to `~/.routedock/spend.json`), a plain `read()` / `write()` store can
+lose updates and let the cap be exceeded. A shared store must implement the
+optional atomic `update(fn)` method, which the client uses automatically.
+`FileSpendStore` implements it with an exclusive lock file
+(`<file>.lock`, stale locks from crashed processes are broken after 10 s):
+
+```ts
+const store: SpendStore = {
+  read, write,
+  // fn(prev) returns the next state, or undefined to leave it unchanged.
+  // Make the read, fn and write atomic (a transaction, CAS loop, lock, ...).
+  async update(fn) { /* ... */ },
+}
+```
+
 ## Provider Usage
 
 ```ts
 import express from 'express'
-import { routedock } from '@routedock/sdk/provider'
+import { routedock } from '@routedock/routedock/provider'
 
 const app = express()
 
@@ -441,6 +517,26 @@ import from `@routedock/routedock/provider` in a Workers snippet — that's the
 Node-only Express entry point and pulls in dependencies (like `express`) that
 don't run on Workers.
 
+### Runtime-neutral entry points
+
+`@routedock/routedock/client`, `/react` and `/provider/hono` use only
+Web-standard APIs. They run in browsers, Cloudflare Workers (no `nodejs_compat`
+needed for this package), Bun, Deno and Node, and contain no `node:*` imports or
+`Buffer` references. CI enforces this (`node scripts/check-runtime-neutral.mjs`)
+against the built output.
+
+Anything that needs Node built-ins is kept out of those entries:
+
+| Import | Runtime | Notes |
+| --- | --- | --- |
+| `@routedock/routedock/client`, `/react`, `/provider/hono` | any | runtime-neutral |
+| `@routedock/routedock/node` | Node only | `FileSpendStore` (`node:fs`) |
+| `@routedock/routedock/provider`, `/provider/fastify` | Node only | Express/Fastify adapters |
+| `@routedock/routedock` | Node | full SDK, includes `FileSpendStore` |
+
+Third-party dependencies are outside this guarantee: for example `mppx` imports
+`node:util`, so a Worker that uses it can still need `nodejs_compat`.
+
 ## React Integration
 
 > **Warning:** These hooks create a RouteDockClient in the browser, so the wallet secret and any commitmentSecret are readable by anyone who loads the page.
@@ -451,10 +547,10 @@ don't run on Workers.
 >
 > For production or mainnet, keep RouteDockClient on the server (a route handler or server action) and read the key from a non-public variable such as `AGENT_SECRET`, as the Agent Usage section does.
 
-`@routedock/sdk/react` provides hooks for client construction, payments, sessions, and live tx log subscription. Wrap your app with `RouteDockProvider`:
+`@routedock/routedock/react` provides hooks for client construction, payments, sessions, and live tx log subscription. Wrap your app with `RouteDockProvider`:
 
 ```tsx
-import { RouteDockProvider, useRouteDockClient } from '@routedock/sdk/react'
+import { RouteDockProvider, useRouteDockClient } from '@routedock/routedock/react'
 import { createClient } from '@supabase/supabase-js'
 
 // Dedicated throwaway testnet key. Never a funded or mainnet key.
@@ -482,7 +578,7 @@ function App({ children }: { children: React.ReactNode }) {
 
 ```ts
 // app/api/price/route.ts (runs on the server only)
-import { RouteDockClient } from '@routedock/sdk/client'
+import { RouteDockClient } from '@routedock/routedock/client'
 
 const client = new RouteDockClient({
   wallet: process.env.AGENT_SECRET!,
@@ -499,7 +595,7 @@ export async function POST() {
 ### `usePay(url, options?)`
 
 ```tsx
-import { usePay } from '@routedock/sdk/react'
+import { usePay } from '@routedock/routedock/react'
 
 function PriceButton() {
   const { pay, result, loading, error } = usePay('https://provider.example.com/price')
@@ -516,7 +612,7 @@ function PriceButton() {
 
 ```tsx
 import { useEffect } from 'react'
-import { useSession } from '@routedock/sdk/react'
+import { useSession } from '@routedock/routedock/react'
 
 function StreamingFeed() {
   const { open, close, status, vouchers, cumulative } = useSession(
@@ -537,7 +633,7 @@ The hook automatically fires `session.close()` in the background on unmount when
 ### `useTxLog(filter?)`
 
 ```tsx
-import { useTxLog } from '@routedock/sdk/react'
+import { useTxLog } from '@routedock/routedock/react'
 
 function ActivityFeed({ channelId }: { channelId: string }) {
   const txLog = useTxLog({ channelId, limit: 25 })
@@ -572,8 +668,9 @@ import {
   RouteDockError,
   RouteDockFacilitatorError,
   RouteDockManifestError,
+  RouteDockPaymentRejectedError,
   RouteDockPolicyRejectError,
-} from '@routedock/sdk/client'
+} from '@routedock/routedock/client'
 
 const client = new RouteDockClient({
   wallet: process.env.AGENT_SECRET!,
@@ -587,6 +684,9 @@ try {
 } catch (err) {
   if (err instanceof RouteDockPolicyRejectError) {
     console.error('Spend cap exceeded:', err.reason)
+  } else if (err instanceof RouteDockPaymentRejectedError) {
+    // The provider refused the signed payment; `reason` is its explanation.
+    console.error(`Payment rejected (HTTP ${err.status}):`, err.reason ?? err.providerError)
   } else if (err instanceof RouteDockFacilitatorError) {
     console.error(`Facilitator HTTP ${err.status} (retryable=${err.retryable})`)
   } else if (err instanceof RouteDockManifestError) {
@@ -604,6 +704,7 @@ try {
 | `RouteDockManifestError` | no | Invalid manifest, missing pricing fields |
 | `RouteDockNoSupportedModeError` | no | Provider has no compatible payment mode |
 | `RouteDockFacilitatorError` | yes | Facilitator/provider 429 or 5xx |
+| `RouteDockPaymentRejectedError` | no | Provider refused the signed paid request (HTTP 401/402/other 4xx); `status` and `reason` carry why |
 | `RouteDockNetworkError` | yes | Timeouts, connection failures |
 | `RouteDockSignatureError` | no | Signing or commitment failure |
 | `RouteDockVoucherMonotonicityError` | no | Non-increasing voucher amount |

package/dist/{MppSessionHandler-1EL8QBAn.d.cts → MppSessionHandler-3QfCHI5x.d.ts}

@@ -1,6 +1,7 @@
-import { g as RouteDockLogger, h as RouteDockManifest } from './logger-D8_Q2ytp.cjs';
+import { b as RouteDockLogger } from './logger-DVa7VT4c.js';
 import { RequestHandler } from 'express';
 import { Store } from 'mppx';
+import { R as RouteDockManifest } from './types-DXaS5Wip.js';
 
 /**
  * Idempotency store for payment settlement.
@@ -99,6 +100,20 @@ type SettlementReplayCheck = {
 } | {
     kind: 'spent';
 };
+/**
+ * Record a settlement so a retry of the same payment is deduped.
+ *
+ * Call this only AFTER the payment has settled. By then the funds have moved,
+ * so a failing store write must not turn a paid request into a 500: the
+ * failure is logged and reported through `onCallbackError(err, 'seenTxStore.set')`
+ * and the request carries on to `onSettled` and the route. Never throws.
+ */
+declare function recordSettlement(store: SeenTxStore, key: string, record: SettlementRecord, ctx: {
+    logger: RouteDockLogger;
+    /** Log prefix, e.g. `[x402]` or `[mpp-charge]`. */
+    label: string;
+    onCallbackError?: ((err: unknown, cb: string) => void) | undefined;
+}): Promise<void>;
 /**
  * Decide what a payment bearing `key` should do.
  *
@@ -159,6 +174,22 @@ declare class InMemorySeenTxStore implements SeenTxStore {
  */
 declare function paymentIdempotencyKey(getHeader: (name: string) => string | undefined, scope: SettlementScope): Promise<string | null>;
 
+/**
+ * Explicit provider configuration for recording `session_settled` on the
+ * agent vault after a clean mpp-session close.
+ *
+ * This replaced the old `process.env.AGENT_VAULT_CONTRACT` read inside the
+ * provider handlers: Workers have no `process.env` without `nodejs_compat`,
+ * and the docs told operators to set `AGENT_VAULT_CONTRACT_ID`, which the SDK
+ * never read. Passing the contract in as an option works on every runtime.
+ */
+interface VaultSettlementConfig {
+    /** Agent vault contract id (C...) whose `record_session_settlement` entry point records the session. */
+    contract: string;
+    /** Soroban RPC endpoint override; defaults to the public endpoint for the configured network. */
+    rpcUrl?: string;
+}
+
 /** Store shape extended with optional atomic update operation. */
 type ChannelStore = Store.Store & {
     update?: (key: string, fn: (prev: unknown) => unknown) => Promise<unknown>;
@@ -209,7 +240,14 @@ interface MppSessionHandlerOptions {
     idleTimeoutMs?: number;
     /** Log sink for internal error paths. Defaults to a console-backed logger. */
     logger?: RouteDockLogger;
+    /**
+     * Record `session_settled` on the agent vault after each clean close.
+     * `contract` is the vault's C... id; `rpcUrl` overrides the default Soroban
+     * RPC endpoint for the configured network. Falls back to the deprecated
+     * `AGENT_VAULT_CONTRACT`/`AGENT_VAULT_CONTRACT_ID` env vars when unset.
+     */
+    vaultSettlement?: VaultSettlementConfig;
 }
 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 };
+export { type ChannelStore as C, InMemorySeenTxStore as I, MAX_SETTLEMENT_REPLAYS as M, type OrphanedSessionInfo as O, type SeenTxStore as S, type VaultSettlementConfig 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, type VoucherStoreValue as h, checkSettlementReplay as i, createMppSessionHandler as j, isVoucherStoreValue as k, paymentIdempotencyKey as p, recordSettlement as r };

package/dist/{MppSessionHandler-Bq4S-JTE.d.ts → MppSessionHandler-xu4Kxu6N.d.cts}

@@ -1,6 +1,7 @@
-import { g as RouteDockLogger, h as RouteDockManifest } from './logger-D8_Q2ytp.js';
+import { b as RouteDockLogger } from './logger-DVa7VT4c.cjs';
 import { RequestHandler } from 'express';
 import { Store } from 'mppx';
+import { R as RouteDockManifest } from './types-DXaS5Wip.cjs';
 
 /**
  * Idempotency store for payment settlement.
@@ -99,6 +100,20 @@ type SettlementReplayCheck = {
 } | {
     kind: 'spent';
 };
+/**
+ * Record a settlement so a retry of the same payment is deduped.
+ *
+ * Call this only AFTER the payment has settled. By then the funds have moved,
+ * so a failing store write must not turn a paid request into a 500: the
+ * failure is logged and reported through `onCallbackError(err, 'seenTxStore.set')`
+ * and the request carries on to `onSettled` and the route. Never throws.
+ */
+declare function recordSettlement(store: SeenTxStore, key: string, record: SettlementRecord, ctx: {
+    logger: RouteDockLogger;
+    /** Log prefix, e.g. `[x402]` or `[mpp-charge]`. */
+    label: string;
+    onCallbackError?: ((err: unknown, cb: string) => void) | undefined;
+}): Promise<void>;
 /**
  * Decide what a payment bearing `key` should do.
  *
@@ -159,6 +174,22 @@ declare class InMemorySeenTxStore implements SeenTxStore {
  */
 declare function paymentIdempotencyKey(getHeader: (name: string) => string | undefined, scope: SettlementScope): Promise<string | null>;
 
+/**
+ * Explicit provider configuration for recording `session_settled` on the
+ * agent vault after a clean mpp-session close.
+ *
+ * This replaced the old `process.env.AGENT_VAULT_CONTRACT` read inside the
+ * provider handlers: Workers have no `process.env` without `nodejs_compat`,
+ * and the docs told operators to set `AGENT_VAULT_CONTRACT_ID`, which the SDK
+ * never read. Passing the contract in as an option works on every runtime.
+ */
+interface VaultSettlementConfig {
+    /** Agent vault contract id (C...) whose `record_session_settlement` entry point records the session. */
+    contract: string;
+    /** Soroban RPC endpoint override; defaults to the public endpoint for the configured network. */
+    rpcUrl?: string;
+}
+
 /** Store shape extended with optional atomic update operation. */
 type ChannelStore = Store.Store & {
     update?: (key: string, fn: (prev: unknown) => unknown) => Promise<unknown>;
@@ -209,7 +240,14 @@ interface MppSessionHandlerOptions {
     idleTimeoutMs?: number;
     /** Log sink for internal error paths. Defaults to a console-backed logger. */
     logger?: RouteDockLogger;
+    /**
+     * Record `session_settled` on the agent vault after each clean close.
+     * `contract` is the vault's C... id; `rpcUrl` overrides the default Soroban
+     * RPC endpoint for the configured network. Falls back to the deprecated
+     * `AGENT_VAULT_CONTRACT`/`AGENT_VAULT_CONTRACT_ID` env vars when unset.
+     */
+    vaultSettlement?: VaultSettlementConfig;
 }
 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 };
+export { type ChannelStore as C, InMemorySeenTxStore as I, MAX_SETTLEMENT_REPLAYS as M, type OrphanedSessionInfo as O, type SeenTxStore as S, type VaultSettlementConfig 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, type VoucherStoreValue as h, checkSettlementReplay as i, createMppSessionHandler as j, isVoucherStoreValue as k, paymentIdempotencyKey as p, recordSettlement as r };

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

@@ -1,8 +1,7 @@
 import { usdcToStroops } from '@routedock/nulth-sdk';
-import { l as SpendStore, a as DailySpend, R as RetryPolicy } from './RouteDockClient-Bh86bVly.js';
-import { ClientStellarSigner } from '@x402/stellar';
-import { h as RouteDockManifest, c as PaymentResult } from './logger-D8_Q2ytp.js';
+import { R as RouteDockManifest, c as PaymentRequest, d as PaymentResult } from './types-DXaS5Wip.cjs';
 import { Keypair } from '@stellar/stellar-sdk';
+import { R as RetryPolicy } from './RouteDockClient-6rmgkbYb.cjs';
 import { SupabaseClient } from '@supabase/supabase-js';
 
 /**
@@ -20,46 +19,27 @@ import { SupabaseClient } from '@supabase/supabase-js';
 declare const usdcToUnits: typeof usdcToStroops;
 
 /**
- * File-backed durable {@link SpendStore}.
+ * 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`.
+ * - Every mode in `modes` has a matching `pricing` entry, so `pay()` and
+ *   `estimateCost()` never read a missing price.
+ * - Every entry in `deprecated_modes` is also listed in `modes`.
+ * - Every price (`amount`, `rate`, `min_deposit`) is a decimal the SDK can
+ *   convert to base units (non-negative, at most 7 fractional digits).
  *
- * Persists the daily spend accumulator to a JSON file on disk, preserving
- * cumulative spending totals across process restarts, crashes, and redeploys.
- *
- * ### Error semantics
- * - File absent (ENOENT): returns null — legitimately no spend recorded yet.
- * - File present but unreadable or malformed: throws — a safety control must
- *   fail closed, not assume nothing was spent.
- *
- * ### Write atomicity
- * Writes go to `<filePath>.tmp` first, then `fs.rename` onto the target.
- * `rename` is atomic within a filesystem, so there is no window where the
- * target file is truncated but not yet fully written.
+ * Every failure is a {@link RouteDockManifestError}.
  */
-declare class FileSpendStore implements SpendStore {
-    readonly filePath: string;
-    constructor(filePath: string);
-    read(): Promise<DailySpend | null>;
-    write(state: DailySpend): Promise<void>;
-}
-
-type Network = 'testnet' | 'mainnet';
-declare class X402Client {
-    private readonly network;
-    private readonly retryPolicy?;
-    private readonly httpClient;
-    private readonly signer;
-    constructor(secretKeyOrSigner: string | ClientStellarSigner, network: Network, retryPolicy?: RetryPolicy | undefined);
-    /** Replace signer (e.g. swap to Nulth ZK account payer before pay) */
-    withSigner(signer: ClientStellarSigner): X402Client;
-    pay(url: string, manifest: RouteDockManifest): Promise<PaymentResult>;
-}
+declare function assertManifestValid(manifest: RouteDockManifest, baseUrl?: string): void;
 
 declare class MppChargeClient {
     private readonly keypair;
     private readonly network;
     private readonly retryPolicy?;
     constructor(keypair: Keypair, network: 'testnet' | 'mainnet', retryPolicy?: RetryPolicy | undefined);
-    pay(url: string, manifest: RouteDockManifest): Promise<PaymentResult>;
+    pay(url: string, manifest: RouteDockManifest, request?: PaymentRequest): Promise<PaymentResult>;
 }
 
 interface OnChainProviderInfo {
@@ -139,4 +119,4 @@ declare class ProviderRegistry {
     fetchProviderManifest(record: ProviderRecord): Promise<RouteDockManifest>;
 }
 
-export { FileSpendStore as F, MppChargeClient as M, type OnChainProviderInfo as O, type ProviderRecord as P, X402Client as X, OnChainRegistry as a, ProviderRegistry as b, type ProviderRegistryConfig as c, usdcToUnits as u };
+export { MppChargeClient as M, type OnChainProviderInfo as O, type ProviderRecord as P, OnChainRegistry as a, ProviderRegistry as b, type ProviderRegistryConfig as c, assertManifestValid as d, usdcToUnits as u };

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

@@ -1,8 +1,7 @@
 import { usdcToStroops } from '@routedock/nulth-sdk';
-import { l as SpendStore, a as DailySpend, R as RetryPolicy } from './RouteDockClient-go9aopfF.cjs';
-import { ClientStellarSigner } from '@x402/stellar';
-import { h as RouteDockManifest, c as PaymentResult } from './logger-D8_Q2ytp.cjs';
+import { R as RouteDockManifest, c as PaymentRequest, d as PaymentResult } from './types-DXaS5Wip.js';
 import { Keypair } from '@stellar/stellar-sdk';
+import { R as RetryPolicy } from './RouteDockClient-CnAkxwrW.js';
 import { SupabaseClient } from '@supabase/supabase-js';
 
 /**
@@ -20,46 +19,27 @@ import { SupabaseClient } from '@supabase/supabase-js';
 declare const usdcToUnits: typeof usdcToStroops;
 
 /**
- * File-backed durable {@link SpendStore}.
+ * 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`.
+ * - Every mode in `modes` has a matching `pricing` entry, so `pay()` and
+ *   `estimateCost()` never read a missing price.
+ * - Every entry in `deprecated_modes` is also listed in `modes`.
+ * - Every price (`amount`, `rate`, `min_deposit`) is a decimal the SDK can
+ *   convert to base units (non-negative, at most 7 fractional digits).
  *
- * Persists the daily spend accumulator to a JSON file on disk, preserving
- * cumulative spending totals across process restarts, crashes, and redeploys.
- *
- * ### Error semantics
- * - File absent (ENOENT): returns null — legitimately no spend recorded yet.
- * - File present but unreadable or malformed: throws — a safety control must
- *   fail closed, not assume nothing was spent.
- *
- * ### Write atomicity
- * Writes go to `<filePath>.tmp` first, then `fs.rename` onto the target.
- * `rename` is atomic within a filesystem, so there is no window where the
- * target file is truncated but not yet fully written.
+ * Every failure is a {@link RouteDockManifestError}.
  */
-declare class FileSpendStore implements SpendStore {
-    readonly filePath: string;
-    constructor(filePath: string);
-    read(): Promise<DailySpend | null>;
-    write(state: DailySpend): Promise<void>;
-}
-
-type Network = 'testnet' | 'mainnet';
-declare class X402Client {
-    private readonly network;
-    private readonly retryPolicy?;
-    private readonly httpClient;
-    private readonly signer;
-    constructor(secretKeyOrSigner: string | ClientStellarSigner, network: Network, retryPolicy?: RetryPolicy | undefined);
-    /** Replace signer (e.g. swap to Nulth ZK account payer before pay) */
-    withSigner(signer: ClientStellarSigner): X402Client;
-    pay(url: string, manifest: RouteDockManifest): Promise<PaymentResult>;
-}
+declare function assertManifestValid(manifest: RouteDockManifest, baseUrl?: string): void;
 
 declare class MppChargeClient {
     private readonly keypair;
     private readonly network;
     private readonly retryPolicy?;
     constructor(keypair: Keypair, network: 'testnet' | 'mainnet', retryPolicy?: RetryPolicy | undefined);
-    pay(url: string, manifest: RouteDockManifest): Promise<PaymentResult>;
+    pay(url: string, manifest: RouteDockManifest, request?: PaymentRequest): Promise<PaymentResult>;
 }
 
 interface OnChainProviderInfo {
@@ -139,4 +119,4 @@ declare class ProviderRegistry {
     fetchProviderManifest(record: ProviderRecord): Promise<RouteDockManifest>;
 }
 
-export { FileSpendStore as F, MppChargeClient as M, type OnChainProviderInfo as O, type ProviderRecord as P, X402Client as X, OnChainRegistry as a, ProviderRegistry as b, type ProviderRegistryConfig as c, usdcToUnits as u };
+export { MppChargeClient as M, type OnChainProviderInfo as O, type ProviderRecord as P, OnChainRegistry as a, ProviderRegistry as b, type ProviderRegistryConfig as c, assertManifestValid as d, usdcToUnits as u };