# Admin API: Agent Status Management

## Overview
These endpoints allow admins to view and manage agent status (Active/Inactive) for their company.

---

## 1. Get All Agents with Status

### Endpoint
```
GET /admin/agents/status
```

### Description
Retrieves all agents for the admin's company with their status. Supports optional filtering by status and line.

### Authentication
- **Required**: Yes
- **Type**: Admin JWT Token
- **Header**: `Authorization: Bearer YOUR_ADMIN_JWT_TOKEN`

### Query Parameters
- `status` (optional): Filter by status - `active` or `inactive`
- `line` (optional): Filter by line name

### Request Example

#### cURL (Bash/Zsh)
```bash
# Get all agents
curl -X GET "http://192.168.1.3:3000/admin/agents/status" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -H "Accept: application/json"

# Get only active agents
curl -X GET "http://192.168.1.3:3000/admin/agents/status?status=active" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -H "Accept: application/json"

# Get agents by line
curl -X GET "http://192.168.1.3:3000/admin/agents/status?line=Line%202" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -H "Accept: application/json"

# Combined filters
curl -X GET "http://192.168.1.3:3000/admin/agents/status?status=active&line=Line%202" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -H "Accept: application/json"
```

#### cURL (PowerShell)
```powershell
$headers = @{
    "Authorization" = "Bearer YOUR_ADMIN_JWT_TOKEN"
    "Accept" = "application/json"
}

# Get all agents
Invoke-RestMethod -Uri "http://192.168.1.3:3000/admin/agents/status" `
  -Method GET `
  -Headers $headers

# Get only active agents
Invoke-RestMethod -Uri "http://192.168.1.3:3000/admin/agents/status?status=active" `
  -Method GET `
  -Headers $headers
```

### Success Response

#### Status Code: 200 OK

```json
{
  "status": "success",
  "message": "Agents retrieved successfully",
  "data": {
    "filters": {
      "status": null,
      "line": null
    },
    "summary": {
      "total_agents": 3,
      "active_agents": 2,
      "inactive_agents": 1
    },
    "agents": [
      {
        "agent_id": 5,
        "agent_name": "Raja",
        "mobile_no": "8825948300",
        "address": "Erode",
        "aadhar_no": "882594830012",
        "report_in": "2025-12-03T09:00:00.000Z",
        "reporting_time": "2025-12-03T20:00:00.000Z",
        "status": "Active",
        "line": "Line 2",
        "last_login": "2025-12-08T08:01:13.000Z",
        "is_logged_in": true,
        "device_type": "web",
        "created_at": "2025-12-03T17:31:14.000Z"
      },
      {
        "agent_id": 6,
        "agent_name": "Kumar",
        "mobile_no": "9876543210",
        "address": "Chennai",
        "aadhar_no": "987654321012",
        "report_in": "2025-12-01T09:00:00.000Z",
        "reporting_time": "2025-12-01T18:00:00.000Z",
        "status": "Inactive",
        "line": "Line 1",
        "last_login": "2025-12-05T10:30:00.000Z",
        "is_logged_in": false,
        "device_type": "android",
        "created_at": "2025-12-01T10:00:00.000Z"
      }
    ]
  }
}
```

### Response Fields

#### filters
- `status`: Applied status filter (if any)
- `line`: Applied line filter (if any)

#### summary
- `total_agents`: Total number of agents
- `active_agents`: Number of active agents
- `inactive_agents`: Number of inactive agents

#### agents (Array)
Each agent object contains:
- `agent_id`: Agent ID
- `agent_name`: Agent name
- `mobile_no`: Mobile number
- `address`: Address
- `aadhar_no`: Aadhar number
- `report_in`: Report in time
- `reporting_time`: Reporting time
- `status`: Status (Active/Inactive)
- `line`: Line assignment
- `last_login`: Last login timestamp
- `is_logged_in`: Current login status
- `device_type`: Device type (android/ios/web)
- `created_at`: Creation timestamp

---

## 2. Update Agent Status

