contract-query/API_TESTING_GUIDE.md

# Contract Analysis Tool - API Testing Guide

This guide provides comprehensive step-by-step instructions to test all APIs in the Contract Analysis Tool with real input examples.

## Prerequisites

1. **Backend Server Running**: `http://localhost:8000`
2. **Frontend Server Running**: `http://localhost:3000`
3. **MongoDB Running**: `localhost:27017`
4. **Redis Running**: `localhost:6379`
5. **Environment Variables**: Ensure `.env` files are properly configured

## Authentication Setup

### Step 1: Initialize Default Users
```bash
curl -X POST http://localhost:8000/api/v1/auth/init-users
```

**Expected Response:**
```json
{
  "message": "Default users created successfully",
  "admin_email": "admin@oliver.agency",
  "user_email": "user@oliver.agency"
}
```

### Step 2: Test Health Check
```bash
curl http://localhost:8000/health
```

**Expected Response:**
```json
{
  "status": "healthy",
  "version": "2.0.0"
}
```

## Authentication APIs

### 1. Admin Login
```bash
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@oliver.agency",
    "password": "admin123"
  }'
```

**Expected Response:**
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "...",
    "email": "admin@oliver.agency",
    "role": "admin",
    "is_active": true,
    "index_access": [...]
  }
}
```

**Save the admin token:**
```bash
ADMIN_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

### 2. User Login
```bash
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@oliver.agency",
    "password": "user123"
  }'
```

**Save the user token:**
```bash
USER_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

### 3. Get Current User Info
```bash
curl -X GET http://localhost:8000/api/v1/auth/me \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

## Admin APIs

### User Management

#### 1. Get All Users
```bash
curl -X GET http://localhost:8000/api/v1/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

#### 2. Create New User
```bash
curl -X POST http://localhost:8000/api/v1/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "testuser@example.com",
    "password": "SecurePass123",
    "role": "user",
    "is_active": true
  }'
```

**Save the user ID from response:**
```bash
NEW_USER_ID="686ec44005b0398525fde787"
```

#### 3. Update User
```bash
curl -X PUT http://localhost:8000/api/v1/admin/users/$NEW_USER_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "updated_testuser@example.com",
    "role": "admin",
    "is_active": false
  }'
```

#### 4. Delete User
```bash
curl -X DELETE http://localhost:8000/api/v1/admin/users/$NEW_USER_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

### Index Management

#### 1. Get All Indices
```bash
curl -X GET http://localhost:8000/api/v1/admin/indices \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

#### 2. Create New Index
```bash
curl -X POST http://localhost:8000/api/v1/admin/indices/create \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -F "name=Test Contract Index" \
  -F "description=Index for testing contract analysis" \
  -F "chunk_size=1000" \
  -F "chunk_overlap=200"
```

**Save the index ID from response:**
```bash
TEST_INDEX_ID="test-index-2025-07-09-abc123"
```

#### 3. Delete Index
```bash
curl -X DELETE http://localhost:8000/api/v1/admin/indices/$TEST_INDEX_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

### Document Management

#### 1. Upload Single Document
```bash
curl -X POST http://localhost:8000/api/v1/admin/documents/upload-single \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -F "file=@/path/to/your/document.pdf" \
  -F "index_id=$TEST_INDEX_ID" \
  -F "custom_name=Test Contract Document"
```

#### 2. Upload Multiple Documents
```bash
curl -X POST http://localhost:8000/api/v1/admin/documents/upload-multiple \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -F "files=@/path/to/document1.pdf" \
  -F "files=@/path/to/document2.pdf" \
  -F "index_id=$TEST_INDEX_ID" \
  -F "base_name=Contract Batch"
```

#### 3. Get Index Documents
```bash
curl -X GET http://localhost:8000/api/v1/admin/documents/$TEST_INDEX_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

**Save a document ID from response:**
```bash
DOCUMENT_ID="686ebfa705b0398525fde785"
```

#### 4. Reprocess Document
```bash
curl -X POST http://localhost:8000/api/v1/admin/documents/$DOCUMENT_ID/reprocess \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

#### 5. Delete Document
```bash
curl -X DELETE http://localhost:8000/api/v1/admin/documents/$DOCUMENT_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

### Index Access Management

#### 1. Grant Index Access to User
```bash
curl -X POST http://localhost:8000/api/v1/admin/users/$USER_ID/grant-index-access \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "index_id": "'$TEST_INDEX_ID'"
  }'
```

#### 2. Revoke Index Access from User
```bash
curl -X POST http://localhost:8000/api/v1/admin/users/$USER_ID/revoke-index-access \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "index_id": "'$TEST_INDEX_ID'"
  }'
```

#### 3. Grant All Indices Access
```bash
curl -X POST http://localhost:8000/api/v1/admin/grant-all-indices/$USER_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

