create-zhx-monorepo 0.2.2 → 2.0.0

package/templates/monorepo-starter/server/scripts/admin-bootstrap.ts

@@ -0,0 +1,61 @@
+import "dotenv/config";
+import { PrismaClient } from "../prisma/generated/client";
+import { PrismaPg } from "@prisma/adapter-pg";
+import argon2 from "argon2";
+
+const connectionString = process.env.DB_URI;
+const adapter = new PrismaPg({ connectionString });
+const prisma = new PrismaClient({ adapter });
+
+async function adminBootstrap() {
+  const { ADMIN_EMAIL, ADMIN_PASSWORD, ADMIN_NAME } = process.env;
+
+  if (process.env.NODE_ENV === "production") {
+    console.log("⚠️  Running in PRODUCTION");
+  }
+
+  if (!ADMIN_EMAIL || !ADMIN_PASSWORD || !ADMIN_NAME) {
+    throw new Error("Missing ADMIN env variables");
+  }
+
+  console.log("🚀 Checking for existing admin...");
+
+  const existingAdmin = await prisma.user.findFirst({
+    where: { role: "admin" },
+  });
+
+  if (existingAdmin) {
+    console.log("existingAdmin", existingAdmin.id);
+
+    throw new Error("❌ Admin already exists. Aborting.");
+  }
+
+  const email = ADMIN_EMAIL.toLowerCase();
+  const hashedPassword = await argon2.hash(ADMIN_PASSWORD);
+
+  const [firstName, ...rest] = ADMIN_NAME.trim().split(" ");
+  const lastName = rest.join(" ") || null;
+
+  const admin = await prisma.user.create({
+    data: {
+      email,
+      password: hashedPassword,
+      firstName: firstName!,
+      lastName,
+      displayName: ADMIN_NAME?.trim(),
+      isEmailVerified: true,
+      role: "admin",
+      status: "active",
+    },
+  });
+
+  console.log("🎉 First admin created");
+  console.log({ id: admin.id, email: admin.email });
+}
+
+adminBootstrap()
+  .catch((e) => {
+    console.error(e.message);
+    process.exit(1);
+  })
+  .finally(() => prisma.$disconnect());

package/templates/monorepo-starter/server/scripts/gen-module.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# Exit if no arguments were provided
+if [ "$#" -eq 0 ]; then
+  echo "❌ Please provide at least one module name"
+  echo "👉 Example: ./generate.sh payment booking"
+  exit 1
+fi
+
+# Loop through all provided arguments
+for NAME in "$@"; do
+  echo "🚀 Generating NestJS module: $NAME"
+
+  nest g module "$NAME"
+  nest g service "$NAME"
+  nest g controller "$NAME"
+
+  echo "✅ $NAME generated successfully"
+  echo "-----------------------------"
+done

package/templates/monorepo-starter/server/scripts/gen-soft-delete.ts

@@ -0,0 +1,52 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const SCHEMA_PATH = path.resolve(__dirname, "../prisma/schema.prisma");
+const OUTPUT_PATH = path.resolve(
+  __dirname,
+  "../src/modules/prisma/soft-delete.models.ts"
+);
+
+const schema = fs.readFileSync(SCHEMA_PATH, "utf8");
+
+// Normalize line endings for consistency
+const normalizedSchema = schema.replace(/\r\n/g, "\n");
+
+// Match full model blocks (multiline-safe)
+const modelRegex = /model\s+(\w+)\s*\{([\s\S]*?)^\s*\}/gm;
+
+const softDeleteModels: string[] = [];
+let totalModels = 0;
+
+let match: RegExpExecArray | null;
+while ((match = modelRegex.exec(normalizedSchema))) {
+  const modelName = match[1] as string;
+  const body = match[2] as string;
+  totalModels++;
+
+  const hasDeletedAt = /deletedAt\s+DateTime\?/i.test(body);
+
+  if (hasDeletedAt) {
+    softDeleteModels.push(modelName);
+  }
+}
+
+// Generate the output file
+const output = `// AUTO-GENERATED FILE — DO NOT EDIT
+// Generated from schema.prisma
+
+export const SoftDeleteModels = new Set<string>([
+${softDeleteModels.map((m) => `  "${m}"`).join(",\n")}
+]);
+`;
+
+fs.writeFileSync(OUTPUT_PATH, output, "utf8");
+
+console.log(
+  `✅ Generated soft delete models (${softDeleteModels.length}/${totalModels} models):`
+);
+console.log(softDeleteModels.join("  -  "));

package/templates/monorepo-starter/server/src/app.module.ts

