thunder-bridge 1.4.2 → 1.5.0

package/dist/types-BNPmVnA7.d.cts

@@ -0,0 +1,252 @@
+/**
+ * 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>;
+/** How many venues have to agree, how far apart they may be, and how long an answer is held */
+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;
+
+declare const brand: unique symbol;
+/**
+ * A whole number of millisatoshi that came from `sats`, `msat` or `fiat`, and
+ * could not have come from anywhere else.
+ *
+ * The brand is why: a bare number is not one of these, so `21` cannot be passed
+ * where a price is wanted and quietly mean twenty-one thousandths of a satoshi.
+ * It costs nothing at runtime, where the value is an ordinary number
+ */
+type Msat = number & {
+    readonly [brand]: "Msat";
+};
+/**
+ * What a payment is worth. A `Msat` is a price known now, and a function is one
+ * worked out when the invoice is minted, which is what a fiat price has to be.
+ *
+ * Build one with `sats`, `msat` or `fiat`
+ */
+type Amount = Msat | (() => Msat | Promise<Msat>);
+/** How a fiat price is turned into millisatoshi at the moment of minting */
+interface FiatOptions {
+    /**
+     * Where the rate comes from, the median of the four MiCA authorised venues by
+     * default. Pass your own to price off one venue, off your own book, or off a
+     * number you already hold
+     */
+    rate?: Ticker;
+    /**
+     * What you add over the rate, in basis points, none by default. A Lightning
+     * invoice lives an hour and a bank transfer takes days, so a shop pricing in
+     * fiat carries that volatility whether or not it charges for it
+     */
+    spreadBps?: number;
+}
+/** A whole number of satoshi, so `sats(21)` is 21000 millisatoshi */
+declare function sats(whole: number): Msat;
+/** An exact number of millisatoshi, for a price already in the smallest unit */
+declare function msat(exact: number): Msat;
+/**
+ * A price named in fiat, converted when the invoice is minted rather than now.
+ *
+ * Name it as a string and it is read digit by digit, exactly. Name it as a
+ * number and it is rounded to the currency's ISO 4217 minor unit, because
+ * binary floating point cannot hold 4.99 and a payment library that pretends
+ * otherwise moves the wrong amount.
+ *
+ * Every conversion asks the rate afresh, so two calls a second apart can
+ * differ. That is the honest behaviour for a fiat price, and the reason an
+ * amount is a function rather than a number.
+ *
+ * The answer is rounded up to a whole satoshi, because a wallet issues an
+ * invoice in satoshi and refuses a fraction of one. Up rather than down, so the
+ * rounding is never the shop's loss. `msatFor` is the raw conversion, for a rail
+ * that has no invoice to round for
+ */
+declare function fiat(major: number | string, currency: string, options?: FiatOptions): () => Promise<Msat>;
+
+/** Where a payment stands, `paid` is the only status that carries a preimage */
+type PaymentStatus = "pending" | "paid" | "expired";
+interface Reported {
+    id: string;
+    status: PaymentStatus;
+    paymentHash: string;
+    verifyUrl: string;
+    preimage: string | null;
+    expiresAt: number;
+    createdAt: number;
+    /** What the watcher needs and the gateway cannot read, `unseal` opens it */
+    sealed: string | null;
+}
+/**
+ * A payment the gateway minted. It resolved the address itself, so it knows who
+ * is paid, how much, and which invoice says so, and none of the three can be
+ * null here
+ */
+interface MintedPayment extends Reported {
+    kind: "minted";
+    lnAddress: string;
+    amountMsat: number;
+    bolt11: string;
+}
+/**
+ * A payment the gateway was handed rather than asked to mint. It was told a hash,
+ * a URL and an expiry and nothing else, which is the point of `watch`, so the
+ * address, the amount and the invoice are all absent rather than merely unknown
+ */
+interface WatchedPayment extends Reported {
+    kind: "watched";
+    lnAddress: null;
+    amountMsat: null;
+    bolt11: null;
+}
+/**
+ * A payment as the gateway reports it, of either sort. Check `kind` and the
+ * three fields a watched payment does not carry stop being null, so nothing here
+ * needs an assertion to read
+ */
+type Payment = MintedPayment | WatchedPayment;
+/**
+ * Who is paid and how much. `to` is a priority list when it is an array: the
+ * gateway takes the first address that can issue a provable invoice for the
+ * amount and the rest are the fallback
+ */
+interface Charge {
+    paidTo: string | string[];
+    amount: Amount;
+    /** Where the gateway posts the settlement, signed with the key it publishes */
+    webhookUrl?: string;
+}
+/**
+ * A charge with its price settled, which is what a proof compares the gateway's
+ * answer against. Asking a fiat price twice gives two numbers, so the proof is
+ * handed the one that was actually asked for
+ */
+interface Priced {
+    paidTo: string[];
+    amountMsat: number;
+}
+/**
+ * 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 Handover {
+    paymentHash: string;
+    verifyUrl: string;
+    expiresAt: number;
+    /** Groups this payment with every other one carrying the same secret */
+    trigger?: string;
+    /**
+     * How many of this 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;
+    /** Sealed with `seal`, so the gateway stores what it cannot read */
+    sealed?: string;
+    webhookUrl?: string;
+}
+/**
+ * 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[];
+}
+/**
+ * A one minute pass onto one trigger's stream. It opens that trigger and nothing
+ * else, which is what makes it the thing to hand a browser when the trigger
+ * secret is not. `expiresAt` is unix seconds, like every other time here
+ */
+interface SocketTicket {
+    ticket: string;
+    expiresAt: number;
+}
+/** Why one wallet in the list could not be used */
+type WalletReason = "address-unusable" | "unreachable" | "amount-not-accepted" | "cannot-prove-delivery" | "invoice-refused";
+/** One wallet on the list that could not be used, and the reason it could not */
+interface WalletFailure {
+    address: string;
+    reason: WalletReason;
+}
+/**
+ * What a delivery carries. Everything needed to act on a settlement and to check
+ * it, and nothing else, so a retry is the same size every time
+ */
+interface Settlement {
+    id: string;
+    status: PaymentStatus;
+    paymentHash: string;
+    preimage: string | null;
+    settledAt: number;
+}
+
+export { type Amount as A, type Charge as C, type FiatOptions as F, type Handover as H, type MedianOptions as M, type Payment as P, type Quote as Q, type Settlement as S, type Ticker as T, type WalletFailure as W, coinmate as a, bitstamp as b, coinbase as c, msatFor as d, type MintedPayment as e, type Msat as f, type PaymentStatus as g, type Priced as h, type SocketTicket as i, type WalletReason as j, kraken as k, type WatchedPayment as l, medianOf as m, fiat as n, msat as o, sats as s };

