thunder-bridge 0.8.1 → 0.8.3

package/dist/rail-Cyc5zTtA.d.cts

@@ -0,0 +1,375 @@
+/** 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. 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;
+}
+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;
+    private strangers;
+    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;
+    /**
+     * Whether the gateway turns away a caller carrying no token, asked by making
+     * one unauthenticated read it would have to refuse. `isPrivate` answers only
+     * whether you configured a token, which is your side of the arrangement and
+     * says nothing about the gateway's, so a made-up token against a public
+     * instance reads as private 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 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;
+}
+
+/** 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 reads it only through your own `amountMsat` */
+    currency: string;
+}
+/** One way to pay one order, already registered with the gateway */
+interface Leg {
+    /** The watched payment's id, which is what `firstToSettle`, `getWatched` and `waitForWatched` take */
+    id: 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>;
+interface BankRailConfig {
+    /** The gateway that will watch these transfers. It has to be one of your own */
+    gateway: ThunderBridge;
+    /** 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 `bankVerifyEndpoint` is mounted, a public https URL with no query of its own */
+    verifyUrl: string;
+    /**
+     * When this order stops being payable, in unix seconds. Re-offering one order
+     * has to return the same second every time, because the gateway compares the
+     * expiry to decide whether a repeated watch is the same watch
+     */
+    expiresAt: (order: Order) => number;
+    /** Groups every leg on the same secret, so one `followTrigger` socket hears them all */
+    trigger?: string;
+    /** Handed back untouched on that stream. Stable across re-offers, for the reason `expiresAt` is */
+    sealed?: (order: Order) => string | Promise<string>;
+    /** Up to ten digits, for accounting systems that still want one */
+    variableSymbol?: (order: Order) => string | undefined;
+    /** Register on a gateway you do not own anyway, on the terms `bankTransfer` sets out */
+    allowPublicGateway?: boolean;
+    /** What `Leg.rail` reads, for a shop running more than one account */
+    name?: string;
+}
+interface LightningRailConfig {
+    /** The gateway that mints the invoice */
+    gateway: ThunderBridge;
+    /** Priority list, the gateway takes the first that can issue a provable invoice */
+    lnAddresses: string[];
+    /** What this order costs in millisatoshi. A shop pricing in fiat writes `msatFor` and its own ticker */
+    amountMsat: (order: Order) => number | Promise<number>;
+    /** Groups every leg on the same secret, so one `followTrigger` socket hears them all */
+    trigger?: string;
+    /**
+     * Makes the mint safe to retry. Unset nothing is sent, because a key stable
+     * across re-offers is one the gateway can join against the bank leg's reference
+     */
+    idempotencyKey?: (order: Order) => string | undefined;
+    webhookUrl?: string;
+    webhookSecret?: string;
+    /** What `Leg.rail` reads, for a shop running more than one wallet */
+    name?: string;
+}
+interface BlindLightningRailConfig {
+    /** The gateway that watches an invoice it was never allowed to mint */
+    gateway: ThunderBridge;
+    /** Priority list, resolved here rather than by the gateway */
+    lnAddresses: string[];
+    /** What this order costs in millisatoshi */
+    amountMsat: (order: Order) => number | Promise<number>;
+    /** Groups every leg on the same secret, so one `followTrigger` socket hears them all */
+    trigger?: string;
+    /** Only a watched leg has anywhere to carry this */
+    sealed?: (order: Order) => string | Promise<string>;
+    /** What `Leg.rail` reads, for a shop running more than one wallet */
+    name?: string;
+}
+/**
+ * Sell for a bank transfer. The money moves straight to your account and the
+ * gateway is told a hash, a URL and an expiry, never the amount or the reference.
+ *
+ * Which bank is read back is `bankVerifyEndpoint`'s business, not this one's, so
+ * a rail built here serves Fio and anything else behind a `Statement`.
+ */
+declare function bankRail(config: BankRailConfig): Rail;
+/**
+ * Sell for Lightning, with the gateway minting the invoice. It is told the
+ * address list and the amount, which is the round trip `blindLightningRail`
+ * spends to avoid.
+ */
+declare function lightningRail(config: LightningRailConfig): Rail;
+/**
+ * Sell for Lightning, resolving the address here and handing the gateway only a
+ * hash and a URL to poll. It costs one more round trip and the gateway learns
+ * neither who is being paid nor how much, so the only refusal left to it is
+ * refusing everyone.
+ */
+declare function blindLightningRail(config: BlindLightningRailConfig): Rail;
+
+export { type BankRailConfig as B, type CreatePaymentParams as C, type FollowOptions as F, type Leg as L, type Order as O, type Payment as P, type Quote as Q, type Rail as R, ThunderBridge as T, type WalletFailure as W, type CreateOptions as a, type CreateQuoteParams as b, type LightningRailConfig as c, type PaymentStatus as d, type ThunderBridgeOptions as e, type TriggerEvent as f, type WaitOptions as g, type WalletReason as h, type WatchPaymentParams as i, bankRail as j, type BlindLightningRailConfig as k, lightningRail as l, blindLightningRail as m };