# Medicines, smart pill dispensers and smart inhalers

## Concepts
* **Medicine** (per patient): name, dose text, type (tablet, capsule, controller inhaler, rescue inhaler, injection, liquid, other),
  dose times `HH:MM` (empty = as needed), window ± minutes (default 60), optional smart device + dispenser slot, from / until, WhatsApp reminder.
* **Dose event**: taken · taken late (after the window, within 3 h) · skipped · missed (worker, after the window) · extra · puff (rescue inhaler).
  One event per scheduled slot; a real event replaces the worker's "missed".
* **Adherence** = (taken + late) ÷ (scheduled slots that are over) for 7 and 30 days, per medicine and per patient.

## Who records doses
| Source | How |
|---|---|
| Smart pill dispenser | Vendor cloud → webhook → `POST /api/v1/doses` (Device Adapter API key). Dispensed = taken. |
| Smart inhaler sensor | Vendor cloud → `POST /api/v1/doses` with `type: "puff"` and `puffs`. |
| Patient | CarePulse Connect app → My medicines (taken / puffs), or patient portal "Today's medicines". |
| Nurse / coordinator | Patient → Medicines → Given / Skip. |

## API
`POST /api/v1/doses`
```json
{"device": {"serial": "HERO-77812", "manufacturer": "Hero Health"}, "patient": {"uhid": "UH240100"},
 "events": [{"type": "dispensed", "slot": "A1", "at": "2026-11-18T08:04:00+05:30"},
            {"type": "puff", "puffs": 2, "at": "2026-11-18T10:12:00+05:30"},
            {"type": "refill_low"}]}
```
* Patient from `patient` (uhid / id / mobile) or the device's binding (binding is created when a medicine is linked to the device).
* Medicine matched by `medication_id`, else device + `slot`, else `medication` name (contains), else the only medicine on that device.
* `type`: taken | dispensed | missed | skipped | puff | refill_low. Max 500 events; events more than 5 min in the future are rejected.
* Response: `{"ok":true,"patient_id":12,"results":[{"ok":true,"medication_id":4,"id":901,"status":"taken","scheduled_at":"2026-11-18 08:00:00"}, …]}`.
* Needs patient consent on record (or a current admission).

`GET /api/v1/medications` (patient-app token only) → today's doses `{medication_id, name, dose, kind, slot "HH:MM"|null, status}`.

## Alerts (Settings → AI & medicines)
| Alert | When | Severity |
|---|---|---|
| Missed doses | ≥ N missed in 24 h (default 1); one alert per patient per day, updated with the count, closes when doses are taken | warning |
| Rescue inhaler overuse | puffs in 24 h ≥ limit (default 8) | warning |
| Refill needed | dispenser sends `refill_low` | info |
WhatsApp reminder to patient / caregiver at dose time if not yet taken (template setting `wa_tpl_medicine`: name, medicine, hospital).
Missed doses (< 70 % in 7 days) and rescue overuse feed the AI risk score.

## Device integration status
Dispensers and inhaler sensors are integrated **through their vendor clouds**; each needs a vendor agreement / API access and a
model certification in the device lab during the pilot (Hero, Livi, MedMinder, Philips; Propeller, Hailie / Adherium, FindAir, Respiro).
Check availability in India before quoting — several are US/EU-only; Indian pharmacy-chain pill boxes with app sync are an alternative.
