create-nexst-monorepo 0.1.0

package/template/apps/api/src/auth/types/auth.types.ts

@@ -0,0 +1,27 @@
+import type { UserSession as LibUserSession } from "@thallesp/nestjs-better-auth";
+import type { FastifyRequest } from "fastify";
+import type { UserRole } from "#src/generated/prisma/client.js";
+
+export type RequestWithSession = FastifyRequest & {
+  session?: null | UserSession;
+  user?: null | UserSession["user"];
+};
+
+/**
+ * The authenticated user attached to the session: the Better Auth identity
+ * enriched with the app's {@link SessionProfile} fields.
+ */
+export type SessionUser = LibUserSession["user"] & SessionProfile;
+
+/** Session shape produced by Better Auth and enriched with the app's fields. */
+export type UserSession = Omit<LibUserSession, "user"> & {
+  user: SessionUser;
+};
+
+/**
+ * The app's fields, merged onto the Better Auth user by the `customSession`
+ * plugin. Mirrors `USER_SESSION_SELECT` in `auth.ts`; keep them in sync.
+ */
+type SessionProfile = {
+  role: UserRole[];
+};

package/template/apps/api/src/bootstrap/register-graphql-enums.ts

@@ -0,0 +1,12 @@
+import { registerEnumType } from "@nestjs/graphql";
+import { UserRole } from "#src/generated/prisma/client.js";
+
+/**
+ * Registers Prisma enums with the GraphQL type system.
+ *
+ * Must be called before GraphQL schema generation so every Prisma enum a DTO
+ * exposes is available as a GraphQL enum type.
+ */
+export function registerGraphqlEnums() {
+  registerEnumType(UserRole, { name: "UserRole" });
+}

package/template/apps/api/src/bootstrap/security.ts

@@ -0,0 +1,24 @@
+import type { FastifyCorsOptions } from "@fastify/cors";
+import helmet from "@fastify/helmet";
+import { ConfigService } from "@nestjs/config";
+import type { NestFastifyApplication } from "@nestjs/platform-fastify";
+import type { AppConfig } from "#src/config/app.config.js";
+
+/**
+ * Configures security middleware for the application.
+ *
+ * @param app - The NestJS application instance
+ */
+export async function addSecurity(app: NestFastifyApplication) {
+  const cfg = app.get(ConfigService<AppConfig, true>);
+  const securityConfig = cfg.get("security", { infer: true });
+
+  const corsOptions: FastifyCorsOptions = {
+    methods: securityConfig.allowedMethods,
+    origin: securityConfig.allowedOrigins,
+    ...securityConfig,
+  };
+
+  app.enableCors(corsOptions);
+  await app.register(helmet);
+}

package/template/apps/api/src/bootstrap/swagger.ts

@@ -0,0 +1,28 @@
+import { ConfigService } from "@nestjs/config";
+import type { NestFastifyApplication } from "@nestjs/platform-fastify";
+import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
+import type { AppConfig } from "#src/config/app.config.js";
+
+/**
+ * Configures Swagger/OpenAPI documentation for the application.
+ *
+ * @param app - The NestJS application instance
+ */
+export function addSwagger(app: NestFastifyApplication): void {
+  const cfg = app.get(ConfigService<AppConfig, true>);
+  const appCfg = cfg.get("app", { infer: true });
+  const swaggerCfg = cfg.get("swagger", { infer: true });
+
+  const builder = new DocumentBuilder()
+    .setTitle(appCfg.title)
+    .setDescription(appCfg.description)
+    .setVersion(appCfg.version);
+
+  for (const tag of swaggerCfg.tags) {
+    builder.addTag(tag);
+  }
+  const config = builder.build();
+
+  const documentFactory = () => SwaggerModule.createDocument(app, config);
+  SwaggerModule.setup(swaggerCfg.path, app, documentFactory);
+}

package/template/apps/api/src/config/app.config.spec.ts

@@ -0,0 +1,22 @@
+import { loadConfig } from "#src/config/app.config.js";
+
+describe("loadConfig", () => {
+  it("merges app.yaml defaults with the validated environment", () => {
+    const config = loadConfig();
+
+    expect(config.app.title).toBeTruthy();
+    expect(config.db.url).toBe(process.env.DATABASE_URL);
+    expect(config.security.allowedMethods).toContain("GET");
+  });
+
+  it("fails fast when a required variable is missing", () => {
+    const original = process.env.DATABASE_URL;
+    delete process.env.DATABASE_URL;
+
+    try {
+      expect(() => loadConfig()).toThrow(/DATABASE_URL/);
+    } finally {
+      process.env.DATABASE_URL = original;
+    }
+  });
+});