package/dist/types-BNPmVnA7.d.ts

@@ -0,0 +1,252 @@
+/**
+ * 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>;
+/** How many venues have to agree, how far apart they may be, and how long an answer is held */
+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;
+
+declare const brand: unique symbol;
+/**
+ * A whole number of millisatoshi that came from `sats`, `msat` or `fiat`, and
+ * could not have come from anywhere else.
+ *
+ * The brand is why: a bare number is not one of these, so `21` cannot be passed
+ * where a price is wanted and quietly mean twenty-one thousandths of a satoshi.
+ * It costs nothing at runtime, where the value is an ordinary number
+ */
+type Msat = number & {
+    readonly [brand]: "Msat";
+};
+/**
+ * What a payment is worth. A `Msat` is a price known now, and a function is one
+ * worked out when the invoice is minted, which is what a fiat price has to be.
+ *
+ * Build one with `sats`, `msat` or `fiat`
+ */
+type Amount = Msat | (() => Msat | Promise<Msat>);
+/** How a fiat price is turned into millisatoshi at the moment of minting */
+interface FiatOptions {
+    /**
+     * Where the rate comes from, the median of the four MiCA authorised venues by
+     * default. Pass your own to price off one venue, off your own book, or off a
+     * number you already hold
+     */
+    rate?: Ticker;
+    /**
+     * What you add over the rate, in basis points, none by default. A Lightning
+     * invoice lives an hour and a bank transfer takes days, so a shop pricing in
+     * fiat carries that volatility whether or not it charges for it
+     */
+    spreadBps?: number;
+}
+/** A whole number of satoshi, so `sats(21)` is 21000 millisatoshi */
+declare function sats(whole: number): Msat;
+/** An exact number of millisatoshi, for a price already in the smallest unit */
+declare function msat(exact: number): Msat;
+/**
+ * A price named in fiat, converted when the invoice is minted rather than now.
+ *
+ * Name it as a string and it is read digit by digit, exactly. Name it as a
+ * number and it is rounded to the currency's ISO 4217 minor unit, because
+ * binary floating point cannot hold 4.99 and a payment library that pretends
+ * otherwise moves the wrong amount.
+ *
+ * Every conversion asks the rate afresh, so two calls a second apart can
+ * differ. That is the honest behaviour for a fiat price, and the reason an
+ * amount is a function rather than a number.
+ *
+ * The answer is rounded up to a whole satoshi, because a wallet issues an
+ * invoice in satoshi and refuses a fraction of one. Up rather than down, so the
+ * rounding is never the shop's loss. `msatFor` is the raw conversion, for a rail
+ * that has no invoice to round for
+ */
+declare function fiat(major: number | string, currency: string, options?: FiatOptions): () => Promise<Msat>;
+
+/** Where a payment stands, `paid` is the only status that carries a preimage */
+type PaymentStatus = "pending" | "paid" | "expired";
+interface Reported {
+    id: string;
+    status: PaymentStatus;
+    paymentHash: string;
+    verifyUrl: string;
+    preimage: string | null;
+    expiresAt: number;
+    createdAt: number;
+    /** What the watcher needs and the gateway cannot read, `unseal` opens it */
+    sealed: string | null;
+}
+/**
+ * A payment the gateway minted. It resolved the address itself, so it knows who
+ * is paid, how much, and which invoice says so, and none of the three can be
+ * null here
+ */
+interface MintedPayment extends Reported {
+    kind: "minted";
+    lnAddress: string;
+    amountMsat: number;
+    bolt11: string;
+}
+/**
+ * A payment the gateway was handed rather than asked to mint. It was told a hash,
+ * a URL and an expiry and nothing else, which is the point of `watch`, so the
+ * address, the amount and the invoice are all absent rather than merely unknown
+ */
+interface WatchedPayment extends Reported {
+    kind: "watched";
+    lnAddress: null;
+    amountMsat: null;
+    bolt11: null;
+}
+/**
+ * A payment as the gateway reports it, of either sort. Check `kind` and the
+ * three fields a watched payment does not carry stop being null, so nothing here
+ * needs an assertion to read
+ */
+type Payment = MintedPayment | WatchedPayment;
+/**
+ * Who is paid and how much. `to` is a priority list when it is an array: the
+ * gateway takes the first address that can issue a provable invoice for the
+ * amount and the rest are the fallback
+ */
+interface Charge {
+    paidTo: string | string[];
+    amount: Amount;
+    /** Where the gateway posts the settlement, signed with the key it publishes */
+    webhookUrl?: string;
+}
+/**
+ * A charge with its price settled, which is what a proof compares the gateway's
+ * answer against. Asking a fiat price twice gives two numbers, so the proof is
+ * handed the one that was actually asked for
+ */
+interface Priced {
+    paidTo: string[];
+    amountMsat: number;
+}
+/**
+ * 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 Handover {
+    paymentHash: string;
+    verifyUrl: string;
+    expiresAt: number;
+    /** Groups this payment with every other one carrying the same secret */
+    trigger?: string;
+    /**
+     * How many of this 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;
+    /** Sealed with `seal`, so the gateway stores what it cannot read */
+    sealed?: string;
+    webhookUrl?: string;
+}
+/**
+ * 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[];
+}
+/**
+ * A one minute pass onto one trigger's stream. It opens that trigger and nothing
+ * else, which is what makes it the thing to hand a browser when the trigger
+ * secret is not. `expiresAt` is unix seconds, like every other time here
+ */
+interface SocketTicket {
+    ticket: string;
+    expiresAt: number;
+}
+/** Why one wallet in the list could not be used */
+type WalletReason = "address-unusable" | "unreachable" | "amount-not-accepted" | "cannot-prove-delivery" | "invoice-refused";
+/** One wallet on the list that could not be used, and the reason it could not */
+interface WalletFailure {
+    address: string;
+    reason: WalletReason;
+}
+/**
+ * What a delivery carries. Everything needed to act on a settlement and to check
+ * it, and nothing else, so a retry is the same size every time
+ */
+interface Settlement {
+    id: string;
+    status: PaymentStatus;
+    paymentHash: string;
+    preimage: string | null;
+    settledAt: number;
+}
+
+export { type Amount as A, type Charge as C, type FiatOptions as F, type Handover as H, type MedianOptions as M, type Payment as P, type Quote as Q, type Settlement as S, type Ticker as T, type WalletFailure as W, coinmate as a, bitstamp as b, coinbase as c, msatFor as d, type MintedPayment as e, type Msat as f, type PaymentStatus as g, type Priced as h, type SocketTicket as i, type WalletReason as j, kraken as k, type WatchedPayment as l, medianOf as m, fiat as n, msat as o, sats as s };

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
   title: thunder-bridge, the endpoint your own service serves
