thunder-bridge 0.8.0 → 0.8.1

package/dist/index.d.cts

@@ -152,6 +152,12 @@ declare class ThunderBridge {
     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
@@ -168,6 +174,12 @@ declare class ThunderBridge {
     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
@@ -188,6 +200,36 @@ declare class ThunderBridge {
      * 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
@@ -282,6 +324,233 @@ interface Minted {
  */
 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;
+    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[]>;
+interface BankTransferParams {
+    /**
+     * The gateway that will watch this transfer. It has to be one of your own,
+     * meaning one you gave a token, unless `allowPublicGateway` says otherwise
+     */
+    gateway: ThunderBridge;
+    /** Long lived and server side. The preimage is derived from 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 */
+    verifyUrl: string;
+    /** 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;
+    /**
+     * Handed back untouched on that stream, so a watcher learns which order settled
+     * without asking anyone. `seal` it and the gateway cannot read it either
+     */
+    sealed?: 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
+     * URL itself answers whether that order was paid. Say true only when the order
+     * book is not worth hiding
+     */
+    allowPublicGateway?: boolean;
+}
+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;
+}
+interface BankVerifyConfig {
+    /** The same secret `bankTransfer` was given */
+    secret: string;
+    /** The account to read */
+    statement: Statement;
+    /** How far back a credit still counts, seven days by default */
+    lookBackSecs?: number;
+}
+/**
+ * Ask for a bank transfer and put it under the gateway's watch, so it settles
+ * the way a Lightning payment does.
+ *
+ * A BOLT11 payment proves settlement with a preimage whose sha256 the payer's
+ * invoice pins. A bank transfer has no such thing, so this mints one: the
+ * preimage is an HMAC of what is being asked for, and its hash is what the
+ * gateway is given. The money still moves straight to your account, and the
+ * gateway still learns only a hash and a URL to poll.
+ *
+ * What the preimage proves is therefore what LUD-21 proves and no more: that
+ * the server holding the secret saw the money arrive. It is the recipient's
+ * own word, made unforgeable by anyone else.
+ *
+ * The gateway has to be one of your own. Unlike a blind Lightning watch, which
+ * hands over a hash and an opaque wallet URL, this hands over a URL naming the
+ * amount and the reference, so whoever runs the gateway can read your order book
+ * from the watches alone.
+ */
+declare function bankTransfer(params: BankTransferParams): Promise<BankTransfer>;
+/**
+ * The verify endpoint the gateway polls, as a Fetch handler, so it runs wherever
+ * `lnurlPayEndpoint` does.
+ *
+ * It answers the LUD-21 shape: `settled` false until a matching credit is on the
+ * statement, then `settled` true with the preimage. Nothing is stored, because
+ * the preimage is derived again from the secret every time it is asked for.
+ *
+ * The query has to carry the signature `bankTransfer` put there. Without that
+ * check this would answer "did anyone send you 480.55 with this note" to whoever
+ * asked, which is your bank statement handed out one question at a time.
+ */
+declare function bankVerifyEndpoint(config: BankVerifyConfig): (request: Request) => Promise<Response>;
+
+interface FioConfig {
+    /**
+     * A token with "Sledování účtu" rights, which is read only and cannot move
+     * money. One token is one account, which is why this takes no account number.
+     *
+     * Give it several and they are used in turn. Fio's window is per token rather
+     * than per account, so five tokens on one account is a read every six seconds,
+     * and generating another token for the same account is what Fio's own
+     * documentation suggests when one is not enough
+     */
+    token: string | string[];
+    /**
+     * Fio's window for one token, 30 seconds. No token is ever asked twice inside
+     * it, and the gap between reads is this divided by however many tokens were
+     * given, so the answers stay evenly spaced rather than arriving in bursts.
+     * Inside that gap the last answer is handed back. Only helps a process that
+     * stays up
+     */
+    minIntervalSecs?: number;
+    /** Override to point at a mock */
+    baseUrl?: string;
+}
+/**
+ * Read one Fio account as a `Statement`, so a bank transfer proves itself the
+ * way a Lightning payment does.
+ *
+ * The token is the read only kind, generated in internetbanking under Nastavení
+ * and API, and it is the whole configuration: a token belongs to one account, so
+ * there is no account number to get wrong. It cannot pay anyone, and the worst a
+ * leaked one costs you is that someone else can read the statement.
+ *
+ * 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.
+ */
+declare function fioStatement(config: FioConfig): Statement;
+
+/**
+ * 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
+ * is a normal answer rather than a fault: Kraken and Bitstamp have no CZK pair
+ *
+ * This is the plugin seam for prices. Another venue is another function of this
+ * shape
+ */
+type Ticker = (currency: string) => Promise<number>;
+interface MedianOptions {
+    /**
+     * How many venues have to answer before a price is usable. Two is the floor
+     * worth having, because one venue is a number nobody checked
+     */
+    minVenues?: number;
+    /**
+     * Refuse the lot when the cheapest and dearest answers are further apart than
+     * this many basis points. Venues normally sit inside 50, so a wider spread means
+     * one of them is broken or stale rather than that the market moved
+     */
+    maxSpreadBps?: number;
+    /** Hold the last answer this long per currency, so an order page is not four requests */
+    holdForSecs?: number;
+}
+/** Coinbase, CASP authorised in Luxembourg. Quotes CZK, EUR and most fiat */
+declare function coinbase(baseUrl?: string): Ticker;
+/** Kraken, CASP authorised by the Central Bank of Ireland. Quotes EUR and USD, no CZK */
+declare function kraken(baseUrl?: string): Ticker;
+/**
+ * Bitstamp, CASP authorised by the CSSF in Luxembourg. Quotes EUR and USD, no CZK.
+ *
+ * An unknown pair is answered with a `200` and the whole ticker list, whose first
+ * entry is BTC/USD, so asking it for CZK and reading the number would quote a
+ * bitcoin at 64,000 crowns. Anything but a single object is therefore refused
+ */
+declare function bitstamp(baseUrl?: string): Ticker;
+/** Coinmate, on the ESMA CASP register, Czech and the one with a real BTC/CZK book */
+declare function coinmate(baseUrl?: string): Ticker;
+/**
+ * Ask several venues and take the middle answer, refusing the lot when they
+ * disagree too much.
+ *
+ * The default is the four MiCA authorised venues below, and every one of them is
+ * replaceable: pass your own list, or one venue, or a function that reads a price
+ * you already have. A venue that does not quote the currency is skipped rather
+ * than fatal, which for CZK leaves Coinbase and Coinmate.
+ *
+ * The middle is taken rather than the mean so one stuck venue moves the answer by
+ * nothing instead of by half its error, and the spread check is what catches the
+ * stuck venue that stays inside the pack.
+ */
+declare function medianOf(tickers?: Ticker[], options?: MedianOptions): Ticker;
+/**
+ * What to ask for over Lightning for a price named in fiat, in millisatoshi.
+ *
+ * `priceMinorPerBtc` is what a `Ticker` returns. The arithmetic is exact, in
+ * BigInt, because a million crown order times a hundred billion millisatoshi
+ * leaves what a double can count, and it rounds up, because the extra
+ * millisatoshi is worth nothing and belongs to the recipient rather than to a
+ * rounding rule.
+ *
+ * `spreadBps` is yours to set, in basis points, and defaults to none. A Lightning
+ * invoice lives an hour and a bank transfer takes days, so a shop pricing in fiat is
+ * carrying that volatility whether or not it charges for it
+ */
+declare function msatFor(amountMinor: number, priceMinorPerBtc: number, options?: {
+    spreadBps?: number;
+}): number;
+
+/**
+ * How many digits ISO 4217 gives the currency's minor unit, so 2 for a crown and a
+ * euro, 0 for a yen and 3 for a dinar.
+ *
+ * There is no sane default here, which is why an unlisted code throws rather than
+ * being treated as two. Assuming two turns 1000 yen into 10 and a dinar into a
+ * tenth of itself, and a payment library that guesses at this is a payment library
+ * that moves the wrong amount.
+ */
+declare function minorUnitsOf(currency: string): number;
+/** The scale that minor unit implies, so 100 for a crown, 1 for a yen, 1000 for a dinar */
+declare function minorScaleOf(currency: string): 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
@@ -338,6 +607,14 @@ declare function invoiceToDataUrl(destination: string, options?: QrOptions): str
 declare function lnurlToSvg(endpoint: string, options?: QrOptions): string;
 /** SVG data URL of the endpoint's QR, for an `<img>` `src` */
 declare function lnurlToDataUrl(endpoint: string, options?: QrOptions): string;
+/**
+ * Render the `spd` from `bankTransfer` as the QR a Czech banking app scans. The
+ * payload is a Short Payment Descriptor, so it carries the account, the amount
+ * and the reference the payer must leave on the transfer
+ */
+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;
 
 /**
  * Bech32-encode a pay endpoint as the `LNURL1` string LUD-01 defines, uppercase
@@ -398,10 +675,21 @@ declare class ProblemError extends Error {
         detail?: string;
     });
 }
-declare const NO_WALLET_AVAILABLE = "urn:problem-type:thunder-bridge-direct:no-wallet-available";
-declare const REQUEST_IN_FLIGHT = "urn:problem-type:thunder-bridge-direct:request-in-flight";
-declare const IDEMPOTENCY_KEY_REUSED = "urn:problem-type:thunder-bridge-direct:idempotency-key-reused";
-declare const PAYMENT_ALREADY_WATCHED = "urn:problem-type:thunder-bridge-direct:payment-already-watched";
+/**
+ * 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
+ */
+declare function isProblemType(problem: {
+    type?: string;
+}, type: string): boolean;
+declare const NO_WALLET_AVAILABLE = "urn:problem-type:thunder-bridge:no-wallet-available";
+declare const REQUEST_IN_FLIGHT = "urn:problem-type:thunder-bridge:request-in-flight";
+declare const IDEMPOTENCY_KEY_REUSED = "urn:problem-type:thunder-bridge:idempotency-key-reused";
+declare const PAYMENT_ALREADY_WATCHED = "urn:problem-type:thunder-bridge:payment-already-watched";
 /**
  * Why an `Idempotency-Key` was refused, `request-in-flight` is the benign one and
  * `key-reused` means the same key was sent for a different request
@@ -432,4 +720,4 @@ declare class NoWalletAvailableError extends ProblemError {
     }, wallets: WalletFailure[]);
 }
 
-export { type CreateOptions, type CreatePaymentParams, type CreateQuoteParams, type FollowOptions, type GatewayCheatCode, GatewayCheatError, IDEMPOTENCY_KEY_REUSED, type IdempotencyConflict, IdempotencyConflictError, type Invoice, type Minted, NO_WALLET_AVAILABLE, NoWalletAvailableError, PAYMENT_ALREADY_WATCHED, type Payment, type PaymentStatus, ProblemError, type QrOptions, type Quote, REQUEST_IN_FLIGHT, ThunderBridge, type ThunderBridgeOptions, type TriggerConfig, type TriggerEvent, UnverifiedRecipientError, type WaitOptions, type WalletFailure, type WalletReason, type WatchPaymentParams, type WebhookOptions, decodeInvoice, invoiceToDataUrl, invoiceToSvg, isProvablyPaid, lnurlPayEndpoint, lnurlToDataUrl, lnurlToSvg, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, seal, toLnurl, unseal, verifyWebhookSignature };
+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 };