### Endpoint
```
PUT /admin/agents/:agent_id/status
```

### Description
Updates an agent's status to Active or Inactive. Only admins can update agents belonging to their company.

### Authentication
- **Required**: Yes
- **Type**: Admin JWT Token
- **Header**: `Authorization: Bearer YOUR_ADMIN_JWT_TOKEN`

### URL Parameters
- `agent_id` (required): The ID of the agent to update

### Request Body
```json
{
  "status": "Active"
}
```
or
```json
{
  "status": "Inactive"
}
```

### Request Example

#### cURL (Bash/Zsh)
```bash
# Activate an agent
curl -X PUT "http://192.168.1.3:3000/admin/agents/5/status" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "status": "Active"
  }'

# Deactivate an agent
curl -X PUT "http://192.168.1.3:3000/admin/agents/5/status" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "status": "Inactive"
  }'
```

#### cURL (PowerShell)
```powershell
$headers = @{
    "Authorization" = "Bearer YOUR_ADMIN_JWT_TOKEN"
    "Content-Type" = "application/json"
    "Accept" = "application/json"
}

$body = @{
    status = "Active"
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://192.168.1.3:3000/admin/agents/5/status" `
  -Method PUT `
  -Headers $headers `
  -Body $body
```

### Success Response

#### Status Code: 200 OK

```json
{
  "status": "success",
  "message": "Agent status updated to Active successfully",
  "data": {
    "agent": {
      "id": 5,
      "name": "Raja",
      "mobile_no": "8825948300",
      "status": "Active",
      "line": "Line 2",
      "last_login": "2025-12-08T08:01:13.000Z",
      "is_logged_in": true,
      "created_at": "2025-12-03T17:31:14.000Z"
    }
  }
}
```

---

## Error Responses

### 400 Bad Request - Missing Parameters
```json
{
  "status": "error",
  "message": "agent_id is required"
}
```

```json
{
  "status": "error",
  "message": "status is required (Active or Inactive)"
}
```

```json
{
  "status": "error",
  "message": "Invalid status. Must be \"Active\" or \"Inactive\""
}
```

### 401 Unauthorized - Invalid/Missing Token
```json
{
  "status": "error",
  "message": "Admin authentication required"
}
```

### 404 Not Found - Agent Not Found
```json
{
  "status": "error",
  "message": "Agent not found or does not belong to your company"
}
```

### 500 Internal Server Error
```json
{
  "status": "error",
  "message": "Failed to fetch agents",
  "error": "Error message details"
}
```

---

## Notes

1. **Status Values**: The API accepts both `Active`/`Inactive` and `active`/`inactive` (case-insensitive), but stores them as `Active`/`Inactive` in the database.

2. **Company Isolation**: Admins can only view and manage agents belonging to their own company.

3. **Status Filtering**: When filtering by status, use lowercase (`active` or `inactive`) in the query parameter.

4. **Agent Access**: Inactive agents may be restricted from certain operations (this depends on your business logic implementation).

5. **Line Filtering**: The line filter matches exact line names assigned to agents.

---

## Use Cases

1. **View All Agents**: Get a complete list of all agents with their current status
2. **Filter Active Agents**: View only active agents for assignment
3. **Filter by Line**: See agents assigned to a specific line
4. **Activate Agent**: Reactivate a previously inactive agent
5. **Deactivate Agent**: Temporarily disable an agent's access
6. **Status Monitoring**: Track how many agents are active vs inactive

---

## Example Workflow

1. **List all agents**:
   ```bash
   GET /admin/agents/status
   ```

2. **Filter to see only active agents**:
   ```bash
   GET /admin/agents/status?status=active
   ```

3. **Deactivate an agent**:
   ```bash
   PUT /admin/agents/5/status
   Body: { "status": "Inactive" }
   ```

4. **Verify the change**:
   ```bash
   GET /admin/agents/status?status=inactive
   ```

5. **Reactivate the agent**:
   ```bash
   PUT /admin/agents/5/status
   Body: { "status": "Active" }
   ```