@flusys/nestjs-iam 6.2.2 → 6.4.0

package/cjs/config/message-keys.js

@@ -51,7 +51,9 @@ const COMPANY_ACTION_PERMISSION_MESSAGES = {
     GET_SUCCESS: 'company.action.permission.get.success'
 };
 const MY_PERMISSION_MESSAGES = {
-    GET_SUCCESS: 'my.permission.get.success'
+    GET_SUCCESS: 'my.permission.get.success',
+    MY_ROLES_SUCCESS: 'my.permission.roles.success',
+    MY_ACTIONS_SUCCESS: 'my.permission.actions.success'
 };
 const IAM_MODE_MESSAGES = {
     DIRECT_MODE_UNAVAILABLE: 'iam.direct.mode.unavailable',

package/cjs/controllers/my-permission.controller.js

@@ -51,6 +51,24 @@ let MyPermissionController = class MyPermissionController {
             data
         };
     }
+    async getMyRoles(user) {
+        const data = await this.permissionService.getUserEffectiveRoles(user.id, user.companyId ?? null, user.branchId ?? null);
+        return {
+            success: true,
+            message: 'Roles loaded successfully',
+            messageKey: _config.MY_PERMISSION_MESSAGES.MY_ROLES_SUCCESS,
+            data
+        };
+    }
+    async getMyActions(user) {
+        const data = await this.permissionService.getUserEffectiveActions(user.id, user.companyId ?? null, user.branchId ?? null);
+        return {
+            success: true,
+            message: 'Actions loaded successfully',
+            messageKey: _config.MY_PERMISSION_MESSAGES.MY_ACTIONS_SUCCESS,
+            data
+        };
+    }
     // NOTE: @Inject() required for bundled code - type metadata may be lost during esbuild
     constructor(permissionService){
         _define_property(this, "permissionService", void 0);
@@ -80,6 +98,42 @@ _ts_decorate([
     ]),
     _ts_metadata("design:returntype", Promise)
 ], MyPermissionController.prototype, "getMyPermissions", null);
+_ts_decorate([
+    (0, _common.Post)('my-roles'),
+    (0, _swagger.ApiOperation)({
+        summary: 'Get current user roles',
+        description: 'Returns effective roles for the authenticated user, merging company-wide (branch-independent) and login-branch-specific role assignments.'
+    }),
+    (0, _nestjsshared.ApiResponseDto)(_permissiondto.UserRoleResponseDto, true, 'single'),
+    (0, _swagger.ApiResponse)({
+        status: 401,
+        description: 'Unauthorized'
+    }),
+    _ts_param(0, (0, _nestjsshared.CurrentUser)()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof _nestjsshared.ILoggedUserInfo === "undefined" ? Object : _nestjsshared.ILoggedUserInfo
+    ]),
+    _ts_metadata("design:returntype", Promise)
+], MyPermissionController.prototype, "getMyRoles", null);
+_ts_decorate([
+    (0, _common.Post)('my-actions'),
+    (0, _swagger.ApiOperation)({
+        summary: 'Get current user direct actions',
+        description: 'Returns effective direct action assignments for the authenticated user, merging company-wide (branch-independent) and login-branch-specific assignments.'
+    }),
+    (0, _nestjsshared.ApiResponseDto)(_permissiondto.UserActionResponseDto, true, 'single'),
+    (0, _swagger.ApiResponse)({
+        status: 401,
+        description: 'Unauthorized'
+    }),
+    _ts_param(0, (0, _nestjsshared.CurrentUser)()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof _nestjsshared.ILoggedUserInfo === "undefined" ? Object : _nestjsshared.ILoggedUserInfo
+    ]),
+    _ts_metadata("design:returntype", Promise)
+], MyPermissionController.prototype, "getMyActions", null);
 MyPermissionController = _ts_decorate([
     (0, _swagger.ApiTags)('IAM - My Permissions'),
     (0, _common.Controller)('iam/permissions'),

package/cjs/controllers/my-permission.controller.spec.js

@@ -9,7 +9,9 @@ describe('MyPermissionController', ()=>{
     let mockPermissionService;
     beforeEach(()=>{
         mockPermissionService = {
-            getMyPermissions: jest.fn()
+            getMyPermissions: jest.fn(),
+            getUserEffectiveRoles: jest.fn(),
+            getUserEffectiveActions: jest.fn()
         };
         controller = new _mypermissioncontroller.MyPermissionController(mockPermissionService);
     });
@@ -53,4 +55,74 @@ describe('MyPermissionController', ()=>{
             expect(mockPermissionService.getMyPermissions).toHaveBeenCalledWith('user-1', null, null, undefined);
         });
     });
+    describe('getMyRoles', ()=>{
+        it('resolves effective roles for the current user, company, and branch', async ()=>{
+            const user = (0, _loggedusermock.buildMockUser)({
+                id: 'user-1',
+                companyId: 'company-1',
+                branchId: 'branch-1'
+            });
+            const roles = [
+                {
+                    id: 'perm-1',
+                    roleId: 'role-1',
+                    roleName: 'Manager'
+                }
+            ];
+            mockPermissionService.getUserEffectiveRoles.mockResolvedValue(roles);
+            const result = await controller.getMyRoles(user);
+            expect(mockPermissionService.getUserEffectiveRoles).toHaveBeenCalledWith('user-1', 'company-1', 'branch-1');
+            expect(result).toEqual({
+                success: true,
+                message: 'Roles loaded successfully',
+                messageKey: expect.any(String),
+                data: roles
+            });
+        });
+        it('passes null for missing company and branch context', async ()=>{
+            const user = (0, _loggedusermock.buildMockUser)({
+                id: 'user-1',
+                companyId: undefined,
+                branchId: undefined
+            });
+            mockPermissionService.getUserEffectiveRoles.mockResolvedValue([]);
+            await controller.getMyRoles(user);
+            expect(mockPermissionService.getUserEffectiveRoles).toHaveBeenCalledWith('user-1', null, null);
+        });
+    });
+    describe('getMyActions', ()=>{
+        it('resolves effective actions for the current user, company, and branch', async ()=>{
+            const user = (0, _loggedusermock.buildMockUser)({
+                id: 'user-1',
+                companyId: 'company-1',
+                branchId: 'branch-1'
+            });
+            const actions = [
+                {
+                    id: 'perm-1',
+                    actionId: 'action-1',
+                    actionCode: 'user.view'
+                }
+            ];
+            mockPermissionService.getUserEffectiveActions.mockResolvedValue(actions);
+            const result = await controller.getMyActions(user);
+            expect(mockPermissionService.getUserEffectiveActions).toHaveBeenCalledWith('user-1', 'company-1', 'branch-1');
+            expect(result).toEqual({
+                success: true,
+                message: 'Actions loaded successfully',
+                messageKey: expect.any(String),
+                data: actions
+            });
+        });
+        it('passes null for missing company and branch context', async ()=>{
+            const user = (0, _loggedusermock.buildMockUser)({
+                id: 'user-1',
+                companyId: undefined,
+                branchId: undefined
+            });
+            mockPermissionService.getUserEffectiveActions.mockResolvedValue([]);
+            await controller.getMyActions(user);
+            expect(mockPermissionService.getUserEffectiveActions).toHaveBeenCalledWith('user-1', null, null);
+        });
+    });
 });

