lightning-agent 0.3.3 → 0.4.0

package/README.md

@@ -53,6 +53,44 @@ wallet.close();
 
 ---
 
+## Batch Payments
+
+Pay multiple invoices or addresses in parallel with concurrency control:
+
+```javascript
+const wallet = createWallet('nostr+walletconnect://...');
+
+// Pay multiple invoices at once
+const { results, successCount, totalSats } = await wallet.payBatch([
+  'lnbc100n1...',
+  'lnbc200n1...',
+  'lnbc300n1...'
+], {
+  concurrency: 3,      // Max parallel payments
+  stopOnError: false   // Continue even if one fails
+});
+
+console.log(`Paid ${successCount} invoices, total ${totalSats} sats`);
+
+// Pay multiple Lightning addresses
+const { results: addrResults } = await wallet.payAddresses([
+  { address: 'alice@getalby.com', amountSats: 50, comment: 'Thanks!' },
+  { address: 'bob@walletofsatoshi.com', amountSats: 100 },
+  { address: 'carol@strike.me', amountSats: 75 }
+], { concurrency: 2 });
+
+// Check individual results
+for (const r of results) {
+  if (r.success) {
+    console.log(`✓ Paid ${r.amountSats} sats, preimage: ${r.preimage}`);
+  } else {
+    console.log(`✗ Failed: ${r.error}`);
+  }
+}
+```
+
+---
+
 ## Auth (LNURL-auth)
 
 Login with a Lightning wallet. No passwords, no OAuth — just a signed cryptographic challenge.

package/lib/wallet.js

@@ -385,6 +385,142 @@ class NWCWallet {
     return decodeBolt11(invoice);
   }
 
