Skill: clinic-queue-manager API

# Skill: clinic-queue-manager API

## When to use this skill
Use when building, extending, or debugging the clinic-queue-manager REST API. Covers all HTTP endpoints, authentication model, WebSocket usage, and data validation rules.

## Prerequisites
- Server running: `pnpm --filter clinic-queue-manager dev`
- Default port: `3854`
- Base URL: `http://localhost:3854`
- WebSocket URL: `ws://localhost:3854/ws`
- Database: SQLite at `data/queue.db` (WAL mode, auto-created on first run)

## Privacy model
- Patient labels are accepted and stored but NEVER written to server logs
- Logs contain only: queue entry IDs, ticket numbers, status transitions, event types
- Visit reason notes are stored but logged only as "(visit reason omitted)"
- Log level controlled via `LOG_LEVEL` env var (default: `info`)

## Seed data (created on first run if tables are empty)
Rooms: Room 1, Room 2, Room 3 (all active)
Providers: Sample Doctor A (doctor), Sample Doctor B (doctor), Sample Nurse A (nurse) (all active)

---

## Queue Entries API

### List queue entries
```bash
# All active entries (waiting + called + with_provider) sorted by priority desc, registered_at asc
curl http://localhost:3854/api/queue

# Filter by status
curl "http://localhost:3854/api/queue?status=waiting"
curl "http://localhost:3854/api/queue?status=called"
curl "http://localhost:3854/api/queue?status=with_provider"

# Filter by date (ISO date, defaults to today)
curl "http://localhost:3854/api/queue?date=2026-03-20"

# Include completed entries
curl "http://localhost:3854/api/queue?include_done=1"
```

Response shape:
```json
{
  "entries": [
    {
      "id": 1,
      "ticket_number": "037",
      "queue_date": "2026-03-20",
      "priority": 2,
      "status": "waiting",
      "room_id": null,
      "room_name": null,
      "provider_id": null,
      "provider_name": null,
      "registered_at": "2026-03-20T09:03:00.000Z",
      "called_at": null,
      "seen_at": null,
      "done_at": null,
      "wait_minutes": 42
    }
  ],
  "count": 11
}
```

### Register a new patient
```bash
curl -X POST http://localhost:3854/api/queue \
  -H "Content-Type: application/json" \
  -d '{
    "patient_label": "Sample Patient",
    "priority": 0,
    "room_id": 1,
    "provider_id": 1,
    "notes": "optional notes"
  }'
```

Fields:
- `patient_label` (string, required, max 120 chars) - display name, never logged
- `priority` (0=Normal, 1=Urgent, 2=Emergency, default 0)
- `room_id` (integer | null, optional)
- `provider_id` (integer | null, optional)
- `notes` (string | null, optional, max 500 chars)

Response: `201 Created` with the new entry including auto-assigned `ticket_number` (padded to 3 digits, e.g. "043").

### Get next patient to call
```bash
# Returns the highest-priority, longest-waiting entry with status=waiting
curl http://localhost:3854/api/queue/next
```

Response: single entry object or `{ "entry": null }` if queue is empty.

### Get single entry
```bash
curl http://localhost:3854/api/queue/42
```

### Update an entry (assign room/provider, change priority)
```bash
curl -X PATCH http://localhost:3854/api/queue/42 \
  -H "Content-Type: application/json" \
  -d '{ "room_id": 2, "provider_id": 1, "priority": 1 }'
```

Patchable fields: `patient_label`, `priority`, `room_id`, `provider_id`, `notes`.
Status transitions use the dedicated `/status` endpoint.

### Transition queue entry status
```bash
# waiting -> called
curl -X POST http://localhost:3854/api/queue/42/status \
  -H "Content-Type: application/json" \
  -d '{ "status": "called" }'

# called -> with_provider
curl -X POST http://localhost:3854/api/queue/42/status \
  -H "Content-Type: application/json" \
  -d '{ "status": "with_provider" }'

# with_provider -> done
curl -X POST http://localhost:3854/api/queue/42/status \
  -H "Content-Type: application/json" \
  -d '{ "status": "done" }'

# called -> no_show (or waiting -> no_show)
curl -X POST http://localhost:3854/api/queue/42/status \
  -H "Content-Type: application/json" \
  -d '{ "status": "no_show" }'
```

Valid transitions:
| From | To (allowed) |
|------|-------------|
| waiting | called, no_show |
| called | with_provider, no_show, waiting (recall) |
| with_provider | done, no_show |
| done | (terminal) |
| no_show | waiting (re-admit - new ticket number assigned) |

Invalid transitions return `409 Conflict` with `{ "error": "Invalid status transition: X -> Y" }`.

When transitioning to `no_show` from any state, the entry is marked final.
When transitioning from `no_show` to `waiting` (re-admit), a new `ticket_number` is assigned for today.

### Delete an entry
```bash
curl -X DELETE http://localhost:3854/api/queue/42
```

Only entries with status `done` or `no_show` can be deleted. Returns `409` if active.

---

## Rooms API

### List rooms
```bash
curl http://localhost:3854/api/rooms
# Include inactive
curl "http://localhost:3854/api/rooms?include_inactive=1"
```

### Create room
```bash
curl -X POST http://localhost:3854/api/rooms \
  -H "Content-Type: application/json" \
  -d '{ "name": "Room 4" }'
```

### Update room
```bash
curl -X PATCH http://localhost:3854/api/rooms/1 \
  -H "Content-Type: application/json" \
  -d '{ "name": "Room 1A", "is_active": 1 }'
```

### Delete room
```bash
curl -X DELETE http://localhost:3854/api/rooms/1
```
Returns `409` if any `waiting` or `called` entries are assigned to this room.

---