package/cjs/services/permission.service.js

@@ -531,6 +531,104 @@ let PermissionService = class PermissionService {
             };
         });
     }
+    // Effective (Merged) Permissions — self-scoped, company-wide + branch-specific
+    /** Get user's effective roles: company-wide (branchId null) merged with branch-specific */ async getUserEffectiveRoles(userId, companyId, branchId) {
+        const permissionRepo = await this.getPermissionRepository();
+        const roleRepo = await this.getRoleRepository();
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        const baseWhere = {
+            permissionType: _iampermissiontypeenum.IamPermissionType.USER_ROLE,
+            sourceType: _iamentitytypeenum.IamEntityType.USER,
+            sourceId: userId
+        };
+        if (enableCompanyFeature && companyId) baseWhere.companyId = companyId;
+        const permissions = enableCompanyFeature && branchId ? await permissionRepo.find({
+            where: [
+                {
+                    ...baseWhere,
+                    branchId: (0, _typeorm.IsNull)()
+                },
+                {
+                    ...baseWhere,
+                    branchId
+                }
+            ]
+        }) : await permissionRepo.find({
+            where: baseWhere
+        });
+        const validPermissions = permissions.filter((p)=>p.isValid());
+        if (validPermissions.length === 0) {
+            return [];
+        }
+        const roleIds = [
+            ...new Set(validPermissions.map((p)=>p.targetId))
+        ];
+        const roles = await roleRepo.find({
+            where: {
+                id: (0, _typeorm.In)(roleIds)
+            }
+        });
+        const roleMap = new Map(roles.map((r)=>[
+                r.id,
+                r
+            ]));
+        return validPermissions.filter((p)=>roleMap.has(p.targetId)).map((p)=>{
+            const role = roleMap.get(p.targetId);
+            return {
+                id: p.id,
+                userId: p.sourceId,
+                roleId: role.id,
+                roleName: role.name,
+                branchId: enableCompanyFeature ? p.branchId ?? null : null,
+                createdAt: p.createdAt
+            };
+        });
+    }
+    /** Get user's effective actions: company-wide (branchId null) merged with branch-specific */ async getUserEffectiveActions(userId, companyId, branchId) {
+        const permissionRepo = await this.getPermissionRepository();
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        const baseWhere = {
+            permissionType: _iampermissiontypeenum.IamPermissionType.USER_ACTION,
+            sourceType: _iamentitytypeenum.IamEntityType.USER,
+            sourceId: userId
+        };
+        if (enableCompanyFeature && companyId) baseWhere.companyId = companyId;
+        const permissions = enableCompanyFeature && branchId ? await permissionRepo.find({
+            where: [
+                {
+                    ...baseWhere,
+                    branchId: (0, _typeorm.IsNull)()
+                },
+                {
+                    ...baseWhere,
+                    branchId
+                }
+            ]
+        }) : await permissionRepo.find({
+            where: baseWhere
+        });
+        const validPermissions = permissions.filter((p)=>p.isValid());
+        if (validPermissions.length === 0) {
+            return [];
+        }
+        const actionIds = [
+            ...new Set(validPermissions.map((p)=>p.targetId))
+        ];
+        const actionMap = await this.getActionsMap(actionIds);
+        return validPermissions.filter((p)=>actionMap.has(p.targetId)).map((p)=>{
+            const action = actionMap.get(p.targetId);
+            return {
+                id: p.id,
+                userId: p.sourceId,
+                actionId: action.id,
+                actionCode: action.code ?? '',
+                actionName: action.name,
+                companyId: ('companyId' in p ? p.companyId : null) ?? null,
+                branchId: ('branchId' in p ? p.branchId : null) ?? null,
+                createdAt: p.createdAt
+            };
+        });
+    }
     // My Permissions
     /** Get user's effective permissions (cache-first approach) */ async getMyPermissions(userId, branchId, companyId, parentCodes) {
         return this.permissionCacheService.getMyPermissionsResponse(userId, branchId, companyId, parentCodes);

package/cjs/services/permission.service.spec.js

@@ -573,6 +573,152 @@ describe('PermissionService', ()=>{
             }));
         });
     });
