# 🤖 Manual Bot API Testing Guide

This guide will help you manually test all the `/api/bots` endpoints.

## 🚀 Prerequisites

1. **Start the services:**
   ```bash
   cd ai-learning-platform
   docker-compose up -d
   ```

2. **Wait for services to be ready:**
   ```bash
   # Check if services are running
   docker-compose ps
   
   # Check backend health
   curl http://localhost:3000/health
   ```

3. **Install axios for testing (if needed):**
   ```bash
   npm install axios
   ```

## 🧪 Test Cases

### 1. GET /api/bots (Get all bots)
```bash
curl -X GET http://localhost:3000/api/bots
```

**Expected Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Bot Name",
      "topic": "Topic",
      "level": "A1",
      "imageUrl": "https://...",
      "agentId": "agent-id",
      "description": "Description",
      "isActive": true,
      "createdAt": "2024-...",
      "updatedAt": "2024-..."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1
  }
}
```

### 2. GET /api/bots/:id (Get bot by ID)
```bash
# Replace {bot-id} with actual bot ID from step 1
curl -X GET http://localhost:3000/api/bots/{bot-id}
```

### 3. GET /api/bots/name/:botName (Get bot by name)
```bash
curl -X GET http://localhost:3000/api/bots/name/TestBot
```

### 4. GET /api/bots/accessible (Get accessible bots - requires auth)
```bash
curl -X GET http://localhost:3000/api/bots/accessible \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### 5. POST /api/bots (Create bot - requires admin/teacher auth)
```bash
curl -X POST http://localhost:3000/api/bots \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "Test Bot",
    "topic": "General Conversation",
    "level": "A1",
    "imageUrl": "https://example.com/bot-image.jpg",
    "agentId": "test-agent-123",
    "description": "A test bot for API testing"
  }'
```

### 6. PUT /api/bots/:id (Update bot - requires admin/teacher auth)
```bash
curl -X PUT http://localhost:3000/api/bots/{bot-id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "Updated Test Bot",
    "topic": "Updated Topic",
    "level": "A2",
    "imageUrl": "https://example.com/updated-bot-image.jpg",
    "agentId": "updated-agent-123",
    "description": "Updated description"
  }'
```

### 7. DELETE /api/bots/:id (Delete bot - requires admin/teacher auth)
```bash
curl -X DELETE http://localhost:3000/api/bots/{bot-id} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## 🔐 Authentication

To get a JWT token for testing authenticated endpoints:

1. **Register a user:**
   ```bash
   curl -X POST http://localhost:3000/api/auth/register \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Test Admin",
       "email": "admin@example.com",
       "password": "K9#mX7$vL2@n",
       "role": "ADMIN"
     }'
   ```

2. **Login to get token:**
   ```bash
   curl -X POST http://localhost:3000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{
       "email": "admin@example.com",
       "password": "K9#mX7$vL2@n"
     }'
   ```

3. **Use the token in subsequent requests:**
   ```bash
   curl -X GET http://localhost:3000/api/bots/accessible \
     -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE"
   ```

## 📊 Expected Status Codes

| Endpoint | Method | Expected Status | Notes |
|----------|--------|----------------|-------|
| `/api/bots` | GET | 200 | Public endpoint |
| `/api/bots/:id` | GET | 200 | Public endpoint |
| `/api/bots/name/:botName` | GET | 200 or 404 | Public endpoint |
| `/api/bots/accessible` | GET | 200 or 401 | Requires authentication |
| `/api/bots` | POST | 201 or 401/403 | Requires admin/teacher role |
| `/api/bots/:id` | PUT | 200 or 401/403 | Requires admin/teacher role |
| `/api/bots/:id` | DELETE | 200 or 401/403 | Requires admin/teacher role |

## 🐛 Troubleshooting

### Common Issues:

1. **Connection refused:**
   - Check if Docker services are running: `docker compose ps`
   - Restart services: `docker compose restart`

2. **Database connection error:**
   - Check if PostgreSQL is running: `docker compose logs postgres`
   - Apply migrations: `docker compose exec backend npx prisma migrate deploy`

3. **Authentication errors:**
   - Make sure you're using a valid JWT token
   - Check if the user has the required role (ADMIN/TEACHER)

4. **Validation errors:**
   - Check the request body format
   - Ensure all required fields are provided

## 🧹 Cleanup

After testing, you can clean up:

```bash
# Stop all services
docker compose down

# Remove test data (optional)
docker compose down -v
```