@flusys/nestjs-shared 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -0,0 +1,1399 @@
+# Shared Package Guide
+
+> **Package:** `@flusys/nestjs-shared`
+> **Type:** Shared NestJS utilities, classes, decorators, guards, and modules
+
+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 (NEW)
+- **Middleware** - Logging, correlation, and performance monitoring (NEW)
+- **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
+```
+
+---
+
+## Installation
+
+```bash
+npm install @flusys/nestjs-shared @flusys/nestjs-core
+```
+
+---
+
+## 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
+
+The `ApiService` base class provides standardized CRUD operations with caching, pagination, and transaction support.
+
+### Basic Usage
+
+```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,
+    });
+  }
+
+  // Filter by user's branch
+  if (user.branchId) {
+    query.andWhere(`${this.entityName}.branchId = :branchId`, {
+      branchId: user.branchId,
+    });
+  }
+
+  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);
+  }
+}
+```
+
+### Generated Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/insert` | POST | Create entity |
+| `/insert-many` | POST | Create multiple entities |
+| `/get/:id` | POST | Get entity by ID |
+| `/get-all` | POST | Get paginated list |
+| `/update` | POST | Update entity |
+| `/update-many` | POST | Update multiple entities |
+| `/delete` | POST | Delete entity |
+
+### Security Configuration
+
+```typescript
+// Global security (all endpoints)
+@Controller('users')
+export class UserController extends createApiController(
+  CreateUserDto,
+  UpdateUserDto,
+  UserResponseDto,
+  {
+    security: 'jwt',  // All endpoints require JWT
+  },
+) {}
+
+// 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
+    },
+
+    // Require ALL permissions
+    delete: {
+      level: 'permission',
+      permissions: ['users.delete', 'users.admin'],
+      require: 'all',
+    },
+  },
+}
+```
+
+See [API-CONTROLLER-SECURITY.md](./API-CONTROLLER-SECURITY.md) for detailed security configuration.
+
+---
+
+## Decorators
+
+### @CurrentUser
+
+Extract the logged-in user from request:
+
+```typescript
+import { CurrentUser } from '@flusys/nestjs-shared/decorators';
+import { ILoggedUserInfo } from '@flusys/nestjs-shared/interfaces';
+
+@Controller('profile')
+export class ProfileController {
+  @Get()
+  getProfile(@CurrentUser() user: ILoggedUserInfo) {
+    return { userId: user.id, companyId: user.companyId };
+  }
+}
+```
+
+### @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
+  }
+}
+```
+
+### @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
+  }
+}
+```
+
+### @RequireAnyPermission
+
+Require any of the listed permissions:
+
+```typescript
+import { RequireAnyPermission } from '@flusys/nestjs-shared/decorators';
+
+@Controller('reports')
+export class ReportsController {
+  @RequireAnyPermission('reports.view', 'reports.admin')
+  @Get()
+  getReports() {
+    // Requires 'reports.view' OR 'reports.admin'
+  }
+}
+```
+
+### @RequireAllPermissions
+
+Require all listed permissions:
+
+```typescript
+import { RequireAllPermissions } from '@flusys/nestjs-shared/decorators';
+
+@Controller('sensitive')
+export class SensitiveController {
+  @RequireAllPermissions('admin.access', 'security.clearance')
+  @Get()
+  getSensitiveData() {
+    // Requires BOTH permissions
+  }
+}
+```
+
+---
+
+## 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:**
+
+```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 (NEW - 2026-01-12, Enhanced - 2026-01-14)
+
+**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';
+
+@UseInterceptors(ResponseMetaInterceptor)
+@Controller('users')
+export class UserController {}
+
+// Response:
+{
+  "data": [...],
+  "meta": {
+    "timestamp": "2024-01-01T00:00:00.000Z",
+    "requestId": "abc-123",
+    "responseTime": 45
+  }
+}
+```
+
+### 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() {}
+}
+```
+
+### SetCreatedByOnBody / SetUpdateByOnBody
+
+Auto-set user IDs on request body:
+
+```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
+  }
+
+  @UseInterceptors(SetUpdateByOnBody)
+  @Put()
+  update(@Body() dto: UpdatePostDto) {
+    // dto.updatedById is automatically set to current user ID
+  }
+}
+```
+
+### Slug Interceptor
+
+Auto-generate slugs from name field:
+
+```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"
+  }
+}
+```
+
+---
+
+## Caching System
+
+### HybridCache
+
+Two-tier caching with in-memory (fast) and Redis (distributed):
+
+```typescript
+import { HybridCache } from '@flusys/nestjs-shared/classes';
+
+@Injectable()
+export class MyService {
+  constructor(
+    @Inject('CACHE_INSTANCE')
+    private cache: HybridCache,
+  ) {}
+
+  async getData(key: string) {
+    // Check cache first
+    const cached = await this.cache.get(key);
+    if (cached) return cached;
+
+    // Fetch from database
+    const data = await this.fetchFromDb();
+
+    // Store in cache (TTL in seconds)
+    await this.cache.set(key, data, 3600);
+
+    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"
+  }
+}
+```
+
+---
+
+## 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');
+    }
+  }
+}
+```
+
+### 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,
+  RequireAllPermissions,
+} from '@flusys/nestjs-shared/decorators';
+
+// Guards
+import {
+  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)
+
+---
+
+## 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 (NEW)
+✅ **Middleware** - Logging and performance monitoring (NEW)
+✅ **Interceptors** - Request/response processing
+✅ **Error Handling** - Centralized error management
+
+This is the shared infrastructure layer used by all other Flusys packages.
+
+---
+
+**Last Updated:** 2026-02-07
+**Recent Improvements:**
+- 2026-02-07: Documentation cleanup - removed outdated JWT configuration section, updated package architecture to match actual structure
+- 2026-01-14: Enhanced `LoggerMiddleware` with complete request/response details (URL, path, query, headers, user context)
+- 2026-01-14: Added multiple response hooks (send, json, end) for reliable response capture
+- 2026-01-14: Improved error logging with stack traces
+- 2026-01-12: Added `LoggerMiddleware` for request correlation and structured logging
+- 2026-01-12: Added AsyncLocalStorage-based request context (requestId, tenantId, userId, companyId)
+- 2026-01-13: Removed JWT config/constants (moved to auth-specific packages)