JSPM

  • Created
  • Published
  • Downloads 372
  • Score
    100M100P100Q125149F
  • License MIT

Lightning Network authentication and payment processing library for modern web applications

Package Exports

  • lightning-auth-and-payment
  • lightning-auth-and-payment/dev

Readme

โšก Lightning Auth & Payment

npm version License: MIT TypeScript Lightning Network

The complete Lightning Network authentication and payment solution for modern web applications

Build Lightning Network-powered applications with ease. From simple single-page shops to complex eCommerce platforms, Lightning Auth & Payment provides everything you need for Lightning Network integration.

๐Ÿš€ Quick Start

For AI Agents (Cursor, etc.)

Use our AI Setup Guide - copy and paste a single prompt to automatically configure everything.

Manual Installation

npm install lightning-auth-and-payment

๐ŸŽฏ Core Features

โœ… Lightning Authentication

  • LNURL-auth protocol - Industry standard Lightning authentication
  • QR Code generation - Works with any Lightning wallet
  • Session management - Secure JWT-based sessions
  • Wallet compatibility - Alby, Phoenix, Breez, Zeus, and more

โœ… Lightning Payments

  • BTCPay Server integration - Real Lightning invoices
  • Automatic polling - Payment status detection
  • QR Code payments - Mobile wallet support
  • Success handling - User-friendly payment confirmation

โœ… Development Experience

  • Local HTTPS server - SSL certificates for wallet compatibility
  • TypeScript support - Full type safety
  • React components - Ready-to-use UI components
  • Hot reload - Fast development iteration

๐Ÿ“ฆ What's Included

๐Ÿ” Authentication

import { LightningAuth, useAuth } from 'lightning-auth-and-payment';

// Server-side authentication
const auth = new LightningAuth({
  sessionSecret: process.env.SESSION_SECRET!,
  lnurlStore: new MemoryLnurlStore(),
});

// Client-side authentication
const { isAuthenticated, login, logout, user } = useAuth();

๐Ÿ’ณ Payments

import { BTCPayPaymentModal, createBTCPayService } from 'lightning-auth-and-payment';

// Payment modal component
<BTCPayPaymentModal
  isOpen={showPayment}
  onClose={() => setShowPayment(false)}
  amount={1000}
  description="Purchase item"
  onPaymentSuccess={() => console.log('Payment successful!')}
  autoCloseDelay={3000}
  successMessage="Payment confirmed!"
/>

// BTCPay service
const btcpayService = createBTCPayService();
const invoice = await btcpayService.createInvoice({
  amount: 1000,
  currency: 'SATS',
  description: 'Purchase item',
});

๐ŸŽจ UI Components

import { 
  AuthHeader, 
  BTCPayPaymentModal, 
  Button, 
  Card 
} from 'lightning-auth-and-payment';

// Pre-built components with Lightning Network styling
<AuthHeader />
<Button onClick={handlePayment}>Buy Now</Button>
<Card>Your content here</Card>

๐Ÿ› ๏ธ Environment Setup

Create .env.local:

# Session Configuration
SESSION_SECRET=your-super-secret-session-key-here-make-it-long-and-random
SESSION_COOKIE_DOMAIN=localhost

# BTCPay Server Configuration (required for payments)
BTCPAY_HOST=https://your-btcpay-server.com
BTCPAY_STORE_ID=your-store-id
BTCPAY_API_KEY=your-api-key
BTCPAY_WEBHOOK_SECRET=your-webhook-secret

# Application Configuration
NEXT_PUBLIC_APP_URL=https://localhost:3443
NODE_ENV=development

๐Ÿ—๏ธ API Routes

The library provides utility functions for common API routes:

// Authentication routes
import { LightningAuth } from 'lightning-auth-and-payment';

// Payment routes  
import { createBTCPayService } from 'lightning-auth-and-payment';

// Session management
import { getSession, createSession } from 'lightning-auth-and-payment';

๐Ÿ”ง Development Server

Start the Lightning development server with HTTPS support:

npm run dev:lightning

This provides:

  • โœ… HTTPS with trusted SSL certificates
  • โœ… Wallet-compatible LNURL endpoints
  • โœ… Hot reload and debugging
  • โœ… Automatic certificate management

