# Waiter Device API Updates (Frontend Documentation)

This document outlines the newly added and updated endpoints specifically tailored for the Waiter KOT (Kitchen Order Ticket) devices. These endpoints allow the waiter to view live orders, create new orders directly from their device, and see their daily completed orders.

---

## 1. Get Live Active Orders (Waiter View)
Fetch all live, active orders that have not been completed or cancelled. 

- **Endpoint**: `GET /api/waiters/orders/live`
- **Auth Required**: Yes (`waiter_token`)
- **Query Params**:
  - `?filter=assigned` (Default) - Returns only orders assigned to the logged-in waiter.
  - `?filter=all` - Returns all live orders in the restaurant.

**Response (Success - 200 OK):**
```json
{
  "success": true,
  "data": [
    {
      "order_id": "TBL12-20260714-190000",
      "table_id": 12,
      "table_number": "Main Hall (12)",
      "waiter_id": "WID-105",
      "customer_name": "John Doe",
      "pax": 3,
      "status": "Running",
      "total": 450.00,
      "waiter_name": "Alex Mercer",
      "items": [
        {
          "menu_item_id": 101,
          "name": "Paneer Butter Masala",
          "quantity": 2,
          "unit_price": 200,
          "is_complimentary": 0,
          "line_total": 400
        }
      ]
    }
  ],
  "total": 1
}
```

---

## 2. Create Order Directly from Waiter Device
Allows the waiter to take an order for a table directly from their device. This immediately locks the table, assigns it to the waiter, and syncs across all live dashboards.

- **Endpoint**: `POST /api/waiters/orders/create`
- **Auth Required**: Yes (`waiter_token`)

**Request Body:**
```json
{
  "table_id": 12,
  "customer_name": "Rohan",
  "pax": 3,
  "order_type": "Dine-in",
  "delivery_charge": 50,
  "parcel_charge": 10,
  "service_charge": 20,
  "additional_charge": 0,
  "other_deduction": 0,
  "waived_off": 0,
  "tip": 0,
  "reason": "Special request",
  "items": [
    {
      "menu_item_id": 105,
      "name": "Chicken Tikka",
      "quantity": 2,
      "unit_price": 250,
      "is_complimentary": false
    },
    {
      "menu_item_id": 45,
      "name": "Garlic Naan",
      "quantity": 4,
      "unit_price": 40,
      "is_complimentary": false
    }
  ]
}
```

**Response (Success - 201 Created):**
```json
{
  "success": true,
  "data": {
    "order_id": "TBL12-20260714-191000",
    "total": 693.00,
    "status": "Running"
  }
}
```

---

## 3. Update Order Status (Mark as Served)
Waiters can update the status of their live orders (e.g., from `READY` to `SERVED`). *Note: This is an existing endpoint, but the waiter token is fully supported here.*

- **Endpoint**: `PATCH /api/orders/:orderId/status`
- **Auth Required**: Yes (`waiter_token` or Admin token)

**Request Body:**
```json
{
  "status": "SERVED"
}
```

**Response (Success - 200 OK):**
```json
{
  "success": true,
  "message": "Order status updated successfully."
}
```

---

## 4. Get Waiter Profile (Updated Metrics)
The standard waiter profile endpoint now returns `orders_completed_today` to show the waiter their exact performance/logs for the current day.

- **Endpoint**: `GET /api/waiters/me`
- **Auth Required**: Yes (`waiter_token`)

**Response (Success - 200 OK):**
```json
{
  "success": true,
  "data": {
    "id": 2,
    "waiter_id": "WID-105",
    "name": "Alex Mercer",
    "shift": "Morning",
    "status": "Active",
    "tablesAssigned": 4,
    "orders_completed_today": 12
  }
}
```

---

## 5. WebSocket Real-Time Events
When a waiter creates an order via `/api/waiters/orders/create`, the following WebSocket events are instantly broadcast. The frontend KDS or Admin Dashboard can listen to these to automatically refresh without polling:

1. **`order_created`**: Emitted globally when the order is generated.
2. **`table_updated`**: Marks the table as `Running` and assigned to the waiter.
3. **`waiter_tables_updated`**: Re-emits the active table count for the assigned waiter.
