cqrs-boilerplate-code 1.0.0

package/README.md

@@ -0,0 +1,2 @@
+# cqrs-pattern-boilerplate-code
+cqrs-pattern-boilerplate-code

package/nest-cli.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "cqrs-boilerplate-code",
+  "version": "1.0.0",
+  "description": "AI Platform Service API Gateway",
+  "private": false,
+  "license": "UNLICENSED",
+  "author": "ankitdetroja",
+  "scripts": {
+    "clean": "rimraf dist coverage",
+    "build": "nest build",
+    "start": "nest start",
+    "start:dev": "nest start --watch",
+    "start:prod": "node dist/main.js",
+    "start:debug": "nest start --debug --watch",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "lint": "eslint \"{src,tests}/**/*.ts\" --fix"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.1.3",
+    "@nestjs/config": "^4.0.2",
+    "@nestjs/core": "^11.1.3",
+    "@nestjs/cqrs": "^11.0.3",
+    "@nestjs/platform-express": "^11.1.3",
+    "@nestjs/swagger": "^11.2.0",
+    "@nestjs/typeorm": "11.0.0",
+    "axios": "1.13.2",
+    "axios-retry": "^4.4.0",
+    "bottleneck": "^2.19.5",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.1",
+    "dotenv": "^16.4.5",
+    "jsonwebtoken": "^9.0.2",
+    "module-alias": "^2.2.3",
+    "nestjs-request-context": "^4.0.0",
+    "pg": "8.16.3",
+    "reflect-metadata": "^0.2.2",
+    "typeorm": "0.3.28",
+    "uuid": "^10.0.0",
+    "winston": "3.19.0"
+  },
+  "devDependencies": {
+    "@faker-js/faker": "^8.4.1",
+    "@golevelup/ts-jest": "^0.5.6",
+    "@nestjs/cli": "^10.3.2",
+    "@nestjs/schematics": "^10.1.1",
+    "@nestjs/testing": "^11.1.3",
+    "@types/jest": "^29.5.12",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/lodash": "^4.17.5",
+    "@types/multer": "^1.4.11",
+    "@types/node": "^20.14.2",
+    "@types/supertest": "^6.0.2",
+    "@types/uuid": "^9.0.8",
+    "jest": "^29.7.0",
+    "jest-mock-extended": "^3.0.7",
+    "prettier": "^3.3.2",
+    "rimraf": "^5.0.5",
+    "source-map-support": "^0.5.21",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.1.4",
+    "ts-loader": "^9.5.1",
+    "ts-mockito": "^2.6.1",
+    "ts-node": "^10.9.2",
+    "tsc-files": "^1.1.4",
+    "typescript": "^5.4.5"
+  }
+}

package/src/common-infra/common-infra.module.ts

@@ -0,0 +1,9 @@
+import { Module } from "@nestjs/common";
+import { DBModule } from "./database/database.module";
+
+@Module({
+  imports: [DBModule],
+  providers: [],
+  exports: [],
+})
+export class CommonInfraModule {}

package/src/common-infra/database/database.module.ts

@@ -0,0 +1,15 @@
+import { Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
+import { ConfigModule, ConfigService } from "@nestjs/config";
+import { typeOrmConfig } from "./typeorm.config";
+
+@Module({
+  imports: [
+    TypeOrmModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: typeOrmConfig,
+    }),
+  ],
+})
+export class DBModule {}

package/src/common-infra/database/typeorm.config.ts

@@ -0,0 +1,18 @@
+import { TypeOrmModuleOptions } from "@nestjs/typeorm";
+import { ConfigService } from "@nestjs/config";
+
+export const typeOrmConfig = (
+  configService: ConfigService,
+): TypeOrmModuleOptions => ({
+  type: "postgres",
+  host: configService.get<string>("DB_HOST"),
+  port: configService.get<number>("DB_PORT"),
+  username: configService.get<string>("DB_USERNAME"),
+  password: configService.get<string>("DB_PASSWORD"),
+  database: configService.get<string>("DB_NAME"),
+  autoLoadEntities: true,
+  synchronize: configService.get<string>("NODE_ENV") !== "production",
+  migrations: ["dist/migrations/*.js"],
+  migrationsRun: true,
+  logging: configService.get<string>("NODE_ENV") !== "production",
+});