package/template/apps/api/src/config/app.config.ts

@@ -0,0 +1,122 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { load } from "js-yaml";
+import { z } from "zod";
+
+const YamlSchema = z.object({
+  app: z.object({
+    description: z.string().min(1),
+    title: z.string().min(1),
+    version: z.string().default("0.1.0"),
+  }),
+  // @if auth
+  mail: z.object({
+    from: z.string().min(1).default("Nexst <no-reply@example.com>"),
+    smtp: z
+      .object({
+        host: z.string().min(1).default("localhost"),
+        port: z.coerce.number().int().min(1).max(65_535).default(1025),
+      })
+      .prefault({}),
+  }),
+  // @endif
+  // @if r2
+  r2: z.object({
+    maxAttempts: z.coerce.number().int().positive().default(3),
+    presignExpiresInSeconds: z.coerce.number().int().positive().default(3600),
+    region: z.string().default("auto"),
+  }),
+  // @endif
+  security: z.object({
+    allowedHeaders: z.array(z.string()).default([]),
+    allowedMethods: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]).array(),
+    allowedOrigins: z.array(z.url()).default([]),
+    credentials: z.coerce.boolean().default(true),
+  }),
+  swagger: z.object({
+    path: z.string().default("api"),
+    tags: z.array(z.string()).default([]),
+  }),
+});
+
+const EnvironmentSchema = z.object({
+  // @if auth
+  BETTER_AUTH_SECRET: z
+    .string()
+    .min(32, "BETTER_AUTH_SECRET must be at least 32 characters (Better Auth recommendation)"),
+  BETTER_AUTH_URL: z.url("BETTER_AUTH_URL is required"),
+  // @endif
+  DATABASE_URL: z.url("DATABASE_URL is required"),
+  // @if auth
+  GOOGLE_CLIENT_ID: z.string().min(1).optional(),
+  GOOGLE_CLIENT_SECRET: z.string().min(1).optional(),
+  MAIL_SMTP_HOST: z.string().min(1).optional(),
+  // @endif
+  // @if r2
+  R2_ACCESS_KEY_ID: z.string().min(1, "R2_ACCESS_KEY_ID is required"),
+  R2_BUCKET: z.string().min(1, "R2_BUCKET is required"),
+  R2_ENDPOINT: z.url("R2_ENDPOINT is required"),
+  R2_PUBLIC_URL: z.url().optional(),
+  R2_SECRET_ACCESS_KEY: z.string().min(1, "R2_SECRET_ACCESS_KEY is required"),
+  // @endif
+  // @if worker
+  REDIS_HOST: z.string().default("redis"),
+  REDIS_PORT: z.coerce.number().min(1).max(65_535).default(6379),
+  REDIS_RETRY_LIMIT: z.coerce.number().min(1).default(5),
+  // @endif
+  // @if auth
+  RESEND_API_KEY: z.string().min(1).optional(),
+  // @endif
+});
+
+const configFile = path.resolve(import.meta.dirname, "resources", "app.yaml");
+
+export type AppConfig = ReturnType<typeof loadConfig>;
+
+/**
+ * Loads the static defaults from `resources/app.yaml` and the secrets and
+ * per-environment values from `process.env`, validating both. Fails fast on
+ * startup instead of at the first request that needs a missing value.
+ */
+export function loadConfig() {
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const yaml = YamlSchema.parse(load(readFileSync(configFile, "utf8")));
+  const env = EnvironmentSchema.parse(process.env);
+
+  return {
+    ...yaml,
+    // @if auth
+    auth: {
+      baseUrl: env.BETTER_AUTH_URL,
+      secret: env.BETTER_AUTH_SECRET,
+    },
+    // @endif
+    db: {
+      url: env.DATABASE_URL,
+    },
+    // @if auth
+    mail: {
+      from: yaml.mail.from,
+      resendApiKey: env.RESEND_API_KEY,
+      smtp: { ...yaml.mail.smtp, host: env.MAIL_SMTP_HOST ?? yaml.mail.smtp.host },
+    },
+    // @endif
+    // @if r2
+    r2: {
+      ...yaml.r2,
+      accessKeyId: env.R2_ACCESS_KEY_ID,
+      bucket: env.R2_BUCKET,
+      endpoint: env.R2_ENDPOINT,
+      publicUrl: env.R2_PUBLIC_URL,
+      secretAccessKey: env.R2_SECRET_ACCESS_KEY,
+    },
+    // @endif
+    // @if worker
+    redis: {
+      host: env.REDIS_HOST,
+      port: env.REDIS_PORT,
+      retryLimit: env.REDIS_RETRY_LIMIT,
+    },
+    // @endif
+  };
+}

