# Waiter APIs Documentation (Production Auth Version)

This document covers the production-level authentication and management APIs for Waiters.

---

## 1. Authentication APIs
Mounted at: `/api/waiter/auth`

### A) Waiter Login (PIN-Only)
Exchange a 4-digit PIN for a secure session cookie.

- **URL:** `/api/waiter/auth/login`
- **Method:** `POST`
- **Access:** Public
- **Request Body:**
```json
{
  "waiter_pin": "1234",
  "device_name": "Samsung Tab A8",
  "ip_address": "192.168.1.15"
}
```

- **Response (Success):**
  - **Status Code:** `200 OK`
  - **Cookie Set:** `waiter_token` (HTTP-Only, Secure, valid for 10 hours)
```json
{
    "success": true,
    "message": "Login successful.",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "data": {
        "id": 3,
        "waiter_id": "WID-105",
        "name": "Alex Mercer",
        "status": "Active"
    }
}
```

- **Response (Failure):**
  - **Status Code:** `401 Unauthorized` (Invalid PIN)
  - **Status Code:** `400 Bad Request` (Missing fields)

---

### B) Get Profile
- **URL:** `/api/waiters/me`
- **Method:** `GET`
- **Auth:** `waiter_token`
- **Response:** Returns the waiter's own details, shift, current status, and number of assigned tables.

### C) Get Personal Login Logs
- **URL:** `/api/waiters/me/logs`
- **Method:** `GET`
- **Auth:** `waiter_token`
- **Query Params:** `page` (default 1), `limit` (default 20)
- **Response:** List of own login/logout history with device and IP details.

### C) Logout
Clears the session cookie and updates login logs.
- **URL:** `/api/waiters/logout` (or `/api/waiter/auth/logout`)
- **Method:** `POST`
- **Auth:** `waiter_token`
- **Access:** Private (Requires valid `waiter_token` cookie)
- **Response:**
  - **Status Code:** `200 OK`
```json
{
  "success": true,
  "message": "Logged out successfully."
}
```

---

### C) Get Tables by Zones
Fetch all active tables grouped by their respective zones (floor-wise).

- **URL:** `/api/waiters/tables/zones`
- **Method:** `GET`
- **Access:** Private (Requires Waiter JWT)
- **Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "zone_name": "Main Hall",
      "color_code": "#ff0000",
      "tables": [
        {
          "id": 10,
          "table_number": "1",
          "status": "Running",
          "customer_name": "John Doe",
          "pax": 4,
          "waiter_name": "Alex",
          "current_order_started_at": "2026-05-15T01:00:00Z"
        }
      ]
    }
  ]
}
```

---

## 2. Waiter Management (Admin)
Mounted at: `/api/waiters`
*All routes below require Admin JWT Authorization header.*

### 1. Get Waiter List (Minimal)
- **URL:** `/api/waiters/list`
- **Method:** `GET`
- **Description:** Returns a minimal list of active waiters (omits deleted) for dropdowns and assignments.
- **Response (200 OK):**
```json
{
  "success": true,
  "data": [
    {
      "waiter_id": "WID-105",
      "name": "Alex Mercer"
    }
  ]
}
```

### 2. Get All Waiters (Full Management & Device Info)
- **URL:** `/api/waiters`
- **Method:** `GET`
- **Description:** Returns complete management list including current working status, assigned tables count, and last logged-in device details.
- **Response (200 OK):**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "waiter_id": "WID-105",
      "name": "Alex Mercer",
      "mobile_number": "9876543210",
      "email": "alex.m@example.com",
      "address": "123 Main Street, NY",
      "shift": "Morning",
      "status": "Active",
      "tablesAssigned": 3,
      "last_login_device": {
        "device_id": "TAB-01",
        "device_type": "Android Tablet",
        "os": "Android 12",
        "last_seen": "2026-05-15T08:30:00.000Z"
      }
    }
  ]
}
```