package/src/core-common/constant/app.constant.ts

@@ -0,0 +1,2 @@
+export const PORT = 3001;
+export const BASE_URL = '/api/retail'

package/src/core-common/core-common.module.ts

@@ -0,0 +1,9 @@
+import { Module } from "@nestjs/common";
+
+@Module({
+  providers: [
+  ],
+  exports: [
+  ],
+})
+export class CoreCommonModule {}

package/src/core-common/error/custom-error/already-exists.error.ts

@@ -0,0 +1,17 @@
+import { HttpStatus } from "@nestjs/common";
+import { GenericError } from "../generic.error";
+
+/**
+ * Custom error class for representing the scenario where an entity already exists/Conflict with existing.
+ * Extends the GenericError class.
+ */
+export class AlreadyExistsError extends GenericError {
+  /**
+   * Constructor for the AlreadyExistsError class.
+   * @param code - Short code associated with the error.
+   * @param message - Detailed error information.
+   */
+  constructor(code: string, message: string) {
+    super(code, message, HttpStatus.CONFLICT);
+  }
+}

package/src/core-common/error/custom-error/bad-request.error.ts

@@ -0,0 +1,8 @@
+import { HttpStatus } from "@nestjs/common";
+import { GenericError } from "../generic.error";
+
+export class BadRequestError extends GenericError {
+  constructor(code: string, message: string) {
+    super(code, message, HttpStatus.BAD_REQUEST);
+  }
+}

package/src/core-common/error/custom-error/conflict.error.ts

@@ -0,0 +1,17 @@
+import { HttpStatus } from "@nestjs/common";
+import { GenericError } from "../generic.error";
+
+/**
+ * Custom error class for representing conflict errors.
+ * Extends the GenericError class.
+ */
+export class ConflictError extends GenericError {
+  /**
+   * Constructor for the ConflictError class.
+   * @param code - Short code associated with the error.
+   * @param message - Detailed error information.
+   */
+  constructor(code: string, message: string) {
+    super(code, message, HttpStatus.CONFLICT);
+  }
+}

package/src/core-common/error/custom-error/custom-validation-error.ts

@@ -0,0 +1,9 @@
+import { BadRequestError } from "./bad-request.error";
+
+export class CustomValidationError extends BadRequestError {
+  constructor(
+    public validationErrors: any
+  ) {
+    super("ValidationError", "There are issues found in the input provided.");
+  }
+}

package/src/core-common/error/custom-error/forbidden.error.ts

@@ -0,0 +1,8 @@
+import { HttpStatus } from "@nestjs/common";
+import { GenericError } from "../generic.error";
+
+export class ForbiddenError extends GenericError {
+  constructor(code: string, message: string) {
+    super(code, message, HttpStatus.FORBIDDEN);
+  }
+}

package/src/core-common/error/custom-error/internal-server.error.ts

@@ -0,0 +1,11 @@
+import { HttpStatus } from "@nestjs/common";
+import { GenericError } from "../generic.error";
+
+export class InternalServerError extends GenericError {
+  constructor(
+    code = "INTERNAL_SERVER_ERROR",
+    message = "An unexpected error occurred",
+  ) {
+    super(code, message, HttpStatus.INTERNAL_SERVER_ERROR);
+  }
+}

package/src/core-common/error/custom-error/not-found.error.ts

@@ -0,0 +1,8 @@
+import { HttpStatus } from "@nestjs/common";
+import { GenericError } from "../generic.error";
+
+export class NotFoundError extends GenericError {
+  constructor(code: string, message: string) {
+    super(code, message, HttpStatus.NOT_FOUND);
+  }
+}

package/src/core-common/error/custom-error/service-unavailable.error.ts

@@ -0,0 +1,8 @@
+import { HttpStatus } from "@nestjs/common";
+import { GenericError } from "../generic.error";
+
+export class ServiceUnavailableError extends GenericError {
+  constructor(code: string, message: string) {
+    super(code, message, HttpStatus.SERVICE_UNAVAILABLE);
+  }
+}

package/src/core-common/error/custom-error/unauthorized.error.ts

@@ -0,0 +1,8 @@
+import { HttpStatus } from "@nestjs/common";
+import { GenericError } from "../generic.error";
+
+export class UnauthorizedError extends GenericError {
+  constructor(code: string, message: string) {
+    super(code, message, HttpStatus.UNAUTHORIZED);
+  }
+}

