thunder-bridge 1.4.2 → 2.1.1

package/dist/bank-CEIuNhV_.d.cts

@@ -0,0 +1,896 @@
+import { R as Resolved, Q as QrOptions } from './qr-CF-YeXU1.cjs';
+import { A as Amount, T as Ticker, C as Charge, f as MintedPayment, h as PaymentStatus, i as Priced, g as Msat, S as Settlement, P as Payment, Q as Quote, e as Held, H as Handover, j as SocketTicket } from './types-DYZ9EkmJ.cjs';
+
+type Sent = {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    deadline?: AbortSignal;
+    staysOnOrigin?: boolean;
+};
+type Verified = {
+    address: string;
+    family: number;
+};
+/** Carries one request to an address ask() already verified, so nothing resolves the name again */
+type Send = (url: string, sent: Sent, signal: AbortSignal, at: readonly Verified[]) => Promise<Response>;
+
+/** What a shop knows about a sale before any rail exists */
+interface Order {
+    /** The bank matches it on the statement, and Lightning keys idempotency on it */
+    reference: string;
+    /** The price in the smallest unit of `currency`, so 48055 is 480.55 CZK */
+    amountMinor: number;
+    /** ISO 4217. The bank rail moves this, Lightning converts it at `rate` */
+    currency: string;
+}
+/** One way to pay one order, already registered with the gateway */
+interface Leg {
+    /** The watched payment's id, which with `paymentHash` is what `firstSettled`, `payment` and `settled` take */
+    id: string;
+    paymentHash: string;
+    /** Which rail made it, so a shop can label a leg without knowing how it was built */
+    rail: string;
+    /** What the payer reads, a BOLT11 invoice or a Short Payment Descriptor */
+    scan: string;
+    /** The same thing as a QR has to encode it, which is not always `scan` itself */
+    qr: string;
+    expiresAt: number;
+}
+/**
+ * A payment method. Everything that differs between rails is bound once when the
+ * rail is built, so the only thing passed per sale is which sale it is
+ */
+type Rail = (order: Order) => Promise<Leg>;
+/** What every rail takes, whatever it moves */
+interface RailConfig {
+    /** Groups every payment from this rail so `follow` can watch the shop */
+    trigger?: string;
+    /** How many of that trigger's settlements the gateway keeps replayable past the hour */
+    replay?: number;
+    /** Where the gateway posts once the money lands, a public https URL */
+    webhookUrl?: string;
+    /** What `Leg.rail` says, so two rails of one kind can be told apart */
+    name?: string;
+}
+/** A Lightning rail the gateway mints for, bound once and then given one order at a time */
+interface LightningRailConfig extends RailConfig {
+    /** Priority list, the first address that can prove an invoice wins */
+    paidTo: string | string[];
+    /**
+     * What to charge for one order, the order's own price converted at `rate` by
+     * default. Give it a function and the price is whatever you say
+     */
+    amount?: (order: Order) => Amount;
+    /** Where the default conversion gets its rate, the median of four venues by default */
+    rate?: Ticker;
+    /** Makes the mint safe to retry, the order's reference by default */
+    idempotencyKey?: (order: Order) => string | undefined;
+}
+/** The same rail with the invoice resolved here, so the gateway is told neither address nor amount */
+interface BlindLightningRailConfig extends LightningRailConfig {
+    /**
+     * What the watcher needs and the gateway must not read, sealed under `secret`
+     * for the invoice's payment hash before it goes anywhere near the gateway
+     */
+    sealed?: {
+        secret: string;
+        data: (order: Order) => unknown;
+    };
+    /**
+     * Where your own `serve.verify` endpoint is mounted, and its secret. Without
+     * it the gateway is handed the wallet's own URL, which a gateway enforcing its
+     * verify challenge will refuse to poll
+     */
+    relayThrough?: {
+        endpoint: string;
+        secret: string;
+    };
+    /** How the rail reaches wallets, pinned to the address it verified unless you say otherwise */
+    send?: Send;
+}
+/** A bank rail: the account the money lands in, and where its arrival is read back from */
+interface BankRailConfig extends RailConfig {
+    /** Long lived and server side. Every preimage is derived from it, so losing it loses every proof */
+    secret: string;
+    /** The account the money goes to, as an IBAN */
+    iban: string;
+    /** Where `serve.bankVerify` is mounted, a public https URL with no query of its own */
+    verifyUrl: string;
+    /** When this leg stops being payable, in unix seconds */
+    expiresAt: (order: Order) => number;
+    /** Sealed before the gateway sees it, the way the blind Lightning rail does */
+    sealed?: {
+        secret: string;
+        data: (order: Order) => unknown;
+    };
+    /** The Czech variable symbol, taken off the reference's digits by default */
+    variableSymbol?: (order: Order) => string | undefined;
+    /**
+     * Register on a gateway you do not own anyway. The sealed verify URL names
+     * nothing about the order, but its operator still learns every watch you place
+     */
+    allowPublicGateway?: boolean;
+}
+/**
+ * A provable invoice from the first address on the list that will issue one, which
+ * is what a client mints for itself rather than asking a gateway to. Everything the
+ * gateway needs to watch it comes back with everything you need to prove it came
+ * from the address you asked for, so you can hand over the first and keep the second.
+ *
+ * Server side: it resolves hostnames and refuses a private one, which no browser can
+ * do. Throws `NoWalletAvailableError` when no address on the list would serve
+ */
+declare function invoiceFrom(paidTo: string | string[], amount: Amount, send?: Send): Promise<Resolved>;
+/**
+ * One call per sale, whatever the rail moves. Each of these was a free function
+ * taking the gateway as a config field, and reaching them through the gateway is
+ * what deleted that field
+ */
+declare class Rails {
+    private readonly gateway;
+    constructor(gateway: ThunderBridge);
+    /** Lightning, with the gateway minting against a priority list of addresses */
+    lightning(config: LightningRailConfig): Rail;
+    /**
+     * Lightning, with the invoice resolved here so the gateway is told neither the
+     * address nor the amount
+     */
+    blindLightning(config: BlindLightningRailConfig): Rail;
+    /** A bank transfer, proved the way a Lightning payment is */
+    bank(config: BankRailConfig): Rail;
+    /**
+     * One bank transfer without building a rail first, for a shop that asks for
+     * them one at a time rather than beside another payment method
+     */
+    transfer(params: BankTransferParams): Promise<BankTransfer>;
+}
+
+/**
+ * What to ask for: who is paid, how much, and how the QR should look. Every
+ * field beyond `paidTo` and `amount` has a default, so the shortest request
+ * names two
+ */
+interface PaymentRequestInit extends Charge, PaymentRequestOptions {
+}
+/** What `requestPayment` takes beyond the charge itself */
+interface PaymentRequestOptions extends WaitOptions {
+    /** Makes the mint safe to retry, so a reloaded checkout replays one invoice */
+    idempotencyKey?: string;
+    /** Groups this request with every other one carrying the same secret, for `follow` */
+    trigger?: string;
+    /** How many of that trigger's settlements the gateway keeps replayable past the hour */
+    replay?: number;
+    /** Size and colour of `qr`, 256 pixels and black by default */
+    qr?: QrOptions;
+}
+/**
+ * One payment asked for: the invoice to show, the QR to draw it with, and one
+ * way to find out it was paid. Everything on it is already proved against the
+ * recipient's own server, so nothing here is the gateway's word
+ */
+interface PaymentRequest {
+    /** What the gateway calls this payment, which is what `payment` and `settled` take */
+    readonly id: string;
+    readonly bolt11: string;
+    readonly paymentHash: string;
+    readonly lnAddress: string;
+    readonly amountMsat: number;
+    /** When the invoice stops being payable, in unix seconds */
+    readonly expiresAt: number;
+    /** The invoice as an SVG QR, ready to put in an element's `innerHTML` */
+    readonly qr: string;
+    /** The payment as the gateway first reported it, for anything the fields above leave out */
+    readonly payment: MintedPayment;
+    /**
+     * Resolves once the money has arrived, and rejects when the invoice expires
+     * unpaid or the wait is aborted. It follows a WebSocket and reconnects through
+     * a drop, so this is one await rather than a poll.
+     *
+     * `gateway.settled(payment)` is the wider question and ends on an expiry too. This
+     * one is about the payment that was asked for, and one that expired was never paid
+     */
+    paid(options?: WaitOptions): Promise<MintedPayment>;
+    /**
+     * The same wait as a callback, for a page that has something else to do.
+     * Returns a function that stops waiting
+     */
+    onPaid(arrived: (payment: MintedPayment) => void, failed?: (reason: unknown) => void): () => void;
+    /**
+     * Ask the recipient's own server whether it settled, and get the preimage it
+     * released or null. This is the only answer that comes from somewhere other
+     * than the gateway, so it is the one to ask when a payment matters
+     */
+    prove(): Promise<string | null>;
+}
+
+/** The wallet's own LUD-21 URL and the hash its preimage has to match */
+interface Relayed {
+    url: string;
+    hash: string;
+}
+/** The verify endpoint that asks the wallet for the gateway, and how often it may be asked */
+interface LightningVerifyConfig {
+    /** The secret the sealed wallet URL was made with, and nothing else uses it */
+    secret: string;
+    /**
+     * How often you want the gateway to ask, in seconds. It goes out as
+     * `Cache-Control: max-age`, so the pace is yours rather than the operator's.
+     * Five by default, which is what a Lightning checkout wants
+     */
+    pollEverySecs?: number;
+    /** How the relay reaches the wallet, pinned to the address it verified unless you say otherwise */
+    send?: Send;
+}
+/**
+ * The URL to hand the gateway instead of the wallet's own, with the wallet's
+ * sealed inside it. Point it at wherever `lightningVerifyEndpoint` is mounted
+ */
+declare function relayedVerifyUrl(endpoint: string, wallet: Relayed, secret: string): Promise<string>;
+
+/** An LNURL-pay endpoint of your own: whose wallets it stands for, and what it charges */
+interface TriggerConfig {
+    /** Priority list, quoted at payRequest and then pinned for the callback */
+    paidTo: string | string[];
+    /**
+     * What this trigger costs right now, asked once per payRequest. `fiat` makes it
+     * a live rate, and any function of your own makes it a time of day rule.
+     *
+     * Give it a `{ least, most }` range instead and the payer chooses inside it,
+     * which is what a tip jar is. One amount pins the price and the wallet offers
+     * no field to type in
+     */
+    amount: Amount | Range;
+    /**
+     * Signs the callback URL. Without it anyone could call the callback and make
+     * this endpoint mint invoices on wallets of their choosing
+     */
+    secret: string;
+    /** Groups every payment here so `follow` can watch the place, keep it off the QR */
+    watchSecret?: string;
+    /**
+     * How many settlements of this place the gateway keeps replayable past the hour
+     * it would otherwise forget them in, up to the ceiling its operator set. What a
+     * page that opens later still gets to see. Needs `watchSecret`
+     */
+    replay?: number;
+    /** How the endpoint reaches wallets, pinned to the address it verified unless you say otherwise */
+    send?: Send;
+    /** Override when a proxy hides the public URL from the request, no trailing slash */
+    baseUrl?: string;
+    /**
+     * Resolve the address here and hand the gateway only a hash and a URL to poll,
+     * instead of asking it to mint. It then cannot tell who is being paid beyond
+     * the domain in the verify URL, nor how much at all, so the only refusal left
+     * to it is refusing everyone. Costs one more round trip and gives up the
+     * gateway's CORS proxying, which a server does not need anyway.
+     *
+     * A gateway that enforces its verify challenge will not poll a wallet's own
+     * LUD-21 URL, so pass `relayThrough` as well and the poll comes to you
+     */
+    blind?: boolean;
+    /**
+     * Where your own `serve.verify` endpoint is mounted, and the secret it was
+     * given. The wallet's URL is sealed inside the one the gateway is handed, so
+     * the gateway polls you and learns neither the wallet nor its provider
+     */
+    relayThrough?: {
+        endpoint: string;
+        secret: string;
+    };
+    /**
+     * What the watcher needs and the gateway must not have. `data` returns it and
+     * `secret` encrypts it, so there is no way to hand the gateway something it
+     * can read. Needs 32 characters of randomness, not a passphrase, and every
+     * watcher of this trigger holds the same one
+     */
+    sealed?: {
+        secret: string;
+        data: (minted: Minted) => unknown;
+    };
+}
+/** What a blind mint produced, which is what the sealed payload is built from */
+/**
+ * What a payer may choose to send, when the endpoint lets them choose at all.
+ * Both ends are asked once per payRequest, so a fiat range moves with the rate
+ */
+interface Range {
+    least: Amount;
+    most: Amount;
+}
+/** What a blind mint produced, which is what the sealed payload is built from */
+interface Minted {
+    lnAddress: string;
+    amountMsat: number;
+    bolt11: string;
+    paymentHash: string;
+    verifyUrl: string;
+    expiresAt: number;
+}
+/**
+ * A trigger's live stream is opened with a ticket rather than with the watch
+ * secret, so something has to hold the secret and trade it for tickets. That is
+ * what these two endpoints are, and they are the only place the gateway's token
+ * has to be
+ */
+interface WatchTicketConfig {
+    /** The trigger to open, the same secret `serve.lnurlPay` groups its payments under */
+    watchSecret: string;
+    /**
+     * How many of this trigger's settlements the socket replays on connect, so a
+     * page opened late still shows what it missed, up to the gateway's ceiling
+     */
+    replay?: number;
+}
+
+/**
+ * What a wrapping operator may charge over the recipient's own amount. This is a
+ * ceiling the client sets rather than a price the operator names, so it sits
+ * above what any operator lists and refuses only the ones reaching past it
+ */
+interface WrapAllowance {
+    /** As a fraction of the recipient's amount, `0.01` by default */
+    proportion?: number;
+    /** The floor in millisatoshi whatever the fraction works out to, `1000` by default */
+    baseMsat?: number;
+}
+/**
+ * Prove the invoice really is the one the recipient issued for what you asked,
+ * before the payer ever sees it, both fetches go straight to the recipient's own
+ * server and none of them goes back to the gateway
+ *
+ * Throws `GatewayCheatError` when a check fails and `UnverifiedRecipientError`
+ * when the recipient could not be reached to run one
+ */
+declare function proveOrigin(payment: MintedPayment, asked: Priced, askedAt?: number): Promise<void>;
+/**
+ * Prove the money arrived by asking the recipient's own server, not the gateway,
+ * returns the preimage when the recipient says it settled and null when it says
+ * it has not, and runs the full origin proof first because a verify url the
+ * gateway made up would otherwise answer for itself
+ */
+declare function proveSettlement(payment: MintedPayment, asked: Priced): Promise<string | null>;
+/** The least a report has to carry for its own proof to be checkable */
+interface Provable {
+    status: PaymentStatus;
+    preimage: string | null;
+    paymentHash: string;
+    bolt11?: string | null;
+}
+/**
+ * A report `carriesProof` has already accepted, so the preimage is there and the
+ * status is settled. Nothing downstream of the check needs a null guard
+ */
+type Proven<T extends Provable> = T & {
+    status: "paid";
+    preimage: string;
+};
+/**
+ * Whether a report proves what it claims: it says paid, and it carries a preimage
+ * that hashes to the payment hash it itself names. Where an invoice comes with it,
+ * the invoice's own hash has to agree too.
+ *
+ * A payment, a settlement delivered to a webhook and a frame off a trigger all
+ * answer this, because all three carry those fields and no other question about
+ * one matters.
+ *
+ * It asks nobody anything, so it costs no round trip and is not a proof of
+ * arrival. Only `proveSettlement` asks the recipient
+ */
+declare function carriesProof<T extends Provable>(report: T): report is Proven<T>;
+/**
+ * The most an operator may add over the recipient's own amount, in millisatoshi.
+ * The proportion is what routing and the liquidity behind it costs, and the base
+ * is the floor it never drops below, because a fraction of a small payment
+ * rounds to nothing the operator can work for
+ */
+declare function wrapFeeCeiling(amountMsat: number, allowance?: WrapAllowance): Msat;
+/**
+ * Prove a wrapping operator's invoice is the recipient's own payment in
+ * disguise, so paying it can only settle by the operator paying the recipient.
+ *
+ * It compares two invoices and asks nobody anything, so it runs in a browser and
+ * costs no round trip. Prove the recipient's own invoice with `proveOrigin`
+ * first, because this says nothing about where that one came from.
+ *
+ * There is no settlement check here and there does not need to be. Both invoices
+ * carry one payment hash, so the preimage that settles the wrap is the preimage
+ * the recipient released, and `proveSettlement` already reads it from the
+ * recipient's own server.
+ *
+ * Throws `WrapRefusedError` naming which binding failed
+ */
+declare function proveWrapped(wrapped: string, recipient: string, allowance?: WrapAllowance): void;
+
+/** How far the gateway's clock may drift from yours before a webhook is refused */
+type WebhookOptions = {
+    toleranceSecs?: number;
+};
+/**
+ * What checks a delivery: the hex the gateway publishes at `/webhook-key`. There
+ * is no shared secret to register, so a gateway holds nothing of yours. Rotating
+ * its cluster key rotates this too, so a signature that stops verifying is a
+ * reason to read the key again before it is a reason to distrust the gateway
+ */
+type WebhookCredential = {
+    publicKey: string;
+};
+/**
+ * Answer the challenge the gateway sends a verify URL before it will poll it,
+ * which is how a caller shows the endpoint agreed to the traffic rather than
+ * merely being named. Returns null for anything that is not a challenge, so a
+ * verify endpoint hands the request on to its own reading of a payment.
+ *
+ * The nonce is echoed to whoever asked, which grants them nothing, so there is
+ * no signature to check here and no secret to hold
+ */
+declare function answerVerifyChallenge(request: Request): Promise<Response | null>;
+
+/** A Fetch handler, which is what every runtime this targets mounts */
+type Handler = (request: Request) => Promise<Response>;
+/** What to do with what the gateway delivers, and what to believe it with */
+interface WebhookHandlers {
+    /**
+     * A settlement that proves itself: it says paid and its preimage hashes to the
+     * payment hash it names. This is the only callback a shop needs
+     */
+    onSettled?: (settlement: Proven<Settlement>) => void | Promise<void>;
+    /**
+     * A delivery that carries no proof, so an expiry. Left unset, the handler
+     * answers `202` and does nothing, because acting on an unproven claim is the
+     * one thing this refuses to do
+     */
+    onUnproven?: (settlement: Settlement) => void | Promise<void>;
+    /** A whole payment rather than a settlement, which is what an older gateway posts */
+    onPayment?: (payment: Payment) => void | Promise<void>;
+    /**
+     * The key that checks the signature, fetched from the gateway once and kept
+     * when you do not pass one. Pass it to pin the key you already read
+     */
+    credential?: WebhookCredential;
+    /** How far the gateway's clock may drift from yours, five minutes by default */
+    toleranceSecs?: number;
+}
+/**
+ * Everything one gateway lets you mount, in one place so a caller never has to
+ * know which handler needs the gateway and which does not. Most of these took it
+ * as a config field before, and reaching them through the gateway deleted it.
+ *
+ * `verify` and `bankVerify` need nothing from the gateway and are here anyway,
+ * because a reader looking for a handler should find every handler in one list
+ */
+declare class Serve {
+    private readonly gateway;
+    constructor(gateway: ThunderBridge);
+    /**
+     * An LNURL-pay endpoint of your own, standing in front of a priority list of
+     * addresses, so a printed QR points at your domain and never expires
+     */
+    lnurlPay(config: TriggerConfig): Handler;
+    /** Trades the watch secret for a one minute socket ticket, refusing anyone without it */
+    watchTicket(config: WatchTicketConfig): Handler;
+    /**
+     * Mints a socket ticket for anybody who asks, which makes the trigger's whole
+     * stream public, preimages included. Only for a board where that is the point
+     */
+    publicWatchTicket(config: WatchTicketConfig): Handler;
+    /**
+     * A verify endpoint of your own that asks the recipient's wallet for you, so
+     * the gateway polls you and never the wallet
+     */
+    verify(config: LightningVerifyConfig): Handler;
+    /** The verify endpoint a bank rail is polled at, answering off your own statement */
+    bankVerify(config: BankVerifyConfig): Handler;
+    /**
+     * The whole webhook route: it answers the gateway's challenge, checks the
+     * signature against the key the gateway publishes, refuses a settlement that
+     * proves nothing, and calls you for the one that does.
+     *
+     * `export const POST = gateway.serve.webhook({ onSettled: fulfil })` is the
+     * entire integration
+     */
+    webhook(handlers: WebhookHandlers): Handler;
+    /** Verify a delivery and read the settlement out of it, null when it is not believable */
+    readSettlement(request: Request, options?: WebhookOptions): Promise<Settlement | null>;
+    /** Verify a delivery and read the payment out of it, null when it is not believable */
+    readPayment(request: Request, options?: WebhookOptions): Promise<Payment | null>;
+    /** Answer the challenge the gateway sends before it will post to a webhook of yours */
+    answerWebhookChallenge(request: Request, options?: WebhookOptions): Promise<Response | null>;
+    private credential;
+}
+
+/** How this instance talks to one gateway */
+interface ThunderBridgeOptions {
+    /**
+     * Sent as `Authorization: Bearer`, which a gateway started with
+     * `GATEWAY_TOKEN` requires on every call, the socket handshake included. No
+     * browser WebSocket can carry a header, so setting this also puts every socket
+     * through a ticket
+     */
+    token?: string;
+    /**
+     * The same long lived server side secret your rail derives its preimages from.
+     * Given here, every call carries a signature the gateway reads as your identity,
+     * so a payment you create is handed back to you and to nobody else. Withheld,
+     * you are anonymous and any holder of an id can read what it names
+     */
+    secret?: string;
+}
+/** How long to wait on a payment, and what the socket URL is allowed to carry */
+interface WaitOptions {
+    /** Give up when this aborts, `AbortSignal.timeout(ms)` covers the usual case */
+    signal?: AbortSignal;
+    /**
+     * Mint a short-lived ticket and put that in the socket URL instead of the
+     * payment id. Implied by `token` and by `secret`. The id stays readable inside the ticket,
+     * what changes is that a URL out of a log stops opening anything after a
+     * minute
+     */
+    tickets?: boolean;
+}
+/** What a socket ticket opens beyond the trigger it names */
+interface TicketOptions {
+    /**
+     * How many of this trigger's settlements the socket replays on connect, up to
+     * the ceiling the gateway's operator set
+     */
+    replay?: number;
+}
+/** What a mint carries beyond the charge: a retry key, and which trigger it joins */
+interface CreateOptions {
+    /**
+     * Makes the POST safe to retry. A repeat of a finished request replays its
+     * payment instead of asking a wallet for a second invoice, a repeat that
+     * arrives while the first is still resolving throws
+     * `IdempotencyConflictError`, and the key is held for 24 hours
+     */
+    idempotencyKey?: string;
+    /**
+     * Groups this payment with every other one carrying the same secret, so
+     * `follow` can watch the place rather than the payment. Registering
+     * sends only its sha256, which is also all the gateway stores, so a stolen
+     * ledger cannot subscribe. Following sends the secret itself, because the
+     * gateway hashes what it is given to find the stream, so the operator of a
+     * gateway you do not own learns it the first time you connect. Keep it apart
+     * from any URL a payer sees
+     */
+    trigger?: string;
+    /**
+     * How many of the trigger's settlements the gateway keeps replayable past the
+     * hour it would otherwise forget them in, up to the ceiling its operator set.
+     * Needs `trigger`, defaults to none
+     */
+    replay?: number;
+}
+/** What to do with a trigger's settlements, and how hard to try to keep hearing them */
+interface FollowOptions {
+    /** Called for the recent settlements replayed on connect, then for each new one */
+    onPayment: (settled: Payment) => void;
+    /**
+     * How many settlements to ask for on connect, defaults to the gateway's ten.
+     * It hands back what it still holds, which is the last hour unless the
+     * payments were minted with `replay`
+     */
+    replay?: number;
+    /** Called when a connection drops or a frame is refused, the follow keeps going */
+    onError?: (error: unknown) => void;
+    /** Reconnect after a drop, defaults to true */
+    reconnect?: boolean;
+    /**
+     * The first wait after a drop, doubling up to 30 seconds and jittered so a
+     * fleet does not come back in lockstep, defaults to 3000. A connection that
+     * opens puts it back to the first wait
+     */
+    reconnectDelayMs?: number;
+    /**
+     * Mint a short-lived ticket and put that in the socket URL instead of the
+     * secret, one per connection. Keeps the secret out of access logs, at the cost
+     * of a POST before each connect. Implied by `token` and by `secret`. Leave it off for a
+     * microcontroller, where one hardcoded URL and a dumb reconnect loop is the
+     * whole point
+     */
+    tickets?: boolean;
+}
+/** How this caller holds a socket open and what it answers on it */
+interface AttendOptions {
+    /**
+     * What this caller answers when the gateway asks about one of its payments.
+     * The preimage when the money is there, null while it is not, and the gateway
+     * checks the preimage against the hash either way
+     */
+    answer: (paymentHash: string) => Promise<string | null> | string | null;
+    /** Called when a connection drops or a frame is refused, the socket keeps going */
+    onError?: (error: unknown) => void;
+    /** Reconnect after a drop, defaults to true */
+    reconnect?: boolean;
+    /** The first wait after a drop, doubling and jittered, defaults to 3000 */
+    reconnectDelayMs?: number;
+}
+/** Talks to a Thunder Bridge gateway and trusts it for nothing it can check itself */
+declare class ThunderBridge {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly handedOut;
+    private readonly secret;
+    private strangers;
+    private speaks;
+    private published;
+    /** Everything this gateway lets you mount, from an LNURL endpoint to a webhook route */
+    readonly serve: Serve;
+    /** One call per sale, whatever the rail moves */
+    readonly rails: Rails;
+    constructor(baseUrl: string, options?: ThunderBridgeOptions);
+    /**
+     * Whether a token was given to this instance, which is your side of the
+     * arrangement and says nothing about the gateway's. `refusesStrangers` is the
+     * one that asks the gateway, and it is the one to guard anything with
+     */
+    get hasToken(): boolean;
+    /**
+     * Whether the gateway turns away a caller carrying no token, asked by making
+     * one unauthenticated read it would have to refuse. `hasToken` answers only
+     * whether you configured one, so a made-up token against a public instance
+     * reads as yours and is not. Asked once and remembered, because an instance
+     * does not change its mind. Anything other than a refusal counts as open, so
+     * an unreachable gateway fails closed
+     */
+    refusesStrangers(): Promise<boolean>;
+    /**
+     * Ask to be paid for one thing. It mints the invoice, proves it came from the
+     * address you asked for, draws the QR and hands back one object with a way to
+     * wait for the money. This is `mint` plus the two things every caller does next
+     */
+    requestPayment(asked: PaymentRequestInit): Promise<PaymentRequest>;
+    /**
+     * Ask the gateway for an invoice payable to the first address on your list
+     * that can issue a provable one, throws `NoWalletAvailableError` when none can
+     * and `GatewayCheatError` when what comes back is not what you asked for
+     */
+    mint(charge: Charge, options?: CreateOptions): Promise<MintedPayment>;
+    /**
+     * Ask which address would serve an amount without minting anything, throws
+     * `NoWalletAvailableError` when none would. A quote is a probe and not a
+     * promise: the address it names can still be refused at create time, because
+     * whether a wallet returns a provable invoice cannot be known without asking
+     * it for one, and asking mints it
+     */
+    quote(charge: Charge): Promise<Quote>;
+    /**
+     * The key this gateway signs webhooks with when you registered none of your own.
+     * `serve.webhook` reads it for you. Asked once and kept, because it is the same
+     * for every instance in the cluster
+     */
+    webhookKey(): Promise<string>;
+    private publishedKey;
+    /**
+     * Read a payment back, null when the gateway has never heard of it. One method
+     * for both sorts: `kind` says whether the gateway minted it or was handed it,
+     * and the address, amount and invoice are null on one it was never told
+     */
+    payment(held: Held): Promise<Payment | null>;
+    /**
+     * List what this gateway is watching, newest first. Only a gateway started
+     * with `GATEWAY_TOKEN` serves this, because on a shared one it would hand
+     * every caller everyone else's payments, so a public gateway answers 404.
+     *
+     * `scanned` says how many settled records were looked at to build the page.
+     * Anything older than that window is not in the answer, and the list does not
+     * pretend otherwise
+     */
+    payments(limit?: number): Promise<{
+        payments: Payment[];
+        scanned: number;
+    }>;
+    /**
+     * Follow a payment over WebSocket until it is paid or expired, reconnecting
+     * through a drop. A payment that never answers gives up after a few tries, and
+     * one that has answered is followed until its own expiry, so the wait always
+     * ends by itself
+     */
+    settled(held: Held, options?: WaitOptions): Promise<Payment>;
+    private followed;
+    /**
+     * Wait on several payments and keep the first one that is really paid, then stop
+     * waiting on the losers, which closes their sockets.
+     *
+     * This is how one order offers two rails. A Lightning invoice and a bank
+     * transfer for the same thing are two payments here, and the payer picks one, so
+     * what you want is the one that arrives and nothing further from the other.
+     *
+     * A leg that expires is a loser, not a winner, which is the whole reason this is
+     * not a race: `settled` ends on `paid` and on `expired` alike, and a
+     * Lightning invoice expires in an hour while a bank transfer takes days. `null`
+     * means every leg ended without being paid.
+     *
+     * Stopping the wait is not revoking the invoice. Nobody can revoke one, because
+     * the recipient's own wallet minted it, so a payer who pays the loser afterwards
+     * really does pay twice and that shows up on `follow` as a second settlement to
+     * refund.
+     */
+    firstSettled(held: Held[], options?: WaitOptions): Promise<Payment | null>;
+    /**
+     * Hand over an invoice you obtained yourself so the gateway watches it without
+     * being told the address or the amount. It can then only refuse everyone
+     * rather than one recipient, which is what makes leaving it cheap. Anything
+     * the watcher needs goes in `sealed`, which the gateway cannot read
+     */
+    watch(handover: Handover): Promise<Payment>;
+    /**
+     * What this payment is called, which you can work out before any gateway has
+     * heard of it. Every gateway you hand the same invoice to answers with the same
+     * name, so watching at several of them adds up to one payment rather than
+     * several, and no gateway's key is in the answer. Null when no secret was given,
+     * because then the gateway names the payment and only it can
+     */
+    nameFor(paymentHash: string): Promise<string | null>;
+    /**
+     * Hold a socket open and answer what the gateway asks about this caller's own
+     * payments, so a watch addressed to this caller settles without anybody
+     * hosting a URL. Reconnects on its own until the returned function is called
+     */
+    attend(options: AttendOptions): () => void;
+    /**
+     * Follow every payment made to one trigger, replayed from the recent ones on
+     * connect and then live, reconnecting on its own until the returned function
+     * is called. A trigger has no terminal state, so this never resolves
+     */
+    follow(secret: string, options: FollowOptions): () => void;
+    /**
+     * A one minute pass onto one trigger's stream, for something that must hold
+     * neither the token nor the trigger secret. Mint it in a handler and answer
+     * with the ticket alone, because that is all a browser needs to connect and
+     * all it can do anything with. `serve.watchTicket` is this method already
+     * wrapped in a route
+     */
+    ticket(trigger: string, options?: TicketOptions): Promise<SocketTicket>;
+    private needsTicket;
+    private wsTicket;
+    private mintedTicket;
+    private sending;
+    private reading;
+    private speaking;
+    private handOut;
+    private proven;
+}
+
+/** One incoming payment as the bank booked it, in the smallest unit of its currency */
+interface Credit {
+    amountMinor: number;
+    currency: string;
+    /** Whatever the payer wrote, wherever this bank puts it. Matching is a whole word, so noise around it is fine */
+    reference: string;
+    /**
+     * Unix seconds. A bank that books a day rather than an instant, as Fio does,
+     * gives the day's midnight in its own zone, so rendering this in UTC can show
+     * the day before. Nothing here matches on it, it is yours to read
+     */
+    bookedAt: number;
+}
+/**
+ * Recent credits on one account, oldest or newest first, it makes no difference.
+ * This is the whole plugin seam: a bank is a function of this shape, and
+ * `fioStatement` is one implementation of it
+ */
+type Statement = (sinceUnix: number) => Promise<Credit[]>;
+/** One transfer to ask for: what is owed, where it lands, and where its arrival is read back from */
+interface BankTransferParams {
+    /**
+     * Long lived and server side, at least 32 characters. The preimage is derived
+     * from it and the verify query is sealed with it, so losing it loses every proof
+     */
+    secret: string;
+    /** What the payer must leave on the transfer, an order id or a nonce. It is matched, not stored */
+    reference: string;
+    /** The price in the smallest unit, so 48055 is 480.55 CZK */
+    amountMinor: number;
+    /** The account the money goes to, as an IBAN */
+    iban: string;
+    /**
+     * Where `bankVerifyEndpoint` is mounted, a public https URL with no query of
+     * its own. Not needed when `answerBy` is "agent", because then nothing is polled
+     */
+    verifyUrl?: string;
+    /**
+     * How the gateway gets its answer. "poll" hands it a URL it fetches, which
+     * needs a public host. "agent" hands it this caller's name instead, and the
+     * socket `bankAgent` holds open answers for it, which needs no host at all
+     */
+    answerBy?: "poll" | "agent";
+    /** When the offer dies, in unix seconds. Money in a bank moves on banking days, so give it days */
+    expiresAt: number;
+    /** Defaults to CZK */
+    currency?: string;
+    /** Up to ten digits, for accounting systems that still want one */
+    variableSymbol?: string;
+    /**
+     * Groups this transfer with everything else paid to the same secret, so one
+     * `followTrigger` socket hears about it. Give the Lightning leg of the same
+     * order the same secret and both rails arrive on one stream
+     */
+    trigger?: string;
+    /** How many settlements of that trigger the gateway keeps replayable past the hour, needs `trigger` */
+    replay?: number;
+    /**
+     * Handed back on that stream, so a watcher learns which order settled without
+     * asking anyone. It is sealed under `secret` for this transfer's payment hash,
+     * so the gateway can neither read it nor move it onto another payment
+     */
+    sealed?: {
+        secret: string;
+        data: unknown;
+    };
+    /**
+     * Where the gateway posts once the money lands, a public https URL. Without one
+     * a transfer is only ever learned by following the trigger or asking
+     */
+    webhookUrl?: string;
+    /**
+     * Register on a gateway you do not own anyway. The sealed verify URL tells its
+     * operator nothing about the order, but the URL itself still answers whether
+     * that order was paid. Say true only when that much is not worth hiding
+     */
+    allowPublicGateway?: boolean;
+}
+/** A transfer the gateway is now watching, and the descriptor the payer scans */
+interface BankTransfer {
+    /** The watched payment's id at the gateway, which is how you read this order back */
+    id: string;
+    /** What the gateway was given, and what the preimage has to hash to */
+    paymentHash: string;
+    /** The same URL you mounted, carrying what to look for and a signature over it */
+    verifyUrl: string;
+    /** The payer scans this, it is a Short Payment Descriptor, the Czech QR platba format */
+    spd: string;
+}
+/** The endpoint the gateway polls for a bank transfer, answering off your own statement */
+interface BankVerifyConfig {
+    /** The same secret `bankTransfer` was given */
+    secret: string;
+    /** The IBAN this endpoint answers for, refusing a question sealed for another account */
+    iban: string;
+    /** The account to read */
+    statement: Statement;
+    /** How far back a credit still counts, seven days by default */
+    lookBackSecs?: number;
+    /**
+     * How often you want the gateway to ask, in seconds. It goes out as
+     * `Cache-Control: max-age`, so the pace is yours to set rather than the
+     * gateway's, and a bank that updates once a minute should say so instead of
+     * being polled every few seconds. Thirty by default, clamped to an hour
+     */
+    pollEverySecs?: number;
+}
+/** One order this caller is waiting on, and the account it is waiting on it in */
+interface BankOrder {
+    iban: string;
+    reference: string;
+    amountMinor: number;
+    currency?: string;
+    expiresAt: number;
+    statement: Statement;
+}
+/** What a caller needs to answer for its own transfers over a socket */
+interface BankAgentConfig {
+    /** The gateway holding the watches this caller raised */
+    gateway: ThunderBridge;
+    /** The same secret `bankTransfer` was given, never leaving this device */
+    secret: string;
+    /** What the payment the gateway is asking about was asking for, or null when it is none of ours */
+    orders: (paymentHash: string) => Promise<BankOrder | null> | BankOrder | null;
+    /** How far back a credit still counts, seven days by default */
+    lookBackSecs?: number;
+    /** Called when a connection drops or a frame is refused, the socket keeps going */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Answer the gateway over a socket this device opens, so a transfer addressed to
+ * this caller settles from a till behind NAT, a browser tab or a phone. The
+ * preimage is derived here from the secret, so the gateway is told only that one
+ * exists and can check it against the hash it already holds.
+ *
+ * Call the returned function to stop attending. Whatever is still open is asked
+ * again on the gateway's own schedule, so leaving and coming back loses nothing
+ */
+declare function bankAgent(config: BankAgentConfig): () => void;
+
+export { type AttendOptions as A, type BankAgentConfig as B, type Credit as C, type WebhookOptions as D, type WrapAllowance as E, type FollowOptions as F, answerVerifyChallenge as G, type Handler as H, carriesProof as I, invoiceFrom as J, proveOrigin as K, type Leg as L, type Minted as M, proveSettlement as N, type Order as O, type PaymentRequest as P, proveWrapped as Q, type RailConfig as R, type Statement as S, ThunderBridge as T, relayedVerifyUrl as U, wrapFeeCeiling as V, type WaitOptions as W, type BankOrder as a, type BankTransfer as b, type BankTransferParams as c, type BankVerifyConfig as d, bankAgent as e, type Rail as f, type ThunderBridgeOptions as g, type BankRailConfig as h, type BlindLightningRailConfig as i, type CreateOptions as j, type LightningRailConfig as k, type LightningVerifyConfig as l, type PaymentRequestInit as m, type PaymentRequestOptions as n, type Provable as o, type Proven as p, Rails as q, type Range as r, type Relayed as s, type Send as t, Serve as u, type TicketOptions as v, type TriggerConfig as w, type WatchTicketConfig as x, type WebhookCredential as y, type WebhookHandlers as z };