# Users Module — API Documentation

Base URL: `http://localhost:PORT/api/v1`

> All endpoints are **Admin only** — require `Authorization: Bearer <admin_token>`.

---

## Table of Contents
1. [Get All Users (Paginated + Filtered)](#1-get-users--all-users)
2. [Get Single User](#2-get-usersid--single-user)
3. [Update User](#3-patch-usersid--update-user)
4. [Delete User (Soft)](#4-delete-usersid--delete-user)

---

## 1. GET `/users` — All Users

Supports pagination, sorting, and filtering. All query params are optional.

**Headers:**
```
Authorization: Bearer <admin_token>
```

**Query Parameters:**
| Param | Type | Description |
|---|---|---|
| `searchTerm` | string | Searches across `name` and `email` |
| `role` | string | Filter by role: `ADMIN` or `USER` |
| `page` | number | Page number (default: `1`) |
| `limit` | number | Items per page (default: `10`) |
| `sortBy` | string | Field to sort by (default: `createdAt`) |
| `sortOrder` | string | `asc` or `desc` (default: `desc`) |

---

#### Basic — `GET /users`

**Response `200`:**
```json
{
  "success": true,
  "message": "Users retrieved successfully",
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 3
  },
  "data": [
    {
      "id": "user-uuid-1",
      "name": "Admin User",
      "email": "admin@example.com",
      "role": "ADMIN",
      "createdAt": "2026-05-28T09:00:00.000Z",
      "updatedAt": "2026-05-28T09:00:00.000Z"
    },
    {
      "id": "user-uuid-2",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "USER",
      "createdAt": "2026-05-29T10:00:00.000Z",
      "updatedAt": "2026-05-29T10:00:00.000Z"
    },
    {
      "id": "user-uuid-3",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "USER",
      "createdAt": "2026-05-30T11:00:00.000Z",
      "updatedAt": "2026-05-30T11:00:00.000Z"
    }
  ]
}
```

---

#### With searchTerm — `GET /users?searchTerm=john`

Searches across `name` and `email`.

**Response `200`:**
```json
{
  "success": true,
  "message": "Users retrieved successfully",
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 1
  },
  "data": [
    {
      "id": "user-uuid-2",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "USER",
      "createdAt": "2026-05-29T10:00:00.000Z",
      "updatedAt": "2026-05-29T10:00:00.000Z"
    }
  ]
}
```

---

#### Filter by role — `GET /users?role=ADMIN`

**Response `200`:**
```json
{
  "success": true,
  "message": "Users retrieved successfully",
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 1
  },
  "data": [
    {
      "id": "user-uuid-1",
      "name": "Admin User",
      "email": "admin@example.com",
      "role": "ADMIN",
      "createdAt": "2026-05-28T09:00:00.000Z",
      "updatedAt": "2026-05-28T09:00:00.000Z"
    }
  ]
}
```

---

#### Pagination + sorting — `GET /users?page=1&limit=2&sortBy=name&sortOrder=asc`

**Response `200`:**
```json
{
  "success": true,
  "message": "Users retrieved successfully",
  "meta": {
    "page": 1,
    "limit": 2,
    "total": 3
  },
  "data": [
    {
      "id": "user-uuid-1",
      "name": "Admin User",
      "email": "admin@example.com",
      "role": "ADMIN",
      "createdAt": "2026-05-28T09:00:00.000Z",
      "updatedAt": "2026-05-28T09:00:00.000Z"
    },
    {
      "id": "user-uuid-3",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "USER",
      "createdAt": "2026-05-30T11:00:00.000Z",
      "updatedAt": "2026-05-30T11:00:00.000Z"
    }
  ]
}
```

> `total: 3` but only 2 returned — use `page=2` to get the remaining 1.

---

#### Combined — `GET /users?searchTerm=example&role=USER&page=1&limit=5`

**Response `200`:**
```json
{
  "success": true,
  "message": "Users retrieved successfully",
  "meta": {
    "page": 1,
    "limit": 5,
    "total": 2
  },
  "data": [
    {
      "id": "user-uuid-2",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "USER",
      "createdAt": "2026-05-29T10:00:00.000Z",
      "updatedAt": "2026-05-29T10:00:00.000Z"
    },
    {
      "id": "user-uuid-3",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "USER",
      "createdAt": "2026-05-30T11:00:00.000Z",
      "updatedAt": "2026-05-30T11:00:00.000Z"
    }
  ]
}
```

---

## 2. GET `/users/:id` — Single User

**Headers:**
```
Authorization: Bearer <admin_token>
```

**Response `200`:**
```json
{
  "success": true,
  "message": "User retrieved successfully",
  "data": {
    "id": "user-uuid-2",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "USER",
    "createdAt": "2026-05-29T10:00:00.000Z",
    "updatedAt": "2026-05-29T10:00:00.000Z"
  }
}
```

**Error `404`:**
```json
{
  "success": false,
  "message": "User not found"
}
```

---

## 3. PATCH `/users/:id` — Update User

Updates `name` and/or `role`. All fields optional. Password changes go through `/auth/change-password`.

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

**Request Body:**
```json
{
  "name": "John Updated",
  "role": "ADMIN"
}
```

**Field Rules:**
| Field | Required | Type | Notes |
|---|---|---|---|
| `name` | No | string | Min 1 character |
| `role` | No | string | `"ADMIN"` or `"USER"` |

**Response `200`:**
```json
{
  "success": true,
  "message": "User updated successfully",
  "data": {
    "id": "user-uuid-2",
    "name": "John Updated",
    "email": "john@example.com",
    "role": "ADMIN",
    "createdAt": "2026-05-29T10:00:00.000Z",
    "updatedAt": "2026-05-30T14:00:00.000Z"
  }
}
```

**Error `404`:**
```json
{
  "success": false,
  "message": "User not found"
}
```

---

## 4. DELETE `/users/:id` — Delete User (Soft)

Soft-deletes the user by setting `deletedAt` timestamp. The user no longer appears in any query but the record is preserved in the database.

**Headers:**
```
Authorization: Bearer <admin_token>
```

**Response `200`:**
```json
{
  "success": true,
  "message": "User deleted successfully",
  "data": {
    "id": "user-uuid-2",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "USER",
    "createdAt": "2026-05-29T10:00:00.000Z",
    "updatedAt": "2026-05-30T15:00:00.000Z"
  }
}
```

**Error `404`:**
```json
{
  "success": false,
  "message": "User not found"
}
```

---

## Notes

- `password` is **never returned** in any response
- Soft-deleted users are **excluded** from all endpoints automatically
- `DELETE` does not permanently remove the record — it sets `deletedAt` to the current timestamp
- To change a user's password use `PATCH /auth/change-password` (requires the user's own token)
