@carecard/common-util 3.0.10 → 3.1.1

package/index.d.ts

@@ -4,7 +4,10 @@
  * @param arrayOfProperties - An array of property names to extract.
  * @returns A new object with the extracted properties.
  */
-export function extractObjectWithProperties(obj: any, arrayOfProperties: string[]): Record<string, any>;
+export function extractObjectWithProperties(
+  obj: any,
+  arrayOfProperties: string[]
+): Record<string, any>;
 
 /**
  * Utility functions for object manipulation.
@@ -15,47 +18,56 @@ export const util: {
 };
 
 /** Throws an Account_Suspended error. */
-export function throwAccountSuspendedError(params?: { userMessage?: string, details?: any }): never;
+export function throwAccountSuspendedError(params?: { userMessage?: string; details?: any }): never;
 /** Throws an Account_Blocked error. */
-export function throwAccountBlockedError(params?: { userMessage?: string, details?: any }): never;
+export function throwAccountBlockedError(params?: { userMessage?: string; details?: any }): never;
 /** Throws an Account_Inactive error. */
-export function throwAccountInactiveError(params?: { userMessage?: string, details?: any }): never;
+export function throwAccountInactiveError(params?: { userMessage?: string; details?: any }): never;
 /** Middleware to handle 404 Not Found. */
 export function notFound404(req: any, res: any, next: any): void;
 /** Central application error handler middleware. */
 export function appErrorHandler(err: any, req: any, res: any, next: any): void;
 /** Throws a Validation_Failure error. */
-export function throwValidationFailureError(params?: { userMessage?: string, details?: any }): never;
+export function throwValidationFailureError(params?: {
+  userMessage?: string;
+  details?: any;
+}): never;
 /** Throws a Record_Exist error. */
-export function throwRecordExistError(params?: { userMessage?: string, details?: any }): never;
+export function throwRecordExistError(params?: { userMessage?: string; details?: any }): never;
 /** Throws a Wrong_Credentials error. */
-export function throwWrongCredentialsError(params?: { userMessage?: string, details?: any }): never;
+export function throwWrongCredentialsError(params?: { userMessage?: string; details?: any }): never;
 /** Throws a Login_Required error. */
-export function throwLoginRequiredError(params?: { userMessage?: string, details?: any }): never;
+export function throwLoginRequiredError(params?: { userMessage?: string; details?: any }): never;
 /** Throws a Record_NotFound error. */
-export function throwRecordNotFoundError(params?: { userMessage?: string, details?: any }): never;
+export function throwRecordNotFoundError(params?: { userMessage?: string; details?: any }): never;
 /** Throws a Record_NotSaved error. */
-export function throwRecordNotSavedError(params?: { userMessage?: string, details?: any }): never;
+export function throwRecordNotSavedError(params?: { userMessage?: string; details?: any }): never;
 /** Throws an Update_Failed error. */
-export function throwUpdateFailedError(params?: { userMessage?: string, details?: any }): never;
+export function throwUpdateFailedError(params?: { userMessage?: string; details?: any }): never;
 /** Throws a Transaction_Failed error. */
-export function throwTransactionFailedError(params?: { userMessage?: string, details?: any }): never;
+export function throwTransactionFailedError(params?: {
+  userMessage?: string;
+  details?: any;
+}): never;
 /** Throws a Used_Token error. */
-export function throwUsedTokenError(params?: { userMessage?: string, details?: any }): never;
+export function throwUsedTokenError(params?: { userMessage?: string; details?: any }): never;
 /** Throws a Bad_Visitor_Token error. */
-export function throwBadVisitorTokenError(params?: { userMessage?: string, details?: any }): never;
+export function throwBadVisitorTokenError(params?: { userMessage?: string; details?: any }): never;
 /** Throws a File_Format_Not_Supported error. */
-export function throwFileFormatNotSupportedError(params?: { userMessage?: string, details?: any }): never;
+export function throwFileFormatNotSupportedError(params?: {
+  userMessage?: string;
+  details?: any;
+}): never;
 /** Throws a Not_Authorized error. */
-export function throwNotAuthorizedError(params?: { userMessage?: string, details?: any }): never;
+export function throwNotAuthorizedError(params?: { userMessage?: string; details?: any }): never;
 /** Throws a Bad_Input error. */
