# User API Documentation

Base path: `/user` (mounted at `/user`)

All routes require `keycloak.protect()` — Bearer token authentication via Keycloak.

---

## POST /user/:username/cashier-reset-password

**Purpose:** Reset a cashier's password to an auto-generated default. The default password is generated as: first 3 chars uppercase + 4th char lowercase + `@` + last 4 chars of username. The password is set as **temporary** (user must change on next login).

### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| username | string | Yes | Username of the cashier to reset |

### Responses
| Code | Body |
|------|------|
| 200 | `{ "message": "Password reset successfully" }` |
| 400 | `{ "message": "Username is required" }` |
| 404 | `{ "message": "No user found" }` |
| 500 | `{ "message": "<error>" }` |

---

## POST /user/change-password

**Purpose:** Authenticated user changes their own password. Verifies old password against Keycloak token endpoint, then sets the new password as **permanent**.

### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| oldPassword | string | Yes | Current password |
| newPassword | string | Yes | New password |
| confirmPassword | string | Yes | Must match newPassword |

### Responses
| Code | Body |
|------|------|
| 200 | `{ "message": "Password changed successfully" }` |
| 400 | `{ "message": "All fields are required" }` or `"New passwords do not match"` or `"Invalid old password"` |
| 401 | `{ "message": "Unauthorized: User" }` |
| 404 | `{ "message": "No user found" }` |
| 500 | `{ "message": "<error>" }` |

---

## POST /user/

**Purpose:** Create a cashier user in Keycloak tied to a specific merchant. The username must correspond to an existing terminal serial in TMS for the given merchantId.

### Middleware
- `keycloak.protect()`
- `createUserValidationRules` (express-validator)

### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| username | string | Yes | Alphanumeric, must exist as serial in TMS |
| password | string | Yes | Minimum 6 characters |
| role | string | Yes | One of: `"cashier"`, `"merchant"`, `"admin"` |
| merchantId | string | Yes | Merchant ID the user belongs to |

### Responses
| Code | Body |
|------|------|
| 201 | `{ "message": "User created successfully", "userId": "<keycloak-id>" }` |
| 400 | `{ "errors": [...] }` (validation) or `{ "message": "Serials did not exist in TMS" }` |
| 500 | `{ "message": "<error>" }` |

---

## GET /user/merchant

**Purpose:** Get all cashier/terminal users belonging to a merchant. Fetches terminal serials from TMS for the given merchantId, then returns the corresponding Keycloak user data for each serial.

### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| merchantId | string | Yes | Merchant ID to retrieve cashier users for |

### Responses
| Code | Body |
|------|------|
| 200 | `[{ "id": "...", "username": "...", "email": null, "firstName": null, "lastName": null, "enabled": true }]` |
| 400 | `{ "message": "merchantId is required" }` |
| 500 | `{ "message": "<error>" }` |

---

## GET /user/admin

**Purpose:** Get all admin users from Keycloak. Requires the authenticated user to have the `"admin"` client role.

### Responses
| Code | Body |
|------|------|
| 200 | `[{ "id": "...", "username": "...", "email": "...", "firstName": "...", "lastName": "...", "enabled": true }]` |
| 400 | `{ "message": "permission is required" }` |
| 500 | `{ "message": "<error>" }` |