package/template/apps/api/src/config/graphql-depth-limit.ts

@@ -0,0 +1,103 @@
+import { GraphQLError, Kind } from "graphql";
+import type {
+  ASTVisitor,
+  DefinitionNode,
+  FragmentDefinitionNode,
+  OperationDefinitionNode,
+  SelectionNode,
+  ValidationContext,
+  ValidationRule,
+} from "graphql";
+
+/**
+ * Ported from `graphql-depth-limit` (github.com/stems/graphql-depth-limit):
+ * that package's `require("graphql")` can't be satisfied under Bun, whose
+ * `graphql` package.json resolves to an ESM build Bun refuses to require()
+ * synchronously. Node never hit this because it has no "bun" export
+ * condition active and falls through to the CJS build instead.
+ */
+export function depthLimit(maxDepth: number): ValidationRule {
+  return (context: ValidationContext): ASTVisitor => {
+    const { definitions } = context.getDocument();
+    const fragments = getFragments(definitions);
+    const operations = getOperations(definitions);
+
+    for (const [name, operation] of operations) {
+      determineDepth(operation, fragments, 0, maxDepth, context, name);
+    }
+
+    // The check above already ran eagerly against the whole document, so
+    // there's nothing left for graphql-js's AST walk to visit.
+    return {};
+  };
+}
+
+function determineDepth(
+  node: FragmentDefinitionNode | OperationDefinitionNode | SelectionNode,
+  fragments: Map<string, FragmentDefinitionNode>,
+  depthSoFar: number,
+  maxDepth: number,
+  context: ValidationContext,
+  operationName: string,
+): number {
+  if (depthSoFar > maxDepth) {
+    context.reportError(
+      new GraphQLError(`'${operationName}' exceeds maximum operation depth of ${maxDepth}`, {
+        nodes: [node],
+      }),
+    );
+    return 0;
+  }
+
+  switch (node.kind) {
+    case Kind.FIELD: {
+      if (node.name.value.startsWith("__") || !node.selectionSet) {
+        return 0;
+      }
+      return (
+        1 +
+        Math.max(
+          ...node.selectionSet.selections.map((selection) =>
+            determineDepth(selection, fragments, depthSoFar + 1, maxDepth, context, operationName),
+          ),
+        )
+      );
+    }
+    case Kind.FRAGMENT_DEFINITION:
+    case Kind.INLINE_FRAGMENT:
+    case Kind.OPERATION_DEFINITION:
+      return Math.max(
+        ...node.selectionSet.selections.map((selection) =>
+          determineDepth(selection, fragments, depthSoFar, maxDepth, context, operationName),
+        ),
+      );
+    case Kind.FRAGMENT_SPREAD: {
+      const fragment = fragments.get(node.name.value);
+      return fragment
+        ? determineDepth(fragment, fragments, depthSoFar, maxDepth, context, operationName)
+        : 0;
+    }
+    default:
+      throw new Error("depth limit cannot handle this node kind");
+  }
+}
+
+function getFragments(definitions: readonly DefinitionNode[]) {
+  const fragments = new Map<string, FragmentDefinitionNode>();
+  for (const definition of definitions) {
+    if (definition.kind === Kind.FRAGMENT_DEFINITION) {
+      fragments.set(definition.name.value, definition);
+    }
+  }
+  return fragments;
+}
+
+function getOperations(definitions: readonly DefinitionNode[]) {
+  const operations = new Map<string, OperationDefinitionNode>();
+  for (const definition of definitions) {
+    if (definition.kind === Kind.OPERATION_DEFINITION) {
+      operations.set(definition.name?.value ?? "", definition);
+    }
+  }
+  return operations;
+}

package/template/apps/api/src/config/graphql.config.ts

