finance_bot/API_CHANGES_SUMMARY.md

📋 Bot API Integration - Changes Summary

✨ What's New

🔐 Authentication System Enhanced

Bot теперь поддерживает:

• ✅ Email/Password регистрацию и логин
• ✅ Telegram-только регистрацию (/register)
• ✅ Привязку существующих аккаунтов (/link)
• ✅ JWT токены с автоматическим обновлением

🤖 New Bot Commands

/start    - Выбор способа регистрации
/register - Одно-кликовая регистрация (Telegram)
/link     - Привязка существующего аккаунта
/help     - Обновленная справка

🔌 New API Endpoints

POST /api/v1/auth/register              - Email регистрация
POST /api/v1/auth/token/get             - Получить токен
POST /api/v1/auth/token/refresh-telegram - Обновить токен
POST /api/v1/auth/telegram/register     - Telegram регистрация

---

📂 Files Modified

Core Application Files

app/db/models/user.py

# Before: telegram_id required, no email support
# After: email + password fields, telegram_id optional
- telegram_id: NOT NULL → NULLABLE
+ email: String(255), unique
+ password_hash: String(255)
+ email_verified: Boolean

app/api/auth.py

# Added 3 new endpoints:
+ POST /api/v1/auth/register
+ POST /api/v1/auth/token/get
+ POST /api/v1/auth/token/refresh-telegram

# New Pydantic models:
+ RegisterRequest/Response
+ GetTokenRequest/Response

app/bot/client.py

# Added 2 new commands:
+ cmd_register() - Quick Telegram registration
+ cmd_link() - Link existing account
+ Updated cmd_start() - Show options
+ Updated cmd_help() - New commands info

docker-compose.yml

# Fixed:
- version: '3.9' (removed - deprecated)
# Added:
+ web dependency for bot service

app/main.py

# No changes - routers already included
# ✓ auth.router properly registered
# ✓ transactions.router properly registered

---

📊 Database Schema Changes

Migration: migrations/versions/003_add_email_auth.py

-- New columns
ALTER TABLE users ADD COLUMN email VARCHAR(255) UNIQUE;
ALTER TABLE users ADD COLUMN password_hash VARCHAR(255);
ALTER TABLE users ADD COLUMN email_verified BOOLEAN DEFAULT FALSE;

-- Make telegram_id nullable
ALTER TABLE users ALTER COLUMN telegram_id DROP NOT NULL;

-- New indexes
CREATE UNIQUE INDEX uq_users_email ON users(email);
CREATE INDEX ix_users_email ON users(email);

Before vs After

Before:

users:
  - id (PK)
  - telegram_id (NOT NULL, UNIQUE)
  - username
  - first_name
  - last_name

After:

users:
  - id (PK)
  - email (UNIQUE, nullable)
  - password_hash (nullable)
  - telegram_id (UNIQUE, nullable) ← changed
  - username
  - first_name
  - last_name
  - email_verified (new)

---

🔄 Authentication Flows

Flow 1: Quick Telegram Registration

User /register
    ↓
Bot calls: POST /api/v1/auth/telegram/register
    ↓
Bot receives JWT token
    ↓
Bot stores in Redis: chat_id:{id}:jwt
    ↓
✅ User ready to use bot immediately

Flow 2: Email Account Link

User /link
    ↓
Bot calls: POST /api/v1/auth/telegram/start
    ↓
Bot receives binding code
    ↓
Bot sends link with code to user
    ↓
User clicks link, logs in with email
    ↓
Frontend calls: POST /api/v1/auth/telegram/confirm
    ↓
Bot calls: POST /api/v1/auth/token/get
    ↓
Bot receives and stores JWT
    ↓
✅ Account linked and ready to use

Flow 3: Email Registration

User → Web Frontend
    ↓
User fills email/password
    ↓
Frontend calls: POST /api/v1/auth/register
    ↓
Frontend receives JWT tokens
    ↓
Frontend can make API calls
    ↓
User can later link Telegram

---

📡 API Integration Example

Python

import aiohttp

# Register user
async with session.post("http://web:8000/api/v1/auth/register",
    json={
        "email": "user@example.com",
        "password": "pass123",
        "first_name": "John"
    }) as resp:
    data = await resp.json()
    token = data["access_token"]

# Use token
headers = {"Authorization": f"Bearer {token}"}
async with session.get("http://web:8000/api/v1/accounts",
    headers=headers) as resp:
    accounts = await resp.json()

