thunder-bridge 1.0.0 → 1.3.0

package/dist/{rail-CL9QkiHo.d.cts → rail-DZzlN-bi.d.cts}

@@ -1,3 +1,17 @@
+type Resolved = {
+    address: string;
+    bolt11: string;
+    verifyUrl: string;
+    paymentHash: string;
+    expiresAt: number;
+};
+/**
+ * Bech32-encode a pay endpoint as the `LNURL1` string LUD-01 defines, uppercase
+ * because that is the form it asks a QR to carry. An onion endpoint is http
+ * rather than https, which LUD-17 spells out, so both are taken here
+ */
+declare function toLnurl(endpoint: string): string;
+
 /** Where a payment stands, `paid` is the only status that carries a preimage */
 type PaymentStatus = "pending" | "paid" | "expired";
 /** Whether the gateway resolved the address and got the invoice, or was handed one to watch */
@@ -75,6 +89,12 @@ interface WatchPaymentParams {
     verifyUrl: string;
     expiresAt: number;
     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?: string;
     webhookUrl?: string;
 }
@@ -147,10 +167,22 @@ interface CreateOptions {
      * from any URL a payer sees
      */
     trigger?: string;
+    /**
+     * How many of the 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;
 }
 interface FollowOptions {
     /** Called for the recent settlements replayed on connect, then for each new one */
     onPayment: (settled: TriggerEvent) => void;
+    /**
+     * How many settlements to ask for on connect, defaults to the gateway's ten.
+     * It hands back what it still holds, which is the last hour unless the
+     * payments were minted with `replay`
+     */
+    replay?: number;
     /** 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 */
@@ -303,6 +335,88 @@ declare class ThunderBridge {
     private checked;
 }
 
+/** A wallet reachable over NIP-47, as its `nostr+walletconnect://` URI describes it */
+interface NwcConnection {
+    /** The wallet service's public key, which is what its answers have to be signed by */
+    walletPubkey: string;
+    /** Where to reach it, tried in order until one answers */
+    relays: string[];
+    /** Our own private key on this connection, and the only thing that authorises it */
+    secret: string;
+}
+/** A minted invoice and everything needed to watch it */
+interface NwcInvoice {
+    bolt11: string;
+    paymentHash: string;
+    expiresAt: number;
+}
+interface NwcVerifyConfig {
+    /** The wallet this endpoint speaks for. It never leaves this process */
+    connection: NwcConnection;
+    /** The secret the payment hash was sealed with, and nothing else uses it */
+    secret: string;
+    /** How often the gateway should ask, in seconds, sent as `Cache-Control: max-age`, `5` by default */
+    pollEverySecs?: number;
+    /** How long one `lookup_invoice` may take before the wallet counts as unreachable, `10_000` by default */
+    askTimeoutMs?: number;
+}
+/**
+ * Read a `nostr+walletconnect://` URI. Refuses a relay that is not `wss`, for the
+ * reason the gateway refuses a verify URL that is not https
+ */
+declare function nwcConnection(uri: string): NwcConnection;
+/** Mint an invoice on the connected wallet, decoded so the caller need not trust its word */
+declare function nwcInvoice(connection: NwcConnection, amountMsat: number, description: string, timeoutMs?: number): Promise<NwcInvoice>;
+/**
+ * Mint a hold invoice on a hash the wallet does not hold the preimage for, which
+ * is what lets an operator be paid only by paying somebody else first. The hash
+ * has to come from the recipient's own invoice, and the invoice that comes back
+ * is decoded rather than believed
+ */
+declare function nwcHoldInvoice(connection: NwcConnection, held: {
+    paymentHash: string;
+    amountMsat: number;
+    description: string;
+    expirySecs: number;
+    minCltvExpiryDelta?: number;
+}, timeoutMs?: number): Promise<NwcInvoice>;
+/**
+ * The preimage the wallet released for this hash, null while it has released
+ * none. A preimage that does not hash to what was asked for is a lie rather than
+ * an answer, so it throws instead of being passed on
+ */
+declare function nwcSettlement(connection: NwcConnection, paymentHash: string, timeoutMs?: number): Promise<string | null>;
+/**
+ * Pay an invoice and keep the preimage the network handed back. Whoever pays
+ * learns it, which is what makes delivery provable to a recipient publishing no
+ * LUD-21 of their own. A preimage that does not hash to the invoice's own hash is
+ * a lie rather than a receipt, so it throws instead of being passed on
+ */
+declare function nwcPay(connection: NwcConnection, bolt11: string, timeoutMs?: number): Promise<string>;
+/**
+ * A verify endpoint of your own that asks your wallet over NIP-47, so the gateway
+ * polls you and never learns the connection, the relay, or which wallet it is.
+ *
+ * `nwcVerifyUrl` seals the payment hash into the query with your secret, which is
+ * what stops a stranger driving your wallet through this handler. It answers the
+ * LUD-21 shape the gateway already speaks, so nothing on that side changes.
+ *
+ * A wallet it cannot reach answers `502` rather than "not settled", because those
+ * are different claims and only one of them is true.
+ */
+declare function nwcVerifyEndpoint(config: NwcVerifyConfig): (request: Request) => Promise<Response>;
+/**
+ * The URL to hand the gateway, with the payment hash sealed inside it. Point it at
+ * wherever `nwcVerifyEndpoint` is mounted
+ */
+declare function nwcVerifyUrl(endpoint: string, paymentHash: string, secret: string): Promise<string>;
+/**
+ * One NIP-47 call, for a method this SDK does not wrap. The wallet's own info
+ * event lists what it will answer, and anything it refuses comes back as a
+ * `WalletRefused` carrying the code it named
+ */
+declare function askWallet(connection: NwcConnection, method: string, params: Record<string, unknown>, timeoutMs?: number): Promise<Record<string, unknown>>;
+
 /** 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 */
@@ -346,6 +460,8 @@ interface BankRailConfig {
     expiresAt: (order: Order) => number;
     /** Groups every leg on the same secret, so one `followTrigger` socket hears them all */
     trigger?: string;
+    /** How many settlements of that trigger the gateway keeps replayable past the hour, needs `trigger` */
+    replay?: number;
     /** 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 */
@@ -365,6 +481,8 @@ interface LightningRailConfig {
     amountMsat: (order: Order) => number | Promise<number>;
     /** Groups every leg on the same secret, so one `followTrigger` socket hears them all */
     trigger?: string;
+    /** How many settlements of that trigger the gateway keeps replayable past the hour, needs `trigger` */
+    replay?: number;
     /**
      * 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
@@ -383,6 +501,8 @@ interface BlindLightningRailConfig {
     amountMsat: (order: Order) => number | Promise<number>;
     /** Groups every leg on the same secret, so one `followTrigger` socket hears them all */
     trigger?: string;
+    /** How many settlements of that trigger the gateway keeps replayable past the hour, needs `trigger` */
+    replay?: number;
     /** Only a watched leg has anywhere to carry this */
     sealed?: (order: Order) => string | Promise<string>;
     webhookUrl?: string;
@@ -399,6 +519,34 @@ interface BlindLightningRailConfig {
     /** What `Leg.rail` reads, for a shop running more than one wallet */
     name?: string;
 }
+interface NwcRailConfig {
+    /** The gateway that watches an invoice your own wallet minted */
+    gateway: ThunderBridge;
+    /** Your wallet over NIP-47, from `nwcConnection`. It never reaches the gateway */
+    connection: NwcConnection;
+    /** What this order costs in millisatoshi */
+    amountMsat: (order: Order) => number | Promise<number>;
+    /**
+     * Where your own `nwcVerifyEndpoint` is mounted, and the secret it unseals
+     * with. The gateway is handed this URL rather than a wallet's, so it polls you
+     * and learns neither the connection nor which wallet is behind it
+     */
+    verifyThrough: {
+        endpoint: string;
+        secret: string;
+    };
+    /** What the payer reads on the invoice, and what your wallet files it under */
+    description?: (order: Order) => string;
+    /** Groups every leg on the same secret, so one `followTrigger` socket hears them all */
+    trigger?: string;
+    /** How many settlements of that trigger the gateway keeps replayable past the hour, needs `trigger` */
+    replay?: number;
+    /** Only a watched leg has anywhere to carry this */
+    sealed?: (order: Order) => string | Promise<string>;
+    webhookUrl?: 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.
@@ -420,5 +568,22 @@ declare function lightningRail(config: LightningRailConfig): Rail;
  * refusing everyone.
  */
 declare function blindLightningRail(config: BlindLightningRailConfig): Rail;
+/**
+ * Sell for Lightning against a wallet of your own over NIP-47, for a wallet that
+ * has no LUD-21 address to be watched at. Your node mints the invoice and releases
+ * the preimage, so the proof comes from one hop nearer than any hosted address can
+ * manage, and the gateway sees a hash and a URL of yours.
+ */
+declare function nwcRail(config: NwcRailConfig): Rail;
+/**
+ * A provable invoice from the first address on the list that will issue one, which
+ * is what a client mints for itself rather than asking a gateway to. Everything the
+ * gateway needs to watch it comes back with everything you need to prove it came
+ * from the address you asked for, so you can hand over the first and keep the second.
+ *
+ * Server side: it resolves hostnames and refuses a private one, which no browser can
+ * do. Throws `NoWalletAvailableError` when no address on the list would serve
+ */
+declare function invoiceFrom(lnAddresses: string[], amountMsat: number): Promise<Resolved>;
 
-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, type Settlement as S, ThunderBridge as T, type WatchPaymentParams as W, type ThunderBridgeOptions as a, type TriggerEvent as b, type WaitOptions as c, type WalletFailure as d, type CreateOptions as e, type CreateQuoteParams as f, type LightningRailConfig as g, type PaymentKind as h, type PaymentStatus as i, type WalletReason as j, bankRail as k, lightningRail as l, type BlindLightningRailConfig as m, blindLightningRail as n };
+export { nwcSettlement as A, type BankRailConfig as B, type CreatePaymentParams as C, nwcVerifyEndpoint as D, nwcVerifyUrl as E, type FollowOptions as F, type Leg as L, type NwcConnection as N, type Order as O, type Payment as P, type Quote as Q, type Rail as R, type Settlement as S, ThunderBridge as T, type WalletFailure as W, type ThunderBridgeOptions as a, type WatchPaymentParams as b, type TriggerEvent as c, type WaitOptions as d, type CreateOptions as e, type CreateQuoteParams as f, type LightningRailConfig as g, type PaymentKind as h, type PaymentStatus as i, type WalletReason as j, bankRail as k, lightningRail as l, type BlindLightningRailConfig as m, type NwcInvoice as n, type NwcRailConfig as o, type NwcVerifyConfig as p, type Resolved as q, askWallet as r, blindLightningRail as s, toLnurl as t, invoiceFrom as u, nwcConnection as v, nwcHoldInvoice as w, nwcInvoice as x, nwcPay as y, nwcRail as z };

package/dist/{rail-CL9QkiHo.d.ts → rail-DZzlN-bi.d.ts}

@@ -1,3 +1,17 @@
+type Resolved = {
+    address: string;
+    bolt11: string;
+    verifyUrl: string;
+    paymentHash: string;
+    expiresAt: number;
+};
+/**
+ * Bech32-encode a pay endpoint as the `LNURL1` string LUD-01 defines, uppercase
+ * because that is the form it asks a QR to carry. An onion endpoint is http
+ * rather than https, which LUD-17 spells out, so both are taken here
+ */
+declare function toLnurl(endpoint: string): string;
+
 /** Where a payment stands, `paid` is the only status that carries a preimage */
 type PaymentStatus = "pending" | "paid" | "expired";
 /** Whether the gateway resolved the address and got the invoice, or was handed one to watch */
@@ -75,6 +89,12 @@ interface WatchPaymentParams {
     verifyUrl: string;
     expiresAt: number;
     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?: string;
     webhookUrl?: string;
 }
@@ -147,10 +167,22 @@ interface CreateOptions {
      * from any URL a payer sees
      */
     trigger?: string;
+    /**
+     * How many of the 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;
 }
 interface FollowOptions {
     /** Called for the recent settlements replayed on connect, then for each new one */
     onPayment: (settled: TriggerEvent) => void;
+    /**
+     * How many settlements to ask for on connect, defaults to the gateway's ten.
+     * It hands back what it still holds, which is the last hour unless the
+     * payments were minted with `replay`
+     */
+    replay?: number;
     /** 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 */
@@ -303,6 +335,88 @@ declare class ThunderBridge {
     private checked;
 }
 
+/** A wallet reachable over NIP-47, as its `nostr+walletconnect://` URI describes it */
+interface NwcConnection {
+    /** The wallet service's public key, which is what its answers have to be signed by */
+    walletPubkey: string;
+    /** Where to reach it, tried in order until one answers */
+    relays: string[];
+    /** Our own private key on this connection, and the only thing that authorises it */
+    secret: string;
+}
+/** A minted invoice and everything needed to watch it */
+interface NwcInvoice {
+    bolt11: string;
+    paymentHash: string;
+    expiresAt: number;
+}
+interface NwcVerifyConfig {
+    /** The wallet this endpoint speaks for. It never leaves this process */
+    connection: NwcConnection;
+    /** The secret the payment hash was sealed with, and nothing else uses it */
+    secret: string;
+    /** How often the gateway should ask, in seconds, sent as `Cache-Control: max-age`, `5` by default */
+    pollEverySecs?: number;
+    /** How long one `lookup_invoice` may take before the wallet counts as unreachable, `10_000` by default */
+    askTimeoutMs?: number;
+}
+/**
+ * Read a `nostr+walletconnect://` URI. Refuses a relay that is not `wss`, for the
+ * reason the gateway refuses a verify URL that is not https
+ */
+declare function nwcConnection(uri: string): NwcConnection;
+/** Mint an invoice on the connected wallet, decoded so the caller need not trust its word */
+declare function nwcInvoice(connection: NwcConnection, amountMsat: number, description: string, timeoutMs?: number): Promise<NwcInvoice>;
+/**
+ * Mint a hold invoice on a hash the wallet does not hold the preimage for, which
+ * is what lets an operator be paid only by paying somebody else first. The hash
+ * has to come from the recipient's own invoice, and the invoice that comes back
+ * is decoded rather than believed
+ */
+declare function nwcHoldInvoice(connection: NwcConnection, held: {
+    paymentHash: string;
+    amountMsat: number;
+    description: string;
+    expirySecs: number;
+    minCltvExpiryDelta?: number;
+}, timeoutMs?: number): Promise<NwcInvoice>;
+/**
+ * The preimage the wallet released for this hash, null while it has released
+ * none. A preimage that does not hash to what was asked for is a lie rather than
+ * an answer, so it throws instead of being passed on
+ */
+declare function nwcSettlement(connection: NwcConnection, paymentHash: string, timeoutMs?: number): Promise<string | null>;
+/**
+ * Pay an invoice and keep the preimage the network handed back. Whoever pays
+ * learns it, which is what makes delivery provable to a recipient publishing no
+ * LUD-21 of their own. A preimage that does not hash to the invoice's own hash is
+ * a lie rather than a receipt, so it throws instead of being passed on
+ */
+declare function nwcPay(connection: NwcConnection, bolt11: string, timeoutMs?: number): Promise<string>;
+/**
+ * A verify endpoint of your own that asks your wallet over NIP-47, so the gateway
+ * polls you and never learns the connection, the relay, or which wallet it is.
+ *
+ * `nwcVerifyUrl` seals the payment hash into the query with your secret, which is
+ * what stops a stranger driving your wallet through this handler. It answers the
+ * LUD-21 shape the gateway already speaks, so nothing on that side changes.
+ *
+ * A wallet it cannot reach answers `502` rather than "not settled", because those
+ * are different claims and only one of them is true.
+ */
+declare function nwcVerifyEndpoint(config: NwcVerifyConfig): (request: Request) => Promise<Response>;
+/**
+ * The URL to hand the gateway, with the payment hash sealed inside it. Point it at
+ * wherever `nwcVerifyEndpoint` is mounted
+ */
+declare function nwcVerifyUrl(endpoint: string, paymentHash: string, secret: string): Promise<string>;
+/**
+ * One NIP-47 call, for a method this SDK does not wrap. The wallet's own info
+ * event lists what it will answer, and anything it refuses comes back as a
+ * `WalletRefused` carrying the code it named
+ */
+declare function askWallet(connection: NwcConnection, method: string, params: Record<string, unknown>, timeoutMs?: number): Promise<Record<string, unknown>>;
+
 /** 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 */
@@ -346,6 +460,8 @@ interface BankRailConfig {
     expiresAt: (order: Order) => number;
     /** Groups every leg on the same secret, so one `followTrigger` socket hears them all */
     trigger?: string;
+    /** How many settlements of that trigger the gateway keeps replayable past the hour, needs `trigger` */
+    replay?: number;
     /** 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 */
@@ -365,6 +481,8 @@ interface LightningRailConfig {
     amountMsat: (order: Order) => number | Promise<number>;
     /** Groups every leg on the same secret, so one `followTrigger` socket hears them all */
     trigger?: string;
+    /** How many settlements of that trigger the gateway keeps replayable past the hour, needs `trigger` */
+    replay?: number;
     /**
      * 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
@@ -383,6 +501,8 @@ interface BlindLightningRailConfig {
     amountMsat: (order: Order) => number | Promise<number>;
     /** Groups every leg on the same secret, so one `followTrigger` socket hears them all */
     trigger?: string;
+    /** How many settlements of that trigger the gateway keeps replayable past the hour, needs `trigger` */
+    replay?: number;
     /** Only a watched leg has anywhere to carry this */
     sealed?: (order: Order) => string | Promise<string>;
     webhookUrl?: string;
@@ -399,6 +519,34 @@ interface BlindLightningRailConfig {
     /** What `Leg.rail` reads, for a shop running more than one wallet */
     name?: string;
 }
+interface NwcRailConfig {
+    /** The gateway that watches an invoice your own wallet minted */
+    gateway: ThunderBridge;
+    /** Your wallet over NIP-47, from `nwcConnection`. It never reaches the gateway */
+    connection: NwcConnection;
+    /** What this order costs in millisatoshi */
+    amountMsat: (order: Order) => number | Promise<number>;
+    /**
+     * Where your own `nwcVerifyEndpoint` is mounted, and the secret it unseals
+     * with. The gateway is handed this URL rather than a wallet's, so it polls you
+     * and learns neither the connection nor which wallet is behind it
+     */
+    verifyThrough: {
+        endpoint: string;
+        secret: string;
+    };
+    /** What the payer reads on the invoice, and what your wallet files it under */
+    description?: (order: Order) => string;
+    /** Groups every leg on the same secret, so one `followTrigger` socket hears them all */
+    trigger?: string;
+    /** How many settlements of that trigger the gateway keeps replayable past the hour, needs `trigger` */
+    replay?: number;
+    /** Only a watched leg has anywhere to carry this */
+    sealed?: (order: Order) => string | Promise<string>;
+    webhookUrl?: 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.
@@ -420,5 +568,22 @@ declare function lightningRail(config: LightningRailConfig): Rail;
  * refusing everyone.
  */
 declare function blindLightningRail(config: BlindLightningRailConfig): Rail;
+/**
+ * Sell for Lightning against a wallet of your own over NIP-47, for a wallet that
+ * has no LUD-21 address to be watched at. Your node mints the invoice and releases
+ * the preimage, so the proof comes from one hop nearer than any hosted address can
+ * manage, and the gateway sees a hash and a URL of yours.
+ */
+declare function nwcRail(config: NwcRailConfig): Rail;
+/**
+ * A provable invoice from the first address on the list that will issue one, which
+ * is what a client mints for itself rather than asking a gateway to. Everything the
+ * gateway needs to watch it comes back with everything you need to prove it came
+ * from the address you asked for, so you can hand over the first and keep the second.
+ *
+ * Server side: it resolves hostnames and refuses a private one, which no browser can
+ * do. Throws `NoWalletAvailableError` when no address on the list would serve
+ */
+declare function invoiceFrom(lnAddresses: string[], amountMsat: number): Promise<Resolved>;
 
-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, type Settlement as S, ThunderBridge as T, type WatchPaymentParams as W, type ThunderBridgeOptions as a, type TriggerEvent as b, type WaitOptions as c, type WalletFailure as d, type CreateOptions as e, type CreateQuoteParams as f, type LightningRailConfig as g, type PaymentKind as h, type PaymentStatus as i, type WalletReason as j, bankRail as k, lightningRail as l, type BlindLightningRailConfig as m, blindLightningRail as n };
+export { nwcSettlement as A, type BankRailConfig as B, type CreatePaymentParams as C, nwcVerifyEndpoint as D, nwcVerifyUrl as E, type FollowOptions as F, type Leg as L, type NwcConnection as N, type Order as O, type Payment as P, type Quote as Q, type Rail as R, type Settlement as S, ThunderBridge as T, type WalletFailure as W, type ThunderBridgeOptions as a, type WatchPaymentParams as b, type TriggerEvent as c, type WaitOptions as d, type CreateOptions as e, type CreateQuoteParams as f, type LightningRailConfig as g, type PaymentKind as h, type PaymentStatus as i, type WalletReason as j, bankRail as k, lightningRail as l, type BlindLightningRailConfig as m, type NwcInvoice as n, type NwcRailConfig as o, type NwcVerifyConfig as p, type Resolved as q, askWallet as r, blindLightningRail as s, toLnurl as t, invoiceFrom as u, nwcConnection as v, nwcHoldInvoice as w, nwcInvoice as x, nwcPay as y, nwcRail as z };