thunder-bridge 0.8.9 → 1.0.0

package/dist/index.d.cts

@@ -1,5 +1,45 @@
-import { T as ThunderBridge, P as Payment, C as CreatePaymentParams, a as TriggerEvent, W as WalletFailure } from './rail-J8QoYbSr.cjs';
-export { B as BankRailConfig, b as CreateOptions, c as CreateQuoteParams, F as FollowOptions, L as Leg, d as LightningRailConfig, O as Order, e as PaymentKind, f as PaymentStatus, Q as Quote, R as Rail, g as ThunderBridgeOptions, h as WaitOptions, i as WalletReason, j as WatchPaymentParams, k as bankRail, l as lightningRail } from './rail-J8QoYbSr.cjs';
+import { T as ThunderBridge, a as ThunderBridgeOptions, W as WatchPaymentParams, b as TriggerEvent, c as WaitOptions, P as Payment, C as CreatePaymentParams, S as Settlement, d as WalletFailure } from './rail-CL9QkiHo.cjs';
+export { B as BankRailConfig, e as CreateOptions, f as CreateQuoteParams, F as FollowOptions, L as Leg, g as LightningRailConfig, O as Order, h as PaymentKind, i as PaymentStatus, Q as Quote, R as Rail, j as WalletReason, k as bankRail, l as lightningRail } from './rail-CL9QkiHo.cjs';
+
+interface GatewaysOptions extends ThunderBridgeOptions {
+    /**
+     * Called for each gateway that would not take the watch, with the url and what
+     * it said. Registering at three and having one refuse still leaves you watched,
+     * so this is how you find out you are less covered than you asked to be, rather
+     * than finding out when the one that took it goes away
+     */
+    onRefused?: (baseUrl: string, refusal: unknown) => void;
+}
+/**
+ * The same payment watched at several gateways at once, which is what makes any
+ * one of them replaceable. They all answer with the same name for it, because a
+ * payment is named after the caller and not after any gateway, so the first
+ * delivery to arrive is the answer and the rest are the same news twice.
+ *
+ * For watching only. Two gateways asked to mint would fetch two different invoices
+ * from the wallet and only one of them could ever be paid
+ */
+declare class Gateways {
+    readonly each: readonly ThunderBridge[];
+    private readonly urls;
+    private readonly onRefused;
+    constructor(baseUrls: string[], options?: GatewaysOptions);
+    /** What this payment is called, which every gateway here will agree on */
+    nameFor(paymentHash: string): Promise<string | null>;
+    /**
+     * Hand the same invoice to every gateway. Throws only when none of them took it,
+     * carrying the first refusal, because one gateway that agreed is enough to be
+     * watched
+     */
+    watchPayment(params: WatchPaymentParams): Promise<TriggerEvent>;
+    /**
+     * Wait for whichever gateway speaks first. A settlement from any of them is the
+     * settlement, and each has already proved the preimage against the hash before
+     * saying so. When they all end without a payment, the first ending is the answer,
+     * and when they all fail, the first failure is thrown
+     */
+    waitForWatched(id: string, options?: WaitOptions): Promise<TriggerEvent>;
+}
 
 /**
  * Encrypt what the watcher needs and the gateway must not have. The gateway
@@ -71,8 +111,6 @@ interface BankTransferParams {
      * a transfer is only ever learned by following the trigger or asking
      */
     webhookUrl?: string;
-    /** Signs that delivery, so `verifyWebhookSignature` can tell it came from the gateway */
-    webhookSecret?: 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
@@ -346,11 +384,12 @@ type WebhookOptions = {
     toleranceSecs?: number;
 };
 /**
- * What checks a delivery. A string is the `webhook.secret` you registered. Pass
- * `{ publicKey }` instead, the hex from the gateway's `/webhook-key`, when you
- * registered no secret and would rather it held nothing of yours
+ * What checks a delivery: the hex the gateway publishes at `/webhook-key`. There
+ * is no shared secret to register, so a gateway holds nothing of yours. Rotating
+ * its cluster key rotates this too, so a signature that stops verifying is a
+ * reason to read the key again before it is a reason to distrust the gateway
  */