### System Monitoring

#### 1. Get System Statistics
```bash
curl -X GET http://localhost:8000/api/v1/admin/stats \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

#### 2. Get Processing Status
```bash
curl -X GET http://localhost:8000/api/v1/admin/documents/processing-status \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

#### 3. Process Pending Documents
```bash
curl -X POST http://localhost:8000/api/v1/admin/documents/process-pending \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

### Admin RAG Query
```bash
curl -X POST http://localhost:8000/api/v1/admin/chat/query \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -F "query=What are the key terms of this contract?" \
  -F "index_id=$TEST_INDEX_ID" \
  -F "top_k=5"
```

## User APIs

### Index Access

#### 1. Get User's Indices
```bash
curl -X GET http://localhost:8000/api/v1/indices/ \
  -H "Authorization: Bearer $USER_TOKEN"
```

#### 2. Get Specific Index
```bash
curl -X GET http://localhost:8000/api/v1/indices/$TEST_INDEX_ID \
  -H "Authorization: Bearer $USER_TOKEN"
```

#### 3. Create User Index
```bash
curl -X POST http://localhost:8000/api/v1/indices/create \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Contract Index",
    "description": "Personal contract analysis index"
  }'
```

### Document Operations

#### 1. Upload Document to Index
```bash
curl -X POST http://localhost:8000/api/v1/documents/upload \
  -H "Authorization: Bearer $USER_TOKEN" \
  -F "file=@/path/to/contract.pdf" \
  -F "index_id=$USER_INDEX_ID"
```

#### 2. Get Documents by Index
```bash
curl -X GET http://localhost:8000/api/v1/documents/index/$USER_INDEX_ID \
  -H "Authorization: Bearer $USER_TOKEN"
```

#### 3. Get Document Details
```bash
curl -X GET http://localhost:8000/api/v1/documents/$DOCUMENT_ID \
  -H "Authorization: Bearer $USER_TOKEN"
```

#### 4. Get Document Summary (AI)
```bash
curl -X GET http://localhost:8000/api/v1/documents/$DOCUMENT_ID/summary \
  -H "Authorization: Bearer $USER_TOKEN"
```

**Expected Response:**
```json
{
  "document_id": "686ebfa705b0398525fde785",
  "filename": "Contract Document.pdf",
  "summary": "This document is a service agreement between...",
  "processing_status": "completed",
  "generated_at": "2025-07-09T19:41:12.301719"
}
```

#### 5. Download Document
```bash
curl -X GET http://localhost:8000/api/v1/documents/$DOCUMENT_ID/download \
  -H "Authorization: Bearer $USER_TOKEN" \
  --output downloaded_document.pdf
```

#### 6. Delete Document
```bash
curl -X DELETE http://localhost:8000/api/v1/documents/$DOCUMENT_ID \
  -H "Authorization: Bearer $USER_TOKEN"
```

### Chat and RAG

#### 1. Query Documents (RAG)
```bash
curl -X POST http://localhost:8000/api/v1/chat/query \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the payment terms in this contract?",
    "index_id": "'$USER_INDEX_ID'",
    "top_k": 5
  }'
```

**Expected Response:**
```json
{
  "response": "Based on the contract analysis, the payment terms include...",
  "cached": false,
  "response_time": 2.34,
  "debug_info": {
    "sources": [...],
    "context_used": true,
    "context_messages_count": 3
  }
}
```

#### 2. Get Chat History
```bash
curl -X GET http://localhost:8000/api/v1/chat/history/$USER_INDEX_ID \
  -H "Authorization: Bearer $USER_TOKEN"
```

#### 3. Clear Chat History
```bash
curl -X DELETE http://localhost:8000/api/v1/chat/history/$USER_INDEX_ID \
  -H "Authorization: Bearer $USER_TOKEN"
```

#### 4. Get Index Chat Status
```bash
curl -X GET http://localhost:8000/api/v1/chat/status/$USER_INDEX_ID \
  -H "Authorization: Bearer $USER_TOKEN"
```

## Permission Testing

### Test User Access Restrictions

#### 1. User Trying to Access Admin Endpoint (Should Fail)
```bash
curl -X GET http://localhost:8000/api/v1/admin/users \
  -H "Authorization: Bearer $USER_TOKEN"
```

**Expected Response:**
```json
{
  "detail": "Not enough permissions"
}
```

#### 2. User Accessing Unauthorized Index (Should Fail)
```bash
curl -X GET http://localhost:8000/api/v1/documents/index/unauthorized-index-id \
  -H "Authorization: Bearer $USER_TOKEN"
```

#### 3. Admin Accessing Any Resource (Should Work)
```bash
curl -X GET http://localhost:8000/api/v1/documents/index/$ANY_INDEX_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

## Frontend Testing