-  version: 1.4.2
+  version: 1.5.0
   license:
     name: MIT
     identifier: MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thunder-bridge",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "Trustless JavaScript client for the Thunder Bridge Lightning payment gateway. Proves the invoice came from your own wallet before the payer sees it.",
   "author": "i-am-fatik",
   "homepage": "https://agora.gripe/en/tools/thunder-bridge",
@@ -17,8 +17,17 @@
   "types": "./dist/index.d.ts",
   "typesVersions": {
     "*": {
-      "server": [
-        "./dist/server.d.ts"
+      "qr": [
+        "./dist/qr.d.ts"
+      ],
+      "price": [
+        "./dist/price.d.ts"
+      ],
+      "bank": [
+        "./dist/bank.d.ts"
+      ],
+      "nwc": [
+        "./dist/nwc.d.ts"
       ]
     }
   },
@@ -33,14 +42,44 @@
         "default": "./dist/index.cjs"
       }
     },
-    "./server": {
+    "./qr": {
       "import": {
-        "types": "./dist/server.d.ts",
-        "default": "./dist/server.js"
+        "types": "./dist/qr.d.ts",
+        "default": "./dist/qr.js"
       },
       "require": {
-        "types": "./dist/server.d.cts",
-        "default": "./dist/server.cjs"
+        "types": "./dist/qr.d.cts",
+        "default": "./dist/qr.cjs"
+      }
+    },
+    "./price": {
+      "import": {
+        "types": "./dist/price.d.ts",
+        "default": "./dist/price.js"
+      },
+      "require": {
+        "types": "./dist/price.d.cts",
+        "default": "./dist/price.cjs"
+      }
+    },
+    "./bank": {
+      "import": {
+        "types": "./dist/bank.d.ts",
+        "default": "./dist/bank.js"
+      },
+      "require": {
+        "types": "./dist/bank.d.cts",
+        "default": "./dist/bank.cjs"
+      }
+    },
+    "./nwc": {
+      "import": {
+        "types": "./dist/nwc.d.ts",
+        "default": "./dist/nwc.js"
+      },
+      "require": {
+        "types": "./dist/nwc.d.cts",
+        "default": "./dist/nwc.cjs"
       }
     }
   },
@@ -52,7 +91,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/server.ts --format esm,cjs --dts --clean --splitting=false",
+    "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",