feat: Add Telegram bot with group support

- Full Telegram bot implementation for Lightning Jackpot
- Commands: /start, /buy, /tickets, /wins, /address, /jackpot, /help
- Lightning invoice generation with QR codes
- Payment polling and confirmation notifications
- User state management (Redis/in-memory fallback)
- Group support with admin settings panel
- Configurable draw announcements and reminders
- Centralized messages for easy i18n
- Docker configuration included

telegram_bot/README.md

@@ -0,0 +1,146 @@
+# 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
+