### 1. Access Frontend
```bash
# Open browser to
http://localhost:3000
```

### 2. Test Login Flow
1. Navigate to `http://localhost:3000/login`
2. Login with admin credentials: `admin@oliver.agency` / `admin123`
3. Verify dashboard access
4. Check admin panel visibility in sidebar

### 3. Test Admin Panel
1. Navigate to `http://localhost:3000/dashboard/admin`
2. Test user management (create, edit, delete)
3. Test index access management
4. Verify system statistics

### 4. Test User Features
1. Login as user: `user@oliver.agency` / `user123`
2. Test document upload and management
3. Test AI summary generation
4. Test chat interface with documents

## Error Testing

### 1. Invalid Authentication
```bash
curl -X GET http://localhost:8000/api/v1/admin/users \
  -H "Authorization: Bearer invalid_token"
```

### 2. Missing Required Fields
```bash
curl -X POST http://localhost:8000/api/v1/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "incomplete@user.com"
  }'
```

### 3. Duplicate Email
```bash
curl -X POST http://localhost:8000/api/v1/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@oliver.agency",
    "password": "test123",
    "role": "user"
  }'
```

## Performance Testing

### 1. Large File Upload
```bash
curl -X POST http://localhost:8000/api/v1/documents/upload \
  -H "Authorization: Bearer $USER_TOKEN" \
  -F "file=@/path/to/large_document.pdf" \
  -F "index_id=$USER_INDEX_ID" \
  --max-time 300
```

### 2. Concurrent Chat Queries
```bash
# Run multiple queries simultaneously
for i in {1..5}; do
  curl -X POST http://localhost:8000/api/v1/chat/query \
    -H "Authorization: Bearer $USER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "Query '$i': What is the contract about?",
      "index_id": "'$USER_INDEX_ID'"
    }' &
done
wait
```

## Complete Test Workflow

### 1. Setup Test Environment
```bash
# Start services
cd /path/to/backend && uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 &
cd /path/to/frontend && npm run dev &

# Initialize users
curl -X POST http://localhost:8000/api/v1/auth/init-users
```

### 2. Login and Get Tokens
```bash
ADMIN_TOKEN=$(curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@oliver.agency", "password": "admin123"}' \
  | jq -r '.access_token')

USER_TOKEN=$(curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@oliver.agency", "password": "user123"}' \
  | jq -r '.access_token')
```

### 3. Create Test Index
```bash
INDEX_RESPONSE=$(curl -X POST http://localhost:8000/api/v1/admin/indices/create \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -F "name=API Test Index" \
  -F "description=Index for API testing")

TEST_INDEX_ID=$(echo $INDEX_RESPONSE | jq -r '.index_id')
```

### 4. Upload and Process Document
```bash
curl -X POST http://localhost:8000/api/v1/admin/documents/upload-single \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -F "file=@/path/to/test_contract.pdf" \
  -F "index_id=$TEST_INDEX_ID" \
  -F "custom_name=Test Contract"
```

### 5. Grant User Access
```bash
USER_ID=$(curl -X GET http://localhost:8000/api/v1/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  | jq -r '.[] | select(.email=="user@oliver.agency") | .id')

curl -X POST http://localhost:8000/api/v1/admin/users/$USER_ID/grant-index-access \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"index_id": "'$TEST_INDEX_ID'"}'
```

### 6. Test User Chat
```bash
curl -X POST http://localhost:8000/api/v1/chat/query \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Summarize this contract",
    "index_id": "'$TEST_INDEX_ID'"
  }'
```

### 7. Test AI Summary
```bash
DOCUMENT_ID=$(curl -X GET http://localhost:8000/api/v1/admin/documents/$TEST_INDEX_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  | jq -r '.documents[0].id')

curl -X GET http://localhost:8000/api/v1/documents/$DOCUMENT_ID/summary \
  -H "Authorization: Bearer $USER_TOKEN"
```

## Troubleshooting

### Common Issues

1. **401 Unauthorized**: Check token validity and format
2. **403 Forbidden**: Verify user has required permissions
3. **404 Not Found**: Ensure resource exists and user has access
4. **422 Validation Error**: Check request body format and required fields
5. **500 Internal Server Error**: Check backend logs and OpenAI API key

### Debug Commands

```bash
# Check backend logs
tail -f backend.log

# Check database connection
curl http://localhost:8000/health

# Verify token
curl -X GET http://localhost:8000/api/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"

# Check OpenAI API key
echo $OPENAI_API_KEY
```

## Notes

- Replace `/path/to/your/document.pdf` with actual file paths
- Replace placeholder IDs with actual IDs from responses
- Ensure all environment variables are properly set
- All timestamps are in UTC format
- File uploads support PDF, DOCX, DOC, TXT, CSV, JSON, HTML, MD, RTF formats
- Maximum file size is 50MB (configurable)