@getalby/lightning-tools 8.0.0 → 8.1.1

package/dist/types/402/l402.d.ts

@@ -10,4 +10,42 @@ declare const fetchWithL402: (url: string, fetchArgs: RequestInit, options: {
     wallet: Wallet;
 }) => Promise<Response>;
 
-export { fetchWithL402 };
+interface WwwAuthenticatePayload {
+    token: string;
+    invoice: string;
+    [key: string]: string;
+}
+/**
+ * Client: parse "www-authenticate" header from server response
+ * @param input
+ * @returns details from the header value (token or macaroon, invoice)
+ */
+declare const parseL402: (input: string) => WwwAuthenticatePayload;
+
+type MacaroonPayload<T> = T & {
+    paymentHash: string;
+};
+declare function issueL402Macaroon<T extends Record<string, unknown>>(secret: string, paymentHash: string, params?: T): Promise<string>;
+declare function verifyL402Macaroon<T = unknown>(secret: string, token: string): Promise<MacaroonPayload<T>>;
+
+/**
+ * Server: create a WWW-Authenticate header for a given macaroon and invoice
+ * @param args the macaroon/token and invoice generated for the client's request
+ * @returns the header value
+ */
+declare const makeL402AuthenticateHeader: (args: {
+    token?: string;
+    invoice: string;
+}) => string;
+/**
+ * Server: parse "authorization" header sent from client
+ * @param input value from authorization header
+ * @returns the macaroon and preimage
+ */
+declare function parseL402Authorization(input: string): {
+    token: string;
+    preimage: string;
+} | null;
+
+export { fetchWithL402, issueL402Macaroon, makeL402AuthenticateHeader, parseL402, parseL402Authorization, verifyL402Macaroon };
+export type { MacaroonPayload };

package/dist/types/402/x402.d.ts

@@ -6,8 +6,27 @@ interface Wallet {
     }>;
 }
 
