thunder-bridge 0.8.1 → 0.8.3

package/dist/index.d.cts

@@ -1,255 +1,5 @@
-/** Where a payment stands, `paid` is the only status that carries a preimage */
-type PaymentStatus = "pending" | "paid" | "expired";
-/** A payment as the gateway reports it, every field is checkable against the recipient */
-interface Payment {
-    id: string;
-    lnAddress: string;
-    amountMsat: number;
-    status: PaymentStatus;
-    paymentHash: string;
-    bolt11: string;
-    preimage: string | null;
-    expiresAt: number;
-    createdAt: number;
-    verifyUrl: string;
-}
-/**
- * `lnAddresses` is a priority list, the gateway takes the first one that can
- * issue a provable invoice for `amountMsat` and the rest are the fallback
- */
-interface CreatePaymentParams {
-    lnAddresses: string[];
-    amountMsat: number;
-    webhookUrl?: string;
-    webhookSecret?: string;
-}
-/**
- * `lnAddresses` is the same priority list `createPayment` takes, and quoting it
- * mints nothing and charges the recipient's wallet nothing
- */
-interface CreateQuoteParams {
-    lnAddresses: string[];
-    amountMsat: number;
-}
-/**
- * Which address would serve an amount, and what the ones ahead of it refused.
- * `feeMsat` is always zero, the payer pays the recipient's own invoice and the
- * gateway is never in the money's path
- */
-interface Quote {
-    lnAddress: string;
-    amountMsat: number;
-    feeMsat: number;
-    minMsat: number;
-    maxMsat: number;
-    metadata: string;
-    refusals: WalletFailure[];
-}
-/**
- * What the gateway reports about a payment it is watching, for a trigger stream
- * or for one you minted yourself. `lnAddress` and `amountMsat` are null when the
- * gateway was never told them, which is the point of `watchPayment`: what the
- * watcher needs but the gateway should not know travels in `sealed` instead
- */
-interface TriggerEvent {
-    id: string;
-    paymentHash: string;
-    verifyUrl: string;
-    status: PaymentStatus;
-    preimage: string | null;
-    expiresAt: number;
-    createdAt: number;
-    sealed: string | null;
-    lnAddress: string | null;
-    amountMsat: number | null;
-}
-/**
- * An invoice you obtained yourself, handed over to be watched. The gateway is
- * given no address and no amount, so it cannot refuse one recipient rather than
- * all of them
- */
-interface WatchPaymentParams {
-    paymentHash: string;
-    verifyUrl: string;
-    expiresAt: number;
-    trigger?: string;
-    sealed?: string;
-}
-/** Why one wallet in the list could not be used */
-type WalletReason = "address-unusable" | "unreachable" | "amount-not-accepted" | "cannot-prove-delivery" | "invoice-refused";
-interface WalletFailure {
-    address: string;
-    reason: WalletReason;
-}
-
-interface ThunderBridgeOptions {
-    /**
-     * Prove every payment against the recipient's own server before handing it
-     * back, and refuse a reported settlement whose preimage does not hash to the
-     * payment hash, defaults to true
-     */
-    verify?: boolean;
-    /**
-     * 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;
-}
-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`. 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;
-}
-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
-     * `followTrigger` can watch the place rather than the payment. Only its
-     * sha256 reaches the gateway, and the secret itself is what authorises the
-     * stream, so keep it apart from any URL a payer sees
-     */
-    trigger?: string;
-}
-interface FollowOptions {
-    /** Called for the recent settlements replayed on connect, then for each new one */
-    onPayment: (settled: TriggerEvent) => void;
-    /** 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`. Leave it off for a
-     * microcontroller, where one hardcoded URL and a dumb reconnect loop is the
-     * whole point
-     */
-    tickets?: boolean;
-}
-/** Talks to a Thunder Bridge gateway and trusts it for nothing it can check itself */
-declare class ThunderBridge {
-    private readonly baseUrl;
-    private readonly verify;
-    private readonly token;
-    constructor(baseUrl: string, options?: ThunderBridgeOptions);
-    /**
-     * Whether a token was given, which is what makes an instance yours: a gateway
-     * started with `GATEWAY_TOKEN` answers nobody else, so anything you hand it
-     * stays between you and it
-     */
-    get isPrivate(): boolean;
-    /**
-     * 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
-     */
-    createPayment(params: CreatePaymentParams, options?: CreateOptions): Promise<Payment>;
-    /**
-     * 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
-     */
-    createQuote(params: CreateQuoteParams): Promise<Quote>;
-    /** Read a payment back, null when the gateway has never heard of it */
-    getPayment(id: string): Promise<Payment | null>;
-    /**
-     * Read back a payment the gateway is only watching, null when it has never
-     * heard of it. A watched payment carries no address, amount or invoice, so
-     * `getPayment` refuses it and this reads the shape both rails share
-     */
-    getWatched(id: string): Promise<TriggerEvent | 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
-     */
-    listPayments(limit?: number): Promise<{
-        payments: TriggerEvent[];
-        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
-     */
-    waitForPayment(id: string, options?: WaitOptions): Promise<Payment>;
-    /**
-     * Follow a payment the gateway is only watching, one it did not mint, until it
-     * is paid or expired.
-     *
-     * A watched payment carries no address, no amount and no invoice, because the
-     * gateway was told none of them, so it reads back as the shape a trigger
-     * streams rather than as a `Payment`. That is every bank transfer, and every
-     * Lightning invoice registered with `watchPayment` instead of `createPayment`.
-     */
-    waitForWatched(id: string, options?: WaitOptions): Promise<TriggerEvent>;
-    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: `waitForPayment` 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 `followTrigger` as a second
-     * settlement to refund.
-     */
-    firstToSettle(ids: string[], options?: WaitOptions): Promise<TriggerEvent | 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
-     */
-    watchPayment(params: WatchPaymentParams): Promise<TriggerEvent>;
-    /**
-     * 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
-     */
-    followTrigger(secret: string, options: FollowOptions): () => void;
-    private needsTicket;
-    private wsTicket;
-    private sending;
-    private reading;
-    private proven;
-    private checked;
-}
+import { T as ThunderBridge, P as Payment, C as CreatePaymentParams, W as WalletFailure } from './rail-Cyc5zTtA.cjs';
+export { B as BankRailConfig, a as CreateOptions, b as CreateQuoteParams, F as FollowOptions, L as Leg, c as LightningRailConfig, O as Order, d as PaymentStatus, Q as Quote, R as Rail, e as ThunderBridgeOptions, f as TriggerEvent, g as WaitOptions, h as WalletReason, i as WatchPaymentParams, j as bankRail, l as lightningRail } from './rail-Cyc5zTtA.cjs';
 
 /**
  * Encrypt what the watcher needs and the gateway must not have. The gateway
@@ -264,72 +14,17 @@ declare function seal(secret: string, plaintext: string): Promise<string>;
  */
 declare function unseal(secret: string, sealed: string): Promise<string | null>;
 
-interface TriggerConfig {
-    /** The gateway that quotes the addresses and mints the invoice */
-    gateway: ThunderBridge;
-    /** Priority list, quoted at payRequest and then pinned for the callback */
-    lnAddresses: string[];
-    /**
-     * What this trigger costs right now, called once per payRequest. A plain
-     * function, so a fiat peg or a time of day rule is just code you write
-     */
-    amountMsat: () => number | Promise<number>;
-    /**
-     * 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 `followTrigger` can watch the place, keep it off the QR */
-    watchSecret?: string;
-    /** 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
-     */
-    blind?: boolean;
-    /**
-     * 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;
-    };
-}
-interface Minted {
-    lnAddress: string;
-    amountMsat: number;
-    bolt11: string;
-    paymentHash: string;
-    verifyUrl: string;
-    expiresAt: number;
-}
-/**
- * An LNURL-pay endpoint standing in front of a priority list of addresses, as a
- * Fetch handler so it runs on Deno Deploy, Workers, Hono, Next and Node alike.
- *
- * It answers both halves of the flow on one path. A bare request is the
- * payRequest and quotes the list, and a signed one is the callback and mints.
- * The winner is chosen at payRequest and pinned into the callback URL because
- * LUD-06 binds the invoice to the metadata already served: if the callback
- * picked a different address the payer's wallet would refuse the invoice.
- *
- * Nothing is stored between the two, so this holds no state of its own.
- */
-declare function lnurlPayEndpoint(config: TriggerConfig): (request: Request) => Promise<Response>;
-
 /** 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 substring, 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;
 }
 /**
@@ -464,8 +159,9 @@ interface FioConfig {
  *
  * Every field on a Fio transaction is optional and arrives as `null` when it is
  * absent, the amount carries its direction in its sign rather than in a flag,
- * and the date is unix milliseconds. This reads all three the way the bank
- * documents them and treats a missing field as absent rather than guessing.
+ * and the date is a day and a UTC offset, `2026-07-15+0200`. This reads all
+ * three the way the bank answers them and treats a missing field as absent
+ * rather than guessing.
  */
 declare function fioStatement(config: FioConfig): Statement;
 
@@ -615,6 +311,14 @@ declare function lnurlToDataUrl(endpoint: string, options?: QrOptions): string;
 declare function spdToSvg(spd: string, options?: QrOptions): string;
 /** SVG data URL of the bank transfer's QR, for an `<img>` `src` */
 declare function spdToDataUrl(spd: string, options?: QrOptions): string;
+/**
+ * Render any rail's `Leg.qr` as an SVG QR code. Each rail states its own payload,
+ * a BOLT11 invoice under the `LIGHTNING` scheme or a Short Payment Descriptor as
+ * it stands, so this draws a leg without being told which rail made it
+ */
+declare function qrToSvg(payload: string, options?: QrOptions): string;
+/** SVG data URL of a leg's QR, for an `<img>` `src` */
+declare function qrToDataUrl(payload: string, options?: QrOptions): string;
 
 /**
  * Bech32-encode a pay endpoint as the `LNURL1` string LUD-01 defines, uppercase
@@ -675,14 +379,7 @@ declare class ProblemError extends Error {
         detail?: string;
     });
 }
-/**
- * Whether a problem document carries this type, accepting the namespace this
- * project used before `direct` left its name.
- *
- * A problem type is an identifier clients branch on, so renaming one is a breaking
- * change. The gateway emits only the new spelling, and this reads both, so a client
- * that has been updated still types the errors of an instance that has not
- */
+/** Whether a problem document carries this type */
 declare function isProblemType(problem: {
     type?: string;
 }, type: string): boolean;
@@ -720,4 +417,4 @@ declare class NoWalletAvailableError extends ProblemError {
     }, wallets: WalletFailure[]);
 }
 
