Feature 16: NestQuest API Service #165

2026-09-23T04:28:30-04:00

dev_agent commented

2026-09-23 04:28:30 -04:00

Feature 16 — NestQuest API Service (feature → dev)

Standalone FastAPI service that owns the NestQuest database and exposes it to the Home Assistant integration (panel plane) and the admin PWA (admin plane), per docs/ARCHITECTURE.md. This is the Feature 16 integration PR (all required tasks complete).

Delivered

Core extractions (HA-free, bundled in the integration):

core/snapshot.py — shared panel snapshot builder.
core/presence_management.py — presence write layer (the integration's presence services now delegate to it).
core/settings_store.py — DB-backed settings store (meta_state, no schema change) reusing the core validators.
core/history.py — history query + CSV.
core/sweep.py — HA-free missed sweep (the integration sweep is now a thin bus-firing shim).

API (api/):

Skeleton: /health, OpenAPI, core wiring (nestquest_core loader), config.
Panel plane (service token, LAN): GET /api/v1/panel/snapshot, POST /api/v1/panel/instances/{id}/complete (idempotent), GET /api/v1/panel/events (SSE).
Transitions: quest-completed, quest-uncompleted, child-day-complete, quest-missed — payloads built by the core builders; one in-process publisher; a lifespan scheduler runs the missed sweep at the configured rollover time.
Admin plane (Authentik OIDC JWT + nestquest-admins; panel token rejected outright): children CRUD/reorder/active, quest definitions (create/update/active), presence schedule/override, uncomplete + regenerate, history + CSV, settings read/update, missed-sweep trigger.
Thin adapters only — all business rules live in core/.

Verification

TZ=UTC uv run pytest -q → 1774 passed (feature branch, after merging origin/dev).
TZ=UTC uv run pytest -q orchestration_tests → 14 passed (merged dev tooling).
Every task PR was independently reviewed by Claude Sonnet 5 (high) at its exact head; three required a remediation cycle (JWKS cache hardening, constant-time panel-token comparison, missed-event publish ordering).

Notes

The feature branch incorporates origin/dev (merge commit df58587).
Deferred low-severity nits are recorded on the individual Maestro tasks.

## Feature 16 — NestQuest API Service (feature → dev) Standalone FastAPI service that owns the NestQuest database and exposes it to the Home Assistant integration (panel plane) and the admin PWA (admin plane), per `docs/ARCHITECTURE.md`. This is the Feature 16 integration PR (all required tasks complete). ### Delivered **Core extractions (HA-free, bundled in the integration):** - `core/snapshot.py` — shared panel snapshot builder. - `core/presence_management.py` — presence write layer (the integration's presence services now delegate to it). - `core/settings_store.py` — DB-backed settings store (meta_state, no schema change) reusing the core validators. - `core/history.py` — history query + CSV. - `core/sweep.py` — HA-free missed sweep (the integration sweep is now a thin bus-firing shim). **API (`api/`):** - Skeleton: `/health`, OpenAPI, core wiring (`nestquest_core` loader), config. - Panel plane (service token, LAN): `GET /api/v1/panel/snapshot`, `POST /api/v1/panel/instances/{id}/complete` (idempotent), `GET /api/v1/panel/events` (SSE). - Transitions: quest-completed, quest-uncompleted, child-day-complete, quest-missed — payloads built by the core builders; one in-process publisher; a lifespan scheduler runs the missed sweep at the configured rollover time. - Admin plane (Authentik OIDC JWT + `nestquest-admins`; panel token rejected outright): children CRUD/reorder/active, quest definitions (create/update/active), presence schedule/override, uncomplete + regenerate, history + CSV, settings read/update, missed-sweep trigger. - Thin adapters only — all business rules live in `core/`. ### Verification - `TZ=UTC uv run pytest -q` → **1774 passed** (feature branch, after merging `origin/dev`). - `TZ=UTC uv run pytest -q orchestration_tests` → **14 passed** (merged dev tooling). - Every task PR was independently reviewed by Claude Sonnet 5 (high) at its exact head; three required a remediation cycle (JWKS cache hardening, constant-time panel-token comparison, missed-event publish ordering). ### Notes - The feature branch incorporates `origin/dev` (merge commit `df58587`). - Deferred low-severity nits are recorded on the individual Maestro tasks.

dev_agent added 16 commits 2026-09-23 04:28:31 -04:00

FastAPI skeleton: health, OpenAPI, core wiring (task 042dfc5c) 7fec3c76ef

FastAPI skeleton: health, OpenAPI, core wiring (task 042dfc5c)

Extract the panel snapshot builder into core (task 9047a97b) ca477125d6

Extract the panel snapshot builder into core (task 9047a97b)

Panel plane: service-token auth and snapshot route (#152 ) 4da762173c

Panel plane: complete route (idempotent) (#153 ) 550a8b3e1e

SSE endpoint and the quest-completed transition (#154 ) a07ce1b2f2

SSE: publish uncompleted, child-day-complete and missed (#155 ) d4a55b6b40

Admin auth: Authentik JWT validation (#156 ) ca1165de3f

Admin auth: nestquest-admins group gate and service-token rejection (#157 ) a30b852789

Admin routes: children (#158 ) 0b7f71831b

Admin routes: quest definitions (#159 ) e85180d492

Co-authored-by: Joshua <joshua@cnjmail.com>
Co-committed-by: Joshua <joshua@cnjmail.com>

Admin routes: presence schedule and override (#160 ) a3773fec8c

Admin routes: uncomplete and regenerate (#161 ) f31f6dc80e

Admin routes: history query and CSV export (#162 ) 0255017cdc

Admin routes: settings read and update (#163 ) fa4415c0d5

Run the missed sweep in the API and publish quest-missed on SSE (task 058c7b69) (#164 ) b1dbb8e1a5

Merge origin/dev into feature/cd03735b-2498-4b34-b84c-c1cb2b271ba7-nestquest-api-service df585878fb

review_agent approved these changes

2026-09-23 04:35:12 -04:00

review_agent left a comment

Independent Claude Sonnet 5 review completed for this exact commit.

approver_agent merged commit d78ef196d0 into dev

2026-09-23 04:37:27 -04:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Maniacs_Mansion/NestQuest#165