lightning-agent 0.1.0 → 0.2.0

package/README.md

@@ -33,7 +33,9 @@ const { paid } = await wallet.waitForPayment(paymentHash, { timeoutMs: 60000 });
 
 // Pay an invoice (spend)
 const { preimage } = await wallet.payInvoice(someInvoice);
-console.log(`Paid! Preimage: ${preimage}`);
+
+// Or pay a Lightning address directly
+await wallet.payAddress('alice@getalby.com', { amountSats: 10 });
 
 // Done
 wallet.close();
@@ -85,6 +87,19 @@ const { preimage, paymentHash } = await wallet.payInvoice('lnbc50u1p...');
 
 **Options:** `{ timeoutMs: 30000 }`
 
+### `wallet.payAddress(address, opts)`
+
+Pay a Lightning address (user@domain) via LNURL-pay. Resolves the address to an invoice and pays it in one call.
+
+```javascript
+const result = await wallet.payAddress('alice@getalby.com', {
+  amountSats: 100,
+  comment: 'Great work!',  // optional
+  timeoutMs: 30000          // optional
+});
+// { preimage, paymentHash, invoice, amountSats }
+```
+
 ### `wallet.waitForPayment(paymentHash, opts?)`
 
 Poll until an invoice is paid (or timeout).
@@ -109,6 +124,15 @@ const { amountSats, network } = wallet.decodeInvoice('lnbc50u1p...');
 
 Close the relay connection. Call when done.
 
+### `resolveLightningAddress(address, amountSats, comment?)`
+
+Resolve a Lightning address to a bolt11 invoice without paying (useful for inspection).
+
+```javascript
+const { resolveLightningAddress } = require('lightning-agent');
+const { invoice, minSats, maxSats } = await resolveLightningAddress('bob@walletofsatoshi.com', 50);
+```
+
 ### `decodeBolt11(invoice)`
 
 Standalone bolt11 decoder (no wallet instance needed).
@@ -175,7 +199,7 @@ This is built for AI agents, not humans:
 
 - **Minimal deps** — just `nostr-tools` and `ws`
 - **No UI** — pure code, works in any Node.js environment
-- **Connection reuse** — maintains a single relay connection across requests
+- **Reliable connections** — fresh relay connection per request for maximum reliability
 - **Timeouts everywhere** — agents can't afford to hang
 - **Simple API** — `createInvoice` to charge, `payInvoice` to pay
 

package/bin/lightning-agent.js

@@ -10,6 +10,7 @@ Usage:
   lightning-agent balance                        Check wallet balance
   lightning-agent invoice <sats> [description]   Create an invoice
   lightning-agent pay <bolt11>                   Pay an invoice
+  lightning-agent send <address> <sats>          Pay a Lightning address
   lightning-agent decode <bolt11>                Decode an invoice (offline)
   lightning-agent wait <payment_hash> [timeout]  Wait for payment
 
@@ -21,6 +22,7 @@ Examples:
   lightning-agent balance
   lightning-agent invoice 50 "AI query fee"
   lightning-agent pay lnbc50u1p...