-type WebhookCredential = string | {
+type WebhookCredential = {
     publicKey: string;
 };
 /** Verify the `X-Signature` header against the raw body and the `X-Timestamp` that came with it */
@@ -370,6 +409,20 @@ declare function parseWebhookRequest(request: Request, credential: WebhookCreden
 declare function parseWatchedWebhook(body: string | Uint8Array, signature: string, credential: WebhookCredential, timestamp: string, options?: WebhookOptions): Promise<TriggerEvent | null>;
 /** `parseWatchedWebhook` from a Fetch API `Request`, the way `parseWebhookRequest` is */
 declare function parseWatchedWebhookRequest(request: Request, credential: WebhookCredential, options?: WebhookOptions): Promise<TriggerEvent | null>;
+/**
+ * Verify a delivery and read the settlement out of it. Null on a bad signature or
+ * on a body that is not a settlement, so a handler that gets null did not just
+ * miss a payment, it was handed something it had no reason to believe
+ */
+declare function parseSettlement(body: string | Uint8Array, signature: string, credential: WebhookCredential, timestamp: string, options?: WebhookOptions): Promise<Settlement | null>;
+/** {@link parseSettlement} from a Fetch API `Request` */
+declare function parseSettlementRequest(request: Request, credential: WebhookCredential, options?: WebhookOptions): Promise<Settlement | null>;
+/**
+ * Whether a delivery proves what it claims, which is the only question that
+ * matters about one: it says paid and it carries a preimage that hashes to the
+ * payment hash the delivery itself names
+ */
+declare function isProvablySettled(settled: Settlement): boolean;
 /**
  * Answer the one challenge the gateway sends before it will watch a payment your
  * webhook is registered on. Returns the body to send back with a 200, or null when
@@ -398,7 +451,7 @@ declare function answerVerifyChallengeRequest(request: Request): Promise<Respons
  * The way a gateway was caught out, every code is a check that held against the
  * recipient's own server and failed against what the gateway returned
  */
-type GatewayCheatCode = "address_not_requested" | "hash_mismatch" | "amount_mismatch" | "description_hash_mismatch" | "verify_url_foreign" | "invoice_not_issued" | "preimage_mismatch";
+type GatewayCheatCode = "address_not_requested" | "hash_mismatch" | "amount_mismatch" | "description_hash_mismatch" | "verify_url_foreign" | "invoice_not_issued" | "preimage_mismatch" | "id_not_mine";
 /**
  * Thrown when the gateway demonstrably misbehaved, the invoice it returned is
  * not the one the address you asked for issued, or a settlement it reported
@@ -470,4 +523,4 @@ declare class NoWalletAvailableError extends ProblemError {
     }, wallets: WalletFailure[]);
 }
 
-export { type BankTransfer, type BankTransferParams, type BankVerifyConfig, CreatePaymentParams, type Credit, type FioConfig, type GatewayCheatCode, GatewayCheatError, IDEMPOTENCY_KEY_REUSED, type IdempotencyConflict, IdempotencyConflictError, type Invoice, type MedianOptions, NO_WALLET_AVAILABLE, NoWalletAvailableError, PAYMENT_ALREADY_WATCHED, Payment, ProblemError, type QrOptions, REQUEST_IN_FLIGHT, type Statement, ThunderBridge, type Ticker, TriggerEvent, UnverifiedRecipientError, WalletFailure, type WebhookCredential, type WebhookOptions, answerVerifyChallenge, answerVerifyChallengeRequest, answerWebhookChallenge, answerWebhookChallengeRequest, bankTransfer, bankVerifyEndpoint, bitstamp, coinbase, coinmate, decodeInvoice, fioStatement, invoiceToDataUrl, invoiceToSvg, isProblemType, isProvablyPaid, kraken, lnurlToDataUrl, lnurlToSvg, medianOf, minorScaleOf, minorUnitsOf, msatFor, parseWatchedWebhook, parseWatchedWebhookRequest, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, qrToDataUrl, qrToSvg, seal, spdToDataUrl, spdToSvg, toLnurl, unseal, verifyWebhookSignature };
+export { type BankTransfer, type BankTransferParams, type BankVerifyConfig, CreatePaymentParams, type Credit, type FioConfig, type GatewayCheatCode, GatewayCheatError, Gateways, type GatewaysOptions, IDEMPOTENCY_KEY_REUSED, type IdempotencyConflict, IdempotencyConflictError, type Invoice, type MedianOptions, NO_WALLET_AVAILABLE, NoWalletAvailableError, PAYMENT_ALREADY_WATCHED, Payment, ProblemError, type QrOptions, REQUEST_IN_FLIGHT, Settlement, type Statement, ThunderBridge, ThunderBridgeOptions, type Ticker, TriggerEvent, UnverifiedRecipientError, WaitOptions, WalletFailure, WatchPaymentParams, type WebhookCredential, type WebhookOptions, answerVerifyChallenge, answerVerifyChallengeRequest, answerWebhookChallenge, answerWebhookChallengeRequest, bankTransfer, bankVerifyEndpoint, bitstamp, coinbase, coinmate, decodeInvoice, fioStatement, invoiceToDataUrl, invoiceToSvg, isProblemType, isProvablyPaid, isProvablySettled, kraken, lnurlToDataUrl, lnurlToSvg, medianOf, minorScaleOf, minorUnitsOf, msatFor, parseSettlement, parseSettlementRequest, parseWatchedWebhook, parseWatchedWebhookRequest, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, qrToDataUrl, qrToSvg, seal, spdToDataUrl, spdToSvg, toLnurl, unseal, verifyWebhookSignature };

package/dist/index.d.ts

@@ -1,5 +1,45 @@
-import { T as ThunderBridge, P as Payment, C as CreatePaymentParams, a as TriggerEvent, W as WalletFailure } from './rail-J8QoYbSr.js';
-export { B as BankRailConfig, b as CreateOptions, c as CreateQuoteParams, F as FollowOptions, L as Leg, d as LightningRailConfig, O as Order, e as PaymentKind, f as PaymentStatus, Q as Quote, R as Rail, g as ThunderBridgeOptions, h as WaitOptions, i as WalletReason, j as WatchPaymentParams, k as bankRail, l as lightningRail } from './rail-J8QoYbSr.js';
+import { T as ThunderBridge, a as ThunderBridgeOptions, W as WatchPaymentParams, b as TriggerEvent, c as WaitOptions, P as Payment, C as CreatePaymentParams, S as Settlement, d as WalletFailure } from './rail-CL9QkiHo.js';
+export { B as BankRailConfig, e as CreateOptions, f as CreateQuoteParams, F as FollowOptions, L as Leg, g as LightningRailConfig, O as Order, h as PaymentKind, i as PaymentStatus, Q as Quote, R as Rail, j as WalletReason, k as bankRail, l as lightningRail } from './rail-CL9QkiHo.js';
+
+interface GatewaysOptions extends ThunderBridgeOptions {
+    /**
+     * Called for each gateway that would not take the watch, with the url and what
+     * it said. Registering at three and having one refuse still leaves you watched,
+     * so this is how you find out you are less covered than you asked to be, rather
+     * than finding out when the one that took it goes away
+     */
+    onRefused?: (baseUrl: string, refusal: unknown) => void;
+}
+/**
+ * The same payment watched at several gateways at once, which is what makes any
+ * one of them replaceable. They all answer with the same name for it, because a
+ * payment is named after the caller and not after any gateway, so the first
+ * delivery to arrive is the answer and the rest are the same news twice.
+ *
+ * For watching only. Two gateways asked to mint would fetch two different invoices
+ * from the wallet and only one of them could ever be paid
+ */
+declare class Gateways {
+    readonly each: readonly ThunderBridge[];
+    private readonly urls;
+    private readonly onRefused;
+    constructor(baseUrls: string[], options?: GatewaysOptions);
+    /** What this payment is called, which every gateway here will agree on */
+    nameFor(paymentHash: string): Promise<string | null>;
+    /**
+     * Hand the same invoice to every gateway. Throws only when none of them took it,
+     * carrying the first refusal, because one gateway that agreed is enough to be
+     * watched
+     */
+    watchPayment(params: WatchPaymentParams): Promise<TriggerEvent>;
+    /**
+     * Wait for whichever gateway speaks first. A settlement from any of them is the
+     * settlement, and each has already proved the preimage against the hash before
+     * saying so. When they all end without a payment, the first ending is the answer,
+     * and when they all fail, the first failure is thrown
+     */
+    waitForWatched(id: string, options?: WaitOptions): Promise<TriggerEvent>;
+}
 
 /**
  * Encrypt what the watcher needs and the gateway must not have. The gateway
@@ -71,8 +111,6 @@ interface BankTransferParams {
      * a transfer is only ever learned by following the trigger or asking
      */
     webhookUrl?: string;
-    /** Signs that delivery, so `verifyWebhookSignature` can tell it came from the gateway */
-    webhookSecret?: 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
@@ -346,11 +384,12 @@ type WebhookOptions = {
     toleranceSecs?: number;
 };
 /**
- * What checks a delivery. A string is the `webhook.secret` you registered. Pass
- * `{ publicKey }` instead, the hex from the gateway's `/webhook-key`, when you
- * registered no secret and would rather it held nothing of yours
+ * What checks a delivery: the hex the gateway publishes at `/webhook-key`. There
+ * is no shared secret to register, so a gateway holds nothing of yours. Rotating
+ * its cluster key rotates this too, so a signature that stops verifying is a
+ * reason to read the key again before it is a reason to distrust the gateway
  */
-type WebhookCredential = string | {
+type WebhookCredential = {
     publicKey: string;
 };
 /** Verify the `X-Signature` header against the raw body and the `X-Timestamp` that came with it */
@@ -370,6 +409,20 @@ declare function parseWebhookRequest(request: Request, credential: WebhookCreden
 declare function parseWatchedWebhook(body: string | Uint8Array, signature: string, credential: WebhookCredential, timestamp: string, options?: WebhookOptions): Promise<TriggerEvent | null>;
 /** `parseWatchedWebhook` from a Fetch API `Request`, the way `parseWebhookRequest` is */
 declare function parseWatchedWebhookRequest(request: Request, credential: WebhookCredential, options?: WebhookOptions): Promise<TriggerEvent | null>;
+/**
+ * Verify a delivery and read the settlement out of it. Null on a bad signature or
+ * on a body that is not a settlement, so a handler that gets null did not just
+ * miss a payment, it was handed something it had no reason to believe
+ */
+declare function parseSettlement(body: string | Uint8Array, signature: string, credential: WebhookCredential, timestamp: string, options?: WebhookOptions): Promise<Settlement | null>;
+/** {@link parseSettlement} from a Fetch API `Request` */
+declare function parseSettlementRequest(request: Request, credential: WebhookCredential, options?: WebhookOptions): Promise<Settlement | null>;
+/**
+ * Whether a delivery proves what it claims, which is the only question that
+ * matters about one: it says paid and it carries a preimage that hashes to the
+ * payment hash the delivery itself names
+ */
+declare function isProvablySettled(settled: Settlement): boolean;
 /**
  * Answer the one challenge the gateway sends before it will watch a payment your
  * webhook is registered on. Returns the body to send back with a 200, or null when
@@ -398,7 +451,7 @@ declare function answerVerifyChallengeRequest(request: Request): Promise<Respons
  * The way a gateway was caught out, every code is a check that held against the
  * recipient's own server and failed against what the gateway returned
  */
-type GatewayCheatCode = "address_not_requested" | "hash_mismatch" | "amount_mismatch" | "description_hash_mismatch" | "verify_url_foreign" | "invoice_not_issued" | "preimage_mismatch";
+type GatewayCheatCode = "address_not_requested" | "hash_mismatch" | "amount_mismatch" | "description_hash_mismatch" | "verify_url_foreign" | "invoice_not_issued" | "preimage_mismatch" | "id_not_mine";
 /**
  * Thrown when the gateway demonstrably misbehaved, the invoice it returned is
  * not the one the address you asked for issued, or a settlement it reported
@@ -470,4 +523,4 @@ declare class NoWalletAvailableError extends ProblemError {
     }, wallets: WalletFailure[]);
 }
 
-export { type BankTransfer, type BankTransferParams, type BankVerifyConfig, CreatePaymentParams, type Credit, type FioConfig, type GatewayCheatCode, GatewayCheatError, IDEMPOTENCY_KEY_REUSED, type IdempotencyConflict, IdempotencyConflictError, type Invoice, type MedianOptions, NO_WALLET_AVAILABLE, NoWalletAvailableError, PAYMENT_ALREADY_WATCHED, Payment, ProblemError, type QrOptions, REQUEST_IN_FLIGHT, type Statement, ThunderBridge, type Ticker, TriggerEvent, UnverifiedRecipientError, WalletFailure, type WebhookCredential, type WebhookOptions, answerVerifyChallenge, answerVerifyChallengeRequest, answerWebhookChallenge, answerWebhookChallengeRequest, bankTransfer, bankVerifyEndpoint, bitstamp, coinbase, coinmate, decodeInvoice, fioStatement, invoiceToDataUrl, invoiceToSvg, isProblemType, isProvablyPaid, kraken, lnurlToDataUrl, lnurlToSvg, medianOf, minorScaleOf, minorUnitsOf, msatFor, parseWatchedWebhook, parseWatchedWebhookRequest, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, qrToDataUrl, qrToSvg, seal, spdToDataUrl, spdToSvg, toLnurl, unseal, verifyWebhookSignature };
+export { type BankTransfer, type BankTransferParams, type BankVerifyConfig, CreatePaymentParams, type Credit, type FioConfig, type GatewayCheatCode, GatewayCheatError, Gateways, type GatewaysOptions, IDEMPOTENCY_KEY_REUSED, type IdempotencyConflict, IdempotencyConflictError, type Invoice, type MedianOptions, NO_WALLET_AVAILABLE, NoWalletAvailableError, PAYMENT_ALREADY_WATCHED, Payment, ProblemError, type QrOptions, REQUEST_IN_FLIGHT, Settlement, type Statement, ThunderBridge, ThunderBridgeOptions, type Ticker, TriggerEvent, UnverifiedRecipientError, WaitOptions, WalletFailure, WatchPaymentParams, type WebhookCredential, type WebhookOptions, answerVerifyChallenge, answerVerifyChallengeRequest, answerWebhookChallenge, answerWebhookChallengeRequest, bankTransfer, bankVerifyEndpoint, bitstamp, coinbase, coinmate, decodeInvoice, fioStatement, invoiceToDataUrl, invoiceToSvg, isProblemType, isProvablyPaid, isProvablySettled, kraken, lnurlToDataUrl, lnurlToSvg, medianOf, minorScaleOf, minorUnitsOf, msatFor, parseSettlement, parseSettlementRequest, parseWatchedWebhook, parseWatchedWebhookRequest, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, qrToDataUrl, qrToSvg, seal, spdToDataUrl, spdToSvg, toLnurl, unseal, verifyWebhookSignature };