# Kitchen Mobile App APIs

These are the updated APIs and expected values for the Kitchen Mobile App / Kitchen Display System (KDS).

## Base URL
All routes are prefixed with `/api/kitchen`

---

## 1. Authentication APIs

### 1.1 Login
*   **Route:** `POST /api/kitchen/auth/login`
*   **Description:** Public route. Logs in a kitchen staff member using their ID and PIN. Returns a 12-hour JWT token.
*   **Headers:** None
*   **Body:**
    ```json
    {
      "kitchen_id": "string (Required. Alphanumeric, hyphens or underscores)",
      "pin": "string (Required. Exactly 4 digits)"
    }
    ```
*   **Success Response (200):**
    ```json
    {
      "success": true,
      "message": "Welcome, John! Kitchen session started.",
      "data": {
        "token": "ey...",
        "staff": {
          "id": 1,
          "kitchen_id": "chef_john",
          "name": "John Doe",
          "is_live": 1
        }
      }
    }
    ```

### 1.2 Get My Profile
*   **Route:** `GET /api/kitchen/auth/me`
*   **Description:** Protected route. Returns the profile of the currently logged-in kitchen staff.
*   **Headers:** `Authorization: Bearer <token>`
*   **Success Response (200):**
    ```json
    {
      "success": true,
      "data": {
        "role": "kitchen",
        "id": 1,
        "kitchen_id": "chef_john",
        "name": "John Doe",
        "is_active": 1,
        "is_live": 1,
        "created_by": 1,
        "last_login": "2023-10-10T12:00:00Z",
        "created_at": "...",
        "updated_at": "..."
      }
    }
    ```

---

## 2. KDS / Operational APIs
**Note:** All of the following routes require a valid JWT token (`Authorization: Bearer <token>`).

### 2.1 Get Live KOTs
*   **Route:** `GET /api/kitchen/live`
*   **Description:** Returns all active KOTs that have a status of 'pending' or 'preparing', enriched with their line items. The primary endpoint for rendering the KDS screen. Tickets are ordered oldest first.
*   **Headers:** `Authorization: Bearer <token>`
*   **Success Response (200):**
    ```json
    {
      "success": true,
      "total": 5,
      "data": [
        {
          "kot_id": 12,
          "order_id": "ORD123",
          "status": "PREPARING",
          "is_printed": 0,
          "notes": "VIP table",
          "created_at": "...",
          "started_at": "...",
          "completed_at": null,
          "table_id": 5,
          "table_number": "T-5",
          "waiter_id": 2,
          "waiter_name": "Alice",
          "items": [
            {
              "id": 45,
              "kot_id": 12,
              "menu_item_id": 101,
              "name": "Margherita Pizza",
              "quantity": 1,
              "portion": "Full",
              "modifiers": "Extra cheese",
              "is_done": 0,
              "is_complimentary": 0,
              "status": "sent_to_kitchen",
              "hold_reason": null
            }
          ]
        }
      ]
    }
    ```

### 2.2 Update KOT Status
*   **Route:** `PATCH /api/kitchen/kot/:id/status`
*   **Description:** Move a KOT forward in its lifecycle. Valid progression: `PREPARING` → `READY` → `SERVED`. Note: only admin or waiters can mark a KOT as `SERVED`.
*   **Headers:** `Authorization: Bearer <token>`
*   **Body:**
    ```json
    {
      "status": "PREPARING"  // Options: "PREPARING", "READY", "SERVED"
    }
    ```
*   **Success Response (200):**
    ```json
    {
      "success": true,
      "data": {
        "kot_id": 12,
        "status": "PREPARING",
        "previous_status": "CREATED"
      }
    }
    ```

### 2.3 Toggle Item Done
*   **Route:** `PATCH /api/kitchen/item/:id/toggle`
*   **Description:** Toggles the `is_done` flag for a single line item within a KOT. Emits a WebSocket event to sync screens.
*   **Headers:** `Authorization: Bearer <token>`
*   **Success Response (200):**
    ```json
    {
      "success": true,
      "data": {
        "item_id": 45,
        "is_done": true
      }
    }
    ```

### 2.4 Send KOT (Create new KOT)
*   **Route:** `POST /api/kitchen/kot/send`
*   **Description:** Creates a new KOT for an existing order and broadcasts the `kot:new` event via WebSocket. Idempotency is supported via `request_id`.
*   **Headers:** `Authorization: Bearer <token>`
*   **Body:**
    ```json
    {
      "order_id": "string (Required)",
      "request_id": "string (Optional, for idempotency to avoid duplicates)",
      "notes": "string (Optional. Customer notes for the entire KOT)",
      "items": [
        {
          "id": "number (Required. Maps to menu_item_id)",
          "name": "string (Required)",
          "qty": "number (Required)",
          "portion": "string (Optional)",
          "modifiers": "string (Optional. Chef instructions)",
          "is_comp": "boolean (Optional)",
          "status": "string (Optional. Default 'sent_to_kitchen'. Set to 'hold' if the item is on hold)",
          "hold_reason": "string (Optional. The reason message if the item status is 'hold')"
        }
      ]
    }
    ```
*   **Success Response (201):**
    ```json
    {
      "success": true,
      "message": "KOT #12 sent to kitchen for order 'ORD123'.",
      "data": { ... } // full KOT object
    }
    ```

### 2.5 Print KOT
*   **Route:** `POST /api/kitchen/kot/:id/print`
*   **Description:** Marks a KOT as `is_printed = true` in the DB and returns a print-optimised JSON payload.
*   **Headers:** `Authorization: Bearer <token>`
*   **Success Response (200):**
    ```json
    {
      "success": true,
      "message": "KOT printed.",
      "data": { ... } // full KOT object
    }
    ```