+  /**
+   * Pay multiple invoices in parallel with concurrency control.
+   * @param {string[]} invoices - Array of bolt11 invoice strings
+   * @param {object} [opts]
+   * @param {number} [opts.concurrency=3] - Max concurrent payments
+   * @param {number} [opts.timeoutMs=30000] - Timeout per payment
+   * @param {boolean} [opts.stopOnError=false] - Stop all payments on first error
+   * @returns {Promise<{ results: Array<{invoice, success, preimage?, error?}>, successCount, failedCount, totalSats }>}
+   */
+  async payBatch(invoices, opts = {}) {
+    if (!Array.isArray(invoices) || invoices.length === 0) {
+      throw new Error('invoices array is required');
+    }
+
+    const concurrency = opts.concurrency || 3;
+    const timeoutMs = opts.timeoutMs || 30000;
+    const stopOnError = opts.stopOnError || false;
+
+    const results = [];
+    let totalSats = 0;
+    let stopped = false;
+
+    // Process in chunks
+    for (let i = 0; i < invoices.length && !stopped; i += concurrency) {
+      const chunk = invoices.slice(i, i + concurrency);
+      
+      const chunkResults = await Promise.all(
+        chunk.map(async (invoice) => {
+          if (stopped) return { invoice, success: false, error: 'Batch stopped' };
+          
+          try {
+            const decoded = decodeBolt11(invoice);
+            const result = await this.payInvoice(invoice, { timeoutMs });
+            totalSats += decoded.amountSats || 0;
+            return {
+              invoice,
+              success: true,
+              preimage: result.preimage,
+              paymentHash: result.paymentHash,
+              amountSats: decoded.amountSats
+            };
+          } catch (err) {
+            if (stopOnError) stopped = true;
+            return {
+              invoice,
+              success: false,
+              error: err.message
+            };
+          }
+        })
+      );
+      
+      results.push(...chunkResults);
+    }
+
+    const successCount = results.filter(r => r.success).length;
+    const failedCount = results.length - successCount;
+
+    return {
+      results,
+      successCount,
+      failedCount,
+      totalSats
+    };
+  }
+
+  /**
+   * Pay multiple Lightning addresses in parallel.
+   * @param {Array<{address: string, amountSats: number, comment?: string}>} payments
+   * @param {object} [opts]
+   * @param {number} [opts.concurrency=3] - Max concurrent payments
+   * @param {number} [opts.timeoutMs=30000] - Timeout per payment
+   * @param {boolean} [opts.stopOnError=false] - Stop all payments on first error
+   * @returns {Promise<{ results: Array, successCount, failedCount, totalSats }>}
+   */
+  async payAddresses(payments, opts = {}) {
+    if (!Array.isArray(payments) || payments.length === 0) {
+      throw new Error('payments array is required');
+    }
+
+    const concurrency = opts.concurrency || 3;
+    const timeoutMs = opts.timeoutMs || 30000;
+    const stopOnError = opts.stopOnError || false;
+
+    const results = [];
+    let totalSats = 0;
+    let stopped = false;
+
+    for (let i = 0; i < payments.length && !stopped; i += concurrency) {
+      const chunk = payments.slice(i, i + concurrency);
+      
+      const chunkResults = await Promise.all(
+        chunk.map(async (payment) => {
+          if (stopped) return { address: payment.address, success: false, error: 'Batch stopped' };
+          
+          try {
+            const result = await this.payAddress(payment.address, {
+              amountSats: payment.amountSats,
+              comment: payment.comment,
+              timeoutMs
+            });
+            totalSats += payment.amountSats;
+            return {
+              address: payment.address,
+              success: true,
+              preimage: result.preimage,
+              paymentHash: result.paymentHash,
+              invoice: result.invoice,
+              amountSats: payment.amountSats
+            };
+          } catch (err) {
+            if (stopOnError) stopped = true;
+            return {
+              address: payment.address,
+              success: false,
+              error: err.message,
+              amountSats: payment.amountSats
+            };
+          }
+        })
+      );
+      
+      results.push(...chunkResults);
+    }
+
+    const successCount = results.filter(r => r.success).length;
+    const failedCount = results.length - successCount;
+
+    return {
+      results,
+      successCount,
+      failedCount,
+      totalSats
+    };
+  }
+
   /**
    * Close the relay connection.
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightning-agent",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Lightning toolkit for AI agents. Payments, auth, escrow, and streaming micropayments.",
   "main": "lib/index.js",
   "bin": {

package/test.js

@@ -154,8 +154,36 @@ delete process.env.NWC_URL;
 
 assertThrows(() => createWallet(), 'createWallet() throws without URL or env');
 
+// ─── Batch Payment Methods ───
+console.log('\n📦 Batch Payment Methods');
+
+const walletForBatch = createWallet(testNwcUrl);
+
+// payBatch validation
+const batchTests = Promise.all([
+  // Test empty array
+  walletForBatch.payBatch([])
+    .then(() => assert(false, 'payBatch rejects empty array'))
+    .catch(e => assert(e.message.includes('required'), 'payBatch rejects empty array')),
+  
+  // Test non-array
+  walletForBatch.payBatch('not an array')
+    .then(() => assert(false, 'payBatch rejects non-array'))
+    .catch(e => assert(e.message.includes('required'), 'payBatch rejects non-array')),
+    
+  // payAddresses validation
+  walletForBatch.payAddresses([])
+    .then(() => assert(false, 'payAddresses rejects empty array'))
+    .catch(e => assert(e.message.includes('required'), 'payAddresses rejects empty array')),
+]).then(() => {
+  // Test that methods exist with correct signatures
+  assert(typeof walletForBatch.payBatch === 'function', 'payBatch method exists');
+  assert(typeof walletForBatch.payAddresses === 'function', 'payAddresses method exists');
+  walletForBatch.close();
+});
+
 // ─── Summary (wait for async tests) ───
-addrTests.then(() => {
+Promise.all([addrTests, batchTests]).then(() => {
   console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━`);
   console.log(`Results: ${passed} passed, ${failed} failed`);
   if (failed > 0) {