tuna/ADMIN_API.md at 544854ec3f584728bd8836bc150ddae68803ba22

 # 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
 . All admin endpoints require admin role verification
 . JWT tokens are validated on every request
 . User passwords are hashed using bcrypt
 . All database queries use parameterized statements to prevent SQL injection
 . 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