cURL

# Register
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"test123"}'

# Get token
curl -X POST http://localhost:8000/api/v1/auth/token/get \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 556399210}'

---

🚀 Deployment Steps

1. Apply Migration

   docker exec finance_bot_migrations alembic upgrade head
   

2. Rebuild Containers

   docker compose down
   docker compose up -d --build
   

3. Test Endpoints

   curl http://localhost:8000/api/v1/auth/register ...
   

4. Monitor Logs

   docker logs -f finance_bot_web
   docker logs -f finance_bot_bot
   

---

📚 Documentation Files

File	Purpose
docs/API_INTEGRATION_GUIDE.md	Complete integration guide with examples
docs/API_ENDPOINTS.md	Full API reference
BOT_API_INTEGRATION_SUMMARY.md	Detailed summary of changes
DEPLOYMENT_CHECKLIST_API.md	13-phase deployment checklist
API_QUICK_START.md	Quick start guide (this file)
examples/bot_api_usage.py	Python implementation examples
test_api.sh	Test script for API endpoints

---

🔑 Key Features

✅ Flexible Authentication

• Users can register with email OR Telegram OR both
• Same user can have multiple auth methods
• Seamless switching between platforms

✅ Token Management

• JWT tokens with configurable TTL
• Refresh tokens for long-term access
• Automatic token refresh in bot

✅ Security

• Password hashing before storage
• JWT tokens with expiration
• HMAC signatures for API calls
• Redis token caching with TTL

✅ Bot Integration

• One-command registration (/register)
• Token stored in Redis for reuse
• Automatic token refresh
• No frontend redirects needed

---

💡 Usage Examples

Register New User

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "SecurePass123",
    "first_name": "John"
  }'

Get Telegram User Token

curl -X POST http://localhost:8000/api/v1/auth/token/get \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 556399210}'

Make Authenticated Request

curl -X GET http://localhost:8000/api/v1/accounts \
  -H "Authorization: Bearer eyJ..."

---

🧪 Testing Checklist

• Email registration works
• Telegram /register works
• /link command works
• Tokens stored in Redis
• Token refresh works
• Authenticated requests work
• Error handling works (400, 401, 404, 500)
• Database migration applied
• No errors in logs

---

🎓 Learning Resources

1. JWT Authentication: docs/API_INTEGRATION_GUIDE.md
2. API Reference: docs/API_ENDPOINTS.md
3. Code Examples: examples/bot_api_usage.py
4. Test Script: test_api.sh
5. Security: See HMAC signatures in bot client

---

🔧 Configuration

Environment Variables

API_BASE_URL=http://web:8000
BOT_TOKEN=your_telegram_bot_token
REDIS_URL=redis://redis:6379/0
DATABASE_URL=postgresql://...

Docker Network

# All services on same network
networks:
  - finance_network (bridge driver)

---

⚠️ Breaking Changes

Migration Required

# Before: new users MUST have telegram_id
User(telegram_id=123)

# After: users can have email OR telegram OR both
User(email="test@example.com")
User(telegram_id=123)
User(email="test@example.com", telegram_id=123)

Bot Flow Changed

# Before: /start → generate code → user clicks link
# After: /start → choose /register or /link

---

✨ Benefits

✅ For Users

• Multiple authentication methods
• One-tap Telegram registration
• No need for web login initially

✅ For Developers

• Clear API endpoints
• Consistent response formats
• Easy integration
• Complete documentation

✅ For Operations

• Single database schema
• Token caching in Redis
• Flexible deployment options

---

📊 Statistics

• Files Modified: 5
• Files Created: 7
• API Endpoints Added: 3
• Bot Commands Added: 2
• Database Columns Added: 3
• Documentation Pages: 5
• Code Examples: 2
• Test Scripts: 1

---

🔗 Quick Links

• Start: API_QUICK_START.md
• Deploy: DEPLOYMENT_CHECKLIST_API.md
• API Docs: docs/API_ENDPOINTS.md
• Integration: docs/API_INTEGRATION_GUIDE.md
• Summary: BOT_API_INTEGRATION_SUMMARY.md
• Examples: examples/bot_api_usage.py

---

Status: ✅ Complete and Ready for Deployment

Last Updated: 2025-12-11

Next Step: Read API_QUICK_START.md or DEPLOYMENT_CHECKLIST_API.md