[seaguent]

Ticket

Closes #4

What changed

• Added shared error codes, response schema, and types.
• Added ApiError and centralized JSON error handling for custom errors, 404s, and unexpected failures.
• Added typed JSON-body and query validation using Zod 4.
• Added runtime tests and request/client type assertions.

Why

Give API routes consistent error responses and reusable request validation, following TDD §3.2.

How to verify

Run from the repository root:

• bun run format:check:all
• bun run lint:all
• bun run typecheck:all
• bun run test:all
• bun run build:all

All passed locally, including 25 tests.

Screenshots

Not applicable; no UI changes.

Checklist

• CI passes locally (format, lint, typecheck, tests, build)
• TDD updated if behavior changed (removed for anything now built)
• No secrets or real member data in the diff

[VidurShah]

Great work Sean. This covers everything in the ticket, and the tests are thorough. The production-mode 500 test and the type tests against the real web client are especially nice.

A few small notes. None of them block merging:

• Unmapped HTTPException statuses become a 500. For example, a 413 from a body-limit middleware would come back as INTERNAL and get logged as a crash. Nothing throws those yet, so I pushed a comment documenting it (c2a2523) instead of changing behavior. If one starts showing up, add it to httpErrors.
• The API tests import from apps/web for the client type checks. That's the API depending on the web app, the reverse of normal, but it's type-only and catches real breakage, so it's fine for now.
• validate returns its 400 directly instead of throwing ApiError. The envelope is identical, so this is only a style point.

Good to merge.