### 3. Create Waiter
- **URL:** `/api/waiters`
- **Method:** `POST`
- **Description:** Creates a new waiter profile with a secure 4-digit PIN for device login.
- **Request Body:**
```json
{ 
  "waiter_id": "WID-105", 
  "name": "Alex Mercer", 
  "mobile_number": "9876543210",
  "email": "alex.m@example.com",
  "address": "123 Main Street, NY",
  "pin": "1122", 
  "shift": "Morning" 
}
```
- **Responses:**
  - `201 Created`: `{ "success": true, "message": "Waiter created successfully.", "data": { "id": 1, "waiter_id": "WID-105", "name": "Alex Mercer", "mobile_number": "9876543210", "email": "alex.m@example.com", "address": "123 Main Street, NY", "shift": "Morning" } }`
  - `400 Bad Request`: `{ "success": false, "message": "waiter_id, name, and pin are required." }` or `{ "success": false, "message": "PIN must be exactly 4 digits." }`
  - `409 Conflict`: `{ "success": false, "message": "waiter_id already exists." }`

### 4. Update Waiter Profile & Status
- **URL:** `/api/waiters/:id`
- **Method:** `PUT`
- **Description:** Updates the waiter's details. If status is updated, it automatically emits a `waiter_status_changed` WebSocket event.
- **Request Body:** (Any combination of the following)
```json
{ 
  "name": "Alex M.", 
  "mobile_number": "9998887776",
  "email": "alex.updated@example.com",
  "address": "456 Advanced Ave, NY",
  "status": "Inactive", 
  "shift": "Night" 
}
```
- **Responses:**
  - `200 OK`: `{ "success": true, "message": "Waiter updated successfully." }`
  - `400 Bad Request`: `{ "success": false, "message": "No fields provided to update." }` or `{ "success": false, "message": "Invalid status. Allowed: Inactive, Active, Break, Off-Duty, Suspended, Weekly-Off, Deleted" }`

### 5. Reset PIN
- **URL:** `/api/waiters/:id/reset-pin`
- **Method:** `PATCH`
- **Description:** Allows an admin to securely reset a waiter's 4-digit login PIN.
- **Request Body:**
```json
{
  "new_pin": "4433"
}
```
- **Responses:**
  - `200 OK`: `{ "success": true, "message": "PIN reset successfully." }`
  - `400 Bad Request`: `{ "success": false, "message": "new_pin must be exactly 4 digits." }`

### 6. Delete Waiter
- **URL:** `/api/waiters/:id`
- **Method:** `DELETE`
- **Description:** Permanently deletes a waiter from the database.
- **Responses:**
  - `200 OK`: `{ "success": true, "message": "Waiter deleted successfully." }`

### Get Login Logs
- **URL:** `/api/waiters/logs`
- **Method:** `GET`
- **Description:** Returns the complete history of waiter logins, logouts, and automatic expiries.
- **Query Params:** `page` (default 1), `limit` (default 50), `waiter_id` (optional filter).
- **Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "waiter_id": "WID-105",
      "name": "Alex Mercer",
      "device_name": "Tablet-01",
      "ip_address": "192.168.1.10",
      "login_time": "2026-05-15T01:00:00Z",
      "logout_time": "2026-05-15T11:00:00Z",
      "session_status": "Expired"
    }
  ],
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 50,
    "total_pages": 2
  }
}
```

---

## 3. Waiter Self-Management
Mounted at: `/api/waiters`

### Update Own Status
- **URL:** `/api/waiters/me/status`
- **Method:** `PATCH`
- **Access:** Private (Waiter JWT)
- **Body:** `{ "status": "Break" }`
- **Description:** Allows a waiter to manage their current active state. Allowed values: `Active`, `Break`, `Off-Duty`, `Inactive`.

---

## 4. Security & Implementation Details

1.  **Cookie Persistence**: The `waiter_token` is an HTTP-Only cookie, making it inaccessible to client-side JavaScript (XSS protection). It is configured to expire automatically after **10 hours**.
2.  **Session Tracking**: Every login is recorded in the `waiter_login_logs` table with the following details:
    *   Waiter ID
    *   Device Name
    *   IP Address
    *   Login/Logout Timestamps
3.  **Real-time Updates**: Login and Status changes trigger the `waiter_status_changed` WebSocket event to notify the Admin dashboard.
4.  **Error Handling**: Standardized JSON error responses with appropriate HTTP status codes (400, 401, 403, 500).