-export function throwBadInputError(params?: { userMessage?: string, details?: any }): never;
+export function throwBadInputError(params?: { userMessage?: string; details?: any }): never;
 /** Throws an Input_Not_Uuid error. */
-export function throwInputNotUuidError(params?: { userMessage?: string, details?: any }): never;
+export function throwInputNotUuidError(params?: { userMessage?: string; details?: any }): never;
 /** Throws a File_Too_Large error. */
-export function throwFileTooLargeError(params?: { userMessage?: string, details?: any }): never;
+export function throwFileTooLargeError(params?: { userMessage?: string; details?: any }): never;
 /** Throws an Invalid_Time_Value error. */
-export function throwInvalidTimeValueError(params?: { userMessage?: string, details?: any }): never;
+export function throwInvalidTimeValueError(params?: { userMessage?: string; details?: any }): never;
 
 /**
  * Application-level error handlers and throwers.
@@ -101,3 +113,78 @@ export const resCode: {
   setCreated201: typeof setCreated201;
   setBadRequest400ClientError: typeof setBadRequest400ClientError;
 };
+
+// --- New Standardized API Response System ---
+
+/**
+ * Standard API response metadata.
+ */
+export interface ApiResponseMeta {
+  version: string;
+  service: string;
+  environment: string;
+  timestamp: string;
+  requestId: string;
+  traceId: string;
+  client?: {
+    appId?: string;
+    ip?: string;
+  };
+  pagination?: {
+    page: number;
+    limit: number;
+    total: number;
+  };
+  [key: string]: any;
+}
+
+/**
+ * Standard API error object.
+ */
+export interface ApiError {
+  code: string;
+  message?: string;
+  details?: string;
+  fields?: Record<string, string>;
+}
+
+/**
+ * Standard API response body.
+ */
+export interface ApiResponse<T = any> {
+  success: boolean;
+  statusCode: number;
+  message: string;
+  data: T | null;
+  error: ApiError | null;
+  meta: ApiResponseMeta;
+}
+
+/**
+ * Express middleware to generate and attach request context.
+ */
+export function requestContext(req: any, res: any, next: any): void;
+
+/**
+ * Standardized API response utility.
+ */
+export function sendResponse<T = any>(params: {
+  req: any;
+  res: any;
+  statusCode?: number;
+  success?: boolean;
+  message?: string;
+  data?: T | null;
+  error?: ApiError | null;
+  meta?: Partial<ApiResponseMeta>;
+}): any;
+
+/**
+ * Helper for standardized errors.
+ */
+export function createError(params: {
+  code: string;
+  details?: string;
+  message?: string;
+  fields?: Record<string, string>;
+}): ApiError;

package/index.js

@@ -1,5 +1,8 @@
-module.exports = {
-    util: require( './lib/untilityFunctions' ),
-    error: require( './lib/appErrorHandlers' ),
-    resCode: require( './lib/responseStatus' )
-}
+'use strict';
+
+/**
+ * @carecard/common-util
+ * Standardized API response and utility functions for Express.js and Next.js microservices.
+ */
+
+module.exports = require('./src/index');

package/index.mjs

@@ -0,0 +1,5 @@
+import commonUtil from './index.js';
+
+export const { util, error, resCode, requestContext, sendResponse, createError } = commonUtil;
+
+export default commonUtil;

package/package.json

