feat(api): let users read and set their preferred language

[abdulrafey1]

What

Exposes the preferred-language setting over the API so clients can list the supported languages and set or clear a user's choice.

Changes

• feat(api): add GET /api/v1/languages, returning the supported languages and the platform default. Unauthenticated — the static-UI translation layer has to render the login, register and password-reset pages, which have no token yet
• feat(api): add PATCH /api/v1/user/me to set or clear the preference, and add language to the user schema
• chore(frontend): regenerate the API client types

How to Test

1. uv run pytest tests/api/v1/test_language.py tests/api/v1/test_user.py -q — 18 tests pass.
2. curl http://localhost:7727/api/v1/languages returns the three languages and "default": "en" with no token.
3. curl -X PATCH .../api/v1/user/me -d '{"language":"es"}' returns 200; GET /api/v1/user/me then reports "language": "es".
4. -d '{"language":"en-US"}' returns 422 and leaves the column untouched — matching is exact and case-sensitive.
5. -d '{"language":null}' clears the preference back to null.

Notes

No migration. GET /me returns the raw stored value, null included, so a client can tell "never chose" from "chose English"; resolving to the default is resolve_language's job.

GET /api/v1/languages is the only endpoint outside auth that requires no token. It serves a compile-time constant — the supported-language table and the platform default — so there is no user data, no database read, and nothing to enumerate. Gating it would force the frontend to carry the duplicate allowlist the endpoint exists to remove.

language is a required field on the request body, so an explicit null clears the preference while omitting the field is a 422 rather than a silent no-op.

Generated content does not consult this preference yet — that arrives with prompt injection in a later change.

This description was written with the assistance of an LLM (Claude).

[hamza-56]

The auth gate blocks the second consumer named in this module docstring: if the static-UI translation layer reads this endpoint, the login, register and password-reset pages cannot fetch the list because there is no token yet. The payload is a constant, non-sensitive allowlist, so either drop the gate or the frontend needs a duplicated client-side list, which is what this endpoint exists to avoid.

[abdulrafey1]

Gate dropped in 39d2c19. You were right that the docstring named a consumer the code blocked; the payload is a compile-time constant, so there was nothing to protect.

• routes.py — dependencies=[Depends(get_current_user)] removed, and the docstring now states why it is public rather than leaving the next reader to wonder.
• test_requires_authentication → test_does_not_require_authentication, asserting 200 with no token. Written first and watched fail with assert 401 == 200 before the gate came off.
• docs: document the preferred language setting #583 is stacked on this branch and documented the Bearer header; updated there in f0004b3. The /user/me examples keep theirs.
• PR body's test step and Notes updated.

One thing worth flagging since it is a first for this codebase: every other endpoint under /api/v1 outside auth is gated, by get_current_user or a permission. This is now the only deliberate exception, so it is called out explicitly in the module docstring and the PR notes rather than left to be discovered.

generated.ts is unchanged — the security removal does not alter the typed surface, so the test.frontend.api staleness check stays green.

[hamza-56]

This move contradicts the rule this same PR adds to architectural_patterns.md: models shared across domains stay in the root sparkth/schemas.py. User is shared, auth.py imports it for the register and login responses, so auth.py now imports the user package, which executes user/init.py and user/routes.py at import time. Any future import of auth.py from the user routes becomes a circular import. Either keep the model in sparkth/schemas.py or document why it is an exception.

[abdulrafey1]

Moved back to sparkth/schemas.py in 39d2c19. The contradiction was real: User is shared by the rule's own definition — auth.py returns it from register and login, user/routes.py from /user/me — so it belongs in the root alongside UserBase and Token.

• class User back in sparkth/schemas.py; auth.py and user/routes.py both import it from there.
• UserLanguageUpdate stays in user/schemas.py — nothing outside those routes sends it, so it is genuinely owned by the package. That is the split the rule describes.
• Verified the chain is gone: auth.UserSchema.__module__ is now sparkth.schemas, so importing auth no longer executes user/__init__.py and therefore user/routes.py.

On the cycle: confirmed latent rather than live — user/routes.py imports fastapi, sqlmodel, core.models.user, lib.auth, lib.db and lib.permissions, but not api.v1.auth, so nothing was broken today. It would have failed the first time someone imported in that direction, which is the worst kind of landmine.

Also amended the rule itself, since "shared" was doing a lot of unstated work: it now names User, says ownership is decided by who imports the model rather than which routes feel closest to it, and spells out the __init__.py → routes.py execution that makes the pull-into-a-package version circular. Same class of mistake should not be inviting next time.

Full suite green: 1726 passed, 3 skipped; ruff, format and mypy strict clean.