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

package/README.md

@@ -1,667 +1,210 @@
-# Shared Package Guide
+# @flusys/nestjs-shared
 
-> **Package:** `@flusys/nestjs-shared`
-> **Version:** 1.1.0
-> **Type:** Shared NestJS utilities, classes, decorators, guards, and modules
+Shared infrastructure for all FLUSYS NestJS packages — base CRUD classes, JWT guard, permission guard, response DTOs, hybrid cache, structured logging, and soft-delete entities.
 
-This comprehensive guide covers the shared package - the shared NestJS infrastructure layer.
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Package Architecture](#package-architecture)
-- [ApiService - Generic CRUD Service](#apiservice---generic-crud-service)
-- [RequestScopedApiService](#requestscopedapiservice)
-- [ApiController - Generic CRUD Controller](#apicontroller---generic-crud-controller)
-- [Decorators](#decorators)
-- [Guards](#guards)
-- [Middleware](#middleware)
-- [Interceptors](#interceptors)
-- [Caching System](#caching-system)
-- [Multi-Tenant DataSource](#multi-tenant-datasource)
-- [DTOs](#dtos)
-- [Base Entities](#base-entities)
-- [Utilities](#utilities)
-- [Error Handling](#error-handling)
-- [Constants](#constants)
-- [API Reference](#api-reference)
+[![npm version](https://img.shields.io/npm/v/@flusys/nestjs-shared.svg)](https://www.npmjs.com/package/@flusys/nestjs-shared)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
 
-## Overview
-
-`@flusys/nestjs-shared` provides shared utilities for building scalable NestJS applications:
-
-- **Generic CRUD** - Standardized API controller and service patterns
-- **Permission System** - Role and permission-based access control with complex logic
-- **Caching** - In-memory + Redis hybrid caching (HybridCache)
-- **Request Correlation** - AsyncLocalStorage-based request tracking
-- **Middleware** - Logging, correlation, and performance monitoring
-- **Interceptors** - Response metadata, idempotency, auto field setting
-- **Multi-Tenancy** - Dynamic database connection management
-- **Error Handling** - Centralized error handling with sensitive data redaction
+## Installation
 
-### Package Hierarchy
-
-```
-@flusys/nestjs-core     <- Pure TypeScript (foundation)
-     |
-@flusys/nestjs-shared   <- Shared NestJS utilities (THIS PACKAGE)
-     |
-@flusys/nestjs-auth     <- Uses common classes
-     |
-@flusys/nestjs-iam      <- Uses common patterns
-     |
-@flusys/nestjs-storage  <- Uses common patterns
+```bash
+npm install @flusys/nestjs-shared @flusys/nestjs-core
+npm install typeorm @nestjs/passport @nestjs/jwt passport-jwt winston
 ```
 
----
-
-## Package Architecture
-
-```
-nestjs-shared/
-├── src/
-│   ├── classes/              # Base classes
-│   │   ├── api-service.class.ts           # Generic CRUD service
-│   │   ├── api-controller.class.ts        # Generic CRUD controller factory (createApiController)
-│   │   ├── request-scoped-api.service.ts  # REQUEST-scoped service base
-│   │   ├── hybrid-cache.class.ts          # Two-tier caching
-│   │   ├── winston.logger.class.ts        # Winston logger config
-│   │   └── winston-logger-adapter.class.ts
-│   │
-│   ├── constants/            # Injection tokens & constants
-│   │   ├── permissions.ts                 # Permission constants (PERMISSIONS)
-│   │   └── index.ts
-│   │
-│   ├── decorators/           # Custom decorators
-│   │   ├── api-response.decorator.ts      # @ApiResponseDto
-│   │   ├── current-user.decorator.ts      # @CurrentUser
-│   │   ├── public.decorator.ts            # @Public
-│   │   ├── require-permission.decorator.ts # @RequirePermission, @RequireAnyPermission, @RequirePermissionCondition
-│   │   ├── sanitize-html.decorator.ts     # @SanitizeHtml, @SanitizeAndTrim
-│   │   └── index.ts
-│   │
-│   ├── dtos/                 # Shared DTOs
-│   │   ├── delete.dto.ts
-│   │   ├── filter-and-pagination.dto.ts
-│   │   ├── identity-response.dto.ts
-│   │   ├── pagination.dto.ts
-│   │   ├── response-payload.dto.ts
-│   │   └── index.ts
-│   │
-│   ├── entities/             # Base entities
-│   │   ├── identity.ts                    # Base entity with UUID
-│   │   ├── user-root.ts                   # Base user entity
-│   │   └── index.ts
-│   │
-│   ├── exceptions/           # Custom exceptions
-│   │   └── permission.exception.ts        # Permission-related exceptions
-│   │
-│   ├── guards/               # Authentication & authorization
-│   │   ├── jwt-auth.guard.ts              # JWT token validation
-│   │   └── permission.guard.ts            # Permission checks
-│   │
-│   ├── interceptors/         # Request/response interceptors
-│   │   ├── delete-empty-id-from-body.interceptor.ts
-│   │   ├── idempotency.interceptor.ts
-│   │   ├── query-performance.interceptor.ts
-│   │   ├── response-meta.interceptor.ts
-│   │   ├── set-user-field-on-body.interceptor.ts  # SetCreatedByOnBody, SetUpdateByOnBody, SetDeletedByOnBody
-│   │   └── slug.interceptor.ts
-│   │
-│   ├── interfaces/           # TypeScript interfaces
-│   │   ├── api.interface.ts               # IService interface
-│   │   ├── datasource.interface.ts        # IDataSourceProvider
-│   │   ├── identity.interface.ts
-│   │   ├── logged-user-info.interface.ts  # ILoggedUserInfo
-│   │   ├── logger.interface.ts            # ILogger
-│   │   ├── module-config.interface.ts     # IModuleConfigService
-│   │   └── permission.interface.ts        # PermissionCondition, PermissionOperator
-│   │
-│   ├── middlewares/          # Middleware
-│   │   └── logger.middleware.ts           # Request logging & correlation
-│   │
-│   ├── modules/              # NestJS modules
-│   │   ├── cache/cache.module.ts
-│   │   ├── datasource/
-│   │   │   ├── datasource.module.ts
-│   │   │   └── multi-tenant-datasource.service.ts
-│   │   └── utils/
-│   │       ├── utils.module.ts
-│   │       └── utils.service.ts
-│   │
-│   └── utils/                # Utility functions
-│       ├── error-handler.util.ts
-│       ├── query-helpers.util.ts
-│       ├── string.util.ts
-│       ├── request.util.ts
-│       └── html-sanitizer.util.ts
-```
-
----
+## 1. Module Registration
 
-## ApiService - Generic CRUD Service
-
-The `ApiService` base class provides standardized CRUD operations with caching, pagination, and transaction support.
-
-### Basic Usage
+Register once in your root `AppModule`:
 
 ```typescript
-import { ApiService, HybridCache } from '@flusys/nestjs-shared/classes';
-import { UtilsService } from '@flusys/nestjs-shared/modules';
-import { Injectable, Inject } from '@nestjs/common';
-import { Repository } from 'typeorm';
+import { Module, MiddlewareConsumer, NestModule } from '@nestjs/common';
+import { CacheModule, UtilsModule } from '@flusys/nestjs-shared/modules';
+import { LoggerMiddleware } from '@flusys/nestjs-shared/middlewares';
+import { GlobalExceptionFilter } from '@flusys/nestjs-shared/filters';
+import { ResponseMetaInterceptor } from '@flusys/nestjs-shared/interceptors';
 
-@Injectable()
-export class UserService extends ApiService<
-  CreateUserDto,         // Create DTO
-  UpdateUserDto,         // Update DTO
-  IUser,                 // Interface
-  User,                  // Entity
-  Repository<User>       // Repository type
-> {
-  constructor(
-    @InjectRepository(User)
-    protected override repository: Repository<User>,
-    @Inject('CACHE_INSTANCE')
-    protected override cacheManager: HybridCache,
-    @Inject(UtilsService)
-    protected override utilsService: UtilsService,
-  ) {
-    super(
-      'user',              // Entity name (for query building)
-      repository,
-      cacheManager,
-      utilsService,
-      'UserService',       // Service name (for logging)
-      true,                // Enable caching
-    );
+@Module({
+  imports: [
+    CacheModule.forRoot(true), // true = global; provides 'CACHE_INSTANCE' token
+    UtilsModule, // provides UtilsService
+  ],
+})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(LoggerMiddleware).forRoutes('*');
   }
 }
-```
 
-### ApiService Methods
+// In bootstrap()
+app.useGlobalFilters(new GlobalExceptionFilter());
+app.useGlobalInterceptors(new ResponseMetaInterceptor());
+```
 
-| Method | Description |
-|--------|-------------|
-| `insert(dto, user)` | Create single entity |
-| `insertMany(dtos, user)` | Create multiple entities |
-| `getById(id, user, select?)` | Get entity by ID |
-| `findById(id, user, select?)` | Find entity (returns null if not found) |
-| `findByIds(ids, user, select?)` | Find multiple by IDs |
-| `getAll(dto, user)` | Get paginated list |
-| `update(dto, user)` | Update single entity |
-| `updateMany(dtos, user)` | Update multiple entities |
-| `delete(dto, user)` | Soft/permanent delete or restore |
+## 2. Entity Base Class
 
-### Customization Hooks
+Every entity must extend `Identity`:
 
 ```typescript
-@Injectable()
-export class UserService extends ApiService<...> {
-  // Convert DTO to entity
-  override async convertSingleDtoToEntity(dto, user): Promise<User> { }
-
-  // Customize SELECT query
-  override async getSelectQuery(query, user, select?): Promise<{ query, isRaw }> { }
-
-  // Add WHERE filters
-  override async getFilterQuery(query, filter, user): Promise<{ query, isRaw }> { }
-
-  // Add global search
-  override async getGlobalSearchQuery(query, globalSearch, user): Promise<{ query, isRaw }> { }
-
-  // Add sort order
-  override async getSortQuery(query, sort, user): Promise<{ query, isRaw }> { }
-
-  // Add extra query conditions (e.g., company filtering)
-  override async getExtraManipulateQuery(query, dto, user): Promise<{ query, isRaw }> { }
-
-  // Before insert hook
-  override async beforeInsertOperation(entity, user, queryRunner): Promise<void> { }
-
-  // After insert hook
-  override async afterInsertOperation(entity, user, queryRunner): Promise<void> { }
-
-  // Before update hook
-  override async beforeUpdateOperation(oldEntity, newEntity, user, queryRunner): Promise<void> { }
-
-  // After update hook
-  override async afterUpdateOperation(entity, user, queryRunner): Promise<void> { }
-
-  // Before delete hook
-  override async beforeDeleteOperation(dto, user, queryRunner): Promise<void> { }
+import { Entity, Column } from 'typeorm';
+import { Identity } from '@flusys/nestjs-shared/entities';
 
-  // After delete hook
-  override async afterDeleteOperation(dto, user, queryRunner): Promise<void> { }
+@Entity('products')
+export class Product extends Identity {
+  @Column({ length: 255 })
+  name: string;
+  // inherited: id (uuid), createdAt, updatedAt, deletedAt,
+  //            createdById, updatedById, deletedById
 }
 ```
 
----
-
-## RequestScopedApiService
+## 3. Generic CRUD — `createApiController` + `RequestScopedApiService`
 
-For dynamic entity resolution based on runtime configuration (e.g., company feature).
+### Service (REQUEST-scoped, DataSource Provider pattern)
 
 ```typescript
-import { RequestScopedApiService } from '@flusys/nestjs-shared/classes';
 import { Injectable, Scope, Inject } from '@nestjs/common';
 import { EntityTarget, Repository } from 'typeorm';
+import { RequestScopedApiService } from '@flusys/nestjs-shared/classes';
+import { HybridCache } from '@flusys/nestjs-shared/classes';
+import { UtilsService } from '@flusys/nestjs-shared/modules';
 
-@Injectable({ scope: Scope.REQUEST })
-export class RoleService extends RequestScopedApiService<
-  CreateRoleDto,
-  UpdateRoleDto,
-  IRole,
-  RoleBase,
-  Repository<RoleBase>
+@Injectable({ scope: Scope.REQUEST }) // required
+export class ProductService extends RequestScopedApiService<
+  CreateProductDto,
+  UpdateProductDto,
+  IProduct,
+  Product
 > {
   constructor(
     @Inject('CACHE_INSTANCE') protected override cacheManager: HybridCache,
     @Inject(UtilsService) protected override utilsService: UtilsService,
-    @Inject(ModuleConfigService) private readonly config: ModuleConfigService,
-    @Inject(DataSourceProvider) private readonly provider: DataSourceProvider,
+    @Inject(ProductConfigService) private readonly config: ProductConfigService,
+    @Inject(ProductDataSourceProvider) private readonly dsp: ProductDataSourceProvider,
   ) {
-    // Pass null for repository - will be initialized dynamically
-    super('role', null as any, cacheManager, utilsService, 'RoleService', true);
+    super('product', null as any, cacheManager, utilsService, ProductService.name, true);
   }
 
-  // Required: Resolve which entity to use
-  protected resolveEntity(): EntityTarget<RoleBase> {
-    return this.config.isCompanyFeatureEnabled() ? RoleWithCompany : Role;
+  // Required: tell the base class which entity and which datasource to use
+  protected resolveEntity(): EntityTarget<Product> {
+    return this.config.isCompanyFeatureEnabled() ? ProductWithCompany : Product;
   }
 
-  // Required: Return the DataSource provider
-  protected getDataSourceProvider(): IDataSourceProvider {
-    return this.provider;
-  }
-
-  // Optional: Initialize additional repositories
-  protected async initializeAdditionalRepositories(): Promise<void> {
-    this.actionRepository = await this.dataSourceProvider.getRepository(Action);
+  protected getDataSourceProvider() {
+    return this.dsp;
   }
 }
 ```
 
-### Key Methods
-
-| Method | Description |
-|--------|-------------|
-| `ensureRepositoryInitialized()` | Must call before using repository |
-| `resolveEntity()` | Abstract - return entity class based on config |
-| `getDataSourceProvider()` | Abstract - return datasource provider |
-| `getDataSourceForService()` | Get raw DataSource for transactions |
-
----
-
-## ApiController - Generic CRUD Controller
-
-The `createApiController` factory creates standardized POST-only RPC controllers.
-
-### Basic Usage
+### Controller (factory function)
 
 ```typescript
-import { createApiController } from '@flusys/nestjs-shared/classes';
 import { Controller, Inject } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
-
-@ApiTags('Users')
-@Controller('users')
-export class UserController extends createApiController<
-  CreateUserDto,
-  UpdateUserDto,
-  UserResponseDto,
-  IUser,
-  UserService
->(CreateUserDto, UpdateUserDto, UserResponseDto) {
-  constructor(@Inject(UserService) protected service: UserService) {
-    super(service);
-  }
-}
-```
-
-### Generated Endpoints
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/insert` | POST | Create entity |
-| `/insert-many` | POST | Create multiple entities |
-| `/get/:id` | POST | Get entity by ID |
-| `/get-all` | POST | Get paginated list |
-| `/update` | POST | Update entity |
-| `/update-many` | POST | Update multiple entities |
-| `/delete` | POST | Delete entity |
-
-### Security Configuration
-
-```typescript
-// Global security (all endpoints)
-@Controller('users')
-export class UserController extends createApiController(
-  CreateUserDto,
-  UpdateUserDto,
-  UserResponseDto,
-  { security: 'jwt' },  // All endpoints require JWT
-) {}
+import { createApiController } from '@flusys/nestjs-shared/classes';
 
-// Per-endpoint security
-@Controller('users')
-export class UserController extends createApiController(
-  CreateUserDto,
-  UpdateUserDto,
-  UserResponseDto,
-  {
-    security: {
-      getAll: 'public',                                    // No auth required
-      getById: 'jwt',                                      // JWT required
-      insert: { level: 'permission', permissions: ['users.create'] },
-      update: { level: 'permission', permissions: ['users.update'] },
-      delete: { level: 'permission', permissions: ['users.delete'] },
-    },
+@Controller('administration/products')
+export class ProductController extends createApiController<
+  CreateProductDto,
+  UpdateProductDto,
+  ProductResponseDto,
+  IProduct,
+  ProductService
+>(CreateProductDto, UpdateProductDto, ProductResponseDto, {
+  entityName: 'product',
+  security: {
+    insert: { level: 'permission', permissions: ['product.create'] },
+    insertMany: { level: 'permission', permissions: ['product.create'] },
+    getAll: { level: 'permission', permissions: ['product.read'] },
+    getById: { level: 'permission', permissions: ['product.read'] },
+    update: { level: 'permission', permissions: ['product.update'] },
+    updateMany: { level: 'permission', permissions: ['product.update'] },
+    delete: { level: 'permission', permissions: ['product.delete'] },
+    bulkUpsert: { level: 'permission', permissions: ['product.create'] },
+    getByIds: { level: 'permission', permissions: ['product.read'] },
+    getByFilter: { level: 'permission', permissions: ['product.read'] },
   },
-) {}
-```
-
----
-
-## Decorators
-
-### @CurrentUser
-
-Extract the logged-in user from request:
-
-```typescript
-import { CurrentUser } from '@flusys/nestjs-shared/decorators';
-import { ILoggedUserInfo } from '@flusys/nestjs-shared/interfaces';
-
-@Controller('profile')
-export class ProfileController {
-  @Post('me')
-  getProfile(@CurrentUser() user: ILoggedUserInfo) {
-    return { userId: user.id, companyId: user.companyId };
-  }
-
-  // Extract specific property
-  @Post('id')
-  getUserId(@CurrentUser('id') userId: string) {
-    return { userId };
+}) {
+  constructor(@Inject(ProductService) public override service: ProductService) {
+    super(service);
   }
 }
 ```
 
-### @Public
-
-Mark route as public (skip authentication). **Use sparingly - security risk**.
-
-```typescript
-import { Public } from '@flusys/nestjs-shared/decorators';
+Generated POST-only endpoints: `/insert`, `/insert-many`, `/get-all`, `/get/:id`,
+`/get-by-ids`, `/get-by-filter`, `/update`, `/update-many`, `/bulk-upsert`, `/delete`.
 
-@Controller('auth')
-export class AuthController {
-  @Public()
-  @Post('login')
-  login() { }
-}
-```
+Security levels: `'public'` (no auth), `'jwt'` (token only), `'permission'` (token + action check).
 
-### @RequirePermission
-
-Require specific permission(s) - **AND logic** by default:
-
-```typescript
-import { RequirePermission } from '@flusys/nestjs-shared/decorators';
-
-@Controller('admin')
-export class AdminController {
-  // Requires 'admin.dashboard' permission
-  @RequirePermission('admin.dashboard')
-  @Post('dashboard')
-  getDashboard() { }
-
-  // Requires BOTH permissions
-  @RequirePermission('users.read', 'admin.access')
-  @Post('users')
-  getUsers() { }
-}
-```
-
-### @RequireAnyPermission
-
-Require any of the listed permissions - **OR logic**:
-
-```typescript
-import { RequireAnyPermission } from '@flusys/nestjs-shared/decorators';
-
-@Controller('reports')
-export class ReportsController {
-  // Requires 'reports.view' OR 'reports.admin'
-  @RequireAnyPermission('reports.view', 'reports.admin')
-  @Post()
-  getReports() { }
-}
-```
-
-### @RequirePermissionCondition
-
-Build complex permission conditions with nested AND/OR logic:
-
-```typescript
-import { RequirePermissionCondition } from '@flusys/nestjs-shared/decorators';
-
-@Controller('sensitive')
-export class SensitiveController {
-  // Complex: User needs 'users.read' AND ('admin' OR 'manager')
-  @RequirePermissionCondition({
-    operator: 'and',
-    permissions: ['users.read'],
-    children: [
-      { operator: 'or', permissions: ['admin', 'manager'] }
-    ]
-  })
-  @Post('complex')
-  getComplexData() { }
-}
-```
-
-### @SanitizeHtml / @SanitizeAndTrim
-
-Escape HTML entities for XSS prevention:
-
-```typescript
-import { SanitizeHtml, SanitizeAndTrim } from '@flusys/nestjs-shared/decorators';
-
-export class CreateCommentDto {
-  @SanitizeHtml()
-  @IsString()
-  content: string;
-
-  @SanitizeAndTrim()  // Escapes HTML AND trims whitespace
-  @IsString()
-  title: string;
-}
-```
-
-### @ApiResponseDto
-
-Generates Swagger schema for response:
-
-```typescript
-import { ApiResponseDto } from '@flusys/nestjs-shared/decorators';
-
-@Controller('users')
-export class UserController {
-  @Post('get-all')
-  @ApiResponseDto(UserResponseDto, true, 'list')  // Array with PaginationMetaDto
-  getAll() { }
-
-  @Post('insert')
-  @ApiResponseDto(UserResponseDto, false)  // Single item
-  insert() { }
-}
-```
-
----
-
-## Guards
-
-### JwtAuthGuard
-
-Validates JWT tokens for protected routes. Extends Passport's `AuthGuard('jwt')` and respects `@Public()` decorator.
+## 4. Guards and Decorators
 
 ```typescript
 import { JwtAuthGuard } from '@flusys/nestjs-shared/guards';
-
-// Apply globally in main.ts
-@Module({
-  providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }],
-})
-export class AppModule {}
-```
-
-**Important:** Constructor needs `@Inject(Reflector)` for bundled code.
-
-### PermissionGuard
-
-Checks user permissions from cache with AND/OR/nested logic support.
-
-```typescript
 import { PermissionGuard } from '@flusys/nestjs-shared/guards';
-
-@Module({
-  providers: [
-    { provide: APP_GUARD, useClass: PermissionGuard },
-    {
-      provide: 'PERMISSION_GUARD_CONFIG',
-      useValue: {
-        enableCompanyFeature: true,
-        userPermissionKeyFormat: 'permissions:user:{userId}',
-        companyPermissionKeyFormat: 'permissions:company:{companyId}:branch:{branchId}:user:{userId}',
-      },
-    },
-  ],
-})
-export class AppModule {}
-```
-
-**Cache Key Formats:**
-
-```typescript
-// Without company feature
-`permissions:user:{userId}`
-
-// With company feature
-`permissions:company:{companyId}:branch:{branchId}:user:{userId}`
-```
-
-### Permission Exceptions
-
-```typescript
 import {
-  InsufficientPermissionsException,  // 403 - Missing permissions
-  NoPermissionsFoundException,        // 403 - No permissions in cache
-  PermissionSystemUnavailableException, // 500 - Cache unavailable
-} from '@flusys/nestjs-shared/exceptions';
-```
-
----
+  CurrentUser,
+  Public,
+  RequirePermission,
+  RequireAnyPermission,
+} from '@flusys/nestjs-shared/decorators';
+import { ILoggedUserInfo } from '@flusys/nestjs-shared/interfaces';
 
-## Middleware
+@UseGuards(JwtAuthGuard, PermissionGuard)
+@RequirePermission('product.create')
+@Post('insert')
+async insert(@Body() dto: CreateProductDto, @CurrentUser() user: ILoggedUserInfo) { }
 
-### LoggerMiddleware
+// Mark endpoint public (no JWT required)
+@Public()
+@Post('public-list')
+async publicList() { }
+```
 
-Combined middleware for request correlation and HTTP logging.
+`ILoggedUserInfo` fields: `id`, `email`, `name?`, `phone?`, `profilePictureId?`, `companyId?`, `branchId?`.
 
-**Features:**
-- Request ID generation/tracking (UUID or from `x-request-id` header)
-- Tenant ID tracking (from `x-tenant-id` header)
-- AsyncLocalStorage context for thread-safe access
-- Automatic sensitive header redaction (authorization, cookie, x-api-key)
-- Performance monitoring (warns on requests > 3s)
-- Body truncation (max 1000 chars)
+## 5. Response DTOs
 
-**Usage:**
+All controllers return one of these shapes:
 
 ```typescript
-import { LoggerMiddleware } from '@flusys/nestjs-shared/middlewares';
+import {
+  SingleResponseDto, // insert, update, getById
+  ListResponseDto, // getAll, getByIds
+  BulkResponseDto, // insertMany, updateMany, bulkUpsert
+  MessageResponseDto, // delete
+} from '@flusys/nestjs-shared/dtos';
 
-@Module({})
-export class AppModule implements NestModule {
-  configure(consumer: MiddlewareConsumer) {
-    consumer.apply(LoggerMiddleware).forRoutes('*');
-  }
-}
+// All shapes include: success, message, messageKey (for i18n), _meta (requestId, timestamp, duration)
+// ListResponseDto / BulkResponseDto also include: meta (total, page, pageSize, count, totalPages)
 ```
 
-**Accessing Request Context:**
+## 6. Exceptions
 
 ```typescript
 import {
-  getRequestId,
-  getTenantId,
-  getUserId,
-  getCompanyId,
-  setUserId,
-  setCompanyId,
-} from '@flusys/nestjs-shared/middlewares';
+  NotFoundException,
+  ConflictException,
+  UnauthorizedException,
+  ForbiddenException,
+  ValidationException,
+  InternalServerException,
+} from '@flusys/nestjs-shared/exceptions';
 
-@Injectable()
-export class MyService {
-  async doSomething() {
-    const requestId = getRequestId();
-    const tenantId = getTenantId();
-    setUserId('user-123');
-  }
-}
+throw new NotFoundException({
+  message: 'User not found',
+  messageKey: USER_MESSAGES.NOT_FOUND,
+});
+throw new ConflictException({
+  message: `User already assigned to this ${typeName}. Please refresh and try again.`,
+  messageKey: USER_PERMISSION_MESSAGES.ALREADY_ASSIGNED,
+  messageVariables: { type: typeName },
+});
+throw new ValidationException([{ field: 'email', message: 'Invalid format' }]);
 ```
 
----
-
-## Interceptors
-
-### ResponseMetaInterceptor
+All exceptions produce: `{ success: false, message, messageKey,messageVariables:{} code, _meta }`.
 
-Adds `_meta` to all responses:
-
-```typescript
-// Response includes:
-{
-  "data": [...],
-  "_meta": {
-    "requestId": "abc-123",
-    "timestamp": "2024-01-01T00:00:00.000Z",
-    "responseTime": 45
-  }
-}
-```
-
-### IdempotencyInterceptor
-
-Prevents duplicate POST requests using `X-Idempotency-Key` header. Caches responses for 24 hours.
-
-### SetCreatedByOnBody / SetUpdateByOnBody / SetDeletedByOnBody
-
-Auto-set audit user IDs on request body from authenticated user.
-
-### DeleteEmptyIdFromBodyInterceptor
-
-Removes empty `id` fields from request body (single and array bodies).
-
-### QueryPerformanceInterceptor
-
-Monitors execution time and warns if request > 1000ms (configurable).
-
-### Slug Interceptor
-
-Auto-generates `slug` from `name` field using `UtilsService.transformToSlug()`.
-
----
-
-## Caching System
-
-### HybridCache
-
-Two-tier caching with in-memory (L1) and Redis (L2):
+## 7. Hybrid Cache
 
 ```typescript
 import { HybridCache } from '@flusys/nestjs-shared/classes';
@@ -671,531 +214,24 @@ export class MyService {
   constructor(@Inject('CACHE_INSTANCE') private cache: HybridCache) {}
 
   async getData(key: string) {
-    // Check cache first
     const cached = await this.cache.get(key);
     if (cached) return cached;
-
     const data = await this.fetchFromDb();
-    await this.cache.set(key, data, 3600);  // TTL in seconds
+    await this.cache.set(key, data, 3600); // TTL in seconds
     return data;
   }
 
   async invalidate(key: string) {
-    await this.cache.del(key);
+    await this.cache.delete(key);
   }
-
-  async invalidateAll() {
-    await this.cache.reset();      // Clear L1
-    await this.cache.resetL2();    // Clear L2 (Redis)
+  async invalidatePrefix(prefix: string) {
+    await this.cache.deleteByPrefix(prefix);
   }
 }
 ```
 
-### CacheModule Setup
-
-```typescript
-import { CacheModule } from '@flusys/nestjs-shared/modules';
-
-@Module({
-  imports: [
-    CacheModule.forRoot(
-      true,     // isGlobal
-      60_000,   // memoryTtl (ms)
-      5000      // memorySize (LRU max items)
-    ),
-  ],
-})
-export class AppModule {}
-```
-
-**Configuration via `USE_CACHE_LABEL` env:**
-- `'memory'` - L1 only
-- `'redis'` - L2 only
-- `'hybrid'` - Both (default)
-
----
-
-## Multi-Tenant DataSource
-
-Dynamic database connection management with connection pooling.
-
-### Setup
-
-```typescript
-import { DataSourceModule } from '@flusys/nestjs-shared/modules';
-
-@Module({
-  imports: [
-    DataSourceModule.forRoot({
-      bootstrapAppConfig: { databaseMode: 'multi-tenant' },
-      defaultDatabaseConfig: {
-        type: 'mysql',
-        host: 'localhost',
-        port: 3306,
-        username: 'root',
-        password: 'password',
-      },
-      tenants: [
-        { id: 'tenant1', database: 'tenant1_db' },
-        { id: 'tenant2', database: 'tenant2_db', host: 'other-server.com' },
-      ],
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-### MultiTenantDataSourceService
-
-| Method | Description |
-|--------|-------------|
-| `getDataSource()` | Get DataSource for current tenant (from header) |
-| `getDataSourceForTenant(id)` | Get DataSource for specific tenant |
-| `getRepository(entity)` | Get repository for current tenant |
-| `withTenant(id, callback)` | Execute callback with specific tenant |
-| `forAllTenants(callback)` | Execute callback for all tenants |
-| `registerTenant(config)` | Register new tenant at runtime |
-| `removeTenant(id)` | Remove tenant and close connection |
-| `getCurrentTenantId()` | Get tenant ID from request header |
-
----
-
-## DTOs
-
-### FilterAndPaginationDto
-
-```typescript
-import { FilterAndPaginationDto } from '@flusys/nestjs-shared/dtos';
-
-// Request body
-{
-  "filter": { "status": "active" },
-  "pagination": { "currentPage": 0, "pageSize": 10 },
-  "sort": { "createdAt": "DESC" },
-  "select": ["id", "name", "email"],
-  "withDeleted": false
-}
-```
-
-### DeleteDto
-
-```typescript
-import { DeleteDto } from '@flusys/nestjs-shared/dtos';
-
-// Soft delete
-{ "id": "uuid", "type": "delete" }
-
-// Restore
-{ "id": "uuid", "type": "restore" }
-
-// Permanent delete
-{ "id": "uuid", "type": "permanent" }
-
-// Multiple IDs
-{ "id": ["uuid1", "uuid2"], "type": "delete" }
-```
-
-### Response DTOs
-
-```typescript
-// Single item
-class SingleResponseDto<T> {
-  success: boolean;
-  message: string;
-  data?: T;
-  _meta?: RequestMetaDto;
-}
-
-// Paginated list
-class ListResponseDto<T> {
-  success: boolean;
-  message: string;
-  data?: T[];
-  meta: PaginationMetaDto;  // { total, page, pageSize, count, hasMore?, totalPages? }
-  _meta?: RequestMetaDto;
-}
-
-// Bulk operations
-class BulkResponseDto<T> {
-  success: boolean;
-  message: string;
-  data?: T[];
-  meta: BulkMetaDto;  // { count, failed?, total? }
-  _meta?: RequestMetaDto;
-}
-
-// Message only
-class MessageResponseDto {
-  success: boolean;
-  message: string;
-  _meta?: RequestMetaDto;
-}
-```
-
----
-
-## Base Entities
-
-### Identity Entity
-
-Base entity with UUID and timestamps:
-
-```typescript
-import { Identity } from '@flusys/nestjs-shared/entities';
-
-@Entity()
-export class Product extends Identity {
-  // Inherited: id, createdAt, updatedAt, deletedAt
-  // Inherited: createdById, updatedById, deletedById
-
-  @Column()
-  name: string;
-}
-```
-
-### UserRoot Entity
-
-Base user entity with common fields:
-
-```typescript
-import { UserRoot } from '@flusys/nestjs-shared/entities';
-
-@Entity()
-export class User extends UserRoot {
-  // Inherited: id, name, email, phone, profilePictureId
-  // Inherited: isActive, emailVerified, phoneVerified
-  // Inherited: lastLoginAt, additionalFields
-  // Inherited: createdAt, updatedAt, deletedAt
-}
-```
-
----
-
-## Utilities
-
-### Query Helpers
-
-```typescript
-import {
-  applyCompanyFilter,
-  buildCompanyWhereCondition,
-  hasCompanyId,
-  validateCompanyOwnership,
-} from '@flusys/nestjs-shared/utils';
-
-// Add company filter to TypeORM query
-applyCompanyFilter(query, {
-  isCompanyFeatureEnabled: true,
-  entityAlias: 'entity',
-}, user);
-
-// Build where condition for company
-const where = buildCompanyWhereCondition(baseWhere, user, isCompanyFeatureEnabled);
-
-// Validate entity belongs to user's company
-validateCompanyOwnership(entity, user, 'Entity');
-```
-
-### String Utilities
-
-```typescript
-import { generateSlug, generateUniqueSlug } from '@flusys/nestjs-shared/utils';
-
-// Generate URL-friendly slug
-const slug = generateSlug('My Product Name', 100);
-// Returns: 'my-product-name'
-
-// Generate unique slug with collision detection
-const uniqueSlug = await generateUniqueSlug(
-  'My Product',
-  async (pattern) => existingSlugs.filter(s => s.startsWith(pattern)),
-  100
-);
-```
-
-### Request Utilities
-
-```typescript
-import {
-  isBrowserRequest,
-  buildCookieOptions,
-  parseDurationToMs,
-} from '@flusys/nestjs-shared/utils';
-
-// Detect browser vs API client
-const isBrowser = isBrowserRequest(req);
-
-// Build secure cookie options
-const cookieOpts = buildCookieOptions(req);
-
-// Parse duration string
-const ms = parseDurationToMs('7d');  // 604800000
-```
-
-### HTML Sanitizer
-
-```typescript
-import { escapeHtml, escapeHtmlVariables } from '@flusys/nestjs-shared/utils';
-
-// Escape single string
-const safe = escapeHtml('<script>alert("xss")</script>');
-// Returns: '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
-
-// Escape all values in an object
-const safeVars = escapeHtmlVariables({
-  userName: '<script>evil</script>',
-  message: 'Hello, World!',
-});
-```
-
----
-
-## Error Handling
-
-### Error Handler Utilities
-
-```typescript
-import {
-  getErrorMessage,
-  logError,
-  rethrowError,
-  logAndRethrow,
-} from '@flusys/nestjs-shared/utils';
-
-interface IErrorContext {
-  operation?: string;
-  entity?: string;
-  userId?: string;
-  id?: string;
-  companyId?: string;
-  data?: Record<string, unknown>;
-}
-
-// Safe error message extraction
-const message = getErrorMessage(error);
-
-// Log with sensitive key redaction (password, secret, token, apiKey)
-logError(logger, error, 'createUser', { userId: user.id });
-
-// Type-safe rethrow
-rethrowError(error);
-
-// Combined log + rethrow
-logAndRethrow(logger, error, 'updateUser', context);
-```
-
----
-
-## Constants
-
-### Permission Constants
-
-```typescript
-import { PERMISSIONS } from '@flusys/nestjs-shared/constants';
-
-// Organized by module:
-PERMISSIONS.USER.CREATE     // 'user.create'
-PERMISSIONS.USER.READ       // 'user.read'
-PERMISSIONS.USER.UPDATE     // 'user.update'
-PERMISSIONS.USER.DELETE     // 'user.delete'
-
-PERMISSIONS.COMPANY.CREATE  // 'company.create'
-PERMISSIONS.BRANCH.CREATE   // 'branch.create'
-
-PERMISSIONS.ROLE.CREATE     // 'role.create'
-PERMISSIONS.FILE.CREATE     // 'file.create'
-PERMISSIONS.FOLDER.CREATE   // 'folder.create'
-// ...etc
-```
-
-### Injection Tokens
-
-```typescript
-'CACHE_INSTANCE'           // HybridCache provider
-'PERMISSION_GUARD_CONFIG'  // PermissionGuard config
-'LOGGER_INSTANCE'          // Logger provider
-```
+`CacheModule.forRoot(true)` connects to Redis automatically when `REDIS_URL` is set; otherwise uses in-memory only.
 
----
-
-## API Reference
-
-### Main Exports
-
-```typescript
-// Classes
-import {
-  ApiService,
-  RequestScopedApiService,
-  createApiController,
-  HybridCache,
-  WinstonLoggerAdapter,
-  NestLoggerAdapter,
-} from '@flusys/nestjs-shared/classes';
-
-// Decorators
-import {
-  CurrentUser,
-  Public,
-  RequirePermission,
-  RequireAnyPermission,
-  RequirePermissionCondition,
-  SanitizeHtml,
-  SanitizeAndTrim,
-  ApiResponseDto,
-} from '@flusys/nestjs-shared/decorators';
-
-// Guards
-import { JwtAuthGuard, PermissionGuard } from '@flusys/nestjs-shared/guards';
-
-// Interceptors
-import {
-  ResponseMetaInterceptor,
-  IdempotencyInterceptor,
-  SetCreatedByOnBody,
-  SetUpdateByOnBody,
-  SetDeletedByOnBody,
-  DeleteEmptyIdFromBodyInterceptor,
-  QueryPerformanceInterceptor,
-  Slug,
-} from '@flusys/nestjs-shared/interceptors';
-
-// Modules
-import {
-  CacheModule,
-  DataSourceModule,
-  UtilsModule,
-  UtilsService,
-  MultiTenantDataSourceService,
-} from '@flusys/nestjs-shared/modules';
-
-// DTOs
-import {
-  FilterAndPaginationDto,
-  PaginationDto,
-  DeleteDto,
-  GetByIdBodyDto,
-  SingleResponseDto,
-  ListResponseDto,
-  BulkResponseDto,
-  MessageResponseDto,
-  IdentityResponseDto,
-  PaginationMetaDto,
-  BulkMetaDto,
-  RequestMetaDto,
-} from '@flusys/nestjs-shared/dtos';
-
-// Entities
-import { Identity, UserRoot } from '@flusys/nestjs-shared/entities';
-
-// Interfaces
-import {
-  ILoggedUserInfo,
-  IService,
-  IDataSourceProvider,
-  IModuleConfigService,
-  ILogger,
-  PermissionCondition,
-  PermissionOperator,
-} from '@flusys/nestjs-shared/interfaces';
-
-// Utilities
-import {
-  getErrorMessage,
-  logError,
-  applyCompanyFilter,
-  buildCompanyWhereCondition,
-  validateCompanyOwnership,
-  generateSlug,
-  generateUniqueSlug,
-  isBrowserRequest,
-  buildCookieOptions,
-  parseDurationToMs,
-  escapeHtml,
-  escapeHtmlVariables,
-} from '@flusys/nestjs-shared/utils';
-
-// Middleware
-import {
-  LoggerMiddleware,
-  getRequestId,
-  getTenantId,
-  getUserId,
-  getCompanyId,
-  setUserId,
-  setCompanyId,
-} from '@flusys/nestjs-shared/middlewares';
-
-// Exceptions
-import {
-  InsufficientPermissionsException,
-  NoPermissionsFoundException,
-  PermissionSystemUnavailableException,
-} from '@flusys/nestjs-shared/exceptions';
-
-// Constants
-import { PERMISSIONS } from '@flusys/nestjs-shared/constants';
-```
-
----
-
-## Best Practices
-
-### 1. Use Generic Service Pattern
-
-```typescript
-// Extend ApiService for consistent CRUD
-@Injectable()
-export class ProductService extends ApiService<...> {
-  // Override hooks for customization
-}
-
-// For dynamic entities, use RequestScopedApiService
-@Injectable({ scope: Scope.REQUEST })
-export class RoleService extends RequestScopedApiService<...> { }
-```
-
-### 2. Always Use @Inject() Decorators
-
-Required for esbuild bundled code:
-
-```typescript
-// CORRECT
-constructor(
-  @Inject(MyService) private readonly myService: MyService,
-  @Inject('CACHE_INSTANCE') private readonly cache: HybridCache,
-) {}
-
-// WRONG - fails in bundled code
-constructor(private readonly myService: MyService) {}
-```
-
-### 3. Use Decorators Consistently
-
-```typescript
-// Use built-in decorators
-@CurrentUser() user: ILoggedUserInfo
-@RequirePermission('users.create')
-@Public()  // Use sparingly!
-
-// Don't access request directly
-@Req() req: Request  // Not type-safe
-```
-
-### 4. Configure Security at Controller Level
-
-```typescript
-// GOOD - configure in createApiController
-export class UserController extends createApiController(..., {
-  security: { insert: 'permission', ... },
-}) {}
-
-// AVOID - adding guards to each endpoint
-@UseGuards(JwtGuard)
-@Post('create')
-create() {}
-```
-
----
+## License
 
-**Last Updated:** 2026-02-21
+MIT © FLUSYS