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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user