package/src/core-common/error/custom-error/unprocess-entity.error.ts

@@ -0,0 +1,8 @@
+import { HttpStatus } from "@nestjs/common";
+import { GenericError } from "../generic.error";
+
+export class UnprocessableEntityError extends GenericError {
+  constructor(code: string, message: string) {
+    super(code, message, HttpStatus.UNPROCESSABLE_ENTITY);
+  }
+}

package/src/core-common/error/custom-error/validation.error.ts

@@ -0,0 +1,8 @@
+import { HttpStatus } from "@nestjs/common";
+import { GenericError } from "../generic.error";
+
+export class ValidationError extends GenericError {
+  constructor(code: string, message: string) {
+    super(code, message, HttpStatus.UNPROCESSABLE_ENTITY);
+  }
+}

package/src/core-common/error/generic.error.ts

@@ -0,0 +1,31 @@
+import { HttpStatus } from "@nestjs/common";
+import { ApiProperty } from "@nestjs/swagger";
+
+/**
+ * Custom error class which needs to be returned from the lower layers to the higher calling layers
+ */
+export class GenericError {
+  @ApiProperty({ description: "Short error code" })
+  public code: string;
+
+  @ApiProperty({ description: "Detailed error description" })
+  public message: string;
+
+  @ApiProperty({ description: "Detailed error description" })
+  public statusCode: HttpStatus;
+
+  /**
+   * Default constructor
+   * @param code - Short error code  e.g. "InvaliOperation", "ItemNotFound" etc
+   * @param message  - Detailed error message
+   */
+  constructor(
+    code: string,
+    message: string,
+    statusCode: HttpStatus = HttpStatus.INTERNAL_SERVER_ERROR,
+  ) {
+    this.code = code;
+    this.message = message;
+    this.statusCode = statusCode;
+  }
+}

package/src/core-common/error/index.ts

@@ -0,0 +1,10 @@
+export * from "./generic.error";
+export * from "./custom-error/bad-request.error";
+export * from "./custom-error/unauthorized.error";
+export * from "./custom-error/forbidden.error";
+export * from "./custom-error/not-found.error";
+export * from "./custom-error/conflict.error";
+export * from "./custom-error/already-exists.error";
+export * from "./custom-error/validation.error";
+export * from "./custom-error/unprocess-entity.error";
+export * from "./custom-error/service-unavailable.error";

package/src/core-common/logger/index.ts

