Nicolas
e9d94ff5f9
## Error handling
Requested: a centralized error-handling service on the API, custom error
codes shared across apps, and a client-side error service for i18n labels.
- packages/shared/src/errors/error-codes.ts — ErrorCode enum + ApiErrorResponse
contract. Single source of truth: neither side hardcodes a raw error string
the other has to guess at.
- apps/api: HttpError now carries an ErrorCode (not just a message).
ErrorHandlerService (new) centralizes every "how do we turn a thrown error
into an HTTP response" decision — app.ts's error middleware is now a thin
adapter calling into it. API messages reverted to English/dev-facing (they
were French from an earlier pass) since user-facing text is now generated
client-side from the code.
- apps/web: ApiClient (class, singleton instance) throws ApiError carrying
the code. ErrorMessageService (new) maps every ErrorCode to a localized
label, structured with a Locale type from the start (only "fr" exists, but
adding a language later is "add a locale to the map", not "hunt down every
hardcoded string"). LoginPage/SignupPage now display
errorMessageService.getLabel(err.code), never err.message directly.
- Tests strengthened to assert on `code`, not just HTTP status (Mocha +
Cucumber, new "the response error code should be" step). Cypress mocks
updated to the new {code, message} response shape.
## Code quality pass
Per explicit feedback: heavy JSDoc on every interface/type/class/function/
method/member touched in this PR, explicit public/private visibility on
every class member (ApiClient, ErrorMessageService, ErrorHandlerService,
HttpError), no HTML/logic mixing (styling extracted out of components
entirely, never inline).
ApiClient/ErrorMessageService were initially written as static-only classes;
switched to instance-based singletons (matching ErrorHandlerService's
existing pattern) after Biome's noStaticOnlyClass rule flagged the
static-only shape as an anti-pattern — same "class with visibility
modifiers" outcome, without fighting the linter.
## SCSS + theming
- apps/web/src/styles/_theme.scss — design tokens as CSS custom properties
on :root (colors, spacing, typography), not plain Sass variables — makes
them available at runtime, not just compile time, so a future theme
switch (e.g. dark mode) is "redefine these variables" rather than
rebuilding stylesheets.
- apps/web/src/styles/global.scss replaces the old single index.css:
reset + theme import only, loaded once from main.tsx.
- Per-page/component styles colocated (HomePage.tsx + HomePage.scss);
styles shared by multiple pages within one feature live in that feature's
folder (features/auth/auth-form.scss, used by both Login/SignupPage) —
not duplicated per page, not dumped in the global stylesheet either.
- Component-level .scss files intentionally don't `@use` the theme
partial: they only consume CSS custom properties (global at runtime via
global.scss), not Sass-level symbols, so importing it would do nothing —
documented inline rather than left as a silently-redundant import.
- vite.config.ts opts into Sass's modern compiler API to silence a
legacy-js-api deprecation warning on every build.
## specs/ updates
- New specs/error-handling.md — the ErrorCode/ApiErrorResponse contract,
both services, with a flow diagram.
- New specs/frontend-architecture.md — apps/web folder structure, routing/
auth-guard flow, SCSS/theming conventions.
- specs/batch-cooking-architecture.md links to both (original doc content
otherwise untouched — it's the user's own hand-authored source doc).
## Verification
Full lint/mocha/cucumber/build green. Manually re-verified the whole auth
flow in a real browser against native dev servers (not just the automated
suites): signup, the EMAIL_ALREADY_IN_USE → "Cet email est déjà utilisé"
translation end-to-end (confirmed the raw API response carries the English
dev message + code, and the UI shows the French label), wrong-password
INVALID_CREDENTIALS → its label, and confirmed the theme tokens actually
apply (computed button background-color matches --color-primary, card
max-width matches the token value) rather than trusting the build succeeding.
45 lines
2.1 KiB
TypeScript
45 lines
2.1 KiB
TypeScript
/**
|
|
* Enumeration of every business/domain error code the API can return.
|
|
*
|
|
* This is the single source of truth for error identification across the
|
|
* whole monorepo: `apps/api` throws errors carrying one of these codes,
|
|
* and `apps/web` maps each code to a localized, user-facing label (see
|
|
* `apps/web/src/services/error-message.service.ts`). Neither side should
|
|
* ever hardcode a raw error string that the other side has to guess at —
|
|
* the code is the contract.
|
|
*
|
|
* When adding a new failure case in the API:
|
|
* 1. Add a new member here.
|
|
* 2. Throw it via `HttpError` (apps/api/src/lib/http-error.ts).
|
|
* 3. Add its translation in `ErrorMessageService` (apps/web).
|
|
*/
|
|
export enum ErrorCode {
|
|
/** Request body/query failed zod schema validation. */
|
|
VALIDATION_ERROR = "VALIDATION_ERROR",
|
|
/** Signup attempted with an email that already has a profile. */
|
|
EMAIL_ALREADY_IN_USE = "EMAIL_ALREADY_IN_USE",
|
|
/** Login failed — wrong email or wrong password (never say which). */
|
|
INVALID_CREDENTIALS = "INVALID_CREDENTIALS",
|
|
/** Request required a session cookie/JWT that is missing, invalid, or stale. */
|
|
NOT_AUTHENTICATED = "NOT_AUTHENTICATED",
|
|
/** No route/resource matches the request. */
|
|
NOT_FOUND = "NOT_FOUND",
|
|
/** Unexpected/unhandled failure — the catch-all, always logged server-side. */
|
|
INTERNAL_ERROR = "INTERNAL_ERROR",
|
|
}
|
|
|
|
/**
|
|
* Shape of every JSON error body the API returns, whatever the failure.
|
|
* Kept intentionally small and stable: `code` is what clients should
|
|
* branch on, `message` is a human-readable (English, developer-facing)
|
|
* description useful for logs/debugging — never shown to end users as-is,
|
|
* since end-user-facing text is localized client-side from `code`.
|
|
*/
|
|
export interface ApiErrorResponse {
|
|
/** Machine-readable error identifier — see {@link ErrorCode}. */
|
|
code: ErrorCode;
|
|
/** Developer-facing description (English). Not localized, not for UI display. */
|
|
message: string;
|
|
/** Present only for VALIDATION_ERROR: per-field error messages from zod. */
|
|
details?: Record<string, string[] | undefined>;
|
|
}
|