thunder-bridge 0.8.10 → 1.0.0

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

@@ -23,7 +23,6 @@ interface CreatePaymentParams {
     lnAddresses: string[];
     amountMsat: number;
     webhookUrl?: string;
-    webhookSecret?: string;
 }
 /**
  * `lnAddresses` is the same priority list `createPayment` takes, and quoting it
@@ -78,7 +77,6 @@ interface WatchPaymentParams {
     trigger?: string;
     sealed?: string;
     webhookUrl?: string;
-    webhookSecret?: string;
 }
 /** Why one wallet in the list could not be used */
 type WalletReason = "address-unusable" | "unreachable" | "amount-not-accepted" | "cannot-prove-delivery" | "invoice-refused";
@@ -86,6 +84,17 @@ 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;
+}
 
 interface ThunderBridgeOptions {
     /**
@@ -101,6 +110,13 @@ interface ThunderBridgeOptions {
      * through a ticket
      */
     token?: string;
+    /**
+     * The same long lived server side secret your rail derives its preimages from.
+     * Given here, every call carries a signature the gateway reads as your identity,
+     * so a payment you create is handed back to you and to nobody else. Withheld,
+     * you are anonymous and any holder of an id can read what it names
+     */
+    secret?: string;
 }
 interface WaitOptions {
     /** Give up when this aborts, `AbortSignal.timeout(ms)` covers the usual case */
@@ -159,7 +175,9 @@ declare class ThunderBridge {
     private readonly baseUrl;
     private readonly verify;
     private readonly token;
+    private readonly secret;
     private strangers;
+    private speaks;
     constructor(baseUrl: string, options?: ThunderBridgeOptions);
     /**
      * Whether a token was given, which is what makes an instance yours: a gateway
@@ -262,6 +280,14 @@ declare class ThunderBridge {
      * the watcher needs goes in `sealed`, which the gateway cannot read
      */
     watchPayment(params: WatchPaymentParams): Promise<TriggerEvent>;
+    /**
+     * What this payment is called, which you can work out before any gateway has
+     * heard of it. Every gateway you hand the same invoice to answers with the same
+     * name, so watching at several of them adds up to one payment rather than
+     * several, and no gateway's key is in the answer. Null when no secret was given,
+     * because then the gateway names the payment and only it can
+     */
+    nameFor(paymentHash: string): Promise<string | null>;
     /**
      * 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
@@ -272,6 +298,7 @@ declare class ThunderBridge {
     private wsTicket;
     private sending;
     private reading;
+    private speaking;
     private proven;
     private checked;
 }
@@ -324,7 +351,6 @@ interface BankRailConfig {
     /** Up to ten digits, for accounting systems that still want one */
     variableSymbol?: (order: Order) => string | undefined;
     webhookUrl?: string;
-    webhookSecret?: string;
     /** 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 */
@@ -345,7 +371,6 @@ interface LightningRailConfig {
      */
     idempotencyKey?: (order: Order) => string | undefined;
     webhookUrl?: string;
-    webhookSecret?: string;
     /** What `Leg.rail` reads, for a shop running more than one wallet */
     name?: string;
 }
@@ -361,7 +386,6 @@ interface BlindLightningRailConfig {
     /** Only a watched leg has anywhere to carry this */
     sealed?: (order: Order) => string | Promise<string>;
     webhookUrl?: string;
-    webhookSecret?: string;
     /**
      * Where your own `lightningVerifyEndpoint` is mounted, and the secret it
      * unseals with. Set both and the gateway is handed your URL rather than the
@@ -397,4 +421,4 @@ declare function lightningRail(config: LightningRailConfig): Rail;
  */
 declare function blindLightningRail(config: BlindLightningRailConfig): Rail;
 
-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, ThunderBridge as T, type WalletFailure as W, type TriggerEvent as a, type CreateOptions as b, type CreateQuoteParams as c, type LightningRailConfig as d, type PaymentKind as e, type PaymentStatus as f, type ThunderBridgeOptions as g, type WaitOptions as h, type WalletReason as i, type WatchPaymentParams as j, bankRail as k, lightningRail as l, type BlindLightningRailConfig as m, blindLightningRail as n };
+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 };

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

@@ -23,7 +23,6 @@ interface CreatePaymentParams {
     lnAddresses: string[];
     amountMsat: number;
     webhookUrl?: string;
-    webhookSecret?: string;
 }
 /**
  * `lnAddresses` is the same priority list `createPayment` takes, and quoting it
@@ -78,7 +77,6 @@ interface WatchPaymentParams {
     trigger?: string;
     sealed?: string;
     webhookUrl?: string;
-    webhookSecret?: string;
 }
 /** Why one wallet in the list could not be used */
 type WalletReason = "address-unusable" | "unreachable" | "amount-not-accepted" | "cannot-prove-delivery" | "invoice-refused";
@@ -86,6 +84,17 @@ 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;
+}
 
 interface ThunderBridgeOptions {
     /**
@@ -101,6 +110,13 @@ interface ThunderBridgeOptions {
      * through a ticket
      */
     token?: string;
+    /**
+     * The same long lived server side secret your rail derives its preimages from.
+     * Given here, every call carries a signature the gateway reads as your identity,
+     * so a payment you create is handed back to you and to nobody else. Withheld,
+     * you are anonymous and any holder of an id can read what it names
+     */
+    secret?: string;
 }
 interface WaitOptions {
     /** Give up when this aborts, `AbortSignal.timeout(ms)` covers the usual case */
@@ -159,7 +175,9 @@ declare class ThunderBridge {
     private readonly baseUrl;
     private readonly verify;
     private readonly token;
+    private readonly secret;
     private strangers;
+    private speaks;
     constructor(baseUrl: string, options?: ThunderBridgeOptions);
     /**
      * Whether a token was given, which is what makes an instance yours: a gateway
@@ -262,6 +280,14 @@ declare class ThunderBridge {
      * the watcher needs goes in `sealed`, which the gateway cannot read
      */
     watchPayment(params: WatchPaymentParams): Promise<TriggerEvent>;
+    /**
+     * What this payment is called, which you can work out before any gateway has
+     * heard of it. Every gateway you hand the same invoice to answers with the same
+     * name, so watching at several of them adds up to one payment rather than
+     * several, and no gateway's key is in the answer. Null when no secret was given,
+     * because then the gateway names the payment and only it can
+     */
+    nameFor(paymentHash: string): Promise<string | null>;
     /**
      * 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
@@ -272,6 +298,7 @@ declare class ThunderBridge {
     private wsTicket;
     private sending;
     private reading;
+    private speaking;
     private proven;
     private checked;
 }
@@ -324,7 +351,6 @@ interface BankRailConfig {
     /** Up to ten digits, for accounting systems that still want one */
     variableSymbol?: (order: Order) => string | undefined;
     webhookUrl?: string;
-    webhookSecret?: string;
     /** 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 */
@@ -345,7 +371,6 @@ interface LightningRailConfig {
      */
     idempotencyKey?: (order: Order) => string | undefined;
     webhookUrl?: string;
-    webhookSecret?: string;
     /** What `Leg.rail` reads, for a shop running more than one wallet */
     name?: string;
 }
@@ -361,7 +386,6 @@ interface BlindLightningRailConfig {
     /** Only a watched leg has anywhere to carry this */
     sealed?: (order: Order) => string | Promise<string>;
     webhookUrl?: string;
-    webhookSecret?: string;
     /**
      * Where your own `lightningVerifyEndpoint` is mounted, and the secret it
      * unseals with. Set both and the gateway is handed your URL rather than the
@@ -397,4 +421,4 @@ declare function lightningRail(config: LightningRailConfig): Rail;
  */
 declare function blindLightningRail(config: BlindLightningRailConfig): Rail;
 
-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, ThunderBridge as T, type WalletFailure as W, type TriggerEvent as a, type CreateOptions as b, type CreateQuoteParams as c, type LightningRailConfig as d, type PaymentKind as e, type PaymentStatus as f, type ThunderBridgeOptions as g, type WaitOptions as h, type WalletReason as i, type WatchPaymentParams as j, bankRail as k, lightningRail as l, type BlindLightningRailConfig as m, blindLightningRail as n };
+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 };

package/dist/server.cjs

@@ -926,8 +926,7 @@ function blindLightningRail(config) {
       expiresAt: resolved2.expiresAt,
       trigger: config.trigger,
       sealed: await config.sealed?.(order),
-      webhookUrl: config.webhookUrl,
-      webhookSecret: config.webhookSecret
+      webhookUrl: config.webhookUrl
     });
     return {
       id: watched.id,

package/dist/server.d.cts

@@ -1,5 +1,5 @@
-import { T as ThunderBridge } from './rail-J8QoYbSr.cjs';
-export { m as BlindLightningRailConfig, n as blindLightningRail } from './rail-J8QoYbSr.cjs';
+import { T as ThunderBridge } from './rail-CL9QkiHo.cjs';
+export { m as BlindLightningRailConfig, n as blindLightningRail } from './rail-CL9QkiHo.cjs';
 
 interface TriggerConfig {
     /** The gateway that quotes the addresses and mints the invoice */

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { T as ThunderBridge } from './rail-J8QoYbSr.js';
-export { m as BlindLightningRailConfig, n as blindLightningRail } from './rail-J8QoYbSr.js';
+import { T as ThunderBridge } from './rail-CL9QkiHo.js';
+export { m as BlindLightningRailConfig, n as blindLightningRail } from './rail-CL9QkiHo.js';
 
 interface TriggerConfig {
     /** The gateway that quotes the addresses and mints the invoice */

package/dist/server.js

@@ -887,8 +887,7 @@ function blindLightningRail(config) {
       expiresAt: resolved2.expiresAt,
       trigger: config.trigger,
       sealed: await config.sealed?.(order),
-      webhookUrl: config.webhookUrl,
-      webhookSecret: config.webhookSecret
+      webhookUrl: config.webhookUrl
     });
     return {
       id: watched.id,

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
   title: thunder-bridge, the endpoint your own service serves
-  version: 0.8.1
+  version: 1.0.0
   license:
     name: MIT
     identifier: MIT
@@ -207,6 +207,48 @@ paths:
               schema:
                 $ref: "#/components/schemas/unsettled"
 
+    post:
+      tags: [bank-transfer]
+      operationId: answerVerifyChallenge
+      summary: Agree to be polled, before the gateway will watch anything pointed here
+      description: |
+        The gateway will not poll a URL a caller merely named. It POSTs a nonce here first and
+        watches nothing unless this endpoint hands the same nonce back, which is how a caller
+        shows the endpoint consented to the traffic rather than being volunteered for it. A
+        registration whose verify URL will not answer is refused with `verify-unconsented`.
+
+        Every verify endpoint the SDK builds answers this as its first line, before it parses
+        its own query, so `bankVerifyEndpoint`, `lightningVerifyEndpoint` and anything wrapping
+        `answerVerifyChallengeRequest` already do it.
+
+        There is nothing to sign. Echoing a nonce grants the asker nothing, so this holds no
+        secret and checks none.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                type:
+                  type: string
+                  enum: [verify-challenge]
+                nonce:
+                  type: string
+                  pattern: "^[0-9a-f]{64}$"
+              required: [type, nonce]
+      responses:
+        "200":
+          description: The same nonce, and nothing else.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  nonce:
+                    type: string
+                required: [nonce]
+
 components:
   schemas:
     settlement:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thunder-bridge",
-  "version": "0.8.10",
+  "version": "1.0.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",