thunder-bridge 0.8.2 → 0.8.4

package/dist/index.d.ts

@@ -1,269 +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. 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;
-}
+import { T as ThunderBridge, P as Payment, C as CreatePaymentParams, a as TriggerEvent, W as WalletFailure } from './rail-QZtUN1D-.js';
+export { B as BankRailConfig, b as CreateOptions, c as CreateQuoteParams, F as FollowOptions, L as Leg, d as LightningRailConfig, O as Order, e as PaymentStatus, Q as Quote, R as Rail, f as ThunderBridgeOptions, g as WaitOptions, h as WalletReason, i as WatchPaymentParams, j as bankRail, l as lightningRail } from './rail-QZtUN1D-.js';
 
 /**
  * Encrypt what the watcher needs and the gateway must not have. The gateway
@@ -278,66 +14,6 @@ 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;
@@ -390,6 +66,13 @@ interface BankTransferParams {
      * without asking anyone. `seal` it and the gateway cannot read it either
      */
     sealed?: string;
+    /**
+     * 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;
+    /** Signs that delivery, so `verifyWebhookSignature` can tell it came from the gateway */
+    webhookSecret?: string;
     /**
      * Register on a gateway you do not own anyway. The verify URL names the amount
      * and the reference, so its operator ends up reading your order book, and the
@@ -489,113 +172,6 @@ interface FioConfig {
  */
 declare function fioStatement(config: FioConfig): Statement;
 
-/** 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;
-
 /**
  * How many minor units of `currency` one bitcoin costs at one venue, so 134883815
  * is 1,348,838.15 CZK. Throws when that venue does not quote that currency, which
@@ -771,6 +347,14 @@ declare function parseWebhook(body: string | Uint8Array, signature: string, secr
  * Cloudflare Workers and Deno, WebCrypto only so it runs anywhere fetch does
  */
 declare function parseWebhookRequest(request: Request, secret: string, options?: WebhookOptions): Promise<Payment | null>;
+/**
+ * The same, for a payment the gateway only watched. A bank transfer and a blind
+ * Lightning leg carry no address, amount or invoice, so they arrive in the shape
+ * `followTrigger` and `getWatched` hand back rather than the minted one
+ */
+declare function parseWatchedWebhook(body: string | Uint8Array, signature: string, secret: string, timestamp: string, options?: WebhookOptions): Promise<TriggerEvent | null>;
+/** `parseWatchedWebhook` from a Fetch API `Request`, the way `parseWebhookRequest` is */
+declare function parseWatchedWebhookRequest(request: Request, secret: string, options?: WebhookOptions): Promise<TriggerEvent | null>;
 
 /**
  * The way a gateway was caught out, every code is a check that held against the
@@ -848,4 +432,4 @@ declare class NoWalletAvailableError extends ProblemError {
     }, wallets: WalletFailure[]);
 }
 
-export { type BankRailConfig, type BankTransfer, type BankTransferParams, type BankVerifyConfig, type BlindLightningRailConfig, type CreateOptions, type CreatePaymentParams, type CreateQuoteParams, type Credit, type FioConfig, type FollowOptions, type GatewayCheatCode, GatewayCheatError, IDEMPOTENCY_KEY_REUSED, type IdempotencyConflict, IdempotencyConflictError, type Invoice, type Leg, type LightningRailConfig, type MedianOptions, type Minted, NO_WALLET_AVAILABLE, NoWalletAvailableError, type Order, PAYMENT_ALREADY_WATCHED, type Payment, type PaymentStatus, ProblemError, type QrOptions, type Quote, REQUEST_IN_FLIGHT, type Rail, type Statement, ThunderBridge, type ThunderBridgeOptions, type Ticker, type TriggerConfig, type TriggerEvent, UnverifiedRecipientError, type WaitOptions, type WalletFailure, type WalletReason, type WatchPaymentParams, type WebhookOptions, bankRail, bankTransfer, bankVerifyEndpoint, bitstamp, blindLightningRail, coinbase, coinmate, decodeInvoice, fioStatement, invoiceToDataUrl, invoiceToSvg, isProblemType, isProvablyPaid, kraken, lightningRail, lnurlPayEndpoint, lnurlToDataUrl, lnurlToSvg, medianOf, minorScaleOf, minorUnitsOf, msatFor, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, qrToDataUrl, qrToSvg, 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, TriggerEvent, UnverifiedRecipientError, WalletFailure, type WebhookOptions, bankTransfer, bankVerifyEndpoint, bitstamp, coinbase, coinmate, decodeInvoice, fioStatement, invoiceToDataUrl, invoiceToSvg, isProblemType, isProvablyPaid, kraken, lnurlToDataUrl, lnurlToSvg, medianOf, minorScaleOf, minorUnitsOf, msatFor, parseWatchedWebhook, parseWatchedWebhookRequest, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, qrToDataUrl, qrToSvg, seal, spdToDataUrl, spdToSvg, toLnurl, unseal, verifyWebhookSignature };