๐Ÿ“ฑ Wallet Compatibility

Desktop Wallets

  • Alby - Browser extension (recommended for development)
  • Phoenix - Desktop Lightning wallet
  • Breez - Mobile/desktop Lightning wallet

Mobile Wallets

  • Phoenix - iOS/Android Lightning wallet
  • Breez - Mobile Lightning wallet
  • Zeus - Advanced Lightning wallet
  • Wallet of Satoshi - Simple Lightning wallet

๐ŸŽจ UI Components

Authentication Components

import { AuthHeader, useAuth } from 'lightning-auth-and-payment';

function MyApp() {
  const { isAuthenticated, login, logout } = useAuth();
  
  return (
    <AuthHeader 
      onLogin={login}
      onLogout={logout}
      isAuthenticated={isAuthenticated}
    />
  );
}

Payment Components

import { BTCPayPaymentModal } from 'lightning-auth-and-payment';

function PaymentButton() {
  const [showPayment, setShowPayment] = useState(false);
  
  return (
    <BTCPayPaymentModal
      isOpen={showPayment}
      onClose={() => setShowPayment(false)}
      amount={1000}
      description="Purchase item"
      onPaymentSuccess={() => {
        // Handle successful payment
        setShowPayment(false);
      }}
      autoCloseDelay={3000}
      successMessage="Payment confirmed!"
    />
  );
}

Utility Components

import { 
  Button, 
  Card, 
  Badge, 
  Dialog 
} from 'lightning-auth-and-payment';

// Pre-styled components with Lightning Network theming
<Button variant="primary">Lightning Button</Button>
<Card>Lightning Card</Card>
<Badge variant="success">Success</Badge>

๐Ÿ” Hooks

Authentication Hooks

import { 
  useAuth,
  useLightningAuth,
  useSession 
} from 'lightning-auth-and-payment';

// Enhanced authentication with all features
const { isAuthenticated, login, logout, user, isLoading } = useAuth();

// Basic Lightning authentication
const { lnurl, showModal, login, closeModal } = useLightningAuth();

// Session management
const { session, refreshSession } = useSession();

Payment Hooks

import { 
  useBTCPayPayment,
  useLightningPayment 
} from 'lightning-auth-and-payment';

// BTCPay Server payments
const { 
  paymentState, 
  createInvoice, 
  copyBolt11 
} = useBTCPayPayment();

// Basic Lightning payments
const { 
  createPayment, 
  paymentStatus, 
  resetPayment 
} = useLightningPayment();

Utility Hooks

import { 
  useCopyToClipboard,
  useCountdown,
  useDebounce,
  useLocalStorage 
} from 'lightning-auth-and-payment';

// Copy to clipboard
const { copied, copy } = useCopyToClipboard();

// Countdown timer
const { timeLeft, isExpired } = useCountdown(targetDate);

// Debounced values
const debouncedValue = useDebounce(value, 500);

// Local storage
const [storedValue, setStoredValue] = useLocalStorage('key', defaultValue);

๐Ÿช E-Commerce Features

import { 
  ECommerceManager,
  OrderManager,
  ProductManager 
} from 'lightning-auth-and-payment';

// E-commerce management
const ecommerce = new ECommerceManager();
const orders = new OrderManager();
const products = new ProductManager();

๐Ÿงช Testing

import { 
  createTestAuth,
  createTestStore,
  mockUser,
  mockInvoice 
} from 'lightning-auth-and-payment/testing';

// Test utilities
const testAuth = createTestAuth();
const testStore = createTestStore();
const user = mockUser();
const invoice = mockInvoice();

๐Ÿ“š Examples

Check out the examples directory for complete implementations:

  • Next.js App Router - Modern Next.js 13+ with App Router
  • Express.js - Traditional Express.js server
  • E-commerce - Complete shopping cart implementation

๐Ÿค Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

๐Ÿ“„ License

MIT License - see LICENSE for details.

๐Ÿ†˜ Support

๐ŸŽฏ Roadmap

  • WebLN integration for browser wallets
  • Lightning Address support
  • Multi-currency support
  • Advanced payment flows
  • Mobile app templates

Built with โšก for the Lightning Network