@flusys/nestjs-shared 0.1.0-beta.3 → 1.0.0-rc

package/fesm/utils/error-handler.util.js

@@ -1,27 +1,104 @@
+import { HttpStatus } from '@nestjs/common';
+/** Check if running in production environment */ const IS_PRODUCTION = process.env.NODE_ENV === 'production';
+/** Sensitive keys that should be redacted from logs */ const SENSITIVE_KEYS = [
+    'password',
+    'secret',
+    'token',
+    'apiKey',
+    'credential',
+    'authorization'
+];
+/** Patterns that indicate sensitive data in error messages */ const SENSITIVE_PATTERNS = [
+    /password/i,
+    /secret/i,
+    /token/i,
+    /key/i,
+    /credential/i,
+    /authorization/i,
+    /bearer/i
+];
 /**
- * Error handling utility for consistent error logging and handling
+ * Error handling utility for consistent error logging and handling.
+ * Provides production-aware error sanitization to prevent sensitive data leakage.
  */ export class ErrorHandler {
     /**
-   * Safely extract error message from unknown error
-   */ static getErrorMessage(error) {
+   * Safely extract error message from unknown error.
+   * @param error - The error to extract message from
+   * @param sanitizeForClient - If true, redacts potentially sensitive info in production
+   */ static getErrorMessage(error, sanitizeForClient = false) {
+        let message = 'Unknown error occurred';
         if (error instanceof Error) {
-            return error.message;
+            message = error.message;
+        } else if (typeof error === 'string') {
+            message = error;
         }
-        if (typeof error === 'string') {
-            return error;
+        // Sanitize for client responses in production
+        if (sanitizeForClient && IS_PRODUCTION) {
+            if (this.containsSensitiveData(message)) {
+                return 'An unexpected error occurred. Please try again later.';
+            }
         }
-        return 'Unknown error occurred';
+        return message;
+    }
+    /**
+   * Check if a string contains potentially sensitive data.
+   */ static containsSensitiveData(text) {
+        return SENSITIVE_PATTERNS.some((pattern)=>pattern.test(text));
     }
     /**
-   * Safely extract error stack from unknown error
-   */ static getErrorStack(error) {
+   * Safely extract error stack from unknown error.
+   * Returns undefined in production for client responses.
+   * @param error - The error to extract stack from
+   * @param forClient - If true, never returns stack in production
+   */ static getErrorStack(error, forClient = false) {
+        // Never expose stack traces to clients in production
+        if (forClient && IS_PRODUCTION) {
+            return undefined;
+        }
         if (error instanceof Error) {
             return error.stack;
         }
         return undefined;
     }
     /**
-   * Create error context object for logging
+   * Create a sanitized error response for clients.
+   * In production, sensitive data is redacted and stack traces removed.
+   */ static createClientError(error, statusCode = HttpStatus.INTERNAL_SERVER_ERROR, code) {
+        const sanitizedError = {
+            message: this.getErrorMessage(error, true),
+            statusCode
+        };
+        if (code) {
+            sanitizedError.code = code;
+        }
+        // Include stack only in development
+        if (!IS_PRODUCTION) {
+            sanitizedError.stack = this.getErrorStack(error);
+        }
+        return sanitizedError;
+    }
+    /**
+   * Sanitize context data to redact sensitive fields from logs.
+   */ static sanitizeContextForLogging(context) {
+        const sanitized = {};
+        for (const [key, value] of Object.entries(context)){
+            // Check if key contains sensitive words
+            const isSensitive = SENSITIVE_KEYS.some((sk)=>key.toLowerCase().includes(sk.toLowerCase()));
+            if (isSensitive) {
+                sanitized[key] = '[REDACTED]';
+            } else if (Array.isArray(value)) {
+                sanitized[key] = value.map((item)=>typeof item === 'object' && item !== null ? this.sanitizeContextForLogging(item) : item);
+            } else if (typeof value === 'object' && value !== null) {
+                sanitized[key] = this.sanitizeContextForLogging(value);
+            } else {
+                sanitized[key] = value;
+            }
+        }
+        return sanitized;
+    }
+    /**
+   * Create error context object for internal logging.
+   * Context data is sanitized to redact sensitive fields.
    */ static createErrorContext(error, context) {
         const errorContext = {
             error: {
@@ -33,20 +110,22 @@
             errorContext.error.name = error.name;
         }
         if (context && Object.keys(context).length > 0) {
-            errorContext.context = context;
+            // Sanitize context to redact sensitive fields
+            errorContext.context = this.sanitizeContextForLogging(context);
         }
         return errorContext;
     }
     /**
-   * Log error with consistent format
+   * Log error with consistent format.
+   * Sensitive data in context is automatically redacted.
    */ static logError(logger, error, operation, context) {
         const errorContext = this.createErrorContext(error, {
             operation,
             ...context
         });
         const errorMessage = `Failed to ${operation}: ${errorContext.error.message}`;
-        const loggerContext = logger.context || 'ErrorHandler';
-        logger.error(errorMessage, errorContext.error.stack, loggerContext, errorContext);
+        // Log full details internally (stack traces are fine for internal logs)
+        logger.error(errorMessage, errorContext.error.stack, errorContext);
     }
     /**
    * Re-throw error with proper type checking

package/fesm/utils/html-sanitizer.util.js

@@ -0,0 +1,82 @@
+/**
+ * HTML Sanitizer Utilities
+ *
+ * Provides functions for escaping HTML content to prevent XSS attacks.
+ * Use these utilities when interpolating user-provided variables into HTML content.
+ */ /**
+ * HTML entity mapping for escaping special characters
+ */ const HTML_ESCAPE_MAP = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#x27;',
+    '/': '&#x2F;',
+    '`': '&#x60;',
+    '=': '&#x3D;'
+};
+/**
+ * Regex pattern matching characters that need HTML escaping
+ */ const HTML_ESCAPE_REGEX = /[&<>"'`=/]/g;
+/**
+ * Escapes HTML special characters to prevent XSS attacks.
+ *
+ * @param str - The string to escape
+ * @returns The escaped string safe for HTML insertion
+ *
+ * @example
+ * ```typescript
+ * escapeHtml('<script>alert("xss")</script>')
+ * // Returns: '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+ * ```
+ */ export function escapeHtml(str) {
+    if (!str || typeof str !== 'string') {
+        return str ?? '';
+    }
+    return str.replace(HTML_ESCAPE_REGEX, (char)=>HTML_ESCAPE_MAP[char] || char);
+}
+/**
+ * Escapes all string values in a variables object for safe HTML interpolation.
+ * Non-string values are converted to strings and escaped.
+ *
+ * @param variables - Object containing template variables
+ * @returns New object with all string values HTML-escaped
+ *
+ * @example
+ * ```typescript
+ * escapeHtmlVariables({ name: '<script>xss</script>', count: 5 })
+ * // Returns: { name: '&lt;script&gt;xss&lt;/script&gt;', count: '5' }
+ * ```
+ */ export function escapeHtmlVariables(variables) {
+    if (!variables || typeof variables !== 'object') {
+        return {};
+    }
+    const escaped = {};
+    for (const [key, value] of Object.entries(variables)){
+        if (value === null || value === undefined) {
+            escaped[key] = '';
+        } else if (typeof value === 'string') {
+            escaped[key] = escapeHtml(value);
+        } else if (typeof value === 'object') {
+            // For objects/arrays, stringify and escape
+            escaped[key] = escapeHtml(JSON.stringify(value));
+        } else {
+            // For numbers, booleans, etc., convert to string (no escaping needed)
+            escaped[key] = String(value);
+        }
+    }
+    return escaped;
+}
+/**
+ * Checks if a string contains potential HTML/script injection.
+ * Useful for logging or validation purposes.
+ *
+ * @param str - The string to check
+ * @returns True if the string contains HTML-like content
+ */ export function containsHtmlContent(str) {
+    if (!str || typeof str !== 'string') {
+        return false;
+    }
+    // Check for common HTML patterns
+    return /<[a-z][\s\S]*>/i.test(str) || /javascript:/i.test(str) || /on\w+=/i.test(str);
+}

package/fesm/utils/index.js

@@ -1 +1,3 @@
 export * from './error-handler.util';
+export * from './html-sanitizer.util';
+export * from './query-helpers.util';

package/fesm/utils/query-helpers.util.js

@@ -0,0 +1,78 @@
+import { BadRequestException } from '@nestjs/common';
+/**
+ * Apply company filter to a query builder if company feature is enabled.
+ * Centralizes the common pattern of filtering by user's company.
+ *
+ * @param query - TypeORM SelectQueryBuilder
+ * @param config - Company filter configuration
+ * @param user - Current logged user (may be null)
+ * @returns The modified query builder
+ *
+ * @example
+ * ```typescript
+ * applyCompanyFilter(query, {
+ *   isCompanyFeatureEnabled: this.config.isCompanyFeatureEnabled(),
+ *   entityAlias: 'file_manager',
+ * }, user);
+ * ```
+ */ export function applyCompanyFilter(query, config, user) {
+    const columnName = config.columnName ?? 'companyId';
+    if (config.isCompanyFeatureEnabled && user?.companyId) {
+        query.andWhere(`${config.entityAlias}.${columnName} = :companyId`, {
+            companyId: user.companyId
+        });
+    }
+    return query;
+}
+/**
+ * Build a where condition object with optional company filter.
+ *
+ * @param baseWhere - Base where condition object
+ * @param isCompanyFeatureEnabled - Whether company feature is enabled
+ * @param user - Current logged user
+ * @returns Where condition with companyId added if applicable
+ *
+ * @example
+ * ```typescript
+ * const where = buildCompanyWhereCondition(
+ *   { id: dto.id },
+ *   this.config.isCompanyFeatureEnabled(),
+ *   user
+ * );
+ * // Returns { id: dto.id, companyId: user.companyId } if company feature enabled
+ * ```
+ */ export function buildCompanyWhereCondition(baseWhere, isCompanyFeatureEnabled, user) {
+    if (isCompanyFeatureEnabled && user?.companyId) {
+        return {
+            ...baseWhere,
+            companyId: user.companyId
+        };
+    }
+    return baseWhere;
+}
+/**
+ * Type guard to check if entity has companyId property
+ */ export function hasCompanyId(entity) {
+    return entity !== null && typeof entity === 'object' && 'companyId' in entity;
+}
+/**
+ * Validates that an entity with companyId belongs to the user's company.
+ * Throws BadRequestException if the entity belongs to another company.
+ *
+ * @param entity - Entity to validate
+ * @param user - Current logged user
+ * @param isCompanyFeatureEnabled - Whether company feature is enabled
+ * @param entityName - Name of entity for error message (e.g., 'Email configuration')
+ * @throws BadRequestException if entity belongs to another company
+ *
+ * @example
+ * ```typescript
+ * validateCompanyOwnership(config, user, this.config.isCompanyFeatureEnabled(), 'Email configuration');
+ * ```
+ */ export function validateCompanyOwnership(entity, user, isCompanyFeatureEnabled, entityName) {
+    if (isCompanyFeatureEnabled && user?.companyId && hasCompanyId(entity)) {
+        if (entity.companyId && entity.companyId !== user.companyId) {
+            throw new BadRequestException(`${entityName} belongs to another company`);
+        }
+    }
+}

package/interceptors/index.d.ts

@@ -2,6 +2,7 @@ export * from './delete-empty-id-from-body.interceptor';
 export * from './idempotency.interceptor';
 export * from './query-performance.interceptor';
 export * from './response-meta.interceptor';
+export * from './set-user-field-on-body.interceptor';
 export * from './set-create-by-on-body.interceptor';
 export * from './set-delete-by-on-body.interceptor';
 export * from './set-update-by-on-body.interceptor';

package/interceptors/set-create-by-on-body.interceptor.d.ts

@@ -1,5 +1 @@
-import { CallHandler, ExecutionContext, NestInterceptor } from '@nestjs/common';
-import { Observable } from 'rxjs';
-export declare class SetCreatedByOnBody implements NestInterceptor {
-    intercept<T = any>(context: ExecutionContext, next: CallHandler<T>): Observable<T>;
-}
+export declare const SetCreatedByOnBody: import("@nestjs/common").Type<import("@nestjs/common").NestInterceptor<any, any>>;

package/interceptors/set-delete-by-on-body.interceptor.d.ts

@@ -1,5 +1 @@
-import { CallHandler, ExecutionContext, NestInterceptor } from '@nestjs/common';
-import { Observable } from 'rxjs';
-export declare class SetDeletedByOnBody implements NestInterceptor {
-    intercept<T = any>(context: ExecutionContext, next: CallHandler<T>): Observable<T>;
-}
+export declare const SetDeletedByOnBody: import("@nestjs/common").Type<import("@nestjs/common").NestInterceptor<any, any>>;

package/interceptors/set-update-by-on-body.interceptor.d.ts

@@ -1,5 +1 @@
-import { CallHandler, ExecutionContext, NestInterceptor } from '@nestjs/common';
-import { Observable } from 'rxjs';
-export declare class SetUpdateByOnBody implements NestInterceptor {
-    intercept<T = any>(context: ExecutionContext, next: CallHandler<T>): Observable<T>;
-}
+export declare const SetUpdateByOnBody: import("@nestjs/common").Type<import("@nestjs/common").NestInterceptor<any, any>>;

package/interceptors/set-user-field-on-body.interceptor.d.ts

@@ -0,0 +1,2 @@
+import { NestInterceptor, Type } from '@nestjs/common';
+export declare function createSetUserFieldInterceptor(fieldName: string): Type<NestInterceptor>;

package/interceptors/slug.interceptor.d.ts

@@ -2,6 +2,7 @@ import { CallHandler, ExecutionContext, NestInterceptor } from '@nestjs/common';
 import { Observable } from 'rxjs';
 import { UtilsService } from '../modules/utils/utils.service';
 export declare class Slug implements NestInterceptor {
-    utilsService: UtilsService;
+    private readonly utilsService;
+    constructor(utilsService: UtilsService);
     intercept<T = any>(context: ExecutionContext, next: CallHandler<T>): Observable<T>;
 }

package/interfaces/api.interface.d.ts

@@ -1,5 +1,5 @@
-import { DeleteDto, FilterAndPaginationDto } from '@flusys/nestjs-shared/dtos';
-import { ILoggedUserInfo } from '@flusys/nestjs-shared/interfaces';
+import { DeleteDto, FilterAndPaginationDto } from '../dtos';
+import { ILoggedUserInfo } from './logged-user-info.interface';
 export interface IService<CreateDtoT, UpdateDtoT, InterfaceT> {
     insert(addDto: CreateDtoT, user: ILoggedUserInfo | null): Promise<InterfaceT>;
     insertMany(addDto: Array<CreateDtoT>, user: ILoggedUserInfo | null): Promise<Array<InterfaceT>>;

package/interfaces/datasource.interface.d.ts

@@ -0,0 +1,5 @@
+import { DataSource, EntityTarget, ObjectLiteral, Repository } from 'typeorm';
+export interface IDataSourceProvider {
+    getRepository<T extends ObjectLiteral>(entity: EntityTarget<T>): Promise<Repository<T>>;
+    getDataSource(): Promise<DataSource>;
+}

package/interfaces/identity.interface.d.ts

@@ -2,8 +2,8 @@ export interface IIdentity {
     id: string;
     createdAt: Date;
     updatedAt: Date;
-    deletedAt: Date;
-    createdById: string;
-    updatedById: string;
-    deletedById: string;
+    deletedAt: Date | null;
+    createdById: string | null;
+    updatedById: string | null;
+    deletedById: string | null;
 }

package/interfaces/index.d.ts

@@ -1,6 +1,7 @@
 export * from './api.interface';
-export * from './base-query.interface';
+export * from './datasource.interface';
 export * from './identity.interface';
 export * from './logged-user-info.interface';
 export * from './logger.interface';
+export * from './module-config.interface';
 export * from './permission.interface';

package/interfaces/module-config.interface.d.ts

@@ -0,0 +1,6 @@
+import { DatabaseMode } from '@flusys/nestjs-core';
+export interface IModuleConfigService {
+    getDatabaseMode(): DatabaseMode;
+    isMultiTenant(): boolean;
+    isCompanyFeatureEnabled(): boolean;
+}

package/interfaces/permission.interface.d.ts

@@ -11,7 +11,6 @@ export interface LegacyPermissionConfig {
 export type PermissionConfig = PermissionCondition | LegacyPermissionConfig | string[];
 export interface PermissionGuardConfig {
     enableCompanyFeature?: boolean;
-    cacheKeyPrefix?: string;
     userPermissionKeyFormat?: string;
     companyPermissionKeyFormat?: string;
 }

package/modules/utils/utils.service.d.ts

@@ -1,6 +1,14 @@
-import { HybridCache } from '@flusys/nestjs-shared/classes';
+import { HybridCache } from '../../classes/hybrid-cache.class';
+export declare const DEFAULT_PHONE_REGEX: RegExp;
+export declare const DEFAULT_PHONE_COUNTRY_CODE = "+88";
+export interface PhoneValidationConfig {
+    regex: RegExp;
+    countryCode: string;
+}
 export declare class UtilsService {
-    constructor();
+    private readonly logger;
+    private phoneConfig;
+    setPhoneValidationConfig(config: PhoneValidationConfig): void;
     getCacheKey(entityName: string, params: any, entityId?: string, tenantId?: string): string;
     trackCacheKey(cacheKey: string, entityName: string, cacheManager: HybridCache, entityId?: string, tenantId?: string): Promise<void>;
     clearCache(entityName: string, cacheManager: HybridCache, entityId?: string, tenantId?: string): Promise<void>;
@@ -16,6 +24,4 @@ export declare class UtilsService {
         columnName: string;
         value: string;
     };
-    getOtpEmailFormat(otp: number, userName?: string | null | undefined): string;
-    getResetPasswordEmailFormat(resetLink: string, userName?: string | null | undefined): string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flusys/nestjs-shared",
-  "version": "0.1.0-beta.3",
+  "version": "1.0.0-rc",
   "description": "Common shared utilities for Flusys NestJS applications",
   "main": "cjs/index.js",
   "module": "fesm/index.js",
@@ -88,7 +88,7 @@
     }
   },
   "peerDependencies": {
-    "@keyv/redis": "^3.0.0",
+    "@keyv/redis": "^5.0.0",
     "@nestjs/common": "^10.0.0 || ^11.0.0",
     "@nestjs/config": "^3.0.0 || ^4.0.0",
     "@nestjs/core": "^10.0.0 || ^11.0.0",
@@ -96,7 +96,7 @@
     "@nestjs/passport": "^10.0.0 || ^11.0.0",
     "@nestjs/swagger": "^7.0.0 || ^11.0.0",
     "@nestjs/typeorm": "^10.0.0 || ^11.0.0",
-    "cacheable": "^1.0.0",
+    "cacheable": "^2.0.0",
     "class-transformer": "^0.5.0",
     "class-validator": "^0.14.0",
     "keyv": "^5.0.0",
@@ -105,6 +105,6 @@
     "winston-daily-rotate-file": "^5.0.0"
   },
   "dependencies": {
-    "@flusys/nestjs-core": "0.1.0-beta.3"
+    "@flusys/nestjs-core": "1.0.0-rc"
   }
 }

package/utils/error-handler.util.d.ts

@@ -1,13 +1,27 @@
 import { Logger } from '@nestjs/common';
+export interface IErrorContext {
+    operation?: string;
+    entity?: string;
+    userId?: string;
+    id?: string;
+    companyId?: string;
+    branchId?: string;
+    sectionId?: string;
+    data?: Record<string, unknown>;
+}
+export interface ISanitizedError {
+    message: string;
+    code?: string;
+    statusCode?: number;
+    stack?: string;
+}
 export declare class ErrorHandler {
-    static getErrorMessage(error: unknown): string;
-    static getErrorStack(error: unknown): string | undefined;
-    static createErrorContext(error: unknown, context?: {
-        operation?: string;
-        entity?: string;
-        userId?: string;
-        [key: string]: unknown;
-    }): {
+    static getErrorMessage(error: unknown, sanitizeForClient?: boolean): string;
+    private static containsSensitiveData;
+    static getErrorStack(error: unknown, forClient?: boolean): string | undefined;
+    static createClientError(error: unknown, statusCode?: number, code?: string): ISanitizedError;
+    private static sanitizeContextForLogging;
+    static createErrorContext(error: unknown, context?: IErrorContext): {
         error: {
             message: string;
             stack?: string;
@@ -15,10 +29,6 @@ export declare class ErrorHandler {
         };
         context?: Record<string, unknown>;
     };
-    static logError(logger: Logger, error: unknown, operation: string, context?: {
-        entity?: string;
-        userId?: string;
-        [key: string]: unknown;
-    }): void;
+    static logError(logger: Logger, error: unknown, operation: string, context?: Omit<IErrorContext, 'operation'>): void;
     static rethrowError(error: unknown): never;
 }

package/utils/html-sanitizer.util.d.ts

@@ -0,0 +1,3 @@
+export declare function escapeHtml(str: string): string;
+export declare function escapeHtmlVariables(variables: Record<string, unknown>): Record<string, string>;
+export declare function containsHtmlContent(str: string): boolean;

package/utils/index.d.ts

@@ -1 +1,3 @@
 export * from './error-handler.util';
+export * from './html-sanitizer.util';
+export * from './query-helpers.util';

package/utils/query-helpers.util.d.ts

@@ -0,0 +1,16 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+import { ILoggedUserInfo } from '../interfaces';
+export interface ICompanyFilterConfig {
+    isCompanyFeatureEnabled: boolean;
+    entityAlias: string;
+    columnName?: string;
+}
+export declare function applyCompanyFilter<T extends ObjectLiteral>(query: SelectQueryBuilder<T>, config: ICompanyFilterConfig, user: ILoggedUserInfo | null | undefined): SelectQueryBuilder<T>;
+export declare function buildCompanyWhereCondition<T extends Record<string, unknown>>(baseWhere: T, isCompanyFeatureEnabled: boolean, user: ILoggedUserInfo | null | undefined): T & {
+    companyId?: string;
+};
+export interface ICompanyEnabled {
+    companyId?: string | null;
+}
+export declare function hasCompanyId<T>(entity: T): entity is T & ICompanyEnabled;
+export declare function validateCompanyOwnership<T>(entity: T, user: ILoggedUserInfo | null | undefined, isCompanyFeatureEnabled: boolean, entityName: string): void;

package/cjs/interfaces/base-query.interface.js

@@ -1,6 +0,0 @@
-/**
- * Base query DTO interface for list/search endpoints
- */ "use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});

package/fesm/interfaces/base-query.interface.js

@@ -1,3 +0,0 @@
-/**
- * Base query DTO interface for list/search endpoints
- */ export { };

package/interfaces/base-query.interface.d.ts

@@ -1,7 +0,0 @@
-export interface IBaseQueryDto {
-    search?: string;
-    sortBy?: string;
-    sortOrder?: 'ASC' | 'DESC';
-    page?: number;
-    limit?: number;
-}