@getalby/lightning-tools 6.0.0 → 7.0.2

package/README.md

@@ -6,7 +6,13 @@
 
 An npm package that provides useful and common tools and helpers to build lightning web applications.
 
-## 🚀 Quick Start
+Before you start coding, look at example scenarios in our **[Developer Sandbox](https://sandbox.albylabs.com/)**
+
+## 🤖 🚀 ⚡ For Developers using Agents / LLMs / Vibe Coding
+
+Skip the rest of this README and use the [Alby Bitcoin Payments Agent Skill](https://github.com/getAlby/alby-agent-skill) instead. It will handle the rest!
+
+## Manual Installation
 
 ```
 npm install @getalby/lightning-tools
@@ -175,7 +181,7 @@ This library includes a `fetchWithL402` function to consume L402 protected resou
 - url: the L402 protected URL
 - fetchArgs: arguments are passed to the underlying `fetch()` function used to do the HTTP request
 - options:
-  - webln: the webln object used to call `sendPayment()` defaults to globalThis.webln
+  - wallet: any object that implements `sendPayment(paymentRequest)` and returns `{ preimage }`. Used to pay the L402 invoice.
   - store: a key/value store object to persiste the l402 for each URL. The store must implement a `getItem()`/`setItem()` function as the browser's localStorage. By default a memory storage is used.
   - headerKey: defaults to L402 but if you need to consume an old LSAT API set this to LSAT
 
@@ -184,12 +190,12 @@ This library includes a `fetchWithL402` function to consume L402 protected resou
 ```js
 import { fetchWithL402 } from "@getalby/lightning-tools/l402";
 
-// this will fetch the resource and pay the invoice with window.webln.
+// pass a wallet that implements sendPayment()
 // the tokens/preimage data will be stored in the browser's localStorage and used for any following request
 await fetchWithL402(
   "https://lsat-weather-api.getalby.repl.co/kigali",
   {},
-  { store: window.localStorage },
+  { wallet: myWallet, store: window.localStorage },
 )
   .then((res) => res.json())
   .then(console.log);
@@ -199,16 +205,16 @@ await fetchWithL402(
 import { fetchWithL402 } from "@getalby/lightning-tools/l402";
 import { NostrWebLNProvider } from "@getalby/sdk";
 
-// use a NWC WebLN provide to do the payments
+// use a NWC provider as the wallet to do the payments
 const nwc = new NostrWebLNProvider({
   nostrWalletConnectUrl: loadNWCUrl(),
 });
 
-// this will fetch the resource and pay the invoice with a NWC webln object
+// this will fetch the resource and pay the invoice using the NWC wallet
 await fetchWithL402(
   "https://lsat-weather-api.getalby.repl.co/kigali",
   {},
-  { webln: nwc },
+  { wallet: nwc },
 )
   .then((res) => res.json())
   .then(console.log);
@@ -242,6 +248,10 @@ const { paymentHash, satoshi, description, createdDate, expiryDate } = invoice;
 
 Helpers to convert sats values to fiat and fiat values to sats.
 
+##### getFiatCurrencies(): Promise<FiatCurrency[]>
+
+Returns the list of available fiat currencies sorted by priority
+
 ##### getFiatValue(satoshi: number, currency: string): number
 
 Returns the fiat value for a specified currency of a satoshi amount
@@ -257,6 +267,7 @@ Like `getFiatValue` but returns a formatted string for a given locale using Java
 #### Examples
 
 ```js
+await fiat.getFiatCurrencies();
 await fiat.getFiatValue({ satoshi: 2100, currency: "eur" });
 await fiat.getSatoshiValue({ amount: 100, currency: "eur" }); // for 1 EUR
 await fiat.getFormattedFiatValue({

package/dist/cjs/fiat.cjs

@@ -1,6 +1,26 @@
 'use strict';
 
 const numSatsInBtc = 100000000;
+const getFiatCurrencies = async () => {
+    const url = "https://getalby.com/api/rates";
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch currencies: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    const mappedCurrencies = Object.entries(data)
+        .filter(([code]) => code.toUpperCase() !== "BTC")
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        .map(([code, details]) => ({
+        code: code.toUpperCase(),
+        name: details.name,
+        priority: details.priority,
+        symbol: details.symbol,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .sort((a, b) => a.priority - b.priority);
+    return mappedCurrencies;
+};
 const getFiatBtcRate = async (currency) => {
     const url = "https://getalby.com/api/rates/" + currency.toLowerCase() + ".json";
     const response = await fetch(url);
@@ -30,6 +50,7 @@ const getFormattedFiatValue = async ({ satoshi, currency, locale, }) => {
 };
 
 exports.getFiatBtcRate = getFiatBtcRate;
+exports.getFiatCurrencies = getFiatCurrencies;
 exports.getFiatValue = getFiatValue;
 exports.getFormattedFiatValue = getFormattedFiatValue;
 exports.getSatoshiValue = getSatoshiValue;

package/dist/cjs/fiat.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"fiat.cjs","sources":["../../src/fiat/fiat.ts"],"sourcesContent":["const numSatsInBtc = 100_000_000;\n\nexport const getFiatBtcRate = async (currency: string): Promise<number> => {\n  const url =\n    \"https://getalby.com/api/rates/\" + currency.toLowerCase() + \".json\";\n  const response = await fetch(url);\n\n  if (!response.ok) {\n    throw new Error(\n      `Failed to fetch rate: ${response.status} ${response.statusText}`,\n    );\n  }\n\n  const data = await response.json();\n\n  return data.rate_float / numSatsInBtc;\n};\n\nexport const getFiatValue = async ({\n  satoshi,\n  currency,\n}: {\n  satoshi: number | string;\n  currency: string;\n}) => {\n  const rate = await getFiatBtcRate(currency);\n\n  return Number(satoshi) * rate;\n};\n\nexport const getSatoshiValue = async ({\n  amount,\n  currency,\n}: {\n  amount: number | string;\n  currency: string;\n}) => {\n  const rate = await getFiatBtcRate(currency);\n\n  return Math.floor(Number(amount) / rate);\n};\n\nexport const getFormattedFiatValue = async ({\n  satoshi,\n  currency,\n  locale,\n}: {\n  satoshi: number | string;\n  currency: string;\n  locale: string;\n}) => {\n  if (!locale) {\n    locale = \"en\";\n  }\n  const fiatValue = await getFiatValue({ satoshi, currency });\n  return fiatValue.toLocaleString(locale, {\n    style: \"currency\",\n    currency,\n  });\n};\n"],"names":[],"mappings":";;AAAA,MAAM,YAAY,GAAG,SAAW;MAEnB,cAAc,GAAG,OAAO,QAAgB,KAAqB;IACxE,MAAM,GAAG,GACP,gCAAgC,GAAG,QAAQ,CAAC,WAAW,EAAE,GAAG,OAAO;AACrE,IAAA,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC;AAEjC,IAAA,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE;AAChB,QAAA,MAAM,IAAI,KAAK,CACb,CAAA,sBAAA,EAAyB,QAAQ,CAAC,MAAM,CAAA,CAAA,EAAI,QAAQ,CAAC,UAAU,CAAA,CAAE,CAClE;IACH;AAEA,IAAA,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE;AAElC,IAAA,OAAO,IAAI,CAAC,UAAU,GAAG,YAAY;AACvC;AAEO,MAAM,YAAY,GAAG,OAAO,EACjC,OAAO,EACP,QAAQ,GAIT,KAAI;AACH,IAAA,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC;AAE3C,IAAA,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI;AAC/B;AAEO,MAAM,eAAe,GAAG,OAAO,EACpC,MAAM,EACN,QAAQ,GAIT,KAAI;AACH,IAAA,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC;IAE3C,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;AAC1C;AAEO,MAAM,qBAAqB,GAAG,OAAO,EAC1C,OAAO,EACP,QAAQ,EACR,MAAM,GAKP,KAAI;IACH,IAAI,CAAC,MAAM,EAAE;QACX,MAAM,GAAG,IAAI;IACf;IACA,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC3D,IAAA,OAAO,SAAS,CAAC,cAAc,CAAC,MAAM,EAAE;AACtC,QAAA,KAAK,EAAE,UAAU;QACjB,QAAQ;AACT,KAAA,CAAC;AACJ;;;;;;;"}
+{"version":3,"file":"fiat.cjs","sources":["../../src/fiat/fiat.ts"],"sourcesContent":["const numSatsInBtc = 100_000_000;\n\nexport interface FiatCurrency {\n  code: string;\n  name: string;\n  symbol: string;\n  priority: number;\n}\n\nexport const getFiatCurrencies = async (): Promise<FiatCurrency[]> => {\n  const url = \"https://getalby.com/api/rates\";\n  const response = await fetch(url);\n\n  if (!response.ok) {\n    throw new Error(\n      `Failed to fetch currencies: ${response.status} ${response.statusText}`,\n    );\n  }\n\n  const data = await response.json();\n  const mappedCurrencies: FiatCurrency[] = Object.entries(data)\n    .filter(([code]) => code.toUpperCase() !== \"BTC\")\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    .map(([code, details]: any) => ({\n      code: code.toUpperCase(),\n      name: details.name,\n      priority: details.priority,\n      symbol: details.symbol,\n    }))\n    .sort((a, b) => a.name.localeCompare(b.name))\n    .sort((a, b) => a.priority - b.priority) as FiatCurrency[];\n\n  return mappedCurrencies;\n};\n\nexport const getFiatBtcRate = async (currency: string): Promise<number> => {\n  const url =\n    \"https://getalby.com/api/rates/\" + currency.toLowerCase() + \".json\";\n  const response = await fetch(url);\n\n  if (!response.ok) {\n    throw new Error(\n      `Failed to fetch rate: ${response.status} ${response.statusText}`,\n    );\n  }\n\n  const data = await response.json();\n\n  return data.rate_float / numSatsInBtc;\n};\n\nexport const getFiatValue = async ({\n  satoshi,\n  currency,\n}: {\n  satoshi: number | string;\n  currency: string;\n}) => {\n  const rate = await getFiatBtcRate(currency);\n\n  return Number(satoshi) * rate;\n};\n\nexport const getSatoshiValue = async ({\n  amount,\n  currency,\n}: {\n  amount: number | string;\n  currency: string;\n}) => {\n  const rate = await getFiatBtcRate(currency);\n\n  return Math.floor(Number(amount) / rate);\n};\n\nexport const getFormattedFiatValue = async ({\n  satoshi,\n  currency,\n  locale,\n}: {\n  satoshi: number | string;\n  currency: string;\n  locale: string;\n}) => {\n  if (!locale) {\n    locale = \"en\";\n  }\n  const fiatValue = await getFiatValue({ satoshi, currency });\n  return fiatValue.toLocaleString(locale, {\n    style: \"currency\",\n    currency,\n  });\n};\n"],"names":[],"mappings":";;AAAA,MAAM,YAAY,GAAG,SAAW;AASzB,MAAM,iBAAiB,GAAG,YAAoC;IACnE,MAAM,GAAG,GAAG,+BAA+B;AAC3C,IAAA,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC;AAEjC,IAAA,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE;AAChB,QAAA,MAAM,IAAI,KAAK,CACb,CAAA,4BAAA,EAA+B,QAAQ,CAAC,MAAM,CAAA,CAAA,EAAI,QAAQ,CAAC,UAAU,CAAA,CAAE,CACxE;IACH;AAEA,IAAA,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE;AAClC,IAAA,MAAM,gBAAgB,GAAmB,MAAM,CAAC,OAAO,CAAC,IAAI;AACzD,SAAA,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,WAAW,EAAE,KAAK,KAAK;;SAE/C,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,CAAM,MAAM;AAC9B,QAAA,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE;QACxB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;AACvB,KAAA,CAAC;AACD,SAAA,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3C,SAAA,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAmB;AAE5D,IAAA,OAAO,gBAAgB;AACzB;MAEa,cAAc,GAAG,OAAO,QAAgB,KAAqB;IACxE,MAAM,GAAG,GACP,gCAAgC,GAAG,QAAQ,CAAC,WAAW,EAAE,GAAG,OAAO;AACrE,IAAA,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC;AAEjC,IAAA,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE;AAChB,QAAA,MAAM,IAAI,KAAK,CACb,CAAA,sBAAA,EAAyB,QAAQ,CAAC,MAAM,CAAA,CAAA,EAAI,QAAQ,CAAC,UAAU,CAAA,CAAE,CAClE;IACH;AAEA,IAAA,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE;AAElC,IAAA,OAAO,IAAI,CAAC,UAAU,GAAG,YAAY;AACvC;AAEO,MAAM,YAAY,GAAG,OAAO,EACjC,OAAO,EACP,QAAQ,GAIT,KAAI;AACH,IAAA,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC;AAE3C,IAAA,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI;AAC/B;AAEO,MAAM,eAAe,GAAG,OAAO,EACpC,MAAM,EACN,QAAQ,GAIT,KAAI;AACH,IAAA,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC;IAE3C,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;AAC1C;AAEO,MAAM,qBAAqB,GAAG,OAAO,EAC1C,OAAO,EACP,QAAQ,EACR,MAAM,GAKP,KAAI;IACH,IAAI,CAAC,MAAM,EAAE;QACX,MAAM,GAAG,IAAI;IACf;IACA,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC3D,IAAA,OAAO,SAAS,CAAC,cAAc,CAAC,MAAM,EAAE;AACtC,QAAA,KAAK,EAAE,UAAU;QACjB,QAAQ;AACT,KAAA,CAAC;AACJ;;;;;;;;"}

package/dist/cjs/index.cjs

@@ -1693,17 +1693,21 @@ const parseL402 = (input) => {
     }
     return keyValuePairs;
 };
+const makeAuthenticateHeader = (args) => {
+    const key = args.key || "L402";
+    return `${key} macaroon="${args.macaroon}", invoice="${args.invoice}"`;
+};
 
 const memoryStorage = new MemoryStorage();
-const HEADER_KEY = "L402"; // we have to update this to L402 at some point
+const HEADER_KEY = "L402";
 const fetchWithL402 = async (url, fetchArgs, options) => {
     if (!options) {
         options = {};
     }
     const headerKey = options.headerKey || HEADER_KEY;
-    const webln = options.webln || globalThis.webln;
-    if (!webln) {
-        throw new Error("WebLN is missing");
+    const wallet = options.wallet;
+    if (!wallet) {
+        throw new Error("wallet is missing");
     }
     const store = options.store || memoryStorage;
     if (!fetchArgs) {
@@ -1730,8 +1734,7 @@ const fetchWithL402 = async (url, fetchArgs, options) => {
     const details = parseL402(header);
     const token = details.token || details.macaroon;
     const inv = details.invoice;
-    await webln.enable();
-    const invResp = await webln.sendPayment(inv);
+    const invResp = await wallet.sendPayment(inv);
     store.setItem(url, JSON.stringify({
         token: token,
         preimage: invResp.preimage,
@@ -1742,6 +1745,26 @@ const fetchWithL402 = async (url, fetchArgs, options) => {
 };
 
 const numSatsInBtc = 100000000;
+const getFiatCurrencies = async () => {
+    const url = "https://getalby.com/api/rates";
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch currencies: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    const mappedCurrencies = Object.entries(data)
+        .filter(([code]) => code.toUpperCase() !== "BTC")
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        .map(([code, details]) => ({
+        code: code.toUpperCase(),
+        name: details.name,
+        priority: details.priority,
+        symbol: details.symbol,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .sort((a, b) => a.priority - b.priority);
+    return mappedCurrencies;
+};
 const getFiatBtcRate = async (currency) => {
     const url = "https://getalby.com/api/rates/" + currency.toLowerCase() + ".json";
     const response = await fetch(url);
@@ -1782,11 +1805,13 @@ exports.fromHexString = fromHexString;
 exports.generateZapEvent = generateZapEvent;
 exports.getEventHash = getEventHash;
 exports.getFiatBtcRate = getFiatBtcRate;
+exports.getFiatCurrencies = getFiatCurrencies;
 exports.getFiatValue = getFiatValue;
 exports.getFormattedFiatValue = getFormattedFiatValue;
 exports.getSatoshiValue = getSatoshiValue;
 exports.isUrl = isUrl;
 exports.isValidAmount = isValidAmount;
+exports.makeAuthenticateHeader = makeAuthenticateHeader;
 exports.parseKeysendResponse = parseKeysendResponse;
 exports.parseL402 = parseL402;
 exports.parseLnUrlPayResponse = parseLnUrlPayResponse;