@@ -0,0 +1,175 @@
+import winston, { Logger } from "winston";
+
+/* ---------------------------------- Types --------------------------------- */
+
+enum SeverityText {
+  INFO = "Information",
+  DEBUG = "Debug",
+  WARNING = "Warning",
+  ERROR = "Error",
+}
+
+type LogMetadata = {
+  ClassName?: string;
+  MethodName?: string;
+};
+
+export type OrgContext = {
+  orgId?: string;
+  orgFid?: string;
+  userId?: string;
+};
+
+/* --------------------------------- Service -------------------------------- */
+
+export class LoggerService {
+  private readonly logger: Logger;
+  private readonly deploymentEnv: string;
+  private readonly hostImageVersion: string;
+  private readonly otelAgentHost: string;
+
+  constructor(logLevel: string = "debug") {
+    this.deploymentEnv = "rls-dev";
+    this.hostImageVersion = process.env.SERVICE_VERSION ?? "202501.1";
+    this.otelAgentHost = process.env.OTEL_AGENT_HOST ?? "10.0.0.1";
+    this.logger = this.createLogger(logLevel);
+    this.overrideConsole();
+  }
+
+  /* ------------------------------- Public API ------------------------------- */
+
+  log(message: string, metadata?: LogMetadata) {
+    this.write("info", SeverityText.INFO, message, metadata);
+  }
+
+  debug(message: string, metadata?: LogMetadata) {
+    this.write("debug", SeverityText.DEBUG, message, metadata);
+  }
+
+  warn(message: string, metadata?: LogMetadata) {
+    this.write("warn", SeverityText.WARNING, message, metadata);
+  }
+
+  error(message: string, metadata?: LogMetadata, error?: Error) {
+    this.write("error", SeverityText.ERROR, message, metadata, error);
+  }
+
+  /* ------------------------------ Logger Core ------------------------------ */
+
+  private write(
+    level: keyof Logger,
+    severity: SeverityText,
+    message: string,
+    metadata: LogMetadata = {},
+    error?: Error,
+  ) {
+    const body = {
+      SeverityText: severity,
+      ...metadata,
+      ...(error && {
+        ErrorMessage: error.message,
+        StackTrace: error.stack,
+      }),
+    };
+
+    this.logger[level](this.redactSecrets(message), body);
+  }
+
+  private createLogger(level: string): Logger {
+    return winston.createLogger({
+      level,
+      levels: winston.config.npm.levels,
+      format: winston.format.combine(
+        winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }),
+        winston.format.printf(({ level, message, timestamp, ...meta }) =>
+          JSON.stringify({
+            message: this.safeStringify(message),
+            attributes: this.buildAttributes(level),
+            timestamp: timestamp,
+            ...this.cleanMeta(meta),
+          }),
+        ),
+      ),
+      transports: [new winston.transports.Console()],
+    });
+  }
+
+  /* ------------------------------- Context -------------------------------- */
+
+  private buildAttributes(level: string) {
+    return {
+      "service.image.version": this.hostImageVersion,
+      "deployment.environment": this.deploymentEnv,
+      "otel.agent.host": this.otelAgentHost,
+      "service.log.level": level,
+    };
+  }
+
+  /* ------------------------------- Helpers -------------------------------- */
+
+  private cleanMeta(meta: Record<string, unknown>) {
+    return Object.fromEntries(
+      Object.entries(meta).filter(
+        ([_, value]) => value !== undefined && value !== "None",
+      ),
+    );
+  }
+
+  private safeStringify(input: unknown): string {
+    try {
+      return typeof input === "string"
+        ? input
+        : JSON.stringify(input, this.circularReplacer());
+    } catch {
+      return "[Unserializable Object]";
+    }
+  }
+
+  private circularReplacer() {
+    const seen = new WeakSet();
+    return (_: string, value: any) => {
+      if (typeof value === "object" && value !== null) {
+        if (seen.has(value)) return "[Circular]";
+        seen.add(value);
+      }
+      return value;
+    };
+  }
+
+  /* ----------------------------- Redaction -------------------------------- */
+
+  private redactSecrets(message: string): string {
+    const patterns = [
+      {
+        name: "JWT",
+        regex: /eyJ[a-zA-Z0-9-_]+\.[a-zA-Z0-9-_]+\.[a-zA-Z0-9-_]+/g,
+        visible: 10,
+      },
+      {
+        name: "BEARER",
+        regex: /Bearer\s+eyJ[A-Za-z0-9\-._~+/]+=*/gi,
+        visible: 15,
+      },
+      { name: "API_KEY", regex: /\b[A-Za-z0-9]{32,}\b/g, visible: 8 },
+      { name: "AWS_SECRET", regex: /AKIA[0-9A-Z]{16}/g, visible: 8 },
+    ];
+
+    return patterns.reduce((msg, { regex, visible, name }) => {
+      return msg.replace(
+        regex,
+        (m) => `${m.slice(0, visible)}...[REDACTED_${name}]`,
+      );
+    }, message);
+  }
+
+  /* --------------------------- Console Override ---------------------------- */
+
+  private overrideConsole() {
+    const blocked = ["NodeSDK", "AuthToken"];
+    console.log = (...args: unknown[]) => {
+      const msg = args.map(String).join(" ");
+      if (blocked.some((k) => msg.includes(k))) return;
+      this.log(msg);
+    };
+  }
+}

package/src/core-common/logger/logger.module.ts

@@ -0,0 +1,8 @@
+import { Module } from "@nestjs/common";
+import { LoggerProvider } from "./logger.provider";
+
+@Module({
+  providers: [LoggerProvider],
+  exports: [LoggerProvider],
+})
+export class LoggerModule {}

package/src/core-common/logger/logger.provider.ts

@@ -0,0 +1,7 @@
+import { Provider } from "@nestjs/common";
+import { LoggerService } from ".";
+
+export const LoggerProvider: Provider = {
+  provide: LoggerService,
+  useClass: LoggerService,
+};

package/src/core-common/response-model/generic-error-response.model.ts