@@ -0,0 +1,77 @@
+import { InMemoryLRUCache } from "@apollo/utils.keyvaluecache";
+import { ApolloDriver } from "@nestjs/apollo";
+import type { ApolloDriverConfig } from "@nestjs/apollo";
+import { Logger } from "@nestjs/common";
+import type { GraphQLFormattedError } from "graphql";
+import { depthLimit } from "#src/config/graphql-depth-limit.js";
+import type { AppExceptionResponse } from "#src/errors/app.exception.js";
+import { ErrorCode } from "#src/errors/error-code.enum.js";
+
+const logger = new Logger("GraphQL");
+
+/**
+ * Reads back the structured payload `@nestjs/apollo` already attached.
+ *
+ * `ApolloBaseDriver.createTransformHttpErrorFn` unwraps any resolver-thrown
+ * `HttpException` and republishes its `getResponse()` body under
+ * `extensions.originalError` before this `formatError` runs — since
+ * `AppException#getResponse()` already *is* `{ code, params, ... }`, this is
+ * the single source of truth for both `message` and `extensions` below.
+ *
+ * @param formattedError - The error Apollo is about to send to the client
+ * @returns The `AppException` payload, or `undefined` for anything else
+ */
+function readAppExceptionPayload(
+  formattedError: GraphQLFormattedError,
+): AppExceptionResponse | undefined {
+  const original = formattedError.extensions?.originalError;
+  return original && typeof original === "object" && "code" in original
+    ? (original as AppExceptionResponse)
+    : undefined;
+}
+
+export const graphqlConfig: ApolloDriverConfig = {
+  autoSchemaFile: true,
+  csrfPrevention: true,
+  debug: process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test",
+  driver: ApolloDriver,
+  formatError: (formattedError: GraphQLFormattedError, error: unknown): GraphQLFormattedError => {
+    const appPayload = readAppExceptionPayload(formattedError);
+    if (appPayload) {
+      return {
+        extensions: {
+          code: appPayload.code,
+          ...(appPayload.params ? { params: appPayload.params } : {}),
+          statusCode: appPayload.statusCode,
+        },
+        locations: formattedError.locations,
+        message: appPayload.code,
+        path: formattedError.path,
+      };
+    }
+
+    const originalError = error instanceof Error ? error : null;
+    const message = originalError?.message ?? "";
+    const isPrismaError = message.includes("Invalid `prisma") || message.includes("Argument `");
+
+    if (isPrismaError) {
+      logger.error("Prisma error:", originalError?.message);
+
+      return {
+        extensions: { code: ErrorCode.INTERNAL_SERVER_ERROR },
+        message: ErrorCode.INTERNAL_SERVER_ERROR,
+      };
+    }
+
+    return formattedError;
+  },
+  graphiql: process.env.NODE_ENV === "development",
+  inheritResolversFromInterfaces: true,
+  introspection: process.env.NODE_ENV !== "production",
+  persistedQueries: {
+    cache: new InMemoryLRUCache(),
+    ttl: 300,
+  },
+  sortSchema: true,
+  validationRules: [depthLimit(7)],
+};

package/template/apps/api/src/config/resources/app.yaml

