# Lightning Jackpot Telegram Bot ⚡🎰

A Telegram bot for the Lightning Jackpot lottery system. Users can buy tickets, check their tickets and wins, and receive instant notifications - all through Telegram!

## Features

- 🎟 **Buy Tickets** - Quick buttons for 1, 2, 5, 10 tickets or custom amounts
- 💸 **Lightning Payments** - Generate and pay Lightning invoices directly in chat
- 📱 **QR Codes** - Visual QR codes for easy wallet scanning
- 🔔 **Real-time Updates** - Automatic payment confirmation notifications
- 🧾 **View Tickets** - See all your ticket purchases and their status
- 🏆 **Track Wins** - View your winning history and payouts
- ⚡ **Lightning Address** - Manage your payout address

## Prerequisites

- Node.js 18+
- Telegram Bot Token (from [@BotFather](https://t.me/BotFather))
- Lightning Jackpot Backend API running

## Installation

1. Clone the repository and navigate to the bot directory:
   ```bash
   cd telegram_bot
   ```

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

3. Create environment file:
   ```bash
   cp env.example .env
   ```

4. Configure your `.env` file:
   ```env
   TELEGRAM_BOT_TOKEN=your_bot_token_here
   API_BASE_URL=http://localhost:3000
   FRONTEND_BASE_URL=http://localhost:3001
   ```

## Development

Run the bot in development mode with auto-reload:
```bash
npm run dev:watch
```

Or run once:
```bash
npm run dev
```

## Production

Build and run:
```bash
npm run build
npm start
```

## Docker

Build the image:
```bash
docker build -t lightning-lotto-telegram-bot .
```

Run the container:
```bash
docker run -d \
  --name telegram-bot \
  -e TELEGRAM_BOT_TOKEN=your_token \
  -e API_BASE_URL=http://backend:3000 \
  -e FRONTEND_BASE_URL=http://frontend:3001 \
  lightning-lotto-telegram-bot
```

## Commands

| Command | Description |
|---------|-------------|
| `/start` | Begin using the bot |
| `/menu` | Show main menu |
| `/buy` | Buy lottery tickets |
| `/tickets` | View your tickets |
| `/wins` | View your past wins |
| `/address` | Update Lightning Address |
| `/help` | Help & information |

## Architecture

```
src/
├── config/          # Configuration management
├── handlers/        # Command and callback handlers
│   ├── start.ts     # /start command
│   ├── buy.ts       # Ticket purchase flow
│   ├── tickets.ts   # View tickets
│   ├── wins.ts      # View wins
│   ├── address.ts   # Lightning address management
│   ├── help.ts      # Help command
│   └── menu.ts      # Menu handling
├── services/
│   ├── api.ts       # Backend API client
│   ├── state.ts     # User state management (Redis/in-memory)
│   ├── qr.ts        # QR code generation
│   └── logger.ts    # Logging service
├── types/           # TypeScript type definitions
├── utils/
│   ├── format.ts    # Formatting utilities
│   └── keyboards.ts # Telegram keyboard builders
└── index.ts         # Main entry point
```

## State Management

The bot uses Redis for persistent state management when available. If Redis is not configured, it falls back to in-memory storage (not recommended for production).

User states:
- `idle` - Default state, browsing menu
- `awaiting_lightning_address` - Waiting for user to enter Lightning Address
- `awaiting_ticket_amount` - Waiting for custom ticket amount
- `awaiting_invoice_payment` - Polling for payment
- `updating_address` - Updating Lightning Address

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `TELEGRAM_BOT_TOKEN` | Telegram Bot API token | Required |
| `API_BASE_URL` | Backend API URL | `http://localhost:3000` |
| `FRONTEND_BASE_URL` | Frontend URL for ticket links | `http://localhost:3001` |
| `REDIS_URL` | Redis connection URL | Optional |
| `MAX_TICKETS_PER_PURCHASE` | Maximum tickets per purchase | `100` |
| `PAYMENT_POLL_INTERVAL_MS` | Payment polling interval | `5000` |
| `PAYMENT_POLL_TIMEOUT_MS` | Payment polling timeout | `900000` |
| `LOG_LEVEL` | Logging level | `info` |

## License

MIT