@@ -0,0 +1,44 @@
+import { Result } from "../result-model/result";
+
+/**
+ * Standard error response to be returned to the caller of the API.
+ * This class represents the structure of an error response returned by the API
+ * in case of failures.
+ */
+
+export class ErrorDisplay {
+  code: string;
+  message: string;
+  validationError?: any;
+}
+export class GenericErrorResponse {
+  statusCode: number;
+  success: boolean = false;
+  error: ErrorDisplay;
+  timestamp: string;
+  data: any;
+
+  constructor() {
+    this.statusCode = 500; // Default value
+    this.success = false;
+    this.timestamp = new Date().toISOString(); // Default value
+  }
+  /**
+   * Sets the properties from the Result object.
+   * @param result - Result object instance returned from the controller method.
+   * @param statusCode - HTTP status code.
+   */
+  initialize(
+    result: Result<any>,
+    statusCode: number,
+  ) {
+    this.statusCode = statusCode;
+    this.error = {
+      code: result.error?.code || "ERROR",
+      message: result.error?.message || "An error occurred.",
+    };
+    this.data = result.data
+    this.success = result.success || false;
+    this.timestamp = result.timestamp || new Date().toISOString();
+  }
+}

package/src/core-common/response-model/generic-success-response.model.ts

@@ -0,0 +1,25 @@
+import { Result } from "../result-model/result";
+
+/**
+ * Standard response object to be returned to the caller of the API.
+ * This class represents the structure of a success response returned by the API.
+ * @typeparam T - The type of data included in the response.
+ */
+export class GenericSuccessResponse<T> {
+  statusCode: number;
+  success: boolean;
+  data: T;
+  timestamp: string;
+
+  /**
+   * Sets the properties from the Result object.
+   * @param result - Result object instance returned from the controller method.
+   * @param statusCode - HTTP status code.
+   */
+  initialize(result: Result<T>, statusCode: number) {
+    this.statusCode = statusCode;
+    this.success = result.success;
+    this.data = result.data;
+    this.timestamp = new Date().toISOString();
+  }
+}

package/src/core-common/result-model/result.ts

@@ -0,0 +1,38 @@
+import { GenericError } from "../error/generic.error";
+
+export class Result<T> {
+  success: boolean;
+  data: T;
+  error: GenericError;
+  timestamp: string;
+
+  public static success<T>(data: T): Result<T> {
+    const result = new Result<T>();
+    result.success = true;
+    result.data = data;
+    result.timestamp = new Date().toISOString();
+    return result;
+  }
+
+  public static failed<T>(error: GenericError, data?: T): Result<T> {
+    const result = new Result<T>();
+    result.success = false;
+    result.timestamp = new Date().toISOString();
+    result.error = error;
+    if (data) {
+      result.data = data;
+    }
+    return result;
+  }
+
+  public static throwError<T>(error: GenericError, data?: T): Result<T> {
+    const result = new Result<T>();
+    result.success = false;
+    result.timestamp = new Date().toISOString();
+    result.error = error;
+    if (data) {
+      result.data = data;
+    }
+    throw result;
+  }
+}

package/src/middleware/async-storage.middleware.ts

@@ -0,0 +1,29 @@
+// async-storage.middleware.ts
+import { Injectable, NestMiddleware } from "@nestjs/common";
+import { AsyncLocalStorage } from "async_hooks";
+import { Request, Response, NextFunction } from "express";
+
+@Injectable()
+export class AsyncStorageMiddleware implements NestMiddleware {
+  private static storage = new AsyncLocalStorage<Map<string, any>>();
+
+  static get(key: string): any {
+    const store = AsyncStorageMiddleware.storage.getStore();
+    return store?.get(key);
+  }
+
+  static set(key: string, value: any): void {
+    const store = AsyncStorageMiddleware.storage.getStore();
+    if (store) {
+      store.set(key, value);
+    }
+  }
+
+  use(req: Request, _res: Response, next: NextFunction) {
+    const store = new Map<string, any>();
+    store.set("request", req);
+    AsyncStorageMiddleware.storage.run(store, () => {
+      next();
+    });
+  }
+}

package/src/middleware/filter/global-exeception.filter.ts

