@getalby/lightning-tools 8.1.0 → 8.2.0

package/dist/cjs/bip21.cjs

@@ -0,0 +1,115 @@
+'use strict';
+
+const BIP21_SCHEME = /^bitcoin:/i;
+// BIP21 grammar: amountparam = "amount=" *digit [ "." *digit ]
+// We require at least one digit on either side of the decimal point — this is
+// slightly stricter than the spec ABNF but matches every real-world example
+// (the spec shows "50", "50.00", "20.3"). Crucially this rejects scientific
+// notation ("1e-3"), hex ("0x10"), commas, signs, and leading "+" / "-".
+const BIP21_AMOUNT_RE = /^(\d+)(?:\.(\d+))?$/;
+const SATS_PER_BTC = 100000000n;
+const BTC_DECIMALS = 8;
+/**
+ * Convert a BIP21-compliant decimal BTC string to an integer number of
+ * satoshis using exact decimal arithmetic (no floats). Fractional digits
+ * beyond 8 are rounded half-up to the nearest satoshi.
+ *
+ * Assumes the input has already been validated against BIP21_AMOUNT_RE.
+ */
+const btcStringToSats = (btc) => {
+    const match = BIP21_AMOUNT_RE.exec(btc);
+    if (!match) {
+        // Should be unreachable — caller pre-validates.
+        return Number.NaN;
+    }
+    const [, integerPart, rawFractional = ""] = match;
+    let fractionalSats;
+    if (rawFractional.length <= BTC_DECIMALS) {
+        fractionalSats = BigInt(rawFractional.padEnd(BTC_DECIMALS, "0"));
+    }
+    else {
+        // Round half-up at the satoshi boundary.
+        const truncated = rawFractional.slice(0, BTC_DECIMALS);
+        const roundDigit = rawFractional.charCodeAt(BTC_DECIMALS) - 48;
+        fractionalSats = BigInt(truncated);
+        if (roundDigit >= 5)
+            fractionalSats += 1n;
+    }
+    const totalSats = BigInt(integerPart) * SATS_PER_BTC + fractionalSats;
+    return Number(totalSats);
+};
+/**
+ * Parse a BIP21 (`bitcoin:`) URI. Returns `null` if the input doesn't have the
+ * `bitcoin:` scheme.
+ *
+ * The address is returned as-is (case preserved) — callers should validate it
+ * separately if they need to ensure it's a well-formed bitcoin address.
+ *
+ * Per BIP21, parameters prefixed with `req-` are required: if the client
+ * doesn't understand any of them, the payment MUST NOT be made. The unknown
+ * required params are surfaced via `unknownRequiredParams` so callers can
+ * decide how to fail.
+ *
+ * @example
+ * parseBip21("bitcoin:bc1q...?amount=0.001&lightning=lnbc...")
+ * // => { address: "bc1q...", amount: 0.001, amountSats: 100000, lightning: "lnbc...", ... }
+ */
+const parseBip21 = (uri) => {
+    if (typeof uri !== "string") {
+        return null;
+    }
+    const normalized = uri.trim();
+    if (!BIP21_SCHEME.test(normalized)) {
+        return null;
+    }
+    const withoutScheme = normalized.replace(BIP21_SCHEME, "");
+    const queryStart = withoutScheme.indexOf("?");
+    const address = queryStart === -1 ? withoutScheme : withoutScheme.slice(0, queryStart);
+    const query = queryStart === -1 ? "" : withoutScheme.slice(queryStart + 1);
+    const params = {};
+    const unknownRequiredParams = [];
+    if (query) {
+        // URLSearchParams handles decoding and repeated params; for BIP21 last-write-wins
+        // is fine since the spec doesn't allow repeats.
+        const search = new URLSearchParams(query);
+        search.forEach((value, key) => {
+            params[key] = value;
+        });
+    }
+    const knownParams = new Set([
+        "amount",
+        "label",
+        "message",
+        "lightning",
+        "lno",
+    ]);
+    for (const key of Object.keys(params)) {
+        if (key.startsWith("req-") && !knownParams.has(key.slice(4))) {
+            unknownRequiredParams.push(key);
+        }
+    }
+    const result = {
+        address: address.trim(),
+        params,
+        unknownRequiredParams,
+    };
+    if (params.amount !== undefined && BIP21_AMOUNT_RE.test(params.amount)) {
+        result.amount = Number(params.amount);
+        result.amountSats = btcStringToSats(params.amount);
+    }
+    if (params.label !== undefined)
+        result.label = params.label;
+    if (params.message !== undefined)
+        result.message = params.message;
+    if (params.lightning !== undefined)
+        result.lightning = params.lightning;
+    if (params.lno !== undefined)
+        result.lno = params.lno;
+    return result;
+};
+/** Returns true if the input starts with the `bitcoin:` URI scheme. */
+const isBip21 = (uri) => typeof uri === "string" && BIP21_SCHEME.test(uri.trim());
+
+exports.isBip21 = isBip21;
+exports.parseBip21 = parseBip21;
+//# sourceMappingURL=bip21.cjs.map

