@flusys/nestjs-shared 1.0.0-beta → 1.0.0-rc

package/README.md

@@ -121,7 +121,6 @@ nestjs-shared/
 │   │
 │   ├── interfaces/           # TypeScript interfaces
 │   │   ├── api.interface.ts
-│   │   ├── base-query.interface.ts
 │   │   ├── identity.interface.ts
 │   │   ├── logged-user-info.interface.ts
 │   │   ├── logger.interface.ts
@@ -298,7 +297,7 @@ override async getExtraManipulateQuery(
 
 ## ApiController - Generic CRUD Controller
 
-The `createApiController` factory creates standardized REST API controllers.
+The `createApiController` factory creates standardized POST-only RPC controllers.
 
 ### Basic Usage
 
@@ -516,100 +515,56 @@ 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:**
+Validates JWT tokens for protected routes. Extends Passport's `AuthGuard('jwt')` and respects `@Public()` decorator.
 
 ```typescript
 import { JwtAuthGuard } from '@flusys/nestjs-shared/guards';
-import { UseGuards } from '@nestjs/common';
 
-// Protect entire controller
+// Apply globally
+@Module({
+  providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }],
+})
+export class AppModule {}
+
+// Or per controller
 @Controller('users')
 @UseGuards(JwtAuthGuard)
 export class UserController {
-  // All routes protected
-
   @Post('login')
-  @Public()  // Skip JWT check for this route
+  @Public()  // Skip JWT check
   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.
+Checks user permissions from cache with AND/OR/nested logic support.
 
 ```typescript
-import { Module } from '@nestjs/common';
-import { APP_GUARD } from '@nestjs/core';
 import { PermissionGuard } from '@flusys/nestjs-shared/guards';
 
+// Apply globally
 @Module({
-  providers: [
-    {
-      provide: APP_GUARD,
-      useClass: PermissionGuard,
-    },
-  ],
+  providers: [{ provide: APP_GUARD, useClass: PermissionGuard }],
 })
 export class AppModule {}
 ```
 
-### Permission Cache Key Format
+**Cache Key Formats:**
 
 ```typescript
 // Without company feature
 `permissions:user:{userId}`
 
-// With company feature (includes branchId for DIRECT permissions)
+// With company feature
 `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,
-});
-```
+**Features:**
+- Supports AND/OR operators via `@RequirePermission` and `@RequireAnyPermission`
+- Nested conditions via `@RequirePermissionCondition`
+- Wildcard support (`*` and `*.suffix`)
+- Company/branch scoped permissions
 
 ---
 
@@ -906,7 +861,7 @@ export class PostController {
 
 ### Slug Interceptor
 
-Auto-generate slugs from name field:
+Auto-generate slugs from name field using UtilsService (injected via DI):
 
 ```typescript
 import { Slug } from '@flusys/nestjs-shared/interceptors';
@@ -922,6 +877,8 @@ export class ProductController {
 }
 ```
 
+**Note:** Requires `UtilsModule` to be imported in your module for dependency injection.
+
 ---
 
 ## Caching System
@@ -1005,7 +962,7 @@ export class AppModule {}
 
 ## Multi-Tenant DataSource
 
-Dynamic database connection management for multi-tenant applications.
+Dynamic database connection management with connection pooling and request-scoped tenant resolution.
 
 ### Setup
 
@@ -1015,7 +972,7 @@ import { DataSourceModule } from '@flusys/nestjs-shared/modules';
 @Module({
   imports: [
     DataSourceModule.forRoot({
-      // Default database config (used as template)
+      bootstrapAppConfig: { databaseMode: 'multi-tenant' },
       defaultDatabaseConfig: {
         type: 'mysql',
         host: 'localhost',
@@ -1023,11 +980,9 @@ import { DataSourceModule } from '@flusys/nestjs-shared/modules';
         username: 'root',
         password: 'password',
       },
-
-      // Tenant configurations
       tenants: [
-        { id: 'tenant1', database: 'tenant1_db', isActive: true },
-        { id: 'tenant2', database: 'tenant2_db', isActive: true },
+        { id: 'tenant1', database: 'tenant1_db' },
+        { id: 'tenant2', database: 'tenant2_db' },
       ],
     }),
   ],
@@ -1035,41 +990,35 @@ import { DataSourceModule } from '@flusys/nestjs-shared/modules';
 export class AppModule {}
 ```
 
-### Usage with Tenant Header
+### Key Methods
 
-```typescript
-// Client sends X-Tenant-ID header
-// DataSource automatically switches to tenant's database
+| Method | Description |
+|--------|-------------|
+| `getDataSource()` | Get DataSource for current tenant (from header) |
+| `getDataSourceForTenant(id)` | Get DataSource for specific tenant |
+| `getRepository(entity)` | Get repository for current tenant |
+| `withTenant(id, callback)` | Execute callback with specific tenant DataSource |
+| `forAllTenants(callback)` | Execute callback for all active tenants |
+| `registerTenant(config)` | Register new tenant at runtime |
+| `removeTenant(id)` | Remove tenant and close connection |
+
+### Usage
 
+```typescript
 @Injectable()
 export class TenantService {
-  constructor(
-    @Inject('DATASOURCE_PROVIDER')
-    private dataSourceProvider: MultiTenantDataSourceService,
-  ) {}
+  constructor(private dataSource: MultiTenantDataSourceService) {}
 
-  async getConnection(tenantId: string) {
-    return this.dataSourceProvider.getConnection(tenantId);
+  async getUsers() {
+    // Auto-resolves tenant from X-Tenant-ID header
+    const repo = await this.dataSource.getRepository(User);
+    return repo.find();
   }
-}
-```
-
-### 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);
-    // ...
+  async crossTenantCopy(fromId: string, toId: string) {
+    const fromDs = await this.dataSource.getDataSourceForTenant(fromId);
+    const toDs = await this.dataSource.getDataSourceForTenant(toId);
+    // Copy data between tenants
   }
 }
 ```
@@ -1092,18 +1041,15 @@ import { FilterAndPaginationDto } from '@flusys/nestjs-shared/dtos';
     "category": "electronics"
   },
   "pagination": {
-    "page": 1,
-    "limit": 10
+    "currentPage": 0,
+    "pageSize": 10
   },
   "sort": {
-    "field": "createdAt",
-    "order": "DESC"
-  },
-  "search": {
-    "fields": ["name", "description"],
-    "value": "laptop"
+    "createdAt": "DESC",
+    "name": "ASC"
   },
-  "select": ["id", "name", "price"]
+  "select": ["id", "name", "price"],
+  "withDeleted": false
 }
 ```
 
@@ -1418,4 +1364,4 @@ This is the shared infrastructure layer used by all other Flusys packages.
 
 ---
 
-**Last Updated:** 2026-02-16
+**Last Updated:** 2026-02-18

package/cjs/classes/api-controller.class.js

@@ -8,10 +8,10 @@ Object.defineProperty(exports, "createApiController", {
         return createApiController;
     }
 });
-const _decorators = require("@flusys/nestjs-shared/decorators");
-const _dtos = require("@flusys/nestjs-shared/dtos");
-const _guards = require("@flusys/nestjs-shared/guards");
-const _interceptors = require("@flusys/nestjs-shared/interceptors");
+const _decorators = require("../decorators");
+const _dtos = require("../dtos");
+const _guards = require("../guards");
+const _interceptors = require("../interceptors");
 const _common = require("@nestjs/common");
 const _swagger = require("@nestjs/swagger");
 const _classtransformer = require("class-transformer");
@@ -104,8 +104,10 @@ function createApiController(createDtoClass, updateDtoClass, responseDtoClass, o
     // 2. It's an object with 'level' property but no endpoint keys
     const isGlobalSecurity = typeof securityConfig === 'string' || securityConfig && typeof securityConfig === 'object' && 'level' in securityConfig && !endpointKeys.some((key)=>key in securityConfig);
     // Normalize security config for each endpoint
+    // IMPORTANT: When per-endpoint security is specified, default to 'jwt' for unconfigured endpoints
+    // to prevent accidentally exposing endpoints without authentication
     const defaultSecurity = isGlobalSecurity ? normalizeSecurity(securityConfig) : {
-        level: 'public'
+        level: 'jwt'
     };
     const security = {
         insert: isGlobalSecurity ? defaultSecurity : normalizeSecurity(securityConfig?.insert),
@@ -347,16 +349,7 @@ function createApiController(createDtoClass, updateDtoClass, responseDtoClass, o
         (0, _common.HttpCode)(_common.HttpStatus.OK),
         (0, _swagger.ApiOperation)({
             summary: 'Get all items with filters and pagination',
-            description: `
-Retrieves items with support for:
-- **filter**: Apply field-based filters (e.g., \`{ "isActive": true }\`)
-- **pagination**: Control page and page size
-- **sort**: Order by any field (e.g., \`{ "createdAt": "DESC" }\`)
-- **select**: Choose specific fields to return
-- **withDeleted**: Include soft-deleted items
-- **extraKey**: Include additional relations
-- **q** (query param): Global text search
-      `
+            description: 'Supports filter, pagination, sort, select, withDeleted, and q (search) params'
         }),
         (0, _swagger.ApiQuery)({
             name: 'q',
@@ -385,15 +378,7 @@ Retrieves items with support for:
         (0, _common.HttpCode)(_common.HttpStatus.OK),
         (0, _swagger.ApiOperation)({
             summary: 'Delete, restore, or permanently remove items',
-            description: `
-Performs one of three actions:
-
-- **"delete"** (soft delete): Marks items as deleted but keeps in database
-- **"restore"**: Reverts soft-deleted items to active
-- **"permanent"**: Completely removes items from database
-
-Supports single ID or array of IDs for batch operations.
-      `
+            description: 'Types: delete (soft), restore, permanent. Supports batch IDs.'
         }),
         (0, _swagger.ApiResponse)({
             status: 200,

package/cjs/classes/index.js

@@ -8,6 +8,7 @@ _export_star(require("./request-scoped-api.service"), exports);
 _export_star(require("./hybrid-cache.class"), exports);
 _export_star(require("./winston-logger-adapter.class"), exports);
 _export_star(require("./winston.logger.class"), exports);
+_export_star(require("../constants/permissions"), exports);
 function _export_star(from, to) {
     Object.keys(from).forEach(function(k) {
         if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {

package/cjs/constants/index.js

@@ -41,6 +41,20 @@ _export(exports, {
         return REQUEST_ID_HEADER;
     }
 });
+_export_star(require("./permissions"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}
 const IS_PUBLIC_KEY = 'isPublic';
 const PERMISSIONS_KEY = 'permissions';
 const CACHE_INSTANCE = 'CACHE_INSTANCE';

package/cjs/constants/permissions.js

@@ -0,0 +1,174 @@
+/**
+ * Centralized Permission Codes
+ *
+ * Single source of truth for all permission codes used across the application.
+ * Use these constants instead of hardcoded strings to prevent typos and enable easy refactoring.
+ *
+ * Naming Convention: <entity>.<action>
+ * - entity: The resource being accessed (e.g., user, role, company)
+ * - action: The operation being performed (create, read, update, delete, assign)
+ */ // ==================== AUTH MODULE ====================
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get ACTION_PERMISSIONS () {
+        return ACTION_PERMISSIONS;
+    },
+    get BRANCH_PERMISSIONS () {
+        return BRANCH_PERMISSIONS;
+    },
+    get COMPANY_ACTION_PERMISSIONS () {
+        return COMPANY_ACTION_PERMISSIONS;
+    },
+    get COMPANY_PERMISSIONS () {
+        return COMPANY_PERMISSIONS;
+    },
+    get EMAIL_CONFIG_PERMISSIONS () {
+        return EMAIL_CONFIG_PERMISSIONS;
+    },
+    get EMAIL_TEMPLATE_PERMISSIONS () {
+        return EMAIL_TEMPLATE_PERMISSIONS;
+    },
+    get FILE_PERMISSIONS () {
+        return FILE_PERMISSIONS;
+    },
+    get FOLDER_PERMISSIONS () {
+        return FOLDER_PERMISSIONS;
+    },
+    get FORM_PERMISSIONS () {
+        return FORM_PERMISSIONS;
+    },
+    get PERMISSIONS () {
+        return PERMISSIONS;
+    },
+    get ROLE_ACTION_PERMISSIONS () {
+        return ROLE_ACTION_PERMISSIONS;
+    },
+    get ROLE_PERMISSIONS () {
+        return ROLE_PERMISSIONS;
+    },
+    get STORAGE_CONFIG_PERMISSIONS () {
+        return STORAGE_CONFIG_PERMISSIONS;
+    },
+    get USER_ACTION_PERMISSIONS () {
+        return USER_ACTION_PERMISSIONS;
+    },
+    get USER_PERMISSIONS () {
+        return USER_PERMISSIONS;
+    },
+    get USER_ROLE_PERMISSIONS () {
+        return USER_ROLE_PERMISSIONS;
+    }
+});
+const USER_PERMISSIONS = {
+    CREATE: 'user.create',
+    READ: 'user.read',
+    UPDATE: 'user.update',
+    DELETE: 'user.delete'
+};
+const COMPANY_PERMISSIONS = {
+    CREATE: 'company.create',
+    READ: 'company.read',
+    UPDATE: 'company.update',
+    DELETE: 'company.delete'
+};
+const BRANCH_PERMISSIONS = {
+    CREATE: 'branch.create',
+    READ: 'branch.read',
+    UPDATE: 'branch.update',
+    DELETE: 'branch.delete'
+};
+const ACTION_PERMISSIONS = {
+    CREATE: 'action.create',
+    READ: 'action.read',
+    UPDATE: 'action.update',
+    DELETE: 'action.delete'
+};
+const ROLE_PERMISSIONS = {
+    CREATE: 'role.create',
+    READ: 'role.read',
+    UPDATE: 'role.update',
+    DELETE: 'role.delete'
+};
+const ROLE_ACTION_PERMISSIONS = {
+    READ: 'role-action.read',
+    ASSIGN: 'role-action.assign'
+};
+const USER_ROLE_PERMISSIONS = {
+    READ: 'user-role.read',
+    ASSIGN: 'user-role.assign'
+};
+const USER_ACTION_PERMISSIONS = {
+    READ: 'user-action.read',
+    ASSIGN: 'user-action.assign'
+};
+const COMPANY_ACTION_PERMISSIONS = {
+    READ: 'company-action.read',
+    ASSIGN: 'company-action.assign'
+};
+const FILE_PERMISSIONS = {
+    CREATE: 'file.create',
+    READ: 'file.read',
+    UPDATE: 'file.update',
+    DELETE: 'file.delete'
+};
+const FOLDER_PERMISSIONS = {
+    CREATE: 'folder.create',
+    READ: 'folder.read',
+    UPDATE: 'folder.update',
+    DELETE: 'folder.delete'
+};
+const STORAGE_CONFIG_PERMISSIONS = {
+    CREATE: 'storage-config.create',
+    READ: 'storage-config.read',
+    UPDATE: 'storage-config.update',
+    DELETE: 'storage-config.delete'
+};
+const EMAIL_CONFIG_PERMISSIONS = {
+    CREATE: 'email-config.create',
+    READ: 'email-config.read',
+    UPDATE: 'email-config.update',
+    DELETE: 'email-config.delete'
+};
+const EMAIL_TEMPLATE_PERMISSIONS = {
+    CREATE: 'email-template.create',
+    READ: 'email-template.read',
+    UPDATE: 'email-template.update',
+    DELETE: 'email-template.delete'
+};
+const FORM_PERMISSIONS = {
+    CREATE: 'form.create',
+    READ: 'form.read',
+    UPDATE: 'form.update',
+    DELETE: 'form.delete'
+};
+const PERMISSIONS = {
+    // Auth
+    USER: USER_PERMISSIONS,
+    COMPANY: COMPANY_PERMISSIONS,
+    BRANCH: BRANCH_PERMISSIONS,
+    // IAM
+    ACTION: ACTION_PERMISSIONS,
+    ROLE: ROLE_PERMISSIONS,
+    ROLE_ACTION: ROLE_ACTION_PERMISSIONS,
+    USER_ROLE: USER_ROLE_PERMISSIONS,
+    USER_ACTION: USER_ACTION_PERMISSIONS,
+    COMPANY_ACTION: COMPANY_ACTION_PERMISSIONS,
+    // Storage
+    FILE: FILE_PERMISSIONS,
+    FOLDER: FOLDER_PERMISSIONS,
+    STORAGE_CONFIG: STORAGE_CONFIG_PERMISSIONS,
+    // Email
+    EMAIL_CONFIG: EMAIL_CONFIG_PERMISSIONS,
+    EMAIL_TEMPLATE: EMAIL_TEMPLATE_PERMISSIONS,
+    // Form Builder
+    FORM: FORM_PERMISSIONS
+};

package/cjs/decorators/api-response.decorator.js

@@ -8,7 +8,7 @@ Object.defineProperty(exports, "ApiResponseDto", {
         return ApiResponseDto;
     }
 });
-const _dtos = require("@flusys/nestjs-shared/dtos");
+const _dtos = require("../dtos");
 const _common = require("@nestjs/common");
 const _swagger = require("@nestjs/swagger");
 const ApiResponseDto = (dto, isArray = false, arrayType = 'list')=>{

package/cjs/decorators/index.js

@@ -6,6 +6,7 @@ _export_star(require("./api-response.decorator"), exports);
 _export_star(require("./current-user.decorator"), exports);
 _export_star(require("./public.decorator"), exports);
 _export_star(require("./require-permission.decorator"), exports);
+_export_star(require("./sanitize-html.decorator"), exports);
 function _export_star(from, to) {
     Object.keys(from).forEach(function(k) {
         if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {

package/cjs/decorators/sanitize-html.decorator.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get SanitizeAndTrim () {
+        return SanitizeAndTrim;
+    },
+    get SanitizeHtml () {
+        return SanitizeHtml;
+    }
+});
+const _classtransformer = require("class-transformer");
+const _htmlsanitizerutil = require("../utils/html-sanitizer.util");
+function SanitizeHtml() {
+    return (0, _classtransformer.Transform)(({ value })=>{
+        if (typeof value === 'string') {
+            return (0, _htmlsanitizerutil.escapeHtml)(value);
+        }
+        return value;
+    });
+}
+function SanitizeAndTrim() {
+    return (0, _classtransformer.Transform)(({ value })=>{
+        if (typeof value === 'string') {
+            return (0, _htmlsanitizerutil.escapeHtml)(value.trim());
+        }
+        return value;
+    });
+}