@flusys/nestjs-iam 2.0.0 → 3.0.0

package/README.md

@@ -1,6 +1,7 @@
 # IAM Package Guide
 
 > **Package:** `@flusys/nestjs-iam`
+> **Version:** 3.0.0
 > **Purpose:** Identity and Access Management with RBAC, ABAC, and permission logic
 
 ## Table of Contents
@@ -10,6 +11,7 @@
 - [Module Configuration](#module-configuration)
 - [Constants](#constants)
 - [Core Concepts](#core-concepts)
+- [Interfaces](#interfaces)
 - [Entities](#entities)
 - [Permission Modes](#permission-modes)
 - [Permission Logic](#permission-logic)
@@ -19,6 +21,7 @@
 - [Multi-Tenant Support](#multi-tenant-support)
 - [Permission Guard Integration](#permission-guard-integration)
 - [Best Practices](#best-practices)
+- [DTOs Reference](#dtos-reference)
 - [API Reference](#api-reference)
 - [Package Architecture](#package-architecture)
 
@@ -168,6 +171,19 @@ enum IamPermissionType {
 }
 ```
 
+### Entity Types
+
+Used for source/target type fields in permissions:
+
+```typescript
+enum IamEntityType {
+  USER = 'user',
+  ROLE = 'role',
+  ACTION = 'action',
+  COMPANY = 'company',
+}
+```
+
 ### Permission Resolution Order
 
 1. **Company-Action Whitelist** - Filter by company (if enabled)
@@ -198,6 +214,88 @@ Company Action Removed
 
 ---
 
+## Interfaces
+
+### IAction
+
+```typescript
+interface IAction {
+  id: string;
+  readOnly: boolean;
+  name: string;
+  description: string | null;
+  code: string | null;
+  actionType: ActionType;
+  permissionLogic: LogicNode | null;
+  serial: number | null;
+  isActive: boolean;
+  parentId: string | null;
+  metadata: Record<string, any> | null;
+  createdAt: Date;
+  updatedAt: Date;
+  deletedAt: Date | null;
+  createdById: string | null;
+  updatedById: string | null;
+  deletedById: string | null;
+}
+```
+
+### IActionTree
+
+```typescript
+interface IActionTree extends IAction {
+  children?: IActionTree[];
+}
+```
+
+### IRole
+
+```typescript
+interface IRole {
+  id: string;
+  readOnly: boolean;
+  name: string;
+  description: string | null;
+  isActive: boolean;
+  serial: number | null;
+  companyId: string | null;
+  metadata: Record<string, any> | null;
+  createdAt: Date;
+  updatedAt: Date;
+  deletedAt: Date | null;
+  createdById: string | null;
+  updatedById: string | null;
+  deletedById: string | null;
+}
+```
+
+### Module Options
+
+```typescript
+// Runtime configuration (currently empty - reserved for future use)
+interface IIAMModuleConfig extends IDataSourceServiceOptions {
+  // Future: cache TTL, etc.
+}
+
+// Full module options
+interface IAMModuleOptions extends IDynamicModuleConfig {
+  bootstrapAppConfig?: IBootstrapAppConfig;
+  config?: IIAMModuleConfig;
+}
+
+// Async options
+interface IAMModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'>, IDynamicModuleConfig {
+  bootstrapAppConfig?: IBootstrapAppConfig;
+  config?: IIAMModuleConfig;
+  useFactory?: (...args: any[]) => Promise<IIAMModuleConfig> | IIAMModuleConfig;
+  inject?: any[];
+  useClass?: Type<IAMOptionsFactory>;
+  useExisting?: Type<IAMOptionsFactory>;
+}
+```
+
+---
+
 ## Entities
 
 ### Entity Groups
@@ -297,6 +395,17 @@ Core permission fields in `permission-base.entity.ts`:
 | `reason` | text | Reason for permission |
 | `metadata` | json | Additional data |
 
+**Methods:**
+
+```typescript
+// Check if permission is currently valid (date constraints)
+isValid(now: Date = new Date()): boolean {
+  if (this.validFrom && now < this.validFrom) return false;
+  if (this.validUntil && now > this.validUntil) return false;
+  return true;
+}
+```
+
 ### UserIamPermissionWithCompany
 
 Extends PermissionBase with:
@@ -403,10 +512,44 @@ const logic: LogicNode = {
 | `ActionService` | REQUEST | Action CRUD, tree queries |
 | `RoleService` | REQUEST | Role CRUD (RBAC/FULL mode only) |
 | `PermissionService` | REQUEST | Permission assignments, my-permissions |
-| `PermissionCacheService` | REQUEST | Cache management |
+| `PermissionCacheService` | SINGLETON | Cache management |
 | `IAMConfigService` | SINGLETON | IAM configuration access |
 | `IAMDataSourceService` | REQUEST | DataSource provider for multi-tenant |
 
+### IAMConfigService
+
+```typescript
+import { IAMConfigService } from '@flusys/nestjs-iam';
+
+// Database mode
+const dbMode = config.getDatabaseMode(); // 'single' | 'multi-tenant'
+const isMultiTenant = config.isMultiTenant();
+
+// Feature flags
+const hasCompany = config.isCompanyFeatureEnabled();
+
+// Permission mode
+const mode = config.getPermissionMode(); // IAMPermissionMode enum
+const isRbac = config.isRbacEnabled(); // true for RBAC or FULL
+const isDirect = config.isDirectPermissionEnabled(); // true for DIRECT or FULL
+
+// Get raw options
+const options = config.getOptions();
+```
+
+### IAMDataSourceService
+
+```typescript
+import { IAMDataSourceService } from '@flusys/nestjs-iam';
+
+// Get repository for entity
+const actionRepo = await dataSourceProvider.getRepository(Action);
+
+// Tenant-specific features
+const enableCompany = dataSourceProvider.getEnableCompanyFeatureForCurrentTenant();
+const entities = await dataSourceProvider.getIAMEntities();
+```
+
 ### ActionService
 
 ```typescript
@@ -475,31 +618,74 @@ const permissions = await permissionService.getMyPermissions(
 
 ### PermissionCacheService
 
+Centralized cache management for IAM permissions. Cache key format matches PermissionGuard in nestjs-shared.
+
+**Cache TTLs:**
+- Permissions: 1 hour (3600000ms)
+- Action codes: 2 hours (7200000ms)
+
+**Interfaces:**
+
+```typescript
+interface PermissionCacheKeyOptions {
+  userId: string;
+  companyId?: string | null;
+  branchId?: string | null;
+  enableCompanyFeature: boolean;
+}
+
+interface CachedMyPermissions {
+  frontendActions: Array<{
+    id: string;
+    code: string;
+    name: string;
+    description: string | null;
+    parentId: string | null;
+  }>;
+  backendCodes: string[];
+}
+```
+
+**Usage:**
+
 ```typescript
 import { PermissionCacheService } from '@flusys/nestjs-iam';
 
-// Set permissions
+// Set permissions (backend codes for PermissionGuard)
 await cacheService.setPermissions(
   { userId, companyId, branchId, enableCompanyFeature: true },
   ['users.read', 'users.write']
 );
 
-// Invalidate user cache
+// Set my-permissions (full response with frontend actions)
+await cacheService.setMyPermissions(cacheOptions, {
+  frontendActions: [...],
+  backendCodes: ['users.read', 'users.write'],
+});
+
+// Get cached my-permissions
+const cached = await cacheService.getMyPermissions(cacheOptions);
+
+// Invalidate single user cache
 await cacheService.invalidateUser('user-id', 'company-id', ['branch-id']);
 
-// Invalidate role members
-await cacheService.invalidateRole('role-id', userIds, 'company-id');
+// Invalidate multiple users cache
+await cacheService.invalidateUsers(userIds, 'company-id', branchIds);
+
+// Invalidate role members (all users assigned to role)
+await cacheService.invalidateRole('role-id', userIds, 'company-id', branchIds);
 
 // Tenant-aware action code cache
 await cacheService.setActionCodeMap(codeToIdMap, tenantId);
 await cacheService.getActionIdsByCodes(['user.view'], tenantId);
-await cacheService.invalidateActionCodeCache(tenantId);
 ```
 
 **Cache Key Formats:**
 ```
 permissions:user:{userId}                                        // Without company
 permissions:company:{companyId}:branch:{branchId}:user:{userId}  // With company
+my-permissions:user:{userId}                                     // My-permissions (no company)
+my-permissions:company:{companyId}:branch:{branchId}:user:{userId}  // My-permissions (with company)
 action-codes:map                                                 // Single tenant
 action-codes:tenant:{tenantId}:map                               // Multi-tenant
 ```
@@ -555,39 +741,67 @@ validateCompanyAccess(
 
 ### Actions API
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/iam/actions/insert` | POST | Create action |
-| `/iam/actions/get-all` | POST | List actions (paginated) |
-| `/iam/actions/get/:id` | GET | Get action by ID |
-| `/iam/actions/tree` | POST | Get hierarchical tree (ALL actions) |
-| `/iam/actions/tree-for-permission` | GET | Get company-filtered actions |
-| `/iam/actions/update` | POST | Update action |
-| `/iam/actions/delete` | POST | Delete action |
+| Endpoint | Method | Permission | Description |
+|----------|--------|------------|-------------|
+| `/iam/actions/insert` | POST | `action.create` | Create action |
+| `/iam/actions/insert-many` | POST | `action.create` | Create multiple actions |
+| `/iam/actions/get-all` | POST | `action.read` | List actions (paginated) |
+| `/iam/actions/get` | POST | `action.read` | Get action by ID |
+| `/iam/actions/tree` | POST | JWT Auth | Get hierarchical tree (ALL actions) |
+| `/iam/actions/tree-for-permission` | POST | JWT Auth | Get company-filtered actions |
+| `/iam/actions/update` | POST | `action.update` | Update action |
+| `/iam/actions/update-many` | POST | `action.update` | Update multiple actions |
+| `/iam/actions/delete` | POST | `action.delete` | Delete action |
 
 ### Roles API (RBAC/FULL mode only)
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/iam/roles/insert` | POST | Create role |
-| `/iam/roles/get-all` | POST | List roles (paginated) |
-| `/iam/roles/get/:id` | GET | Get role by ID |
-| `/iam/roles/update` | POST | Update role |
-| `/iam/roles/delete` | POST | Delete role |
+| Endpoint | Method | Permission | Description |
+|----------|--------|------------|-------------|
+| `/iam/roles/insert` | POST | `role.create` | Create role |
+| `/iam/roles/insert-many` | POST | `role.create` | Create multiple roles |
+| `/iam/roles/get-all` | POST | `role.read` | List roles (paginated, auto-filtered by company) |
+| `/iam/roles/get` | POST | `role.read` | Get role by ID |
+| `/iam/roles/update` | POST | `role.update` | Update role |
+| `/iam/roles/update-many` | POST | `role.update` | Update multiple roles |
+| `/iam/roles/delete` | POST | `role.delete` | Delete role |
 
 ### Permissions API
 
-| Endpoint | Method | Modes | Description |
-|----------|--------|-------|-------------|
-| `/iam/permissions/role-actions/assign` | POST | RBAC, FULL | Assign actions to role |
-| `/iam/permissions/role-actions/get` | POST | RBAC, FULL | Get role actions |
-| `/iam/permissions/user-roles/assign` | POST | RBAC, FULL | Assign roles to user |
-| `/iam/permissions/user-roles/get` | POST | RBAC, FULL | Get user roles |
-| `/iam/permissions/user-actions/assign` | POST | DIRECT, FULL | Assign actions to user |
-| `/iam/permissions/user-actions/get` | POST | DIRECT, FULL | Get user actions |
-| `/iam/permissions/company-actions/assign` | POST | All (company enabled) | Company action whitelist |
-| `/iam/permissions/company-actions/get` | POST | All (company enabled) | Get company actions |
-| `/iam/permissions/my-permissions` | POST | All | Get current user's permissions |
+| Endpoint | Method | Permission | Modes | Description |
+|----------|--------|------------|-------|-------------|
+| `/iam/permissions/role-actions/assign` | POST | `role-action.assign` | RBAC, FULL | Assign actions to role |
+| `/iam/permissions/get-role-actions` | POST | `role-action.read` | RBAC, FULL | Get role actions |
+| `/iam/permissions/user-roles/assign` | POST | `user-role.assign` | RBAC, FULL | Assign roles to user |
+| `/iam/permissions/get-user-roles` | POST | `user-role.read` | RBAC, FULL | Get user roles |
+| `/iam/permissions/user-actions/assign` | POST | `user-action.assign` | DIRECT, FULL | Assign actions to user |
+| `/iam/permissions/get-user-actions` | POST | `user-action.read` | DIRECT, FULL | Get user actions |
+| `/iam/permissions/company-actions/assign` | POST | `company-action.assign` | Company enabled | Company action whitelist |
+| `/iam/permissions/get-company-actions` | POST | `company-action.read` | Company enabled | Get company actions |
+| `/iam/permissions/my-permissions` | POST | JWT Auth | All | Get current user's permissions |
+
+### Permission Constants
+
+These permission codes are defined in `@flusys/nestjs-shared`:
+
+```typescript
+// Actions
+ACTION_PERMISSIONS = { CREATE: 'action.create', READ: 'action.read', UPDATE: 'action.update', DELETE: 'action.delete' }
+
+// Roles
+ROLE_PERMISSIONS = { CREATE: 'role.create', READ: 'role.read', UPDATE: 'role.update', DELETE: 'role.delete' }
+
+// Role-Action assignments
+ROLE_ACTION_PERMISSIONS = { ASSIGN: 'role-action.assign', READ: 'role-action.read' }
+
+// User-Role assignments
+USER_ROLE_PERMISSIONS = { ASSIGN: 'user-role.assign', READ: 'user-role.read' }
+
+// User-Action assignments (direct)
+USER_ACTION_PERMISSIONS = { ASSIGN: 'user-action.assign', READ: 'user-action.read' }
+
+// Company-Action assignments
+COMPANY_ACTION_PERMISSIONS = { ASSIGN: 'company-action.assign', READ: 'company-action.read' }
+```
 
 **Controller Registration by Mode:**
 
@@ -596,6 +810,7 @@ validateCompanyAccess(
 | DIRECT | ActionController, MyPermissionController, UserActionPermissionController |
 | RBAC | ActionController, MyPermissionController, RoleController, RolePermissionController |
 | FULL | All controllers |
+| Company Enabled | + CompanyActionPermissionController |
 
 ---
 
@@ -654,17 +869,16 @@ When `getMyPermissions` is called:
 ## Permission Guard Integration
 
 ```typescript
-import { PermissionGuard } from '@flusys/nestjs-shared/guards';
 import { RequirePermission, RequireAnyPermission } from '@flusys/nestjs-shared/decorators';
 
 @Controller('users')
 export class UserController {
   @RequirePermission('user.view')
-  @Get()
+  @Post('get-all')
   getUsers() {}
 
   @RequireAnyPermission('user.create', 'admin')
-  @Post()
+  @Post('insert')
   createUser() {}
 }
 ```
@@ -710,6 +924,99 @@ Direct actions should be exceptions and branch-specific overrides, not the prima
 
 ---
 
+## DTOs Reference
+
+### Permission Operation DTOs
+
+```typescript
+// Permission action enum for add/remove operations
+enum PermissionAction {
+  ADD = 'add',
+  REMOVE = 'remove',
+}
+
+// Common item structure for permission assignments
+interface PermissionItemDto {
+  id: string;              // ID of target (action or role)
+  action: PermissionAction; // ADD or REMOVE
+}
+```
+
+### Assignment DTOs
+
+```typescript
+// Assign actions directly to user
+interface AssignUserActionsDto {
+  userId: string;
+  companyId?: string;  // Company scope (when enabled)
+  branchId?: string;   // Branch scope (null = company-wide)
+  items: PermissionItemDto[];
+}
+
+// Assign roles to user
+interface AssignUserRolesDto {
+  userId: string;
+  companyId?: string;
+  branchId?: string;
+  items: PermissionItemDto[];
+}
+
+// Assign actions to role
+interface AssignRoleActionsDto {
+  roleId: string;
+  items: PermissionItemDto[];
+}
+
+// Assign actions to company (whitelist)
+interface AssignCompanyActionsDto {
+  companyId: string;
+  items: PermissionItemDto[];
+}
+```
+
+### Query DTOs
+
+```typescript
+// Query user's permissions (my-permissions)
+interface MyPermissionsQueryDto {
+  parentCodes?: string[]; // Filter by parent action codes
+}
+
+// Query action tree
+interface ActionTreeQueryDto {
+  search?: string;      // Filter by name or code
+  isActive?: boolean;   // Filter by active status
+  withDeleted?: boolean; // Include deleted actions
+}
+```
+
+### Response DTOs
+
+```typescript
+// My-permissions response
+interface MyPermissionsResponseDto {
+  frontendActions: FrontendActionDto[];
+  cachedEndpoints: number; // Count of backend codes cached
+}
+
+interface FrontendActionDto {
+  id: string;
+  code: string;
+  name: string;
+  description: string | null;
+}
+
+// Permission operation result
+interface PermissionOperationResultDto {
+  success: boolean;
+  added: number;
+  removed: number;
+  message: string;
+}
+```
+
+---
+
 ## API Reference
 
 ### Exports
@@ -753,14 +1060,52 @@ export { LogicNode } from './types/logic-node.type';
 
 // DTOs
 export * from './dtos';
+// Key DTOs:
+// - CreateActionDto, UpdateActionDto, ActionResponseDto, ActionTreeDto, ActionTreeQueryDto
+// - CreateRoleDto, UpdateRoleDto, RoleResponseDto
+// - PermissionAction (enum: ADD, REMOVE), PermissionItemDto
+// - AssignUserActionsDto, AssignRoleActionsDto, AssignUserRolesDto, AssignCompanyActionsDto
+// - GetUserActionsDto, GetRoleActionsDto, GetUserRolesDto, GetCompanyActionsDto
+// - UserActionResponseDto, RoleActionResponseDto, UserRoleResponseDto, CompanyActionResponseDto
+// - MyPermissionsQueryDto, MyPermissionsResponseDto, FrontendActionDto
+// - PermissionOperationResultDto
 
 // Interfaces
 export * from './interfaces';
+// Key Interfaces:
+// - IAction, IActionTree (for action responses)
+// - IRole (for role responses)
+// - IIAMModuleConfig, IAMModuleOptions, IAMOptionsFactory, IAMModuleAsyncOptions
 
 // Swagger Config
 export { iamSwaggerConfig } from './docs';
 ```
 
+### Swagger Configuration
+
+```typescript
+import { iamSwaggerConfig } from '@flusys/nestjs-iam';
+
+// Generate swagger config based on features
+const swaggerOptions = iamSwaggerConfig(
+  enableCompanyFeature, // boolean
+  permissionMode,       // IAMPermissionMode
+);
+
+// Returns IModuleSwaggerOptions with:
+// - title, description, version, path, bearerAuth
+// - excludeSchemaProperties (hides companyId/branchId when company disabled)
+// - excludeTags (hides unused controllers based on mode)
+// - excludeQueryParameters (hides unused query params)
+```
+
+The swagger config automatically:
+- Excludes Auth-related tags (Authentication, Users, Companies, etc.)
+- Hides Company Action endpoints when company feature is disabled
+- Hides RBAC endpoints (Roles, User-Roles) in DIRECT mode
+- Hides Direct endpoints (User-Actions) in RBAC mode
+- Shows appropriate documentation based on current configuration
+
 ### Module Static Methods
 
 ```typescript
@@ -828,4 +1173,4 @@ nestjs-iam/src/
 
 ---
 
-**Last Updated:** 2026-02-21
+**Last Updated:** 2026-02-25

package/cjs/entities/action-base.entity.js

@@ -74,10 +74,10 @@ _ts_decorate([
 ], ActionBase.prototype, "code", void 0);
 _ts_decorate([
     (0, _typeorm.Column)({
-        type: 'enum',
-        enum: _enums.ActionType,
+        type: 'varchar',
+        length: 50,
         nullable: false,
-        default: _enums.ActionType.BACKEND,
+        default: 'BACKEND',
         name: 'action_type'
     }),
     _ts_metadata("design:type", typeof _enums.ActionType === "undefined" ? Object : _enums.ActionType)

package/cjs/entities/permission-base.entity.js

@@ -69,16 +69,16 @@ let PermissionBase = class PermissionBase extends _nestjsshared.Identity {
 };
 _ts_decorate([
     (0, _typeorm.Column)({
-        type: 'enum',
-        enum: IamPermissionType,
+        type: 'varchar',
+        length: 50,
         name: 'permission_type'
     }),
     _ts_metadata("design:type", String)
 ], PermissionBase.prototype, "permissionType", void 0);
 _ts_decorate([
     (0, _typeorm.Column)({
-        type: 'enum',
-        enum: IamEntityType,
+        type: 'varchar',
+        length: 50,
         name: 'source_type'
     }),
     _ts_metadata("design:type", String)
@@ -92,8 +92,8 @@ _ts_decorate([
 ], PermissionBase.prototype, "sourceId", void 0);
 _ts_decorate([
     (0, _typeorm.Column)({
-        type: 'enum',
-        enum: IamEntityType,
+        type: 'varchar',
+        length: 50,
         name: 'target_type'
     }),
     _ts_metadata("design:type", String)

package/entities/permission-base.entity.d.ts

@@ -12,10 +12,10 @@ export declare enum IamEntityType {
     COMPANY = "company"
 }
 export declare abstract class PermissionBase extends Identity {
-    permissionType: IamPermissionType;
-    sourceType: IamEntityType;
+    permissionType: string;
+    sourceType: string;
     sourceId: string;
-    targetType: IamEntityType;
+    targetType: string;
     targetId: string;
     userId: string | null;
     validFrom: Date | null;

package/fesm/entities/action-base.entity.js

@@ -67,10 +67,10 @@ _ts_decorate([
 ], ActionBase.prototype, "code", void 0);
 _ts_decorate([
     Column({
-        type: 'enum',
-        enum: ActionType,
+        type: 'varchar',
+        length: 50,
         nullable: false,
-        default: ActionType.BACKEND,
+        default: 'BACKEND',
         name: 'action_type'
     }),
     _ts_metadata("design:type", typeof ActionType === "undefined" ? Object : ActionType)

package/fesm/entities/permission-base.entity.js

@@ -51,16 +51,16 @@ export var IamEntityType = /*#__PURE__*/ function(IamEntityType) {
 }
 _ts_decorate([
     Column({
-        type: 'enum',
-        enum: IamPermissionType,
+        type: 'varchar',
+        length: 50,
         name: 'permission_type'
     }),
     _ts_metadata("design:type", String)
 ], PermissionBase.prototype, "permissionType", void 0);
 _ts_decorate([
     Column({
-        type: 'enum',
-        enum: IamEntityType,
+        type: 'varchar',
+        length: 50,
         name: 'source_type'
     }),
     _ts_metadata("design:type", String)
@@ -74,8 +74,8 @@ _ts_decorate([
 ], PermissionBase.prototype, "sourceId", void 0);
 _ts_decorate([
     Column({
-        type: 'enum',
-        enum: IamEntityType,
+        type: 'varchar',
+        length: 50,
         name: 'target_type'
     }),
     _ts_metadata("design:type", String)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flusys/nestjs-iam",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Identity and Access Management (IAM) module for NestJS applications",
   "main": "cjs/index.js",
   "module": "fesm/index.js",
@@ -89,7 +89,7 @@
     "typeorm": "^0.3.0"
   },
   "dependencies": {
-    "@flusys/nestjs-core": "2.0.0",
-    "@flusys/nestjs-shared": "2.0.0"
+    "@flusys/nestjs-core": "3.0.0",
+    "@flusys/nestjs-shared": "3.0.0"
   }
 }