-export { type BankTransfer, type BankTransferParams, type BankVerifyConfig, type CreateOptions, type CreatePaymentParams, type CreateQuoteParams, type Credit, type FioConfig, type FollowOptions, type GatewayCheatCode, GatewayCheatError, IDEMPOTENCY_KEY_REUSED, type IdempotencyConflict, IdempotencyConflictError, type Invoice, type MedianOptions, type Minted, NO_WALLET_AVAILABLE, NoWalletAvailableError, PAYMENT_ALREADY_WATCHED, type Payment, type PaymentStatus, ProblemError, type QrOptions, type Quote, REQUEST_IN_FLIGHT, type Statement, ThunderBridge, type ThunderBridgeOptions, type Ticker, type TriggerConfig, type TriggerEvent, UnverifiedRecipientError, type WaitOptions, type WalletFailure, type WalletReason, type WatchPaymentParams, type WebhookOptions, bankTransfer, bankVerifyEndpoint, bitstamp, coinbase, coinmate, decodeInvoice, fioStatement, invoiceToDataUrl, invoiceToSvg, isProblemType, isProvablyPaid, kraken, lnurlPayEndpoint, lnurlToDataUrl, lnurlToSvg, medianOf, minorScaleOf, minorUnitsOf, msatFor, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, seal, spdToDataUrl, spdToSvg, toLnurl, unseal, verifyWebhookSignature };
+export { type BankTransfer, type BankTransferParams, type BankVerifyConfig, CreatePaymentParams, type Credit, type FioConfig, type GatewayCheatCode, GatewayCheatError, IDEMPOTENCY_KEY_REUSED, type IdempotencyConflict, IdempotencyConflictError, type Invoice, type MedianOptions, NO_WALLET_AVAILABLE, NoWalletAvailableError, PAYMENT_ALREADY_WATCHED, Payment, ProblemError, type QrOptions, REQUEST_IN_FLIGHT, type Statement, ThunderBridge, type Ticker, UnverifiedRecipientError, WalletFailure, type WebhookOptions, bankTransfer, bankVerifyEndpoint, bitstamp, coinbase, coinmate, decodeInvoice, fioStatement, invoiceToDataUrl, invoiceToSvg, isProblemType, isProvablyPaid, kraken, lnurlToDataUrl, lnurlToSvg, medianOf, minorScaleOf, minorUnitsOf, msatFor, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, qrToDataUrl, qrToSvg, seal, spdToDataUrl, spdToSvg, toLnurl, unseal, verifyWebhookSignature };