@@ -1,46 +1,53 @@
 import { Module } from "@nestjs/common";
 import { ConfigModule } from "@nestjs/config";
-import { ScheduleModule } from "@nestjs/schedule";
-import { APP_GUARD, Reflector } from "@nestjs/core";
-import { EnvModule } from "@modules/env/env.module";
-import { validateEnv } from "@schemas/env.schema";
-import { AuthGuard } from "@guards/auth.guard";
-import { AuthModule } from "@modules/auth/auth.module";
-import { TokenModule } from "@modules/token/token.module";
-import { PublicModule } from "@modules/public/public.module";
-import { TokenService } from "@modules/token/token.service";
-import { PrismaModule } from "@modules/prisma/prisma.module";
-import { LoggerModule } from "@modules/logger/logger.module";
-import { SchedulerModule } from "@modules/scheduler/scheduler.module";
-import { NotificationModule } from "@modules/notification/notification.module";
-import { TemplateModule } from "@modules/template/template.module";
-import { AllExceptionsFilter } from "@filters/exceptions.filter";
-import { ResponseInterceptor } from "@/lib/interceptors/response.interceptor";
+import { APP_GUARD, APP_PIPE } from "@nestjs/core";
+import { ZodValidationPipe } from "nestjs-zod";
+
+import { EnvModule } from "@/modules/env/env.module";
+import { validateEnv } from "@/schemas/env.schema";
+import { AuthGuard } from "@/guards/auth.guard";
+import { AuthModule } from "@/modules/auth/auth.module";
+import { TokenModule } from "@/modules/token/token.module";
+import { PublicModule } from "@/modules/public/public.module";
+import { PrismaModule } from "@/modules/prisma/prisma.module";
+import { LoggerModule } from "@/modules/logger/logger.module";
+import { SchedulerModule } from "@/modules/scheduler/scheduler.module";
+import { NotificationModule } from "@/modules/notification/notification.module";
+import { AllExceptionsFilter } from "@/filters/exceptions.filter";
+import { ResponseInterceptor } from "@/interceptors/response.interceptor";
+import { AdminModule } from "@/modules/admin/admin.module";
+import { CacheModule } from "@/modules/cache/cache.module";
+import { UserModule } from "@/modules/user/user.module";
+import { MediaModule } from "@/modules/media/media.module";
 
 @Module({
   imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+      validate: validateEnv,
+    }),
+    EnvModule,
+    CacheModule,
+    SchedulerModule,
     PublicModule,
     PrismaModule,
     LoggerModule,
-    EnvModule,
+    NotificationModule,
     AuthModule,
     TokenModule,
