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

# 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

   docker exec finance_bot_migrations alembic upgrade head
   

2. Rebuild containers

   docker compose up -d --build
   

3. Test registration

   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

   docker logs -f finance_bot_bot
   docker logs -f finance_bot_web
   

---

🐛 Troubleshooting

Migration fails

# 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