@flusys/nestjs-shared 1.1.0 → 1.2.0-rc.1

package/fesm/classes/winston.logger.class.js

@@ -16,9 +16,9 @@ import { existsSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { createLogger, format, transports } from 'winston';
 // Handle both webpack (no default export) and esbuild (default export)
+import * as DailyRotateFileModule from 'winston-daily-rotate-file';
 import * as TransportModule from 'winston-transport';
 const Transport = TransportModule.default || TransportModule;
-import * as DailyRotateFileModule from 'winston-daily-rotate-file';
 const DailyRotateFile = DailyRotateFileModule.default || DailyRotateFileModule;
 // Configuration
 const logConfig = envConfig.getLogConfig();
@@ -35,33 +35,48 @@ if (!existsSync(LOG_DIR)) {
 }
 // Custom Formats
 /**
- * Custom format for structured logging
- * Includes: timestamp, level, context, requestId, userId, message, metadata
- */ const structuredFormat = format.printf(({ timestamp, level, message, context, requestId, userId, stack, ...metadata })=>{
-    const logEntry = {
-        timestamp,
-        level: level.toUpperCase(),
-        context: context || 'App',
-        message
-    };
-    if (requestId) logEntry.requestId = requestId;
-    if (userId) logEntry.userId = userId;
-    if (Object.keys(metadata).length > 0) logEntry.metadata = metadata;
-    if (stack) logEntry.stack = stack;
-    return JSON.stringify(logEntry);
-});
-/**
- * Custom format for development console output
- * Human-readable format with colors
- */ const devConsoleFormat = format.printf(({ timestamp, level, message, context, requestId, userId, method, url, path, statusCode, duration, stack })=>{
-    const ctx = context || 'App';
-    const reqId = requestId ? ` [${requestId}]` : '';
-    const user = userId ? ` (user:${userId})` : '';
-    const endpoint = method && (path || url) ? ` [${method} ${path || url}]` : '';
-    const status = statusCode ? ` [${statusCode}]` : '';
-    const time = duration ? ` (${duration})` : '';
-    const stackTrace = stack ? `\n${stack}` : '';
-    return `${timestamp} [${level.toUpperCase().padEnd(7)}] [${ctx}]${endpoint}${status}${time}${reqId}${user} ${message}${stackTrace}`;
+ * Custom format for structured logging (production)
+ * Multi-line format:
+ * - Line 1: Timestamp
+ * - Line 2: Log Level
+ * - Line 3: [RequestId]
+ * - Line 4: Empty
+ * - Line 5+: Message with context
+ */ const LEVEL_MAP = {
+    error: 'Error',
+    warn: 'Warning',
+    info: 'Information',
+    debug: 'Debug',
+    verbose: 'Verbose'
+};
+const LOG_SEPARATOR = '─'.repeat(80);
+const structuredFormat = format.printf(({ timestamp, level, message, context, requestId, userId, tenantId, companyId, method, url, path, statusCode, duration, stack, ...metadata })=>{
+    const reqId = requestId || 'no-request-id';
+    const levelFormatted = LEVEL_MAP[level] || level.charAt(0).toUpperCase() + level.slice(1);
+    const contextParts = [];
+    if (context) contextParts.push(`Context: ${context}`);
+    if (method && (path || url)) contextParts.push(`Endpoint: ${method} ${path || url}`);
+    if (statusCode) contextParts.push(`Status: ${statusCode}`);
+    if (duration) contextParts.push(`Duration: ${duration}`);
+    if (userId) contextParts.push(`UserId: ${userId}`);
+    if (tenantId) contextParts.push(`TenantId: ${tenantId}`);
+    if (companyId) contextParts.push(`CompanyId: ${companyId}`);
+    let content = message;
+    if (contextParts.length > 0) {
+        content = `${contextParts.join(' | ')}\n${message}`;
+    }
+    const metaKeys = Object.keys(metadata).filter((k)=>k !== 'splat');
+    if (metaKeys.length > 0) {
+        const metaStr = JSON.stringify(metaKeys.reduce((acc, k)=>({
+                ...acc,
+                [k]: metadata[k]
+            }), {}));
+        content += `\nMetadata: ${metaStr}`;
+    }
+    if (stack) {
+        content += `\nStack: ${stack}`;
+    }
+    return `${LOG_SEPARATOR}\n${timestamp} | ${levelFormatted} | [${reqId}]\n${content}`;
 });
 // Transports
 /**
@@ -84,63 +99,44 @@ if (!existsSync(LOG_DIR)) {
     maxFiles: LOG_MAX_FILES,
     level: 'error'
 });
-// Tenant-Aware Transport
-/**
- * Cache for tenant-specific transports
- * Avoids creating new transport instances for each log entry
- */ const tenantTransportCache = new Map();
-/**
- * Get or create a tenant-specific transport
- * Creates logs in: logs/{tenantId}/combined-YYYY-MM-DD.log
- */ function getTenantTransport(tenantId) {
-    if (tenantTransportCache.has(tenantId)) {
-        return tenantTransportCache.get(tenantId);
-    }
-    const tenantLogDir = join(LOG_DIR, tenantId);
-    if (!existsSync(tenantLogDir)) {
-        mkdirSync(tenantLogDir, {
+// Transport Caches
+const moduleTransportCache = new Map();
+const tenantTransportCache = new Map();
+function getCachedTransport(cache, name) {
+    const cached = cache.get(name);
+    if (cached) return cached;
+    const logDir = join(LOG_DIR, name);
+    if (!existsSync(logDir)) {
+        mkdirSync(logDir, {
             recursive: true
         });
     }
     const transport = new DailyRotateFile({
-        filename: `${tenantLogDir}/combined-%DATE%.log`,
+        filename: `${logDir}/combined-%DATE%.log`,
         datePattern: 'YYYY-MM-DD',
         zippedArchive: true,
         maxSize: LOG_MAX_SIZE,
         maxFiles: LOG_MAX_FILES,
         level: LOG_LEVEL
     });
-    tenantTransportCache.set(tenantId, transport);
+    cache.set(name, transport);
     return transport;
 }
-/**
- * Tenant-aware transport wrapper
- * Routes logs to tenant-specific folders when tenantId is present
- */ let TenantAwareTransport = class TenantAwareTransport extends Transport {
+const getModuleTransport = (name)=>getCachedTransport(moduleTransportCache, name);
+const getTenantTransport = (name)=>getCachedTransport(tenantTransportCache, name);
+let TenantAwareTransport = class TenantAwareTransport extends Transport {
     log(info, callback) {
         setImmediate(()=>this.emit('logged', info));
         const tenantId = info.tenantId || info.metadata?.tenantId;
-        if (USE_TENANT_MODE && tenantId) {
-            // Write to tenant-specific folder
-            const tenantTransport = getTenantTransport(tenantId);
-            tenantTransport.log(info, callback);
-        } else {
-            // Write to default log folder
-            this.defaultTransport.log(info, callback);
-        }
+        const transport = USE_TENANT_MODE && tenantId ? getTenantTransport(tenantId) : this.defaultTransport;
+        transport.log(info, callback);
     }
     constructor(defaultTransport){
-        super(), _define_property(this, "defaultTransport", void 0);
-        this.defaultTransport = defaultTransport;
+        super(), _define_property(this, "defaultTransport", void 0), this.defaultTransport = defaultTransport;
     }
 };
-/**
- * Tenant-aware combined transport
- * When USE_TENANT_MODE=true, routes to tenant folders (like database mode)
- */ const tenantAwareCombinedTransport = new TenantAwareTransport(combinedRotateTransport);
-/**
- * Console transport for development
- */ const consoleTransport = new transports.Console({
+const tenantAwareCombinedTransport = new TenantAwareTransport(combinedRotateTransport);
+const consoleTransport = new transports.Console({
     level: LOG_LEVEL,
     format: format.combine(format.colorize({
         all: true
@@ -148,7 +144,7 @@ if (!existsSync(LOG_DIR)) {
         format: 'YYYY-MM-DD HH:mm:ss'
     }), format.errors({
         stack: true
-    }), devConsoleFormat)
+    }), structuredFormat)
 });
 // Logger Instances
 /**
@@ -190,7 +186,43 @@ if (!existsSync(LOG_DIR)) {
 });
 // Exports
 /**
- * Winston logger instance
+ * Winston logger instance (global)
  * - DEV: Console output with colors
  * - PROD: File-based with daily rotation, tenant-aware routing
  */ export const instance = envConfig.isProduction() ? prodLogger : devLogger;
+/**
+ * Module logger cache to avoid creating multiple loggers for the same module
+ */ const moduleLoggerCache = new Map();
+/**
+ * Create a module-specific logger instance
+ * - DEV: Console output (same as global)
+ * - PROD: File-based with module-specific folder + shared error log
+ *
+ * @param moduleName - The module name (e.g., 'auth', 'iam', 'storage')
+ * @returns Logger instance for the module
+ */ export function createModuleLogger(moduleName) {
+    // In dev mode, use global console logger
+    if (!envConfig.isProduction()) {
+        return devLogger;
+    }
+    // Check cache first
+    if (moduleLoggerCache.has(moduleName)) {
+        return moduleLoggerCache.get(moduleName);
+    }
+    // Create module-specific logger for production
+    const moduleLogger = createLogger({
+        level: LOG_LEVEL,
+        format: format.combine(format.timestamp({
+            format: 'YYYY-MM-DD HH:mm:ss.SSS'
+        }), format.errors({
+            stack: true
+        }), structuredFormat),
+        transports: [
+            getModuleTransport(moduleName),
+            errorRotateTransport
+        ],
+        exitOnError: false
+    });
+    moduleLoggerCache.set(moduleName, moduleLogger);
+    return moduleLogger;
+}

package/fesm/constants/index.js

@@ -4,7 +4,6 @@ export const PERMISSIONS_KEY = 'permissions';
 // Injection tokens
 export const CACHE_INSTANCE = 'CACHE_INSTANCE';
 export const PERMISSION_GUARD_CONFIG = 'PERMISSION_GUARD_CONFIG';
-export const LOGGER_INSTANCE = 'LOGGER_INSTANCE';
 // Header names
 export const IDEMPOTENCY_KEY_HEADER = 'x-idempotency-key';
 export const REQUEST_ID_HEADER = 'x-request-id';
@@ -14,3 +13,5 @@ export const PERMISSIONS_CACHE_PREFIX = 'permissions';
 export const IDEMPOTENCY_CACHE_PREFIX = 'idempotency';
 // Permission codes
 export * from './permissions';
+// Message keys for localization
+export * from './message-keys';

package/fesm/constants/message-keys.js

@@ -0,0 +1,49 @@
+// ==================== AUTH (Shared across guards/interceptors) ====================
+// These are duplicated in nestjs-auth but needed here to avoid circular dependencies
+export const AUTH_MESSAGES = {
+    TOKEN_REQUIRED: 'auth.token.required',
+    TOKEN_INVALID: 'auth.token.invalid',
+    ENTITY_BELOG_ANOTHER_COMPANY: 'entity.belongs.another.company',
+    COMPANY_NO_ACCESS: 'auth.company.no.access'
+};
+// ==================== ERROR (HTTP Exceptions) ====================
+export const ERROR_MESSAGES = {
+    NOT_FOUND: 'error.not.found',
+    VALIDATION: 'error.validation',
+    UNAUTHORIZED: 'error.unauthorized',
+    FORBIDDEN: 'error.forbidden',
+    CONFLICT: 'error.conflict',
+    DB_FOREIGN_KEY: 'error.db.foreign.key',
+    DB_NOT_NULL: 'error.db.not.null',
+    DB_INVALID_INPUT: 'error.db.invalid.input',
+    DB_VALUE_TOO_LONG: 'error.db.value.too.long',
+    DB_CHECK_CONSTRAINT: 'error.db.check.constraint',
+    DB_DEADLOCK: 'error.db.deadlock',
+    INTERNAL: 'error.internal',
+    SERVICE_UNAVAILABLE: 'error.service.unavailable',
+    UNKNOWN: 'error.unknown',
+    HTTP: 'error.http',
+    GENERIC: 'error.generic',
+    PERMISSION_SYSTEM_UNAVAILABLE: 'error.permission.system.unavailable',
+    INSUFFICIENT_PERMISSIONS: 'error.insufficient.permissions',
+    INSUFFICIENT_PERMISSIONS_OR: 'error.insufficient.permissions.or',
+    NO_PERMISSIONS_FOUND: 'error.no.permissions.found',
+    ENDPOINT_DISABLED: 'error.endpoint.disabled'
+};
+// ==================== SYSTEM (Infrastructure) ====================
+export const SYSTEM_MESSAGES = {
+    REPOSITORY_NOT_AVAILABLE: 'system.repository.not.available',
+    DATASOURCE_NOT_AVAILABLE: 'system.datasource.not.available',
+    DATABASE_CONFIG_NOT_AVAILABLE: 'system.database.config.not.available',
+    SERVICE_NOT_AVAILABLE: 'system.service.not.available',
+    CONFIG_REQUIRED: 'system.config.required',
+    INTERNAL_ERROR: 'system.internal.error',
+    DUPLICATE_REQUEST: 'system.duplicate.request',
+    INVALID_TENANT_ID: 'system.invalid.tenant.id',
+    TENANT_NOT_FOUND: 'system.tenant.not.found',
+    TENANT_HEADER_REQUIRED: 'system.tenant.header.required',
+    MISSING_PARAMETER: 'system.missing.parameter',
+    SDK_NOT_INSTALLED: 'system.sdk.not.installed',
+    PATH_TRAVERSAL_DETECTED: 'system.path.traversal.detected',
+    INVALID_FILE_KEY: 'system.invalid.file.key'
+};

package/fesm/constants/permissions.js

@@ -1,13 +1,4 @@
-/**
- * Centralized Permission Codes
- *
- * Single source of truth for all permission codes used across the application.
- * Use these constants instead of hardcoded strings to prevent typos and enable easy refactoring.
- *
- * Naming Convention: <entity>.<action>
- * - entity: The resource being accessed (e.g., user, role, company)
- * - action: The operation being performed (create, read, update, delete, assign)
- */ // ==================== AUTH MODULE ====================
+// ==================== AUTH MODULE ====================
 export const USER_PERMISSIONS = {
     CREATE: 'user.create',
     READ: 'user.read',
@@ -74,6 +65,9 @@ export const STORAGE_CONFIG_PERMISSIONS = {
     UPDATE: 'storage-config.update',
     DELETE: 'storage-config.delete'
 };
+export const UPLOAD_CONFIG_PERMISSIONS = {
+    DELETE: 'upload-config.delete'
+};
 // ==================== EMAIL MODULE ====================
 export const EMAIL_CONFIG_PERMISSIONS = {
     CREATE: 'email-config.create',
@@ -100,10 +94,74 @@ export const FORM_RESULT_PERMISSIONS = {
     UPDATE: 'form-result.update',
     DELETE: 'form-result.delete'
 };
+// ==================== EVENT MANAGER MODULE ====================
+export const EVENT_PERMISSIONS = {
+    CREATE: 'event.create',
+    READ: 'event.read',
+    UPDATE: 'event.update',
+    DELETE: 'event.delete'
+};
+// ==================== NOTIFICATION MODULE ====================
+export const NOTIFICATION_PERMISSIONS = {
+    CREATE: 'notification.create',
+    READ: 'notification.read',
+    UPDATE: 'notification.update',
+    DELETE: 'notification.delete'
+};
+// ==================== LOCALIZATION MODULE ====================
+export const LANGUAGE_PERMISSIONS = {
+    CREATE: 'language.create',
+    READ: 'language.read',
+    UPDATE: 'language.update',
+    DELETE: 'language.delete'
+};
+export const TRANSLATION_KEY_PERMISSIONS = {
+    CREATE: 'translation-key.create',
+    READ: 'translation-key.read',
+    UPDATE: 'translation-key.update',
+    DELETE: 'translation-key.delete'
+};
+export const TRANSLATION_PERMISSIONS = {
+    CREATE: 'translation.create',
+    READ: 'translation.read',
+    UPDATE: 'translation.update',
+    DELETE: 'translation.delete'
+};
+// ==================== TASK MANAGER MODULE ====================
+export const TASK_BOARD_PERMISSIONS = {
+    CREATE: 'task-board.create',
+    READ: 'task-board.read',
+    UPDATE: 'task-board.update',
+    DELETE: 'task-board.delete',
+    MANAGE_MEMBERS: 'task-board.manage-members'
+};
+export const TASK_LIST_PERMISSIONS = {
+    CREATE: 'task-list.create',
+    READ: 'task-list.read',
+    UPDATE: 'task-list.update',
+    DELETE: 'task-list.delete'
+};
+export const TASK_PERMISSIONS = {
+    CREATE: 'task.create',
+    READ: 'task.read',
+    UPDATE: 'task.update',
+    DELETE: 'task.delete',
+    MOVE: 'task.move',
+    ASSIGN: 'task.assign'
+};
+export const TASK_LABEL_PERMISSIONS = {
+    CREATE: 'task-label.create',
+    READ: 'task-label.read',
+    UPDATE: 'task-label.update',
+    DELETE: 'task-label.delete'
+};
+export const TASK_COMMENT_PERMISSIONS = {
+    CREATE: 'task-comment.create',
+    READ: 'task-comment.read',
+    DELETE: 'task-comment.delete'
+};
 // ==================== AGGREGATED EXPORTS ====================
-/**
- * All permission codes grouped by module
- */ export const PERMISSIONS = {
+export const PERMISSIONS = {
     // Auth
     USER: USER_PERMISSIONS,
     COMPANY: COMPANY_PERMISSIONS,
@@ -124,5 +182,19 @@ export const FORM_RESULT_PERMISSIONS = {
     EMAIL_TEMPLATE: EMAIL_TEMPLATE_PERMISSIONS,
     // Form Builder
     FORM: FORM_PERMISSIONS,
-    FORM_RESULT: FORM_RESULT_PERMISSIONS
+    FORM_RESULT: FORM_RESULT_PERMISSIONS,
+    // Event Manager
+    EVENT: EVENT_PERMISSIONS,
+    // Notification
+    NOTIFICATION: NOTIFICATION_PERMISSIONS,
+    // Localization
+    LANGUAGE: LANGUAGE_PERMISSIONS,
+    TRANSLATION_KEY: TRANSLATION_KEY_PERMISSIONS,
+    TRANSLATION: TRANSLATION_PERMISSIONS,
+    // Task Manager
+    TASK_BOARD: TASK_BOARD_PERMISSIONS,
+    TASK_LIST: TASK_LIST_PERMISSIONS,
+    TASK: TASK_PERMISSIONS,
+    TASK_LABEL: TASK_LABEL_PERMISSIONS,
+    TASK_COMMENT: TASK_COMMENT_PERMISSIONS
 };

package/fesm/decorators/api-response.decorator.js

@@ -1,28 +1,10 @@
 import { BulkMetaDto, BulkResponseDto, ListResponseDto, PaginationMetaDto, SingleResponseDto } from '../dtos';
 import { applyDecorators } from '@nestjs/common';
 import { ApiExtraModels, ApiOkResponse, getSchemaPath } from '@nestjs/swagger';
-/**
- * API Response Decorator
- * Wraps response with the appropriate response structure
- *
- * @param dto - The DTO class for the data
- * @param isArray - Whether the data is an array (default: false)
- * @param arrayType - For arrays: 'list' (paginated) or 'bulk' (operations) (default: 'list')
- *
- * @example
- * // Single item response
- * @ApiResponseDto(UserDto)
- *
- * // Paginated list response (get-all)
- * @ApiResponseDto(UserDto, true, 'list')
- *
- * // Bulk operation response (insert-many, update-many)
- * @ApiResponseDto(UserDto, true, 'bulk')
- */ export const ApiResponseDto = (dto, isArray = false, arrayType = 'list')=>{
-    // Select appropriate wrapper based on response type
+export const ApiResponseDto = (dto, isArray = false, arrayType = 'list')=>{
     let wrapperDto;
     let metaDto = null;
-    if (!isArray) {
+    if (!isArray || arrayType === 'single') {
         wrapperDto = SingleResponseDto;
     } else if (arrayType === 'bulk') {
         wrapperDto = BulkResponseDto;

package/fesm/decorators/index.js

@@ -1,5 +1,5 @@
 export * from './api-response.decorator';
 export * from './current-user.decorator';
+export * from './log-action.decorator';
 export * from './public.decorator';
 export * from './require-permission.decorator';
-export * from './sanitize-html.decorator';

package/fesm/decorators/log-action.decorator.js

@@ -0,0 +1,139 @@
+import { Logger } from '@nestjs/common';
+import { createModuleLogger } from '../classes/winston.logger.class';
+import { getRequestId, getUserId, getTenantId, getCompanyId } from '../middlewares/logger.middleware';
+function createLoggerAdapter(className, moduleName) {
+    if (moduleName) {
+        const winstonLogger = createModuleLogger(moduleName);
+        return {
+            log: (level, message, meta)=>{
+                winstonLogger.log(level, message, {
+                    context: className,
+                    ...meta
+                });
+            },
+            error: (message, stack, meta)=>{
+                winstonLogger.error(message, {
+                    context: className,
+                    stack,
+                    ...meta
+                });
+            }
+        };
+    }
+    const nestLogger = new Logger(className);
+    return {
+        log: (level, message, meta)=>{
+            nestLogger[level](message, meta);
+        },
+        error: (message, stack, meta)=>{
+            nestLogger.error(message, stack, meta);
+        }
+    };
+}
+export function LogAction(options = {}) {
+    return function(target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        const className = target.constructor.name;
+        const methodName = String(propertyKey);
+        descriptor.value = async function(...args) {
+            const startTime = Date.now();
+            // Resolve module: decorator option > instance property > undefined
+            const moduleName = options.module || this.moduleName;
+            const logger = createLoggerAdapter(className, moduleName);
+            const action = options.action || `${this.entityName || className}.${methodName}`;
+            const logLevel = options.logLevel || 'debug';
+            const context = {
+                requestId: getRequestId(),
+                userId: getUserId(),
+                tenantId: getTenantId(),
+                companyId: getCompanyId(),
+                method: methodName,
+                module: moduleName
+            };
+            const startMessage = `Executing action method "${action}"`;
+            const startContext = options.includeParams ? {
+                ...context,
+                params: sanitizeParams(args)
+            } : context;
+            logger.log(logLevel, startMessage, startContext);
+            try {
+                const result = await originalMethod.apply(this, args);
+                const duration = Date.now() - startTime;
+                const resultType = getResultType(result);
+                const successMessage = `Executed action method "${action}", returned result "${resultType}" in ${duration.toFixed(2)}ms.`;
+                const successContext = options.includeResult && result ? {
+                    ...context,
+                    duration: `${duration}ms`,
+                    resultType,
+                    resultPreview: getResultPreview(result)
+                } : {
+                    ...context,
+                    duration: `${duration}ms`,
+                    resultType
+                };
+                logger.log(logLevel, successMessage, successContext);
+                return result;
+            } catch (error) {
+                const duration = Date.now() - startTime;
+                const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+                logger.error(`Failed action method "${action}" after ${duration.toFixed(2)}ms: ${errorMessage}`, error instanceof Error ? error.stack : undefined, {
+                    ...context,
+                    duration: `${duration}ms`,
+                    error: errorMessage
+                });
+                throw error;
+            }
+        };
+        return descriptor;
+    };
+}
+function sanitizeParams(args) {
+    return args.map((arg)=>{
+        if (arg === null || arg === undefined) return arg;
+        if (typeof arg === 'object') {
+            const sanitized = {
+                ...arg
+            };
+            const sensitiveKeys = [
+                'password',
+                'secret',
+                'token',
+                'apiKey',
+                'authorization'
+            ];
+            for (const key of Object.keys(sanitized)){
+                if (sensitiveKeys.some((sk)=>key.toLowerCase().includes(sk))) {
+                    sanitized[key] = '[REDACTED]';
+                }
+            }
+            return sanitized;
+        }
+        return arg;
+    });
+}
+function getResultType(result) {
+    if (result === null) return 'null';
+    if (result === undefined) return 'undefined';
+    if (Array.isArray(result)) return `Array<${result.length} items>`;
+    if (typeof result === 'object') {
+        const name = result.constructor?.name;
+        return name && name !== 'Object' ? name : 'Object';
+    }
+    return typeof result;
+}
+function getResultPreview(result) {
+    if (Array.isArray(result)) {
+        return {
+            count: result.length,
+            sample: result.slice(0, 2)
+        };
+    }
+    if (typeof result === 'object' && result !== null) {
+        const keys = Object.keys(result).slice(0, 5);
+        return {
+            keys,
+            hasMore: Object.keys(result).length > 5
+        };
+    }
+    return result;
+}