@routedock/routedock 0.1.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RouteDock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -6,8 +6,6 @@ Unified payment execution layer for autonomous agents on Stellar. One SDK for x4
 
 ```bash
 npm install @routedock/sdk
-# or
-pnpm add @routedock/sdk
 ```
 
 ## Agent Usage
@@ -19,17 +17,17 @@ import { Keypair } from '@stellar/stellar-sdk'
 const client = new RouteDockClient({
   wallet: Keypair.fromSecret(process.env.AGENT_SECRET),
   network: 'testnet',
-  spendCap: { daily: '1.00', asset: 'USDC' }, // optional local guard
+  spendCap: { daily: '1.00', asset: 'USDC' },
 })
 
 // Single call — SDK reads manifest, picks mode automatically
-const result = await client.pay('https://provider.railway.app/price')
+const result = await client.pay('https://provider.example.com/price')
 // result.data   — response body
 // result.txHash — settlement hash (or null for session vouchers)
 // result.mode   — 'x402' | 'mpp-charge' | 'mpp-session'
 
 // Sustained streaming access
-const session = await client.openSession('https://provider.railway.app/stream/orderbook')
+const session = await client.openSession('https://provider.example.com/stream/orderbook')
 for await (const update of session.stream()) {
   console.log(update)
   if (done) break
@@ -37,51 +35,315 @@ for await (const update of session.stream()) {
 await session.close() // triggers on-chain settlement
 ```
 
+### Durable spend cap
+
+The `spendCap` is enforced via a pluggable `SpendStore` (`read()` / `write()`).
+By default the client uses an in-memory store that resets on every process
+restart — and logs a startup warning — so the cap is **not** durable. For
+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'
+
+const redisSpendStore: SpendStore = {
+  async read(): Promise<DailySpend | null> {
+    const raw = await redis.get('routedock:dailySpend')
+    return raw ? (JSON.parse(raw) as DailySpend) : null
+  },
+  async write(state: DailySpend): Promise<void> {
+    await redis.set('routedock:dailySpend', JSON.stringify(state))
+  },
+}
+
+const client = new RouteDockClient({
+  wallet: Keypair.fromSecret(process.env.AGENT_SECRET),
+  network: 'mainnet',
+  spendCap: { daily: '1.00', asset: 'USDC' },
+  spendStore: redisSpendStore,
+})
+```
+
 ## Provider Usage
 
 ```ts
 import express from 'express'
-import { routedock, SupabaseSessionStore } from '@routedock/sdk/provider'
-import { createClient } from '@supabase/supabase-js'
+import { routedock } from '@routedock/sdk/provider'
 
 const app = express()
 
-// Price endpoint — x402 + MPP charge
 app.use('/price', routedock({
   modes: ['x402', 'mpp-charge'],
   pricing: { x402: '0.001', 'mpp-charge': '0.0008' },
   asset: 'USDC',
+  assetContract: process.env.USDC_ASSET_CONTRACT,
   payee: process.env.STELLAR_PAYEE_ADDRESS,
-  network: process.env.STELLAR_NETWORK as 'testnet' | 'mainnet',
-  facilitatorApiKey: process.env.OPENZEPPELIN_API_KEY,
+  network: 'testnet',
+  payeeSecretKey: process.env.STELLAR_PAYEE_SECRET,
+  manifest,
+  onSettled: async (txHash, amount, mode) => {
+    console.log(`settled: ${mode} ${amount} USDC — ${txHash}`)
+  },
 }))
+```
+
+## Session Lifecycle Hooks
+
+For `mpp-session` mode, the middleware exposes three hooks that fire at each stage of the payment channel lifecycle:
 
-// Stream endpoint — MPP session only
-const store = new SupabaseSessionStore(createClient(process.env.SUPABASE_URL, process.env.SUPABASE_SERVICE_KEY))
-app.use('/stream/orderbook', routedock({
+```ts
+app.use('/stream', routedock({
   modes: ['mpp-session'],
-  pricing: { 'mpp-session': { rate: '0.0001', channelContract: process.env.CHANNEL_CONTRACT_ID } },
+  pricing: { 'mpp-session': { rate: '0.0001', channelContract: CHANNEL_CONTRACT } },
   asset: 'USDC',
-  payee: process.env.STELLAR_PAYEE_ADDRESS,
-  network: process.env.STELLAR_NETWORK as 'testnet' | 'mainnet',
-  store,
+  assetContract: USDC_ASSET_CONTRACT,
+  payee: PAYEE_ADDRESS,
+  network: 'testnet',
+  payeeSecretKey: PAYEE_SECRET,
+  manifest,
+  commitmentPublicKey: COMMITMENT_PUBLIC_KEY,
+
+  // Fires once when the first voucher is verified for a new session
+  onSessionOpen: async (channelId) => {
+    await db.from('sessions').insert({
+      channel_id: channelId,
+      status: 'open',
+      voucher_count: 0,
+    })
+  },
+
+  // Fires after each verified ed25519 commitment (off-chain, no tx fee)
+  onVoucher: async (voucherIndex, cumulativeAmount) => {
+    await db.from('sessions').update({
+      voucher_count: voucherIndex,
+      cumulative_amount: parseFloat(cumulativeAmount),
+    }).eq('channel_id', channelId)
+  },
+
+  // Fires after the on-chain channel close settles the cumulative amount
+  onSettled: async (txHash, totalPaid, mode) => {
+    await db.from('sessions').update({
+      status: 'closed',
+      settlement_tx_hash: txHash,
+    }).eq('channel_id', channelId)
+  },
 }))
 ```
 
+| Hook | When it fires | On-chain? |
+|---|---|---|
+| `onSessionOpen(channelId)` | First verified voucher in a new session | No |
+| `onVoucher(index, cumulativeAmount)` | Each verified ed25519 commitment | No |
+| `onSettled(txHash, amount, mode)` | Channel close transaction confirmed | Yes |
+
+## 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.
+>
+> Next.js inlines every `NEXT_PUBLIC_*` variable into the client bundle at build time, so never put a Stellar secret in one.
+>
+> Only use these hooks with a dedicated, low-balance testnet key, and spendCap does not protect a key that has leaked.
+>
+> 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`:
+
+```tsx
+import { RouteDockProvider, useRouteDockClient } from '@routedock/sdk/react'
+import { createClient } from '@supabase/supabase-js'
+
+// Dedicated throwaway testnet key. Never a funded or mainnet key.
+const THROWAWAY_TESTNET_SECRET = 'S...'
+
+function App({ children }: { children: React.ReactNode }) {
+  const client = useRouteDockClient({
+    wallet: THROWAWAY_TESTNET_SECRET,
+    network: 'testnet',
+    spendCap: { daily: '1.00', asset: 'USDC' },
+  })
+  const supabase = createClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+  )
+  return (
+    <RouteDockProvider client={client} supabase={supabase}>
+      {children}
+    </RouteDockProvider>
+  )
+}
+```
+
+### Paying from the server
+
+```ts
+// app/api/price/route.ts (runs on the server only)
+import { RouteDockClient } from '@routedock/sdk/client'
+
+const client = new RouteDockClient({
+  wallet: process.env.AGENT_SECRET!,
+  network: 'testnet',
+  spendCap: { daily: '1.00', asset: 'USDC' },
+})
+
+export async function POST() {
+  const result = await client.pay('https://provider.example.com/price')
+  return Response.json({ mode: result.mode, txHash: result.txHash, data: result.data })
+}
+```
+
+### `usePay(url, options?)`
+
+```tsx
+import { usePay } from '@routedock/sdk/react'
+
+function PriceButton() {
+  const { pay, result, loading, error } = usePay('https://provider.example.com/price')
+  if (error) return <span>Error: {error.message}</span>
+  return (
+    <button onClick={pay} disabled={loading}>
+      {loading ? 'Paying…' : result ? `Paid: ${result.txHash}` : 'Pay 0.001 USDC'}
+    </button>
+  )
+}
+```
+
+### `useSession(url)`
+
+```tsx
+import { useEffect } from 'react'
+import { useSession } from '@routedock/sdk/react'
+
+function StreamingFeed() {
+  const { open, close, status, vouchers, cumulative } = useSession(
+    'https://provider.example.com/stream/orderbook',
+  )
+  useEffect(() => { void open() }, [])
+  return (
+    <div>
+      <p>Status: {status} — vouchers: {vouchers} — paid: {cumulative} USDC</p>
+      <button onClick={close} disabled={status !== 'open'}>Close & settle</button>
+    </div>
+  )
+}
+```
+
+The hook automatically fires `session.close()` in the background on unmount when status is `open` (best-effort settlement).
+
+### `useTxLog(filter?)`
+
+```tsx
+import { useTxLog } from '@routedock/sdk/react'
+
+function ActivityFeed({ channelId }: { channelId: string }) {
+  const txLog = useTxLog({ channelId, limit: 25 })
+  return (
+    <ul>
+      {txLog.map((row) => (
+        <li key={row.id}>{row.mode} — {row.amount} USDC — {row.tx_hash}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+| Hook | Returns | Requires from `RouteDockProvider` |
+|---|---|---|
+| `useRouteDockClient(config)` | Memoized `RouteDockClient` | — (creator hook) |
+| `usePay(url, options?)` | `{ pay, result, loading, error }` | `client` |
+| `useSession(url)` | `{ session, status, vouchers, cumulative, error, open, close }` | `client` (with `commitmentSecret`) |
+| `useTxLog(filter?)` | `TxLogRow[]` (newest first) | `supabase` |
+
+React is a peer dependency — install `react@^18` (or `^19`) in your app.
+
+---
+
+## Error Handling
+
+All SDK failures extend `RouteDockError` with a stable `code`, `retryable` flag, and optional `cause`. Transient failures (network timeouts, facilitator 5xx, Horizon RPC errors) are retried automatically with exponential backoff unless you disable retries.
+
+```ts
+import {
+  RouteDockClient,
+  RouteDockError,
+  RouteDockFacilitatorError,
+  RouteDockManifestError,
+  RouteDockPolicyRejectError,
+} from '@routedock/sdk/client'
+
+const client = new RouteDockClient({
+  wallet: process.env.AGENT_SECRET!,
+  network: 'testnet',
+  retryPolicy: { maxAttempts: 4, baseDelayMs: 250 },
+})
+
+try {
+  const result = await client.pay('https://provider.example.com/price')
+  console.log(result.mode, result.txHash)
+} catch (err) {
+  if (err instanceof RouteDockPolicyRejectError) {
+    console.error('Spend cap exceeded:', err.reason)
+  } else if (err instanceof RouteDockFacilitatorError) {
+    console.error(`Facilitator HTTP ${err.status} (retryable=${err.retryable})`)
+  } else if (err instanceof RouteDockManifestError) {
+    console.error('Manifest or config problem:', err.message)
+  } else if (err instanceof RouteDockError) {
+    console.error(`[${err.code}] ${err.message} (retryable=${err.retryable})`)
+  } else {
+    throw err
+  }
+}
+```
+
+| Error | `retryable` | Typical cause |
+|---|---|---|
+| `RouteDockManifestError` | no | Invalid manifest, missing pricing fields |
+| `RouteDockNoSupportedModeError` | no | Provider has no compatible payment mode |
+| `RouteDockFacilitatorError` | yes | Facilitator/provider 429 or 5xx |
+| `RouteDockNetworkError` | yes | Timeouts, connection failures |
+| `RouteDockSignatureError` | no | Signing or commitment failure |
+| `RouteDockVoucherMonotonicityError` | no | Non-increasing voucher amount |
+| `RouteDockPolicyRejectError` | no | Local spend cap exceeded |
+| `RouteDockChannelStateError` | no | Channel simulate/close invariant violation |
+
 ## Mode Selection Logic
 
 The `ModeRouter` uses this decision tree (deterministic, no randomness):
 
 1. If `{ sustained: true }` passed AND manifest supports `mpp-session` → session
 2. Else if manifest supports `mpp-charge` AND network is Stellar → MPP charge (lower fees)
-3. Else if manifest supports `x402` → x402 with OZ facilitator
+3. Else if manifest supports `x402` → x402 with facilitator
 4. Else throw `RouteDockNoSupportedModeError`
 
 Override with `{ forceMode: 'x402' }` to bypass auto-selection.
 
+## Dispute Resolution
+
+For `mpp-session` mode, the session handle exposes three methods to handle server unavailability or crashes:
+
+```ts
+const session = await client.openSession('https://provider.example.com/stream')
+
+// Check the current dispute status (open, in-refund-window, refundable, settled)
+const status = await session.getDisputeStatus()
+
+// If server is unresponsive, request a refund (starts the refund window)
+const refundTxHash = await session.requestRefund()
+
+// Server-side: settle with the latest signed voucher before refund window expires
+const settleTxHash = await session.settleWithLatestVoucher()
+```
+
+| Method | Purpose | Requires | Returns |
+|--------|---------|----------|---------|
+| `getDisputeStatus()` | Query channel state | None | `'open' \| 'in-refund-window' \| 'refundable' \| 'settled'` |
+| `requestRefund()` | Initiate refund process | Signed agent keypair | Transaction hash (string) |
+| `settleWithLatestVoucher()` | Server counter-settle | Latest voucher signature | Transaction hash (string) |
+
+Raises: `RouteDockDisputeError`, `RouteDockChannelStateError`, `RouteDockRefundWindowError`
+
 ## Security
 
-The `one-way-channel` Soroban contract wrapped by `MppSessionClient` is **unaudited** (`stellar-experimental/one-way-channel`). Safe defaults are enforced: 17280 ledger refund window, durable `SupabaseSessionStore` with monotonic invariant. Production use should await a formal audit.
+The `one-way-channel` Soroban contract wrapped by `MppSessionClient` is **unaudited** (`stellar-experimental/one-way-channel`). Safe defaults are enforced: 17280 ledger refund window, monotonic cumulative enforcement at application, database, and contract layers. Production mainnet use should await a formal audit.
 
 ## License
 

package/dist/MppSessionHandler-B4TyD7Xg.d.cts

@@ -0,0 +1,121 @@
+import { RequestHandler } from 'express';
+import { Store } from 'mppx';
+import { R as RouteDockManifest } from './types-DmhmfLzP.cjs';
+
+/**
+ * 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) and checks this store. On a hit it replays the cached
+ * settlement response and skips both the on-chain settle and `onSettled`.
+ *
+ * The default {@link InMemorySeenTxStore} is per-handler and per-process. For
+ * multi-instance deployments, supply a shared implementation backed by Redis,
+ * Supabase, etc.
+ */
+/** 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>;
+}
+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;
+}
+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;
+}
+/**
+ * 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 order;
+    constructor(maxEntriesOrOptions?: number | InMemorySeenTxStoreOptions);
+    private readonly maxEntries;
+    get(key: string): SettlementRecord | undefined;
+    set(key: string, record: SettlementRecord): void;
+}
+/**
+ * Derive a collision-resistant idempotency key from the inbound
+ * payment-bearing headers. 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. 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): 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;
+}
+declare function createMppSessionHandler(opts: MppSessionHandlerOptions): RequestHandler;
+
+export { type ChannelStore as C, InMemorySeenTxStore as I, type MppSessionHandlerOptions as M, type OrphanedSessionInfo as O, type SeenTxStore as S, type VoucherStoreValue as V, type SettlementRecord as a, type InMemorySeenTxStoreOptions as b, type OrphanReason as c, createMppSessionHandler as d, isVoucherStoreValue as i, paymentIdempotencyKey as p };

package/dist/MppSessionHandler-CLB5SzgN.d.ts

@@ -0,0 +1,121 @@
+import { RequestHandler } from 'express';
+import { Store } from 'mppx';
+import { R as RouteDockManifest } from './types-DmhmfLzP.js';
+
+/**
+ * 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) and checks this store. On a hit it replays the cached
+ * settlement response and skips both the on-chain settle and `onSettled`.
+ *
+ * The default {@link InMemorySeenTxStore} is per-handler and per-process. For
+ * multi-instance deployments, supply a shared implementation backed by Redis,
+ * Supabase, etc.
+ */
+/** 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>;
+}
+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;
+}
+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;
+}
+/**
+ * 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 order;
+    constructor(maxEntriesOrOptions?: number | InMemorySeenTxStoreOptions);
+    private readonly maxEntries;
+    get(key: string): SettlementRecord | undefined;
+    set(key: string, record: SettlementRecord): void;
+}
+/**
+ * Derive a collision-resistant idempotency key from the inbound
+ * payment-bearing headers. 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. 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): 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;
+}
+declare function createMppSessionHandler(opts: MppSessionHandlerOptions): RequestHandler;
+
+export { type ChannelStore as C, InMemorySeenTxStore as I, type MppSessionHandlerOptions as M, type OrphanedSessionInfo as O, type SeenTxStore as S, type VoucherStoreValue as V, type SettlementRecord as a, type InMemorySeenTxStoreOptions as b, type OrphanReason as c, createMppSessionHandler as d, isVoucherStoreValue as i, paymentIdempotencyKey as p };