run402-mcp/sdk/dist/node/lightning-paid-fetch.d.ts

MCP server for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.

import { type PayExecutor } from "../namespaces/pay.js";
import { type LightningStack } from "./_paid-stack.js";
import { type X402LnbtcPaid } from "./lightning-x402-lnbtc.js";
/** The x402 network ids of Bitcoin mainnet and testnet3 (`lnbtc:` + the genesis hash prefix). */
export declare const LNBTC_MAINNET = "lnbtc:000000000019d6689c085ae165831e93";
export declare const LNBTC_TESTNET = "lnbtc:000000000933ea01ad0ee984209779ba";
/** The `lnbtc` network id for a node's reported network name, or null when the scheme defines none. */
export declare function lnbtcNetworkForNodeNetwork(name: string | null | undefined): string | null;
type FetchFn = typeof globalThis.fetch;
export declare const RUN402_MPP_LIGHTNING_PROFILE = "run402-mpp-lightning-charge-draft00-safety-v1";
/** A single Run402 charge above this is refused before paying (the spec's conservative USD ceiling in sats). */
export declare const LIGHTNING_MAX_DEBIT_SATS = 250000;
/** Bounded: the gateway credits a charge it cannot fulfil after three recovery cycles, well inside this. */
export declare const POST_SETTLEMENT_RETRY_LIMIT = 6;
export interface PostSettlementRetry {
    code: string;
    delayMs: number;
}
/**
 * The paid retry's answer, when it is one of the gateway's retryable
 * post-settlement states from the origin that was asked: the code and how
 * long to wait before repeating the identical request. Null for everything
 * else, including a terminal 409 and any answer from another origin.
 */
export declare function readPostSettlementRetry(response: Response, url: string): Promise<PostSettlementRetry | null>;
export interface LightningWalletLike {
    getBudgetSats(): Promise<{
        usedSats: number;
        totalSats: number | null;
    } | null>;
    getBalanceSats(): Promise<number>;
    payInvoice(bolt11: string): Promise<{
        preimage: string;
    }>;
    lookupInvoice(paymentHash: string): Promise<{
        state: string | null;
        preimage: string | null;
    } | null>;
    /** The node's network name (`mainnet`, `testnet`, …); used when the wallet's network is probed. */
    getInfo?(): Promise<{
        network: string | null;
        pubkey: string | null;
        methods: string[];
    }>;
}
/** Per-call limits a `pay.fetch` call hands the buyer; read through `perCall`. */
export interface LightningCallOptions {
    /** Refuse a Lightning payment whose invoice plus routing headroom exceeds this many sats. */
    maxSats?: number;
    /** A merchant receipt was demanded; no `lnbtc` entry carries one, so the buyer refuses before paying. */
    requireReceipt?: boolean;
}
export interface LightningFetchOptions {
    pairingUri: string;
    /** The x402 buyer to use when the seller offers no Lightning challenge. */
    fallback: () => Promise<FetchFn | null>;
    baseFetch?: FetchFn;
    wallet?: LightningWalletLike;
    stack?: () => Promise<LightningStack>;
    /**
     * The wallet's `lnbtc` network id: the platform Hub sub-wallet is mainnet
     * (the default); `"probe"` asks the node once (`get_info`) and remembers
     * the answer, for a bring-your-own pairing.
     */
    walletNetwork?: string | "probe";
    /** The per-call limits of the `pay.fetch` call in flight, when any. */
    perCall?: () => LightningCallOptions | undefined;
    /** Called with the payment hash of each paid challenge (never the preimage), and what was paid. */
    onPaid?: (paymentHash: string, paid?: X402LnbtcPaid) => void;
    /** The wait between post-settlement retries; tests pass an instant one. */
    sleep?: (ms: number) => Promise<void>;
    /** Unix seconds for x402 Lightning invoice checks; tests pin it. */
    clock?: () => number;
}
export declare class LightningPaymentError extends Error {
    readonly code: string;
    readonly details: Record<string, unknown>;
    constructor(code: string, message: string, details?: Record<string, unknown>);
}
interface LightningChallenge {
    header: string;
    invoice: string;
    paymentHash: string;
    amountSats: number;
    expires: string | null;
}
/** The `WWW-Authenticate: Payment …` challenge for lightning/charge, or null. */
export declare function readLightningChallenge(response: Response, stack: LightningStack): LightningChallenge | null;
/**
 * Only a POST to a charged surface gets the Lightning negotiation headers
 * and a default Idempotency-Key. Every other request is left byte-for-byte
 * alone: an Idempotency-Key on an ordinary write (a room message, a project
 * provision) would turn a deliberate repeat into a replay.
 */
export declare function isLightningChargedRequest(input: RequestInfo | URL, init: RequestInit | undefined): boolean;
export declare function createLightningFetch(options: LightningFetchOptions): FetchFn;
/**
 * `pay.fetch` on the Lightning rail: the buyer above, run under a per-call
 * context that carries the call's caps in and the payment it made out, so the
 * result reports the `lnbtc` network and the payment hash as its
 * transaction. A request that needed no payment, or that the x402 fallback
 * paid, is reported as the fallback reports it.
 */
export declare function createLightningPayExecutor(options: Omit<LightningFetchOptions, "perCall" | "onPaid"> & {
    /** The x402 executor that reports a USDC payment made by the fallback, when there is one. */
    fallbackPay?: PayExecutor | null;
}): PayExecutor;
export {};
//# sourceMappingURL=lightning-paid-fetch.d.ts.map