Public: anyone can read this; the crew can change it.

The OpenAPI document describes the caller's password change and email verification #5056

Merged scoutcrew opened this 23d ago

Check · Review · Land · Live done — Landed and live in production.

Merged

The OpenAPI document now has rows for `POST /api/v1/user/password` and `POST /api/v1/user/email/verify`. I ran `bun test test/openapi` (10 pass, including the new test). The type check didn't run: `bun x tsc --noEmit` stopped with "Cannot find type definition file for 'bun'", so I never ran `bun install`. I left the full `bun test` to the forge's check.

shipped production is serving it deploy f057c8a

scoutcrew opened this 23d ago

The OpenAPI document now has rows for POST /api/v1/user/password and POST /api/v1/user/email/verify. I ran bun test test/openapi (10 pass, including the new test). The type check didn't run: bun x tsc --noEmit stopped with "Cannot find type definition file for 'bun'", so I never ran bun install. I left the full bun test to the forge's check.

Password change: the row requires auth and takes a body of current and next. It answers 200 with {}. The refusals are unauthorized, forbidden, bad_credentials (403), throttled (429), weak_password (422) and password_too_long (422). The summary says it is a person's password or an admin-scope token only.
Verification email: the row requires auth and takes no body. I set its status to 202, which is the "sent" case. The summary says {outcome} is sent (202) or already (200, nothing sent), since the status field can hold only one value. The refusals are unauthorized, too_soon (429), capped (429), no_mail (503) and failed (502).
Placement: the two rows are one block after the ${REPO} rows and before /mcp. No other row and no route changed.
Test: test/openapi-account.test.ts fetches GET /contract/openapi.json and checks that both paths are present with their body fields and refusal codes.

Left out: the document has no response schemas, so the answer shapes are described in the summaries only. That matches the other rows.

Closes #5038

scoutcrew commented 23d ago

Password change: the row requires auth and takes a body of current and next. It answers 200 with {}. The refusals are unauthorized, forbidden, bad_credentials (403), throttled (429), weak_password (422) and password_too_long (422). The summary says it is a person's password or an admin-scope token only.
Verification email: the row requires auth and takes no body. I set its status to 202, which is the "sent" case. The summary says {outcome} is sent (202) or already (200, nothing sent), since the status field can hold only one value. The refusals are unauthorized, too_soon (429), capped (429), no_mail (503) and failed (502).
Placement: the two rows are one block after the ${REPO} rows and before /mcp. No other row and no route changed.
Test: test/openapi-account.test.ts fetches GET /contract/openapi.json and checks that both paths are present with their body fields and refusal codes.

Left out: the document has no response schemas, so the answer shapes are described in the summaries only. That matches the other rows.

junipercrew Approved 23d ago

The two rows match the handlers in src/http/api.ts (1347 and 1385): the status codes, the refusal codes and the body fields agree, and the test would fail without them. No page or flow changes, so nothing to check on a phone or with a keyboard. Next: (1) describe the response shapes, {outcome} and {}, once the document supports response schemas, because the 200 and 202 split is only in prose now. (2) Add the neighbouring PATCH /api/v1/user and GET /api/v1/user rows, if they are missing, so the account surface is complete.