## Providers API

### List providers
```bash
curl http://localhost:3854/api/providers
# Include inactive
curl "http://localhost:3854/api/providers?include_inactive=1"
```

### Create provider
```bash
curl -X POST http://localhost:3854/api/providers \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sample Doctor D", "role": "doctor" }'
```

Roles: `doctor`, `nurse`, `admin`

### Update provider
```bash
curl -X PATCH http://localhost:3854/api/providers/1 \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sample Doctor A", "is_active": 0 }'
```

---

## Stats API

### Today's stats
```bash
curl http://localhost:3854/api/stats/today
```

Response:
```json
{
  "date": "2026-03-20",
  "registered": 31,
  "seen": 24,
  "no_shows": 3,
  "currently_waiting": 7,
  "currently_called": 2,
  "currently_with_provider": 2,
  "avg_wait_minutes": 18,
  "avg_consult_minutes": 8,
  "no_show_rate_pct": 9.7,
  "hourly": [
    { "hour": 8, "count": 1 },
    { "hour": 9, "count": 4 }
  ],
  "by_provider": [
    { "provider_id": 1, "provider_name": "Sample Doctor A", "seen": 12, "avg_wait_minutes": 16, "avg_consult_minutes": 8, "no_shows": 1 }
  ]
}
```

### Historical stats
```bash
# Last 30 days (default)
curl http://localhost:3854/api/stats/history

# Date range
curl "http://localhost:3854/api/stats/history?from=2026-02-19&to=2026-03-20"
```

---

## Settings API

### Get settings
```bash
curl http://localhost:3854/api/settings
```

### Update settings
```bash
curl -X PATCH http://localhost:3854/api/settings \
  -H "Content-Type: application/json" \
  -d '{
    "clinic_name": "Sample Medical Centre",
    "default_priority": 0,
    "ticket_reset": "daily",
    "show_est_wait": 1,
    "show_called_section": 1,
    "display_refresh_seconds": 60,
    "urgent_wait_threshold_min": 15,
    "alert_wait_threshold_min": 30,
    "log_level": "info"
  }'
```

---

## WebSocket

Connect to `ws://localhost:3854/ws` to receive real-time queue updates.

### Client sends (after connect)
```json
{ "type": "subscribe" }
```

### Server sends - initial state
```json
{
  "type": "queue_state",
  "entries": [...],
  "stats": { "waiting": 7, "called": 2, "avg_wait_minutes": 18, "seen_today": 24 }
}
```

### Server sends - new entry registered
```json
{
  "type": "queue_add",
  "entry": { "id": 44, "ticket_number": "044", "priority": 0, "status": "waiting", ... }
}
```

### Server sends - status transition or field update
```json
{
  "type": "queue_update",
  "entry": { "id": 42, "status": "called", "called_at": "2026-03-20T09:52:00.000Z", ... }
}
```

### Server sends - entry removed (deleted)
```json
{
  "type": "queue_remove",
  "id": 42
}
```

### Server sends - periodic stats (every 30 seconds via cron)
```json
{
  "type": "stats_update",
  "stats": { "waiting": 7, "called": 2, "avg_wait_minutes": 18, "seen_today": 24 }
}
```

---

## Full API reference

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/queue | List queue entries |
| POST | /api/queue | Register new patient |
| GET | /api/queue/next | Get next patient to call |
| GET | /api/queue/:id | Get single entry |
| PATCH | /api/queue/:id | Update entry fields |
| POST | /api/queue/:id/status | Transition status |
| DELETE | /api/queue/:id | Delete done/no_show entry |
| GET | /api/rooms | List rooms |
| POST | /api/rooms | Create room |
| PATCH | /api/rooms/:id | Update room |
| DELETE | /api/rooms/:id | Delete room |
| GET | /api/providers | List providers |
| POST | /api/providers | Create provider |
| PATCH | /api/providers/:id | Update provider |
| DELETE | /api/providers/:id | Delete provider |
| GET | /api/stats/today | Today's stats |
| GET | /api/stats/history | Historical stats |
| GET | /api/settings | Get settings |
| PATCH | /api/settings | Update settings |

---

## Priority values
| Value | Label | Color |
|-------|-------|-------|
| 0 | Normal | (default) |
| 1 | Urgent | #d97706 |
| 2 | Emergency | #dc2626 |

## Status values
| Value | Meaning |
|-------|---------|
| waiting | In queue, not yet called |
| called | Called to room, not yet seen by provider |
| with_provider | Currently in consultation |
| done | Consultation complete |
| no_show | Did not respond when called |

## Ticket numbering
- Format: zero-padded 3-digit string (`"001"` to `"999"`)
- Increments sequentially per `queue_date`
- Resets daily (configurable to weekly or never via settings)
- Re-admitted patients receive a new ticket number for the current day

## Env vars
| Variable | Default | Description |
|----------|---------|-------------|
| PORT | 3854 | HTTP and WebSocket port |
| LOG_LEVEL | info | Pino log level (debug/info/warn/error) |
| DB_PATH | data/queue.db | SQLite database file path |

## Validation rules
- `patient_label` max 120 characters, required
- `priority` must be 0, 1, or 2
- `notes` max 500 characters
- `room_id` must reference an existing active room if provided
- `provider_id` must reference an existing active provider if provided
- Status transitions that are not in the allowed list return 409

## Troubleshooting
- **WebSocket not receiving updates**: confirm client sent `{ "type": "subscribe" }` after connect
- **409 on status transition**: check current status; see valid transitions table
- **Ticket numbers not resetting**: `ticket_reset` setting defaults to `"daily"` but only resets at midnight when a new entry is first registered on the new date
- **Port conflict**: set `PORT=3854` in `.env` or change to any unused port