Docs: every v2 route documents its body, answer and parameters (1.52.1)

Most routes answered by a v1 handler showed an empty body and
`data: unknown` in /docs/v2. Each now documents what its handler reads
and answers, and every path and query parameter is described.

- `documented: { body?, response? }` on v1Route/defineRoute, with shared
  shapes in src/v2/docs.ts. Documentation only: not enforced, so nothing
  that works can start failing; outside production a body or answer that
  doesn't fit is logged ("doesn't match its documented schema").
- QUERY_HELP / PATH_HELP describe common parameters; empty bodies say
  "No body needed".
- Declared the funnel's eventIds and webhook deliveries' status/before.
- tests/v2Docs.test.ts keeps the document complete; frontend types
  regenerated, three call sites' types tightened (no payload change).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-02 13:26:15 +02:00
co-authored by Claude Opus 5.5
parent 6e64e64bff
commit d74af96f1d
27 changed files with 34727 additions and 1036 deletions
+12 -1
View File
@@ -1,6 +1,6 @@
# Handover — where things stand and how to carry on
Last updated: 2026-11-02, after **1.52.0** (and Hub 1.5.0). The plan itself is in
Last updated: 2026-11-02, after **1.52.1** (and Hub 1.5.0). The plan itself is in
[ROADMAP-v2.md](./ROADMAP-v2.md) (decisions table at the end); the previous round of
features is in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
@@ -14,6 +14,7 @@ encrypted settings unreadable or break existing installs.
| Version | What |
|---------|------|
| 1.52.1 | **API documentation complete:** every v2 route documents its body, answer and parameters — the ~300 answered by v1 handlers through `documented` shapes (`src/v2/docs.ts`), shown but not enforced, logged outside production when they don't fit; empty bodies say "No body needed". Test `tests/v2Docs.test.ts` |
| 1.52.0 | **Urgent fix + Corrections:** required attendee forms no longer leave paid door/manual registrations without tickets — popup with "Fill in later" (`Registration.formWaivedAt`, `POST /api/v2/registrations/{id}/form-later`); one form per person on picked sessions; forms with no questions don't hold tickets; kiosk asks for the forms the server says are missing. Admin **Corrections** page (`src/services/corrections.ts`, `/api/v2/corrections/…`): issue missing tickets, pay later (`ticketsReleasedAt`), make it free (`complimentaryDiscount`), check in after the event. Migration `20261102120000_corrections`. e2e `e2e/corrections.spec.ts` |
| 1.51.17 | **Security:** forgot-password and sign-in don't reveal whether an account exists (same answer, status and timing); forgot-password rate-limited |
| 1.51.16 | **Incoming webhooks and message links on v2** — `src/v2/links.ts` (`/api/v2/webhooks/…`, one-click unsubscribe, 308s for old links); provider URLs and email links point at v2 |
@@ -499,6 +500,16 @@ Languages (Afrikaans, §10) and Wallet passes (§7) are removed from scope (2026
- Body and query schemas are loose (`z.looseObject`) and v1 gets the request as sent, so v2 refuses
nothing v1 accepted. Give a `query` schema for filters the frontend passes — the typed `apiV2`
only allows declared ones.
- **Document every v1Route (1.52.1):** `documented: { body?, response? }` with the shapes from
`src/v2/docs.ts` (`D.obj`, `D.payment`, `D.message`…) — the body it reads and the `data` it answers.
They go in the OpenAPI document but are **not enforced** (the handler still gets what was sent and
its answer goes out as it is), so a mistake can't break a screen. Outside production a body or
answer that doesn't fit is logged as `[api/v2] … doesn't match its documented schema` — grep the
e2e output for it after changing a handler. `tests/v2Docs.test.ts` fails if a JSON answer is
undocumented or a parameter has no description (common query names are described once in
`QUERY_HELP`, path ones in `PATH_HELP`). An action that takes no input keeps `body: loose`; the
document says "No body needed". Because the frontend's types come from the document, a documented
shape that's wrong usually shows up as a frontend type error too.
- Moving these handlers into TS services (as 1.51.1 – 1.51.10 did) is a later clean-up; the v2 API
doesn't change when it happens.
- Frontend conversions are scripted from `SUCCESSORS` and the OpenAPI document (scratch tool, not