@@ -0,0 +1,117 @@
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+} from "@nestjs/common";
+import { Response } from "express";
+import { GenericError } from "../../core-common/error";
+import { CustomValidationError } from "../../core-common/error/custom-error/custom-validation-error";
+import { Result } from "../../core-common/result-model/result";
+
+/**
+ * Handles and processes  exceptions, providing standardized error responses.
+ * This global exception handler can be used to catch and respond to exceptions thrown
+ * during HTTP requests and format responses accordingly.
+ */
+
+@Catch()
+export class GlobalExceptionHandler implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const response = host.switchToHttp().getResponse<Response>();
+
+    /* 1️⃣ Domain Result (highest priority) */
+    if (exception instanceof Result) {
+      const statusCode =
+        exception.error?.statusCode ?? HttpStatus.INTERNAL_SERVER_ERROR;
+
+      const payload: any = {
+        statusCode,
+        success: false,
+        error: {
+          code: exception.error?.code ?? "ERROR",
+          message: exception.error?.message ?? "An error occurred",
+        },
+        timestamp: exception.timestamp ?? new Date().toISOString(),
+      };
+
+      if (exception.data !== undefined && exception.data !== null) {
+        payload.data = exception.data;
+      }
+
+      return response.status(statusCode).json(payload);
+    }
+
+    /* 2️⃣ Custom domain errors */
+    if (exception instanceof GenericError) {
+      return response.status(exception.statusCode).json({
+        statusCode: exception.statusCode,
+        success: false,
+        error: {
+          code: exception.code,
+          message: exception.message,
+        },
+        timestamp: new Date().toISOString(),
+      });
+    }
+
+    /* 3️⃣ NestJS HTTP exceptions */
+    if (exception instanceof HttpException) {
+      const status = exception.getStatus();
+      const res = exception.getResponse();
+
+      const isValidationPipeError = exception.stack?.includes("ValidationPipe");
+
+      if (isValidationPipeError) {
+        const validationErrors = new CustomValidationError(res);
+        return response.status(validationErrors.statusCode).json({
+          success: false,
+          error: {
+            code: validationErrors.code,
+            message: validationErrors.message,
+            validationError: validationErrors.validationErrors,
+          },
+          timestamp: new Date().toISOString(),
+        });
+      }
+
+      return response.status(status).json({
+        statusCode: status,
+        success: false,
+        error: {
+          code: "HTTP_EXCEPTION",
+          message:
+            typeof res === "string"
+              ? res
+              : ((res as any).message ?? exception.message),
+        },
+        timestamp: new Date().toISOString(),
+      });
+    }
+
+    /* 4️⃣ Native JS errors (TypeError, Error, etc.) */
+    if (exception instanceof Error) {
+      return response.status(HttpStatus.INTERNAL_SERVER_ERROR).json({
+        statusCode: HttpStatus.INTERNAL_SERVER_ERROR,
+        success: false,
+        error: {
+          code: exception.name,
+          message: exception.message,
+        },
+        timestamp: new Date().toISOString(),
+      });
+    }
+
+    /* 5️⃣ Truly unknown (non-Error throwables) */
+    return response.status(HttpStatus.INTERNAL_SERVER_ERROR).json({
+      statusCode: HttpStatus.INTERNAL_SERVER_ERROR,
+      success: false,
+      error: {
+        code: "UNKNOWN_ERROR",
+        message: "Internal server error",
+      },
+      timestamp: new Date().toISOString(),
+    });
+  }
+}

package/src/middleware/index.ts

@@ -0,0 +1,2 @@
+export * from './async-storage.middleware'
+export * from './platform-auth.middleware'

package/src/middleware/interceptor/response-handler.ts

