finance_bot/BOT_API_INTEGRATION_SUMMARY.md

# Bot API Integration - Complete Summary

## 🎯 What Was Done

### 1. **Updated User Model** (`app/db/models/user.py`)
- Added `email` field (unique, nullable) for email/password authentication
- Added `password_hash` field for secure password storage
- Made `telegram_id` optional (nullable)
- Added `email_verified` field for email verification tracking
- Updated `__repr__` to show authentication method

### 2. **New API Endpoints** (`app/api/auth.py`)

#### Email Registration
```
POST /api/v1/auth/register
```
- Registers new user with email/password
- Returns JWT tokens immediately
- Bot can use for quick user creation

#### Get Token for Telegram User
```
POST /api/v1/auth/token/get
```
- Get fresh JWT token by chat_id
- Useful after successful Telegram binding
- Returns access_token + expires_in

#### Telegram Token Refresh
```
POST /api/v1/auth/token/refresh-telegram
```
- Refresh access token for Telegram user
- Query parameter: `chat_id`
- Returns new access_token

### 3. **New Bot Commands** (`app/bot/client.py`)

#### `/start`
- Shows registration options (instead of binding flow)
- Options: Quick Register or Link Account
- Stores user state in Redis

#### `/register`
- **One-tap registration** for Telegram users
- Calls `POST /api/v1/auth/telegram/register`
- Automatically gets JWT token
- Stores in Redis for 30 days

#### `/link`
- Link existing account to Telegram
- Generates binding code
- User confirms in web with email login
- Stores JWT after confirmation

#### `/help`
- Updated to show registration options
- Different help for registered vs unregistered users

### 4. **Database Migration** (`migrations/versions/003_add_email_auth.py`)
- Adds `email`, `password_hash` columns
- Makes `telegram_id` nullable
- Adds `email_verified` column
- Creates indexes and constraints

### 5. **Documentation**
- `docs/API_INTEGRATION_GUIDE.md` - Complete integration guide with code examples
- `docs/API_ENDPOINTS.md` - Full API reference with cURL examples

---

## 🔄 Authentication Flow

### Option 1: Quick Telegram Registration
```
User /start
  ↓
User /register
  ↓
Bot → POST /api/v1/auth/telegram/register
  ↓
Bot ← JWT Token
  ↓
Store JWT in Redis
  ↓
User can use bot immediately
```

### Option 2: Email Registration
```
User /start
  ↓
User clicks web link (frontend)
  ↓
User signs up with email
  ↓
Frontend → POST /api/v1/auth/register
  ↓
Frontend ← JWT Tokens
  ↓
User /link
  ↓
User confirms binding
  ↓
Bot → POST /api/v1/auth/telegram/confirm
  ↓
Bot gets JWT
  ↓
Store in Redis
```

### Option 3: Link Existing Account
```
User /link
  ↓
Bot → POST /api/v1/auth/telegram/start
  ↓
Bot ← Binding Code
  ↓
Bot sends link with code
  ↓
User clicks link (web)
  ↓
User logs in with email
  ↓
Frontend → POST /api/v1/auth/telegram/confirm
  ↓
Bot queries JWT
  ↓
Store in Redis
```

---

## 🔐 Token Storage

### In Redis (Bot)
```
Key: chat_id:{chat_id}:jwt
Value: JWT Token
TTL: 30 days
```

### Example Usage in Bot
```python
# Store token after registration
redis.setex(f"chat_id:{chat_id}:jwt", 86400*30, jwt_token)

# Get token before API call
token = redis.get(f"chat_id:{chat_id}:jwt")

# Use in request
headers = {"Authorization": f"Bearer {token}"}
```

---

## 📝 API Endpoints Quick Reference

| Method | Endpoint | Purpose | Auth |
|--------|----------|---------|------|
| POST | `/api/v1/auth/register` | Email registration | No |
| POST | `/api/v1/auth/login` | Email login | No |
| POST | `/api/v1/auth/refresh` | Refresh access token | No (refresh_token in body) |
| POST | `/api/v1/auth/telegram/register` | Quick Telegram registration | No |
| POST | `/api/v1/auth/telegram/start` | Start binding process | No |
| POST | `/api/v1/auth/telegram/confirm` | Confirm binding | Yes |
| POST | `/api/v1/auth/token/get` | Get token by chat_id | No |
| POST | `/api/v1/auth/token/refresh-telegram` | Refresh Telegram token | No |
| POST | `/api/v1/auth/logout` | Logout | Yes |

