@routedock/routedock 0.1.1 → 0.2.0

package/dist/RouteDockClient-BbkqjhMG.d.ts

@@ -0,0 +1,455 @@
+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 { ClientStellarSigner } from '@x402/stellar';
+import { SignAuthEntry } from '@stellar/stellar-sdk/contract';
+import { usdcToStroops } from '@routedock/nulth-sdk';
+
+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. */
+    maxDelayMs?: number;
+    /** Called before each retry with the attempt number, error, and upcoming delay. */
+    /**
+     * Observability hook fired before each retry. Awaited, so a returned promise
+     * is honoured; throwing or rejecting is caught and logged rather than
+     * aborting the retry loop.
+     */
+    onRetry?: (attempt: number, error: Error, nextDelayMs: number) => void | Promise<void>;
+}
+declare const DEFAULT_RETRY_POLICY: Required<Omit<RetryPolicy, 'onRetry'>>;
+/**
+ * Full jitter exponential backoff delay.
+ * Delay range: 0..min(maxDelayMs, baseDelayMs * 2 ** attempt).
+ */
+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.
+ */
+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 that all keys in `latency_hints` must be a subset of declared `regions`.
+ */
+declare function assertManifestValid(manifest: RouteDockManifest, baseUrl?: string): void;
+/**
+ * Override the manifest cache's max size (default 512). Affects the shared,
+ * process-wide cache used by all RouteDockClient instances.
+ */
+declare function configureManifestCache(maxSize: number): void;
+/**
+ * Evict a provider's cached manifest immediately, forcing the next
+ * `fetchManifest(baseUrl)` to re-fetch and re-validate it. Use when a
+ * provider signals that their manifest changed (e.g. after a config update
+ * or a failed payment due to a mode change) so the next request does not
+ * keep routing on a stale cached copy for the remainder of the TTL.
+ *
+ * The cache is keyed by base URL as passed to `fetchManifest` — callers that
+ * pass a full URL (e.g. `RouteDockClient.invalidateManifest`) must normalize
+ * 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;
+    session?: boolean;
+    /**
+     * Preferred streaming transport for sustained sessions. When 'websocket',
+     * the mpp-session-ws variant is preferred when the provider advertises it;
+     * when 'sse' (or omitted), the classic mpp-session mode is preferred.
+     * Either transport falls back to the other session variant when the
+     * preferred one is not advertised.
+     */
+    transport?: 'sse' | 'websocket';
+    /** Prefer the lowest-cost supported per-request mode when set to 'cost'. */
+    optimize?: 'cost';
+    /** Optional maximum acceptable per-request amount for cost-based selection. */
+    budget_per_request?: string;
+    /**
+     * Override mode selection and use this specific mode.
+     * Throws RouteDockNoSupportedModeError if the provider does not support it.
+     */
+    forceMode?: PaymentMode;
+    /** Structured logger for mode selection events. Defaults to no-op. */
+    logger?: RouteDockLogger;
+}
+/**
+ * Fetch, validate, and cache a RouteDock manifest from `baseUrl`.
+ *
+ * `expectedPayee`, when provided, is the out-of-band trust anchor for the
+ * manifest (e.g. the account this provider registered on-chain): the fetched
+ * manifest's `payee` must equal it or `RouteDockSignatureError` is thrown.
+ * 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.
+ */
+declare function fetchManifest(baseUrl: string, retryPolicy?: RetryPolicy, manifestTimeoutMs?: number, expectedPayee?: string): Promise<RouteDockManifest>;
+/**
+ * Deterministic mode selection per Section 6.3 of ROUTEDOCK_MASTER.md.
+ *
+ * Active modes are always considered before modes listed in `deprecated_modes`.
+ * Deprecated modes remain usable as a compatibility fallback and produce a
+ * logger warning when selected. An explicit forceMode remains authoritative,
+ * but also warns when the forced mode is deprecated.
+ */
+declare function selectMode(manifest: RouteDockManifest, options?: ModeSelectOptions): PaymentMode;
+/**
+ * Rank a list of provider manifests by estimated p50 round-trip latency for a given target region.
+ * Manifests declaring latency_hints for the target region are sorted ascending by latency (lowest first).
+ * Manifests that list the region in `regions` without an explicit latency hint come next.
+ * Manifests not advertising the target region come last.
+ */
+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;
+}
+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;
+}
+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'>;
+}
+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;
+        };
+        'mpp-charge'?: {
+            amount: 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;
+    prover?: 'mock';
+    witnessSecret: string;
+    allowedPayees: readonly string[];
+    dailyCapUsdc: string;
+    expiryLedger?: number;
+    verifierContract?: string;
+}
+declare function assertNulthVaultManifest(manifest: RouteDockManifest, nulthAccount: string): void;
+declare function fetchLedgerSequence(network: 'testnet' | 'mainnet'): Promise<number>;
+declare function prepareNulthSigner(vault: NulthVaultConfig, manifest: RouteDockManifest, mode: PaymentMode, network: 'testnet' | 'mainnet', ledgerSequenceOverride?: number): Promise<{
+    signer: ClientStellarSigner;
+    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;
+}
+/**
+ * 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") */
+    daily: string;
+    asset: 'USDC';
+    /**
+     * Optional per-endpoint daily spend caps, keyed by endpoint origin URL
+     * (e.g. "https://api.openai.com"). Checked before the global `daily` cap.
+     * An endpoint not listed here is only subject to the global cap.
+     * Both limits are enforced independently — hitting an endpoint cap does
+     * not prevent spend on other endpoints, but all spend still counts toward
+     * the global cap.
+     *
+     * Keys are normalized to `new URL(key).origin` when the client is
+     * constructed (lowercased host, no trailing slash, no default port), so
+     * "https://API.example.com/", "https://api.example.com" and
+     * "https://api.example.com:443" are all equivalent. A key that isn't a
+     * valid URL, that includes a path/query/hash, or that normalizes to the
+     * same origin as another key throws at construction time.
+     */
+    endpointCaps?: Record<string, string>;
+}
+type VaultConfig = NulthVaultConfig;
+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) */
+    spendCap?: SpendCap;
+    /**
+     * Ed25519 secret key (S...) for signing channel commitments. Required for mpp-session.
+     *
+     * WARNING: Do not log or serialize the config object — it contains this secret in plaintext.
+     * The RouteDockClient stores it outside the instance to prevent leakage via JSON.stringify
+     * or console.log, but the raw config object is not protected.
+     */
+    commitmentSecret?: string | undefined;
+    /** Retry policy for transient failures (network, facilitator 5xx). */
+    retryPolicy?: RetryPolicy;
+    /**
+     * 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).
+     * Inject a persistent implementation for production safety.
+     */
+    spendStore?: SpendStore;
+    /** Structured logger for SDK events. Defaults to no-op (silent). */
+    logger?: RouteDockLogger;
+    /**
+     * Timeout in milliseconds for manifest fetches. A provider that accepts the TCP
+     * connection but never sends a response body will be aborted after this delay.
+     * Default: 5000 ms.
+     */
+    manifestTimeoutMs?: number;
+    /**
+     * Out-of-band trust anchor for manifests: the Stellar payee (G...) the client
+     * expects the provider to be (e.g. the account registered in the on-chain
+     * provider registry, or a pinned/allowlisted key). When set, every fetched
+     * manifest's `payee` must equal this value or payment is refused with
+     * `RouteDockSignatureError`. Without it, a self-signed manifest proves nothing
+     * about who served it, so set this whenever you obtained a provider address
+     * from a registry.
+     */
+    expectedPayee?: string;
+    /**
+     * Vault custody mode. When `nulth`, payments use a Nulth account as payer
+     * with off-chain ZK proofs attached as auth signatures.
+     */
+    vault?: VaultConfig;
+}
+/**
+ * @deprecated Use {@link usdcToStroops} — the same validated bigint converter,
+ * shared across the SDK and nulth-sdk. Kept as a thin alias so existing spend
+ * cap code keeps working during migration.
+ */
+declare const usdcToMicros: typeof usdcToStroops;
+declare class RouteDockClient {
+    /** Per-(account,asset) trustline existence cache keyed by `${network}:${pubkey}:${asset}` */
+    private static _trustlineCache;
+    private readonly keypair;
+    private readonly network;
+    private readonly spendCap;
+    private readonly retryPolicy;
+    private readonly logger;
+    private readonly manifestTimeoutMs;
+    private readonly expectedPayee;
+    private readonly vault;
+    /**
+     * Durable backing store for the local daily spend accumulator (keyed by
+     * YYYY-MM-DD). Totals are persisted as decimal strings of microUSDC
+     * (1 USDC = 10^7) so stores stay JSON-safe with no precision loss.
+     */
+    private readonly spendStore;
+    private x402;
+    private readonly charge;
+    private readonly session;
+    /**
+     * Promise-chain mutex for serializing read-modify-write on the spend
+     * accumulator. Each pay() call awaits the previous one, preventing
+     * concurrent read-modify-write races that could overrun the cap.
+     */
+    private _spendMutex;
+    /**
+     * Pending spend reservations keyed by reserveId. Used by _rollbackSpend
+     * to revert the accumulator when a payment fails after reservation.
+     */
+    private _pendingReserves;
+    constructor(config: RouteDockClientConfig);
+    /** Fetch manifest and select mode — shared by pay() and estimateCost(). */
+    private _resolveManifest;
+    /**
+     * Serialize async work through the per-instance spend mutex so concurrent
+     * pay() calls cannot interleave read-modify-write on the accumulator.
+     */
+    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.
+     */
+    preflight(manifest: RouteDockManifest): Promise<PreflightResult>;
+    /**
+     * Verify via Horizon that the payer account has a trustline for the
+     * payment asset declared in the manifest. Throws RouteDockTrustlineError
+     * with an exact Stellar CLI change-trust remediation command when the
+     * trustline is missing. Results are cached per (account, asset) so the
+     * per-payment overhead is one RPC call amortized to zero after the first.
+     */
+    private _checkTrustline;
+    /**
+     * 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.
+     */
+    pay(url: string, options?: ModeSelectOptions): Promise<PaymentResult>;
+    /** Nulth ZK vault path — proof built off-chain, attached as auth signature */
+    private _payWithNulthVault;
+    /**
+     * Resolve manifest and compute the expected charge WITHOUT submitting any
+     * transaction. Safe to call before committing — for approval gates and
+     * budget-aware routing.
+     */
+    estimateCost(url: string, options?: ModeSelectOptions): Promise<EstimateCostResult>;
+    /**
+     * Open a sustained MPP session at `url`. Verifies mpp-session is supported
+     * before opening a channel. Returns a SessionHandle for streaming + closing.
+     *
+     * By default the session auto-closes after a wall-clock timeout (1h) so an
+     * orphaned channel cannot keep collateral locked on-chain — override or
+     * disable via `options.maxDurationMs`.
+     */
+    openSession(url: string, options?: SessionOptions): Promise<SessionHandle>;
+    /**
+     * Record spend for an MPP session voucher. Called before each voucher
+     * fetch in stream(). Enforces the same local daily and per-endpoint caps
+     * as discrete pay() calls. Returns a commit function to clean up the
+     * reservation after the voucher fetch succeeds.
+     */
+    private _recordSessionSpend;
+    /**
+     * Remove the commitment secret from memory and make it eligible for GC.
+     * Call when this client instance is no longer needed — particularly in
+     * long-lived processes or Worker threads.
+     */
+    dispose(): void;
+    /**
+     * Evict the cached manifest for `url` immediately, so the next pay() /
+     * estimateCost() / openSession() call re-fetches it instead of routing on
+     * the stale cached copy. Use when a provider signals their manifest
+     * changed (e.g. after a config update) and the change must take effect
+     * before the cache TTL expires.
+     */
+    invalidateManifest(url: string): void;
+    /**
+     * Reserve spend against local daily caps BEFORE dispatching payment.
+     * Returns a reserveId that must be passed to _commitSpend() on success
+     * or _rollbackSpend() on failure.
+     *
+     * The entire read-check-write is serialized through the per-instance
+     * mutex (_withSpendMutex) so concurrent pay() calls cannot interleave
+     * and overrun the cap.
+     *
+     * Enforcement order:
+     *   1. Per-endpoint cap (if `endpointCaps[endpointKey]` is set) — checked first.
+     *   2. Global daily cap — checked second.
+     *
+     * Both limits are independent: a payment is only reserved after **both** pass.
+     * All spend (regardless of endpoint) counts toward the global accumulator.
+     */
+    private _checkAndReserveSpend;
+    /**
+     * Commit a previously reserved spend after payment succeeds. For discrete
+     * pay() calls this is a no-op (the spend was already recorded by reserve).
+     * Reserved for future use if the committed amount differs from the reserved.
+     */
+    private _commitSpend;
+    /**
+     * Rollback a previously reserved spend when payment fails. Reverts the
+     * tentative accumulator write done by _checkAndReserveSpend.
+     */
+    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 };