+  lightning-agent send alice@getalby.com 100
   lightning-agent decode lnbc50u1p...
 `.trim();
 
@@ -99,6 +101,23 @@ async function main() {
         break;
       }
 
+      case 'send': {
+        const address = args[1];
+        const sats = parseInt(args[2], 10);
+        if (!address || !address.includes('@')) {
+          console.error('Error: Lightning address required (user@domain)');
+          process.exit(1);
+        }
+        if (!sats || sats <= 0) {
+          console.error('Error: amount in sats required (positive integer)');
+          process.exit(1);
+        }
+        console.error(`Sending ${sats} sats to ${address}...`);
+        const result = await wallet.payAddress(address, { amountSats: sats });
+        console.log(`Paid! Preimage: ${result.preimage}`);
+        break;
+      }
+
       case 'wait': {
         const paymentHash = args[1];
         if (!paymentHash) {

package/lib/index.js

@@ -1,10 +1,11 @@
 'use strict';
 
-const { createWallet, parseNwcUrl, decodeBolt11, NWCWallet } = require('./wallet');
+const { createWallet, parseNwcUrl, decodeBolt11, resolveLightningAddress, NWCWallet } = require('./wallet');
 
 module.exports = {
   createWallet,
   parseNwcUrl,
   decodeBolt11,
+  resolveLightningAddress,
   NWCWallet
 };

package/lib/wallet.js

@@ -96,6 +96,57 @@ function decodeBolt11(invoice) {
   };
 }
 
+// ─── Lightning Address (LNURL-pay) resolver ───
+
+/**
+ * Resolve a Lightning address to a bolt11 invoice via LNURL-pay.
+ * Lightning address format: user@domain → https://domain/.well-known/lnurlp/user
+ * @param {string} address - Lightning address (user@domain)
+ * @param {number} amountSats - Amount in satoshis
+ * @param {string} [comment] - Optional payer comment
+ * @returns {Promise<{ invoice: string, minSats: number, maxSats: number }>}
+ */
+async function resolveLightningAddress(address, amountSats, comment) {
+  const [name, domain] = address.split('@');
+  if (!name || !domain) throw new Error('Invalid Lightning address: ' + address);
+
+  // Step 1: Fetch LNURL-pay metadata
+  const metaUrl = `https://${domain}/.well-known/lnurlp/${name}`;
+  const metaRes = await fetch(metaUrl);
+  if (!metaRes.ok) throw new Error(`LNURL fetch failed (${metaRes.status}): ${metaUrl}`);
+  const meta = await metaRes.json();
+
+  if (meta.status === 'ERROR') throw new Error('LNURL error: ' + (meta.reason || 'unknown'));
+  if (!meta.callback) throw new Error('LNURL response missing callback URL');
+
+  const minSats = Math.ceil((meta.minSendable || 1000) / 1000);
+  const maxSats = Math.floor((meta.maxSendable || 100000000000) / 1000);
+
+  if (amountSats < minSats) throw new Error(`Amount ${amountSats} below minimum ${minSats} sats`);
+  if (amountSats > maxSats) throw new Error(`Amount ${amountSats} above maximum ${maxSats} sats`);
+
+  // Step 2: Request invoice from callback
+  const amountMsats = amountSats * 1000;
+  const sep = meta.callback.includes('?') ? '&' : '?';
+  let cbUrl = `${meta.callback}${sep}amount=${amountMsats}`;
+  if (comment && meta.commentAllowed && comment.length <= meta.commentAllowed) {
+    cbUrl += `&comment=${encodeURIComponent(comment)}`;
+  }
+
+  const invoiceRes = await fetch(cbUrl);
+  if (!invoiceRes.ok) throw new Error(`LNURL callback failed (${invoiceRes.status})`);
+  const invoiceData = await invoiceRes.json();
+
+  if (invoiceData.status === 'ERROR') throw new Error('LNURL error: ' + (invoiceData.reason || 'unknown'));
+  if (!invoiceData.pr) throw new Error('LNURL response missing invoice (pr field)');
+
+  return {
+    invoice: invoiceData.pr,
+    minSats,
+    maxSats
+  };
+}
+
 // ─── NWC URL parser ───
 
 function parseNwcUrl(nwcUrl) {
@@ -295,6 +346,35 @@ class NWCWallet {
     return { paid: false, preimage: null, settledAt: null };
   }
 
+  /**
+   * Pay a Lightning address (LNURL-pay) like user@domain.com.
+   * Resolves the address to a bolt11 invoice, then pays it.
+   * @param {string} address - Lightning address (user@domain)
+   * @param {object} opts
+   * @param {number} opts.amountSats - Amount in satoshis (required)
+   * @param {string} [opts.comment] - Optional payer comment
+   * @param {number} [opts.timeoutMs] - Payment timeout
+   * @returns {Promise<{ preimage, paymentHash, invoice, amountSats }>}
+   */
+  async payAddress(address, opts = {}) {
+    if (!address || !address.includes('@')) {
+      throw new Error('Invalid Lightning address: must be user@domain');
+    }
+    if (!opts.amountSats || opts.amountSats <= 0) {
+      throw new Error('amountSats is required and must be positive');
+    }
+
+    const resolved = await resolveLightningAddress(address, opts.amountSats, opts.comment);
+    const payResult = await this.payInvoice(resolved.invoice, { timeoutMs: opts.timeoutMs || 30000 });
+
+    return {
+      preimage: payResult.preimage,
+      paymentHash: payResult.paymentHash,
+      invoice: resolved.invoice,
+      amountSats: opts.amountSats
+    };
+  }
+
   /**
    * Decode a bolt11 invoice (offline, no NWC needed).
    * @param {string} invoice - Bolt11 invoice string
@@ -327,5 +407,6 @@ module.exports = {
   createWallet,
   parseNwcUrl,
   decodeBolt11,
+  resolveLightningAddress,
   NWCWallet
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightning-agent",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Lightning payments for AI agents. Two functions: charge and pay.",
   "main": "lib/index.js",
   "bin": {

package/test.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { createWallet, parseNwcUrl, decodeBolt11, NWCWallet } = require('./lib');
+const { createWallet, parseNwcUrl, decodeBolt11, resolveLightningAddress, NWCWallet } = require('./lib');
 
 let passed = 0;
 let failed = 0;
@@ -118,6 +118,32 @@ const decoded = wallet.decodeInvoice('lnbc50u1ptest');
 assert(decoded.amountSats === 5000, 'wallet.decodeInvoice works');
 wallet.close();
 
+// ─── Lightning Address tests ───
+console.log('\n⚡ Lightning Address');
+
+assert(typeof resolveLightningAddress === 'function', 'resolveLightningAddress is exported');
+
+// Wallet has payAddress method
+const walletForAddr = createWallet(testNwcUrl);
+assert(typeof walletForAddr.payAddress === 'function', 'wallet has payAddress()');
+walletForAddr.close();
+
+// payAddress validation
+const walletForAddrTest = createWallet(testNwcUrl);
+
+// Test via promise catches
+const addrTests = Promise.all([
+  walletForAddrTest.payAddress('invalid', { amountSats: 10 })
+    .then(() => assert(false, 'payAddress rejects invalid address'))
+    .catch(e => assert(e.message.includes('Invalid Lightning address'), 'payAddress rejects invalid address')),
+  walletForAddrTest.payAddress('user@domain.com', {})
+    .then(() => assert(false, 'payAddress requires amountSats'))
+    .catch(e => assert(e.message.includes('amountSats'), 'payAddress requires amountSats')),
+  walletForAddrTest.payAddress('user@domain.com', { amountSats: -5 })
+    .then(() => assert(false, 'payAddress rejects negative amount'))
+    .catch(e => assert(e.message.includes('amountSats'), 'payAddress rejects negative amount')),
+]).then(() => walletForAddrTest.close());
+
 // createWallet from env
 console.log('\n🌍 createWallet from env');
 process.env.NWC_URL = testNwcUrl;
@@ -128,11 +154,13 @@ delete process.env.NWC_URL;
 
 assertThrows(() => createWallet(), 'createWallet() throws without URL or env');
 
-// ─── Summary ───
-console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-console.log(`Results: ${passed} passed, ${failed} failed`);
-if (failed > 0) {
-  process.exit(1);
-} else {
-  console.log('All tests passed! ✅');
-}
+// ─── Summary (wait for async tests) ───
+addrTests.then(() => {
+  console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+  console.log(`Results: ${passed} passed, ${failed} failed`);
+  if (failed > 0) {
+    process.exit(1);
+  } else {
+    console.log('All tests passed! ✅');
+  }
+});