@flusys/nestjs-shared 1.0.0-rc → 2.0.0-rc.0

package/README.md

@@ -8,9 +8,9 @@ This comprehensive guide covers the shared package - the shared NestJS infrastru
 ## Table of Contents
 
 - [Overview](#overview)
-- [Installation](#installation)
 - [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)
@@ -20,7 +20,9 @@ This comprehensive guide covers the shared package - the shared NestJS infrastru
 - [Multi-Tenant DataSource](#multi-tenant-datasource)
 - [DTOs](#dtos)
 - [Base Entities](#base-entities)
+- [Utilities](#utilities)
 - [Error Handling](#error-handling)
+- [Constants](#constants)
 - [API Reference](#api-reference)
 
 ---
@@ -30,34 +32,26 @@ This comprehensive guide covers the shared package - the shared NestJS infrastru
 `@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
-- **Caching** - In-memory + Redis hybrid caching
+- **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 utilities
+- **Error Handling** - Centralized error handling with sensitive data redaction
 
 ### 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
-```
-
----
-
-## Installation
-
-```bash
-npm install @flusys/nestjs-shared @flusys/nestjs-core
+@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
 ```
 
 ---
@@ -73,17 +67,19 @@ nestjs-shared/
 │   │   ├── 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 # Logger adapters
-│   │   └── index.ts
+│   │   ├── winston-logger-adapter.class.ts
+│   │   └── nest-logger-adapter.class.ts
 │   │
 │   ├── constants/            # Injection tokens & constants
+│   │   ├── permissions.ts                 # Permission constants
 │   │   └── index.ts
 │   │
 │   ├── decorators/           # Custom decorators
-│   │   ├── api-response.decorator.ts      # Swagger response decorator
-│   │   ├── current-user.decorator.ts
-│   │   ├── public.decorator.ts
-│   │   ├── require-permission.decorator.ts
+│   │   ├── api-response.decorator.ts      # @ApiResponseDto
+│   │   ├── current-user.decorator.ts      # @CurrentUser
+│   │   ├── public.decorator.ts            # @Public
+│   │   ├── require-permission.decorator.ts # @RequirePermission
+│   │   ├── sanitize.decorator.ts          # @SanitizeHtml, @SanitizeAndTrim
 │   │   └── index.ts
 │   │
 │   ├── dtos/                 # Shared DTOs
@@ -95,18 +91,16 @@ nestjs-shared/
 │   │   └── index.ts
 │   │
 │   ├── entities/             # Base entities
-│   │   ├── identity.ts
-│   │   ├── user-root.ts
+│   │   ├── identity.ts                    # Base entity with UUID
+│   │   ├── user-root.ts                   # Base user entity
 │   │   └── index.ts
 │   │
 │   ├── exceptions/           # Custom exceptions
-│   │   ├── permission.exception.ts
-│   │   └── index.ts
+│   │   └── permission.exception.ts        # Permission-related exceptions
 │   │
 │   ├── guards/               # Authentication & authorization
-│   │   ├── jwt-auth.guard.ts             # JWT token validation
-│   │   ├── permission.guard.ts           # Permission checks
-│   │   └── index.ts
+│   │   ├── jwt-auth.guard.ts              # JWT token validation
+│   │   └── permission.guard.ts            # Permission checks
 │   │
 │   ├── interceptors/         # Request/response interceptors
 │   │   ├── delete-empty-id-from-body.interceptor.ts
@@ -116,35 +110,34 @@ nestjs-shared/
 │   │   ├── set-create-by-on-body.interceptor.ts
 │   │   ├── set-delete-by-on-body.interceptor.ts
 │   │   ├── set-update-by-on-body.interceptor.ts
-│   │   ├── slug.interceptor.ts
-│   │   └── index.ts
+│   │   └── slug.interceptor.ts
 │   │
 │   ├── interfaces/           # TypeScript interfaces
-│   │   ├── api.interface.ts
+│   │   ├── api.interface.ts               # IService interface
 │   │   ├── identity.interface.ts
-│   │   ├── logged-user-info.interface.ts
-│   │   ├── logger.interface.ts
-│   │   ├── permission.interface.ts
-│   │   └── index.ts
+│   │   ├── logged-user-info.interface.ts  # ILoggedUserInfo
+│   │   ├── logger.interface.ts            # ILogger
+│   │   ├── permission.interface.ts        # PermissionCondition
+│   │   └── datasource-provider.interface.ts
 │   │
 │   ├── middlewares/          # Middleware
-│   │   ├── logger.middleware.ts          # Request logging & correlation
-│   │   └── index.ts
+│   │   └── logger.middleware.ts           # Request logging & correlation
 │   │
 │   ├── modules/              # NestJS modules
 │   │   ├── cache/cache.module.ts
 │   │   ├── datasource/
 │   │   │   ├── datasource.module.ts
-│   │   │   ├── multi-tenant-datasource.service.ts
-│   │   │   └── index.ts
-│   │   ├── utils/
-│   │   │   ├── utils.module.ts
-│   │   │   └── utils.service.ts
-│   │   └── index.ts
+│   │   │   └── multi-tenant-datasource.service.ts
+│   │   └── utils/
+│   │       ├── utils.module.ts
+│   │       └── utils.service.ts
 │   │
 │   └── utils/                # Utility functions
 │       ├── error-handler.util.ts
-│       └── index.ts
+│       ├── query-helpers.util.ts
+│       ├── string.util.ts
+│       ├── request.util.ts
+│       └── html-sanitizer.util.ts
 ```
 
 ---
@@ -159,11 +152,7 @@ The `ApiService` base class provides standardized CRUD operations with caching,
 import { ApiService, HybridCache } from '@flusys/nestjs-shared/classes';
 import { UtilsService } from '@flusys/nestjs-shared/modules';
 import { Injectable, Inject } from '@nestjs/common';
-import { InjectRepository } from '@nestjs/typeorm';
 import { Repository } from 'typeorm';
-import { User } from './user.entity';
-import { CreateUserDto, UpdateUserDto } from './user.dto';
-import { IUser } from './user.interface';
 
 @Injectable()
 export class UserService extends ApiService<
@@ -178,6 +167,7 @@ export class UserService extends ApiService<
     protected override repository: Repository<User>,
     @Inject('CACHE_INSTANCE')
     protected override cacheManager: HybridCache,
+    @Inject(UtilsService)
     protected override utilsService: UtilsService,
   ) {
     super(
@@ -189,30 +179,6 @@ export class UserService extends ApiService<
       true,                // Enable caching
     );
   }
-
-  // Override to customize DTO to entity conversion
-  override async convertSingleDtoToEntity(
-    dto: CreateUserDto | UpdateUserDto,
-    user: ILoggedUserInfo,
-  ): Promise<User> {
-    const entity = new User();
-    Object.assign(entity, dto);
-    return entity;
-  }
-
-  // Override to customize query selection
-  override async getSelectQuery(
-    query: SelectQueryBuilder<User>,
-    user: ILoggedUserInfo,
-    select?: string[],
-  ) {
-    if (!select?.length) {
-      select = ['id', 'name', 'email', 'createdAt'];
-    }
-    const selectFields = select.map(f => `${this.entityName}.${f}`);
-    query.select(selectFields);
-    return { query, isRaw: false };
-  }
 }
 ```
 
@@ -224,11 +190,11 @@ export class UserService extends ApiService<
 | `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 |
-| `restore(dto, user)` | Restore soft-deleted |
+| `delete(dto, user)` | Soft/permanent delete or restore |
 
 ### Customization Hooks
 
@@ -244,6 +210,12 @@ export class UserService extends ApiService<...> {
   // 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 }> { }
 
@@ -267,32 +239,61 @@ export class UserService extends ApiService<...> {
 }
 ```
 
-### Company/Branch Filtering Example
+---
+
+## RequestScopedApiService
+
+For dynamic entity resolution based on runtime configuration (e.g., company feature).
 
 ```typescript
-override async getExtraManipulateQuery(
-  query: SelectQueryBuilder<User>,
-  dto: FilterAndPaginationDto,
-  user: ILoggedUserInfo,
-) {
-  // Filter by user's company
-  if (user.companyId) {
-    query.andWhere(`${this.entityName}.companyId = :companyId`, {
-      companyId: user.companyId,
-    });
+import { RequestScopedApiService } from '@flusys/nestjs-shared/classes';
+import { Injectable, Scope, Inject } from '@nestjs/common';
+import { EntityTarget, Repository } from 'typeorm';
+
+@Injectable({ scope: Scope.REQUEST })
+export class RoleService extends RequestScopedApiService<
+  CreateRoleDto,
+  UpdateRoleDto,
+  IRole,
+  RoleBase,
+  Repository<RoleBase>
+> {
+  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,
+  ) {
+    // Pass null for repository - will be initialized dynamically
+    super('role', null as any, cacheManager, utilsService, 'RoleService', true);
+  }
+
+  // Required: Resolve which entity to use
+  protected resolveEntity(): EntityTarget<RoleBase> {
+    return this.config.isCompanyFeatureEnabled() ? RoleWithCompany : Role;
   }
 
-  // Filter by user's branch
-  if (user.branchId) {
-    query.andWhere(`${this.entityName}.branchId = :branchId`, {
-      branchId: user.branchId,
-    });
+  // Required: Return the DataSource provider
+  protected getDataSourceProvider(): IDataSourceProvider {
+    return this.provider;
   }
 
-  return { query, isRaw: false };
+  // Optional: Initialize additional repositories
+  protected async initializeAdditionalRepositories(): Promise<void> {
+    this.actionRepository = await this.dataSourceProvider.getRepository(Action);
+  }
 }
 ```
 
+### 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
@@ -303,11 +304,8 @@ The `createApiController` factory creates standardized POST-only RPC controllers
 
 ```typescript
 import { createApiController } from '@flusys/nestjs-shared/classes';
-import { Controller } from '@nestjs/common';
+import { Controller, Inject } from '@nestjs/common';
 import { ApiTags } from '@nestjs/swagger';
-import { CreateUserDto, UpdateUserDto, UserResponseDto } from './user.dto';
-import { IUser } from './user.interface';
-import { UserService } from './user.service';
 
 @ApiTags('Users')
 @Controller('users')
@@ -318,7 +316,7 @@ export class UserController extends createApiController<
   IUser,
   UserService
 >(CreateUserDto, UpdateUserDto, UserResponseDto) {
-  constructor(protected service: UserService) {
+  constructor(@Inject(UserService) protected service: UserService) {
     super(service);
   }
 }
@@ -345,9 +343,7 @@ export class UserController extends createApiController(
   CreateUserDto,
   UpdateUserDto,
   UserResponseDto,
-  {
-    security: 'jwt',  // All endpoints require JWT
-  },
+  { security: 'jwt' },  // All endpoints require JWT
 ) {}
 
 // Per-endpoint security
@@ -366,29 +362,8 @@ export class UserController extends createApiController(
     },
   },
 ) {}
-
-// Permission combinations
-{
-  security: {
-    // Require ANY of these permissions
-    insert: {
-      level: 'permission',
-      permissions: ['users.create', 'users.admin'],
-      require: 'any',  // Default
-    },
-
-    // Require ALL permissions
-    delete: {
-      level: 'permission',
-      permissions: ['users.delete', 'users.admin'],
-      require: 'all',
-    },
-  },
-}
 ```
 
-See [API-CONTROLLER-SECURITY.md](./API-CONTROLLER-SECURITY.md) for detailed security configuration.
-
 ---
 
 ## Decorators
@@ -403,16 +378,22 @@ import { ILoggedUserInfo } from '@flusys/nestjs-shared/interfaces';
 
 @Controller('profile')
 export class ProfileController {
-  @Get()
+  @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 };
+  }
 }
 ```
 
 ### @Public
 
-Mark route as public (skip authentication):
+Mark route as public (skip authentication). **Use sparingly - security risk**.
 
 ```typescript
 import { Public } from '@flusys/nestjs-shared/decorators';
@@ -421,43 +402,44 @@ import { Public } from '@flusys/nestjs-shared/decorators';
 export class AuthController {
   @Public()
   @Post('login')
-  login() {
-    // No JWT required
-  }
+  login() { }
 }
 ```
 
 ### @RequirePermission
 
-Require specific permission:
+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')
-  @Get('dashboard')
-  getDashboard() {
-    // Requires 'admin.dashboard' permission
-  }
+  @Post('dashboard')
+  getDashboard() { }
+
+  // Requires BOTH permissions
+  @RequirePermission('users.read', 'admin.access')
+  @Post('users')
+  getUsers() { }
 }
 ```
 
 ### @RequireAnyPermission
 
-Require any of the listed permissions:
+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')
-  @Get()
-  getReports() {
-    // Requires 'reports.view' OR 'reports.admin'
-  }
+  @Post()
+  getReports() { }
 }
 ```
 
@@ -470,14 +452,6 @@ import { RequirePermissionCondition } from '@flusys/nestjs-shared/decorators';
 
 @Controller('sensitive')
 export class SensitiveController {
-  // Simple: User needs 'admin' OR 'manager'
-  @RequirePermissionCondition({
-    operator: 'or',
-    permissions: ['admin', 'manager'],
-  })
-  @Get('simple')
-  getSimpleData() {}
-
   // Complex: User needs 'users.read' AND ('admin' OR 'manager')
   @RequirePermissionCondition({
     operator: 'and',
@@ -486,33 +460,52 @@ export class SensitiveController {
       { operator: 'or', permissions: ['admin', 'manager'] }
     ]
   })
-  @Get('complex')
-  getComplexData() {}
+  @Post('complex')
+  getComplexData() { }
+}
+```
 
-  // Very complex: (A AND B) OR (C AND D)
-  @RequirePermissionCondition({
-    operator: 'or',
-    children: [
-      { operator: 'and', permissions: ['finance.read', 'finance.write'] },
-      { operator: 'and', permissions: ['admin.full', 'reports.access'] }
-    ]
-  })
-  @Get('very-complex')
-  getVeryComplexData() {}
+### @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;
 }
 ```
 
-**Note:** For simple "require ALL permissions" use case, use `@RequirePermission` which defaults to AND logic:
+### @ApiResponseDto
+
+Generates Swagger schema for response:
+
 ```typescript
-@RequirePermission('admin.access', 'security.clearance')  // User needs BOTH
+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
 
-The shared package provides two guards for authentication and authorization:
-
 ### JwtAuthGuard
 
 Validates JWT tokens for protected routes. Extends Passport's `AuthGuard('jwt')` and respects `@Public()` decorator.
@@ -520,22 +513,15 @@ Validates JWT tokens for protected routes. Extends Passport's `AuthGuard('jwt')`
 ```typescript
 import { JwtAuthGuard } from '@flusys/nestjs-shared/guards';
 
-// Apply globally
+// Apply globally in main.ts
 @Module({
   providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }],
 })
 export class AppModule {}
-
-// Or per controller
-@Controller('users')
-@UseGuards(JwtAuthGuard)
-export class UserController {
-  @Post('login')
-  @Public()  // Skip JWT check
-  async login() { }
-}
 ```
 
+**Important:** Constructor needs `@Inject(Reflector)` for bundled code.
+
 ### PermissionGuard
 
 Checks user permissions from cache with AND/OR/nested logic support.
@@ -543,9 +529,18 @@ Checks user permissions from cache with AND/OR/nested logic support.
 ```typescript
 import { PermissionGuard } from '@flusys/nestjs-shared/guards';
 
-// Apply globally
 @Module({
-  providers: [{ provide: APP_GUARD, useClass: PermissionGuard }],
+  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 {}
 ```
@@ -560,11 +555,15 @@ export class AppModule {}
 `permissions:company:{companyId}:branch:{branchId}:user:{userId}`
 ```
 
-**Features:**
-- Supports AND/OR operators via `@RequirePermission` and `@RequireAnyPermission`
-- Nested conditions via `@RequirePermissionCondition`
-- Wildcard support (`*` and `*.suffix`)
-- Company/branch scoped permissions
+### Permission Exceptions
+
+```typescript
+import {
+  InsufficientPermissionsException,  // 403 - Missing permissions
+  NoPermissionsFoundException,        // 403 - No permissions in cache
+  PermissionSystemUnavailableException, // 500 - Cache unavailable
+} from '@flusys/nestjs-shared/exceptions';
+```
 
 ---
 
@@ -572,39 +571,24 @@ export class AppModule {}
 
 ### LoggerMiddleware
 
-**Location:** `@flusys/nestjs-shared/middlewares/logger.middleware.ts`
-
-Combined middleware that handles:
-1. **Request Correlation** - Tracks requests across services using AsyncLocalStorage
-2. **HTTP Request/Response Logging** - Structured logging with Winston
-3. **Detailed Request/Response Information** - Complete visibility into all requests
-
-**Key Features:**
-- **Request ID Generation** - Automatic UUID generation or uses `x-request-id` header
-- **Tenant ID Tracking** - Extracts `x-tenant-id` from headers for multi-tenant apps
-- **AsyncLocalStorage Context** - Thread-safe request context accessible anywhere
-- **Security** - Automatically redacts sensitive headers (authorization, cookie, x-api-key)
-- **Performance Monitoring** - Logs slow requests (>3s) with dedicated warning logs
-- **Body Truncation** - Limits log size to 1000 characters
-- **Debug Mode** - Conditionally logs headers and body based on LOG_LEVEL=debug
-- **Complete Request Details** - URL, path, query params, content type, user agent, client IP
-- **Complete Response Details** - Status code, message, content type, content length, user/company context
-- **Multiple Response Hooks** - Captures responses via `res.send()`, `res.json()`, and `res.end()`
-- **Error Handling** - Logs response errors with stack traces
-- **User Context** - Automatically includes userId and companyId in response logs if available
+Combined middleware for request correlation and HTTP logging.
+
+**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)
 
 **Usage:**
 
 ```typescript
 import { LoggerMiddleware } from '@flusys/nestjs-shared/middlewares';
-import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
 
-@Module({
-  // ...
-})
+@Module({})
 export class AppModule implements NestModule {
   configure(consumer: MiddlewareConsumer) {
-    // Apply to all routes
     consumer.apply(LoggerMiddleware).forRoutes('*');
   }
 }
@@ -625,195 +609,28 @@ import {
 @Injectable()
 export class MyService {
   async doSomething() {
-    const requestId = getRequestId(); // Get current request ID
-    const tenantId = getTenantId();   // Get tenant ID from header
-
-    // Set user context after authentication
+    const requestId = getRequestId();
+    const tenantId = getTenantId();
     setUserId('user-123');
-    setCompanyId('company-456');
-
-    // Use in logs
-    this.logger.info('Processing request', {
-      requestId,
-      tenantId,
-      userId: getUserId(),
-      companyId: getCompanyId(),
-    });
   }
 }
 ```
 
-**Request Context Interface:**
-
-```typescript
-interface IRequestContext {
-  requestId: string;      // UUID or from x-request-id header
-  tenantId?: string;      // From x-tenant-id header
-  userId?: string;        // Set after authentication
-  companyId?: string;     // Set after authentication
-  startTime: number;      // Request start timestamp
-}
-```
-
-**Configuration:**
-
-```typescript
-// Environment-based configuration
-const IS_DEBUG = envConfig.getLogConfig().level === 'debug';
-const TENANT_ID_HEADER = 'x-tenant-id';
-const EXCLUDED_PATHS = ['/health', '/metrics', '/favicon.ico'];
-const EXCLUDED_HEADERS = ['authorization', 'cookie', 'x-api-key'];
-const MAX_BODY_LOG_SIZE = 1000;
-```
-
-**Console Log Format (Development):**
-
-The development console logger displays HTTP requests in human-readable format:
-
-```
-2026-01-17 22:41:23 [INFO   ] [HTTP] [POST /auth/login] [200] (45ms) [uuid] Incoming request
-2026-01-17 22:41:23 [INFO   ] [HTTP] [POST /auth/login] [200] (45ms) [uuid] (user:user-123) Response [200]
-2026-01-17 22:41:25 [WARN   ] [HTTP] [GET /api/users] [404] (12ms) [uuid] Response [404]
-2026-01-17 22:41:30 [ERROR  ] [HTTP] [POST /api/orders] [500] (234ms) [uuid] (user:user-123) Response [500]
-```
-
-**Format Structure:**
-- `[timestamp]` - Request timestamp
-- `[level]` - Log level (INFO, WARN, ERROR)
-- `[context]` - Always "HTTP" for HTTP requests
-- `[METHOD /path]` - HTTP method and endpoint path
-- `[statusCode]` - HTTP response status (only in response logs)
-- `(duration)` - Request duration (only in response logs)
-- `[uuid]` - Request correlation ID
-- `(user:userId)` - User ID if authenticated (only in response logs)
-
-**File Log Format (Production):**
-
-```json
-// Incoming request (Enhanced with full details)
-{
-  "level": "info",
-  "message": "Incoming request",
-  "context": "HTTP",
-  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "tenantId": "tenant-123",
-  "method": "POST",
-  "url": "/api/users/insert?sort=name",
-  "path": "/api/users/insert",
-  "query": { "sort": "name" },
-  "ip": "192.168.1.100",
-  "userAgent": "Mozilla/5.0...",
-  "contentType": "application/json",
-  "contentLength": "342",
-  "headers": { ... },  // Only in debug mode
-  "body": { ... },     // Only in debug mode, truncated to 1000 chars
-  "params": { ... }    // Only in debug mode (route params)
-}
-
-// Response (Enhanced with full details)
-{
-  "level": "info",
-  "message": "Response [200]",
-  "context": "HTTP",
-  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "tenantId": "tenant-123",
-  "method": "POST",
-  "url": "/api/users/insert?sort=name",
-  "path": "/api/users/insert",
-  "statusCode": 200,
-  "statusMessage": "OK",
-  "duration": "125ms",
-  "durationMs": 125,
-  "contentType": "application/json; charset=utf-8",
-  "contentLength": "156",
-  "userId": "user-456",      // Automatically added if available
-  "companyId": "company-789" // Automatically added if available
-}
-
-// Error response (includes response body automatically)
-{
-  "level": "warn",
-  "message": "Response [400]",
-  "context": "HTTP",
-  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "tenantId": "tenant-123",
-  "method": "POST",
-  "url": "/api/users/insert",
-  "path": "/api/users/insert",
-  "statusCode": 400,
-  "statusMessage": "Bad Request",
-  "duration": "45ms",
-  "durationMs": 45,
-  "userId": "user-456",
-  "companyId": "company-789",
-  "responseBody": {
-    "statusCode": 400,
-    "message": "Validation failed",
-    "errors": ["Email is required"]
-  }
-}
-
-// Slow request warning (Enhanced with more context)
-{
-  "level": "warn",
-  "message": "Slow request detected",
-  "context": "HTTP",
-  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "tenantId": "tenant-123",
-  "userId": "user-456",
-  "companyId": "company-789",
-  "method": "POST",
-  "url": "/api/reports/generate",
-  "path": "/api/reports/generate",
-  "duration": "3245ms",
-  "durationMs": 3245,
-  "threshold": "3000ms"
-}
-
-// Response error
-{
-  "level": "error",
-  "message": "Response error",
-  "context": "HTTP",
-  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "tenantId": "tenant-123",
-  "method": "POST",
-  "url": "/api/users/insert",
-  "path": "/api/users/insert",
-  "error": "Socket hang up",
-  "stack": "Error: Socket hang up\n  at ..."
-}
-```
-
-**Benefits:**
-
-- **Request Tracing** - Correlate logs across multiple services using requestId
-- **Multi-Tenant Support** - Automatic tenant isolation in logs
-- **Security** - Sensitive data automatically redacted
-- **Performance Monitoring** - Identify slow endpoints
-- **Debugging** - Conditional verbose logging
-
 ---
 
 ## Interceptors
 
 ### ResponseMetaInterceptor
 
-Adds request metadata to responses:
+Adds `_meta` to all responses:
 
 ```typescript
-import { ResponseMetaInterceptor } from '@flusys/nestjs-shared/interceptors';
-
-@UseInterceptors(ResponseMetaInterceptor)
-@Controller('users')
-export class UserController {}
-
-// Response:
+// Response includes:
 {
   "data": [...],
-  "meta": {
-    "timestamp": "2024-01-01T00:00:00.000Z",
+  "_meta": {
     "requestId": "abc-123",
+    "timestamp": "2024-01-01T00:00:00.000Z",
     "responseTime": 45
   }
 }
@@ -821,63 +638,23 @@ export class UserController {}
 
 ### IdempotencyInterceptor
 
-Prevent duplicate requests:
+Prevents duplicate POST requests using `X-Idempotency-Key` header. Caches responses for 24 hours.
 
-```typescript
-import { IdempotencyInterceptor } from '@flusys/nestjs-shared/interceptors';
+### SetCreatedByOnBody / SetUpdateByOnBody / SetDeletedByOnBody
 
-@UseInterceptors(IdempotencyInterceptor)
-@Controller('payments')
-export class PaymentController {
-  @Post()
-  // Clients send X-Idempotency-Key header
-  // Duplicate requests return cached response
-  processPayment() {}
-}
-```
+Auto-set audit user IDs on request body from authenticated user.
 
-### SetCreatedByOnBody / SetUpdateByOnBody
+### DeleteEmptyIdFromBodyInterceptor
 
-Auto-set user IDs on request body:
+Removes empty `id` fields from request body (single and array bodies).
 
-```typescript
-import { SetCreatedByOnBody, SetUpdateByOnBody } from '@flusys/nestjs-shared/interceptors';
-
-@Controller('posts')
-export class PostController {
-  @UseInterceptors(SetCreatedByOnBody)
-  @Post()
-  create(@Body() dto: CreatePostDto) {
-    // dto.createdById is automatically set to current user ID
-  }
+### QueryPerformanceInterceptor
 
-  @UseInterceptors(SetUpdateByOnBody)
-  @Put()
-  update(@Body() dto: UpdatePostDto) {
-    // dto.updatedById is automatically set to current user ID
-  }
-}
-```
+Monitors execution time and warns if request > 1000ms (configurable).
 
 ### Slug Interceptor
 
-Auto-generate slugs from name field using UtilsService (injected via DI):
-
-```typescript
-import { Slug } from '@flusys/nestjs-shared/interceptors';
-
-@Controller('products')
-export class ProductController {
-  @UseInterceptors(Slug)
-  @Post()
-  create(@Body() dto: CreateProductDto) {
-    // dto.slug is auto-generated from dto.name
-    // "My Product" -> "my-product"
-  }
-}
-```
-
-**Note:** Requires `UtilsModule` to be imported in your module for dependency injection.
+Auto-generates `slug` from `name` field using `UtilsService.transformToSlug()`.
 
 ---
 
@@ -885,29 +662,22 @@ export class ProductController {
 
 ### HybridCache
 
-Two-tier caching with in-memory (fast) and Redis (distributed):
+Two-tier caching with in-memory (L1) and Redis (L2):
 
 ```typescript
 import { HybridCache } from '@flusys/nestjs-shared/classes';
 
 @Injectable()
 export class MyService {
-  constructor(
-    @Inject('CACHE_INSTANCE')
-    private cache: HybridCache,
-  ) {}
+  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;
 
-    // Fetch from database
     const data = await this.fetchFromDb();
-
-    // Store in cache (TTL in seconds)
-    await this.cache.set(key, data, 3600);
-
+    await this.cache.set(key, data, 3600);  // TTL in seconds
     return data;
   }
 
@@ -915,9 +685,9 @@ export class MyService {
     await this.cache.del(key);
   }
 
-  async invalidatePattern(pattern: string) {
-    // Delete all keys matching pattern
-    await this.cache.delByPattern('users:*');
+  async invalidateAll() {
+    await this.cache.reset();      // Clear L1
+    await this.cache.resetL2();    // Clear L2 (Redis)
   }
 }
 ```
@@ -929,40 +699,26 @@ import { CacheModule } from '@flusys/nestjs-shared/modules';
 
 @Module({
   imports: [
-    CacheModule.forRoot({
-      // In-memory cache config
-      memory: {
-        max: 500,           // Max items
-        ttl: 3600,          // Default TTL (seconds)
-      },
-
-      // Redis config (optional)
-      redis: {
-        url: 'redis://localhost:6379',
-        ttl: 3600,
-      },
-    }),
+    CacheModule.forRoot(
+      true,     // isGlobal
+      60_000,   // memoryTtl (ms)
+      5000      // memorySize (LRU max items)
+    ),
   ],
 })
 export class AppModule {}
 ```
 
-### Cache Methods
-
-| Method | Description |
-|--------|-------------|
-| `get(key)` | Get cached value |
-| `set(key, value, ttl?)` | Set value with optional TTL |
-| `del(key)` | Delete single key |
-| `delByPattern(pattern)` | Delete keys matching pattern |
-| `reset()` | Clear all cache |
-| `has(key)` | Check if key exists |
+**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 and request-scoped tenant resolution.
+Dynamic database connection management with connection pooling.
 
 ### Setup
 
@@ -982,7 +738,7 @@ import { DataSourceModule } from '@flusys/nestjs-shared/modules';
       },
       tenants: [
         { id: 'tenant1', database: 'tenant1_db' },
-        { id: 'tenant2', database: 'tenant2_db' },
+        { id: 'tenant2', database: 'tenant2_db', host: 'other-server.com' },
       ],
     }),
   ],
@@ -990,38 +746,18 @@ import { DataSourceModule } from '@flusys/nestjs-shared/modules';
 export class AppModule {}
 ```
 
-### Key Methods
+### 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 DataSource |
-| `forAllTenants(callback)` | Execute callback for all active tenants |
+| `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 |
-
-### Usage
-
-```typescript
-@Injectable()
-export class TenantService {
-  constructor(private dataSource: MultiTenantDataSourceService) {}
-
-  async getUsers() {
-    // Auto-resolves tenant from X-Tenant-ID header
-    const repo = await this.dataSource.getRepository(User);
-    return repo.find();
-  }
-
-  async crossTenantCopy(fromId: string, toId: string) {
-    const fromDs = await this.dataSource.getDataSourceForTenant(fromId);
-    const toDs = await this.dataSource.getDataSourceForTenant(toId);
-    // Copy data between tenants
-  }
-}
-```
+| `getCurrentTenantId()` | Get tenant ID from request header |
 
 ---
 
@@ -1029,89 +765,71 @@ export class TenantService {
 
 ### FilterAndPaginationDto
 
-Standard filtering and pagination:
-
 ```typescript
 import { FilterAndPaginationDto } from '@flusys/nestjs-shared/dtos';
 
 // Request body
 {
-  "filter": {
-    "status": "active",
-    "category": "electronics"
-  },
-  "pagination": {
-    "currentPage": 0,
-    "pageSize": 10
-  },
-  "sort": {
-    "createdAt": "DESC",
-    "name": "ASC"
-  },
-  "select": ["id", "name", "price"],
+  "filter": { "status": "active" },
+  "pagination": { "currentPage": 0, "pageSize": 10 },
+  "sort": { "createdAt": "DESC" },
+  "select": ["id", "name", "email"],
   "withDeleted": false
 }
 ```
 
 ### DeleteDto
 
-Soft or permanent delete:
-
 ```typescript
 import { DeleteDto } from '@flusys/nestjs-shared/dtos';
 
-// Soft delete (sets deletedAt)
-{
-  "id": "user-123",
-  "type": "soft"
-}
+// Soft delete
+{ "id": "uuid", "type": "delete" }
+
+// Restore
+{ "id": "uuid", "type": "restore" }
 
 // Permanent delete
-{
-  "id": "user-123",
-  "type": "permanent"
-}
+{ "id": "uuid", "type": "permanent" }
 
 // Multiple IDs
-{
-  "id": ["user-123", "user-456"],
-  "type": "soft"
-}
+{ "id": ["uuid1", "uuid2"], "type": "delete" }
 ```
 
-### ResponsePayloadDto
-
-Standardized response format:
+### Response DTOs
 
 ```typescript
-import { ResponsePayloadDto } from '@flusys/nestjs-shared/dtos';
+// Single item
+class SingleResponseDto<T> {
+  success: boolean;
+  message: string;
+  data?: T;
+  _meta?: RequestMetaDto;
+}
 
-// Success response
-{
-  "success": true,
-  "data": { ... },
-  "message": "Operation successful"
+// Paginated list
+class ListResponseDto<T> {
+  success: boolean;
+  message: string;
+  data?: T[];
+  meta: PaginationMetaDto;  // { total, page, pageSize, count, hasMore?, totalPages? }
+  _meta?: RequestMetaDto;
 }
 
-// Paginated response
-{
-  "success": true,
-  "data": [...],
-  "pagination": {
-    "total": 100,
-    "page": 1,
-    "limit": 10,
-    "totalPages": 10
-  }
+// Bulk operations
+class BulkResponseDto<T> {
+  success: boolean;
+  message: string;
+  data?: T[];
+  meta: BulkMetaDto;  // { count, failed?, total? }
+  _meta?: RequestMetaDto;
 }
 
-// Error response
-{
-  "success": false,
-  "error": {
-    "code": "VALIDATION_ERROR",
-    "message": "Invalid input"
-  }
+// Message only
+class MessageResponseDto {
+  success: boolean;
+  message: string;
+  _meta?: RequestMetaDto;
 }
 ```
 
@@ -1129,65 +847,174 @@ 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;
-
-  @Column()
-  price: number;
 }
 ```
 
 ### UserRoot Entity
 
-Base user 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, password, phone, isActive, createdAt, updatedAt, deletedAt
-
-  @Column({ nullable: true })
-  customField: string;
+  // Inherited: id, name, email, phone, profilePictureId
+  // Inherited: isActive, emailVerified, phoneVerified
+  // Inherited: lastLoginAt, additionalFields
+  // Inherited: createdAt, updatedAt, deletedAt
 }
 ```
 
 ---
 
-## Error Handling
+## Utilities
+
+### Query Helpers
 
-### ErrorHandler
+```typescript
+import {
+  applyCompanyFilter,
+  buildCompanyWhereCondition,
+  hasCompanyId,
+  validateCompanyOwnership,
+} from '@flusys/nestjs-shared/utils';
 
-Centralized error handling utility:
+// 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 { ErrorHandler } from '@flusys/nestjs-shared/utils';
+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
+);
+```
 
-@Injectable()
-export class UserService {
-  async createUser(dto: CreateUserDto) {
-    try {
-      return await this.repository.save(dto);
-    } catch (error) {
-      // Handles TypeORM errors, validation errors, etc.
-      throw ErrorHandler.handle(error, 'Failed to create user');
-    }
-  }
+### 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);
 ```
 
-### Error Types
+---
+
+## Constants
+
+### Permission Constants
 
 ```typescript
-// Automatically converted to appropriate HTTP exception:
+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
+```
 
-// TypeORM unique constraint → ConflictException (409)
-// TypeORM foreign key → BadRequestException (400)
-// Validation error → BadRequestException (400)
-// Not found → NotFoundException (404)
-// Unknown → InternalServerErrorException (500)
+### Injection Tokens
+
+```typescript
+'CACHE_INSTANCE'           // HybridCache provider
+'PERMISSION_GUARD_CONFIG'  // PermissionGuard config
+'LOGGER_INSTANCE'          // Logger provider
 ```
 
 ---
@@ -1200,8 +1027,11 @@ export class UserService {
 // Classes
 import {
   ApiService,
+  RequestScopedApiService,
   createApiController,
   HybridCache,
+  WinstonLoggerAdapter,
+  NestLoggerAdapter,
 } from '@flusys/nestjs-shared/classes';
 
 // Decorators
@@ -1211,13 +1041,13 @@ import {
   RequirePermission,
   RequireAnyPermission,
   RequirePermissionCondition,
+  SanitizeHtml,
+  SanitizeAndTrim,
+  ApiResponseDto,
 } from '@flusys/nestjs-shared/decorators';
 
 // Guards
-import {
-  JwtAuthGuard,
-  PermissionGuard,
-} from '@flusys/nestjs-shared/guards';
+import { JwtAuthGuard, PermissionGuard } from '@flusys/nestjs-shared/guards';
 
 // Interceptors
 import {
@@ -1225,6 +1055,9 @@ import {
   IdempotencyInterceptor,
   SetCreatedByOnBody,
   SetUpdateByOnBody,
+  SetDeletedByOnBody,
+  DeleteEmptyIdFromBodyInterceptor,
+  QueryPerformanceInterceptor,
   Slug,
 } from '@flusys/nestjs-shared/interceptors';
 
@@ -1233,31 +1066,76 @@ import {
   CacheModule,
   DataSourceModule,
   UtilsModule,
+  UtilsService,
+  MultiTenantDataSourceService,
 } from '@flusys/nestjs-shared/modules';
 
 // DTOs
 import {
   FilterAndPaginationDto,
+  PaginationDto,
   DeleteDto,
-  ResponsePayloadDto,
+  GetByIdBodyDto,
+  SingleResponseDto,
+  ListResponseDto,
+  BulkResponseDto,
+  MessageResponseDto,
+  IdentityResponseDto,
+  PaginationMetaDto,
+  BulkMetaDto,
+  RequestMetaDto,
 } from '@flusys/nestjs-shared/dtos';
 
 // Entities
-import {
-  Identity,
-  UserRoot,
-} from '@flusys/nestjs-shared/entities';
+import { Identity, UserRoot } from '@flusys/nestjs-shared/entities';
 
 // Interfaces
 import {
   ILoggedUserInfo,
-  IPermissionConfig,
+  IService,
+  IDataSourceProvider,
+  IModuleConfigService,
+  ILogger,
+  PermissionCondition,
+  PermissionOperator,
 } from '@flusys/nestjs-shared/interfaces';
 
 // Utilities
 import {
-  ErrorHandler,
+  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';
 ```
 
 ---
@@ -1267,101 +1145,58 @@ import {
 ### 1. Use Generic Service Pattern
 
 ```typescript
-// ✅ Extend ApiService for consistent CRUD
+// Extend ApiService for consistent CRUD
 @Injectable()
 export class ProductService extends ApiService<...> {
   // Override hooks for customization
 }
 
-// ❌ Don't create custom CRUD from scratch
-@Injectable()
-export class ProductService {
-  async getAll() { /* custom implementation */ }
-  async getById() { /* custom implementation */ }
-  // Inconsistent, error-prone
-}
+// For dynamic entities, use RequestScopedApiService
+@Injectable({ scope: Scope.REQUEST })
+export class RoleService extends RequestScopedApiService<...> { }
 ```
 
-### 2. Use Decorators Consistently
+### 2. Always Use @Inject() Decorators
+
+Required for esbuild bundled code:
 
 ```typescript
-// ✅ Use built-in decorators
+// 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
-@Public()
 @RequirePermission('users.create')
+@Public()  // Use sparingly!
 
-// ❌ Don't access request directly
-@Req() req: Request
-const user = req.user; // Not type-safe
+// Don't access request directly
+@Req() req: Request  // Not type-safe
 ```
 
-### 3. Configure Security at Controller Level
+### 4. Configure Security at Controller Level
 
 ```typescript
-// ✅ Configure security in createApiController
+// GOOD - configure in createApiController
 export class UserController extends createApiController(..., {
-  security: { ... },
+  security: { insert: 'permission', ... },
 }) {}
 
-// ❌ Don't add @UseGuards to each endpoint
+// AVOID - adding guards to each endpoint
 @UseGuards(JwtGuard)
 @Post('create')
 create() {}
 ```
 
-### 4. Use Cache for Repeated Queries
-
-```typescript
-// ✅ Cache expensive operations
-async getPermissions(userId: string) {
-  const cacheKey = `permissions:${userId}`;
-  const cached = await this.cache.get(cacheKey);
-  if (cached) return cached;
-
-  const permissions = await this.fetchPermissions(userId);
-  await this.cache.set(cacheKey, permissions, 3600);
-  return permissions;
-}
-```
-
----
-
-## Dependencies
-
-- `@nestjs/common`
-- `@nestjs/core`
-- `@nestjs/typeorm`
-- `@nestjs/swagger`
-- `typeorm`
-- `class-validator`
-- `class-transformer`
-- `@flusys/nestjs-core`
-
----
-
-## Related Documentation
-
-- [API Controller Security Guide](./API-CONTROLLER-SECURITY.md)
-- [Core Package Guide](./CORE-GUIDE.md)
-- [Auth Package Guide](./AUTH-GUIDE.md)
-
----
-
-## Summary
-
-The `@flusys/nestjs-shared` package provides:
-
-- **Generic CRUD** - Consistent API patterns
-- **Permission System** - Flexible access control
-- **Caching** - High-performance data access
-- **Multi-Tenancy** - Database isolation
-- **Request Correlation** - AsyncLocalStorage-based tracking
-- **Middleware** - Logging and performance monitoring
-- **Interceptors** - Request/response processing
-- **Error Handling** - Centralized error management
-
-This is the shared infrastructure layer used by all other Flusys packages.
-
 ---
 
-**Last Updated:** 2026-02-18
+**Last Updated:** 2026-02-21