@onlineapps/service-common 1.0.15 → 1.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-common",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "description": "Common utilities for both infrastructure services and business services",
   "main": "src/index.js",
   "scripts": {

package/src/errors/BusinessError.js

@@ -0,0 +1,117 @@
+'use strict';
+
+const ERROR_TYPES = {
+  TRANSIENT: 'TRANSIENT',
+  BUSINESS: 'BUSINESS',
+  FATAL: 'FATAL',
+  VALIDATION: 'VALIDATION',
+  TIMEOUT: 'TIMEOUT',
+  RATE_LIMIT: 'RATE_LIMIT',
+  UNKNOWN: 'UNKNOWN'
+};
+
+class BusinessError extends Error {
+  constructor(message, { statusCode = 500, errorCode = 'INTERNAL_ERROR', type = 'BUSINESS', details = [], operation = null, service = null } = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.statusCode = statusCode;
+    this.errorCode = errorCode;
+    this.type = type;
+    this.details = Array.isArray(details) ? details : [details];
+    this.operation = operation || null;
+    this.service = service || process.env.SERVICE_NAME || null;
+  }
+
+  toJSON() {
+    return {
+      code: this.errorCode,
+      message: this.message,
+      statusCode: this.statusCode,
+      details: this.details.length > 0 ? this.details : undefined,
+      service: this.service || undefined,
+      operation: this.operation || undefined
+    };
+  }
+}
+
+class NotFoundError extends BusinessError {
+  constructor(message, options = {}) {
+    super(message, {
+      statusCode: 404,
+      errorCode: options.errorCode || 'RESOURCE_NOT_FOUND',
+      type: ERROR_TYPES.BUSINESS,
+      ...options
+    });
+  }
+}
+
+class ValidationError extends BusinessError {
+  constructor(message, options = {}) {
+    super(message, {
+      statusCode: 400,
+      errorCode: options.errorCode || 'VALIDATION_FAILED',
+      type: ERROR_TYPES.VALIDATION,
+      ...options
+    });
+  }
+}
+
+class ConflictError extends BusinessError {
+  constructor(message, options = {}) {
+    super(message, {
+      statusCode: 409,
+      errorCode: options.errorCode || 'DUPLICATE_RESOURCE',
+      type: ERROR_TYPES.BUSINESS,
+      ...options
+    });
+  }
+}
+
+class BusinessRuleError extends BusinessError {
+  constructor(message, options = {}) {
+    super(message, {
+      statusCode: 422,
+      errorCode: options.errorCode || 'BUSINESS_RULE_VIOLATED',
+      type: ERROR_TYPES.VALIDATION,
+      ...options
+    });
+  }
+}
+
+class AuthorizationError extends BusinessError {
+  constructor(message, options = {}) {
+    super(message, {
+      statusCode: 403,
+      errorCode: options.errorCode || 'FORBIDDEN',
+      type: ERROR_TYPES.BUSINESS,
+      ...options
+    });
+  }
+}
+
+class ServiceUnavailableError extends BusinessError {
+  constructor(message, options = {}) {
+    super(message, {
+      statusCode: 503,
+      errorCode: options.errorCode || 'SERVICE_UNAVAILABLE',
+      type: ERROR_TYPES.TRANSIENT,
+      ...options
+    });
+  }
+}
+
+function isBusinessError(error) {
+  return error instanceof BusinessError;
+}
+
+module.exports = {
+  BusinessError,
+  NotFoundError,
+  ValidationError,
+  ConflictError,
+  BusinessRuleError,
+  AuthorizationError,
+  ServiceUnavailableError,
+  isBusinessError,
+  ERROR_TYPES
+};

package/src/errors/errorMiddleware.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const { BusinessError, isBusinessError } = require('./BusinessError');
+
+function businessErrorHandler(err, req, res, next) {
+  if (res.headersSent) {
+    return next(err);
+  }
+
+  const logger = req.app?.locals?.logger || console;
+
+  if (isBusinessError(err)) {
+    logger.warn(`[BusinessError] ${err.errorCode}: ${err.message}`, {
+      statusCode: err.statusCode,
+      errorCode: err.errorCode,
+      type: err.type,
+      details: err.details,
+      service: err.service,
+      operation: err.operation,
+      method: req.method,
+      url: req.originalUrl
+    });
+
+    return res.status(err.statusCode).json({
+      error: err.toJSON()
+    });
+  }
+
+  if (err.name === 'SequelizeUniqueConstraintError') {
+    const fields = err.errors?.map(e => e.path) || [];
+    logger.warn(`[BusinessError] DUPLICATE_RESOURCE: ${err.message}`, {
+      statusCode: 409,
+      fields,
+      method: req.method,
+      url: req.originalUrl
+    });
+
+    return res.status(409).json({
+      error: {
+        code: 'DUPLICATE_RESOURCE',
+        message: 'Resource already exists',
+        statusCode: 409,
+        details: fields.length > 0 ? [`Duplicate value for: ${fields.join(', ')}`] : undefined
+      }
+    });
+  }
+
+  if (err.name === 'SequelizeValidationError') {
+    const details = err.errors?.map(e => e.message) || [];
+    logger.warn(`[BusinessError] VALIDATION_FAILED: ${err.message}`, {
+      statusCode: 400,
+      details,
+      method: req.method,
+      url: req.originalUrl
+    });
+
+    return res.status(400).json({
+      error: {
+        code: 'VALIDATION_FAILED',
+        message: 'Validation failed',
+        statusCode: 400,
+        details
+      }
+    });
+  }
+
+  if (err.type === 'entity.parse.failed' || (err.message && err.message.includes('JSON'))) {
+    return res.status(400).json({
+      error: {
+        code: 'INVALID_JSON',
+        message: 'Invalid JSON in request body',
+        statusCode: 400
+      }
+    });
+  }
+
+  logger.error(`[UnhandledError] ${err.message}`, {
+    error: err.message,
+    stack: err.stack,
+    method: req.method,
+    url: req.originalUrl
+  });
+
+  const isProduction = process.env.NODE_ENV === 'production';
+
+  return res.status(500).json({
+    error: {
+      code: 'INTERNAL_ERROR',
+      message: isProduction ? 'Internal server error' : err.message,
+      statusCode: 500
+    }
+  });
+}
+
+function notFoundHandler(req, res) {
+  const logger = req.app?.locals?.logger || console;
+  logger.warn('Route not found', {
+    method: req.method,
+    url: req.originalUrl
+  });
+
+  res.status(404).json({
+    error: {
+      code: 'ROUTE_NOT_FOUND',
+      message: `Route ${req.method} ${req.originalUrl} not found`,
+      statusCode: 404
+    }
+  });
+}
+
+module.exports = { businessErrorHandler, notFoundHandler };

package/src/errors/index.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const {
+  BusinessError,
+  NotFoundError,
+  ValidationError,
+  ConflictError,
+  BusinessRuleError,
+  AuthorizationError,
+  ServiceUnavailableError,
+  isBusinessError,
+  ERROR_TYPES
+} = require('./BusinessError');
+
+const { businessErrorHandler, notFoundHandler } = require('./errorMiddleware');
+
+module.exports = {
+  BusinessError,
+  NotFoundError,
+  ValidationError,
+  ConflictError,
+  BusinessRuleError,
+  AuthorizationError,
+  ServiceUnavailableError,
+  isBusinessError,
+  ERROR_TYPES,
+  businessErrorHandler,
+  notFoundHandler
+};

package/src/index.js

@@ -30,6 +30,19 @@ const {
   getCriticalConfigWithFallbacks,
   getInfrastructureHealthConfig
 } = require('./runtime-config');
+const {
+  BusinessError,
+  NotFoundError,
+  ValidationError,
+  ConflictError,
+  BusinessRuleError,
+  AuthorizationError,
+  ServiceUnavailableError,
+  isBusinessError,
+  ERROR_TYPES,
+  businessErrorHandler,
+  notFoundHandler
+} = require('./errors');
 
 module.exports = {
   // Infrastructure readiness utilities (used by both infrastructure and business services)
@@ -55,7 +68,20 @@ module.exports = {
   getInfrastructureHealthConfig,
 
   // Reporting utilities
-  sendMonitoringFailFallbackEmail
+  sendMonitoringFailFallbackEmail,
+
+  // Business error classes and middleware
+  BusinessError,
+  NotFoundError,
+  ValidationError,
+  ConflictError,
+  BusinessRuleError,
+  AuthorizationError,
+  ServiceUnavailableError,
+  isBusinessError,
+  ERROR_TYPES,
+  businessErrorHandler,
+  notFoundHandler
 };
 
 

package/tests/unit/BusinessError.test.js

@@ -0,0 +1,171 @@
+'use strict';
+
+const {
+  BusinessError,
+  NotFoundError,
+  ValidationError,
+  ConflictError,
+  BusinessRuleError,
+  AuthorizationError,
+  ServiceUnavailableError,
+  isBusinessError,
+  businessErrorHandler,
+  notFoundHandler
+} = require('../../src/errors');
+
+describe('BusinessError hierarchy', () => {
+  test('BusinessError has correct defaults', () => {
+    const err = new BusinessError('Something went wrong');
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(BusinessError);
+    expect(err.name).toBe('BusinessError');
+    expect(err.message).toBe('Something went wrong');
+    expect(err.statusCode).toBe(500);
+    expect(err.errorCode).toBe('INTERNAL_ERROR');
+    expect(err.type).toBe('BUSINESS');
+    expect(err.details).toEqual([]);
+  });
+
+  test('NotFoundError sets 404', () => {
+    const err = new NotFoundError('Document not found', {
+      details: ['UUID abc123 does not exist'],
+      operation: 'getDocument'
+    });
+    expect(err).toBeInstanceOf(BusinessError);
+    expect(err.statusCode).toBe(404);
+    expect(err.errorCode).toBe('RESOURCE_NOT_FOUND');
+    expect(err.type).toBe('BUSINESS');
+    expect(err.details).toEqual(['UUID abc123 does not exist']);
+    expect(err.operation).toBe('getDocument');
+  });
+
+  test('ValidationError sets 400', () => {
+    const err = new ValidationError('Invalid input', { details: ['field X is required'] });
+    expect(err.statusCode).toBe(400);
+    expect(err.errorCode).toBe('VALIDATION_FAILED');
+    expect(err.type).toBe('VALIDATION');
+  });
+
+  test('ConflictError sets 409', () => {
+    const err = new ConflictError('Duplicate');
+    expect(err.statusCode).toBe(409);
+    expect(err.errorCode).toBe('DUPLICATE_RESOURCE');
+  });
+
+  test('BusinessRuleError sets 422', () => {
+    const err = new BusinessRuleError('Cannot invoice draft');
+    expect(err.statusCode).toBe(422);
+    expect(err.errorCode).toBe('BUSINESS_RULE_VIOLATED');
+    expect(err.type).toBe('VALIDATION');
+  });
+
+  test('AuthorizationError sets 403', () => {
+    const err = new AuthorizationError('No access');
+    expect(err.statusCode).toBe(403);
+    expect(err.errorCode).toBe('FORBIDDEN');
+  });
+
+  test('ServiceUnavailableError sets 503', () => {
+    const err = new ServiceUnavailableError('DB down');
+    expect(err.statusCode).toBe(503);
+    expect(err.errorCode).toBe('SERVICE_UNAVAILABLE');
+    expect(err.type).toBe('TRANSIENT');
+  });
+
+  test('isBusinessError returns true for BusinessError subtypes', () => {
+    expect(isBusinessError(new NotFoundError('x'))).toBe(true);
+    expect(isBusinessError(new Error('x'))).toBe(false);
+    expect(isBusinessError(null)).toBe(false);
+  });
+
+  test('toJSON returns structured error', () => {
+    const err = new NotFoundError('Not found', {
+      details: ['detail1'],
+      operation: 'findDoc',
+      service: 'invoicing'
+    });
+    const json = err.toJSON();
+    expect(json).toEqual({
+      code: 'RESOURCE_NOT_FOUND',
+      message: 'Not found',
+      statusCode: 404,
+      details: ['detail1'],
+      service: 'invoicing',
+      operation: 'findDoc'
+    });
+  });
+
+  test('custom errorCode can be overridden', () => {
+    const err = new NotFoundError('Tenant missing', { errorCode: 'TENANT_NOT_FOUND' });
+    expect(err.errorCode).toBe('TENANT_NOT_FOUND');
+  });
+});
+
+describe('businessErrorHandler middleware', () => {
+  let req, res, next;
+
+  beforeEach(() => {
+    req = { method: 'GET', originalUrl: '/api/test', app: { locals: { logger: { warn: jest.fn(), error: jest.fn() } } } };
+    res = { status: jest.fn().mockReturnThis(), json: jest.fn().mockReturnThis(), headersSent: false };
+    next = jest.fn();
+  });
+
+  test('formats BusinessError as structured JSON', () => {
+    const err = new NotFoundError('Doc not found', { details: ['UUID 123'] });
+    businessErrorHandler(err, req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(404);
+    expect(res.json).toHaveBeenCalledWith({
+      error: {
+        code: 'RESOURCE_NOT_FOUND',
+        message: 'Doc not found',
+        statusCode: 404,
+        details: ['UUID 123'],
+        service: undefined,
+        operation: undefined
+      }
+    });
+  });
+
+  test('wraps generic Error as INTERNAL_ERROR 500', () => {
+    const err = new Error('kaboom');
+    businessErrorHandler(err, req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(500);
+    const body = res.json.mock.calls[0][0];
+    expect(body.error.code).toBe('INTERNAL_ERROR');
+    expect(body.error.statusCode).toBe(500);
+  });
+
+  test('does not leak stack in production', () => {
+    const origEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = 'production';
+
+    const err = new Error('secret details');
+    businessErrorHandler(err, req, res, next);
+
+    const body = res.json.mock.calls[0][0];
+    expect(body.error.message).toBe('Internal server error');
+
+    process.env.NODE_ENV = origEnv;
+  });
+
+  test('calls next() if headers already sent', () => {
+    res.headersSent = true;
+    const err = new Error('late');
+    businessErrorHandler(err, req, res, next);
+    expect(next).toHaveBeenCalledWith(err);
+    expect(res.status).not.toHaveBeenCalled();
+  });
+});
+
+describe('notFoundHandler middleware', () => {
+  test('returns ROUTE_NOT_FOUND 404', () => {
+    const req = { method: 'GET', originalUrl: '/unknown', app: { locals: { logger: { warn: jest.fn() } } } };
+    const res = { status: jest.fn().mockReturnThis(), json: jest.fn().mockReturnThis() };
+    notFoundHandler(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(404);
+    expect(res.json.mock.calls[0][0].error.code).toBe('ROUTE_NOT_FOUND');
+  });
+});