@bringinxyz/lnurl-pay

Enhanced LNURL Pay with Bringin POS mode support for Lightning micro-payments

Official Bringin library for Lightning Network micro-payments

⚡ Micro-Payments Enabled!

| Mode | Minimum Payment | Use Case | |------|----------------|----------| | Standard | 22,000+ sats (~$6-10) | Manual wallet payments | | POS Mode | 20+ sats (~$0.01) | Micro-transactions, tips, small purchases |

21,980 sats reduction = 99.9% lower minimums!

Quick Start

const lnurlPay = require('@bringinxyz/lnurl-pay');

// ❌ This would fail with standard mode (below 22k sats minimum)
// ✅ This works with POS mode!
const microPayment = await lnurlPay.requestInvoice({
  lnUrlOrAddress: '[email protected]',
  tokens: 100,        // Just 100 sats! 
  posMode: true,      // Enable micro-payments
  comment: 'Coffee tip'
});

console.log('Micro-payment invoice:', microPayment.invoice);

🚀 Features

• Drop-in Compatibility: Works exactly like lnurl-pay - no code changes needed
• Micro-Payment Support: Enable payments as low as 20 sats vs 22,000+ sats
• Smart HTTP Client: Auto-detects fetch vs axios for optimal performance
• TypeScript Support: Full type definitions included
• Production Ready: Comprehensive error handling and validation
• Real-World Tested: Successfully tested with live Bringin endpoints

📦 Installation

# For Node 18+ (built-in fetch)
npm install @bringinxyz/lnurl-pay

# For older Node versions
npm install @bringinxyz/lnurl-pay axios

🔄 Migration from lnurl-pay

Migrating from lnurl-pay to @bringinxyz/lnurl-pay is seamless:

Before (lnurl-pay)

const lnurlPay = require('lnurl-pay');

const invoice = await lnurlPay.requestInvoice({
  lnUrlOrAddress: '[email protected]',
  tokens: 25000
});

After (@bringinxyz/lnurl-pay)

const lnurlPay = require('@bringinxyz/lnurl-pay');

// Same code works + new POS mode capability!
const invoice = await lnurlPay.requestInvoice({
  lnUrlOrAddress: '[email protected]',
  tokens: 100,        // Now possible with posMode!
  posMode: true       // NEW: Enable micro-payments
});

That's it! Just change the require statement and optionally add posMode: true for micro-payments.

📖 Usage Examples

Basic Usage (Drop-in Replacement)

const lnurlPay = require('@bringinxyz/lnurl-pay');

// Standard usage - exactly same as lnurl-pay
const invoice = await lnurlPay.requestInvoice({
  lnUrlOrAddress: '[email protected]',
  tokens: 25000
});

console.log('Works exactly like lnurl-pay:', invoice.invoice);

Micro-Payments with POS Mode

// Micro-payment that would be impossible with standard mode
const microInvoice = await lnurlPay.requestInvoice({
  lnUrlOrAddress: '[email protected]',
  tokens: 50,         // 50 sats vs 22,000 sats minimum!
  posMode: true,      // This makes it possible
  comment: 'Small tip'
});

console.log('Micro-payment invoice:', microInvoice.invoice);

Side-by-Side Comparison

// Get standard mode parameters
const standard = await lnurlPay.requestPayServiceParams({
  lnUrlOrAddress: '[email protected]',
  posMode: false
});

// Get POS mode parameters  
const pos = await lnurlPay.requestPayServiceParams({
  lnUrlOrAddress: '[email protected]',
  posMode: true
});

console.log('Standard minimum:', standard.min, 'sats');
console.log('POS minimum:', pos.min, 'sats');
console.log('Reduction:', standard.min - pos.min, 'sats');
console.log('Percentage improvement:', 
  ((standard.min - pos.min) / standard.min * 100).toFixed(1) + '%');

Two-Step Process

// Step 1: Get service parameters
const params = await lnurlPay.requestPayServiceParams({
  lnUrlOrAddress: '[email protected]',
  posMode: true
});

// Step 2: Request invoice using the parameters
const invoice = await lnurlPay.requestInvoiceWithServiceParams({
  params: params,
  tokens: 75
});

🧪 Testing

Run the comprehensive test suite:

# Run integration tests
npm test

# Run examples
npm run example:basic
npm run example:pos
npm run example:comparison

📚 API Documentation

See docs/API.md for complete API documentation including:

• Full function reference
• Data types and interfaces
• Error handling guide
• Best practices
• Migration examples

🔧 Configuration

HTTP Client Selection

The library automatically chooses the best HTTP client:

• Node.js 18+: Uses built-in fetch API
• Node.js 14-17: Uses axios (if installed)
• Browser: Uses built-in fetch API

Timeout Configuration

const invoice = await lnurlPay.requestInvoice({
  lnUrlOrAddress: '[email protected]',
  tokens: 100,
  posMode: true,
  timeout: 15000  // 15 second timeout
});

🛡️ Error Handling

The library provides clear, actionable error messages:

try {
  const invoice = await lnurlPay.requestInvoice({
    lnUrlOrAddress: '[email protected]',
    tokens: 10,
    posMode: true
  });
} catch (error) {
  if (error.message.includes('Amount too small')) {
    console.log('Amount is below minimum');
  } else if (error.message.includes('Invalid Lightning address')) {
    console.log('Invalid address format');
  } else {
    console.log('Network or service error:', error.message);
  }
}

🌟 Key Benefits

For Developers

• Zero Migration Cost: Existing lnurl-pay code works unchanged
• Enhanced Capabilities: Add micro-payment support with one parameter
• TypeScript Ready: Full type definitions for better development experience
• Production Quality: Comprehensive error handling and validation

For Users

• Micro-Payments: Pay as little as 20 sats instead of 22,000+ sats
• Lower Barriers: Enable tips, small purchases, and micro-transactions
• Same Experience: Works with existing Lightning wallets and apps

For Merchants

• New Revenue Streams: Accept micro-payments for digital content
• Better UX: No minimum payment barriers for small purchases
• Lightning Fast: Instant settlement for micro-transactions

🏢 Professional Branding

As an official Bringin package, @bringinxyz/lnurl-pay provides:

• Guaranteed Quality: Official Bringin development standards
• Long-term Support: Backed by the Bringin team
• Package Discovery: Easy to find under @bringinxyz namespace
• Trust Factor: Users know it's the official Bringin package
• Future Growth: Part of the Bringin ecosystem

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• GitHub Issues: https://github.com/bringinxyz/lnurl-pay/issues
• Documentation: https://github.com/bringinxyz/lnurl-pay#readme
• NPM Package: https://www.npmjs.com/package/@bringinxyz/lnurl-pay
• Company Website: https://bringin.xyz

🙏 Acknowledgments

• Built on top of the excellent lnurl-pay library
• Powered by Bringin's POS mode technology
• Community feedback and testing

Ready to enable micro-payments? Install @bringinxyz/lnurl-pay today and unlock 99.9% lower minimum payments! ⚡