@flusys/nestjs-iam 1.0.0-rc → 2.0.0

package/fesm/services/action.service.js

@@ -25,13 +25,13 @@ function _ts_param(paramIndex, decorator) {
         decorator(target, key, paramIndex);
     };
 }
-import { RequestScopedApiService, HybridCache } from '@flusys/nestjs-shared/classes';
+import { HybridCache, RequestScopedApiService } from '@flusys/nestjs-shared/classes';
 import { UtilsService } from '@flusys/nestjs-shared/modules';
 import { BadRequestException, Inject, Injectable, Scope } from '@nestjs/common';
 import { In } from 'typeorm';
 import { Action } from '../entities/action.entity';
 import { IAMConfigService } from './iam-config.service';
-import { IAMDataSourceProvider } from './iam-datasource.provider';
+import { IAMDataSourceService } from './iam-datasource.service';
 import { PermissionService } from './permission.service';
 export class ActionService extends RequestScopedApiService {
     resolveEntity() {
@@ -93,55 +93,33 @@ export class ActionService extends RequestScopedApiService {
             deletedById: entity.deletedById
         };
     }
-    // Custom Methods
-    /** Get actions available for permission assignment (filtered by company whitelist) */ async getActionsForPermission(user) {
-        await this.ensureRepositoryInitialized();
+    requireUser(user, methodName) {
         if (!user) {
-            throw new BadRequestException('User is required for getActionsForPermission');
+            throw new BadRequestException(`User is required for ${methodName}`);
         }
-        const selectFields = [
-            'id',
-            'code',
-            'name',
-            'description',
-            'actionType',
-            'permissionLogic',
-            'isActive',
-            'parentId',
-            'serial'
-        ];
-        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
-        if (enableCompanyFeature && user.companyId) {
+    }
+    /** Get actions available for permission assignment (filtered by company whitelist) */ async getActionsForPermission(user) {
+        await this.ensureRepositoryInitialized();
+        this.requireUser(user, 'getActionsForPermission');
+        let whereClause = {};
+        if (this.iamConfigService.isCompanyFeatureEnabled() && user.companyId) {
             const companyActionIds = await this.permissionService.getCompanyActionIds(user.companyId);
             if (companyActionIds.length === 0) {
                 return [];
             }
-            const actions = await this.repository.find({
-                where: {
-                    id: In(companyActionIds)
-                },
-                select: selectFields
-            });
-            return actions.map((action)=>this.convertEntityToResponseDto(action, false));
+            whereClause = {
+                id: In(companyActionIds)
+            };
         }
         const actions = await this.repository.find({
-            select: selectFields
+            where: whereClause,
+            select: this.actionSelectFields
         });
         return actions.map((action)=>this.convertEntityToResponseDto(action, false));
     }
-    /**
-   * Get actions in hierarchical tree structure
-   *
-   * @param user - Logged in user info for company filtering
-   * @param search - Optional search term (name or code)
-   * @param isActive - Optional filter by active status
-   * @param withDeleted - Include deleted actions (default: false)
-   * @returns Array of root actions with nested children
-   */ async getActionTree(user, search, isActive, withDeleted = false) {
+    /** Get actions in hierarchical tree structure */ async getActionTree(user, search, isActive, withDeleted = false) {
         await this.ensureRepositoryInitialized();
-        if (!user) {
-            throw new BadRequestException('User is required for getActionTree');
-        }
+        this.requireUser(user, 'getActionTree');
         const query = this.repository.createQueryBuilder('action');
         if (!withDeleted) {
             query.andWhere('action.deletedAt IS NULL');
@@ -189,7 +167,18 @@ export class ActionService extends RequestScopedApiService {
         return rootNodes;
     }
     constructor(cacheManager, utilsService, iamConfigService, dataSourceProvider, permissionService){
-        super('action', null, cacheManager, utilsService, ActionService.name, true), _define_property(this, "cacheManager", void 0), _define_property(this, "utilsService", void 0), _define_property(this, "iamConfigService", void 0), _define_property(this, "dataSourceProvider", void 0), _define_property(this, "permissionService", void 0), this.cacheManager = cacheManager, this.utilsService = utilsService, this.iamConfigService = iamConfigService, this.dataSourceProvider = dataSourceProvider, this.permissionService = permissionService;
+        super('action', null, cacheManager, utilsService, ActionService.name, true), _define_property(this, "cacheManager", void 0), _define_property(this, "utilsService", void 0), _define_property(this, "iamConfigService", void 0), _define_property(this, "dataSourceProvider", void 0), _define_property(this, "permissionService", void 0), // Custom Methods
+        _define_property(this, "actionSelectFields", void 0), this.cacheManager = cacheManager, this.utilsService = utilsService, this.iamConfigService = iamConfigService, this.dataSourceProvider = dataSourceProvider, this.permissionService = permissionService, this.actionSelectFields = [
+            'id',
+            'code',
+            'name',
+            'description',
+            'actionType',
+            'permissionLogic',
+            'isActive',
+            'parentId',
+            'serial'
+        ];
     }
 }
 ActionService = _ts_decorate([
@@ -199,14 +188,14 @@ ActionService = _ts_decorate([
     _ts_param(0, Inject('CACHE_INSTANCE')),
     _ts_param(1, Inject(UtilsService)),
     _ts_param(2, Inject(IAMConfigService)),
-    _ts_param(3, Inject(IAMDataSourceProvider)),
+    _ts_param(3, Inject(IAMDataSourceService)),
     _ts_param(4, Inject(PermissionService)),
     _ts_metadata("design:type", Function),
     _ts_metadata("design:paramtypes", [
         typeof HybridCache === "undefined" ? Object : HybridCache,
         typeof UtilsService === "undefined" ? Object : UtilsService,
         typeof IAMConfigService === "undefined" ? Object : IAMConfigService,
-        typeof IAMDataSourceProvider === "undefined" ? Object : IAMDataSourceProvider,
+        typeof IAMDataSourceService === "undefined" ? Object : IAMDataSourceService,
         typeof PermissionService === "undefined" ? Object : PermissionService
     ])
 ], ActionService);

package/fesm/services/iam-config.service.js

@@ -38,12 +38,9 @@ export class IAMConfigService {
     isMultiTenant() {
         return this.getDatabaseMode() === 'multi-tenant';
     }
-    // Company Feature
-    getEnableCompanyFeature() {
-        return this.options.bootstrapAppConfig?.enableCompanyFeature ?? false;
-    }
+    // Feature Flags
     isCompanyFeatureEnabled() {
-        return this.getEnableCompanyFeature();
+        return this.options.bootstrapAppConfig?.enableCompanyFeature ?? false;
     }
     // Permission Mode
     getPermissionMode() {

package/fesm/services/{iam-datasource.provider.js → iam-datasource.service.js}

@@ -29,9 +29,9 @@ import { MultiTenantDataSourceService } from '@flusys/nestjs-shared/modules';
 import { Inject, Injectable, Logger, Optional, Scope } from '@nestjs/common';
 import { REQUEST } from '@nestjs/core';
 import { Request } from 'express';
-import { IAM_MODULE_OPTIONS } from '../config/iam.constants';
-import { IAMModuleOptions } from '../interfaces/iam-module-options.interface';
-export class IAMDataSourceProvider extends MultiTenantDataSourceService {
+import { PermissionModeHelper } from '../helpers';
+import { IAMConfigService } from './iam-config.service';
+export class IAMDataSourceService extends MultiTenantDataSourceService {
     // Factory Methods
     static buildParentOptions(options) {
         return {
@@ -42,20 +42,17 @@ export class IAMDataSourceProvider extends MultiTenantDataSourceService {
         };
     }
     // Feature Flags
-    getEnableCompanyFeature() {
-        return this.iamOptions.bootstrapAppConfig?.enableCompanyFeature ?? false;
-    }
     getEnableCompanyFeatureForTenant(tenant) {
-        return tenant?.enableCompanyFeature ?? this.getEnableCompanyFeature();
+        return tenant?.enableCompanyFeature ?? this.configService.isCompanyFeatureEnabled();
     }
     getEnableCompanyFeatureForCurrentTenant() {
         return this.getEnableCompanyFeatureForTenant(this.getCurrentTenant() ?? undefined);
     }
     // Entity Management
     async getIAMEntities() {
-        const { Action, Role, RoleWithCompany, UserIamPermission, UserIamPermissionWithCompany, getIAMEntitiesByConfig } = await import('../entities');
+        const { getIAMEntitiesByConfig } = await import('../entities');
         const enableCompanyFeature = this.getEnableCompanyFeatureForCurrentTenant();
-        const permissionMode = this.iamOptions.bootstrapAppConfig?.permissionMode || 'FULL';
+        const permissionMode = PermissionModeHelper.toString(this.configService.getPermissionMode());
         return getIAMEntitiesByConfig(enableCompanyFeature, permissionMode);
     }
     // Overrides
@@ -64,9 +61,9 @@ export class IAMDataSourceProvider extends MultiTenantDataSourceService {
         return super.createDataSourceFromConfig(config, entities);
     }
     async getSingleDataSource() {
-        if (!IAMDataSourceProvider.singleDataSource) {
-            if (IAMDataSourceProvider.singleConnectionLock) {
-                return IAMDataSourceProvider.singleConnectionLock;
+        if (!IAMDataSourceService.singleDataSource) {
+            if (IAMDataSourceService.singleConnectionLock) {
+                return IAMDataSourceService.singleConnectionLock;
             }
             const lockPromise = (async ()=>{
                 const config = this.getDefaultDatabaseConfig();
@@ -74,63 +71,63 @@ export class IAMDataSourceProvider extends MultiTenantDataSourceService {
                     throw new Error('Default database config is not available');
                 }
                 const ds = await this.createDataSourceFromConfig(config);
-                IAMDataSourceProvider.singleDataSource = ds;
-                IAMDataSourceProvider.initialized = true;
+                IAMDataSourceService.singleDataSource = ds;
+                IAMDataSourceService.initialized = true;
                 return ds;
             })();
-            IAMDataSourceProvider.singleConnectionLock = lockPromise;
+            IAMDataSourceService.singleConnectionLock = lockPromise;
             try {
                 return await lockPromise;
             } finally{
-                IAMDataSourceProvider.singleConnectionLock = null;
+                IAMDataSourceService.singleConnectionLock = null;
             }
         }
-        return IAMDataSourceProvider.singleDataSource;
+        return IAMDataSourceService.singleDataSource;
     }
     async getOrCreateTenantConnection(tenant) {
         // Return existing initialized connection from IAM-specific cache
-        const existing = IAMDataSourceProvider.tenantConnections.get(tenant.id);
+        const existing = IAMDataSourceService.tenantConnections.get(tenant.id);
         if (existing?.isInitialized) {
             return existing;
         }
         // If another request is creating this tenant's connection, wait for it
-        const pendingConnection = IAMDataSourceProvider.connectionLocks.get(tenant.id);
+        const pendingConnection = IAMDataSourceService.connectionLocks.get(tenant.id);
         if (pendingConnection) {
             return pendingConnection;
         }
         // Create connection with lock to prevent race conditions
         const config = this.buildTenantDatabaseConfig(tenant);
         const connectionPromise = this.createDataSourceFromConfig(config);
-        IAMDataSourceProvider.connectionLocks.set(tenant.id, connectionPromise);
+        IAMDataSourceService.connectionLocks.set(tenant.id, connectionPromise);
         try {
             const dataSource = await connectionPromise;
-            IAMDataSourceProvider.tenantConnections.set(tenant.id, dataSource);
+            IAMDataSourceService.tenantConnections.set(tenant.id, dataSource);
             return dataSource;
         } finally{
-            IAMDataSourceProvider.connectionLocks.delete(tenant.id);
+            IAMDataSourceService.connectionLocks.delete(tenant.id);
         }
     }
-    constructor(iamOptions, request){
-        super(IAMDataSourceProvider.buildParentOptions(iamOptions), request), _define_property(this, "iamOptions", void 0), _define_property(this, "logger", void 0), this.iamOptions = iamOptions, this.logger = new Logger(IAMDataSourceProvider.name);
+    constructor(configService, request){
+        super(IAMDataSourceService.buildParentOptions(configService.getOptions()), request), _define_property(this, "configService", void 0), _define_property(this, "logger", void 0), this.configService = configService, this.logger = new Logger(IAMDataSourceService.name);
     }
 }
 // Override parent's static properties to have IAM-specific cache
-_define_property(IAMDataSourceProvider, "tenantConnections", new Map());
-_define_property(IAMDataSourceProvider, "singleDataSource", null);
-_define_property(IAMDataSourceProvider, "tenantsRegistry", new Map());
-_define_property(IAMDataSourceProvider, "initialized", false);
-_define_property(IAMDataSourceProvider, "connectionLocks", new Map());
-_define_property(IAMDataSourceProvider, "singleConnectionLock", null);
-IAMDataSourceProvider = _ts_decorate([
+_define_property(IAMDataSourceService, "tenantConnections", new Map());
+_define_property(IAMDataSourceService, "singleDataSource", null);
+_define_property(IAMDataSourceService, "tenantsRegistry", new Map());
+_define_property(IAMDataSourceService, "initialized", false);
+_define_property(IAMDataSourceService, "connectionLocks", new Map());
+_define_property(IAMDataSourceService, "singleConnectionLock", null);
+IAMDataSourceService = _ts_decorate([
     Injectable({
         scope: Scope.REQUEST
     }),
-    _ts_param(0, Inject(IAM_MODULE_OPTIONS)),
+    _ts_param(0, Inject(IAMConfigService)),
     _ts_param(1, Optional()),
     _ts_param(1, Inject(REQUEST)),
     _ts_metadata("design:type", Function),
     _ts_metadata("design:paramtypes", [
-        typeof IAMModuleOptions === "undefined" ? Object : IAMModuleOptions,
+        typeof IAMConfigService === "undefined" ? Object : IAMConfigService,
         typeof Request === "undefined" ? Object : Request
     ])
-], IAMDataSourceProvider);
+], IAMDataSourceService);

package/fesm/services/index.js

@@ -1,6 +1,6 @@
 export * from './action.service';
 export * from './iam-config.service';
-export * from './iam-datasource.provider';
+export * from './iam-datasource.service';
 export * from './permission-cache.service';
 export * from './permission.service';
 export * from './role.service';

package/fesm/services/permission-cache.service.js

@@ -31,18 +31,17 @@ import { Inject, Injectable, Logger } from '@nestjs/common';
 export class PermissionCacheService {
     // Cache Key Generation
     generateCacheKey(options) {
-        const { userId, companyId, branchId, enableCompanyFeature } = options;
-        if (enableCompanyFeature && companyId) {
-            return `${this.CACHE_PREFIX}:company:${companyId}:branch:${branchId || 'null'}:user:${userId}`;
-        }
-        return `${this.CACHE_PREFIX}:user:${userId}`;
+        return this.buildCacheKey(this.CACHE_PREFIX, options);
     }
     generateMyPermissionsCacheKey(options) {
+        return this.buildCacheKey(this.MY_PERMISSIONS_PREFIX, options);
+    }
+    buildCacheKey(prefix, options) {
         const { userId, companyId, branchId, enableCompanyFeature } = options;
         if (enableCompanyFeature && companyId) {
-            return `${this.MY_PERMISSIONS_PREFIX}:company:${companyId}:branch:${branchId || 'null'}:user:${userId}`;
+            return `${prefix}:company:${companyId}:branch:${branchId || 'null'}:user:${userId}`;
         }
-        return `${this.MY_PERMISSIONS_PREFIX}:user:${userId}`;
+        return `${prefix}:user:${userId}`;
     }
     // Cache Operations
     async setPermissions(options, permissions) {
@@ -56,17 +55,6 @@ export class PermissionCacheService {
         // Don't throw - cache failure shouldn't break the operation
         }
     }
-    async getPermissions(options) {
-        try {
-            const key = this.generateCacheKey(options);
-            const result = await this.cacheManager.get(key);
-            return result || null;
-        } catch (error) {
-            const errorMessage = ErrorHandler.getErrorMessage(error);
-            this.logger.error(`Failed to get permissions from cache: ${errorMessage}`);
-            return null;
-        }
-    }
     // My-Permissions Cache Operations
     async setMyPermissions(options, data) {
         try {
@@ -129,16 +117,6 @@ export class PermissionCacheService {
             return null;
         }
     }
-    async invalidateActionCodeCache(tenantId) {
-        try {
-            const key = this.generateActionCodeCacheKey(tenantId);
-            await this.cacheManager.del(key);
-            this.logger.debug(`Invalidated action code cache${tenantId ? ` for tenant ${tenantId}` : ''}`);
-        } catch (error) {
-            const errorMessage = ErrorHandler.getErrorMessage(error);
-            this.logger.warn(`Failed to invalidate action code cache: ${errorMessage}`);
-        }
-    }
     // Cache Invalidation
     async invalidateUser(userId, companyId, branchIds) {
         try {
@@ -178,13 +156,6 @@ export class PermissionCacheService {
         }
         return successCount;
     }
-    /** Invalidate cache for all users in company (requires userIds via invalidateUsers) */ async invalidateCompany(companyId) {
-        // Note: HybridCache doesn't support pattern matching (keys() method)
-        // Company-wide invalidation requires passing individual user IDs
-        // This is a placeholder that logs a warning
-        this.logger.warn(`invalidateCompany called for ${companyId}, but pattern matching is not supported. ` + `Use invalidateUsers() with specific user IDs instead.`);
-        return 0;
-    }
     async invalidateRole(roleId, userIds, companyId, branchIds) {
         if (userIds.length === 0) {
             this.logger.debug(`No users found for role ${roleId}`);
@@ -196,17 +167,6 @@ export class PermissionCacheService {
         }
         return count;
     }
-    // Administrative Operations
-    /** Clear all permission caches (memory and redis) */ async clearAll() {
-        try {
-            await this.cacheManager.reset(); // Clear memory cache
-            await this.cacheManager.resetL2(); // Clear redis cache
-            this.logger.warn('Cleared all cache entries (memory and redis)');
-        } catch (error) {
-            const errorMessage = ErrorHandler.getErrorMessage(error);
-            this.logger.error(`Failed to clear all caches: ${errorMessage}`);
-        }
-    }
     constructor(cacheManager){
         _define_property(this, "cacheManager", void 0);
         _define_property(this, "logger", void 0);

package/fesm/services/permission.service.js

@@ -25,7 +25,7 @@ function _ts_param(paramIndex, decorator) {
         decorator(target, key, paramIndex);
     };
 }
-import { BadRequestException, Inject, Injectable, Logger, Scope } from '@nestjs/common';
+import { BadRequestException, ConflictException, Inject, Injectable, Logger, Scope } from '@nestjs/common';
 import { In, IsNull } from 'typeorm';
 import { PermissionAction } from '../dtos/permission.dto';
 import { Action } from '../entities/action.entity';
@@ -36,7 +36,7 @@ import { IamEntityType, IamPermissionType, UserIamPermission } from '../entities
 import { ActionType } from '../enums/action-type.enum';
 import { IAMPermissionMode } from '../enums/permission-type.enum';
 import { IAMConfigService } from './iam-config.service';
-import { IAMDataSourceProvider } from './iam-datasource.provider';
+import { IAMDataSourceService } from './iam-datasource.service';
 import { PermissionCacheService } from './permission-cache.service';
 export class PermissionService {
     // Repository Getters
@@ -62,8 +62,7 @@ export class PermissionService {
         const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
         const branchId = dto.branchId ?? null;
         const companyId = dto.companyId ?? null;
-        const itemsToAdd = dto.items.filter((item)=>item.action === PermissionAction.ADD);
-        const itemsToRemove = dto.items.filter((item)=>item.action === PermissionAction.REMOVE);
+        const { toAdd: itemsToAdd, toRemove: itemsToRemove } = this.splitItemsByAction(dto.items);
         let added = 0;
         let removed = 0;
         if (itemsToAdd.length > 0) {
@@ -97,8 +96,15 @@ export class PermissionService {
                     branchId: enableCompanyFeature ? branchId : null
                 }));
             if (newPermissions.length > 0) {
-                await permissionRepo.save(newPermissions);
-                added = newPermissions.length;
+                try {
+                    await permissionRepo.save(newPermissions);
+                    added = newPermissions.length;
+                } catch (error) {
+                    if (error?.code === 'ER_DUP_ENTRY' || error?.message?.includes('Duplicate entry')) {
+                        throw new ConflictException('Some permissions already exist for this user. Please refresh and try again.');
+                    }
+                    throw error;
+                }
             }
         }
         if (itemsToRemove.length > 0) {
@@ -118,12 +124,7 @@ export class PermissionService {
             removed = result.affected || 0;
         }
         await this.invalidateUserPermissionCache(dto.userId, branchId, companyId);
-        return {
-            success: true,
-            added,
-            removed,
-            message: `Successfully processed ${dto.items.length} items: ${added} added, ${removed} removed`
-        };
+        return this.buildOperationResult(dto.items.length, added, removed);
     }
     async getUserActions(userId, branchId, companyId) {
         const permissionRepo = await this.getPermissionRepository();
@@ -189,8 +190,7 @@ export class PermissionService {
             });
             roleCompanyId = role?.companyId ?? null;
         }
-        const itemsToAdd = dto.items.filter((item)=>item.action === PermissionAction.ADD);
-        const itemsToRemove = dto.items.filter((item)=>item.action === PermissionAction.REMOVE);
+        const { toAdd: itemsToAdd, toRemove: itemsToRemove } = this.splitItemsByAction(dto.items);
         let added = 0;
         let removed = 0;
         if (itemsToAdd.length > 0) {
@@ -219,8 +219,15 @@ export class PermissionService {
                     branchId: null
                 }));
             if (newPermissions.length > 0) {
-                await permissionRepo.save(newPermissions);
-                added = newPermissions.length;
+                try {
+                    await permissionRepo.save(newPermissions);
+                    added = newPermissions.length;
+                } catch (error) {
+                    if (error?.code === 'ER_DUP_ENTRY' || error?.message?.includes('Duplicate entry')) {
+                        throw new ConflictException('Some role-action permissions already exist. Please refresh and try again.');
+                    }
+                    throw error;
+                }
             }
         }
         if (itemsToRemove.length > 0) {
@@ -235,12 +242,7 @@ export class PermissionService {
             removed = result.affected || 0;
         }
         const affectedUsers = await this.invalidateRoleMembersCache(dto.roleId);
-        return {
-            success: true,
-            added,
-            removed,
-            message: `Successfully processed ${dto.items.length} items: ${added} added, ${removed} removed. Invalidated cache for ${affectedUsers} users.`
-        };
+        return this.buildOperationResult(dto.items.length, added, removed, `. Invalidated cache for ${affectedUsers} users.`);
     }
     async getRoleActions(roleId) {
         const permissionRepo = await this.getPermissionRepository();
@@ -282,8 +284,7 @@ export class PermissionService {
     /** Assign or remove actions to/from a company (whitelist) */ async assignCompanyActions(dto) {
         const permissionRepo = await this.getPermissionRepository();
         const dataSource = permissionRepo.manager.connection;
-        const itemsToAdd = dto.items.filter((item)=>item.action === PermissionAction.ADD);
-        const itemsToRemove = dto.items.filter((item)=>item.action === PermissionAction.REMOVE);
+        const { toAdd: itemsToAdd, toRemove: itemsToRemove } = this.splitItemsByAction(dto.items);
         let added = 0;
         let removed = 0;
         let removedRoleActions = 0;
@@ -303,12 +304,7 @@ export class PermissionService {
         });
         const affectedCacheEntries = await this.invalidateCompanyMembersCache(dto.companyId);
         const cascadeInfo = removedRoleActions > 0 || removedUserActions > 0 ? ` Cascaded removal: ${removedRoleActions} role permissions, ${removedUserActions} user permissions.` : '';
-        return {
-            success: true,
-            added,
-            removed,
-            message: `Successfully processed ${dto.items.length} items: ${added} added, ${removed} removed.${cascadeInfo} Invalidated ${affectedCacheEntries} cache entries.`
-        };
+        return this.buildOperationResult(dto.items.length, added, removed, `.${cascadeInfo} Invalidated ${affectedCacheEntries} cache entries.`);
     }
     async addCompanyActions(permissionRepo, companyId, actionIds) {
         const existingPermissions = await permissionRepo.find({
@@ -449,8 +445,7 @@ export class PermissionService {
         const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
         const branchId = dto.branchId ?? null;
         const companyId = dto.companyId ?? null;
-        const itemsToAdd = dto.items.filter((item)=>item.action === PermissionAction.ADD);
-        const itemsToRemove = dto.items.filter((item)=>item.action === PermissionAction.REMOVE);
+        const { toAdd: itemsToAdd, toRemove: itemsToRemove } = this.splitItemsByAction(dto.items);
         let added = 0;
         let removed = 0;
         if (itemsToAdd.length > 0) {
@@ -484,8 +479,15 @@ export class PermissionService {
                     branchId: enableCompanyFeature ? branchId : null
                 }));
             if (newPermissions.length > 0) {
-                await permissionRepo.save(newPermissions);
-                added = newPermissions.length;
+                try {
+                    await permissionRepo.save(newPermissions);
+                    added = newPermissions.length;
+                } catch (error) {
+                    if (error?.code === 'ER_DUP_ENTRY' || error?.message?.includes('Duplicate entry')) {
+                        throw new ConflictException('Some user-role permissions already exist. Please refresh and try again.');
+                    }
+                    throw error;
+                }
             }
         }
         if (itemsToRemove.length > 0) {
@@ -505,12 +507,7 @@ export class PermissionService {
             removed = result.affected || 0;
         }
         await this.invalidateUserPermissionCache(dto.userId, branchId, companyId);
-        return {
-            success: true,
-            added,
-            removed,
-            message: `Successfully processed ${dto.items.length} items: ${added} added, ${removed} removed`
-        };
+        return this.buildOperationResult(dto.items.length, added, removed);
     }
     /** Get user's roles (branch-scoped, filtered by companyId and branchId if provided) */ async getUserRoles(userId, branchId, companyId) {
         const permissionRepo = await this.getPermissionRepository();
@@ -702,6 +699,20 @@ export class PermissionService {
         return cacheData;
     }
     // Helper Methods
+    /** Split permission items into add and remove arrays */ splitItemsByAction(items) {
+        return {
+            toAdd: items.filter((item)=>item.action === PermissionAction.ADD),
+            toRemove: items.filter((item)=>item.action === PermissionAction.REMOVE)
+        };
+    }
+    /** Build standard operation result DTO */ buildOperationResult(totalItems, added, removed, additionalMessage = '') {
+        return {
+            success: true,
+            added,
+            removed,
+            message: `Successfully processed ${totalItems} items: ${added} added, ${removed} removed${additionalMessage}`
+        };
+    }
     /** Get role IDs assigned to a user (merges company-wide + branch-specific roles) */ async getUserRoleIds(userId, branchId, companyId) {
         const permissionRepo = await this.getPermissionRepository();
         const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
@@ -889,11 +900,11 @@ PermissionService = _ts_decorate([
     }),
     _ts_param(0, Inject(PermissionCacheService)),
     _ts_param(1, Inject(IAMConfigService)),
-    _ts_param(2, Inject(IAMDataSourceProvider)),
+    _ts_param(2, Inject(IAMDataSourceService)),
     _ts_metadata("design:type", Function),
     _ts_metadata("design:paramtypes", [
         typeof PermissionCacheService === "undefined" ? Object : PermissionCacheService,
         typeof IAMConfigService === "undefined" ? Object : IAMConfigService,
-        typeof IAMDataSourceProvider === "undefined" ? Object : IAMDataSourceProvider
+        typeof IAMDataSourceService === "undefined" ? Object : IAMDataSourceService
     ])
 ], PermissionService);

package/fesm/services/role.service.js

@@ -32,7 +32,7 @@ import { Inject, Injectable, Scope } from '@nestjs/common';
 import { RoleWithCompany } from '../entities/role-with-company.entity';
 import { Role } from '../entities/role.entity';
 import { IAMConfigService } from './iam-config.service';
-import { IAMDataSourceProvider } from './iam-datasource.provider';
+import { IAMDataSourceService } from './iam-datasource.service';
 export class RoleService extends RequestScopedApiService {
     resolveEntity() {
         return this.iamConfigService.isCompanyFeatureEnabled() ? RoleWithCompany : Role;
@@ -122,12 +122,12 @@ RoleService = _ts_decorate([
     _ts_param(0, Inject('CACHE_INSTANCE')),
     _ts_param(1, Inject(UtilsService)),
     _ts_param(2, Inject(IAMConfigService)),
-    _ts_param(3, Inject(IAMDataSourceProvider)),
+    _ts_param(3, Inject(IAMDataSourceService)),
     _ts_metadata("design:type", Function),
     _ts_metadata("design:paramtypes", [
         typeof HybridCache === "undefined" ? Object : HybridCache,
         typeof UtilsService === "undefined" ? Object : UtilsService,
         typeof IAMConfigService === "undefined" ? Object : IAMConfigService,
-        typeof IAMDataSourceProvider === "undefined" ? Object : IAMDataSourceProvider
+        typeof IAMDataSourceService === "undefined" ? Object : IAMDataSourceService
     ])
 ], RoleService);

package/helpers/company-access.helper.d.ts

@@ -0,0 +1,3 @@
+import { ILoggedUserInfo } from '@flusys/nestjs-shared';
+import { IAMConfigService } from '../services/iam-config.service';
+export declare function validateCompanyAccess(config: IAMConfigService, companyId: string | undefined, user: ILoggedUserInfo, errorMessage?: string): void;

package/helpers/index.d.ts

@@ -1,2 +1,2 @@
-export * from './permission-evaluator.helper';
+export * from './company-access.helper';
 export * from './permission-mode.helper';

package/interfaces/iam-module-options.interface.d.ts

@@ -1,4 +1,5 @@
 import { IBootstrapAppConfig, IDataSourceServiceOptions, IDynamicModuleConfig, IModuleOptionsFactory } from '@flusys/nestjs-core';
+import { ModuleMetadata, Type } from '@nestjs/common';
 export interface IIAMModuleConfig extends IDataSourceServiceOptions {
 }
 export interface IAMModuleOptions extends IDynamicModuleConfig {
@@ -9,4 +10,11 @@ export interface IAMOptionsFactory extends IModuleOptionsFactory<IIAMModuleConfi
     createIAMOptions(): Promise<IIAMModuleConfig> | IIAMModuleConfig;
     createOptions(): Promise<IIAMModuleConfig> | IIAMModuleConfig;
 }
-export * from './iam-module-async-options.interface';
+export 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>;
+}

package/interfaces/index.d.ts

@@ -1,4 +1,3 @@
 export * from './action.interface';
 export * from './role.interface';
 export * from './iam-module-options.interface';
-export * from './iam-module-async-options.interface';

package/modules/iam.module.d.ts

@@ -2,10 +2,9 @@ import { DynamicModule } from '@nestjs/common';
 import { IAMModuleAsyncOptions, IAMModuleOptions } from '../interfaces/iam-module-options.interface';
 export declare class IAMModule {
     private static getControllers;
-    private static getEntities;
     private static getServices;
     private static getPermissionGuardConfigProvider;
-    private static getRepositoryProviders;
+    private static getExports;
     static forRoot(options?: IAMModuleOptions): DynamicModule;
     static forRootAsync(asyncOptions: IAMModuleAsyncOptions): DynamicModule;
     private static createAsyncProviders;