---

## 🚀 Bot Flow Examples

### User Wants Quick Registration
```
/start
→ Choose /register
→ One tap
→ ✅ Account created, JWT stored
→ /balance works immediately
```

### User Has Email Account
```
/start
→ Choose /link
→ Click link with binding code
→ Log in to web with email
→ Confirm binding
→ Bot gets JWT
→ ✅ Ready to use
```

### User Already Registered
```
/start
→ ✅ Already connected!
→ Can use /balance, /add, etc.
```

---

## 🔧 Deployment Checklist

- [ ] Apply migration: `alembic upgrade head`
- [ ] Update docker-compose.yml (already fixed version warning)
- [ ] Set environment variables
- [ ] Test endpoints with cURL
- [ ] Update bot with new commands
- [ ] Test bot /register command
- [ ] Test bot /link command
- [ ] Verify tokens stored in Redis
- [ ] Test API calls with token

---

## 💡 Key Improvements

1. **Flexible Authentication**
   - Email/password for web users
   - Telegram-only for bot users
   - Mixed for both platforms

2. **Seamless Bot Experience**
   - No web redirects needed
   - `/register` for instant access
   - `/link` for existing users

3. **Secure Token Management**
   - JWT tokens with 15min expiry
   - Refresh tokens for 30 days
   - Redis caching for fast access

4. **Better API Design**
   - Clear endpoint purposes
   - Consistent response formats
   - Proper error handling

5. **Complete Documentation**
   - Integration guide with code
   - API reference with examples
   - Python/Node.js implementations

---

## 📚 Files Modified/Created

### Modified
- `app/db/models/user.py` - Added email/password fields
- `app/api/auth.py` - Added new endpoints
- `app/bot/client.py` - Added /register, /link commands
- `app/main.py` - Already had proper router includes
- `docker-compose.yml` - Fixed version warning, added web dependency for bot

### Created
- `migrations/versions/003_add_email_auth.py` - Database migration
- `docs/API_INTEGRATION_GUIDE.md` - Complete integration guide
- `docs/API_ENDPOINTS.md` - API reference

---

## ✅ Next Steps

1. **Run migration**
   ```bash
   docker exec finance_bot_migrations alembic upgrade head
   ```

2. **Rebuild containers**
   ```bash
   docker compose up -d --build
   ```

3. **Test registration**
   ```bash
   curl -X POST http://localhost:8000/api/v1/auth/register \
     -H "Content-Type: application/json" \
     -d '{"email":"test@example.com","password":"test123","first_name":"Test"}'
   ```

4. **Test bot /register**
   - Send `/register` to bot
   - Should get JWT token
   - Verify in Redis: `redis-cli get "chat_id:{id}:jwt"`

5. **Monitor logs**
   ```bash
   docker logs -f finance_bot_bot
   docker logs -f finance_bot_web
   ```

---

## 🐛 Troubleshooting

### Migration fails
```bash
# Check migration status
docker exec finance_bot_migrations alembic current

# Rollback if needed
docker exec finance_bot_migrations alembic downgrade -1

# Reapply
docker exec finance_bot_migrations alembic upgrade head
```

### Bot can't reach web
- Check network connectivity
- Verify API_BASE_URL is correct
- Check logs: `docker logs finance_bot_bot`

### Token not stored in Redis
- Check Redis connection
- Verify Redis is running: `docker ps | grep redis`
- Check Redis key: `redis-cli get "chat_id:556399210:jwt"`

### Endpoint returns 404
- Check auth router is included in main.py ✓
- Verify endpoint path matches
- Check logs for routing errors

---

## 📞 Support

For API issues:
1. Check `docs/API_ENDPOINTS.md` for endpoint details
2. Review bot logs: `docker logs finance_bot_bot`
3. Check web logs: `docker logs finance_bot_web`
4. Test endpoint with cURL first

For bot issues:
1. Verify bot token is set in environment
2. Check Redis connection
3. Monitor logs during command execution
4. Verify API base URL in bot config