+    // ==================== Effective (Merged) Permissions ====================
+    describe('getUserEffectiveRoles', ()=>{
+        it('returns an empty array when the user has no role assignments', async ()=>{
+            mockPermissionRepo.find.mockResolvedValue([]);
+            expect(await service.getUserEffectiveRoles('user-1')).toEqual([]);
+            expect(mockRoleRepo.find).not.toHaveBeenCalled();
+        });
+        it('queries only by userId when the company feature is disabled, ignoring companyId/branchId', async ()=>{
+            mockPermissionRepo.find.mockResolvedValue([]);
+            await service.getUserEffectiveRoles('user-1', 'company-1', 'branch-1');
+            expect(mockPermissionRepo.find).toHaveBeenCalledWith({
+                where: {
+                    permissionType: _iampermissiontypeenum.IamPermissionType.USER_ROLE,
+                    sourceType: _iamentitytypeenum.IamEntityType.USER,
+                    sourceId: 'user-1'
+                }
+            });
+        });
+        it('merges company-wide (branchId null) and branch-specific role assignments via an OR query', async ()=>{
+            mockIamConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            mockPermissionRepo.find.mockResolvedValue([
+                buildPermissionRow({
+                    id: 'perm-1',
+                    permissionType: _iampermissiontypeenum.IamPermissionType.USER_ROLE,
+                    targetType: _iamentitytypeenum.IamEntityType.ROLE,
+                    targetId: 'role-1',
+                    companyId: 'company-1',
+                    branchId: null
+                }),
+                buildPermissionRow({
+                    id: 'perm-2',
+                    permissionType: _iampermissiontypeenum.IamPermissionType.USER_ROLE,
+                    targetType: _iamentitytypeenum.IamEntityType.ROLE,
+                    targetId: 'role-2',
+                    companyId: 'company-1',
+                    branchId: 'branch-1'
+                })
+            ]);
+            mockRoleRepo.find.mockResolvedValue([
+                {
+                    id: 'role-1',
+                    name: 'Company Admin'
+                },
+                {
+                    id: 'role-2',
+                    name: 'Branch Manager'
+                }
+            ]);
+            const result = await service.getUserEffectiveRoles('user-1', 'company-1', 'branch-1');
+            expect(mockPermissionRepo.find).toHaveBeenCalledWith({
+                where: [
+                    expect.objectContaining({
+                        sourceId: 'user-1',
+                        companyId: 'company-1',
+                        branchId: expect.anything()
+                    }),
+                    expect.objectContaining({
+                        sourceId: 'user-1',
+                        companyId: 'company-1',
+                        branchId: 'branch-1'
+                    })
+                ]
+            });
+            expect(result.map((r)=>r.roleId).sort()).toEqual([
+                'role-1',
+                'role-2'
+            ]);
+        });
+        it('excludes expired/not-yet-valid permission rows', async ()=>{
+            mockPermissionRepo.find.mockResolvedValue([
+                buildPermissionRow({
+                    permissionType: _iampermissiontypeenum.IamPermissionType.USER_ROLE,
+                    targetType: _iamentitytypeenum.IamEntityType.ROLE,
+                    targetId: 'role-1',
+                    validUntil: new Date('2000-01-01')
+                })
+            ]);
+            const result = await service.getUserEffectiveRoles('user-1');
+            expect(result).toEqual([]);
+            expect(mockRoleRepo.find).not.toHaveBeenCalled();
+        });
+    });
+    describe('getUserEffectiveActions', ()=>{
+        it('returns an empty array when the user has no action assignments', async ()=>{
+            mockPermissionRepo.find.mockResolvedValue([]);
+            expect(await service.getUserEffectiveActions('user-1')).toEqual([]);
+            expect(mockActionRepo.find).not.toHaveBeenCalled();
+        });
+        it('merges company-wide (branchId null) and branch-specific action assignments via an OR query', async ()=>{
+            mockIamConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            mockPermissionRepo.find.mockResolvedValue([
+                buildPermissionRow({
+                    id: 'perm-1',
+                    targetId: 'action-1',
+                    companyId: 'company-1',
+                    branchId: null
+                }),
+                buildPermissionRow({
+                    id: 'perm-2',
+                    targetId: 'action-2',
+                    companyId: 'company-1',
+                    branchId: 'branch-1'
+                })
+            ]);
+            mockActionRepo.find.mockResolvedValue([
+                buildAction({
+                    id: 'action-1',
+                    code: 'user.view'
+                }),
+                buildAction({
+                    id: 'action-2',
+                    code: 'user.create'
+                })
+            ]);
+            const result = await service.getUserEffectiveActions('user-1', 'company-1', 'branch-1');
+            expect(mockPermissionRepo.find).toHaveBeenCalledWith({
+                where: [
+                    expect.objectContaining({
+                        sourceId: 'user-1',
+                        companyId: 'company-1',
+                        branchId: expect.anything()
+                    }),
+                    expect.objectContaining({
+                        sourceId: 'user-1',
+                        companyId: 'company-1',
+                        branchId: 'branch-1'
+                    })
+                ]
+            });
+            expect(result.map((a)=>a.actionId).sort()).toEqual([
+                'action-1',
+                'action-2'
+            ]);
+        });
+        it('excludes expired/not-yet-valid permission rows', async ()=>{
+            mockPermissionRepo.find.mockResolvedValue([
+                buildPermissionRow({
+                    targetId: 'action-1',
+                    validUntil: new Date('2000-01-01')
+                })
+            ]);
+            const result = await service.getUserEffectiveActions('user-1');
+            expect(result).toEqual([]);
+            expect(mockActionRepo.find).not.toHaveBeenCalled();
+        });
+    });
     // ==================== My Permissions / permission-mode branching ====================
     describe('getMyPermissions', ()=>{
         it('delegates to the cache service and returns its response', async ()=>{

package/config/message-keys.d.ts

@@ -18,6 +18,8 @@ export declare const COMPANY_ACTION_PERMISSION_MESSAGES: {
 };
 export declare const MY_PERMISSION_MESSAGES: {
     readonly GET_SUCCESS: "my.permission.get.success";
+    readonly MY_ROLES_SUCCESS: "my.permission.roles.success";
+    readonly MY_ACTIONS_SUCCESS: "my.permission.actions.success";
 };
 export declare const IAM_MODE_MESSAGES: {
     readonly DIRECT_MODE_UNAVAILABLE: "iam.direct.mode.unavailable";

package/controllers/my-permission.controller.d.ts

@@ -1,8 +1,10 @@
 import { ILoggedUserInfo, SingleResponseDto } from '@flusys/nestjs-shared';
-import { MyPermissionsQueryDto, MyPermissionsResponseDto } from '../dtos/permission.dto';
+import { MyPermissionsQueryDto, MyPermissionsResponseDto, UserActionResponseDto, UserRoleResponseDto } from '../dtos/permission.dto';
 import { PermissionService } from '../services/permission.service';
 export declare class MyPermissionController {
     private readonly permissionService;
     constructor(permissionService: PermissionService);
     getMyPermissions(query: MyPermissionsQueryDto, user: ILoggedUserInfo): Promise<SingleResponseDto<MyPermissionsResponseDto>>;
+    getMyRoles(user: ILoggedUserInfo): Promise<SingleResponseDto<UserRoleResponseDto[]>>;
+    getMyActions(user: ILoggedUserInfo): Promise<SingleResponseDto<UserActionResponseDto[]>>;
 }

package/fesm/config/message-keys.js

@@ -18,7 +18,9 @@ export const COMPANY_ACTION_PERMISSION_MESSAGES = {
     GET_SUCCESS: 'company.action.permission.get.success'
 };
 export const MY_PERMISSION_MESSAGES = {
-    GET_SUCCESS: 'my.permission.get.success'
+    GET_SUCCESS: 'my.permission.get.success',
+    MY_ROLES_SUCCESS: 'my.permission.roles.success',
+    MY_ACTIONS_SUCCESS: 'my.permission.actions.success'
 };
 export const IAM_MODE_MESSAGES = {
     DIRECT_MODE_UNAVAILABLE: 'iam.direct.mode.unavailable',

package/fesm/controllers/my-permission.controller.js

@@ -29,7 +29,7 @@ import { ApiResponseDto, CurrentUser, ILoggedUserInfo, JwtAuthGuard } from '@flu
 import { MY_PERMISSION_MESSAGES } from '../config';
 import { Body, Controller, Inject, Post, UseGuards } from '@nestjs/common';
 import { ApiBearerAuth, ApiBody, ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
-import { MyPermissionsQueryDto, MyPermissionsResponseDto } from '../dtos/permission.dto';
+import { MyPermissionsQueryDto, MyPermissionsResponseDto, UserActionResponseDto, UserRoleResponseDto } from '../dtos/permission.dto';
 import { PermissionService } from '../services/permission.service';
 export class MyPermissionController {
     async getMyPermissions(query, user) {
@@ -41,6 +41,24 @@ export class MyPermissionController {
             data
         };
     }
+    async getMyRoles(user) {
+        const data = await this.permissionService.getUserEffectiveRoles(user.id, user.companyId ?? null, user.branchId ?? null);
+        return {
+            success: true,
+            message: 'Roles loaded successfully',
+            messageKey: MY_PERMISSION_MESSAGES.MY_ROLES_SUCCESS,
+            data
+        };
+    }
+    async getMyActions(user) {
+        const data = await this.permissionService.getUserEffectiveActions(user.id, user.companyId ?? null, user.branchId ?? null);
+        return {
+            success: true,
+            message: 'Actions loaded successfully',
+            messageKey: MY_PERMISSION_MESSAGES.MY_ACTIONS_SUCCESS,
+            data
+        };
+    }
     // NOTE: @Inject() required for bundled code - type metadata may be lost during esbuild
     constructor(permissionService){
         _define_property(this, "permissionService", void 0);
@@ -70,6 +88,42 @@ _ts_decorate([
     ]),
     _ts_metadata("design:returntype", Promise)
 ], MyPermissionController.prototype, "getMyPermissions", null);
+_ts_decorate([
+    Post('my-roles'),
+    ApiOperation({
+        summary: 'Get current user roles',
+        description: 'Returns effective roles for the authenticated user, merging company-wide (branch-independent) and login-branch-specific role assignments.'
+    }),
+    ApiResponseDto(UserRoleResponseDto, true, 'single'),
+    ApiResponse({
+        status: 401,
+        description: 'Unauthorized'
+    }),
+    _ts_param(0, CurrentUser()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof ILoggedUserInfo === "undefined" ? Object : ILoggedUserInfo
+    ]),
+    _ts_metadata("design:returntype", Promise)
+], MyPermissionController.prototype, "getMyRoles", null);
+_ts_decorate([
+    Post('my-actions'),
+    ApiOperation({
+        summary: 'Get current user direct actions',
+        description: 'Returns effective direct action assignments for the authenticated user, merging company-wide (branch-independent) and login-branch-specific assignments.'
+    }),
+    ApiResponseDto(UserActionResponseDto, true, 'single'),
+    ApiResponse({
+        status: 401,
+        description: 'Unauthorized'
+    }),
+    _ts_param(0, CurrentUser()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof ILoggedUserInfo === "undefined" ? Object : ILoggedUserInfo
+    ]),
+    _ts_metadata("design:returntype", Promise)
+], MyPermissionController.prototype, "getMyActions", null);
 MyPermissionController = _ts_decorate([
     ApiTags('IAM - My Permissions'),
     Controller('iam/permissions'),

package/fesm/controllers/my-permission.controller.spec.js

@@ -5,7 +5,9 @@ describe('MyPermissionController', ()=>{
     let mockPermissionService;
     beforeEach(()=>{
         mockPermissionService = {
-            getMyPermissions: jest.fn()
+            getMyPermissions: jest.fn(),
+            getUserEffectiveRoles: jest.fn(),
+            getUserEffectiveActions: jest.fn()
         };
         controller = new MyPermissionController(mockPermissionService);
     });
@@ -49,4 +51,74 @@ describe('MyPermissionController', ()=>{
             expect(mockPermissionService.getMyPermissions).toHaveBeenCalledWith('user-1', null, null, undefined);
         });
     });
+    describe('getMyRoles', ()=>{
+        it('resolves effective roles for the current user, company, and branch', async ()=>{
+            const user = buildMockUser({
+                id: 'user-1',
+                companyId: 'company-1',
+                branchId: 'branch-1'
+            });
+            const roles = [
+                {
+                    id: 'perm-1',
+                    roleId: 'role-1',
+                    roleName: 'Manager'
+                }
+            ];
+            mockPermissionService.getUserEffectiveRoles.mockResolvedValue(roles);
+            const result = await controller.getMyRoles(user);
+            expect(mockPermissionService.getUserEffectiveRoles).toHaveBeenCalledWith('user-1', 'company-1', 'branch-1');
+            expect(result).toEqual({
+                success: true,
+                message: 'Roles loaded successfully',
+                messageKey: expect.any(String),
+                data: roles
+            });
+        });
+        it('passes null for missing company and branch context', async ()=>{
+            const user = buildMockUser({
+                id: 'user-1',
+                companyId: undefined,
+                branchId: undefined
+            });
+            mockPermissionService.getUserEffectiveRoles.mockResolvedValue([]);
+            await controller.getMyRoles(user);
+            expect(mockPermissionService.getUserEffectiveRoles).toHaveBeenCalledWith('user-1', null, null);
+        });
+    });
+    describe('getMyActions', ()=>{
+        it('resolves effective actions for the current user, company, and branch', async ()=>{
+            const user = buildMockUser({
+                id: 'user-1',
+                companyId: 'company-1',
+                branchId: 'branch-1'
+            });
+            const actions = [
+                {
+                    id: 'perm-1',
+                    actionId: 'action-1',
+                    actionCode: 'user.view'
+                }
+            ];
+            mockPermissionService.getUserEffectiveActions.mockResolvedValue(actions);
+            const result = await controller.getMyActions(user);
+            expect(mockPermissionService.getUserEffectiveActions).toHaveBeenCalledWith('user-1', 'company-1', 'branch-1');
+            expect(result).toEqual({
+                success: true,
+                message: 'Actions loaded successfully',
+                messageKey: expect.any(String),
+                data: actions
+            });
+        });
+        it('passes null for missing company and branch context', async ()=>{
+            const user = buildMockUser({
+                id: 'user-1',
+                companyId: undefined,
+                branchId: undefined
+            });
+            mockPermissionService.getUserEffectiveActions.mockResolvedValue([]);
+            await controller.getMyActions(user);
+            expect(mockPermissionService.getUserEffectiveActions).toHaveBeenCalledWith('user-1', null, null);
+        });
+    });
 });

package/fesm/services/permission.service.js

@@ -521,6 +521,104 @@ export class PermissionService {
             };
         });
     }
+    // Effective (Merged) Permissions — self-scoped, company-wide + branch-specific
+    /** Get user's effective roles: company-wide (branchId null) merged with branch-specific */ async getUserEffectiveRoles(userId, companyId, branchId) {
+        const permissionRepo = await this.getPermissionRepository();
+        const roleRepo = await this.getRoleRepository();
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        const baseWhere = {
+            permissionType: IamPermissionType.USER_ROLE,
+            sourceType: IamEntityType.USER,
+            sourceId: userId
+        };
+        if (enableCompanyFeature && companyId) baseWhere.companyId = companyId;
+        const permissions = enableCompanyFeature && branchId ? await permissionRepo.find({
+            where: [
+                {
+                    ...baseWhere,
+                    branchId: IsNull()
+                },
+                {
+                    ...baseWhere,
+                    branchId
+                }
+            ]
+        }) : await permissionRepo.find({
+            where: baseWhere
+        });
+        const validPermissions = permissions.filter((p)=>p.isValid());
+        if (validPermissions.length === 0) {
+            return [];
+        }
+        const roleIds = [
+            ...new Set(validPermissions.map((p)=>p.targetId))
+        ];
+        const roles = await roleRepo.find({
+            where: {
+                id: In(roleIds)
+            }
+        });
+        const roleMap = new Map(roles.map((r)=>[
+                r.id,
+                r
+            ]));
+        return validPermissions.filter((p)=>roleMap.has(p.targetId)).map((p)=>{
+            const role = roleMap.get(p.targetId);
+            return {
+                id: p.id,
+                userId: p.sourceId,
+                roleId: role.id,
+                roleName: role.name,
+                branchId: enableCompanyFeature ? p.branchId ?? null : null,
+                createdAt: p.createdAt
+            };
+        });
+    }
+    /** Get user's effective actions: company-wide (branchId null) merged with branch-specific */ async getUserEffectiveActions(userId, companyId, branchId) {
+        const permissionRepo = await this.getPermissionRepository();
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        const baseWhere = {
+            permissionType: IamPermissionType.USER_ACTION,
+            sourceType: IamEntityType.USER,
+            sourceId: userId
+        };
+        if (enableCompanyFeature && companyId) baseWhere.companyId = companyId;
+        const permissions = enableCompanyFeature && branchId ? await permissionRepo.find({
+            where: [
+                {
+                    ...baseWhere,
+                    branchId: IsNull()
+                },
+                {
+                    ...baseWhere,
+                    branchId
+                }
+            ]
+        }) : await permissionRepo.find({
+            where: baseWhere
+        });
+        const validPermissions = permissions.filter((p)=>p.isValid());
+        if (validPermissions.length === 0) {
+            return [];
+        }
+        const actionIds = [
+            ...new Set(validPermissions.map((p)=>p.targetId))
+        ];
+        const actionMap = await this.getActionsMap(actionIds);
+        return validPermissions.filter((p)=>actionMap.has(p.targetId)).map((p)=>{
+            const action = actionMap.get(p.targetId);
+            return {
+                id: p.id,
+                userId: p.sourceId,
+                actionId: action.id,
+                actionCode: action.code ?? '',
+                actionName: action.name,
+                companyId: ('companyId' in p ? p.companyId : null) ?? null,
+                branchId: ('branchId' in p ? p.branchId : null) ?? null,
+                createdAt: p.createdAt
+            };
+        });
+    }
     // My Permissions
     /** Get user's effective permissions (cache-first approach) */ async getMyPermissions(userId, branchId, companyId, parentCodes) {
         return this.permissionCacheService.getMyPermissionsResponse(userId, branchId, companyId, parentCodes);

package/fesm/services/permission.service.spec.js

@@ -569,6 +569,152 @@ describe('PermissionService', ()=>{
             }));
         });
     });
