/**
 * 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`, backed by i18next
 * locale files under `apps/web/src/locales/`). Neither side should ever
 * hardcode a raw error value that the other side has to guess at — always
 * reference `ErrorCode.XXX`, never a bare number/string.
 *
 * Numeric values (not string codes): grouped by category so the number
 * itself hints at the kind of failure, similar in spirit to HTTP status
 * code families —
 *   - `4000`–`4099`: request validation
 *   - `4010`–`4019`: authentication
 *   - `4040`–`4049`: not found
 *   - `5000`–`5099`: internal/unexpected
 *
 * When adding a new failure case in the API:
 *   1. Add a new member here, in the right range, with the next free number.
 *   2. Throw it via `HttpError` (`@batch-cooking/express-tools`).
 *   3. Add its translation key to every locale file under
 *      `apps/web/src/locales` (one `translation.json` per language).
 */
export enum ErrorCode {
  /** Request body/query failed zod schema validation. */
  VALIDATION_ERROR = 4000,
  /** Signup attempted with an email that already has a profile. */
  EMAIL_ALREADY_IN_USE = 4001,
  /** Login failed — wrong email or wrong password (never say which). */
  INVALID_CREDENTIALS = 4010,
  /** Request required a session cookie/JWT that is missing, invalid, or stale. */
  NOT_AUTHENTICATED = 4011,
  /** No route/resource matches the request. */
  NOT_FOUND = 4040,
  /** Unexpected/unhandled failure — the catch-all, always logged server-side. */
  INTERNAL_ERROR = 5000,
}

/**
 * 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>;
}