@flusys/nestjs-shared 4.1.0 → 5.0.0

package/README.md

@@ -1,92 +1,9 @@
 # @flusys/nestjs-shared
 
-> Shared NestJS infrastructure — generic CRUD base classes, JWT guards, permission system, hybrid caching, structured logging, multi-tenancy, and response standardization for the entire FLUSYS ecosystem.
+Shared infrastructure for all FLUSYS NestJS packages — base CRUD classes, JWT guard, permission guard, response DTOs, hybrid cache, structured logging, and soft-delete entities.
 
 [![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)
-[![NestJS](https://img.shields.io/badge/NestJS-11.x-red.svg)](https://nestjs.com/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.x-green.svg)](https://nodejs.org/)
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Features](#features)
-- [Architecture Position](#architecture-position)
-- [Compatibility](#compatibility)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Base Classes](#base-classes)
-  - [ApiService](#apiservice)
-  - [RequestScopedApiService](#requestscopedapiservice)
-  - [createApiController](#createapicontroller)
-- [Base Entities](#base-entities)
-- [Response DTOs](#response-dtos)
-- [Guards](#guards)
-- [Decorators](#decorators)
-- [Interceptors](#interceptors)
-- [HybridCache](#hybridcache)
-- [Middlewares](#middlewares)
-- [Exceptions & Filters](#exceptions--filters)
-- [Modules](#modules)
-- [Multi-Tenant DataSource Service](#multi-tenant-datasource-service)
-- [Logger System](#logger-system)
-- [Permission System](#permission-system)
-- [Permission Constants](#permission-constants)
-- [Cross-Module Adapter Interfaces](#cross-module-adapter-interfaces)
-- [Troubleshooting](#troubleshooting)
-- [License](#license)
-
----
-
-## Overview
-
-`@flusys/nestjs-shared` is the shared infrastructure layer that all FLUSYS feature modules depend on. It provides the building blocks — generic CRUD, guards, decorators, DTOs, caching — so each feature module only needs to implement business logic.
-
----
-
-## Features
-
-- **Generic CRUD** — `ApiService` + `createApiController` with 7 standardized POST-only RPC endpoints
-- **Permission System** — AND/OR/nested logic trees with wildcard matching, action-level guards
-- **Hybrid Cache** — In-memory (CacheableMemory) + Redis (`@keyv/redis`) with automatic L1/L2 fallback
-- **Request Correlation** — `AsyncLocalStorage`-based request tracking with correlation IDs
-- **Structured Logging** — Winston + daily-rotate-file with tenant-aware routing
-- **Multi-Tenancy** — Dynamic database connection management with per-tenant DataSource pooling
-- **Response Standardization** — Consistent `SingleResponseDto`, `ListResponseDto`, `BulkResponseDto`, `MessageResponseDto`
-- **Security** — HTML sanitization (XSS prevention), slug generation, path traversal protection
-- **Interceptors** — Response metadata, idempotency, audit fields, slug auto-generation
-
----
-
-## Architecture Position
-
-```
-@flusys/nestjs-core
-        ↓
-@flusys/nestjs-shared   ← THIS PACKAGE
-        ↓
-┌───────┴───────────────────────┐
-auth  iam  storage  form-builder  email  event-manager  notification  localization
-(all depend on nestjs-shared, none depend on each other)
-```
-
----
-
-## Compatibility
-
-| Package | Version |
-|---------|---------|
-| `@flusys/nestjs-core` | `^4.0.0` |
-| `@nestjs/core` | `^11.0.0` |
-| `@nestjs/common` | `^11.0.0` |
-| `@nestjs/passport` | `^10.0.0` |
-| `typeorm` | `^0.3.0` |
-| `winston` | `^3.0.0` |
-| `keyv` | `^5.0.0` |
-| Node.js | `>= 18.x` |
 
 ---
 
@@ -94,22 +11,24 @@ auth  iam  storage  form-builder  email  event-manager  notification  localizati
 
 ```bash
 npm install @flusys/nestjs-shared @flusys/nestjs-core
+npm install typeorm @nestjs/passport @nestjs/jwt passport-jwt winston
 ```
 
----
-
-## Quick Start
+## 1. Module Registration
 
-### 1. Register Global Modules
+Register once in your root `AppModule`:
 
 ```typescript
 import { Module, MiddlewareConsumer, NestModule } from '@nestjs/common';
-import { CacheModule, UtilsModule, LoggerMiddleware } from '@flusys/nestjs-shared';
+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';
 
 @Module({
   imports: [
-    CacheModule.forRoot(true), // true = global
-    UtilsModule,
+    CacheModule.forRoot(true),  // true = global; provides 'CACHE_INSTANCE' token
+    UtilsModule,                // provides UtilsService
   ],
 })
 export class AppModule implements NestModule {
@@ -117,107 +36,69 @@ export class AppModule implements NestModule {
     consumer.apply(LoggerMiddleware).forRoutes('*');
   }
 }
-```
 
-### 2. Register Global Exception Filter & Interceptors
-
-```typescript
-import { GlobalExceptionFilter, ResponseMetaInterceptor } from '@flusys/nestjs-shared';
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  app.useGlobalFilters(new GlobalExceptionFilter());
-  app.useGlobalInterceptors(new ResponseMetaInterceptor());
-  await app.listen(3000);
-}
+// In bootstrap()
+app.useGlobalFilters(new GlobalExceptionFilter());
+app.useGlobalInterceptors(new ResponseMetaInterceptor());
 ```
 
----
-
-## Base Classes
-
-### ApiService
+## 2. Entity Base Class
 
-Generic CRUD service for simple, static repositories (no dynamic entity switching):
+Every entity must extend `Identity`:
 
 ```typescript
-import { Injectable, Inject } from '@nestjs/common';
-import { InjectRepository } from '@nestjs/typeorm';
-import { Repository } from 'typeorm';
-import { ApiService } from '@flusys/nestjs-shared/classes';
-import { HybridCache } from '@flusys/nestjs-shared/classes';
-import { UtilsService } from '@flusys/nestjs-shared/modules';
+import { Entity, Column } from 'typeorm';
+import { Identity } from '@flusys/nestjs-shared/entities';
 
-@Injectable()
-export class ProductService extends ApiService<
-  CreateProductDto,
-  UpdateProductDto,
-  IProduct,
-  Product,
-  Repository<Product>
-> {
-  constructor(
-    @InjectRepository(Product) repo: Repository<Product>,
-    @Inject('CACHE_INSTANCE') cacheManager: HybridCache,
-    @Inject(UtilsService) utilsService: UtilsService,
-  ) {
-    super('product', repo, cacheManager, utilsService, ProductService.name);
-  }
+@Entity('products')
+export class Product extends Identity {
+  @Column({ length: 255 })
+  name: string;
+  // inherited: id (uuid), createdAt, updatedAt, deletedAt,
+  //            createdById, updatedById, deletedById
 }
 ```
 
-**Built-in methods:**
+## 3. Generic CRUD — `createApiController` + `RequestScopedApiService`
 
-| Method | Description |
-|--------|-------------|
-| `insert(dto, user)` | Create a single record |
-| `insertMany(dtos, user)` | Bulk create records |
-| `update(dto, user)` | Update a record by ID |
-| `updateMany(dtos, user)` | Bulk update records |
-| `delete(dto, user)` | Soft delete by ID |
-| `getAll(filter, user)` | Paginated list with filtering |
-| `getById(id, dto)` | Get single record by ID |
-
-### RequestScopedApiService
-
-For services that need **dynamic entity loading** per request (DataSource Provider pattern). Use this for all feature modules that have `WithCompany` entity variants:
+### Service (REQUEST-scoped, DataSource Provider pattern)
 
 ```typescript
 import { Injectable, Scope, Inject } from '@nestjs/common';
+import { EntityTarget, Repository } from 'typeorm';
 import { RequestScopedApiService } from '@flusys/nestjs-shared/classes';
 import { HybridCache } from '@flusys/nestjs-shared/classes';
 import { UtilsService } from '@flusys/nestjs-shared/modules';
 
-@Injectable({ scope: Scope.REQUEST }) // REQUEST scope required
+@Injectable({ scope: Scope.REQUEST }) // required
 export class ProductService extends RequestScopedApiService<
   CreateProductDto,
   UpdateProductDto,
   IProduct,
-  ProductBase,
-  Repository<ProductBase>
+  Product,
+  Repository<Product>
 > {
   constructor(
     @Inject('CACHE_INSTANCE') protected override cacheManager: HybridCache,
     @Inject(UtilsService) protected override utilsService: UtilsService,
-    @Inject(ModuleConfigService) private readonly moduleConfig: ModuleConfigService,
-    @Inject(DataSourceProvider) private readonly dataSourceProvider: DataSourceProvider,
+    @Inject(ProductConfigService) private readonly config: ProductConfigService,
+    @Inject(ProductDataSourceProvider) private readonly dsp: ProductDataSourceProvider,
   ) {
     super('product', null as any, cacheManager, utilsService, ProductService.name, true);
   }
 
-  protected override async ensureRepositoryInitialized(): Promise<void> {
-    if (!this.repositoryInitialized) {
-      const entity = this.moduleConfig.isCompanyFeatureEnabled() ? ProductWithCompany : Product;
-      this.repository = await this.dataSourceProvider.getRepository(entity);
-      this.repositoryInitialized = true;
-    }
+  // Required: tell the base class which entity and which datasource to use
+  protected resolveEntity(): EntityTarget<Product> {
+    return this.config.isCompanyFeatureEnabled() ? ProductWithCompany : Product;
+  }
+
+  protected getDataSourceProvider() {
+    return this.dsp;
   }
 }
 ```
 
-### createApiController
-
-Factory function that generates a fully-typed CRUD controller class:
+### Controller (factory function)
 
 ```typescript
 import { Controller, Inject } from '@nestjs/common';
@@ -235,11 +116,14 @@ export class ProductController extends createApiController<
   security: {
     insert:     { level: 'permission', permissions: ['product.create'] },
     insertMany: { level: 'permission', permissions: ['product.create'] },
-    getById:    { level: 'permission', permissions: ['product.read'] },
     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) {
@@ -248,236 +132,54 @@ export class ProductController extends createApiController<
 }
 ```
 
-**Generated endpoints:**
+Generated POST-only endpoints: `/insert`, `/insert-many`, `/get-all`, `/get/:id`,
+`/get-by-ids`, `/get-by-filter`, `/update`, `/update-many`, `/bulk-upsert`, `/delete`.
 
-| Route | Method | Permission |
-|-------|--------|-----------|
-| `POST /products/insert` | `insert` | configurable |
-| `POST /products/insert-many` | `insertMany` | configurable |
-| `POST /products/get-all` | `getAll` | configurable |
-| `POST /products/get/:id` | `getById` | configurable |
-| `POST /products/update` | `update` | configurable |
-| `POST /products/update-many` | `updateMany` | configurable |
-| `POST /products/delete` | `delete` | configurable |
-
-**Security levels:**
-
-| Level | Description |
-|-------|-------------|
-| `'public'` | No authentication required (`@Public()`) |
-| `'authenticated'` | Requires valid JWT only |
-| `'permission'` | Requires JWT + specific action permissions |
-
----
+Security levels: `'public'` (no auth), `'jwt'` (token only), `'permission'` (token + action check).
 
-## Base Entities
-
-### Identity (IdentityEntity)
-
-Base entity for all FLUSYS entities. All entities must extend this:
-
-```typescript
-import { Identity } from '@flusys/nestjs-shared/entities';
-
-@Entity('products')
-export class Product extends Identity {
-  @Column() name: string;
-  // id, createdAt, updatedAt, deletedAt inherited
-}
-```
-
-**Fields:**
-
-| Column | Type | Description |
-|--------|------|-------------|
-| `id` | `uuid` | Primary key, auto-generated |
-| `createdAt` | `timestamp` | Auto-set on insert |
-| `updatedAt` | `timestamp` | Auto-updated on save |
-| `deletedAt` | `timestamp \| null` | Soft delete timestamp |
-| `createdBy` | `uuid \| null` | User ID that created the record |
-| `updatedBy` | `uuid \| null` | User ID that last updated the record |
-
-### UserRoot
-
-Extended base entity for user entities. `@flusys/nestjs-auth`'s `User` extends this:
-
-```typescript
-import { UserRoot } from '@flusys/nestjs-shared/entities';
-
-@Entity('user')
-export class User extends UserRoot {
-  // Inherits: id, email, name, password, phone, avatar,
-  //           isEmailVerified, isPhoneVerified, isActive, isSystemUser,
-  //           lastLoginAt, createdAt, updatedAt, deletedAt
-}
-```
-
----
-
-## Response DTOs
-
-All responses follow a consistent structure:
-
-```typescript
-import {
-  SingleResponseDto,
-  ListResponseDto,
-  BulkResponseDto,
-  MessageResponseDto,
-} from '@flusys/nestjs-shared/dtos';
-```
-
-| DTO | Shape | Used for |
-|-----|-------|---------|
-| `SingleResponseDto<T>` | `{ success, message, messageKey?, data?, _meta? }` | insert, update, getById |
-| `ListResponseDto<T>` | `{ success, message, messageKey?, data?, meta, _meta? }` | getAll |
-| `BulkResponseDto<T>` | `{ success, message, messageKey?, data?, meta, _meta? }` | insertMany, updateMany |
-| `MessageResponseDto` | `{ success, message, messageKey?, _meta? }` | delete, actions |
-
-**PaginationMetaDto:**
-```typescript
-{ total: number; page: number; pageSize: number; count: number; hasMore?: boolean; totalPages?: number }
-```
-
-**messageKey:** Every response includes a `messageKey` string (e.g., `'auth.login_success'`) for frontend localization. The frontend can look up this key in its translation dictionary instead of relying on the English message text.
-
----
-
-## Guards
-
-### JwtAuthGuard
-
-Validates Bearer JWT tokens on incoming requests:
+## 4. Guards and Decorators
 
 ```typescript
 import { JwtAuthGuard } from '@flusys/nestjs-shared/guards';
-
-@UseGuards(JwtAuthGuard)
-@Post('protected')
-async protectedEndpoint(@CurrentUser() user: ILoggedUserInfo) { }
-```
-
-Applied globally by default in the FLUSYS app. Use `@Public()` to bypass.
-
-### PermissionGuard
-
-Checks that the authenticated user has the required action permission:
-
-```typescript
 import { PermissionGuard } from '@flusys/nestjs-shared/guards';
-import { RequirePermission } from '@flusys/nestjs-shared/decorators';
+import {
+  CurrentUser,
+  Public,
+  RequirePermission,
+  RequireAnyPermission,
+} from '@flusys/nestjs-shared/decorators';
+import { ILoggedUserInfo } from '@flusys/nestjs-shared/interfaces';
 
 @UseGuards(JwtAuthGuard, PermissionGuard)
 @RequirePermission('product.create')
 @Post('insert')
-async insert() { }
-```
-
-> **Note:** Always use `@Inject(Reflector)` in your guard constructors — esbuild bundling loses TypeScript metadata.
-
----
-
-## Decorators
-
-| Decorator | Import | Description |
-|-----------|--------|-------------|
-| `@CurrentUser()` | `@flusys/nestjs-shared/decorators` | Inject full `ILoggedUserInfo` object |
-| `@CurrentUser('id')` | `@flusys/nestjs-shared/decorators` | Inject a specific field from user info |
-| `@Public()` | `@flusys/nestjs-shared/decorators` | Mark endpoint as public (skip JWT guard) |
-| `@RequirePermission(action)` | `@flusys/nestjs-shared/decorators` | Require a specific action permission |
-| `@RequireAnyPermission(...actions)` | `@flusys/nestjs-shared/decorators` | Require any one of listed permissions |
-| `@SanitizeHtml()` | `@flusys/nestjs-shared/decorators` | Strip HTML tags from string fields |
-| `@SanitizeAndTrim()` | `@flusys/nestjs-shared/decorators` | Strip HTML and trim whitespace |
-| `@LogAction(description)` | `@flusys/nestjs-shared/decorators` | Log method calls for audit |
-| `@ApiResponseDto(type)` | `@flusys/nestjs-shared/decorators` | Swagger response shorthand |
-
-### ILoggedUserInfo
-
-```typescript
-interface ILoggedUserInfo {
-  id: string;
-  email: string;
-  name: string;
-  companyId?: string;
-  branchId?: string;
-  permissions?: string[];
-  isSystemUser?: boolean;
-}
-```
-
----
-
-## Interceptors
-
-| Interceptor | Token | Description |
-|-------------|-------|-------------|
-| `ResponseMetaInterceptor` | class | Adds `_meta` (requestId, timestamp, duration) to all responses |
-| `IdempotencyInterceptor` | class | Prevents duplicate POST requests using `x-idempotency-key` header |
-| `SetCreatedByInterceptor` | class | Auto-sets `createdBy` from JWT user on insert |
-| `SetUpdatedByInterceptor` | class | Auto-sets `updatedBy` from JWT user on update |
-| `DeleteEmptyIdInterceptor` | class | Strips empty `id` fields from request bodies |
-| `SlugInterceptor` | class | Auto-generates URL slugs from `name` fields |
-
----
-
-## HybridCache
-
-Two-tier cache: L1 in-memory (CacheableMemory) → L2 Redis. Automatically falls back to in-memory if Redis is unavailable.
-
-```typescript
-import { HybridCache } from '@flusys/nestjs-shared/classes';
-
-@Injectable()
-export class MyService {
-  constructor(@Inject('CACHE_INSTANCE') private cache: HybridCache) {}
-
-  async getData(key: string): Promise<any> {
-    const cached = await this.cache.get(key);
-    if (cached) return cached;
-
-    const data = await this.fetchFromDb();
-    await this.cache.set(key, data, 3600); // TTL in seconds
-    return data;
-  }
+async insert(@Body() dto: CreateProductDto, @CurrentUser() user: ILoggedUserInfo) { }
 
-  async invalidate(key: string): Promise<void> {
-    await this.cache.delete(key);
-  }
-
-  async invalidateByPrefix(prefix: string): Promise<void> {
-    await this.cache.deleteByPrefix(prefix);
-  }
-}
+// Mark endpoint public (no JWT required)
+@Public()
+@Post('public-list')
+async publicList() { }
 ```
 
----
-
-## Middlewares
+`ILoggedUserInfo` fields: `id`, `email`, `name?`, `phone?`, `profilePictureId?`, `companyId?`, `branchId?`.
 
-### LoggerMiddleware
+## 5. Response DTOs
 
-HTTP request/response logger with correlation IDs. Attach to all routes:
+All controllers return one of these shapes:
 
 ```typescript
-import { LoggerMiddleware } from '@flusys/nestjs-shared/middlewares';
+import {
+  SingleResponseDto,   // insert, update, getById
+  ListResponseDto,     // getAll, getByIds
+  BulkResponseDto,     // insertMany, updateMany, bulkUpsert
+  MessageResponseDto,  // delete
+} from '@flusys/nestjs-shared/dtos';
 
-@Module({})
-export class AppModule implements NestModule {
-  configure(consumer: MiddlewareConsumer) {
-    consumer.apply(LoggerMiddleware).forRoutes('*');
-  }
-}
+// All shapes include: success, message, messageKey (for i18n), _meta (requestId, timestamp, duration)
+// ListResponseDto / BulkResponseDto also include: meta (total, page, pageSize, count, totalPages)
 ```
 
-Logged fields: method, URL, status, duration, requestId, userId (from JWT), IP, user-agent.
-
-The middleware also sets an `AsyncLocalStorage` context so `requestId` and `userId` are available in any service without passing them through method parameters.
-
----
-
-## Exceptions & Filters
-
-### Built-in Exception Classes
+## 6. Exceptions
 
 ```typescript
 import {
@@ -485,261 +187,49 @@ import {
   ConflictException,
   UnauthorizedException,
   ForbiddenException,
-  BadRequestException,
   ValidationException,
+  InternalServerException,
 } from '@flusys/nestjs-shared/exceptions';
 
-// All exceptions accept { message, messageKey } for localization
-throw new NotFoundException({ message: 'User not found', messageKey: 'user.not_found' });
-```
-
-### GlobalExceptionFilter
-
-Catches all unhandled exceptions and returns a consistent error response:
-
-```typescript
-// Register globally
-app.useGlobalFilters(new GlobalExceptionFilter());
-```
-
-Error response shape:
-```json
-{
-  "success": false,
-  "message": "User not found",
-  "messageKey": "user.not_found",
-  "code": 404,
-  "_meta": { "requestId": "...", "timestamp": "..." }
-}
-```
-
----
-
-## Modules
-
-### CacheModule
-
-```typescript
-import { CacheModule } from '@flusys/nestjs-shared/modules';
-
-// Global (register once in AppModule)
-CacheModule.forRoot(true)
-
-// Local (non-global)
-CacheModule.forRoot(false)
-```
-
-Provides `HybridCache` as `'CACHE_INSTANCE'` injection token. Automatically connects to Redis if `REDIS_URL` is set.
-
-### UtilsModule
-
-```typescript
-import { UtilsModule } from '@flusys/nestjs-shared/modules';
-
-@Module({ imports: [UtilsModule] })
-export class AppModule {}
-```
-
-Provides `UtilsService` with slug generation, HTML sanitization, and query helper utilities.
-
-### DataSourceModule
-
-```typescript
-import { DataSourceModule } from '@flusys/nestjs-shared/modules';
-
-DataSourceModule.forRoot(dataSourceOptions)
+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' }]);
 ```
 
-Wraps `MultiTenantDataSourceService` for dynamic tenant-based DataSource resolution.
-
----
-
-## Multi-Tenant DataSource Service
+All exceptions produce: `{ success: false, message, messageKey,messageVariables:{} code, _meta }`.
 
-`MultiTenantDataSourceService` manages separate TypeORM DataSource connections per tenant. Each feature module extends it to create an isolated static connection cache:
+## 7. Hybrid Cache
 
 ```typescript
-import { MultiTenantDataSourceService } from '@flusys/nestjs-shared/modules';
+import { HybridCache } from '@flusys/nestjs-shared/classes';
 
-// Feature module DataSource Provider (extends with isolated cache)
 @Injectable()
-export class ProductDataSourceProvider extends MultiTenantDataSourceService {
-  // Static cache isolated to this module
-  private static moduleDataSource: DataSource | null = null;
-  private static moduleTenantSources: Map<string, DataSource> = new Map();
+export class MyService {
+  constructor(@Inject('CACHE_INSTANCE') private cache: HybridCache) {}
 
-  protected override getSingleDataSource(): DataSource | null {
-    return ProductDataSourceProvider.moduleDataSource;
+  async getData(key: string) {
+    const cached = await this.cache.get(key);
+    if (cached) return cached;
+    const data = await this.fetchFromDb();
+    await this.cache.set(key, data, 3600); // TTL in seconds
+    return data;
   }
 
-  // ... override other cache accessors
+  async invalidate(key: string) { await this.cache.delete(key); }
+  async invalidatePrefix(prefix: string) { await this.cache.deleteByPrefix(prefix); }
 }
 ```
 
----
-
-## Logger System
+`CacheModule.forRoot(true)` connects to Redis automatically when `REDIS_URL` is set; otherwise uses in-memory only.
 
-Winston-based structured logger with daily file rotation:
-
-```typescript
-import { WinstonLoggerAdapter, NestLoggerAdapter } from '@flusys/nestjs-shared/classes';
-
-// Use as NestJS app logger
-const app = await NestFactory.create(AppModule, {
-  logger: new NestLoggerAdapter(),
-});
-```
-
-Log levels: `error`, `warn`, `info`, `http`, `debug`. Configured via `LOG_LEVEL` env var.
-
-Files rotate daily. Configured via `LOG_DIR`, `LOG_MAX_SIZE`, `LOG_MAX_FILES` env vars.
-
----
-
-## Permission System
-
-Permission logic supports complex AND/OR trees with wildcard matching:
-
-```typescript
-import { IPermissionLogic, IActionNode, IGroupNode } from '@flusys/nestjs-shared/interfaces';
-
-// Single permission
-const simple: IPermissionLogic = { action: 'product.read' };
-
-// Wildcard
-const wildcard: IPermissionLogic = { action: 'product.*' };
-
-// AND logic (user needs ALL of these)
-const andLogic: IPermissionLogic = {
-  operator: 'AND',
-  children: [
-    { action: 'product.read' },
-    { action: 'product.update' },
-  ],
-};
-
-// OR logic (user needs ANY of these)
-const orLogic: IPermissionLogic = {
-  operator: 'OR',
-  children: [
-    { action: 'admin.*' },
-    { action: 'product.read' },
-  ],
-};
-
-// Nested
-const nested: IPermissionLogic = {
-  operator: 'AND',
-  children: [
-    { action: 'product.read' },
-    {
-      operator: 'OR',
-      children: [{ action: 'admin.manage' }, { action: 'product.update' }],
-    },
-  ],
-};
-```
-
----
-
-## Permission Constants
-
-All module permission strings are centralized here:
-
-```typescript
-import {
-  USER_PERMISSIONS,
-  COMPANY_PERMISSIONS,
-  ROLE_PERMISSIONS,
-  ACTION_PERMISSIONS,
-  FILE_PERMISSIONS,
-  FOLDER_PERMISSIONS,
-  STORAGE_CONFIG_PERMISSIONS,
-  FORM_PERMISSIONS,
-  FORM_RESULT_PERMISSIONS,
-  EMAIL_TEMPLATE_PERMISSIONS,
-  EMAIL_CONFIG_PERMISSIONS,
-  LANGUAGE_PERMISSIONS,
-  TRANSLATION_PERMISSIONS,
-  NOTIFICATION_PERMISSIONS,
-  EVENT_PERMISSIONS,
-} from '@flusys/nestjs-shared/constants';
-
-// Example: USER_PERMISSIONS
-// { CREATE: 'user.create', READ: 'user.read', UPDATE: 'user.update', DELETE: 'user.delete' }
-```
-
----
-
-## Cross-Module Adapter Interfaces
-
-These interfaces are defined in `nestjs-shared` so modules can reference the contract without importing each other:
-
-```typescript
-import { INotificationAdapter, NOTIFICATION_ADAPTER } from '@flusys/nestjs-shared/interfaces';
-import { IEventManagerAdapter, EVENT_MANAGER_ADAPTER } from '@flusys/nestjs-shared/interfaces';
-```
-
-Pattern: Feature module A wants to send a notification (defined in module B). Instead of importing B from A (circular dep), A imports only the interface from `nestjs-shared` and uses `@Optional() @Inject(NOTIFICATION_ADAPTER)`.
-
----
-
-## Troubleshooting
-
-**`Cannot read properties of undefined` on injected service**
-
-All constructor dependencies need `@Inject()` decorators — esbuild bundling loses TypeScript metadata:
-
-```typescript
-// Wrong
-constructor(private readonly service: MyService) {}
-
-// Correct
-constructor(@Inject(MyService) private readonly service: MyService) {}
-```
-
----
-
-**`No metadata for entity X`**
-
-You are using `RequestScopedApiService` but forgot to call `ensureRepositoryInitialized()` before accessing `this.repository`. Override the method:
-
-```typescript
-protected override async ensureRepositoryInitialized(): Promise<void> {
-  if (!this.repositoryInitialized) {
-    this.repository = await this.dataSourceProvider.getRepository(MyEntity);
-    this.repositoryInitialized = true;
-  }
-}
-```
-
----
-
-**Cache not connecting to Redis**
-
-`CacheModule` falls back to in-memory automatically if `REDIS_URL` is not set or Redis is unreachable. Check that `REDIS_URL` is set correctly in your `.env` file.
-
----
-
-**`instanceof` checks fail after bundling**
-
-Use property-based checks instead:
-
-```typescript
-// Wrong (fails after esbuild)
-if (dto instanceof UpdateProductDto) { }
-
-// Correct
-if ('id' in dto && dto.id) { }
-```
-
----
 
 ## License
 
 MIT © FLUSYS
-
----
-
-> Part of the **FLUSYS** framework — a full-stack monorepo powering Angular 21 + NestJS 11 applications.