package/dist/cjs/bip21.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bip21.cjs","sources":["../../src/bip21/utils.ts"],"sourcesContent":["import type { Bip21 } from \"./types\";\n\nconst BIP21_SCHEME = /^bitcoin:/i;\n\n// BIP21 grammar: amountparam = \"amount=\" *digit [ \".\" *digit ]\n// We require at least one digit on either side of the decimal point — this is\n// slightly stricter than the spec ABNF but matches every real-world example\n// (the spec shows \"50\", \"50.00\", \"20.3\"). Crucially this rejects scientific\n// notation (\"1e-3\"), hex (\"0x10\"), commas, signs, and leading \"+\" / \"-\".\nconst BIP21_AMOUNT_RE = /^(\\d+)(?:\\.(\\d+))?$/;\n\nconst SATS_PER_BTC = 100_000_000n;\nconst BTC_DECIMALS = 8;\n\n/**\n * Convert a BIP21-compliant decimal BTC string to an integer number of\n * satoshis using exact decimal arithmetic (no floats). Fractional digits\n * beyond 8 are rounded half-up to the nearest satoshi.\n *\n * Assumes the input has already been validated against BIP21_AMOUNT_RE.\n */\nconst btcStringToSats = (btc: string): number => {\n  const match = BIP21_AMOUNT_RE.exec(btc);\n  if (!match) {\n    // Should be unreachable — caller pre-validates.\n    return Number.NaN;\n  }\n  const [, integerPart, rawFractional = \"\"] = match;\n\n  let fractionalSats: bigint;\n  if (rawFractional.length <= BTC_DECIMALS) {\n    fractionalSats = BigInt(rawFractional.padEnd(BTC_DECIMALS, \"0\"));\n  } else {\n    // Round half-up at the satoshi boundary.\n    const truncated = rawFractional.slice(0, BTC_DECIMALS);\n    const roundDigit = rawFractional.charCodeAt(BTC_DECIMALS) - 48;\n    fractionalSats = BigInt(truncated);\n    if (roundDigit >= 5) fractionalSats += 1n;\n  }\n\n  const totalSats = BigInt(integerPart) * SATS_PER_BTC + fractionalSats;\n  return Number(totalSats);\n};\n\n/**\n * Parse a BIP21 (`bitcoin:`) URI. Returns `null` if the input doesn't have the\n * `bitcoin:` scheme.\n *\n * The address is returned as-is (case preserved) — callers should validate it\n * separately if they need to ensure it's a well-formed bitcoin address.\n *\n * Per BIP21, parameters prefixed with `req-` are required: if the client\n * doesn't understand any of them, the payment MUST NOT be made. The unknown\n * required params are surfaced via `unknownRequiredParams` so callers can\n * decide how to fail.\n *\n * @example\n * parseBip21(\"bitcoin:bc1q...?amount=0.001&lightning=lnbc...\")\n * // => { address: \"bc1q...\", amount: 0.001, amountSats: 100000, lightning: \"lnbc...\", ... }\n */\nexport const parseBip21 = (uri: string): Bip21 | null => {\n  if (typeof uri !== \"string\") {\n    return null;\n  }\n  const normalized = uri.trim();\n  if (!BIP21_SCHEME.test(normalized)) {\n    return null;\n  }\n\n  const withoutScheme = normalized.replace(BIP21_SCHEME, \"\");\n  const queryStart = withoutScheme.indexOf(\"?\");\n  const address =\n    queryStart === -1 ? withoutScheme : withoutScheme.slice(0, queryStart);\n  const query = queryStart === -1 ? \"\" : withoutScheme.slice(queryStart + 1);\n\n  const params: Record<string, string> = {};\n  const unknownRequiredParams: string[] = [];\n\n  if (query) {\n    // URLSearchParams handles decoding and repeated params; for BIP21 last-write-wins\n    // is fine since the spec doesn't allow repeats.\n    const search = new URLSearchParams(query);\n    search.forEach((value, key) => {\n      params[key] = value;\n    });\n  }\n\n  const knownParams = new Set([\n    \"amount\",\n    \"label\",\n    \"message\",\n    \"lightning\",\n    \"lno\",\n  ]);\n\n  for (const key of Object.keys(params)) {\n    if (key.startsWith(\"req-\") && !knownParams.has(key.slice(4))) {\n      unknownRequiredParams.push(key);\n    }\n  }\n\n  const result: Bip21 = {\n    address: address.trim(),\n    params,\n    unknownRequiredParams,\n  };\n\n  if (params.amount !== undefined && BIP21_AMOUNT_RE.test(params.amount)) {\n    result.amount = Number(params.amount);\n    result.amountSats = btcStringToSats(params.amount);\n  }\n  if (params.label !== undefined) result.label = params.label;\n  if (params.message !== undefined) result.message = params.message;\n  if (params.lightning !== undefined) result.lightning = params.lightning;\n  if (params.lno !== undefined) result.lno = params.lno;\n\n  return result;\n};\n\n/** Returns true if the input starts with the `bitcoin:` URI scheme. */\nexport const isBip21 = (uri: string): boolean =>\n  typeof uri === \"string\" && BIP21_SCHEME.test(uri.trim());\n"],"names":[],"mappings":"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"}