@@ -0,0 +1,69 @@
+import {
+    CallHandler,
+    ExecutionContext,
+    Injectable,
+    NestInterceptor,
+} from "@nestjs/common";
+import { ServerResponse } from "http";
+import { Observable } from "rxjs";
+import { GenericErrorResponse } from "../../core-common/response-model/generic-error-response.model";
+import { GenericSuccessResponse } from "../../core-common/response-model/generic-success-response.model";
+import { Result } from "../../core-common/result-model/result";
+import { HttpResponseFormatter } from "../utils/http-response.formatter";
+import { LoggerService } from "@core-common/logger";
+/**
+ * Intercepts the response and returns a standard ApiReponse object
+ */
+@Injectable()
+export class ResponseHandler implements NestInterceptor {
+  constructor(
+    private readonly logger: LoggerService
+  ) {}
+
+  intercept(exContext: ExecutionContext, next: CallHandler): Observable<any> {
+    return new Observable((subscriber) => {
+      next.handle().subscribe({
+        next: (data) => {
+          const mapped = this.handleResponse(exContext, data);
+          subscriber.next(mapped);
+        },
+        error: (err) => {
+          this.logger.error('Error in ResponseHandler Interceptor', err);
+          subscriber.error(err);
+        },
+        complete: () => {
+          subscriber.complete();
+        },
+      });
+    });
+  }
+
+  /**
+   * Checks the response content and appropriately sets the status code and wraps the return value in a ApiErroReponse or a
+   * ApiSuccessReponse
+   * @param excecutionContext  - Instance of the executionContext object
+   * @param result  Data returned by the controller method
+   * @returns - Instance of ApiSuccessReponse or ApiErrorReponse
+   */
+  private handleResponse(
+    excecutionContext: ExecutionContext,
+    result: Result<any>,
+  ): GenericSuccessResponse<any> | GenericErrorResponse {
+    let serverResponse = excecutionContext
+      .switchToHttp()
+      .getResponse<ServerResponse>();
+
+    const apiReponse: any = new HttpResponseFormatter().getStandardApiResponse(
+      serverResponse.statusCode,
+      result,
+    );
+    serverResponse.statusCode = apiReponse.statusCode
+      ? apiReponse.statusCode
+      : apiReponse?.error?.statusCode;
+    serverResponse[`statusCode`] = serverResponse.statusCode;
+    if (apiReponse?.statusCode) {
+      delete apiReponse?.error?.statusCode;
+    }
+    return apiReponse;
+  }
+}

package/src/middleware/platform-auth.middleware.ts

@@ -0,0 +1,13 @@
+import { Injectable, NestMiddleware } from "@nestjs/common";
+import { Request, Response } from "express";
+
+@Injectable()
+export class AuthMiddleware implements NestMiddleware<Request, Response> {
+  use(req: Request, _res: Response, next: () => void): void {
+    const authHeader = req.headers["authorization"];
+    // Implement your authentication logic here
+    // For example, validate JWT token from authHeader      
+    console.log("Auth Middleware executed", authHeader);
+    next();
+  }
+}

package/src/middleware/utils/http-response.formatter.ts

