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

Lightning Network authentication and payment processing library for modern web applications

# Lightning Auth and Payment Examples

This directory contains comprehensive examples showing how to use `lightning-auth-and-payment` in different scenarios and frameworks.

## 📁 Examples Overview

### 🚀 [Next.js Full Example](./nextjs/)
**Complete Lightning Network integration with Next.js**
- ⚡ Authentication + Payments
- 🔧 Auto-generated API routes
- 🗄️ Automatic Prisma schema
- 💳 BTCPay Server integration
- 📱 Mobile wallet support

**Perfect for:** Full-featured Lightning applications, e-commerce, content platforms

### 🎯 [Next.js Complete Example](./nextjs-complete/)
**Comprehensive Next.js application with database integration**
- ⚡ Authentication + Payments
- 🗄️ SQLite & PostgreSQL support
- 🔧 Complete database setup
- 📚 Detailed documentation
- 🛠️ Setup scripts included
- 🎨 Modern UI with Tailwind CSS

**Perfect for:** Learning, production applications, complex integrations

### 🔐 [Auth Only Example](./auth-only/)
**Lightning authentication without payments**
- ⚡ Lightning wallet authentication
- 🔐 No passwords required
- 📱 QR code login
- 🚫 No payment processing

**Perfect for:** Secure login systems, API authentication, admin panels, member areas

### 💳 [Payment Only Example](./payment-only/)
**Lightning payments without authentication**
- ⚡ Lightning Network payments
- 💳 BTCPay Server integration
- 📱 QR code payments
- 🚫 No user accounts

**Perfect for:** Donation systems, product sales, service payments, event tickets

### ⚛️ [React Example](./react/)
**React application with Lightning integration**
- ⚡ Authentication + Payments
- 🎨 Custom UI components
- 📱 Mobile wallet support
- 🔧 Manual API integration

**Perfect for:** React applications, custom UIs, SPAs

### 🚀 [Express.js Example](./express/)
**Express.js server with Lightning integration**
- ⚡ Authentication + Payments
- 🔧 Manual API route setup
- 📱 Mobile wallet support
- 🗄️ Database integration

**Perfect for:** Node.js APIs, microservices, backend services

## 🎯 Choosing the Right Example

| Use Case | Recommended Example | Why |
|----------|-------------------|-----|
| **Full Lightning App** | Next.js Full | Complete integration, auto-generated routes |
| **Secure Login Only** | Auth Only | Clean authentication without payments |
| **Payment Processing** | Payment Only | Simple payments without user accounts |
| **React SPA** | React | Custom UI with Lightning integration |
| **Node.js API** | Express.js | Manual control over API routes |

## 🚀 Quick Start

1. **Choose your example:**
   ```bash
   cd examples/nextjs  # or auth-only, payment-only, react, express
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Configure environment:**
   ```bash
   cp .env.example .env.local
   # Edit .env.local with your configuration
   ```

4. **Start development:**
   ```bash
   npm run dev:lightning  # For Next.js examples
   npm run dev           # For React/Express examples
   ```

## 🔧 Configuration Options

### Next.js Plugin Configuration

**Full Lightning Integration (Auth + Payments):**
```javascript
// next.config.js
import { withLightning } from 'lightning-auth-and-payment/nextjs';

export default withLightning({
  database: 'prisma',
  storage: 'database',
  btcpay: true,
  development: true,
})(nextConfig);
```

**Authentication Only:**
```javascript
// next.config.js
import { withLightningAuth } from 'lightning-auth-and-payment/nextjs';

export default withLightningAuth({
  database: 'prisma',
  storage: 'database',
  development: true,
})(nextConfig);
```

**Payments Only:**
```javascript
// next.config.js
import { withLightningPayment } from 'lightning-auth-and-payment/nextjs';

export default withLightningPayment({
  database: 'prisma',
  storage: 'database',
  btcpay: true,
  development: true,
})(nextConfig);
```

### Environment Variables
```env
# Required for all examples
SESSION_SECRET=your-super-secret-key-here
SESSION_COOKIE_DOMAIN=localhost
DATABASE_URL="file:./prisma/dev.db"

