lightning-auth-and-payment/examples/nextjs-complete/README.md

Lightning Network authentication and payment processing library for modern web applications

# ⚡ Lightning Auth Complete Example

A comprehensive Next.js application demonstrating Lightning Network authentication and payments using the `lightning-auth-and-payment` library.

## 🚀 Features

- **Lightning Authentication**: Login with Lightning Network wallets
- **Lightning Payments**: Accept payments via BTCPay Server
- **Database Integration**: Prisma with SQLite/PostgreSQL support
- **Zero-Config Setup**: Automatic API route generation
- **Modern UI**: Tailwind CSS with responsive design
- **Type Safety**: Full TypeScript support

## 📋 Prerequisites

- Node.js 18+ 
- npm or yarn
- Lightning Network wallet (Alby, Zeus, etc.)
- BTCPay Server (for payments)

## 🛠️ Quick Start

### 1. Install Dependencies

```bash
npm install
```

### 2. Environment Setup

Copy the environment template:

```bash
cp env.example .env.local
```

Edit `.env.local` with your configuration:

```env
# Lightning Network Configuration
SESSION_SECRET=your-super-secret-session-key-here-make-it-long-and-random
NEXT_PUBLIC_APP_URL=https://localhost:3443
NODE_ENV=development

# Database Configuration
DATABASE_URL="file:./dev.db"

# 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
```

### 3. Database Setup

#### Option A: SQLite (Default)

```bash
# Generate Prisma client
npm run db:generate

# Run migrations
npm run db:migrate

# Seed with sample data
npm run db:seed
```

#### Option B: PostgreSQL

1. Update `.env.local`:
```env
DATABASE_URL="postgresql://username:password@localhost:5432/lightning_auth_example"
```

2. Update `prisma/schema.prisma`:
```prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}
```

3. Run database setup:
```bash
npm run db:generate
npm run db:migrate
npm run db:seed
```

### 4. Start Development

```bash
# Start Lightning development server with HTTPS
npm run dev:lightning
```

Open [https://localhost:3443](https://localhost:3443) in your browser.

## 🗄️ Database Configuration

### SQLite (Default)

SQLite is perfect for development and small applications:

```env
DATABASE_URL="file:./dev.db"
```

**Pros:**
- Zero configuration
- File-based database
- Perfect for development
- No external dependencies

**Cons:**
- Limited concurrent writes
- Not suitable for production scale

### PostgreSQL

PostgreSQL is recommended for production applications:

```env
DATABASE_URL="postgresql://username:password@localhost:5432/lightning_auth_example"
```

**Setup:**
1. Install PostgreSQL
2. Create database: `createdb lightning_auth_example`
3. Update connection string
4. Run migrations: `npm run db:migrate`

**Pros:**
- Production-ready
- Excellent performance
- ACID compliance
- Advanced features

**Cons:**
- Requires external database server
- More complex setup

## 🔧 Available Scripts

```bash
# Development
npm run dev              # Standard Next.js dev server
npm run dev:lightning    # Lightning dev server with HTTPS

# Database
npm run db:generate      # Generate Prisma client
npm run db:migrate       # Run database migrations
npm run db:reset         # Reset database
npm run db:seed          # Seed with sample data
npm run db:setup         # Complete database setup
npm run db:studio        # Open Prisma Studio

# Production
npm run build           # Build for production
npm run start           # Start production server
```

## 📁 Project Structure

```
src/
├── app/                    # Next.js app directory
│   ├── layout.tsx         # Root layout with LightningProvider
│   ├── page.tsx           # Home page
│   └── globals.css        # Global styles
├── components/            # React components
│   ├── LightningLogin.tsx # Authentication component
│   └── ProductCatalog.tsx # Product catalog with payments
└── lib/                   # Utilities
    ├── db.ts              # Prisma client
    └── database-adapter.ts # Lightning auth database adapter

prisma/
├── schema.prisma          # Database schema
└── seed.ts               # Database seeding script
```

## 🔐 Authentication Flow

1. User clicks "Login with Lightning"
2. System generates LNURL challenge
3. User scans QR code with Lightning wallet
4. Wallet signs challenge and returns response
5. System verifies signature and creates session
6. User is authenticated and can make purchases

## 💳 Payment Flow

1. Authenticated user selects product
2. System creates BTCPay Server invoice
3. User pays with Lightning wallet
4. BTCPay Server confirms payment
5. System updates order status
6. User receives product access

## 🎨 Customization

### Styling

The example uses Tailwind CSS. Customize in `tailwind.config.js`:

```javascript
module.exports = {
  theme: {
    extend: {
      colors: {
        orange: {
          500: '#f97316',
          600: '#ea580c',
        },
      },
    },
  },
};
```

### Components

All components are in `src/components/`. They use the `lightning-auth-and-payment` library:

```typescript
import { useLightningAuth, BTCPayPaymentModal } from 'lightning-auth-and-payment';
```

### Database Schema

The Prisma schema includes all necessary models for Lightning authentication and payments. Customize in `prisma/schema.prisma`.

## 🚀 Deployment

### Vercel (Recommended)

1. Connect your GitHub repository to Vercel
2. Set environment variables in Vercel dashboard
3. Deploy automatically on push

### Environment Variables for Production

```env
# Required
SESSION_SECRET=your-production-secret-key
DATABASE_URL=your-production-database-url
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

# Optional
NEXT_PUBLIC_APP_URL=https://your-domain.com
NODE_ENV=production
```

## 🔍 Troubleshooting

### Common Issues

1. **Database connection errors**: Check `DATABASE_URL` format
2. **HTTPS certificate errors**: Use `npm run dev:lightning` for development
3. **BTCPay Server errors**: Verify API credentials and server status
4. **Lightning wallet connection**: Ensure wallet supports LNURL-auth

### Debug Mode

Enable debug logging by setting:

```env
NODE_ENV=development
```

## 📚 Learn More

- [Lightning Auth & Payment Library](https://github.com/erich-mueller/lightning-auth-and-payment)
- [Next.js Documentation](https://nextjs.org/docs)
- [Prisma Documentation](https://www.prisma.io/docs)
- [BTCPay Server Documentation](https://docs.btcpayserver.org/)
- [Lightning Network Documentation](https://lightning.network/)

## 🤝 Contributing

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

## 📄 License

MIT License - see LICENSE file for details.