thunder-bridge 0.8.1 → 0.8.3

package/README.md

@@ -12,10 +12,11 @@ amount you asked for rather than the amount the gateway echoed back, and its
 settlement proof url belongs to the recipient. A gateway that substitutes an
 invoice is caught before a payer sees a QR code.
 
-Lightning is the rail it was built for, not the only one it can prove.
-`bankTransfer` derives a preimage and hands the gateway its hash, which puts money
-landing in a bank account behind the same watch and the same proof. `Statement` is
-the seam a bank plugs into and `fioStatement` is the first one.
+Lightning is the rail it was built for, not the only one it can prove. A bank
+transfer has no preimage, so `bankTransfer` derives one and hands the gateway its
+hash, which puts money arriving in a bank account behind the same watch, the same
+poll and the same proof. `Statement` is where a bank plugs in and `fioStatement`
+is the first one.
 
 It touches only `fetch`, `crypto.subtle`, `URL` and `WebSocket`, so it runs in
 Node, Bun, Deno, Cloudflare Workers and the browser. The gateway it talks to is
@@ -36,7 +37,7 @@ CORS open, so the proof fetches work from a browser too.
 ```ts
 import { ThunderBridge, invoiceToSvg, type CreatePaymentParams } from "thunder-bridge";
 
-const gateway = new ThunderBridge("https://thunder-bridge-direct-production.up.railway.app");
+const gateway = new ThunderBridge("https://thunder-bridge-production.up.railway.app");
 
 const request: CreatePaymentParams = {
   lnAddresses: ["alice@coinos.io", "alice@getalby.com"],
@@ -105,18 +106,39 @@ them and this table does not repeat them.
 
 | Export | What it does |
 |---|---|
-| `lnurlPayEndpoint(config)` | a whole LNURL-pay endpoint as one Fetch handler, so a static QR points at your domain |
-| `bankTransfer(params)` | register a Czech QR platba as a watched payment. Refuses a gateway with no token |
-| `bankVerifyEndpoint(config)` | the other half, the LUD-21 shape backed by your own statement |
-| `fioStatement(config)` | a `Statement` reading a Fio account, several tokens used strictly in turn |
+| `lnurlPayEndpoint(config)` | a whole LNURL-pay endpoint as one Fetch handler, so a static QR points at your domain. From `thunder-bridge/server` |
 | `seal(secret, plaintext)`, `unseal` | the blob the gateway stores and cannot read |
 | `toLnurl(url)` | bech32-encode an endpoint url |
+| `bankTransfer(params)` | register a Czech QR platba as a watched payment. Refuses a gateway that serves strangers |
+| `bankVerifyEndpoint(config)` | the other half, the LUD-21 shape backed by your own statement |
+| `fioStatement(config)` | a `Statement` reading a Fio account, several tokens used strictly in turn |
+
+What your service answers once those handlers are mounted is written out in
+[`openapi.yaml`](openapi.yaml), shipped with this package.
 
 `Statement` is a plain `(sinceUnix) => Promise<Credit[]>`, so another bank is
 another function of that shape and persistence wraps it from outside rather than
 living inside it. Nothing above it changes, and the package stays ignorant of
 whatever runtime you keep state in.
 
+**One shape for every payment method** - [`src/rail.ts`](src/rail.ts)
+
+| Export | What it does |
+|---|---|
+| `bankRail(config)` | a `Rail` selling for a bank transfer, reading back through any `Statement` |
+| `lightningRail(config)` | a `Rail` where the gateway mints the invoice, so it learns the address and the amount |
+| `blindLightningRail(config)` | a `Rail` that resolves the address itself and tells the gateway only a hash. From `thunder-bridge/server` |
+
+`Rail` is `(order: Order) => Promise<Leg>`. 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: a reference, an amount in minor units and a currency. A `Leg` reads
+the same whichever rail made it, which is what lets `firstToSettle` take a mixed
+list without being told what is in it.
+
+The gateway is already indifferent to all of this. It holds a payment hash, polls
+a verify URL and reports what came back, so a rail is an SDK-side arrangement of
+calls the gateway already answers, not a plugin it has to load.
+
 **Pricing a fiat order** - [`src/price.ts`](src/price.ts), [`src/currency.ts`](src/currency.ts)
 
 | Export | What it does |
@@ -129,10 +151,12 @@ whatever runtime you keep state in.
 **QR codes** - [`src/qr.ts`](src/qr.ts)
 
 Every renderer returns a string, so they work on a server, in a worker and in a
-browser with no canvas involved. `invoiceToSvg` takes an invoice or a lightning
-address, `lnurlToSvg` takes your own endpoint url, `spdToSvg` takes the `spd` from
-`bankTransfer`. Each has a `…ToDataUrl` twin for an `<img>` `src`. A BOLT12 offer
-is not handled, because this gateway never returns one.
+browser with no canvas involved. `qrToSvg` takes any rail's `Leg.qr` and needs to
+know nothing else, because a rail states its own payload. Below it sit the
+format-named ones for calling directly: `invoiceToSvg` takes an invoice or a
+lightning address, `lnurlToSvg` takes your own endpoint url, `spdToSvg` takes a
+Short Payment Descriptor. Each has a `…ToDataUrl` twin for an `<img>` `src`. A
+BOLT12 offer is not handled, because this gateway never returns one.
 
 ```ts
 import { invoiceToSvg, lnurlToSvg } from "thunder-bridge";