-    TemplateModule,
-    NotificationModule,
-    SchedulerModule,
-    ScheduleModule.forRoot(),
-    ConfigModule.forRoot({
-      isGlobal: true,
-      validate: validateEnv,
-    }),
+    UserModule,
+    AdminModule,
+    MediaModule,
   ],
 
   providers: [
     {
       provide: APP_GUARD,
-      useFactory: (tokenService, reflector) =>
-        new AuthGuard(tokenService, reflector),
-      inject: [TokenService, Reflector],
+      useClass: AuthGuard,
+    },
+    {
+      provide: APP_PIPE,
+      useClass: ZodValidationPipe,
     },
     AllExceptionsFilter,
     ResponseInterceptor,

package/templates/monorepo-starter/server/src/lib/constants/index.ts

@@ -0,0 +1,59 @@
+/**
+ * IMPORTANT = user must see this even if it costs money (SMS / WhatsApp)
+ * Do NOT mark notifications important unless missing it causes
+ * loss of access, money, or travel.
+ */
+
+export const NOTIFICATION_POLICY_MAP: Record<
+  NotificationPurpose,
+  { priority: NotificationPriority; push: boolean }
+> = {
+  // AUTH
+  authSignUp: {
+    priority: "normal",
+    push: false,
+  },
+  authSignIn: {
+    priority: "normal",
+    push: false,
+  },
+
+  authSetPassword: {
+    priority: "important",
+    push: false,
+  },
+  authResetPassword: {
+    priority: "important",
+    push: false,
+  },
+  authVerifyIdentifier: {
+    priority: "important",
+    push: false,
+  },
+  authUpdateIdentifier: {
+    priority: "important",
+    push: false,
+  },
+  authUpdateMfa: {
+    priority: "important",
+    push: false,
+  },
+  authDisableMfa: {
+    priority: "important",
+    push: false,
+  },
+  authVerifyMfa: {
+    priority: "important",
+    push: false,
+  },
+
+  // ACCOUNT
+  accountSuspended: {
+    priority: "important",
+    push: true,
+  },
+  accountReactivated: {
+    priority: "important",
+    push: true,
+  },
+};

package/templates/monorepo-starter/server/src/lib/decorators/boolean-query.decorator.ts

@@ -0,0 +1,18 @@
+import { createParamDecorator, type ExecutionContext } from "@nestjs/common";
+
+export const BooleanQuery = createParamDecorator(
+  (key: string, ctx: ExecutionContext): boolean => {
+    const request = ctx.switchToHttp().getRequest();
+    const value = request.query[key];
+
+    if (value === undefined) return false;
+
+    if (typeof value === "boolean") return value;
+
+    if (typeof value === "string") {
+      return value.toLowerCase() === "true";
+    }
+
+    return false;
+  },
+);

package/templates/monorepo-starter/server/src/lib/decorators/logger.decorator.ts

@@ -1,5 +1,5 @@
 import { Inject } from "@nestjs/common";
-import { LoggerService } from "@modules/logger/logger.service";
+import { LoggerService } from "@/modules/logger/logger.service";
 
 export function InjectLogger(context?: string): PropertyDecorator {
   return (target: object, propertyKey: string | symbol) => {

package/templates/monorepo-starter/server/src/lib/decorators/oauth.decorator.ts

@@ -0,0 +1,7 @@
+import { applyDecorators, UseGuards } from "@nestjs/common";
+import { OAuthGuard, type OAuthProvider } from "@/guards/oauth.guard";
+import { Public } from "@/decorators/public.decorator";
+
+export function UseOAuthGuard(provider: OAuthProvider) {
+  return applyDecorators(Public(), UseGuards(OAuthGuard(provider)));
+}

package/templates/monorepo-starter/server/src/lib/decorators/user.decorator.ts

@@ -0,0 +1,10 @@
+import { createParamDecorator, type ExecutionContext } from "@nestjs/common";
+
+export const User = createParamDecorator(
+  (data: keyof Express.User | undefined, ctx: ExecutionContext) => {
+    const req = ctx.switchToHttp().getRequest();
+    const user = req.user;
+
+    return data ? user?.[data] : user;
+  },
+);

package/templates/monorepo-starter/server/src/lib/filters/exceptions.filter.ts

@@ -1,4 +1,5 @@
-import { LoggerService } from "@modules/logger/logger.service";
+import { ZodError } from "zod";
+import { ZodValidationException } from "nestjs-zod";
 import type { Request, Response } from "express";
 import {
   Catch,
@@ -7,7 +8,10 @@ import {
   type ExceptionFilter,
   type ArgumentsHost,
 } from "@nestjs/common";
-import { InjectLogger } from "@decorators/logger.decorator";
+import { Prisma } from "@generated/prisma";
+
+import { InjectLogger } from "@/decorators/logger.decorator";
+import { LoggerService } from "@/modules/logger/logger.service";
 
 @Catch()
 export class AllExceptionsFilter implements ExceptionFilter {
@@ -19,44 +23,185 @@ export class AllExceptionsFilter implements ExceptionFilter {
     const req = ctx.getRequest<Request>();
     const res = ctx.getResponse<Response>();
 
-    const status =
-      exception instanceof HttpException
-        ? exception.getStatus()
-        : HttpStatus.INTERNAL_SERVER_ERROR;
-
-    let message: any = "Internal server error";
+    let status = HttpStatus.INTERNAL_SERVER_ERROR;
+    let message = "Internal server error";
+    let action: string | undefined = undefined;
+    let errorCode: string | undefined = undefined;
+    let meta: Record<string, any> | undefined = undefined;
 
+    // ---------- NestJS HttpException ----------
     if (exception instanceof HttpException) {
-      const res = exception.getResponse();
-
-      if (
-        res &&
-        typeof res === "object" &&
-        "message" in res &&
-        Array.isArray((res as any).message)
-      ) {
-        message = (res as any).message;
-      } else if (typeof res === "string") {
-        message = res;
-      } else if (typeof exception.message === "string") {
+      status = exception.getStatus();
+      const response = exception.getResponse();
+
+      if (typeof response === "object" && response !== null) {
+        const resObj = response as any;
+
+        if (Array.isArray(resObj.message)) {
+          message = resObj.message.join(", ");
+        } else if (typeof resObj.message === "string") {
+          message = resObj.message;
+        } else {
+          message = "Request failed";
+        }
+
+        action = resObj.action;
+        meta = resObj.meta;
+        errorCode = resObj.errorCode;
+      } else {
         message = exception.message;
       }
     }
-    // if (response.headersSent) return;
 
-    this.logger.error(`❌ Exception caught`, {
+    // -------- Prisma ClientKnownRequestError --------
+    else if (exception instanceof Prisma.PrismaClientKnownRequestError) {
+      switch (exception.code) {
+        case "P2002": {
+          status = 409;
+          const target = Array.isArray(exception.meta?.target)
+            ? exception.meta?.target.join(", ")
+            : String(exception.meta?.target ?? "");
+          message = `Duplicate entry${target ? `: ${target}` : ""}`;
+          break;
+        }
+        case "P2025": {
+          status = 404;
+
+          const model =
+            typeof exception.meta?.modelName === "string"
+              ? exception.meta.modelName
+              : "Resource";
+
+          message = `${model} not found`;
+          break;
+        }
+        case "P2003":
+          status = 400;
+          message = "Foreign key constraint failed";
+          break;
+        case "P2016":
+          status = 400;
+          message = "Query interpretation error";
+          break;
+        case "P2011":
+          status = 400;
+          message = "Null constraint violation";
+          break;
+        case "P2012":
+          status = 400;
+          message = "Missing required value";
+          break;
+        case "P2014":
+          status = 400;
+          message = "Invalid relation operation";
+          break;
+        case "P2001":
+          status = 404;
+          message = "Record does not exist";
+          break;
+        default:
+          status = 400;
+          message = "Database operation failed";
+      }
+    }
+
+    // -------- Prisma Validation Error --------
+    else if (exception instanceof Prisma.PrismaClientValidationError) {
+      status = 400;
+      const errorMessage = exception.message;
+
+      if (errorMessage.includes("Unknown argument")) {
+        const match = errorMessage.match(/Unknown argument `(\w+)`/);
+        if (match) {
+          message = `Invalid field: ${match[1]} is not a valid field for this operation`;
+        } else {
+          message = "Invalid data provided for database operation";
+        }
+      } else if (errorMessage.includes("Invalid value")) {
+        message = "Invalid data format provided";
+      } else {
+        message = "Database validation failed";
+      }
+    }
+
+    // -------- Prisma Unknown Request Error --------
+    else if (exception instanceof Prisma.PrismaClientUnknownRequestError) {
+      status = 400;
+      message = "Database request error";
+
+      if (process.env.NODE_ENV === "development") {
+        meta = { detail: exception.message };
+      }
+    }
+
+    // -------- Prisma Initialization Error --------
+    else if (exception instanceof Prisma.PrismaClientInitializationError) {
+      status = 500;
+      message = "Database connection failed";
+
+      if (process.env.NODE_ENV === "development") {
+        meta = { detail: exception.message };
+      }
+    }
+
+    // -------- Prisma Rust Panic Error --------
+    else if (exception instanceof Prisma.PrismaClientRustPanicError) {
+      status = 500;
+      message = "Database engine error";
+
+      if (process.env.NODE_ENV === "development") {
+        meta = { detail: exception.message };
+      }
+    }
+
+    // ---------- Zod validation errors ----------
+    else if (
+      exception instanceof ZodValidationException ||
+      exception instanceof ZodError
+    ) {
+      status = HttpStatus.BAD_REQUEST;
+
+      const zodError = (
+        exception instanceof ZodValidationException
+          ? exception.getZodError()
+          : exception
+      ) as ZodError;
+
+      meta = zodError.issues.map((issue) => ({
+        field: issue.path.join("."),
+        message: issue.message,
+        errorCode: issue.code,
+      }));
+
+      console.log("meta", meta);
+
+      message = "Validation failed";
+    }
+
+    // ---------- Other runtime errors ----------
+    else if (exception instanceof Error) {
+      message = exception.message || message;
+    }
+
+    // ---------- Logging ----------
+    this.logger.error("❌ Exception caught", {
       message: exception.message,
       stack: exception.stack,
       status,
       path: req.url,
       method: req.method,
+      errorCode,
+      meta,
     });
 
+    // ---------- Response ----------
     res.status(status).json({
       status,
-      data: null,
-      message,
       success: false,
+      message,
+      action,
+      meta,
+      errorCode,
     });
   }
 }

package/templates/monorepo-starter/server/src/lib/guards/auth.guard.ts

@@ -1,13 +1,19 @@
-import { Injectable, UnauthorizedException } from "@nestjs/common";
-import type { CanActivate, ExecutionContext } from "@nestjs/common";
 import { Reflector } from "@nestjs/core";
 import type { Request, Response } from "express";
-import { IS_PUBLIC_KEY } from "@decorators/public.decorator";
-import { ROLES_KEY } from "@decorators/roles.decorator";
+import {
+  Injectable,
+  ForbiddenException,
+  UnauthorizedException,
+  type CanActivate,
+  type ExecutionContext,
+} from "@nestjs/common";
 import type { UserRole } from "@generated/prisma";
-import { TokenService } from "@modules/token/token.service";
-import { LoggerService } from "@modules/logger/logger.service";
-import { InjectLogger } from "@decorators/logger.decorator";
+
+import { ROLES_KEY } from "@/decorators/roles.decorator";
+import { InjectLogger } from "@/decorators/logger.decorator";
+import { IS_PUBLIC_KEY } from "@/decorators/public.decorator";
+import { TokenService } from "@/modules/token/token.service";
+import { LoggerService } from "@/modules/logger/logger.service";
 
 @Injectable()
 export class AuthGuard implements CanActivate {
@@ -16,7 +22,7 @@ export class AuthGuard implements CanActivate {
 
   constructor(
     private readonly tokenService: TokenService,
-    private readonly reflector: Reflector
+    private readonly reflector: Reflector,
   ) {}
 
   async canActivate(context: ExecutionContext): Promise<boolean> {
@@ -29,76 +35,34 @@ export class AuthGuard implements CanActivate {
 
     const requiredRoles = this.reflector.getAllAndOverride<UserRole[]>(
       ROLES_KEY,
-      [context.getHandler(), context.getClass()]
+      [context.getHandler(), context.getClass()],
     );
 
     const ctx = context.switchToHttp();
     const req = ctx.getRequest<Request>();
     const res = ctx.getResponse<Response>();
 
-    const accessToken = req.cookies["accessToken"];
-    const refreshToken = req.cookies["refreshToken"];
-
     try {
-      if (!accessToken) {
-        this.logger.warn(`Access token missing}`, {
-          route: req.url,
-        });
-        throw new Error("Access token is missing or expired");
-      }
-      const decoded = await this.tokenService.verifyToken(
-        accessToken,
-        "access"
-      );
-      if (!decoded) throw new UnauthorizedException("Invalid Access Token");
-      this.checkRoles(decoded.roles, requiredRoles);
-      this.tokenService.attachDecodedUser(req, decoded);
-      this.logger.debug(`✅ User Attached - Auth success`, {
-        userId: decoded.sub,
-      });
+      const payload = await this.tokenService.verifyToken(req, "accessToken");
+      this.checkRoles(payload.rol, requiredRoles);
+      this.tokenService.attachAuthContext(req, payload);
       return true;
-    } catch (err) {
-      if (!refreshToken)
-        throw new UnauthorizedException("Refresh token is missing");
-
-      try {
-        const decoded = await this.tokenService.verifyToken(
-          refreshToken,
-          "refresh"
-        );
-        if (!decoded) throw new Error("Invalid or expire Refresh Token");
-        this.logger.debug(`Refresh token verified`, {
-          userId: decoded.sub,
-        });
-        this.checkRoles(decoded.roles, requiredRoles);
-        await this.tokenService.refreshTokens(req, res, decoded);
-
-        if (!req["user"]) throw new UnauthorizedException("User not found");
+    } catch (err: any) {
+      const code = err?.response?.errorCode ?? err?.errorCode;
+      if (code !== "access_token_missing") throw err;
 
-        this.logger.log(`✅ Auth success`, {
-          userId: req.user?.id,
-          method: req.method,
-        });
-
-        return true;
-      } catch {
-        this.logger.warn(`Access denied: Missing or invalid token`);
-
-        throw new UnauthorizedException(
-          "Unauthorized: Invalid or expired token."
-        );
-      }
+      const payload = await this.tokenService.verifyToken(req, "refreshToken");
+      this.checkRoles(payload.rol, requiredRoles);
+      await this.tokenService.refreshTokens(req, res, payload);
+      if (!req["user"]) throw new UnauthorizedException("User not found");
+      return true;
     }
   }
 
-  private checkRoles(userRoles: UserRole[], requiredRoles?: UserRole[]) {
+  private checkRoles(userRole: UserRole, requiredRoles?: UserRole[]) {
     if (requiredRoles?.length) {
-      const hasRole = userRoles.some((role) => requiredRoles.includes(role));
-      if (!hasRole) {
-        throw new UnauthorizedException(
-          `Forbidden: Requires ${requiredRoles.join(", ")} access.`
-        );
-      }
+      const hasRole = requiredRoles.some((role) => role === userRole);
+      if (!hasRole) throw new ForbiddenException({ errorCode: "forbidden" });
     }
   }
 }