@@ -0,0 +1,126 @@
+import { HttpStatus } from "@nestjs/common";
+import { AlreadyExistsError } from "../../core-common/error/custom-error/already-exists.error";
+import { GenericError } from "../../core-common/error/generic.error";
+import { GenericErrorResponse } from "../../core-common/response-model/generic-error-response.model";
+import { GenericSuccessResponse } from "../../core-common/response-model/generic-success-response.model";
+import { Result } from "../../core-common/result-model/result";
+import { BadRequestError, ConflictError, ForbiddenError, NotFoundError, ServiceUnavailableError, UnauthorizedError, UnprocessableEntityError, ValidationError } from "../../core-common/error";
+import { InternalServerError } from "../../core-common/error/custom-error/internal-server.error";
+
+/**
+ * Helps in returning a appropriate and standard Response format  based on success or error scenario
+ */
+export class HttpResponseFormatter {
+  constructor() {}
+  /**
+   * Returns a standard formatted  ApiSuccesReponse or ApiErrorResponse depending on the response data
+   * @param statusCode - Http Status code
+   * @param responseData - Response value from the api controller method
+   */
+  public getStandardApiResponse(
+    statusCode: number,
+    responseData: any,
+  ): GenericSuccessResponse<any> | GenericErrorResponse {
+    if (this.isSuccessfulResult(responseData)) {
+      return this.getSuccessResponse(responseData, statusCode);
+    }
+
+    if (this.isFailedResult(responseData)) {
+      return this.getFailureResponse(responseData);
+    }
+
+    return responseData;
+  }
+
+  /**
+   *
+   * @param responseData Initializes and returns  the success api response
+   * @param statusCode - Http Status code
+   * @returns - instance of ApiSuccessResponse object
+   */
+  private getSuccessResponse(
+    responseData: any,
+    statusCode: number,
+  ): GenericSuccessResponse<any> {
+    const apiSuccessResponse = new GenericSuccessResponse();
+    apiSuccessResponse.initialize(responseData, statusCode);
+    return apiSuccessResponse;
+  }
+
+  /**
+   * Checks if the the data is of type Result and is successful
+   * @param responseData - response data
+   * @returns - boolean
+   */
+  private isSuccessfulResult(responseData: any): boolean {
+    return responseData instanceof Result && responseData.success;
+  }
+
+  /**
+   * Checks if the the data is of type Result and is successful
+   * @param responseData - response data
+   * @returns - boolean
+   */
+  private isFailedResult(responseData: any): boolean {
+    return responseData instanceof Result && !responseData.success;
+  }
+
+  /**
+   * Gets the failure response based on the result contents
+   * @param result - Result object returned from the controller method
+   */
+  private getFailureResponse(result: Result<any>) {
+    const statusCode = this.getStatusCode(result.error);
+    const apiErrorResponse = new GenericErrorResponse();
+    apiErrorResponse.initialize(result, statusCode);
+    return apiErrorResponse;
+  }
+
+  private getStatusCode(error: GenericError): number {
+    if (error instanceof BadRequestError) {
+      return HttpStatus.BAD_REQUEST;
+    }
+
+    if (error instanceof UnauthorizedError) {
+      return HttpStatus.UNAUTHORIZED;
+    }
+
+    if (error instanceof ForbiddenError) {
+      return HttpStatus.FORBIDDEN;
+    }
+
+    if (error instanceof NotFoundError) {
+      return HttpStatus.NOT_FOUND;
+    }
+
+    if (error instanceof AlreadyExistsError) {
+      return HttpStatus.CONFLICT;
+    }
+
+    if (error instanceof ConflictError) {
+      return HttpStatus.CONFLICT;
+    }
+
+    if (error instanceof ValidationError) {
+      return HttpStatus.UNPROCESSABLE_ENTITY;
+    }
+
+    if (error instanceof UnprocessableEntityError) {
+      return HttpStatus.UNPROCESSABLE_ENTITY;
+    }
+
+    if (error instanceof ServiceUnavailableError) {
+      return HttpStatus.SERVICE_UNAVAILABLE;
+    }
+
+    if (error instanceof InternalServerError) {
+      return HttpStatus.INTERNAL_SERVER_ERROR;
+    }
+
+    if (error instanceof GenericError) {
+      return error.statusCode;
+    }
+
+    return HttpStatus.INTERNAL_SERVER_ERROR;
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,10 @@
+{
+    "extends": "./tsconfig.json",
+    "exclude": [
+        "node_modules",
+        "dist",
+        "coverage",
+        "tests",
+        "**/*.spec.ts"
+    ]
+}

package/tsconfig.json

@@ -0,0 +1,58 @@
+{
+    "compilerOptions": {
+        /* Language & Environment */
+        "target": "es2024",
+        "lib": [
+            "es2024"
+        ],
+        "module": "commonjs",
+        "moduleResolution": "node",
+        "types": [
+            "node"
+        ],
+        /* Output */
+        "outDir": "./dist",
+        "declaration": true,
+        "sourceMap": true,
+        "removeComments": true,
+        "incremental": true,
+        /* Decorators (NestJS) */
+        "emitDecoratorMetadata": true,
+        "experimentalDecorators": true,
+        /* Module Interop */
+        "esModuleInterop": true,
+        "allowSyntheticDefaultImports": true,
+        "resolveJsonModule": true,
+        /* Base Paths */
+        "baseUrl": ".",
+        "paths": {
+            "@routes/*": [
+                "src/routes/*"
+            ],
+            "@core-common/*": [
+                "src/core-common/*"
+            ],
+            "@common-infra/*": [
+                "src/common-infra/*"
+            ],
+            "@middleware/*": [
+                "src/middleware/*"
+            ]
+        },
+        /* Type Safety (non-strict by design) */
+        "strict": false,
+        "strictNullChecks": false,
+        "strictPropertyInitialization": false,
+        "noImplicitAny": false,
+        "noImplicitReturns": false,
+        "strictBindCallApply": true,
+        /* Code Quality */
+        "forceConsistentCasingInFileNames": true,
+        "noFallthroughCasesInSwitch": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        /* Performance */
+        "skipLibCheck": true,
+        "inlineSources": true
+    }
+}