# Waiter Management API Documentation

These APIs handle both the Administrative management of waiters and the Device interaction for the waiters themselves.

## Table of Contents

- [Admin Operations (Requires Admin Token)](#admin-operations)
  - [Get All Waiters](#get-all-waiters)
  - [Create Waiter](#create-waiter)
  - [Update Waiter Profile](#update-waiter-profile)
  - [Reset Waiter PIN](#reset-waiter-pin)
  - [Delete Waiter](#delete-waiter)
  - [Verify Admin Password](#verify-admin-password)
- [Device Operations (Waiter Tokens)](#device-operations)
  - [Waiter Device Login](#waiter-device-login)
  - [Update Own Status](#update-own-status)
- [WebSocket Real-time Events](#websocket-real-time-events)

---

## Admin Operations

All endpoints under Admin Operations require a valid Admin JWT passed as an `Authorization` header: `Bearer <token>`.

### Get All Waiters
- **Endpoint:** `GET /api/waiters`
- **Description:** Retrieves all waiters, including their real-time device information and number of currently assigned active tables.

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "waiter_id": "WID-104",
      "name": "John Doe",
      "shift": "Morning",
      "status": "Active",
      "tablesAssigned": 4,
      "last_login_device": {
        "device_id": "TAB-01-UUID",
        "device_type": "Tablet",
        "os": "Android",
        "last_seen": "2026-04-16T18:00:00.000Z"
      }
    }
  ]
}
```

### Create Waiter
- **Endpoint:** `POST /api/waiters`
- **Description:** Register a new waiter in the system.

**Request:**
```json
{
  "waiter_id": "WID-105",
  "name": "Alex Mercer",
  "shift": "Night",
  "pin": "1234" 
}
```

**Response:**
```json
{
  "success": true,
  "message": "Waiter created successfully.",
  "data": { "id": 2, "waiter_id": "WID-105", "name": "Alex Mercer", "shift": "Night" }
}
```

### Update Waiter Profile
- **Endpoint:** `PUT /api/waiters/:id`
- **Description:** Update standard fields (name, shift, status) of a waiter. Note: changing `status` here will trigger a WebSocket update.

**Request:**
```json
{
  "name": "Alex M.",
  "shift": "Evening",
  "status": "Break" 
}
```

### Reset Waiter PIN
- **Endpoint:** `PATCH /api/waiters/:id/reset-pin`
- **Description:** Change a waiter's PIN. 

**Request:**
```json
{
  "new_pin": "5678"
}
```

### Delete Waiter
- **Endpoint:** `DELETE /api/waiters/:id`

### Verify Admin Password
- **Endpoint:** `POST /api/admin/verify-password`
- **Description:** A security route used to prompt an existing logged-in Admin for their password before allowing sensitive actions (like resetting PINs or viewing plain-text sensitive info).

**Request:**
```json
{
  "password": "mySecureAdminPassword"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Password verified successfully."
}
```

---

## Device Operations

These routes are hit by the Android/iOS devices carried by waiters.

### Waiter Device Login
- **Endpoint:** `POST /api/waiters/login`
- **Description:** Exchanges `waiter_id` and `pin` for a session JWT. Automatically sets the waiter's status to `Active` and updates device info. Emits a Real-time update.

**Request:**
```json
{
  "waiter_id": "WID-104",
  "pin": "1234",
  "device_info": {
    "device_id": "TAB-01-UUID",
    "device_type": "Tablet",
    "os": "Android"
  }
}
```

**Response:**
```json
{
  "success": true,
  "message": "Login successful.",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "data": {
    "id": 3,
    "waiter_id": "WID-105",
    "name": "Alex Mercer",
    "status": "Active"
  }
}
```

### Update Own Status
- **Endpoint:** `PATCH /api/waiters/me/status`
- **Headers:** `Authorization: Bearer <waiter_jwt>`
- **Description:** Allows the waiter to clock out or go on break. Emits a Real-time update.

**Request:**
```json
{
  "status": "Break"
}
```

### Get Tables by Zones
- **Endpoint:** `GET /api/waiters/tables/zones`
- **Headers:** `Authorization: Bearer <waiter_jwt>`
- **Description:** Returns all active tables grouped by their assigned zones. Includes occupancy details like customer name, pax, and assigned waiter.

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "zone_name": "Balcony",
      "color_code": "#ffaa00",
      "tables": [
        {
          "id": 5,
          "table_number": "B-1",
          "status": "Running",
          "customer_name": "Alex",
          "pax": 2,
          "waiter_name": "John Doe",
          "current_order_started_at": "2026-05-15T01:10:00Z"
        }
      ]
    }
  ]
}
```

---

## WebSocket Real-time Events

Connect a WebSocket Client (Socket.io) to your backend base URL.

### 1. `waiter_status_changed`
Emitted globally when a waiter's status goes from `Off-Duty` -> `Active` or `Active` -> `Break`, etc.

**Payload:**
```json
{
  "waiter_id": "WID-104",
  "new_status": "Break",
  "timestamp": "2026-04-16T18:05:00.000Z"
}
```

### 2. `waiter_tables_updated`
Emitted globally whenever a table operation affects how many active tables a waiter has assigned.
Triggers:
- A Waiter is assigned to a table (`/api/tables/:id/metadata`).
- A table is Settle/Paid (`/api/tables/:id/settle`).
- A table is Cleared (`/api/tables/:id/clear`).

**Payload:**
```json
{
  "waiter_id": "WID-104",
  "tables_assigned": 5
}
```