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

package/README.md

@@ -1,56 +1,9 @@
-# Shared Package Guide
+# @flusys/nestjs-shared
 
-> **Package:** `@flusys/nestjs-shared`
-> **Type:** Shared NestJS utilities, classes, decorators, guards, and modules
+Shared infrastructure for all FLUSYS NestJS packages — base CRUD classes, JWT guard, permission guard, response DTOs, hybrid cache, structured logging, and soft-delete entities.
 
-This comprehensive guide covers the shared package - the shared NestJS infrastructure layer.
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Installation](#installation)
-- [Package Architecture](#package-architecture)
-- [ApiService - Generic CRUD Service](#apiservice---generic-crud-service)
-- [ApiController - Generic CRUD Controller](#apicontroller---generic-crud-controller)
-- [Decorators](#decorators)
-- [Guards](#guards)
-- [Middleware](#middleware)
-- [Interceptors](#interceptors)
-- [Caching System](#caching-system)
-- [Multi-Tenant DataSource](#multi-tenant-datasource)
-- [DTOs](#dtos)
-- [Base Entities](#base-entities)
-- [Error Handling](#error-handling)
-- [API Reference](#api-reference)
-
----
-
-## Overview
-
-`@flusys/nestjs-shared` provides shared utilities for building scalable NestJS applications:
-
-- **Generic CRUD** - Standardized API controller and service patterns
-- **Permission System** - Role and permission-based access control
-- **Caching** - In-memory + Redis hybrid caching
-- **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
-
-### 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
-```
+[![npm version](https://img.shields.io/npm/v/@flusys/nestjs-shared.svg)](https://www.npmjs.com/package/@flusys/nestjs-shared)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
 
@@ -58,1364 +11,227 @@ This comprehensive guide covers the shared package - the shared NestJS infrastru
 
 ```bash
 npm install @flusys/nestjs-shared @flusys/nestjs-core
+npm install typeorm @nestjs/passport @nestjs/jwt passport-jwt winston
 ```
 
----
-
-## Package Architecture
-
-```
-nestjs-shared/
-├── src/
-│   ├── classes/              # Base classes
-│   │   ├── api-service.class.ts           # Generic CRUD service
-│   │   ├── api-controller.class.ts        # Generic CRUD controller factory
-│   │   ├── 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
-│   │
-│   ├── constants/            # Injection tokens & constants
-│   │   └── index.ts
-│   │
-│   ├── decorators/           # Custom decorators
-│   │   ├── api-response.decorator.ts      # Swagger response decorator
-│   │   ├── current-user.decorator.ts
-│   │   ├── public.decorator.ts
-│   │   ├── require-permission.decorator.ts
-│   │   └── index.ts
-│   │
-│   ├── dtos/                 # Shared DTOs
-│   │   ├── delete.dto.ts
-│   │   ├── filter-and-pagination.dto.ts
-│   │   ├── identity-response.dto.ts
-│   │   ├── pagination.dto.ts
-│   │   ├── response-payload.dto.ts
-│   │   └── index.ts
-│   │
-│   ├── entities/             # Base entities
-│   │   ├── identity.ts
-│   │   ├── user-root.ts
-│   │   └── index.ts
-│   │
-│   ├── exceptions/           # Custom exceptions
-│   │   ├── permission.exception.ts
-│   │   └── index.ts
-│   │
-│   ├── guards/               # Authentication & authorization
-│   │   ├── jwt-auth.guard.ts             # JWT token validation
-│   │   ├── permission.guard.ts           # Permission checks
-│   │   └── index.ts
-│   │
-│   ├── interceptors/         # Request/response interceptors
-│   │   ├── delete-empty-id-from-body.interceptor.ts
-│   │   ├── idempotency.interceptor.ts
-│   │   ├── 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
-│   │   └── index.ts
-│   │
-│   ├── interfaces/           # TypeScript interfaces
-│   │   ├── api.interface.ts
-│   │   ├── base-query.interface.ts
-│   │   ├── identity.interface.ts
-│   │   ├── logged-user-info.interface.ts
-│   │   ├── logger.interface.ts
-│   │   ├── permission.interface.ts
-│   │   └── index.ts
-│   │
-│   ├── middlewares/          # Middleware
-│   │   ├── logger.middleware.ts          # Request logging & correlation
-│   │   └── index.ts
-│   │
-│   ├── 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
-│   │
-│   └── utils/                # Utility functions
-│       ├── error-handler.util.ts
-│       └── index.ts
-```
-
----
-
-## ApiService - Generic CRUD Service
+## 1. Module Registration
 
-The `ApiService` base class provides standardized CRUD operations with caching, pagination, and transaction support.
-
-### Basic Usage
+Register once in your root `AppModule`:
 
 ```typescript
-import { ApiService, HybridCache } from '@flusys/nestjs-shared/classes';
-import { UtilsService } from '@flusys/nestjs-shared/modules';
-import { Injectable, Inject } from '@nestjs/common';
-import { 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<
-  CreateUserDto,         // Create DTO
-  UpdateUserDto,         // Update DTO
-  IUser,                 // Interface
-  User,                  // Entity
-  Repository<User>       // Repository type
-> {
-  constructor(
-    @InjectRepository(User)
-    protected override repository: Repository<User>,
-    @Inject('CACHE_INSTANCE')
-    protected override cacheManager: HybridCache,
-    protected override utilsService: UtilsService,
-  ) {
-    super(
-      'user',              // Entity name (for query building)
-      repository,
-      cacheManager,
-      utilsService,
-      'UserService',       // Service name (for logging)
-      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 };
-  }
-}
-```
-
-### 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) |
-| `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 |
-
-### 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 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> { }
-}
-```
-
-### Company/Branch Filtering Example
-
-```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 { Module, MiddlewareConsumer, NestModule } from '@nestjs/common';
+import { CacheModule, UtilsModule } from '@flusys/nestjs-shared/modules';
+import { LoggerMiddleware } from '@flusys/nestjs-shared/middlewares';
+import { GlobalExceptionFilter } from '@flusys/nestjs-shared/filters';
+import { ResponseMetaInterceptor } from '@flusys/nestjs-shared/interceptors';
 
-  // Filter by user's branch
-  if (user.branchId) {
-    query.andWhere(`${this.entityName}.branchId = :branchId`, {
-      branchId: user.branchId,
-    });
+@Module({
+  imports: [
+    CacheModule.forRoot(true), // true = global; provides 'CACHE_INSTANCE' token
+    UtilsModule, // provides UtilsService
+  ],
+})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(LoggerMiddleware).forRoutes('*');
   }
-
-  return { query, isRaw: false };
 }
-```
-
----
-
-## ApiController - Generic CRUD Controller
-
-The `createApiController` factory creates standardized REST API controllers.
-
-### Basic Usage
-
-```typescript
-import { createApiController } from '@flusys/nestjs-shared/classes';
-import { Controller } 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')
-export class UserController extends createApiController<
-  CreateUserDto,
-  UpdateUserDto,
-  UserResponseDto,
-  IUser,
-  UserService
->(CreateUserDto, UpdateUserDto, UserResponseDto) {
-  constructor(protected service: UserService) {
-    super(service);
-  }
-}
+// In bootstrap()
+app.useGlobalFilters(new GlobalExceptionFilter());
+app.useGlobalInterceptors(new ResponseMetaInterceptor());
 ```
 
-### 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 |
+## 2. Entity Base Class
 
-### Security Configuration
+Every entity must extend `Identity`:
 
 ```typescript
-// Global security (all endpoints)
-@Controller('users')
-export class UserController extends createApiController(
-  CreateUserDto,
-  UpdateUserDto,
-  UserResponseDto,
-  {
-    security: 'jwt',  // All endpoints require JWT
-  },
-) {}
-
-// Per-endpoint security
-@Controller('users')
-export class UserController extends createApiController(
-  CreateUserDto,
-  UpdateUserDto,
-  UserResponseDto,
-  {
-    security: {
-      getAll: 'public',                                    // No auth required
-      getById: 'jwt',                                      // JWT required
-      insert: { level: 'permission', permissions: ['users.create'] },
-      update: { level: 'permission', permissions: ['users.update'] },
-      delete: { level: 'permission', permissions: ['users.delete'] },
-    },
-  },
-) {}
-
-// Permission combinations
-{
-  security: {
-    // Require ANY of these permissions
-    insert: {
-      level: 'permission',
-      permissions: ['users.create', 'users.admin'],
-      require: 'any',  // Default
-    },
+import { Entity, Column } from 'typeorm';
+import { Identity } from '@flusys/nestjs-shared/entities';
 
-    // Require ALL permissions
-    delete: {
-      level: 'permission',
-      permissions: ['users.delete', 'users.admin'],
-      require: 'all',
-    },
-  },
+@Entity('products')
+export class Product extends Identity {
+  @Column({ length: 255 })
+  name: string;
+  // inherited: id (uuid), createdAt, updatedAt, deletedAt,
+  //            createdById, updatedById, deletedById
 }
 ```
 
-See [API-CONTROLLER-SECURITY.md](./API-CONTROLLER-SECURITY.md) for detailed security configuration.
-
----
-
-## Decorators
+## 3. Generic CRUD — `createApiController` + `RequestScopedApiService`
 
-### @CurrentUser
-
-Extract the logged-in user from request:
+### Service (REQUEST-scoped, DataSource Provider pattern)
 
 ```typescript
-import { CurrentUser } from '@flusys/nestjs-shared/decorators';
-import { ILoggedUserInfo } from '@flusys/nestjs-shared/interfaces';
+import { Injectable, Scope, Inject } from '@nestjs/common';
+import { EntityTarget, Repository } from 'typeorm';
+import { RequestScopedApiService } from '@flusys/nestjs-shared/classes';
+import { HybridCache } from '@flusys/nestjs-shared/classes';
+import { UtilsService } from '@flusys/nestjs-shared/modules';
 
-@Controller('profile')
-export class ProfileController {
-  @Get()
-  getProfile(@CurrentUser() user: ILoggedUserInfo) {
-    return { userId: user.id, companyId: user.companyId };
+@Injectable({ scope: Scope.REQUEST }) // required
+export class ProductService extends RequestScopedApiService<
+  CreateProductDto,
+  UpdateProductDto,
+  IProduct,
+  Product
+> {
+  constructor(
+    @Inject('CACHE_INSTANCE') protected override cacheManager: HybridCache,
+    @Inject(UtilsService) protected override utilsService: UtilsService,
+    @Inject(ProductConfigService) private readonly config: ProductConfigService,
+    @Inject(ProductDataSourceProvider) private readonly dsp: ProductDataSourceProvider,
+  ) {
+    super('product', null as any, cacheManager, utilsService, ProductService.name, true);
   }
-}
-```
-
-### @Public
-
-Mark route as public (skip authentication):
-
-```typescript
-import { Public } from '@flusys/nestjs-shared/decorators';
 
-@Controller('auth')
-export class AuthController {
-  @Public()
-  @Post('login')
-  login() {
-    // No JWT required
+  // Required: tell the base class which entity and which datasource to use
+  protected resolveEntity(): EntityTarget<Product> {
+    return this.config.isCompanyFeatureEnabled() ? ProductWithCompany : Product;
   }
-}
-```
-
-### @RequirePermission
-
-Require specific permission:
 
-```typescript
-import { RequirePermission } from '@flusys/nestjs-shared/decorators';
-
-@Controller('admin')
-export class AdminController {
-  @RequirePermission('admin.dashboard')
-  @Get('dashboard')
-  getDashboard() {
-    // Requires 'admin.dashboard' permission
+  protected getDataSourceProvider() {
+    return this.dsp;
   }
 }
 ```
 
-### @RequireAnyPermission
-
-Require any of the listed permissions:
+### Controller (factory function)
 
 ```typescript
-import { RequireAnyPermission } from '@flusys/nestjs-shared/decorators';
+import { Controller, Inject } from '@nestjs/common';
+import { createApiController } from '@flusys/nestjs-shared/classes';
 
-@Controller('reports')
-export class ReportsController {
-  @RequireAnyPermission('reports.view', 'reports.admin')
-  @Get()
-  getReports() {
-    // Requires 'reports.view' OR 'reports.admin'
+@Controller('administration/products')
+export class ProductController extends createApiController<
+  CreateProductDto,
+  UpdateProductDto,
+  ProductResponseDto,
+  IProduct,
+  ProductService
+>(CreateProductDto, UpdateProductDto, ProductResponseDto, {
+  entityName: 'product',
+  security: {
+    insert: { level: 'permission', permissions: ['product.create'] },
+    insertMany: { level: 'permission', permissions: ['product.create'] },
+    getAll: { level: 'permission', permissions: ['product.read'] },
+    getById: { level: 'permission', permissions: ['product.read'] },
+    update: { level: 'permission', permissions: ['product.update'] },
+    updateMany: { level: 'permission', permissions: ['product.update'] },
+    delete: { level: 'permission', permissions: ['product.delete'] },
+    bulkUpsert: { level: 'permission', permissions: ['product.create'] },
+    getByIds: { level: 'permission', permissions: ['product.read'] },
+    getByFilter: { level: 'permission', permissions: ['product.read'] },
+  },
+}) {
+  constructor(@Inject(ProductService) public override service: ProductService) {
+    super(service);
   }
 }
 ```
 
-### @RequirePermissionCondition
-
-Build complex permission conditions with nested AND/OR logic:
-
-```typescript
-import { RequirePermissionCondition } from '@flusys/nestjs-shared/decorators';
+Generated POST-only endpoints: `/insert`, `/insert-many`, `/get-all`, `/get/:id`,
+`/get-by-ids`, `/get-by-filter`, `/update`, `/update-many`, `/bulk-upsert`, `/delete`.
 
-@Controller('sensitive')
-export class SensitiveController {
-  // Simple: User needs 'admin' OR 'manager'
-  @RequirePermissionCondition({
-    operator: 'or',
-    permissions: ['admin', 'manager'],
-  })
-  @Get('simple')
-  getSimpleData() {}
+Security levels: `'public'` (no auth), `'jwt'` (token only), `'permission'` (token + action check).
 
-  // Complex: User needs 'users.read' AND ('admin' OR 'manager')
-  @RequirePermissionCondition({
-    operator: 'and',
-    permissions: ['users.read'],
-    children: [
-      { operator: 'or', permissions: ['admin', 'manager'] }
-    ]
-  })
-  @Get('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() {}
-}
-```
-
-**Note:** For simple "require ALL permissions" use case, use `@RequirePermission` which defaults to AND logic:
-```typescript
-@RequirePermission('admin.access', 'security.clearance')  // User needs BOTH
-```
-
----
-
-## Guards
-
-The shared package provides two guards for authentication and authorization:
-
-### JwtAuthGuard
-
-**Location:** `@flusys/nestjs-shared/guards/jwt-auth.guard.ts`
-
-The `JwtAuthGuard` validates JWT tokens for protected routes. It extends Passport's `AuthGuard('jwt')` and respects the `@Public()` decorator.
-
-**Why in shared module:**
-- All feature modules (auth, iam, storage) need JWT authentication
-- Keeps feature modules independent (no cross-dependencies)
-- JwtStrategy registration remains in auth module
-- This guard just validates tokens using the registered strategy
-
-**Usage:**
+## 4. Guards and Decorators
 
 ```typescript
 import { JwtAuthGuard } from '@flusys/nestjs-shared/guards';
-import { UseGuards } from '@nestjs/common';
-
-// Protect entire controller
-@Controller('users')
-@UseGuards(JwtAuthGuard)
-export class UserController {
-  // All routes protected
-
-  @Post('login')
-  @Public()  // Skip JWT check for this route
-  async login() { }
-}
-
-// Or apply globally
-@Module({
-  providers: [
-    {
-      provide: APP_GUARD,
-      useClass: JwtAuthGuard,
-    },
-  ],
-})
-export class AppModule {}
-```
-
-**Features:**
-- Validates JWT tokens from `Authorization: Bearer <token>` header
-- Respects `@Public()` decorator to skip authentication
-- Throws `UnauthorizedException` for invalid/expired tokens
-- Works with JwtStrategy registered in auth module
-
-**Note:** The JwtStrategy (which registers the JWT validation logic with Passport) is still in the auth module at `@flusys/nestjs-auth/strategies/jwt.strategy.ts`. This guard uses that registered strategy.
-
-### PermissionGuard
-
-**Location:** `@flusys/nestjs-shared/guards/permission.guard.ts`
-
-The `PermissionGuard` handles permission-based access control.
-
-```typescript
-import { Module } from '@nestjs/common';
-import { APP_GUARD } from '@nestjs/core';
 import { PermissionGuard } from '@flusys/nestjs-shared/guards';
-
-@Module({
-  providers: [
-    {
-      provide: APP_GUARD,
-      useClass: PermissionGuard,
-    },
-  ],
-})
-export class AppModule {}
-```
-
-### Permission Cache Key Format
-
-```typescript
-// Without company feature
-`permissions:user:{userId}`
-
-// With company feature (includes branchId for DIRECT permissions)
-`permissions:company:{companyId}:branch:{branchId}:user:{userId}`
-```
-
-### Permission Guard Configuration
-
-```typescript
-// Configure via PermissionModule options
-PermissionModule.forRoot({
-  // Cache TTL in seconds
-  cacheTtl: 3600,
-
-  // Permission check mode
-  mode: 'RBAC' | 'DIRECT' | 'FULL',
-
-  // Custom permission resolver
-  resolver: CustomPermissionResolver,
-});
-```
-
----
-
-## Middleware
-
-### 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
-
-**Usage:**
-
-```typescript
-import { LoggerMiddleware } from '@flusys/nestjs-shared/middlewares';
-import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
-
-@Module({
-  // ...
-})
-export class AppModule implements NestModule {
-  configure(consumer: MiddlewareConsumer) {
-    // Apply to all routes
-    consumer.apply(LoggerMiddleware).forRoutes('*');
-  }
-}
-```
-
-**Accessing Request Context:**
-
-```typescript
 import {
-  getRequestId,
-  getTenantId,
-  getUserId,
-  getCompanyId,
-  setUserId,
-  setCompanyId,
-} from '@flusys/nestjs-shared/middlewares';
-
-@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
-    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:
-
-```typescript
-import { ResponseMetaInterceptor } from '@flusys/nestjs-shared/interceptors';
+  CurrentUser,
+  Public,
+  RequirePermission,
+  RequireAnyPermission,
+} from '@flusys/nestjs-shared/decorators';
+import { ILoggedUserInfo } from '@flusys/nestjs-shared/interfaces';
 
-@UseInterceptors(ResponseMetaInterceptor)
-@Controller('users')
-export class UserController {}
+@UseGuards(JwtAuthGuard, PermissionGuard)
+@RequirePermission('product.create')
+@Post('insert')
+async insert(@Body() dto: CreateProductDto, @CurrentUser() user: ILoggedUserInfo) { }
 
-// Response:
-{
-  "data": [...],
-  "meta": {
-    "timestamp": "2024-01-01T00:00:00.000Z",
-    "requestId": "abc-123",
-    "responseTime": 45
-  }
-}
+// Mark endpoint public (no JWT required)
+@Public()
+@Post('public-list')
+async publicList() { }
 ```
 
-### IdempotencyInterceptor
-
-Prevent duplicate requests:
-
-```typescript
-import { IdempotencyInterceptor } from '@flusys/nestjs-shared/interceptors';
-
-@UseInterceptors(IdempotencyInterceptor)
-@Controller('payments')
-export class PaymentController {
-  @Post()
-  // Clients send X-Idempotency-Key header
-  // Duplicate requests return cached response
-  processPayment() {}
-}
-```
+`ILoggedUserInfo` fields: `id`, `email`, `name?`, `phone?`, `profilePictureId?`, `companyId?`, `branchId?`.
 
-### SetCreatedByOnBody / SetUpdateByOnBody
+## 5. Response DTOs
 
-Auto-set user IDs on request body:
+All controllers return one of these shapes:
 
 ```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
-  }
+import {
+  SingleResponseDto, // insert, update, getById
+  ListResponseDto, // getAll, getByIds
+  BulkResponseDto, // insertMany, updateMany, bulkUpsert
+  MessageResponseDto, // delete
+} from '@flusys/nestjs-shared/dtos';
 
-  @UseInterceptors(SetUpdateByOnBody)
-  @Put()
-  update(@Body() dto: UpdatePostDto) {
-    // dto.updatedById is automatically set to current user ID
-  }
-}
+// All shapes include: success, message, messageKey (for i18n), _meta (requestId, timestamp, duration)
+// ListResponseDto / BulkResponseDto also include: meta (total, page, pageSize, count, totalPages)
 ```
 
-### Slug Interceptor
-
-Auto-generate slugs from name field:
+## 6. Exceptions
 
 ```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"
-  }
-}
+import {
+  NotFoundException,
+  ConflictException,
+  UnauthorizedException,
+  ForbiddenException,
+  ValidationException,
+  InternalServerException,
+} from '@flusys/nestjs-shared/exceptions';
+
+throw new NotFoundException({
+  message: 'User not found',
+  messageKey: USER_MESSAGES.NOT_FOUND,
+});
+throw new ConflictException({
+  message: `User already assigned to this ${typeName}. Please refresh and try again.`,
+  messageKey: USER_PERMISSION_MESSAGES.ALREADY_ASSIGNED,
+  messageVariables: { type: typeName },
+});
+throw new ValidationException([{ field: 'email', message: 'Invalid format' }]);
 ```
 
----
-
-## Caching System
-
-### HybridCache
+All exceptions produce: `{ success: false, message, messageKey,messageVariables:{} code, _meta }`.
 
-Two-tier caching with in-memory (fast) and Redis (distributed):
+## 7. Hybrid Cache
 
 ```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;
   }
 
   async invalidate(key: string) {
-    await this.cache.del(key);
-  }
-
-  async invalidatePattern(pattern: string) {
-    // Delete all keys matching pattern
-    await this.cache.delByPattern('users:*');
-  }
-}
-```
-
-### CacheModule Setup
-
-```typescript
-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,
-      },
-    }),
-  ],
-})
-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 |
-
----
-
-## Multi-Tenant DataSource
-
-Dynamic database connection management for multi-tenant applications.
-
-### Setup
-
-```typescript
-import { DataSourceModule } from '@flusys/nestjs-shared/modules';
-
-@Module({
-  imports: [
-    DataSourceModule.forRoot({
-      // Default database config (used as template)
-      defaultDatabaseConfig: {
-        type: 'mysql',
-        host: 'localhost',
-        port: 3306,
-        username: 'root',
-        password: 'password',
-      },
-
-      // Tenant configurations
-      tenants: [
-        { id: 'tenant1', database: 'tenant1_db', isActive: true },
-        { id: 'tenant2', database: 'tenant2_db', isActive: true },
-      ],
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-### Usage with Tenant Header
-
-```typescript
-// Client sends X-Tenant-ID header
-// DataSource automatically switches to tenant's database
-
-@Injectable()
-export class TenantService {
-  constructor(
-    @Inject('DATASOURCE_PROVIDER')
-    private dataSourceProvider: MultiTenantDataSourceService,
-  ) {}
-
-  async getConnection(tenantId: string) {
-    return this.dataSourceProvider.getConnection(tenantId);
-  }
-}
-```
-
-### Tenant Resolution
-
-```typescript
-// Default: Resolved from X-Tenant-ID header
-@Controller('users')
-export class UserController {
-  // Automatically uses tenant-specific database
-}
-
-// Manual tenant specification
-@Injectable()
-export class CrossTenantService {
-  async copyData(fromTenant: string, toTenant: string) {
-    const fromConn = await this.dataSourceProvider.getConnection(fromTenant);
-    const toConn = await this.dataSourceProvider.getConnection(toTenant);
-    // ...
-  }
-}
-```
-
----
-
-## DTOs
-
-### FilterAndPaginationDto
-
-Standard filtering and pagination:
-
-```typescript
-import { FilterAndPaginationDto } from '@flusys/nestjs-shared/dtos';
-
-// Request body
-{
-  "filter": {
-    "status": "active",
-    "category": "electronics"
-  },
-  "pagination": {
-    "page": 1,
-    "limit": 10
-  },
-  "sort": {
-    "field": "createdAt",
-    "order": "DESC"
-  },
-  "search": {
-    "fields": ["name", "description"],
-    "value": "laptop"
-  },
-  "select": ["id", "name", "price"]
-}
-```
-
-### DeleteDto
-
-Soft or permanent delete:
-
-```typescript
-import { DeleteDto } from '@flusys/nestjs-shared/dtos';
-
-// Soft delete (sets deletedAt)
-{
-  "id": "user-123",
-  "type": "soft"
-}
-
-// Permanent delete
-{
-  "id": "user-123",
-  "type": "permanent"
-}
-
-// Multiple IDs
-{
-  "id": ["user-123", "user-456"],
-  "type": "soft"
-}
-```
-
-### ResponsePayloadDto
-
-Standardized response format:
-
-```typescript
-import { ResponsePayloadDto } from '@flusys/nestjs-shared/dtos';
-
-// Success response
-{
-  "success": true,
-  "data": { ... },
-  "message": "Operation successful"
-}
-
-// Paginated response
-{
-  "success": true,
-  "data": [...],
-  "pagination": {
-    "total": 100,
-    "page": 1,
-    "limit": 10,
-    "totalPages": 10
-  }
-}
-
-// Error response
-{
-  "success": false,
-  "error": {
-    "code": "VALIDATION_ERROR",
-    "message": "Invalid input"
+    await this.cache.delete(key);
   }
-}
-```
-
----
-
-## Base Entities
-
-### Identity Entity
-
-Base entity with UUID and timestamps:
-
-```typescript
-import { Identity } from '@flusys/nestjs-shared/entities';
-
-@Entity()
-export class Product extends Identity {
-  // Inherited: id, createdAt, updatedAt, deletedAt
-
-  @Column()
-  name: string;
-
-  @Column()
-  price: number;
-}
-```
-
-### UserRoot Entity
-
-Base user entity:
-
-```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;
-}
-```
-
----
-
-## Error Handling
-
-### ErrorHandler
-
-Centralized error handling utility:
-
-```typescript
-import { ErrorHandler } from '@flusys/nestjs-shared/utils';
-
-@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');
-    }
+  async invalidatePrefix(prefix: string) {
+    await this.cache.deleteByPrefix(prefix);
   }
 }
 ```
 
-### Error Types
-
-```typescript
-// Automatically converted to appropriate HTTP exception:
-
-// TypeORM unique constraint → ConflictException (409)
-// TypeORM foreign key → BadRequestException (400)
-// Validation error → BadRequestException (400)
-// Not found → NotFoundException (404)
-// Unknown → InternalServerErrorException (500)
-```
-
----
-
-## API Reference
-
-### Main Exports
-
-```typescript
-// Classes
-import {
-  ApiService,
-  createApiController,
-  HybridCache,
-} from '@flusys/nestjs-shared/classes';
-
-// Decorators
-import {
-  CurrentUser,
-  Public,
-  RequirePermission,
-  RequireAnyPermission,
-  RequirePermissionCondition,
-} from '@flusys/nestjs-shared/decorators';
-
-// Guards
-import {
-  JwtAuthGuard,
-  PermissionGuard,
-} from '@flusys/nestjs-shared/guards';
-
-// Interceptors
-import {
-  ResponseMetaInterceptor,
-  IdempotencyInterceptor,
-  SetCreatedByOnBody,
-  SetUpdateByOnBody,
-  Slug,
-} from '@flusys/nestjs-shared/interceptors';
-
-// Modules
-import {
-  CacheModule,
-  DataSourceModule,
-  UtilsModule,
-} from '@flusys/nestjs-shared/modules';
-
-// DTOs
-import {
-  FilterAndPaginationDto,
-  DeleteDto,
-  ResponsePayloadDto,
-} from '@flusys/nestjs-shared/dtos';
-
-// Entities
-import {
-  Identity,
-  UserRoot,
-} from '@flusys/nestjs-shared/entities';
-
-// Interfaces
-import {
-  ILoggedUserInfo,
-  IPermissionConfig,
-} from '@flusys/nestjs-shared/interfaces';
-
-// Utilities
-import {
-  ErrorHandler,
-} from '@flusys/nestjs-shared/utils';
-```
-
----
-
-## Best Practices
-
-### 1. Use Generic Service Pattern
-
-```typescript
-// ✅ 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
-}
-```
-
-### 2. Use Decorators Consistently
-
-```typescript
-// ✅ Use built-in decorators
-@CurrentUser() user: ILoggedUserInfo
-@Public()
-@RequirePermission('users.create')
-
-// ❌ Don't access request directly
-@Req() req: Request
-const user = req.user; // Not type-safe
-```
-
-### 3. Configure Security at Controller Level
-
-```typescript
-// ✅ Configure security in createApiController
-export class UserController extends createApiController(..., {
-  security: { ... },
-}) {}
-
-// ❌ Don't add @UseGuards 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)
+`CacheModule.forRoot(true)` connects to Redis automatically when `REDIS_URL` is set; otherwise uses in-memory only.
 
----
-
-## 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.
-
----
+## License
 
-**Last Updated:** 2026-02-16
+MIT © FLUSYS