@flusys/nestjs-shared 2.0.0 → 3.0.0

package/README.md

@@ -1,6 +1,7 @@
 # Shared Package Guide
 
 > **Package:** `@flusys/nestjs-shared`
+> **Version:** 3.0.0
 > **Type:** Shared NestJS utilities, classes, decorators, guards, and modules
 
 This comprehensive guide covers the shared package - the shared NestJS infrastructure layer.
@@ -23,6 +24,7 @@ This comprehensive guide covers the shared package - the shared NestJS infrastru
 - [Utilities](#utilities)
 - [Error Handling](#error-handling)
 - [Constants](#constants)
+- [Logger System](#logger-system)
 - [API Reference](#api-reference)
 
 ---
@@ -32,13 +34,14 @@ 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 with complex logic
+- **Permission System** - Role and permission-based access control with complex logic and wildcard matching
 - **Caching** - In-memory + Redis hybrid caching (HybridCache)
-- **Request Correlation** - AsyncLocalStorage-based request tracking
+- **Request Correlation** - AsyncLocalStorage-based request tracking with correlation IDs
 - **Middleware** - Logging, correlation, and performance monitoring
 - **Interceptors** - Response metadata, idempotency, auto field setting
-- **Multi-Tenancy** - Dynamic database connection management
+- **Multi-Tenancy** - Dynamic database connection management with connection pooling
 - **Error Handling** - Centralized error handling with sensitive data redaction
+- **Logging** - Winston-based logging with tenant-aware routing and daily rotation
 
 ### Package Hierarchy
 
@@ -63,35 +66,34 @@ nestjs-shared/
 ├── src/
 │   ├── classes/              # Base classes
 │   │   ├── api-service.class.ts           # Generic CRUD service
-│   │   ├── api-controller.class.ts        # Generic CRUD controller factory
+│   │   ├── 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
-│   │   └── nest-logger-adapter.class.ts
+│   │   ├── hybrid-cache.class.ts          # Two-tier caching (memory + Redis)
+│   │   ├── winston.logger.class.ts        # Winston logger config with tenant routing
+│   │   └── winston-logger-adapter.class.ts # ILogger adapters
 │   │
 │   ├── constants/            # Injection tokens & constants
-│   │   ├── permissions.ts                 # Permission constants
-│   │   └── index.ts
+│   │   ├── permissions.ts                 # Permission constants (PERMISSIONS)
+│   │   └── index.ts                       # Metadata keys, injection tokens, headers
 │   │
 │   ├── decorators/           # Custom decorators
 │   │   ├── api-response.decorator.ts      # @ApiResponseDto
 │   │   ├── current-user.decorator.ts      # @CurrentUser
 │   │   ├── public.decorator.ts            # @Public
-│   │   ├── require-permission.decorator.ts # @RequirePermission
-│   │   ├── sanitize.decorator.ts          # @SanitizeHtml, @SanitizeAndTrim
+│   │   ├── require-permission.decorator.ts # @RequirePermission, @RequireAnyPermission, @RequirePermissionLogic
+│   │   ├── 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
+│   │   ├── delete.dto.ts                  # DeleteDto with soft/restore/permanent
+│   │   ├── filter-and-pagination.dto.ts   # FilterAndPaginationDto, GetByIdBodyDto
+│   │   ├── identity-response.dto.ts       # IdentityResponseDto
+│   │   ├── pagination.dto.ts              # PaginationDto
+│   │   ├── response-payload.dto.ts        # Single/List/Bulk/Message response DTOs
 │   │   └── index.ts
 │   │
 │   ├── entities/             # Base entities
-│   │   ├── identity.ts                    # Base entity with UUID
+│   │   ├── identity.ts                    # Base entity with UUID & audit fields
 │   │   ├── user-root.ts                   # Base user entity
 │   │   └── index.ts
 │   │
@@ -99,45 +101,44 @@ nestjs-shared/
 │   │   └── permission.exception.ts        # Permission-related exceptions
 │   │
 │   ├── guards/               # Authentication & authorization
-│   │   ├── jwt-auth.guard.ts              # JWT token validation
-│   │   └── permission.guard.ts            # Permission checks
+│   │   ├── jwt-auth.guard.ts              # JWT token validation with @Public support
+│   │   └── permission.guard.ts            # Permission checks with wildcard matching
 │   │
 │   ├── interceptors/         # Request/response interceptors
 │   │   ├── delete-empty-id-from-body.interceptor.ts
-│   │   ├── idempotency.interceptor.ts
+│   │   ├── idempotency.interceptor.ts     # Prevents duplicate POST requests
 │   │   ├── query-performance.interceptor.ts
-│   │   ├── response-meta.interceptor.ts
-│   │   ├── set-create-by-on-body.interceptor.ts
-│   │   ├── set-delete-by-on-body.interceptor.ts
-│   │   ├── set-update-by-on-body.interceptor.ts
-│   │   └── slug.interceptor.ts
+│   │   ├── response-meta.interceptor.ts   # Adds _meta to responses
+│   │   ├── set-user-field-on-body.interceptor.ts  # Factory + SetCreatedByOnBody, etc.
+│   │   └── slug.interceptor.ts            # Auto-generates slug from name
 │   │
 │   ├── interfaces/           # TypeScript interfaces
 │   │   ├── api.interface.ts               # IService interface
-│   │   ├── identity.interface.ts
+│   │   ├── datasource.interface.ts        # IDataSourceProvider
+│   │   ├── identity.interface.ts          # IIdentity interface
 │   │   ├── logged-user-info.interface.ts  # ILoggedUserInfo
-│   │   ├── logger.interface.ts            # ILogger
-│   │   ├── permission.interface.ts        # PermissionCondition
-│   │   └── datasource-provider.interface.ts
+│   │   ├── logger.interface.ts            # ILogger interface
+│   │   ├── module-config.interface.ts     # IModuleConfigService
+│   │   └── permission.interface.ts        # ILogicNode, PermissionConfig, PermissionGuardConfig
 │   │
 │   ├── middlewares/          # Middleware
-│   │   └── logger.middleware.ts           # Request logging & correlation
+│   │   └── logger.middleware.ts           # Request correlation with AsyncLocalStorage
 │   │
 │   ├── modules/              # NestJS modules
-│   │   ├── cache/cache.module.ts
+│   │   ├── cache/cache.module.ts          # CacheModule.forRoot()
 │   │   ├── datasource/
-│   │   │   ├── datasource.module.ts
+│   │   │   ├── datasource.module.ts       # DataSourceModule.forRoot/forRootAsync/forFeature
 │   │   │   └── multi-tenant-datasource.service.ts
 │   │   └── utils/
-│   │       ├── utils.module.ts
-│   │       └── utils.service.ts
+│   │       ├── utils.module.ts            # Global UtilsModule
+│   │       └── utils.service.ts           # Cache helpers, string utilities
 │   │
 │   └── utils/                # Utility functions
-│       ├── error-handler.util.ts
-│       ├── query-helpers.util.ts
-│       ├── string.util.ts
-│       ├── request.util.ts
-│       └── html-sanitizer.util.ts
+│       ├── error-handler.util.ts          # ErrorHandler class
+│       ├── html-sanitizer.util.ts         # escapeHtml, escapeHtmlVariables
+│       ├── query-helpers.util.ts          # applyCompanyFilter, validateCompanyOwnership
+│       ├── request.util.ts                # isBrowserRequest, buildCookieOptions, parseDurationToMs
+│       └── string.util.ts                 # generateSlug, generateUniqueSlug
 ```
 
 ---
@@ -149,10 +150,12 @@ The `ApiService` base class provides standardized CRUD operations with caching,
 ### Basic Usage
 
 ```typescript
-import { ApiService, HybridCache } from '@flusys/nestjs-shared/classes';
-import { UtilsService } from '@flusys/nestjs-shared/modules';
+import { ApiService, HybridCache } from '@flusys/nestjs-shared';
+import { UtilsService } from '@flusys/nestjs-shared';
 import { Injectable, Inject } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
 import { Repository } from 'typeorm';
+import { CACHE_INSTANCE } from '@flusys/nestjs-shared';
 
 @Injectable()
 export class UserService extends ApiService<
@@ -165,17 +168,17 @@ export class UserService extends ApiService<
   constructor(
     @InjectRepository(User)
     protected override repository: Repository<User>,
-    @Inject('CACHE_INSTANCE')
+    @Inject(CACHE_INSTANCE)
     protected override cacheManager: HybridCache,
     @Inject(UtilsService)
     protected override utilsService: UtilsService,
   ) {
     super(
-      'user',              // Entity name (for query building)
+      'user',              // Entity name (for query alias)
       repository,
       cacheManager,
       utilsService,
-      'UserService',       // Service name (for logging)
+      'UserService',       // Logger context name
       true,                // Enable caching
     );
   }
@@ -184,71 +187,94 @@ export class UserService extends ApiService<
 
 ### ApiService Methods
 
-| 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 |
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `insert` | `(dto, user) → Promise<T>` | Create single entity |
+| `insertMany` | `(dtos[], user) → Promise<T[]>` | Create multiple entities |
+| `findById` | `(id, user, select?) → Promise<T>` | Find entity by ID (throws if not found) |
+| `findByIds` | `(ids[], user) → Promise<T[]>` | Find multiple by IDs |
+| `getAll` | `(search, filterDto, user) → Promise<{data, total}>` | Get paginated list with filters |
+| `update` | `(dto, user) → Promise<T>` | Update single entity |
+| `updateMany` | `(dtos[], user) → Promise<T[]>` | Update multiple entities |
+| `delete` | `(deleteDto, user) → Promise<null>` | Soft/permanent delete or restore |
+| `clearCacheForAll` | `() → Promise<void>` | Clear all entity cache |
+| `clearCacheForId` | `(entities[]) → Promise<void>` | Clear cache for specific entities |
 
 ### Customization Hooks
 
 ```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 }> { }
+  // Repository initialization (for RequestScopedApiService)
+  protected async ensureRepositoryInitialized(): Promise<void> { }
+
+  // Convert DTO to entity (called for single item)
+  protected async convertSingleDtoToEntity(
+    dto: CreateDtoT | UpdateDtoT,
+    user: ILoggedUserInfo | null
+  ): Promise<EntityT> { }
+
+  // Convert entity to response DTO
+  protected convertEntityToResponseDto(entity: EntityT, isRaw: boolean): InterfaceT { }
+
+  // Convert entity list to response list
+  protected convertEntityListToResponseListDto(entities: EntityT[], isRaw: boolean): InterfaceT[] { }
+
+  // Customize SELECT query (add joins, selections)
+  protected async getSelectQuery(
+    query: SelectQueryBuilder<EntityT>,
+    user: ILoggedUserInfo | null,
+    select?: string[]
+  ): Promise<{ query: SelectQueryBuilder<EntityT>; isRaw: boolean }> { }
+
+  // Add WHERE filters from filter object
+  protected async getFilterQuery(
+    query: SelectQueryBuilder<EntityT>,
+    filter: Record<string, any>,
+    user: ILoggedUserInfo | null
+  ): Promise<{ query: SelectQueryBuilder<EntityT>; isRaw: boolean }> { }
+
+  // Add global search conditions (default: searches 'name' field)
+  protected async getGlobalSearchQuery(
+    query: SelectQueryBuilder<EntityT>,
+    search: string,
+    user: ILoggedUserInfo | null
+  ): Promise<{ query: SelectQueryBuilder<EntityT>; isRaw: boolean }> { }
+
+  // Add sort conditions
+  protected async getSortQuery(
+    query: SelectQueryBuilder<EntityT>,
+    sort: Record<string, 'ASC' | 'DESC'>,
+    user: ILoggedUserInfo | null
+  ): Promise<{ query: SelectQueryBuilder<EntityT>; isRaw: boolean }> { }
 
   // 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> { }
-
-  // After delete hook
-  override async afterDeleteOperation(dto, user, queryRunner): Promise<void> { }
+  protected async getExtraManipulateQuery(
+    query: SelectQueryBuilder<EntityT>,
+    dto: FilterAndPaginationDto,
+    user: ILoggedUserInfo | null
+  ): Promise<{ query: SelectQueryBuilder<EntityT>; isRaw: boolean }> { }
+
+  // Lifecycle hooks
+  protected async beforeInsertOperation(dto, user, queryRunner): Promise<void> { }
+  protected async afterInsertOperation(entities[], user, queryRunner): Promise<void> { }
+  protected async beforeUpdateOperation(dto, user, queryRunner): Promise<void> { }
+  protected async afterUpdateOperation(entities[], user, queryRunner): Promise<void> { }
+  protected async beforeDeleteOperation(dto, user, queryRunner): Promise<void> { }
+  protected async afterDeleteOperation(entities[], user, queryRunner): Promise<void> { }
 }
-```
 
 ---
 
 ## RequestScopedApiService
 
-For dynamic entity resolution based on runtime configuration (e.g., company feature).
+For dynamic entity resolution based on runtime configuration (e.g., company feature toggling). Extends `ApiService` with lazy repository initialization.
 
 ```typescript
-import { RequestScopedApiService } from '@flusys/nestjs-shared/classes';
+import { RequestScopedApiService, HybridCache, CACHE_INSTANCE } from '@flusys/nestjs-shared';
+import { UtilsService, IDataSourceProvider } from '@flusys/nestjs-shared';
 import { Injectable, Scope, Inject } from '@nestjs/common';
-import { EntityTarget, Repository } from 'typeorm';
+import { DataSource, EntityTarget, Repository } from 'typeorm';
 
 @Injectable({ scope: Scope.REQUEST })
 export class RoleService extends RequestScopedApiService<
@@ -258,8 +284,10 @@ export class RoleService extends RequestScopedApiService<
   RoleBase,
   Repository<RoleBase>
 > {
+  private actionRepository!: Repository<Action>;
+
   constructor(
-    @Inject('CACHE_INSTANCE') protected override cacheManager: HybridCache,
+    @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,
@@ -268,42 +296,55 @@ export class RoleService extends RequestScopedApiService<
     super('role', null as any, cacheManager, utilsService, 'RoleService', true);
   }
 
-  // Required: Resolve which entity to use
+  // Required: Resolve which entity class to use based on runtime config
   protected resolveEntity(): EntityTarget<RoleBase> {
     return this.config.isCompanyFeatureEnabled() ? RoleWithCompany : Role;
   }
 
-  // Required: Return the DataSource provider
+  // Required: Return the DataSource provider for repository creation
   protected getDataSourceProvider(): IDataSourceProvider {
     return this.provider;
   }
 
-  // Optional: Initialize additional repositories
-  protected async initializeAdditionalRepositories(): Promise<void> {
-    this.actionRepository = await this.dataSourceProvider.getRepository(Action);
+  // Override to initialize additional repositories alongside primary
+  protected override async ensureRepositoryInitialized(): Promise<void> {
+    await super.ensureRepositoryInitialized();
+    // Initialize additional repositories if needed
+    const repos = await this.initializeAdditionalRepositories([Action]);
+    this.actionRepository = repos[0];
   }
 }
 ```
 
 ### 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 |
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `ensureRepositoryInitialized()` | `() → Promise<void>` | Auto-called before operations, initializes repository |
+| `resolveEntity()` | `() → EntityTarget<EntityT>` | **Abstract** - Return entity class based on runtime config |
+| `getDataSourceProvider()` | `() → IDataSourceProvider` | **Abstract** - Return DataSource provider |
+| `initializeAdditionalRepositories()` | `(entities[]) → Promise<Repository[]>` | Initialize extra repositories |
+| `getDataSourceForService()` | `() → Promise<DataSource>` | Get raw DataSource for transactions |
+
+### IDataSourceProvider Interface
+
+```typescript
+interface IDataSourceProvider {
+  getRepository<T extends ObjectLiteral>(entity: EntityTarget<T>): Promise<Repository<T>>;
+  getDataSource(): Promise<DataSource>;
+}
+```
 
 ---
 
 ## ApiController - Generic CRUD Controller
 
-The `createApiController` factory creates standardized POST-only RPC controllers.
+The `createApiController` factory creates standardized POST-only RPC controllers with full Swagger documentation.
 
 ### Basic Usage
 
 ```typescript
-import { createApiController } from '@flusys/nestjs-shared/classes';
+import { createApiController } from '@flusys/nestjs-shared';
 import { Controller, Inject } from '@nestjs/common';
 import { ApiTags } from '@nestjs/swagger';
 
@@ -324,26 +365,51 @@ export class UserController extends createApiController<
 
 ### 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 |
+| Endpoint | Method | Description | Interceptors |
+|----------|--------|-------------|--------------|
+| `/insert` | POST | Create entity | Idempotency, SetCreatedByOnBody, Slug |
+| `/insert-many` | POST | Create multiple entities | Idempotency, SetCreatedByOnBody, Slug |
+| `/get/:id` | POST | Get entity by ID | - |
+| `/get-all` | POST | Get paginated list with filters | - |
+| `/update` | POST | Update entity | SetUpdateByOnBody, Slug |
+| `/update-many` | POST | Update multiple entities | SetUpdateByOnBody, Slug |
+| `/delete` | POST | Delete/restore/permanent delete | SetDeletedByOnBody |
+
+### Security Configuration Types
+
+```typescript
+// Security levels
+type SecurityLevel = 'public' | 'jwt' | 'permission';
+
+// Endpoint names
+type ApiEndpoint = 'insert' | 'insertMany' | 'getById' | 'getAll' | 'update' | 'updateMany' | 'delete';
+
+// Endpoint security config
+interface EndpointSecurity {
+  level: SecurityLevel;
+  permissions?: string[];          // Required permissions
+  operator?: 'AND' | 'OR';         // How to combine permissions (default: AND)
+  logic?: IPermissionLogic;        // Complex permission logic tree
+}
+
+// Per-endpoint or global config
+type ApiSecurityConfig = { [K in ApiEndpoint]?: EndpointSecurity | SecurityLevel };
+
+interface ApiControllerOptions {
+  security?: ApiSecurityConfig | EndpointSecurity | SecurityLevel;
+}
+```
 
-### Security Configuration
+### Security Configuration Examples
 
 ```typescript
-// Global security (all endpoints)
+// Global security - all endpoints require JWT
 @Controller('users')
 export class UserController extends createApiController(
   CreateUserDto,
   UpdateUserDto,
   UserResponseDto,
-  { security: 'jwt' },  // All endpoints require JWT
+  { security: 'jwt' },
 ) {}
 
 // Per-endpoint security
@@ -356,14 +422,43 @@ export class UserController extends createApiController(
     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'] },
+      insert: { level: 'permission', permissions: ['user.create'] },
+      update: { level: 'permission', permissions: ['user.update'] },
+      delete: { level: 'permission', permissions: ['user.delete'] },
     },
   },
 ) {}
+
+// Permission with OR logic
+{
+  security: {
+    getAll: { level: 'permission', permissions: ['user.read', 'admin'], operator: 'OR' },
+  },
+}
+
+// Complex permission logic
+{
+  security: {
+    delete: {
+      level: 'permission',
+      logic: {
+        type: 'group',
+        operator: 'AND',
+        children: [
+          { type: 'action', actionId: 'user.delete' },
+          { type: 'group', operator: 'OR', children: [
+            { type: 'action', actionId: 'admin' },
+            { type: 'action', actionId: 'manager' },
+          ]},
+        ],
+      },
+    },
+  },
+}
 ```
 
+**Important:** When per-endpoint security is specified, unconfigured endpoints default to `'jwt'` (not `'public'`) for security.
+
 ---
 
 ## Decorators
@@ -373,8 +468,8 @@ export class UserController extends createApiController(
 Extract the logged-in user from request:
 
 ```typescript
-import { CurrentUser } from '@flusys/nestjs-shared/decorators';
-import { ILoggedUserInfo } from '@flusys/nestjs-shared/interfaces';
+import { CurrentUser } from '@flusys/nestjs-shared';
+import { ILoggedUserInfo } from '@flusys/nestjs-shared';
 
 @Controller('profile')
 export class ProfileController {
@@ -396,7 +491,7 @@ export class ProfileController {
 Mark route as public (skip authentication). **Use sparingly - security risk**.
 
 ```typescript
-import { Public } from '@flusys/nestjs-shared/decorators';
+import { Public } from '@flusys/nestjs-shared';
 
 @Controller('auth')
 export class AuthController {
@@ -411,7 +506,7 @@ export class AuthController {
 Require specific permission(s) - **AND logic** by default:
 
 ```typescript
-import { RequirePermission } from '@flusys/nestjs-shared/decorators';
+import { RequirePermission } from '@flusys/nestjs-shared';
 
 @Controller('admin')
 export class AdminController {
@@ -432,7 +527,7 @@ export class AdminController {
 Require any of the listed permissions - **OR logic**:
 
 ```typescript
-import { RequireAnyPermission } from '@flusys/nestjs-shared/decorators';
+import { RequireAnyPermission } from '@flusys/nestjs-shared';
 
 @Controller('reports')
 export class ReportsController {
@@ -443,22 +538,26 @@ export class ReportsController {
 }
 ```
 
-### @RequirePermissionCondition
+### @RequirePermissionLogic
 
-Build complex permission conditions with nested AND/OR logic:
+Build complex permission logic with ILogicNode tree (matches frontend ILogicNode):
 
 ```typescript
-import { RequirePermissionCondition } from '@flusys/nestjs-shared/decorators';
+import { RequirePermissionLogic } from '@flusys/nestjs-shared';
 
 @Controller('sensitive')
 export class SensitiveController {
   // Complex: User needs 'users.read' AND ('admin' OR 'manager')
-  @RequirePermissionCondition({
-    operator: 'and',
-    permissions: ['users.read'],
+  @RequirePermissionLogic({
+    type: 'group',
+    operator: 'AND',
     children: [
-      { operator: 'or', permissions: ['admin', 'manager'] }
-    ]
+      { type: 'action', actionId: 'users.read' },
+      { type: 'group', operator: 'OR', children: [
+        { type: 'action', actionId: 'admin' },
+        { type: 'action', actionId: 'manager' },
+      ]},
+    ],
   })
   @Post('complex')
   getComplexData() { }
@@ -470,7 +569,7 @@ export class SensitiveController {
 Escape HTML entities for XSS prevention:
 
 ```typescript
-import { SanitizeHtml, SanitizeAndTrim } from '@flusys/nestjs-shared/decorators';
+import { SanitizeHtml, SanitizeAndTrim } from '@flusys/nestjs-shared';
 
 export class CreateCommentDto {
   @SanitizeHtml()
@@ -488,7 +587,7 @@ export class CreateCommentDto {
 Generates Swagger schema for response:
 
 ```typescript
-import { ApiResponseDto } from '@flusys/nestjs-shared/decorators';
+import { ApiResponseDto } from '@flusys/nestjs-shared';
 
 @Controller('users')
 export class UserController {
@@ -511,29 +610,30 @@ export class UserController {
 Validates JWT tokens for protected routes. Extends Passport's `AuthGuard('jwt')` and respects `@Public()` decorator.
 
 ```typescript
-import { JwtAuthGuard } from '@flusys/nestjs-shared/guards';
+import { JwtAuthGuard } from '@flusys/nestjs-shared';
+import { APP_GUARD } from '@nestjs/core';
 
-// Apply globally in main.ts
+// Apply globally
 @Module({
   providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }],
 })
 export class AppModule {}
 ```
 
-**Important:** Constructor needs `@Inject(Reflector)` for bundled code.
+**Important:** Constructor needs `@Inject(Reflector)` for bundled code (this is already handled in the guard).
 
 ### PermissionGuard
 
-Checks user permissions from cache with AND/OR/nested logic support.
+Checks user permissions from cache with AND/OR/nested logic support and wildcard matching.
 
 ```typescript
-import { PermissionGuard } from '@flusys/nestjs-shared/guards';
+import { PermissionGuard, PERMISSION_GUARD_CONFIG, CACHE_INSTANCE } from '@flusys/nestjs-shared';
 
 @Module({
   providers: [
     { provide: APP_GUARD, useClass: PermissionGuard },
     {
-      provide: 'PERMISSION_GUARD_CONFIG',
+      provide: PERMISSION_GUARD_CONFIG,
       useValue: {
         enableCompanyFeature: true,
         userPermissionKeyFormat: 'permissions:user:{userId}',
@@ -545,24 +645,85 @@ import { PermissionGuard } from '@flusys/nestjs-shared/guards';
 export class AppModule {}
 ```
 
+**PermissionGuardConfig Interface:**
+
+```typescript
+interface PermissionGuardConfig {
+  enableCompanyFeature?: boolean;
+  userPermissionKeyFormat?: string;     // Default: 'permissions:user:{userId}'
+  companyPermissionKeyFormat?: string;  // Default: 'permissions:company:{companyId}:branch:{branchId}:user:{userId}'
+}
+```
+
 **Cache Key Formats:**
 
 ```typescript
-// Without company feature
-`permissions:user:{userId}`
+// Without company feature (enableCompanyFeature: false)
+'permissions:user:{userId}'
+
+// With company feature (enableCompanyFeature: true && user.companyId exists)
+'permissions:company:{companyId}:branch:{branchId}:user:{userId}'
+```
+
+**Wildcard Permission Matching:**
+
+The guard supports wildcard permissions for flexible access control:
+
+```typescript
+// User has permissions: ['user.*', 'admin']
+
+// These checks will PASS:
+@RequirePermission('user.create')  // Matches 'user.*'
+@RequirePermission('user.read')    // Matches 'user.*'
+@RequirePermission('admin')        // Exact match
 
-// With company feature
-`permissions:company:{companyId}:branch:{branchId}:user:{userId}`
+// Wildcard patterns:
+'*'           // Matches ALL permissions (super admin)
+'user.*'      // Matches 'user.create', 'user.read', 'user.update', etc.
+'storage.*'   // Matches 'storage.file.create', 'storage.folder.read', etc.
 ```
 
 ### Permission Exceptions
 
 ```typescript
 import {
-  InsufficientPermissionsException,  // 403 - Missing permissions
-  NoPermissionsFoundException,        // 403 - No permissions in cache
-  PermissionSystemUnavailableException, // 500 - Cache unavailable
-} from '@flusys/nestjs-shared/exceptions';
+  InsufficientPermissionsException,     // 403 - Missing required permissions
+  NoPermissionsFoundException,           // 403 - No permissions in cache for user
+  PermissionSystemUnavailableException,  // 500 - Cache not available
+} from '@flusys/nestjs-shared';
+
+// Exception response formats:
+// InsufficientPermissionsException (AND):
+{
+  "success": false,
+  "message": "Missing required permissions: user.create, user.update",
+  "code": "INSUFFICIENT_PERMISSIONS",
+  "missingPermissions": ["user.create", "user.update"],
+  "operator": "AND"
+}
+
+// InsufficientPermissionsException (OR):
+{
+  "success": false,
+  "message": "Requires at least one of: admin, manager",
+  "code": "INSUFFICIENT_PERMISSIONS",
+  "missingPermissions": ["admin", "manager"],
+  "operator": "OR"
+}
+
+// NoPermissionsFoundException:
+{
+  "success": false,
+  "message": "No permissions found. Please contact administrator.",
+  "code": "NO_PERMISSIONS_FOUND"
+}
+
+// PermissionSystemUnavailableException:
+{
+  "success": false,
+  "message": "Permission system temporarily unavailable. Please try again later.",
+  "code": "PERMISSION_SYSTEM_UNAVAILABLE"
+}
 ```
 
 ---
@@ -571,20 +732,24 @@ import {
 
 ### LoggerMiddleware
 
-Combined middleware for request correlation and HTTP logging.
+Combined middleware for request correlation and HTTP logging using AsyncLocalStorage.
 
 **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
+- AsyncLocalStorage context for thread-safe access across async operations
 - Automatic sensitive header redaction (authorization, cookie, x-api-key)
 - Performance monitoring (warns on requests > 3s)
-- Body truncation (max 1000 chars)
+- Body truncation (max 1000 chars in logs)
+- Excluded paths: `/health`, `/metrics`, `/favicon.ico`
+
+**Configuration via environment:**
+- `LOG_LEVEL` - Logging level (debug enables verbose logging)
 
 **Usage:**
 
 ```typescript
-import { LoggerMiddleware } from '@flusys/nestjs-shared/middlewares';
+import { LoggerMiddleware } from '@flusys/nestjs-shared';
 
 @Module({})
 export class AppModule implements NestModule {
@@ -594,7 +759,19 @@ export class AppModule implements NestModule {
 }
 ```
 
-**Accessing Request Context:**
+**Request Context Interface:**
+
+```typescript
+interface IRequestContext {
+  requestId: string;
+  tenantId?: string;
+  userId?: string;
+  companyId?: string;
+  startTime: number;
+}
+```
+
+**Accessing Request Context (read-only):**
 
 ```typescript
 import {
@@ -602,34 +779,37 @@ import {
   getTenantId,
   getUserId,
   getCompanyId,
-  setUserId,
-  setCompanyId,
-} from '@flusys/nestjs-shared/middlewares';
+  requestContext,  // AsyncLocalStorage instance for advanced usage
+} from '@flusys/nestjs-shared';
 
 @Injectable()
 export class MyService {
   async doSomething() {
-    const requestId = getRequestId();
-    const tenantId = getTenantId();
-    setUserId('user-123');
+    const requestId = getRequestId();   // Current request's correlation ID
+    const tenantId = getTenantId();     // From x-tenant-id header
+    const userId = getUserId();         // Set by auth guard (if available)
+    const companyId = getCompanyId();   // Set by auth (if available)
   }
 }
 ```
 
+**Note:** The context values (`userId`, `companyId`) are populated by authentication guards after JWT validation. The middleware only initializes `requestId` and `tenantId` from headers.
+
 ---
 
 ## Interceptors
 
 ### ResponseMetaInterceptor
 
-Adds `_meta` to all responses:
+Automatically adds `_meta` to all responses with `success` field:
 
 ```typescript
-// Response includes:
+// Response structure:
 {
+  "success": true,
   "data": [...],
   "_meta": {
-    "requestId": "abc-123",
+    "requestId": "req_abc123def456",
     "timestamp": "2024-01-01T00:00:00.000Z",
     "responseTime": 45
   }
@@ -638,23 +818,92 @@ Adds `_meta` to all responses:
 
 ### IdempotencyInterceptor
 
-Prevents duplicate POST requests using `X-Idempotency-Key` header. Caches responses for 24 hours.
+Prevents duplicate POST requests using `X-Idempotency-Key` header.
+
+**How it works:**
+1. If key exists and completed → returns cached response (no reprocessing)
+2. If key exists but processing → throws `ConflictException` (409)
+3. If key is new → processes request and caches response for 24 hours
+
+**Usage:**
+
+```typescript
+// Client includes header:
+// X-Idempotency-Key: unique-order-123
+
+// Controller (auto-applied by createApiController for insert endpoints)
+@UseInterceptors(IdempotencyInterceptor)
+@Post('create-order')
+createOrder(@Body() dto: CreateOrderDto) { }
+```
 
 ### SetCreatedByOnBody / SetUpdateByOnBody / SetDeletedByOnBody
 
 Auto-set audit user IDs on request body from authenticated user.
 
+```typescript
+// Factory function for custom field names
+import { createSetUserFieldInterceptor } from '@flusys/nestjs-shared';
+
+// Built-in interceptors:
+export const SetCreatedByOnBody = createSetUserFieldInterceptor('createdById');
+export const SetUpdateByOnBody = createSetUserFieldInterceptor('updatedById');
+export const SetDeletedByOnBody = createSetUserFieldInterceptor('deletedById');
+
+// Usage:
+@UseInterceptors(SetCreatedByOnBody)
+@Post('insert')
+insert(@Body() dto: CreateDto) { }
+
+// Works with arrays too:
+// Input: [{ name: 'A' }, { name: 'B' }]
+// Output: [{ name: 'A', createdById: 'user-123' }, { name: 'B', createdById: 'user-123' }]
+```
+
 ### DeleteEmptyIdFromBodyInterceptor
 
-Removes empty `id` fields from request body (single and array bodies).
+Removes empty/null `id` fields from request body (single objects and arrays).
+
+```typescript
+// Input: { id: '', name: 'Test' }
+// Output: { name: 'Test' }
+
+// Input: [{ id: null, name: 'A' }, { id: '123', name: 'B' }]
+// Output: [{ name: 'A' }, { id: '123', name: 'B' }]
+```
 
 ### QueryPerformanceInterceptor
 
-Monitors execution time and warns if request > 1000ms (configurable).
+Monitors endpoint execution time and logs warnings for slow requests.
+
+```typescript
+import { QueryPerformanceInterceptor } from '@flusys/nestjs-shared';
+
+// Default threshold: 1000ms
+app.useGlobalInterceptors(new QueryPerformanceInterceptor());
+
+// Custom threshold: 500ms
+app.useGlobalInterceptors(new QueryPerformanceInterceptor(500));
+```
 
 ### Slug Interceptor
 
-Auto-generates `slug` from `name` field using `UtilsService.transformToSlug()`.
+Auto-generates `slug` from `name` field if not provided.
+
+```typescript
+import { Slug } from '@flusys/nestjs-shared';
+
+@UseInterceptors(Slug)
+@Post('insert')
+insert(@Body() dto: CreateDto) { }
+
+// Input: { name: 'My Product Name' }
+// Output: { name: 'My Product Name', slug: 'my-product-name' }
+
+// If slug already provided, it's preserved:
+// Input: { name: 'My Product', slug: 'custom-slug' }
+// Output: { name: 'My Product', slug: 'custom-slug' }
+```
 
 ---
 
@@ -665,7 +914,7 @@ Auto-generates `slug` from `name` field using `UtilsService.transformToSlug()`.
 Two-tier caching with in-memory (L1) and Redis (L2):
 
 ```typescript
-import { HybridCache } from '@flusys/nestjs-shared/classes';
+import { HybridCache } from '@flusys/nestjs-shared';
 
 @Injectable()
 export class MyService {
@@ -695,7 +944,7 @@ export class MyService {
 ### CacheModule Setup
 
 ```typescript
-import { CacheModule } from '@flusys/nestjs-shared/modules';
+import { CacheModule } from '@flusys/nestjs-shared';
 
 @Module({
   imports: [
@@ -723,7 +972,7 @@ Dynamic database connection management with connection pooling.
 ### Setup
 
 ```typescript
-import { DataSourceModule } from '@flusys/nestjs-shared/modules';
+import { DataSourceModule } from '@flusys/nestjs-shared';
 
 @Module({
   imports: [
@@ -766,7 +1015,7 @@ export class AppModule {}
 ### FilterAndPaginationDto
 
 ```typescript
-import { FilterAndPaginationDto } from '@flusys/nestjs-shared/dtos';
+import { FilterAndPaginationDto } from '@flusys/nestjs-shared';
 
 // Request body
 {
@@ -781,7 +1030,7 @@ import { FilterAndPaginationDto } from '@flusys/nestjs-shared/dtos';
 ### DeleteDto
 
 ```typescript
-import { DeleteDto } from '@flusys/nestjs-shared/dtos';
+import { DeleteDto } from '@flusys/nestjs-shared';
 
 // Soft delete
 { "id": "uuid", "type": "delete" }
@@ -842,7 +1091,7 @@ class MessageResponseDto {
 Base entity with UUID and timestamps:
 
 ```typescript
-import { Identity } from '@flusys/nestjs-shared/entities';
+import { Identity } from '@flusys/nestjs-shared';
 
 @Entity()
 export class Product extends Identity {
@@ -859,7 +1108,7 @@ export class Product extends Identity {
 Base user entity with common fields:
 
 ```typescript
-import { UserRoot } from '@flusys/nestjs-shared/entities';
+import { UserRoot } from '@flusys/nestjs-shared';
 
 @Entity()
 export class User extends UserRoot {
@@ -882,7 +1131,7 @@ import {
   buildCompanyWhereCondition,
   hasCompanyId,
   validateCompanyOwnership,
-} from '@flusys/nestjs-shared/utils';
+} from '@flusys/nestjs-shared';
 
 // Add company filter to TypeORM query
 applyCompanyFilter(query, {
@@ -900,7 +1149,7 @@ validateCompanyOwnership(entity, user, 'Entity');
 ### String Utilities
 
 ```typescript
-import { generateSlug, generateUniqueSlug } from '@flusys/nestjs-shared/utils';
+import { generateSlug, generateUniqueSlug } from '@flusys/nestjs-shared';
 
 // Generate URL-friendly slug
 const slug = generateSlug('My Product Name', 100);
@@ -921,7 +1170,7 @@ import {
   isBrowserRequest,
   buildCookieOptions,
   parseDurationToMs,
-} from '@flusys/nestjs-shared/utils';
+} from '@flusys/nestjs-shared';
 
 // Detect browser vs API client
 const isBrowser = isBrowserRequest(req);
@@ -936,7 +1185,7 @@ const ms = parseDurationToMs('7d');  // 604800000
 ### HTML Sanitizer
 
 ```typescript
-import { escapeHtml, escapeHtmlVariables } from '@flusys/nestjs-shared/utils';
+import { escapeHtml, escapeHtmlVariables } from '@flusys/nestjs-shared';
 
 // Escape single string
 const safe = escapeHtml('<script>alert("xss")</script>');
@@ -953,68 +1202,228 @@ const safeVars = escapeHtmlVariables({
 
 ## Error Handling
 
-### Error Handler Utilities
+### ErrorHandler Class
+
+Centralized error handling with automatic sensitive data redaction.
 
 ```typescript
-import {
-  getErrorMessage,
-  logError,
-  rethrowError,
-  logAndRethrow,
-} from '@flusys/nestjs-shared/utils';
+import { ErrorHandler, IErrorContext } from '@flusys/nestjs-shared';
+import { Logger } from '@nestjs/common';
 
+const logger = new Logger('MyService');
+
+// Error context interface
 interface IErrorContext {
   operation?: string;
   entity?: string;
   userId?: string;
   id?: string;
   companyId?: string;
+  branchId?: string;
+  sectionId?: 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 });
+// Safe error message extraction from unknown error
+const message = ErrorHandler.getErrorMessage(error);
+// Returns: 'Error message' | 'Unknown error occurred'
 
-// Type-safe rethrow
-rethrowError(error);
+// Log error with sensitive key redaction
+// Automatically redacts: password, secret, token, apiKey, credential, authorization
+ErrorHandler.logError(logger, error, 'createUser', {
+  entity: 'User',
+  userId: user.id,
+  data: { email: 'test@example.com', password: 'secret123' }, // password will be [REDACTED]
+});
 
-// Combined log + rethrow
-logAndRethrow(logger, error, 'updateUser', context);
+// Type-safe rethrow (preserves Error instances, wraps others)
+ErrorHandler.rethrowError(error);  // throws: never
+
+// Combined log + rethrow (common pattern)
+ErrorHandler.logAndRethrow(logger, error, 'updateUser', { entity: 'User', id: userId });
+
+// Typical usage in service
+async createUser(dto: CreateUserDto): Promise<User> {
+  try {
+    return await this.repository.save(dto);
+  } catch (error) {
+    ErrorHandler.logAndRethrow(this.logger, error, 'createUser', {
+      entity: 'User',
+      data: dto,
+    });
+  }
+}
 ```
 
+**Sensitive Keys (automatically redacted in logs):**
+- `password`
+- `secret`
+- `token`
+- `apiKey`
+- `credential`
+- `authorization`
+
 ---
 
 ## Constants
 
+### Metadata Keys
+
+```typescript
+import { IS_PUBLIC_KEY, PERMISSIONS_KEY } from '@flusys/nestjs-shared';
+
+// Used internally by decorators:
+IS_PUBLIC_KEY     // 'isPublic' - marks routes as public
+PERMISSIONS_KEY   // 'permissions' - stores permission requirements
+```
+
+### Injection Tokens
+
+```typescript
+import {
+  CACHE_INSTANCE,
+  PERMISSION_GUARD_CONFIG,
+  LOGGER_INSTANCE,
+} from '@flusys/nestjs-shared';
+
+// Injection tokens:
+CACHE_INSTANCE            // 'CACHE_INSTANCE' - HybridCache provider
+PERMISSION_GUARD_CONFIG   // 'PERMISSION_GUARD_CONFIG' - PermissionGuard config
+LOGGER_INSTANCE           // 'LOGGER_INSTANCE' - ILogger provider
+```
+
+### Header Names
+
+```typescript
+import {
+  IDEMPOTENCY_KEY_HEADER,
+  REQUEST_ID_HEADER,
+  CLIENT_TYPE_HEADER,
+} from '@flusys/nestjs-shared';
+
+// HTTP header names:
+IDEMPOTENCY_KEY_HEADER  // 'x-idempotency-key' - For IdempotencyInterceptor
+REQUEST_ID_HEADER       // 'x-request-id' - For request correlation
+CLIENT_TYPE_HEADER      // 'x-client-type' - For client detection (browser/api)
+```
+
+### Cache Key Prefixes
+
+```typescript
+import {
+  PERMISSIONS_CACHE_PREFIX,
+  IDEMPOTENCY_CACHE_PREFIX,
+} from '@flusys/nestjs-shared';
+
+// Cache key prefixes:
+PERMISSIONS_CACHE_PREFIX   // 'permissions' - For user permissions cache
+IDEMPOTENCY_CACHE_PREFIX   // 'idempotency' - For idempotency keys
+```
+
 ### Permission Constants
 
 ```typescript
-import { PERMISSIONS } from '@flusys/nestjs-shared/constants';
+import { PERMISSIONS, PermissionCode } from '@flusys/nestjs-shared';
 
-// Organized by module:
+// Auth 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.COMPANY.READ    // 'company.read'
+// ...
+
 PERMISSIONS.BRANCH.CREATE   // 'branch.create'
+// ...
 
+// IAM Module
+PERMISSIONS.ACTION.CREATE   // 'action.create'
 PERMISSIONS.ROLE.CREATE     // 'role.create'
+PERMISSIONS.ROLE_ACTION.READ    // 'role-action.read'
+PERMISSIONS.ROLE_ACTION.ASSIGN  // 'role-action.assign'
+PERMISSIONS.USER_ROLE.READ      // 'user-role.read'
+PERMISSIONS.USER_ROLE.ASSIGN    // 'user-role.assign'
+PERMISSIONS.USER_ACTION.READ    // 'user-action.read'
+PERMISSIONS.USER_ACTION.ASSIGN  // 'user-action.assign'
+PERMISSIONS.COMPANY_ACTION.READ    // 'company-action.read'
+PERMISSIONS.COMPANY_ACTION.ASSIGN  // 'company-action.assign'
+
+// Storage Module
 PERMISSIONS.FILE.CREATE     // 'file.create'
 PERMISSIONS.FOLDER.CREATE   // 'folder.create'
-// ...etc
+PERMISSIONS.STORAGE_CONFIG.CREATE  // 'storage-config.create'
+
+// Email Module
+PERMISSIONS.EMAIL_CONFIG.CREATE     // 'email-config.create'
+PERMISSIONS.EMAIL_TEMPLATE.CREATE   // 'email-template.create'
+
+// Form Builder Module
+PERMISSIONS.FORM.CREATE        // 'form.create'
+PERMISSIONS.FORM_RESULT.CREATE // 'form-result.create'
+
+// Type-safe permission code type:
+type PermissionCode = 'user.create' | 'user.read' | ... ; // Union of all permission strings
 ```
 
-### Injection Tokens
+---
+
+## Logger System
+
+### Winston Logger
+
+Production-ready logging with tenant-aware routing and daily rotation.
+
+**Configuration via environment:**
+- `LOG_DIR` - Directory for log files (default: `logs/`)
+- `LOG_LEVEL` - Minimum log level (default: `info`)
+- `LOG_MAX_SIZE` - Max file size before rotation
+- `LOG_MAX_FILES` - Max number of log files to keep
+- `USE_TENANT_MODE` - Enable tenant-aware log routing
+
+**Logger Modes:**
+
+```typescript
+import { instance as winstonLogger } from '@flusys/nestjs-shared';
+
+// Development: Console output with colors
+// Production: File-based with daily rotation + tenant routing
+```
+
+**Log File Structure:**
+
+```
+logs/
+├── combined-2024-01-15.log      # All logs (tenant mode off)
+├── error-2024-01-15.log         # Error logs only
+└── {tenantId}/                  # Tenant-specific folders (tenant mode on)
+    └── combined-2024-01-15.log
+```
+
+### Logger Adapters
 
 ```typescript
-'CACHE_INSTANCE'           // HybridCache provider
-'PERMISSION_GUARD_CONFIG'  // PermissionGuard config
-'LOGGER_INSTANCE'          // Logger provider
+import { WinstonLoggerAdapter, NestLoggerAdapter, ILogger } from '@flusys/nestjs-shared';
+import { Logger } from '@nestjs/common';
+
+// ILogger interface
+interface ILogger {
+  log(message: string, context?: string, ...args: any[]): void;
+  error(message: string, trace?: string, context?: string, ...args: any[]): void;
+  warn(message: string, context?: string, ...args: any[]): void;
+  debug(message: string, context?: string, ...args: any[]): void;
+  verbose(message: string, context?: string, ...args: any[]): void;
+}
+
+// Winston adapter (recommended for production)
+// Automatically includes correlation context (requestId, userId, tenantId, companyId)
+const logger = new WinstonLoggerAdapter('MyService');
+logger.log('Operation completed', undefined, { orderId: '123' });
+// Output: { requestId: 'uuid', userId: 'user-id', context: 'MyService', message: 'Operation completed', orderId: '123' }
+
+// NestJS adapter (for testing or simple use cases)
+const nestLogger = new NestLoggerAdapter(new Logger('MyService'));
 ```
 
 ---
@@ -1023,59 +1432,69 @@ PERMISSIONS.FOLDER.CREATE   // 'folder.create'
 
 ### Main Exports
 
+All exports are available from the main package entry point:
+
 ```typescript
-// Classes
+// Import everything from main entry
 import {
+  // Classes
   ApiService,
   RequestScopedApiService,
   createApiController,
   HybridCache,
   WinstonLoggerAdapter,
   NestLoggerAdapter,
-} from '@flusys/nestjs-shared/classes';
+  instance as winstonLogger,
 
-// Decorators
-import {
+  // Controller Types
+  ApiEndpoint,
+  SecurityLevel,
+  EndpointSecurity,
+  ApiSecurityConfig,
+  ApiControllerOptions,
+
+  // Decorators
   CurrentUser,
   Public,
   RequirePermission,
   RequireAnyPermission,
-  RequirePermissionCondition,
+  RequirePermissionLogic,
+  RequirePermissionCondition,  // @deprecated - use RequirePermissionLogic
   SanitizeHtml,
   SanitizeAndTrim,
   ApiResponseDto,
-} from '@flusys/nestjs-shared/decorators';
+  ArrayResponseType,
 
-// Guards
-import { JwtAuthGuard, PermissionGuard } from '@flusys/nestjs-shared/guards';
+  // Guards
+  JwtAuthGuard,
+  PermissionGuard,
 
-// Interceptors
-import {
+  // Interceptors
   ResponseMetaInterceptor,
   IdempotencyInterceptor,
   SetCreatedByOnBody,
   SetUpdateByOnBody,
   SetDeletedByOnBody,
+  createSetUserFieldInterceptor,  // Factory function
   DeleteEmptyIdFromBodyInterceptor,
   QueryPerformanceInterceptor,
   Slug,
-} from '@flusys/nestjs-shared/interceptors';
 
-// Modules
-import {
+  // Modules
   CacheModule,
   DataSourceModule,
+  DataSourceModuleOptions,
+  DataSourceOptionsFactory,
+  DataSourceModuleAsyncOptions,
   UtilsModule,
   UtilsService,
   MultiTenantDataSourceService,
-} from '@flusys/nestjs-shared/modules';
 
-// DTOs
-import {
+  // DTOs
   FilterAndPaginationDto,
+  GetByIdBodyDto,
   PaginationDto,
   DeleteDto,
-  GetByIdBodyDto,
   SingleResponseDto,
   ListResponseDto,
   BulkResponseDto,
@@ -1084,58 +1503,137 @@ import {
   PaginationMetaDto,
   BulkMetaDto,
   RequestMetaDto,
-} from '@flusys/nestjs-shared/dtos';
 
-// Entities
-import { Identity, UserRoot } from '@flusys/nestjs-shared/entities';
+  // Entities
+  Identity,
+  UserRoot,
 
-// Interfaces
-import {
+  // Interfaces
   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 {
+  IIdentity,
+  ILogicNode,
+  IActionNode,
+  IGroupNode,
+  IPermissionLogic,
+  SimplePermissionConfig,
+  PermissionConfig,
+  PermissionGuardConfig,
+
+  // Middleware
   LoggerMiddleware,
+  IRequestContext,
+  requestContext,
   getRequestId,
   getTenantId,
   getUserId,
   getCompanyId,
-  setUserId,
-  setCompanyId,
-} from '@flusys/nestjs-shared/middlewares';
 
-// Exceptions
-import {
+  // Exceptions
   InsufficientPermissionsException,
   NoPermissionsFoundException,
   PermissionSystemUnavailableException,
-} from '@flusys/nestjs-shared/exceptions';
 
-// Constants
-import { PERMISSIONS } from '@flusys/nestjs-shared/constants';
+  // Constants
+  IS_PUBLIC_KEY,
+  PERMISSIONS_KEY,
+  CACHE_INSTANCE,
+  PERMISSION_GUARD_CONFIG,
+  LOGGER_INSTANCE,
+  IDEMPOTENCY_KEY_HEADER,
+  REQUEST_ID_HEADER,
+  CLIENT_TYPE_HEADER,
+  PERMISSIONS_CACHE_PREFIX,
+  IDEMPOTENCY_CACHE_PREFIX,
+  PERMISSIONS,
+  PermissionCode,
+  // Individual permission exports
+  USER_PERMISSIONS,
+  COMPANY_PERMISSIONS,
+  BRANCH_PERMISSIONS,
+  ACTION_PERMISSIONS,
+  ROLE_PERMISSIONS,
+  ROLE_ACTION_PERMISSIONS,
+  USER_ROLE_PERMISSIONS,
+  USER_ACTION_PERMISSIONS,
+  COMPANY_ACTION_PERMISSIONS,
+  FILE_PERMISSIONS,
+  FOLDER_PERMISSIONS,
+  STORAGE_CONFIG_PERMISSIONS,
+  EMAIL_CONFIG_PERMISSIONS,
+  EMAIL_TEMPLATE_PERMISSIONS,
+  FORM_PERMISSIONS,
+  FORM_RESULT_PERMISSIONS,
+
+  // Utilities
+  ErrorHandler,
+  IErrorContext,
+  escapeHtml,
+  escapeHtmlVariables,
+  applyCompanyFilter,
+  buildCompanyWhereCondition,
+  hasCompanyId,
+  validateCompanyOwnership,
+  ICompanyFilterConfig,
+  ICompanyEnabled,
+  isBrowserRequest,
+  buildCookieOptions,
+  parseDurationToMs,
+  generateSlug,
+  generateUniqueSlug,
+} from '@flusys/nestjs-shared';
+```
+
+---
+
+## UtilsService
+
+Global utility service for cache management and string operations.
+
+```typescript
+import { UtilsService, CACHE_INSTANCE, HybridCache } from '@flusys/nestjs-shared';
+
+@Injectable()
+export class MyService {
+  constructor(
+    @Inject(UtilsService) private readonly utilsService: UtilsService,
+    @Inject(CACHE_INSTANCE) private readonly cache: HybridCache,
+  ) {}
+
+  // Cache key generation with optional tenant prefix
+  getCacheKey(entityName: string, params: any, entityId?: string, tenantId?: string): string;
+  // Example: this.utilsService.getCacheKey('user', { filter: {} }, 'user-123', 'tenant-1')
+  // Returns: 'tenant_tenant-1_entity_user_id_user-123_select_{"filter":{}}'
+
+  // Track cache keys for invalidation
+  async trackCacheKey(
+    cacheKey: string,
+    entityName: string,
+    cacheManager: HybridCache,
+    entityId?: string,
+    tenantId?: string,
+  ): Promise<void>;
+
+  // Clear all cached entries for an entity
+  async clearCache(
+    entityName: string,
+    cacheManager: HybridCache,
+    entityId?: string,
+    tenantId?: string,
+  ): Promise<void>;
+
+  // Generate URL-friendly slug
+  transformToSlug(value: string, salt?: boolean): string;
+  // Example: this.utilsService.transformToSlug('My Product Name')
+  // Returns: 'my-product-name'
+  // With salt: 'my-product-name-42'
+
+  // Generate random integer
+  getRandomInt(min: number, max: number): number;
+}
 ```
 
 ---
@@ -1145,58 +1643,136 @@ import { PERMISSIONS } from '@flusys/nestjs-shared/constants';
 ### 1. Use Generic Service Pattern
 
 ```typescript
-// Extend ApiService for consistent CRUD
+// Extend ApiService for consistent CRUD operations
 @Injectable()
-export class ProductService extends ApiService<...> {
-  // Override hooks for customization
+export class ProductService extends ApiService<
+  CreateProductDto,
+  UpdateProductDto,
+  IProduct,
+  Product,
+  Repository<Product>
+> {
+  // Override hooks for custom business logic
+  protected async beforeInsertOperation(dto, user, qr): Promise<void> {
+    // Validation, transformations, etc.
+  }
 }
 
-// For dynamic entities, use RequestScopedApiService
+// For dynamic entity resolution, use RequestScopedApiService
 @Injectable({ scope: Scope.REQUEST })
-export class RoleService extends RequestScopedApiService<...> { }
+export class RoleService extends RequestScopedApiService<...> {
+  protected resolveEntity() {
+    return this.config.isCompanyFeatureEnabled() ? RoleWithCompany : Role;
+  }
+}
 ```
 
 ### 2. Always Use @Inject() Decorators
 
-Required for esbuild bundled code:
+Required for esbuild bundled code (NestJS DI metadata may be lost):
 
 ```typescript
-// CORRECT
+// CORRECT - explicit injection
 constructor(
   @Inject(MyService) private readonly myService: MyService,
-  @Inject('CACHE_INSTANCE') private readonly cache: HybridCache,
+  @Inject(CACHE_INSTANCE) private readonly cache: HybridCache,
+  @Inject(UtilsService) private readonly utils: UtilsService,
 ) {}
 
-// WRONG - fails in bundled code
+// WRONG - may fail in bundled code
 constructor(private readonly myService: MyService) {}
 ```
 
 ### 3. Use Decorators Consistently
 
 ```typescript
-// Use built-in decorators
+// Use built-in decorators for type safety
 @CurrentUser() user: ILoggedUserInfo
-@RequirePermission('users.create')
-@Public()  // Use sparingly!
+@CurrentUser('id') userId: string  // Extract specific property
+
+// Permission decorators
+@RequirePermission('user.create')                    // Single permission (AND)
+@RequirePermission('user.create', 'admin')           // Multiple permissions (AND)
+@RequireAnyPermission('user.read', 'admin')          // Multiple permissions (OR)
+@RequirePermissionLogic({ type: 'group', ... })      // Complex logic
+
+// Mark public routes sparingly - security risk!
+@Public()
 
-// Don't access request directly
-@Req() req: Request  // Not type-safe
+// Avoid direct request access - use decorators
+// @Req() req: Request  // Not type-safe, avoid!
 ```
 
 ### 4. Configure Security at Controller Level
 
 ```typescript
-// GOOD - configure in createApiController
-export class UserController extends createApiController(..., {
-  security: { insert: 'permission', ... },
-}) {}
+// GOOD - centralized security config
+export class UserController extends createApiController(
+  CreateUserDto, UpdateUserDto, UserResponseDto,
+  {
+    security: {
+      getAll: 'jwt',
+      insert: { level: 'permission', permissions: ['user.create'] },
+      update: { level: 'permission', permissions: ['user.update'] },
+      delete: { level: 'permission', permissions: ['user.delete'] },
+    },
+  },
+) {}
 
-// AVOID - adding guards to each endpoint
+// AVOID - scattered guards on each endpoint
 @UseGuards(JwtGuard)
 @Post('create')
 create() {}
 ```
 
+### 5. Use Permission Constants
+
+```typescript
+import { PERMISSIONS } from '@flusys/nestjs-shared';
+
+// GOOD - use constants for type safety and refactoring
+@RequirePermission(PERMISSIONS.USER.CREATE)
+
+// AVOID - hardcoded strings prone to typos
+@RequirePermission('user.create')
+```
+
+### 6. Leverage Company Filtering Utilities
+
+```typescript
+import { applyCompanyFilter, validateCompanyOwnership } from '@flusys/nestjs-shared';
+
+// In service getExtraManipulateQuery hook
+protected async getExtraManipulateQuery(query, dto, user) {
+  applyCompanyFilter(query, {
+    isCompanyFeatureEnabled: this.config.isCompanyFeatureEnabled(),
+    entityAlias: this.entityName,
+  }, user);
+  return { query, isRaw: false };
+}
+
+// Validate ownership before operations
+validateCompanyOwnership(entity, user, this.config.isCompanyFeatureEnabled(), 'Product');
+```
+
+### 7. Error Handling Pattern
+
+```typescript
+import { ErrorHandler } from '@flusys/nestjs-shared';
+
+// Use ErrorHandler for consistent logging with sensitive data redaction
+async createUser(dto: CreateUserDto): Promise<User> {
+  try {
+    return await this.repository.save(dto);
+  } catch (error) {
+    ErrorHandler.logAndRethrow(this.logger, error, 'createUser', {
+      entity: 'User',
+      data: dto,  // Sensitive fields auto-redacted
+    });
+  }
+}
+```
+
 ---
 
-**Last Updated:** 2026-02-21
+**Last Updated:** 2026-02-25