@@ -1,29 +1,67 @@
 {
   "name": "@carecard/common-util",
-  "version": "3.0.10",
-  "repository": "https://github.com/CareCard-ca/pkg-common-util",
-  "description": "Common utility for MVC framework",
+  "version": "3.1.1",
+  "description": "Standardized API response and utility functions for Express.js and Next.js microservices",
   "main": "index.js",
+  "module": "index.mjs",
   "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "require": "./index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CareCard-ca/pkg-common-util"
+  },
   "scripts": {
     "test": "export NODE_ENV=test && mocha --recursive",
-    "test:types": "tsc --noEmit && mocha -r ts-node/register test/types.test.ts"
+    "test:types": "tsc --noEmit && mocha -r ts-node/register test/types.test.ts",
+    "test:coverage": "export NODE_ENV=test && nyc mocha --recursive",
+    "test:types:coverage": "tsc --noEmit && export NODE_ENV=test && nyc mocha -r ts-node/register 'test/**/*.{js,ts}'",
+    "coverage": "export NODE_ENV=test && nyc mocha --recursive -r ts-node/register 'test/**/*.{js,ts}' && nyc check-coverage",
+    "prettier": "prettier --write .",
+    "prettier:check": "prettier --check .",
+    "prepare": "husky"
   },
   "keywords": [
-    "validate",
-    "data"
+    "express",
+    "nextjs",
+    "api-response",
+    "standardization",
+    "utility",
+    "request-context",
+    "tracing"
   ],
   "author": "CareCard team",
   "license": "ISC",
   "devDependencies": {
+    "@istanbuljs/nyc-config-typescript": "1.0.2",
     "@types/mocha": "10.0.10",
     "@types/node": "25.5.0",
-    "mocha": "11.7.5",
+    "express": "5.1.0",
+    "husky": "9.1.7",
+    "mocha": "^11.3.0",
+    "nyc": "17.1.0",
+    "prettier": "^3.8.1",
+    "source-map-support": "0.5.21",
     "supertest": "7.1.4",
     "ts-node": "10.9.2",
     "typescript": "5.9.3"
   },
-  "dependencies": {
-    "express": "5.1.0"
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
   }
 }

package/readme.md

@@ -1,7 +1,161 @@
-#Common Utility
-### Functions
+# @carecard/common-util
 
