thunder-bridge 1.4.2 → 1.5.0

package/dist/nwc.d.cts

@@ -0,0 +1,120 @@
+import { A as Amount, T as Ticker } from './types-BNPmVnA7.cjs';
+import { R as RailConfig, O as Order, T as ThunderBridge, a as Rail } from './client-CzGZcByI.cjs';
+import './qr-CF-YeXU1.cjs';
+import './bank-B3mHISn1.cjs';
+
+/** 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;
+}
+/** The endpoint the gateway polls for an NWC payment, answering off your own wallet */
+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` whose `reason` says which kind of refusal it was
+ */
+declare function askWallet(connection: NwcConnection, method: string, params: Record<string, unknown>, timeoutMs?: number): Promise<Record<string, unknown>>;
+/** A Lightning rail minting on a wallet of your own over NIP-47, bound once per shop */
+interface NwcRailConfig extends RailConfig {
+    /** The wallet that mints, which never leaves this process */
+    connection: NwcConnection;
+    /**
+     * What to charge for one order, the order's own price converted at `rate` by
+     * default. Give it a function and the price is whatever you say
+     */
+    amount?: (order: Order) => Amount;
+    /** Where the default conversion gets its rate, the median of four venues by default */
+    rate?: Ticker;
+    /** Where `nwcVerifyEndpoint` is mounted, and the secret the hash is sealed with */
+    verifyThrough: {
+        endpoint: string;
+        secret: string;
+    };
+    /** What the payer's wallet shows, the order's reference by default */
+    description?: (order: Order) => string;
+    /** Sealed before the gateway sees it, the way the blind Lightning rail does */
+    sealed?: (order: Order) => string | Promise<string>;
+}
+/**
+ * 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.
+ *
+ * This rail lives here rather than on `gateway.rails` because NIP-47 needs the
+ * nostr crypto in this module, and a browser showing a QR should not download it
+ */
+declare function nwcRail(gateway: ThunderBridge, config: NwcRailConfig): Rail;
+
+export { type NwcConnection, type NwcInvoice, type NwcRailConfig, type NwcVerifyConfig, askWallet, nwcConnection, nwcHoldInvoice, nwcInvoice, nwcPay, nwcRail, nwcSettlement, nwcVerifyEndpoint, nwcVerifyUrl };

package/dist/nwc.d.ts

@@ -0,0 +1,120 @@
+import { A as Amount, T as Ticker } from './types-BNPmVnA7.js';
+import { R as RailConfig, O as Order, T as ThunderBridge, a as Rail } from './client-Cc5gtjGV.js';
+import './qr-CF-YeXU1.js';
+import './bank-B3mHISn1.js';
+
+/** 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;
+}
+/** The endpoint the gateway polls for an NWC payment, answering off your own wallet */
+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` whose `reason` says which kind of refusal it was
+ */
+declare function askWallet(connection: NwcConnection, method: string, params: Record<string, unknown>, timeoutMs?: number): Promise<Record<string, unknown>>;
+/** A Lightning rail minting on a wallet of your own over NIP-47, bound once per shop */
+interface NwcRailConfig extends RailConfig {
+    /** The wallet that mints, which never leaves this process */
+    connection: NwcConnection;
+    /**
+     * What to charge for one order, the order's own price converted at `rate` by
+     * default. Give it a function and the price is whatever you say
+     */
+    amount?: (order: Order) => Amount;
+    /** Where the default conversion gets its rate, the median of four venues by default */
+    rate?: Ticker;
+    /** Where `nwcVerifyEndpoint` is mounted, and the secret the hash is sealed with */
+    verifyThrough: {
+        endpoint: string;
+        secret: string;
+    };
+    /** What the payer's wallet shows, the order's reference by default */
+    description?: (order: Order) => string;
+    /** Sealed before the gateway sees it, the way the blind Lightning rail does */
+    sealed?: (order: Order) => string | Promise<string>;
+}
+/**
+ * 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.
+ *
+ * This rail lives here rather than on `gateway.rails` because NIP-47 needs the
+ * nostr crypto in this module, and a browser showing a QR should not download it
+ */
+declare function nwcRail(gateway: ThunderBridge, config: NwcRailConfig): Rail;
+
+export { type NwcConnection, type NwcInvoice, type NwcRailConfig, type NwcVerifyConfig, askWallet, nwcConnection, nwcHoldInvoice, nwcInvoice, nwcPay, nwcRail, nwcSettlement, nwcVerifyEndpoint, nwcVerifyUrl };