+    // ==================== Effective (Merged) Permissions ====================
+    describe('getUserEffectiveRoles', ()=>{
+        it('returns an empty array when the user has no role assignments', async ()=>{
+            mockPermissionRepo.find.mockResolvedValue([]);
+            expect(await service.getUserEffectiveRoles('user-1')).toEqual([]);
+            expect(mockRoleRepo.find).not.toHaveBeenCalled();
+        });
+        it('queries only by userId when the company feature is disabled, ignoring companyId/branchId', async ()=>{
+            mockPermissionRepo.find.mockResolvedValue([]);
+            await service.getUserEffectiveRoles('user-1', 'company-1', 'branch-1');
+            expect(mockPermissionRepo.find).toHaveBeenCalledWith({
+                where: {
+                    permissionType: IamPermissionType.USER_ROLE,
+                    sourceType: IamEntityType.USER,
+                    sourceId: 'user-1'
+                }
+            });
+        });
+        it('merges company-wide (branchId null) and branch-specific role assignments via an OR query', async ()=>{
+            mockIamConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            mockPermissionRepo.find.mockResolvedValue([
+                buildPermissionRow({
+                    id: 'perm-1',
+                    permissionType: IamPermissionType.USER_ROLE,
+                    targetType: IamEntityType.ROLE,
+                    targetId: 'role-1',
+                    companyId: 'company-1',
+                    branchId: null
+                }),
+                buildPermissionRow({
+                    id: 'perm-2',
+                    permissionType: IamPermissionType.USER_ROLE,
+                    targetType: IamEntityType.ROLE,
+                    targetId: 'role-2',
+                    companyId: 'company-1',
+                    branchId: 'branch-1'
+                })
+            ]);
+            mockRoleRepo.find.mockResolvedValue([
+                {
+                    id: 'role-1',
+                    name: 'Company Admin'
+                },
+                {
+                    id: 'role-2',
+                    name: 'Branch Manager'
+                }
+            ]);
+            const result = await service.getUserEffectiveRoles('user-1', 'company-1', 'branch-1');
+            expect(mockPermissionRepo.find).toHaveBeenCalledWith({
+                where: [
+                    expect.objectContaining({
+                        sourceId: 'user-1',
+                        companyId: 'company-1',
+                        branchId: expect.anything()
+                    }),
+                    expect.objectContaining({
+                        sourceId: 'user-1',
+                        companyId: 'company-1',
+                        branchId: 'branch-1'
+                    })
+                ]
+            });
+            expect(result.map((r)=>r.roleId).sort()).toEqual([
+                'role-1',
+                'role-2'
+            ]);
+        });
+        it('excludes expired/not-yet-valid permission rows', async ()=>{
+            mockPermissionRepo.find.mockResolvedValue([
+                buildPermissionRow({
+                    permissionType: IamPermissionType.USER_ROLE,
+                    targetType: IamEntityType.ROLE,
+                    targetId: 'role-1',
+                    validUntil: new Date('2000-01-01')
+                })
+            ]);
+            const result = await service.getUserEffectiveRoles('user-1');
+            expect(result).toEqual([]);
+            expect(mockRoleRepo.find).not.toHaveBeenCalled();
+        });
+    });
+    describe('getUserEffectiveActions', ()=>{
+        it('returns an empty array when the user has no action assignments', async ()=>{
+            mockPermissionRepo.find.mockResolvedValue([]);
+            expect(await service.getUserEffectiveActions('user-1')).toEqual([]);
+            expect(mockActionRepo.find).not.toHaveBeenCalled();
+        });
+        it('merges company-wide (branchId null) and branch-specific action assignments via an OR query', async ()=>{
+            mockIamConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            mockPermissionRepo.find.mockResolvedValue([
+                buildPermissionRow({
+                    id: 'perm-1',
+                    targetId: 'action-1',
+                    companyId: 'company-1',
+                    branchId: null
+                }),
+                buildPermissionRow({
+                    id: 'perm-2',
+                    targetId: 'action-2',
+                    companyId: 'company-1',
+                    branchId: 'branch-1'
+                })
+            ]);
+            mockActionRepo.find.mockResolvedValue([
+                buildAction({
+                    id: 'action-1',
+                    code: 'user.view'
+                }),
+                buildAction({
+                    id: 'action-2',
+                    code: 'user.create'
+                })
+            ]);
+            const result = await service.getUserEffectiveActions('user-1', 'company-1', 'branch-1');
+            expect(mockPermissionRepo.find).toHaveBeenCalledWith({
+                where: [
+                    expect.objectContaining({
+                        sourceId: 'user-1',
+                        companyId: 'company-1',
+                        branchId: expect.anything()
+                    }),
+                    expect.objectContaining({
+                        sourceId: 'user-1',
+                        companyId: 'company-1',
+                        branchId: 'branch-1'
+                    })
+                ]
+            });
+            expect(result.map((a)=>a.actionId).sort()).toEqual([
+                'action-1',
+                'action-2'
+            ]);
+        });
+        it('excludes expired/not-yet-valid permission rows', async ()=>{
+            mockPermissionRepo.find.mockResolvedValue([
+                buildPermissionRow({
+                    targetId: 'action-1',
+                    validUntil: new Date('2000-01-01')
+                })
+            ]);
+            const result = await service.getUserEffectiveActions('user-1');
+            expect(result).toEqual([]);
+            expect(mockActionRepo.find).not.toHaveBeenCalled();
+        });
+    });
     // ==================== My Permissions / permission-mode branching ====================
     describe('getMyPermissions', ()=>{
         it('delegates to the cache service and returns its response', async ()=>{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flusys/nestjs-iam",
-  "version": "6.2.2",
+  "version": "6.4.0",
   "description": "Identity and Access Management (IAM) module for NestJS applications",
   "main": "cjs/index.js",
   "module": "fesm/index.js",
@@ -90,7 +90,7 @@
     "express": "^5.0.0"
   },
   "dependencies": {
-    "@flusys/nestjs-core": "6.2.2",
-    "@flusys/nestjs-shared": "6.2.2"
+    "@flusys/nestjs-core": "6.4.0",
+    "@flusys/nestjs-shared": "6.4.0"
   }
 }

package/services/permission.service.d.ts

@@ -19,6 +19,8 @@ export declare class PermissionService {
     getCompanyActions(companyId: string, isOnlyId?: boolean): Promise<CompanyActionResponseDto[] | string[]>;
     assignUserRoles(dto: AssignUserRolesDto): Promise<PermissionOperationResultDto>;
     getUserRoles(userId: string, branchId?: string | undefined, companyId?: string | undefined): Promise<UserRoleResponseDto[]>;
+    getUserEffectiveRoles(userId: string, companyId?: string | null, branchId?: string | null): Promise<UserRoleResponseDto[]>;
+    getUserEffectiveActions(userId: string, companyId?: string | null, branchId?: string | null): Promise<UserActionResponseDto[]>;
     getMyPermissions(userId: string, branchId: string | null, companyId?: string | null, parentCodes?: string[]): Promise<MyPermissionsResponseDto>;
     private splitItemsByAction;
     private buildOperationResult;