package/dist/SessionReconciler-Dscw43F3.d.ts

@@ -0,0 +1,125 @@
+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 { Keypair } from '@stellar/stellar-sdk';
+
+/**
+ * Settlement idempotency backed by Postgres via Supabase.
+ *
+ * The in-memory default {@link InMemorySeenTxStore} is per-handler and
+ * per-process. On serverless/edge runtimes (Cloudflare Workers, Deno Deploy,
+ * Lambda@Edge) each request may land in a fresh isolate with an empty cache.
+ * An agent retrying after a post-settlement timeout would miss the cache and
+ * settle a second time, charging twice on-chain.
+ *
+ * Postgres gives the read-your-writes consistency this needs; Workers KV
+ * would not, since a retry can outrun propagation and reintroduce the double
+ * settle.
+ *
+ * Requires the `settlements` table from migration `003_settlement_idempotency`:
+ *
+ * ```sql
+ * CREATE TABLE settlements (
+ *   key        TEXT PRIMARY KEY,
+ *   tx_hash    TEXT,
+ *   headers    JSONB,
+ *   created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+ * );
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { SupabaseSeenTxStore } from '@routedock/routedock/store'
+ * import { createClient } from '@supabase/supabase-js'
+ *
+ * const supabase = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_KEY!)
+ * const seenTxStore = new SupabaseSeenTxStore(supabase)
+ *
+ * routedockHono({ ..., seenTxStore })
+ * ```
+ */
+declare class SupabaseSeenTxStore implements SeenTxStore {
+    private readonly supabase;
+    constructor(supabase: SupabaseClient);
+    get(key: string): Promise<SettlementRecord | undefined>;
+    set(key: string, record: SettlementRecord): Promise<void>;
+}
+
+interface RegisterProviderOptions {
+    supabase: SupabaseClient;
+    manifest: RouteDockManifest & {
+        signature?: string;
+        signature_version?: string;
+    };
+    baseUrl: string;
+    /**
+     * Whether to flag the provider record as verified in Supabase.
+     * Defaults to true (since signature is verified before writing).
+     */
+    verified?: boolean;
+}
+/**
+ * Register a provider in the Supabase `providers` table.
+ *
+ * Verifies the manifest's Ed25519 signature before upserting into the
+ * database keyed on `base_url`.
+ *
+ * Throws `RouteDockSignatureError` if the manifest is unsigned or invalid,
+ * and `Error` if the database upsert fails.
+ */
+declare function registerProvider(optionsOrSupabase: RegisterProviderOptions | SupabaseClient, manifestArg?: RouteDockManifest & {
+    signature?: string;
+}, baseUrlArg?: string, verifiedArg?: boolean): Promise<void>;
+
+/**
+ * Session Reconciler — Recovery mechanism for orphaned MPP sessions
+ *
+ * Scans Supabase for sessions marked as "closing" (client initiated close but
+ * provider crashed before broadcasting settlement). Recovers abandoned funds by
+ * broadcasting the channel close transaction with the latest signed commitment.
+ *
+ * Idempotent: Safe to run multiple times on the same session (settlement_tx_hash
+ * acts as deduplication key).
+ */
+
+type Network = 'testnet' | 'mainnet';
+type ChannelCloseFn = (args: {
+    channel: string;
+    amount: bigint;
+    signature: Buffer;
+    feePayer: {
+        envelopeSigner: Keypair;
+    };
+    network: 'stellar:testnet' | 'stellar:pubnet';
+}) => Promise<string>;
+interface SessionReconcilerOptions {
+    supabase: SupabaseClient;
+    network: Network;
+    payeeSecretKey: string;
+    onRecovered?: (channelId: string, txHash: string, totalPaid: string) => Promise<void>;
+    /** Injectable for testing. Defaults to @stellar/mpp/channel/server close() */
+    channelClose?: ChannelCloseFn;
+}
+interface ReconciliationStats {
+    orphanedCount: number;
+    recoveredCount: number;
+    skippedCount: number;
+    failedCount: number;
+    errors: Array<{
+        channelId: string;
+        reason: string;
+    }>;
+}
+declare function decimalToStroops(amountStr: string): bigint;
+/**
+ * Scan for abandoned sessions and attempt recovery.
+ * Idempotent: sessions with settlement_tx_hash are skipped (already recovered).
+ */
+declare function reconcileAbandonedSessions(opts: SessionReconcilerOptions): Promise<ReconciliationStats>;
+/**
+ * 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>;
+
+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 };