# Required for payment examples
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
```

## 🎯 Next.js Complete Example

The `nextjs-complete` example is the most comprehensive and includes:

### Features
- **Complete Database Setup**: SQLite and PostgreSQL support
- **Detailed Documentation**: Step-by-step setup guides
- **Setup Scripts**: Automated configuration
- **Modern UI**: Tailwind CSS with responsive design
- **Production Ready**: Includes deployment considerations

### Quick Start
```bash
cd examples/nextjs-complete
npm install
./setup.sh
npm run dev:lightning
```

### Database Options

**SQLite (Default)**:
```env
DATABASE_URL="file:./dev.db"
```

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

### Documentation
- [Complete Setup Guide](./nextjs-complete/README.md)
- [Database Configuration](./nextjs-complete/DATABASE_SETUP.md)
- [Production Deployment](./nextjs-complete/README.md#deployment)

## 📚 What Each Example Includes

### Next.js Examples
- ✅ **Auto-generated API routes** - No manual coding needed
- ✅ **Automatic Prisma schema** - Database schema generated automatically
- ✅ **HTTPS development server** - SSL certificates for Lightning wallets
- ✅ **TypeScript support** - Full type safety
- ✅ **Hot reloading** - Fast development

### React Example
- ✅ **Custom UI components** - Full control over design
- ✅ **Lightning hooks** - Easy state management
- ✅ **Payment modals** - Ready-to-use payment UI
- ✅ **QR code generation** - Mobile wallet support

### Express.js Example
- ✅ **Manual API setup** - Full control over routes
- ✅ **Database integration** - Flexible database options
- ✅ **Middleware support** - Custom middleware integration
- ✅ **Production ready** - Easy deployment

## 🛠️ Development Features

### HTTPS Development Server
All examples include the `lightning-dev-server` for local HTTPS development:
```bash
npm run dev:lightning
```

This provides:
- 🔒 SSL certificates for Lightning wallets
- 📱 Mobile wallet compatibility
- 🚀 Automatic server management
- 🔧 Development tools

### Database Integration
- 🗄️ **Prisma ORM** - Type-safe database access
- 📊 **Automatic migrations** - Schema management
- 🔄 **Database seeding** - Test data
- 🚀 **Production ready** - Easy deployment

## 🚀 Production Deployment

### Next.js Examples
1. **Deploy to Vercel/Netlify**
2. **Set up BTCPay Server** (for payments)
3. **Configure environment variables**
4. **Run database migrations**

### React Example
1. **Build the application**
2. **Deploy to static hosting**
3. **Set up API backend**
4. **Configure Lightning endpoints**

### Express.js Example
1. **Deploy to Node.js hosting**
2. **Set up database**
3. **Configure BTCPay Server**
4. **Set up reverse proxy**

## 🔗 Additional Resources

- 📖 [Main Documentation](../README.md)
- 🚀 [Quick Start Guide](../QUICK_START.md)
- 🤖 [AI Setup Guide](../AI_SETUP_GUIDE.md)
- 🔧 [Next.js Plugin Guide](../NEXTJS_PLUGIN.md)
- 📝 [Changelog](../CHANGELOG.md)

## 💡 Tips and Best Practices

### Development
- Use `npm run dev:lightning` for Lightning wallet testing
- Test with mobile Lightning wallets (Alby, Zeus, etc.)
- Use BTCPay Server for payment testing

### Production
- Set up proper BTCPay Server instance
- Use strong session secrets
- Configure proper CORS settings
- Set up monitoring and logging

### Security
- Never commit `.env` files
- Use HTTPS in production
- Validate all inputs
- Implement rate limiting

## 🤝 Contributing

Found an issue or want to improve an example? We welcome contributions!

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

## 📄 License

All examples are licensed under the MIT License. See the main repository for details.