package/dist/cjs/index.cjs

@@ -1674,6 +1674,28 @@ class LightningAddress {
     }
 }
 
+/** Apply a previously-obtained credential to the outgoing request headers. */
+const applyCredentials = (headers, credentials) => {
+    headers.set(credentials.header, credentials.value);
+};
+/** Attach payment metadata to a response and return it (typed). */
+const attachPayment = (response, payment) => {
+    if (payment) {
+        response.payment = payment;
+    }
+    return response;
+};
+/** Payment metadata describing a request authorized with a reused credential. */
+const reusedCredentialPayment = (credentials) => credentials ? { paid: false, amount: 0, credentials } : undefined;
+/** Satoshi amount of a BOLT11 invoice (0 when it cannot be decoded). */
+const getInvoiceAmount = (invoice) => {
+    try {
+        return new Invoice({ pr: invoice }).satoshi;
+    }
+    catch (_) {
+        return 0;
+    }
+};
 function createGuardedWallet(wallet, maxAmountSats) {
     return {
         payInvoice: async (args) => {
@@ -1725,6 +1747,9 @@ const handleL402Payment = async (l402Header, url, fetchArgs, headers, wallet) =>
     const details = parseL402(l402Header);
     const token = details.token || details.macaroon;
     const invoice = details.invoice;
+    // Preserve the scheme the server challenged with (L402 or LSAT) so the
+    // retry's Authorization header matches what the server expects.
+    const scheme = /^\s*LSAT\b/i.test(l402Header) ? "LSAT" : "L402";
     if (!token) {
         throw new Error("L402: missing token/macaroon in WWW-Authenticate header");
     }
@@ -1732,8 +1757,16 @@ const handleL402Payment = async (l402Header, url, fetchArgs, headers, wallet) =>
         throw new Error("L402: missing invoice in WWW-Authenticate header");
     }
     const invResp = await wallet.payInvoice({ invoice });
-    headers.set("Authorization", `L402 ${token}:${invResp.preimage}`);
-    return fetch(url, fetchArgs);
+    const value = `${scheme} ${token}:${invResp.preimage}`;
+    headers.set("Authorization", value);
+    const response = await fetch(url, fetchArgs);
+    return attachPayment(response, {
+        paid: true,
+        amount: getInvoiceAmount(invoice),
+        feesPaid: invResp.fees_paid,
+        preimage: invResp.preimage,
+        credentials: { header: "Authorization", value },
+    });
 };
 const fetchWithL402 = async (url, fetchArgs, options) => {
     const wallet = options.wallet;
@@ -1747,6 +1780,15 @@ const fetchWithL402 = async (url, fetchArgs, options) => {
     fetchArgs.mode = "cors";
     const headers = new Headers(fetchArgs.headers ?? undefined);
     fetchArgs.headers = headers;
+    // If the caller supplied a credential, we MUST use it and never pay again —
+    // even if the server still responds with a 402. Re-paying here is the exact
+    // double-charge this API exists to prevent; the caller decides what to do
+    // with a rejected credential (retry after settlement, top up, etc.).
+    if (options.credentials) {
+        applyCredentials(headers, options.credentials);
+        const reusedResp = await fetch(url, fetchArgs);
+        return attachPayment(reusedResp, reusedCredentialPayment(options.credentials));
+    }
     const initResp = await fetch(url, fetchArgs);
     const header = initResp.headers.get("www-authenticate");
     if (!header) {
@@ -1767,7 +1809,7 @@ const buildX402PaymentSignature = (scheme, network, invoice, requirements) => {
     return btoa(unescape(encodeURIComponent(json)));
 };
 
-const handleX402Payment = async (x402Header, url, fetchArgs, headers, wallet) => {
+const decodeX402Header = (x402Header) => {
     let parsed;
     try {
         parsed = JSON.parse(decodeURIComponent(escape(atob(x402Header))));
@@ -1778,9 +1820,31 @@ const handleX402Payment = async (x402Header, url, fetchArgs, headers, wallet) =>
     if (!Array.isArray(parsed.accepts) || parsed.accepts.length === 0) {
         throw new Error("x402: PAYMENT-REQUIRED header contains no payment options");
     }
-    const requirements = parsed.accepts.find((e) => {
-        return e.extra?.paymentMethod === "lightning";
-    });
+    return { accepts: parsed.accepts };
+};
+/**
+ * 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.
+ */
+const findX402LightningRequirements = (x402Header) => {
+    let accepts;
+    try {
+        ({ accepts } = decodeX402Header(x402Header));
+    }
+    catch (_) {
+        return null;
+    }
+    const requirements = accepts.find((e) => e?.extra?.paymentMethod === "lightning");
+    if (!requirements?.extra?.invoice)
+        return null;
+    return requirements;
+};
+const handleX402Payment = async (x402Header, url, fetchArgs, headers, wallet) => {
+    const { accepts } = decodeX402Header(x402Header);
+    const requirements = accepts.find((e) => e?.extra?.paymentMethod === "lightning");
     if (!requirements) {
         throw new Error("x402: unsupported x402 network, only Bitcoin lightning network is supported.");
     }
@@ -1791,9 +1855,17 @@ const handleX402Payment = async (x402Header, url, fetchArgs, headers, wallet) =>
     if (invoice.amountRaw != requirements.amount) {
         throw new Error(`Invalid invoice amount: ${invoice.amountRaw}. expected ${requirements.amount}`);
     }
-    await wallet.payInvoice({ invoice: invoice.paymentRequest });
-    headers.set("payment-signature", buildX402PaymentSignature(requirements.scheme, requirements.network, invoice.paymentRequest, requirements));
-    return fetch(url, fetchArgs);
+    const invResp = await wallet.payInvoice({ invoice: invoice.paymentRequest });
+    const value = buildX402PaymentSignature(requirements.scheme, requirements.network, invoice.paymentRequest, requirements);
+    headers.set("payment-signature", value);
+    const response = await fetch(url, fetchArgs);
+    return attachPayment(response, {
+        paid: true,
+        amount: invoice.satoshi,
+        feesPaid: invResp.fees_paid,
+        preimage: invResp.preimage,
+        credentials: { header: "payment-signature", value },
+    });
 };
 const fetchWithX402 = async (url, fetchArgs, options) => {
     const wallet = options.wallet;
@@ -1804,6 +1876,15 @@ const fetchWithX402 = async (url, fetchArgs, options) => {
     fetchArgs.mode = "cors";
     const headers = new Headers(fetchArgs.headers ?? undefined);
     fetchArgs.headers = headers;
+    // If the caller supplied a credential, we MUST use it and never pay again —
+    // even if the server still responds with a 402. Re-paying here is the exact
+    // double-charge this API exists to prevent; the caller decides what to do
+    // with a rejected credential (retry after settlement, top up, etc.).
+    if (options.credentials) {
+        applyCredentials(headers, options.credentials);
+        const reusedResp = await fetch(url, fetchArgs);
+        return attachPayment(reusedResp, reusedCredentialPayment(options.credentials));
+    }
     const initResp = await fetch(url, fetchArgs);
     const header = initResp.headers.get("PAYMENT-REQUIRED");
     if (!header) {
@@ -1950,8 +2031,16 @@ const handleMppChargePayment = async (wwwAuthHeader, url, fetchArgs, headers, wa
     const invResp = await wallet.payInvoice({ invoice });
     // Per spec: Authorization: Payment <base64url-token>  (single token, no wrapper)
     const credential = buildMppCredential(challenge, invResp.preimage);
-    headers.set("Authorization", `Payment ${credential}`);
-    return fetch(url, fetchArgs);
+    const value = `Payment ${credential}`;
+    headers.set("Authorization", value);
+    const response = await fetch(url, fetchArgs);
+    return attachPayment(response, {
+        paid: true,
+        amount: getInvoiceAmount(invoice),
+        feesPaid: invResp.fees_paid,
+        preimage: invResp.preimage,
+        credentials: { header: "Authorization", value },
+    });
 };
 /**
  * Fetch a resource protected by the draft-lightning-charge-00 payment
@@ -1962,9 +2051,11 @@ const handleMppChargePayment = async (wwwAuthHeader, url, fetchArgs, headers, wa
  * the function pays the embedded BOLT11 invoice and retries with the
  * resulting preimage as the credential.
  *
- * Note: lightning-charge uses consume-once challenge semantics – each
- * challenge embeds a fresh invoice, so paid credentials cannot be reused.
- * The `store` option is accepted for API consistency but is not used.
+ * Pass a previous credential via `options.credentials` to reuse it (e.g. when
+ * polling); the credential is applied and the function NEVER pays again, even
+ * if the server still responds with a 402 (that response is returned as-is).
+ * Note: lightning-charge typically uses consume-once challenge semantics, so a
+ * reused credential is only accepted by servers that explicitly support it.
  */
 const fetchWithMpp = async (url, fetchArgs, options) => {
     const wallet = options.wallet;
@@ -1978,6 +2069,15 @@ const fetchWithMpp = async (url, fetchArgs, options) => {
     fetchArgs.mode = "cors";
     const headers = new Headers(fetchArgs.headers ?? undefined);
     fetchArgs.headers = headers;
+    // If the caller supplied a credential, we MUST use it and never pay again —
+    // even if the server still responds with a 402. Re-paying here is the exact
+    // double-charge this API exists to prevent; the caller decides what to do
+    // with a rejected credential (retry after settlement, top up, etc.).
+    if (options.credentials) {
+        applyCredentials(headers, options.credentials);
+        const reusedResp = await fetch(url, fetchArgs);
+        return attachPayment(reusedResp, reusedCredentialPayment(options.credentials));
+    }
     const initResp = await fetch(url, fetchArgs);
     const wwwAuthHeader = initResp.headers.get("www-authenticate");
     if (!wwwAuthHeader ||
@@ -1998,20 +2098,38 @@ const fetch402 = async (url, fetchArgs, options) => {
     fetchArgs.mode = "cors";
     const headers = new Headers(fetchArgs.headers ?? undefined);
     fetchArgs.headers = headers;
+    // If the caller supplied a credential, we MUST use it and never pay again —
+    // even if the server still responds with a 402. Re-paying here is the exact
+    // double-charge this API exists to prevent; the caller decides what to do
+    // with a rejected credential (retry after settlement, top up, etc.).
+    if (options.credentials) {
+        applyCredentials(headers, options.credentials);
+        const reusedResp = await fetch(url, fetchArgs);
+        return attachPayment(reusedResp, reusedCredentialPayment(options.credentials));
+    }
     const initResp = await fetch(url, fetchArgs);
+    // L402 / LSAT: dedicated scheme, dispatch directly.
     const wwwAuthHeader = initResp.headers.get("www-authenticate");
     if (wwwAuthHeader) {
         const trimmed = wwwAuthHeader.trimStart().toLowerCase();
-        if (trimmed.startsWith("payment")) {
-            return handleMppChargePayment(wwwAuthHeader, url, fetchArgs, headers, wallet);
-        }
         if (trimmed.startsWith("l402") || trimmed.startsWith("lsat")) {
             return handleL402Payment(wwwAuthHeader, url, fetchArgs, headers, wallet);
         }
-        throw new Error(`fetch402: unsupported WWW-Authenticate scheme: ${wwwAuthHeader}`);
     }
+    // A server may advertise multiple payment options at once (e.g. an MPP
+    // USDC challenge in WWW-Authenticate alongside an x402 PAYMENT-REQUIRED
+    // header that lists both USDC and lightning). Try each lightning-payable
+    // handler in turn; only if none matches do we hand the original 402 back
+    // to the caller so they can decide what to do with non-lightning offers.
+    // 1. MPP-lightning challenge (Payment method="lightning" intent="charge").
+    //    parseMppChallenge returns null for any other method, which lets us
+    //    fall through to x402 instead of throwing.
+    if (wwwAuthHeader && parseMppChallenge(wwwAuthHeader)) {
+        return handleMppChargePayment(wwwAuthHeader, url, fetchArgs, headers, wallet);
+    }
+    // 2. x402 PAYMENT-REQUIRED with a lightning entry in `accepts`.
     const x402Header = initResp.headers.get("PAYMENT-REQUIRED");
-    if (x402Header) {
+    if (x402Header && findX402LightningRequirements(x402Header)) {
         return handleX402Payment(x402Header, url, fetchArgs, headers, wallet);
     }
     return initResp;
@@ -2145,16 +2263,129 @@ const getFormattedFiatValue = async ({ satoshi, currency, locale, }) => {
     });
 };
 
+const BIP21_SCHEME = /^bitcoin:/i;
+// BIP21 grammar: amountparam = "amount=" *digit [ "." *digit ]
+// We require at least one digit on either side of the decimal point — this is
+// slightly stricter than the spec ABNF but matches every real-world example
+// (the spec shows "50", "50.00", "20.3"). Crucially this rejects scientific
+// notation ("1e-3"), hex ("0x10"), commas, signs, and leading "+" / "-".
+const BIP21_AMOUNT_RE = /^(\d+)(?:\.(\d+))?$/;
+const SATS_PER_BTC = 100000000n;
+const BTC_DECIMALS = 8;
+/**
+ * Convert a BIP21-compliant decimal BTC string to an integer number of
+ * satoshis using exact decimal arithmetic (no floats). Fractional digits
+ * beyond 8 are rounded half-up to the nearest satoshi.
+ *
+ * Assumes the input has already been validated against BIP21_AMOUNT_RE.
+ */
+const btcStringToSats = (btc) => {
+    const match = BIP21_AMOUNT_RE.exec(btc);
+    if (!match) {
+        // Should be unreachable — caller pre-validates.
+        return Number.NaN;
+    }
+    const [, integerPart, rawFractional = ""] = match;
+    let fractionalSats;
+    if (rawFractional.length <= BTC_DECIMALS) {
+        fractionalSats = BigInt(rawFractional.padEnd(BTC_DECIMALS, "0"));
+    }
+    else {
+        // Round half-up at the satoshi boundary.
+        const truncated = rawFractional.slice(0, BTC_DECIMALS);
+        const roundDigit = rawFractional.charCodeAt(BTC_DECIMALS) - 48;
+        fractionalSats = BigInt(truncated);
+        if (roundDigit >= 5)
+            fractionalSats += 1n;
+    }
+    const totalSats = BigInt(integerPart) * SATS_PER_BTC + fractionalSats;
+    return Number(totalSats);
+};
+/**
+ * Parse a BIP21 (`bitcoin:`) URI. Returns `null` if the input doesn't have the
+ * `bitcoin:` scheme.
+ *
+ * The address is returned as-is (case preserved) — callers should validate it
+ * separately if they need to ensure it's a well-formed bitcoin address.
+ *
+ * Per BIP21, parameters prefixed with `req-` are required: if the client
+ * doesn't understand any of them, the payment MUST NOT be made. The unknown
+ * required params are surfaced via `unknownRequiredParams` so callers can
+ * decide how to fail.
+ *
+ * @example
+ * parseBip21("bitcoin:bc1q...?amount=0.001&lightning=lnbc...")
+ * // => { address: "bc1q...", amount: 0.001, amountSats: 100000, lightning: "lnbc...", ... }
+ */
+const parseBip21 = (uri) => {
+    if (typeof uri !== "string") {
+        return null;
+    }
+    const normalized = uri.trim();
+    if (!BIP21_SCHEME.test(normalized)) {
+        return null;
+    }
+    const withoutScheme = normalized.replace(BIP21_SCHEME, "");
+    const queryStart = withoutScheme.indexOf("?");
+    const address = queryStart === -1 ? withoutScheme : withoutScheme.slice(0, queryStart);
+    const query = queryStart === -1 ? "" : withoutScheme.slice(queryStart + 1);
+    const params = {};
+    const unknownRequiredParams = [];
+    if (query) {
+        // URLSearchParams handles decoding and repeated params; for BIP21 last-write-wins
+        // is fine since the spec doesn't allow repeats.
+        const search = new URLSearchParams(query);
+        search.forEach((value, key) => {
+            params[key] = value;
+        });
+    }
+    const knownParams = new Set([
+        "amount",
+        "label",
+        "message",
+        "lightning",
+        "lno",
+    ]);
+    for (const key of Object.keys(params)) {
+        if (key.startsWith("req-") && !knownParams.has(key.slice(4))) {
+            unknownRequiredParams.push(key);
+        }
+    }
+    const result = {
+        address: address.trim(),
+        params,
+        unknownRequiredParams,
+    };
+    if (params.amount !== undefined && BIP21_AMOUNT_RE.test(params.amount)) {
+        result.amount = Number(params.amount);
+        result.amountSats = btcStringToSats(params.amount);
+    }
+    if (params.label !== undefined)
+        result.label = params.label;
+    if (params.message !== undefined)
+        result.message = params.message;
+    if (params.lightning !== undefined)
+        result.lightning = params.lightning;
+    if (params.lno !== undefined)
+        result.lno = params.lno;
+    return result;
+};
+/** Returns true if the input starts with the `bitcoin:` URI scheme. */
+const isBip21 = (uri) => typeof uri === "string" && BIP21_SCHEME.test(uri.trim());
+
 exports.DEFAULT_PROXY = DEFAULT_PROXY;
 exports.Invoice = Invoice;
 exports.LN_ADDRESS_REGEX = LN_ADDRESS_REGEX;
 exports.LightningAddress = LightningAddress;
+exports.applyCredentials = applyCredentials;
+exports.attachPayment = attachPayment;
 exports.createGuardedWallet = createGuardedWallet;
 exports.decodeInvoice = decodeInvoice;
 exports.fetch402 = fetch402;
 exports.fetchWithL402 = fetchWithL402;
 exports.fetchWithMpp = fetchWithMpp;
 exports.fetchWithX402 = fetchWithX402;
+exports.findX402LightningRequirements = findX402LightningRequirements;
 exports.fromHexString = fromHexString;
 exports.generateZapEvent = generateZapEvent;
 exports.getEventHash = getEventHash;
@@ -2162,16 +2393,20 @@ exports.getFiatBtcRate = getFiatBtcRate;
 exports.getFiatCurrencies = getFiatCurrencies;
 exports.getFiatValue = getFiatValue;
 exports.getFormattedFiatValue = getFormattedFiatValue;
+exports.getInvoiceAmount = getInvoiceAmount;
 exports.getSatoshiValue = getSatoshiValue;
+exports.isBip21 = isBip21;
 exports.isUrl = isUrl;
 exports.isValidAmount = isValidAmount;
 exports.issueL402Macaroon = issueL402Macaroon;
 exports.makeL402AuthenticateHeader = makeL402AuthenticateHeader;
+exports.parseBip21 = parseBip21;
 exports.parseKeysendResponse = parseKeysendResponse;
 exports.parseL402 = parseL402;
 exports.parseL402Authorization = parseL402Authorization;
 exports.parseLnUrlPayResponse = parseLnUrlPayResponse;
 exports.parseNostrResponse = parseNostrResponse;
+exports.reusedCredentialPayment = reusedCredentialPayment;
 exports.sendBoostagram = sendBoostagram;
 exports.serializeEvent = serializeEvent;
 exports.validateEvent = validateEvent;