@@ -0,0 +1,29 @@
+app:
+  title: Nexst API
+  description: The Nexst backend
+  version: "0.1.0"
+
+swagger:
+  tags: [health]
+  path: api
+# @if r2
+
+r2:
+  maxAttempts: 5
+  presignExpiresInSeconds: 3600
+  region: auto
+# @endif
+# @if auth
+
+mail:
+  from: Nexst <no-reply@example.com>
+  smtp:
+    host: localhost
+    port: 1025
+# @endif
+
+security:
+  allowedHeaders: [Content-Type, Authorization, Apollo-Require-Preflight]
+  allowedMethods: [GET, POST, PUT, PATCH, DELETE, OPTIONS]
+  allowedOrigins: [http://localhost:3000, https://example.com]
+  credentials: true

package/template/apps/api/src/errors/app-parse-uuid.pipe.ts

@@ -0,0 +1,27 @@
+import { HttpStatus, ParseUUIDPipe } from "@nestjs/common";
+import type { ParseUUIDPipeOptions } from "@nestjs/common";
+import { AppException } from "#src/errors/app.exception.js";
+import { ErrorCode } from "#src/errors/error-code.enum.js";
+
+/**
+ * Drop-in replacement for `ParseUUIDPipe` that fails with an
+ * {@link AppException} instead of the built-in pipe's hardcoded
+ * "Validation failed (uuid is expected)" text.
+ *
+ * `ParseUUIDPipe` is instantiated directly at resolver/controller
+ * parameters across the API and is not covered by the global
+ * `ValidationPipe`'s `exceptionFactory` — this wrapper closes that gap with
+ * the same `VALIDATION_FAILED` code and violation shape.
+ *
+ * @param options - The same options `ParseUUIDPipe` accepts
+ * @returns A `ParseUUIDPipe` configured to throw codes-only on failure
+ */
+export function AppParseUUIDPipe(options?: ParseUUIDPipeOptions): ParseUUIDPipe {
+  return new ParseUUIDPipe({
+    ...options,
+    exceptionFactory: () =>
+      new AppException(ErrorCode.VALIDATION_FAILED, HttpStatus.BAD_REQUEST, {
+        violations: [{ constraints: ["isUuid"], field: "id" }],
+      }),
+  });
+}

package/template/apps/api/src/errors/app.exception.ts

@@ -0,0 +1,47 @@
+import { HttpException } from "@nestjs/common";
+import type { HttpStatus } from "@nestjs/common";
+import type { ErrorCode } from "#src/errors/error-code.enum.js";
+
+/** The exact shape `AppException#getResponse()` returns. */
+export interface AppExceptionResponse {
+  code: ErrorCode;
+  message: ErrorCode;
+  params?: ErrorParams;
+  statusCode: HttpStatus;
+}
+
+/**
+ * Structured, JSON-serializable interpolation data for a code. Left as
+ * `unknown` values rather than restricted to primitives, since some codes
+ * (e.g. `VALIDATION_FAILED`) carry a list of `{ field, constraints }`
+ * objects rather than a flat key-value pair.
+ */
+export type ErrorParams = Record<string, unknown>;
+
+/**
+ * The one exception type application code throws for any expected,
+ * user-facing failure — a missing record, a name conflict, an unauthorized
+ * action. It carries a machine-readable `code` and optional structured
+ * `params` for interpolation instead of an English sentence; the frontend
+ * owns turning `code` + `params` into copy.
+ *
+ * The HTTP status is still chosen by the call site, exactly as with
+ * `NotFoundException`/`ConflictException`/etc. — this class only removes
+ * the free-text message, it does not change status semantics.
+ *
+ * `message` is set to the code string itself, not left for `HttpException`
+ * to derive a title from the class name: every consumer that reads
+ * `.message` (logs, `@nestjs/apollo`'s resolver-error unwrapping) should see
+ * the code, never prose.
+ */
+export class AppException extends HttpException {
+  readonly code: ErrorCode;
+  readonly params?: ErrorParams;
+
+  constructor(code: ErrorCode, status: HttpStatus, params?: ErrorParams) {
+    const response: AppExceptionResponse = { code, message: code, params, statusCode: status };
+    super(response, status);
+    this.code = code;
+    this.params = params;
+  }
+}

package/template/apps/api/src/errors/error-code.enum.ts

@@ -0,0 +1,54 @@
+/**
+ * Every machine-readable error code the API can return, over REST or GraphQL.
+ *
+ * Flat, no per-module namespacing: a duplicate failure thrown from two
+ * modules (e.g. "user not found") collapses onto one member here. Every
+ * call site throws {@link AppException} with one of these codes instead of
+ * a free-text message; grows as new failure cases are added.
+ */
+export enum ErrorCode {
+  /** Generic fallback for a 400 that carries no more specific code. */
+  BAD_REQUEST = "BAD_REQUEST",
+
+  /** Generic fallback for a 409 that carries no more specific code. */
+  CONFLICT = "CONFLICT",
+
+  // @if auth
+  /** The user's email address is not verified. */
+  EMAIL_NOT_VERIFIED = "EMAIL_NOT_VERIFIED",
+  // @endif
+
+  /** Generic fallback for a 403 that carries no more specific code. */
+  FORBIDDEN = "FORBIDDEN",
+
+  // @if auth
+  /** The route requires a role the user does not have. */
+  INSUFFICIENT_ROLE = "INSUFFICIENT_ROLE",
+  // @endif
+
+  /** Generic fallback for a 500 that carries no more specific code. */
+  INTERNAL_SERVER_ERROR = "INTERNAL_SERVER_ERROR",
+
+  /** Generic fallback for a 404 that carries no more specific code. */
+  NOT_FOUND = "NOT_FOUND",
+
+  // @if auth
+  /** The request's underlying HTTP context could not be resolved. */
+  REQUEST_CONTEXT_MISSING = "REQUEST_CONTEXT_MISSING",
+  // @endif
+
+  /** Generic fallback for a 503 that carries no more specific code. */
+  SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
+
+  /** Generic fallback for a 429: the caller hit a rate limit and should retry. */
+  TOO_MANY_REQUESTS = "TOO_MANY_REQUESTS",
+
+  /** Generic fallback for a 401 that carries no more specific code. */
+  UNAUTHORIZED = "UNAUTHORIZED",
+
+  /** Generic fallback for a 422 that carries no more specific code. */
+  UNPROCESSABLE_ENTITY = "UNPROCESSABLE_ENTITY",
+
+  /** One or more DTO fields failed class-validator validation. */
+  VALIDATION_FAILED = "VALIDATION_FAILED",
+}

package/template/apps/api/src/errors/http-status-fallback-code.util.ts

@@ -0,0 +1,27 @@
+import { HttpStatus } from "@nestjs/common";
+import { ErrorCode } from "#src/errors/error-code.enum.js";
+
+const STATUS_FALLBACK_CODE: Partial<Record<HttpStatus, ErrorCode>> = {
+  [HttpStatus.BAD_REQUEST]: ErrorCode.BAD_REQUEST,
+  [HttpStatus.CONFLICT]: ErrorCode.CONFLICT,
+  [HttpStatus.FORBIDDEN]: ErrorCode.FORBIDDEN,
+  [HttpStatus.NOT_FOUND]: ErrorCode.NOT_FOUND,
+  [HttpStatus.SERVICE_UNAVAILABLE]: ErrorCode.SERVICE_UNAVAILABLE,
+  [HttpStatus.TOO_MANY_REQUESTS]: ErrorCode.TOO_MANY_REQUESTS,
+  [HttpStatus.UNAUTHORIZED]: ErrorCode.UNAUTHORIZED,
+  [HttpStatus.UNPROCESSABLE_ENTITY]: ErrorCode.UNPROCESSABLE_ENTITY,
+};
+
+/**
+ * Maps an HTTP status to a generic {@link ErrorCode} fallback.
+ *
+ * Used when an exception reaching a filter is not an {@link AppException} —
+ * a third-party exception, or a call site not yet migrated — so the response
+ * never falls back to free text even outside this rewrite's own call sites.
+ *
+ * @param status - The HTTP status the response will carry
+ * @returns The generic code for that status, or `INTERNAL_SERVER_ERROR`
+ */
+export function fallbackCodeForStatus(status: HttpStatus): ErrorCode {
+  return STATUS_FALLBACK_CODE[status] ?? ErrorCode.INTERNAL_SERVER_ERROR;
+}

package/template/apps/api/src/errors/validation-exception.factory.ts

@@ -0,0 +1,43 @@
+import { HttpStatus } from "@nestjs/common";
+import type { ValidationError } from "@nestjs/common";
+import { AppException } from "#src/errors/app.exception.js";
+import { ErrorCode } from "#src/errors/error-code.enum.js";
+
+interface FieldViolation {
+  constraints: string[];
+  field: string;
+}
+
+/**
+ * `ValidationPipe`'s `exceptionFactory`: turns `class-validator`'s
+ * `ValidationError[]` into a single {@link AppException}.
+ *
+ * `ValidationError.constraints` is already keyed by the constraint's own
+ * machine-readable name (`isEmail`, `minLength`, …) — only its value is the
+ * English default sentence, which this factory discards.
+ *
+ * @param errors - The validation errors `class-validator` produced
+ * @returns An `AppException` carrying every violated field and rule
+ */
+export function validationExceptionFactory(errors: ValidationError[]): AppException {
+  return new AppException(ErrorCode.VALIDATION_FAILED, HttpStatus.BAD_REQUEST, {
+    violations: flatten(errors),
+  });
+}
+
+/**
+ * Flattens `class-validator`'s nested `ValidationError[]` (used by
+ * `@ValidateNested()` DTOs) into dotted field paths.
+ *
+ * @param errors - The validation errors to flatten
+ * @param prefix - The dotted field path accumulated so far
+ * @returns One violation per invalid field, however deeply nested
+ */
+function flatten(errors: ValidationError[], prefix = ""): FieldViolation[] {
+  return errors.flatMap((error) => {
+    const field = prefix ? `${prefix}.${error.property}` : error.property;
+    const own = error.constraints ? [{ constraints: Object.keys(error.constraints), field }] : [];
+    const nested = error.children?.length ? flatten(error.children, field) : [];
+    return [...own, ...nested];
+  });
+}