-Extract specific attributes from an object
-```js
-extractObjectWithProperties( obj, arrayOfProperties )
+Standardized API response system, request context middleware, and utility functions for Express.js and Next.js microservices.
+
+## Features
+
+- **Standardized Response Format**: Consistent JSON structure for all API responses.
+- **Request Context Middleware**: Automatic generation of `requestId` and `traceId`.
+- **Distributed Tracing Support**: Header-based trace propagation (`x-trace-id`).
+- **Type Safety**: Full TypeScript support with included type definitions.
+- **Next.js & Express Compatibility**: Works seamlessly across different Node.js frameworks.
+- **Microservice Ready**: Built-in metadata for service identification, environment, and versioning.
+
+## Installation
+
+```bash
+npm install @carecard/common-util
+```
+
+## Usage
+
+### Express.js
+
+#### Setup Middleware
+
+```javascript
+const express = require('express');
+const { requestContext } = require('@carecard/common-util');
+
+const app = express();
+
+// Attach request context (generates requestId, traceId, extracts client info)
+app.use(requestContext);
+```
+
+#### Sending Responses
+
+```javascript
+const { sendResponse } = require('@carecard/common-util');
+
+app.get('/api/users', (req, res) => {
+  const users = [{ id: 1, name: 'John Doe' }];
+
+  return sendResponse({
+    req,
+    res,
+    message: 'Users fetched successfully',
+    data: users,
+    meta: {
+      pagination: { page: 1, limit: 10, total: 1 }
+    }
+  });
+});
+```
+
+#### Standardized Error Handling
+
+```javascript
+const { error } = require('@carecard/common-util');
+const { appErrorHandler, notFound404, throwRecordNotFoundError } = error;
+
+const app = require('express')();
+
+// Usage in controllers
+app.get('/api/users/:id', (req, res) => {
+  const user = null;
+  if (!user) {
+    throwRecordNotFoundError({ userMessage: 'User not found' });
+  }
+});
+
+// Handle 404s
+app.use(notFound404);
+
+// Central error handler
+app.use(appErrorHandler);
 ```
+
+### Next.js (API Routes)
+
+#### JavaScript Example
+
+```javascript
+// pages/api/hello.js
+import { sendResponse } from '@carecard/common-util';
+
+export default function handler(req, res) {
+  return sendResponse({
+    req,
+    res,
+    message: 'Hello from Next.js!',
+    data: { greeting: 'Welcome' }
+  });
+}
+```
+
+#### TypeScript Example
+
+```typescript
+// pages/api/hello.ts
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { sendResponse } from '@carecard/common-util';
+
+export default function handler(req: NextApiRequest, res: NextApiResponse) {
+  return sendResponse({
+    req,
+    res,
+    message: 'Typed response',
+    data: { status: 'ok' }
+  });
+}
+```
+
+## API Reference
+
+### `sendResponse({ req, res, statusCode, success, message, data, error, meta })`
+
+Sends a standardized JSON response.
+
+### `requestContext(req, res, next)`
+
+Middleware that attaches:
+
+- `req.requestId`: UUID v4 unique to the request.
+- `req.traceId`: Propagated from `x-trace-id` header or newly generated.
+- `req.client`: Object containing `appId` (from `x-app-id`) and `ip`.
+
+### `createError({ code, message, details, fields })`
+
+Helper to create a standardized error object for `sendResponse`.
+
+## Standard Response Structure
+
+```json
+{
+  "success": true,
+  "statusCode": 200,
+  "message": "Success message",
+  "data": { ... },
+  "error": null,
+  "meta": {
+    "version": "1.0.0",
+    "service": "my-service",
+    "environment": "production",
+    "timestamp": "2024-03-26T00:00:00.000Z",
+    "requestId": "...",
+    "traceId": "...",
+    "client": { "appId": "...", "ip": "..." }
+  }
+}
+```
+
+## Environment Variables
+
+- `API_VERSION`: Used in `meta.version` (default: `1.0.0`)
+- `SERVICE_NAME`: Used in `meta.service` (default: `unknown-service`)
+- `NODE_ENV`: Used in `meta.environment` (default: `development`)
+
+## License
+
+ISC

package/src/index.js

@@ -0,0 +1,12 @@
+const requestContext = require('./middleware/requestContext');
+const sendResponse = require('./utils/sendResponse');
+const createError = require('./utils/createError');
+
+module.exports = {
+  util: require('./lib/utilityFunctions'),
+  error: require('./lib/appErrorHandlers'),
+  resCode: require('./lib/responseStatus'),
+  requestContext,
+  sendResponse,
+  createError
+};

package/src/lib/appErrorHandlers.js

@@ -0,0 +1,265 @@
+'use strict';
+
+const sendResponse = require('../utils/sendResponse');
+const createError = require('../utils/createError');
+
+/**
+ * These are application level error handlers. All error responses should be send using these functions.
+ * These should be use in app.js file, not in controller files.
+ */
+module.exports = {
+  throwAccountSuspendedError,
+  throwAccountBlockedError,
+  throwAccountInactiveError,
+  notFound404,
+  appErrorHandler,
+  throwValidationFailureError,
+  throwRecordExistError,
+  throwWrongCredentialsError,
+  throwLoginRequiredError,
+  throwRecordNotFoundError,
+  throwRecordNotSavedError,
+  throwUpdateFailedError,
+  throwTransactionFailedError,
+  throwUsedTokenError,
+  throwBadVisitorTokenError: throwVisitorTokenError,
+  throwFileFormatNotSupportedError,
+  throwNotAuthorizedError,
+  throwBadInputError,
+  throwInputNotUuidError,
+  throwFileTooLargeError,
+  throwInvalidTimeValueError
+};
+
+function notFound404(req, res, next) {
+  return sendResponse({
+    req,
+    res,
+    statusCode: 404,
+    success: false,
+    message: 'Not found',
+    error: createError({
+      code: 'NOT_FOUND',
+      message: 'Not found',
+      details: null
+    })
+  });
+}
+
+function appErrorHandler(err, req, res, next) {
+  let statusCode = 500;
+  const errorMessage = err?.message || 'Internal Server Error';
+
+  switch (err?.message) {
+    case 'Account_Suspended':
+    case 'Account_Blocked':
+    case 'Account_Inactive':
+      statusCode = 403;
+      break;
+
+    case 'Validation_Failure':
+    case 'Used_Token':
+    case 'Wrong_Credentials':
+    case 'Bad_Visitor_Token':
+    case 'Login_Required':
+    case 'Not_Authorized':
+      statusCode = 401;
+      break;
+
+    case 'Record_NotSaved':
+    case 'Update_Failed':
+    case 'Transaction_Failed':
+    case 'Bad_Input':
+    case 'Input_Not_Uuid':
+      statusCode = 400;
+      break;
+
+    case 'Record_Exist':
+      statusCode = 409;
+      break;
+
+    case 'Record_NotFound':
+      statusCode = 404;
+      break;
+
+    case 'File_Format_Not_Supported':
+      statusCode = 415;
+      break;
+
+    case 'File too large':
+      statusCode = 413;
+      break;
+
+    case 'Invalid time value':
+      statusCode = 403;
+      break;
+
+    default:
+      statusCode = 500;
+  }
+
+  return sendResponse({
+    req,
+    res,
+    statusCode,
+    success: false,
+    message: errorMessage,
+    error: createError({
+      code: err?.code ?? null,
+      message: err?.userMessage ?? null,
+      details: err?.details ?? null
+    })
+  });
+}
+
+function throwAccountSuspendedError(params = {}) {
+  const error = new Error('Account_Suspended');
+  error.code = 'ACCOUNT_SUSPENDED';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwAccountBlockedError(params = {}) {
+  const error = new Error('Account_Blocked');
+  error.code = 'ACCOUNT_BLOCKED';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwAccountInactiveError(params = {}) {
+  const error = new Error('Account_Inactive');
+  error.code = 'ACCOUNT_INACTIVE';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwValidationFailureError(params = {}) {
+  const error = new Error('Validation_Failure');
+  error.code = 'VALIDATION_FAILURE';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwWrongCredentialsError(params = {}) {
+  const error = new Error('Wrong_Credentials');
+  error.code = 'WRONG_CREDENTIALS';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwRecordExistError(params = {}) {
+  const error = new Error('Record_Exist');
+  error.code = 'RECORD_EXIST';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwRecordNotFoundError(params = {}) {
+  const error = new Error('Record_NotFound');
+  error.code = 'RECORD_NOT_FOUND';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwRecordNotSavedError(params = {}) {
+  const error = new Error('Record_NotSaved');
+  error.code = 'RECORD_NOT_SAVED';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwLoginRequiredError(params = {}) {
+  const error = new Error('Login_Required');
+  error.code = 'LOGIN_REQUIRED';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwUpdateFailedError(params = {}) {
+  const error = new Error('Update_Failed');
+  error.code = 'UPDATE_FAILED';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwTransactionFailedError(params = {}) {
+  const error = new Error('Transaction_Failed');
+  error.code = 'TRANSACTION_FAILED';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwUsedTokenError(params = {}) {
+  const error = new Error('Used_Token');
+  error.code = 'USED_TOKEN';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwVisitorTokenError(params = {}) {
+  const error = new Error('Bad_Visitor_Token');
+  error.code = 'BAD_VISITOR_TOKEN';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwFileFormatNotSupportedError(params = {}) {
+  const error = new Error('File_Format_Not_Supported');
+  error.code = 'FILE_FORMAT_NOT_SUPPORTED';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwNotAuthorizedError(params = {}) {
+  const error = new Error('Not_Authorized');
+  error.code = 'NOT_AUTHORIZED';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwBadInputError(params = {}) {
+  const error = new Error('Bad_Input');
+  error.code = 'BAD_INPUT';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwInputNotUuidError(params = {}) {
+  const error = new Error('Input_Not_Uuid');
+  error.code = 'INPUT_NOT_UUID';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwFileTooLargeError(params = {}) {
+  const error = new Error('File too large');
+  error.code = 'FILE_TOO_LARGE';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}
+
+function throwInvalidTimeValueError(params = {}) {
+  const error = new Error('Invalid time value');
+  error.code = 'INVALID_TIME_VALUE';
+  error.userMessage = params.userMessage ?? null;
+  error.details = params.details ?? null;
+  throw error;
+}

package/{lib → src/lib}/responseStatus.js

@@ -26,12 +26,11 @@
  * @param ETag
  * @returns {*}
  */
-function setOk200( res, ETag ) {
+function setOk200(res, ETag) {
+  res.set({ ETag: ETag });
+  res.status(200);
 
-    res.set( { ETag: ETag } );
-    res.status( 200 );
-
-    return res;
+  return res;
 }
 
 /**
@@ -50,9 +49,9 @@ function setOk200( res, ETag ) {
  * @param res
  * @returns {*}
  */
-function setCreated201( res ) {
-    res.status( 201 );
-    return res;
+function setCreated201(res) {
+  res.status(201);
+  return res;
 }
 
 /**
@@ -64,14 +63,13 @@ function setCreated201( res ) {
  * @param res
  * @returns {*}
  */
-function setBadRequest400ClientError( res ) {
-    res.status( 400 );
-    return res;
+function setBadRequest400ClientError(res) {
+  res.status(400);
+  return res;
 }
 
 module.exports = {
-    setOk200,
-    setCreated201,
-    setBadRequest400ClientError
+  setOk200,
+  setCreated201,
+  setBadRequest400ClientError
 };
-

package/src/lib/utilityFunctions.js

@@ -0,0 +1,20 @@
+// Create new object only with properties given in array.
+function extractObjectWithProperties(obj, arrayOfProperties) {
+  const returnObj = {};
+
+  if (!obj || !Array.isArray(arrayOfProperties)) {
+    return returnObj;
+  }
+
+  arrayOfProperties.forEach((nameOfProperty) => {
+    if (Object.prototype.hasOwnProperty.call(obj, nameOfProperty)) {
+      returnObj[nameOfProperty] = obj[nameOfProperty];
+    }
+  });
+
+  return returnObj;
+}
+
+module.exports = {
+  extractObjectWithProperties
+};

package/src/middleware/requestContext.js

@@ -0,0 +1,30 @@
+const { randomUUID } = require('node:crypto');
+
+/**
+ * Express middleware to generate and attach request context.
+ *
+ * Generates requestId (UUID v4)
+ * Reads traceId from header 'x-trace-id' OR generates one
+ * Reads appId from header 'x-app-id'
+ * Extracts client IP
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
+ */
+const requestContext = (req, res, next) => {
+  req.requestId = randomUUID();
+  req.traceId = req.headers['x-trace-id'] || randomUUID();
+
+  const appId = req.headers['x-app-id'];
+  const ip = req.ip || req.headers['x-forwarded-for'] || req.socket.remoteAddress;
+
+  req.client = {
+    appId,
+    ip
+  };
+
+  next();
+};
+
+module.exports = requestContext;

package/src/types/response.types.ts

@@ -0,0 +1,67 @@
+/**
+ * Standard API response metadata.
+ */
+export interface ApiResponseMeta {
+  version: string;
+  service: string;
+  environment: string;
+  timestamp: string;
+  requestId: string;
+  traceId: string;
+  client?: {
+    appId?: string;
+    ip?: string;
+  };
+  pagination?: {
+    page: number;
+    limit: number;
+    total: number;
+  };
+  [key: string]: any;
+}
+
+/**
+ * Standard API error object.
+ */
+export interface ApiError {
+  code: string;
+  message?: string;
+  details?: string;
+  fields?: Record<string, string>;
+}
+
+/**
+ * Standard API response body.
+ */
+export interface ApiResponse<T = any> {
+  success: boolean;
+  statusCode: number;
+  message: string;
+  data: T | null;
+  error: ApiError | null;
+  meta: ApiResponseMeta;
+}
+
+/**
+ * Parameters for sendResponse utility.
+ */
+export interface SendResponseParams<T = any> {
+  req: any;
+  res: any;
+  statusCode?: number;
+  success?: boolean;
+  message?: string;
+  data?: T | null;
+  error?: ApiError | null;
+  meta?: Partial<ApiResponseMeta>;
+}
+
+/**
+ * Parameters for createError utility.
+ */
+export interface CreateErrorParams {
+  code: string;
+  details?: string;
+  message?: string;
+  fields?: Record<string, string>;
+}

package/src/utils/createError.js

@@ -0,0 +1,20 @@
+/**
+ * Helper for standardized errors.
+ *
+ * @param {Object} params
+ * @param {string} params.code
+ * @param {string} [params.details]
+ * @param {string} [params.message]
+ * @param {Record<string, string>} [params.fields]
+ * @returns {Object} Standardized error object
+ */
+const createError = ({ code, details, message, fields }) => {
+  return {
+    code,
+    details,
+    message,
+    fields
+  };
+};
+
+module.exports = createError;

package/src/utils/sendResponse.js

@@ -0,0 +1,65 @@
+/**
+ * Standardized API response utility.
+ *
+ * Automatically injects:
+ * - version (from env: API_VERSION)
+ * - service (from env: SERVICE_NAME)
+ * - environment (NODE_ENV)
+ * - timestamp
+ * - requestId
+ * - traceId
+ * - client info
+ *
+ * @param {Object} params
+ * @param {import('express').Request} params.req
+ * @param {import('express').Response} params.res
+ * @param {number} [params.statusCode=200]
+ * @param {boolean} [params.success=true]
+ * @param {string} [params.message='']
+ * @param {any} [params.data=null]
+ * @param {Object} [params.error=null]
+ * @param {Object} [params.meta={}]
+ */
+const sendResponse = ({
+  req,
+  res,
+  statusCode = 200,
+  success = true,
+  message = '',
+  data = null,
+  error = null,
+  meta = {}
+}) => {
+  const standardMeta = {
+    version: process.env.API_VERSION || '1.0.0',
+    service: process.env.SERVICE_NAME || 'unknown-service',
+    environment: process.env.NODE_ENV || 'development',
+    timestamp: new Date().toISOString(),
+    requestId: req.requestId || '',
+    traceId: req.traceId || '',
+    client:
+      req.client && typeof req.client === 'object' && req.client.constructor === Object
+        ? req.client
+        : {}
+  };
+
+  if (statusCode === 204) {
+    return res.status(204).send();
+  }
+
+  const response = {
+    success,
+    statusCode,
+    message,
+    data,
+    error,
+    meta: {
+      ...standardMeta,
+      ...meta
+    }
+  };
+
+  return res.status(statusCode).json(response);
+};
+
+module.exports = sendResponse;

package/lib/appErrorHandlers.js

@@ -1,297 +0,0 @@
-'use strict';
-/**
- * These are application level error handlers. All error responses should be send using these functions.
- * These should be use in app.js file, not in controller files.
- */
-module.exports = {
-    throwAccountSuspendedError,
-    throwAccountBlockedError,
-    throwAccountInactiveError,
-    notFound404,
-    appErrorHandler,
-    throwValidationFailureError,
-    throwRecordExistError,
-    throwWrongCredentialsError,
-    throwLoginRequiredError,
-    throwRecordNotFoundError,
-    throwRecordNotSavedError,
-    throwUpdateFailedError,
-    throwTransactionFailedError,
-    throwUsedTokenError,
-    throwBadVisitorTokenError: throwVisitorTokenError,
-    throwFileFormatNotSupportedError,
-    throwNotAuthorizedError,
-    throwBadInputError,
-    throwInputNotUuidError,
-    throwFileTooLargeError,
-    throwInvalidTimeValueError
-}
-
-
-function notFound404(req, res, next) {
-    res.status(404);
-    const response = {
-        error:
-            {
-                code: 'NOT_FOUND',
-                message: 'Not found',
-                details: null
-            }
-    }
-
-    res.send(response)
-}
-
-function appErrorHandler(err, req, res, next) {
-    const response =
-        {
-            error:
-                {
-                    code: err.code ?? null,
-                    message: err.userMessage ?? null,
-                    details: err.details ?? null
-                }
-        };
-
-    switch (err?.message) {
-
-        case "Account_Suspended":
-        case "Account_Blocked":
-        case "Account_Inactive":
-            res.status(403);
-            res.send(response)
-            break;
-
-        case "Validation_Failure":
-            res.status(401);
-            res.send(response)
-            break;
-
-        case "Used_Token":
-        case "Wrong_Credentials":
-            res.status(401);
-            res.send(response)
-            break;
-
-        case "Bad_Visitor_Token":
-            res.status(401);
-            res.send(response)
-            break;
-
-        case "Record_NotSaved":
-            res.status(400);
-            res.send(response)
-            break;
-
-        case "Record_Exist":
-            res.status(409);
-            res.send(response)
-            break;
-
-        case "Record_NotFound":
-            res.status(404);
-            res.send(response)
-            break;
-
-        case "Update_Failed":
-            res.status(400);
-            res.send(response)
-            break;
-
-        case "Login_Required":
-            res.status(401);
-            res.send(response)
-            break;
-
-        case "Transaction_Failed":
-            res.status(400);
-            res.send(response)
-            break;
-
-        case "File_Format_Not_Supported":
-            res.status(415);
-            res.send(response)
-            break;
-
-        case "Not_Authorized":
-            res.status(401);
-            res.send(response)
-            break;
-
-        case "Bad_Input":
-            res.status(400);
-            res.send(response);
-            break;
-
-        case  "Input_Not_Uuid" :
-            res.status(400);
-            res.send(response)
-            break;
-
-        case "File too large":
-            res.status(413);
-            res.send(response)
-            break;
-
-        case "Invalid time value":
-            res.status(403);
-            res.send(response)
-            break;
-
-        default:
-            res.status(500);
-            res.send(response)
-    }
-}
-
-function throwAccountSuspendedError(params = {}) {
-    const error = new Error("Account_Suspended");
-    error.code = "ACCOUNT_SUSPENDED";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwAccountBlockedError(params = {}) {
-    const error = new Error("Account_Blocked");
-    error.code = "ACCOUNT_BLOCKED";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwAccountInactiveError(params = {}) {
-    const error = new Error("Account_Inactive");
-    error.code = "ACCOUNT_INACTIVE";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwValidationFailureError(params = {}) {
-    const error = new Error("Validation_Failure");
-    error.code = "VALIDATION_FAILURE";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwWrongCredentialsError(params = {}) {
-    const error = new Error("Wrong_Credentials");
-    error.code = "WRONG_CREDENTIALS";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwRecordExistError(params = {}) {
-    const error = new Error("Record_Exist");
-    error.code = "RECORD_EXIST";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwRecordNotFoundError(params = {}) {
-    const error = new Error("Record_NotFound");
-    error.code = "RECORD_NOT_FOUND";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwRecordNotSavedError(params = {}) {
-    const error = new Error("Record_NotSaved");
-    error.code = "RECORD_NOT_SAVED";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwLoginRequiredError(params = {}) {
-    const error = new Error("Login_Required");
-    error.code = "LOGIN_REQUIRED";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwUpdateFailedError(params = {}) {
-    const error = new Error("Update_Failed");
-    error.code = "UPDATE_FAILED";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwTransactionFailedError(params = {}) {
-    const error = new Error("Transaction_Failed");
-    error.code = "TRANSACTION_FAILED";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwUsedTokenError(params = {}) {
-    const error = new Error("Used_Token");
-    error.code = "USED_TOKEN";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwVisitorTokenError(params = {}) {
-    const error = new Error("Bad_Visitor_Token");
-    error.code = "BAD_VISITOR_TOKEN";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwFileFormatNotSupportedError(params = {}) {
-    const error = new Error("File_Format_Not_Supported");
-    error.code = "FILE_FORMAT_NOT_SUPPORTED";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwNotAuthorizedError(params = {}) {
-    const error = new Error("Not_Authorized");
-    error.code = "NOT_AUTHORIZED";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwBadInputError(params = {}) {
-    const error = new Error("Bad_Input");
-    error.code = "BAD_INPUT";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwInputNotUuidError(params = {}) {
-    const error = new Error("Input_Not_Uuid");
-    error.code = "INPUT_NOT_UUID";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwFileTooLargeError(params = {}) {
-    const error = new Error("File too large");
-    error.code = "FILE_TOO_LARGE";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}
-
-function throwInvalidTimeValueError(params = {}) {
-    const error = new Error("Invalid time value");
-    error.code = "INVALID_TIME_VALUE";
-    error.userMessage = params.userMessage ?? null;
-    error.details = params.details ?? null;
-    throw error;
-}

package/lib/untilityFunctions.js

@@ -1,18 +0,0 @@
-// Create new object only with properties given in array.
-function extractObjectWithProperties( obj, arrayOfProperties ) {
-    let returnObj = {};
-
-    arrayOfProperties.forEach( nameOfProperty => {
-        if ( obj?.[ nameOfProperty ] ) {
-            returnObj[ nameOfProperty ] = obj?.[ nameOfProperty ];
-        }
-    } );
-
-    return returnObj;
-}
-
-
-
-module.exports = {
-    extractObjectWithProperties
-};