tuna/backend/ADMIN_API.md

# Admin API Endpoints

This document describes the admin-specific API endpoints for the Candivista platform.

## Authentication

All admin endpoints require authentication with a valid JWT token from a user with `role: 'admin'`.

**Headers:**
```
Authorization: Bearer <jwt_token>
Content-Type: application/json
```

## Base URL
```
http://localhost:8083/rest/admin
```

## Endpoints

### System Statistics

#### GET /statistics
Get system-wide statistics and metrics.

**Response:**
```json
{
  "total_users": 150,
  "active_users": 142,
  "total_jobs": 89,
  "total_interviews": 234,
  "total_tokens_purchased": 1250,
  "total_tokens_used": 890,
  "total_revenue": 12500.00,
  "generated_at": "2024-01-15T10:30:00Z"
}
```

### User Management

#### GET /users
Get all users in the system.

**Response:**
```json
[
  {
    "id": "user-uuid",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "role": "recruiter",
    "company_name": "Tech Corp",
    "is_active": true,
    "last_login_at": "2024-01-15T09:00:00Z",
    "created_at": "2024-01-01T00:00:00Z"
  }
]
```

#### GET /users/:id
Get a specific user by ID.

#### PUT /users/:id
Update user information.

**Request Body:**
```json
{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "role": "recruiter",
  "company_name": "Tech Corp",
  "is_active": true
}
```

#### PATCH /users/:id/toggle-status
Toggle user active/inactive status.

**Response:**
```json
{
  "success": true,
  "new_status": false
}
```

#### PATCH /users/:id/password
Change user password.

**Request Body:**
```json
{
  "new_password": "newpassword123"
}
```

#### POST /users
Create a new user.

**Request Body:**
```json
{
  "email": "newuser@example.com",
  "password": "password123",
  "first_name": "Jane",
  "last_name": "Smith",
  "role": "recruiter",
  "company_name": "Startup Inc"
}
```

### Job Management

#### GET /jobs
Get all jobs in the system with user information.

**Response:**
```json
[
  {
    "id": "job-uuid",
    "user_id": "user-uuid",
    "title": "Senior Developer",
    "description": "Job description...",
    "status": "active",
    "created_at": "2024-01-15T10:00:00Z",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "company_name": "Tech Corp"
  }
]
```

#### GET /jobs/:id
Get a specific job by ID.

#### PATCH /jobs/:id/status
Update job status.

**Request Body:**
```json
{
  "status": "paused"
}
```

#### PUT /jobs/:id
Update job information.

**Request Body:**
```json
{
  "title": "Updated Job Title",
  "description": "Updated description...",
  "status": "active"
}
```

### Token Management

#### GET /user-token-summaries
Get token usage summaries for all users.

**Response:**
```json
[
  {
    "user_id": "user-uuid",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "total_purchased": 50,
    "total_used": 25,
    "total_available": 25,
    "utilization_percentage": 50.0
  }
]
```

#### POST /add-tokens
Add tokens to a specific user.

**Request Body:**
```json
{
  "user_id": "user-uuid",
  "quantity": 10,
  "price_per_token": 5.00,
  "total_price": 50.00
}
```

### Token Packages

#### GET /token-packages
Get all token packages.

**Response:**
```json
[
  {
    "id": "package-uuid",
    "name": "Professional Pack",
    "description": "Ideal for regular recruiters",
    "quantity": 20,
    "price_per_token": 4.00,
    "total_price": 80.00,
    "discount_percentage": 20,
    "is_popular": true,
    "is_active": true
  }
]
```

#### POST /token-packages
Create a new token package.

**Request Body:**
```json
{
  "name": "New Package",
  "description": "Package description",
  "quantity": 10,
  "price_per_token": 4.50,
  "total_price": 45.00,
  "discount_percentage": 10,
  "is_popular": false,
  "is_active": true
}
```

#### PUT /token-packages/:id
Update a token package.

#### PATCH /token-packages/:id/toggle-status
Toggle package active/inactive status.

#### DELETE /token-packages/:id
Delete a token package.

### Interview Management

#### GET /interviews
Get all interviews in the system.

#### GET /interviews/:id
Get a specific interview by ID.

### Payment Records

#### GET /payments
Get all payment records.

#### GET /payments/:id
Get a specific payment record by ID.

## Error Responses

All endpoints return appropriate HTTP status codes and error messages:

- `400 Bad Request` - Invalid request data
- `401 Unauthorized` - Invalid or missing authentication
- `403 Forbidden` - Insufficient permissions (non-admin user)
- `404 Not Found` - Resource not found
- `500 Internal Server Error` - Server error

**Error Response Format:**
```json
{
  "message": "Error description",
  "status": 400
}
```

## Testing

Use the provided test script to verify admin endpoints:

```bash
node test-admin.js
```

## Security Notes

1. All admin endpoints require admin role verification
2. JWT tokens are validated on every request
3. User passwords are hashed using bcrypt
4. All database queries use parameterized statements to prevent SQL injection
5. Admin actions are logged for audit purposes

## Database Schema

The admin endpoints interact with the following database tables:
- `users` - User accounts and profiles
- `jobs` - Job postings
- `interview_tokens` - Token purchases and usage
- `token_packages` - Available token packages
- `interviews` - Interview sessions
- `payment_records` - Payment history
- `user_usage` - Usage tracking and limits