+interface X402Requirements {
+    scheme: string;
+    network: string;
+    extra: {
+        invoice: string;
+        paymentMethod?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+
+/**
+ * Probe a PAYMENT-REQUIRED header for a lightning-payable offer without
+ * throwing. Returns the matching requirements, or null if the header has no
+ * lightning entry (e.g. USDC-only endpoints) or is malformed. Used by the
+ * top-level fetch402 dispatcher to decide whether to attempt payment or hand
+ * the 402 back to the caller.
+ */
+declare const findX402LightningRequirements: (x402Header: string) => X402Requirements | null;
 declare const fetchWithX402: (url: string, fetchArgs: RequestInit, options: {
     wallet: Wallet;
 }) => Promise<Response>;
 
-export { fetchWithX402 };
+export { fetchWithX402, findX402LightningRequirements };

package/dist/types/402.d.ts

@@ -16,6 +16,62 @@ declare const fetchWithL402: (url: string, fetchArgs: RequestInit, options: {
     wallet: Wallet;
 }) => Promise<Response>;
 
+interface WwwAuthenticatePayload {
+    token: string;
+    invoice: string;
+    [key: string]: string;
+}
+/**
+ * Client: parse "www-authenticate" header from server response
+ * @param input
+ * @returns details from the header value (token or macaroon, invoice)
+ */
+declare const parseL402: (input: string) => WwwAuthenticatePayload;
+
+type MacaroonPayload<T> = T & {
+    paymentHash: string;
+};
+declare function issueL402Macaroon<T extends Record<string, unknown>>(secret: string, paymentHash: string, params?: T): Promise<string>;
+declare function verifyL402Macaroon<T = unknown>(secret: string, token: string): Promise<MacaroonPayload<T>>;
+
+/**
+ * Server: create a WWW-Authenticate header for a given macaroon and invoice
+ * @param args the macaroon/token and invoice generated for the client's request
+ * @returns the header value
+ */
+declare const makeL402AuthenticateHeader: (args: {
+    token?: string;
+    invoice: string;
+}) => string;
+/**
+ * Server: parse "authorization" header sent from client
+ * @param input value from authorization header
+ * @returns the macaroon and preimage
+ */
+declare function parseL402Authorization(input: string): {
+    token: string;
+    preimage: string;
+} | null;
+
+interface X402Requirements {
+    scheme: string;
+    network: string;
+    extra: {
+        invoice: string;
+        paymentMethod?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+
+/**
+ * Probe a PAYMENT-REQUIRED header for a lightning-payable offer without
+ * throwing. Returns the matching requirements, or null if the header has no
+ * lightning entry (e.g. USDC-only endpoints) or is malformed. Used by the
+ * top-level fetch402 dispatcher to decide whether to attempt payment or hand
+ * the 402 back to the caller.
+ */
+declare const findX402LightningRequirements: (x402Header: string) => X402Requirements | null;
 declare const fetchWithX402: (url: string, fetchArgs: RequestInit, options: {
     wallet: Wallet;
 }) => Promise<Response>;
@@ -37,5 +93,5 @@ declare const fetchWithMpp: (url: string, fetchArgs: RequestInit, options: {
     wallet: Wallet;
 }) => Promise<Response>;
 
-export { createGuardedWallet, fetch402, fetchWithL402, fetchWithMpp, fetchWithX402 };
-export type { Wallet };
+export { createGuardedWallet, fetch402, fetchWithL402, fetchWithMpp, fetchWithX402, findX402LightningRequirements, issueL402Macaroon, makeL402AuthenticateHeader, parseL402, parseL402Authorization, verifyL402Macaroon };
+export type { MacaroonPayload, Wallet };

package/dist/types/bolt11.d.ts

@@ -24,6 +24,7 @@ type DecodedInvoice = {
     description: string | undefined;
 };
 declare const decodeInvoice: (paymentRequest: string) => DecodedInvoice | null;
+declare function validatePreimage(preimage: string, paymentHash: string): boolean;
 
 declare class Invoice {
     paymentRequest: string;
@@ -46,5 +47,5 @@ declare class Invoice {
     hasExpired(): boolean;
 }
 
-export { Invoice, decodeInvoice, fromHexString };
+export { Invoice, decodeInvoice, fromHexString, validatePreimage };
 export type { InvoiceArgs, SuccessAction };

package/dist/types/index.d.ts

@@ -27,6 +27,7 @@ type DecodedInvoice = {
     description: string | undefined;
 };
 declare const decodeInvoice: (paymentRequest: string) => DecodedInvoice | null;
+declare function validatePreimage(preimage: string, paymentHash: string): boolean;
 
 declare class Invoice {
     paymentRequest: string;
@@ -257,6 +258,62 @@ declare const fetchWithL402: (url: string, fetchArgs: RequestInit, options: {
     wallet: Wallet;
 }) => Promise<Response>;
 
+interface WwwAuthenticatePayload {
+    token: string;
+    invoice: string;
+    [key: string]: string;
+}
+/**
+ * Client: parse "www-authenticate" header from server response
+ * @param input
+ * @returns details from the header value (token or macaroon, invoice)
+ */
+declare const parseL402: (input: string) => WwwAuthenticatePayload;
+
+type MacaroonPayload<T> = T & {
+    paymentHash: string;
+};
+declare function issueL402Macaroon<T extends Record<string, unknown>>(secret: string, paymentHash: string, params?: T): Promise<string>;
+declare function verifyL402Macaroon<T = unknown>(secret: string, token: string): Promise<MacaroonPayload<T>>;
+
+/**
+ * Server: create a WWW-Authenticate header for a given macaroon and invoice
+ * @param args the macaroon/token and invoice generated for the client's request
+ * @returns the header value
+ */
+declare const makeL402AuthenticateHeader: (args: {
+    token?: string;
+    invoice: string;
+}) => string;
+/**
+ * Server: parse "authorization" header sent from client
+ * @param input value from authorization header
+ * @returns the macaroon and preimage
+ */
+declare function parseL402Authorization(input: string): {
+    token: string;
+    preimage: string;
+} | null;
+
+interface X402Requirements {
+    scheme: string;
+    network: string;
+    extra: {
+        invoice: string;
+        paymentMethod?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+
+/**
+ * Probe a PAYMENT-REQUIRED header for a lightning-payable offer without
+ * throwing. Returns the matching requirements, or null if the header has no
+ * lightning entry (e.g. USDC-only endpoints) or is malformed. Used by the
+ * top-level fetch402 dispatcher to decide whether to attempt payment or hand
+ * the 402 back to the caller.
+ */
+declare const findX402LightningRequirements: (x402Header: string) => X402Requirements | null;
 declare const fetchWithX402: (url: string, fetchArgs: RequestInit, options: {
     wallet: Wallet;
 }) => Promise<Response>;
@@ -300,5 +357,5 @@ declare const getFormattedFiatValue: ({ satoshi, currency, locale, }: {
     locale: string;
 }) => Promise<string>;
 
-export { DEFAULT_PROXY, Invoice, LN_ADDRESS_REGEX, LightningAddress, createGuardedWallet, decodeInvoice, fetch402, fetchWithL402, fetchWithMpp, fetchWithX402, fromHexString, generateZapEvent, getEventHash, getFiatBtcRate, getFiatCurrencies, getFiatValue, getFormattedFiatValue, getSatoshiValue, isUrl, isValidAmount, parseKeysendResponse, parseLnUrlPayResponse, parseNostrResponse, sendBoostagram, serializeEvent, validateEvent };
-export type { Boost, BoostArguments, BoostOptions, Event, FiatCurrency, InvoiceArgs, KeySendRawData, KeysendResponse, LUD18PayerData, LUD18ServicePayerData, LnUrlPayResponse, LnUrlRawData, NostrProvider, NostrResponse, RequestInvoiceArgs, SuccessAction, Wallet, WeblnBoostParams, ZapArgs, ZapOptions };
+export { DEFAULT_PROXY, Invoice, LN_ADDRESS_REGEX, LightningAddress, createGuardedWallet, decodeInvoice, fetch402, fetchWithL402, fetchWithMpp, fetchWithX402, findX402LightningRequirements, fromHexString, generateZapEvent, getEventHash, getFiatBtcRate, getFiatCurrencies, getFiatValue, getFormattedFiatValue, getSatoshiValue, isUrl, isValidAmount, issueL402Macaroon, makeL402AuthenticateHeader, parseKeysendResponse, parseL402, parseL402Authorization, parseLnUrlPayResponse, parseNostrResponse, sendBoostagram, serializeEvent, validateEvent, validatePreimage, verifyL402Macaroon };
+export type { Boost, BoostArguments, BoostOptions, Event, FiatCurrency, InvoiceArgs, KeySendRawData, KeysendResponse, LUD18PayerData, LUD18ServicePayerData, LnUrlPayResponse, LnUrlRawData, MacaroonPayload, NostrProvider, NostrResponse, RequestInvoiceArgs, SuccessAction, Wallet, WeblnBoostParams, ZapArgs, ZapOptions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getalby/lightning-tools",
-  "version": "8.0.0",
+  "version": "8.1.1",
   "description": "Collection of helpful building blocks and tools to develop Bitcoin Lightning web apps",
   "type": "module",
   "repository": "https://github.com/getAlby/js-lightning-tools.git",