@flusys/nestjs-iam 6.0.2 → 6.1.1

package/cjs/controllers/action.controller.spec.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _loggedusermock = require("@test-utils/mocks/logged-user.mock");
+const _actioncontroller = require("./action.controller");
+describe('ActionController', ()=>{
+    let controller;
+    let mockActionService;
+    let mockIamConfigService;
+    beforeEach(()=>{
+        mockActionService = {
+            insert: jest.fn(),
+            findById: jest.fn(),
+            getAll: jest.fn(),
+            update: jest.fn(),
+            delete: jest.fn(),
+            getActionsForPermission: jest.fn(),
+            getActionTree: jest.fn()
+        };
+        mockIamConfigService = {};
+        controller = new _actioncontroller.ActionController(mockActionService, mockIamConfigService);
+    });
+    it('wires the injected service onto the generated controller base', ()=>{
+        expect(controller.actionService).toBe(mockActionService);
+        expect(controller.service).toBe(mockActionService);
+    });
+    describe('getActionsForPermission', ()=>{
+        it('returns actions scoped to the caller session company when no companyId is given', async ()=>{
+            const user = (0, _loggedusermock.buildMockUser)();
+            mockActionService.getActionsForPermission.mockResolvedValue([
+                {
+                    id: 'action-1',
+                    code: 'user.create'
+                }
+            ]);
+            const result = await controller.getActionsForPermission({}, user);
+            expect(mockActionService.getActionsForPermission).toHaveBeenCalledWith(user, undefined);
+            expect(result.success).toBe(true);
+            expect(result.data).toEqual([
+                {
+                    id: 'action-1',
+                    code: 'user.create'
+                }
+            ]);
+        });
+        it('forwards an explicit companyId override', async ()=>{
+            const user = (0, _loggedusermock.buildMockUser)();
+            mockActionService.getActionsForPermission.mockResolvedValue([]);
+            await controller.getActionsForPermission({
+                companyId: 'company-2'
+            }, user);
+            expect(mockActionService.getActionsForPermission).toHaveBeenCalledWith(user, 'company-2');
+        });
+    });
+    describe('getActionTree', ()=>{
+        it('returns the hierarchical action tree with query filters applied', async ()=>{
+            const user = (0, _loggedusermock.buildMockUser)();
+            mockActionService.getActionTree.mockResolvedValue([
+                {
+                    id: 'action-1',
+                    children: []
+                }
+            ]);
+            const result = await controller.getActionTree({
+                search: 'user',
+                isActive: true,
+                withDeleted: false
+            }, user);
+            expect(mockActionService.getActionTree).toHaveBeenCalledWith(user, 'user', true, false);
+            expect(result.data).toEqual([
+                {
+                    id: 'action-1',
+                    children: []
+                }
+            ]);
+        });
+    });
+});

package/cjs/controllers/company-action-permission.controller.js

@@ -57,7 +57,7 @@ let CompanyActionPermissionController = class CompanyActionPermissionController
         };
     }
     async getCompanyActions(dto) {
-        const actions = await this.permissionService.getCompanyActions(dto.companyId);
+        const actions = await this.permissionService.getCompanyActions(dto.companyId, false);
         return {
             success: true,
             message: 'Company actions retrieved successfully',

package/cjs/controllers/company-action-permission.controller.spec.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _companyactionpermissioncontroller = require("./company-action-permission.controller");
+describe('CompanyActionPermissionController', ()=>{
+    let controller;
+    let mockPermissionService;
+    beforeEach(()=>{
+        mockPermissionService = {
+            assignCompanyActions: jest.fn(),
+            getCompanyActions: jest.fn()
+        };
+        controller = new _companyactionpermissioncontroller.CompanyActionPermissionController(mockPermissionService);
+    });
+    describe('assignCompanyActions', ()=>{
+        it('whitelists actions for a company', async ()=>{
+            mockPermissionService.assignCompanyActions.mockResolvedValue({
+                added: 3,
+                removed: 0,
+                total: 3
+            });
+            const result = await controller.assignCompanyActions({
+                companyId: 'company-1',
+                actionIds: [
+                    'action-1',
+                    'action-2',
+                    'action-3'
+                ]
+            });
+            expect(mockPermissionService.assignCompanyActions).toHaveBeenCalledWith({
+                companyId: 'company-1',
+                actionIds: [
+                    'action-1',
+                    'action-2',
+                    'action-3'
+                ]
+            });
+            expect(result.success).toBe(true);
+            expect(result.data).toEqual({
+                added: 3,
+                removed: 0,
+                total: 3
+            });
+        });
+    });
+    describe('getCompanyActions', ()=>{
+        it('returns the whitelisted actions for a company', async ()=>{
+            mockPermissionService.getCompanyActions.mockResolvedValue([
+                {
+                    actionId: 'action-1'
+                }
+            ]);
+            const result = await controller.getCompanyActions({
+                companyId: 'company-1'
+            });
+            expect(mockPermissionService.getCompanyActions).toHaveBeenCalledWith('company-1', false);
+            expect(result.data).toEqual([
+                {
+                    actionId: 'action-1'
+                }
+            ]);
+        });
+    });
+});

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

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _loggedusermock = require("@test-utils/mocks/logged-user.mock");
+const _mypermissioncontroller = require("./my-permission.controller");
+describe('MyPermissionController', ()=>{
+    let controller;
+    let mockPermissionService;
+    beforeEach(()=>{
+        mockPermissionService = {
+            getMyPermissions: jest.fn()
+        };
+        controller = new _mypermissioncontroller.MyPermissionController(mockPermissionService);
+    });
+    describe('getMyPermissions', ()=>{
+        it('resolves permissions for the current user, branch, and company', async ()=>{
+            const user = (0, _loggedusermock.buildMockUser)({
+                id: 'user-1',
+                companyId: 'company-1',
+                branchId: 'branch-1'
+            });
+            const permissions = {
+                menus: [],
+                actions: [
+                    'user.create'
+                ]
+            };
+            mockPermissionService.getMyPermissions.mockResolvedValue(permissions);
+            const result = await controller.getMyPermissions({
+                parentCodes: [
+                    'user'
+                ]
+            }, user);
+            expect(mockPermissionService.getMyPermissions).toHaveBeenCalledWith('user-1', 'branch-1', 'company-1', [
+                'user'
+            ]);
+            expect(result).toEqual({
+                success: true,
+                message: 'Permissions loaded successfully',
+                messageKey: expect.any(String),
+                data: permissions
+            });
+        });
+        it('passes null for missing branch and company context', async ()=>{
+            const user = (0, _loggedusermock.buildMockUser)({
+                id: 'user-1',
+                companyId: undefined,
+                branchId: undefined
+            });
+            mockPermissionService.getMyPermissions.mockResolvedValue({});
+            await controller.getMyPermissions({}, user);
+            expect(mockPermissionService.getMyPermissions).toHaveBeenCalledWith('user-1', null, null, undefined);
+        });
+    });
+});

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

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _common = require("@nestjs/common");
+const _loggedusermock = require("@test-utils/mocks/logged-user.mock");
+const _rolepermissioncontroller = require("./role-permission.controller");
+describe('RolePermissionController', ()=>{
+    let controller;
+    let mockPermissionService;
+    let mockConfig;
+    beforeEach(()=>{
+        mockPermissionService = {
+            assignRoleActions: jest.fn(),
+            getRoleActions: jest.fn(),
+            assignUserRoles: jest.fn(),
+            getUserRoles: jest.fn()
+        };
+        mockConfig = {
+            isCompanyFeatureEnabled: jest.fn().mockReturnValue(false)
+        };
+        controller = new _rolepermissioncontroller.RolePermissionController(mockPermissionService, mockConfig);
+    });
+    describe('assignRoleActions', ()=>{
+        it('assigns actions to a role and returns the operation summary', async ()=>{
+            mockPermissionService.assignRoleActions.mockResolvedValue({
+                added: 2,
+                removed: 1,
+                total: 3
+            });
+            const result = await controller.assignRoleActions({
+                roleId: 'role-1',
+                actionIds: [
+                    'action-1',
+                    'action-2'
+                ]
+            });
+            expect(mockPermissionService.assignRoleActions).toHaveBeenCalledWith({
+                roleId: 'role-1',
+                actionIds: [
+                    'action-1',
+                    'action-2'
+                ]
+            });
+            expect(result.success).toBe(true);
+            expect(result.data).toEqual({
+                added: 2,
+                removed: 1,
+                total: 3
+            });
+        });
+    });
+    describe('getRoleActions', ()=>{
+        it('returns actions assigned to the role', async ()=>{
+            mockPermissionService.getRoleActions.mockResolvedValue([
+                {
+                    actionId: 'action-1'
+                }
+            ]);
+            const result = await controller.getRoleActions({
+                roleId: 'role-1'
+            });
+            expect(mockPermissionService.getRoleActions).toHaveBeenCalledWith('role-1');
+            expect(result.data).toEqual([
+                {
+                    actionId: 'action-1'
+                }
+            ]);
+        });
+    });
+    describe('assignUserRoles', ()=>{
+        it('assigns roles to a user when the caller has access to the target company', async ()=>{
+            mockConfig.isCompanyFeatureEnabled.mockReturnValue(true);
+            const user = (0, _loggedusermock.buildMockUser)({
+                companyId: 'company-1'
+            });
+            mockPermissionService.assignUserRoles.mockResolvedValue({
+                added: 1,
+                removed: 0,
+                total: 1
+            });
+            const result = await controller.assignUserRoles({
+                userId: 'user-2',
+                roleIds: [
+                    'role-1'
+                ],
+                companyId: 'company-1'
+            }, user);
+            expect(mockPermissionService.assignUserRoles).toHaveBeenCalledWith({
+                userId: 'user-2',
+                roleIds: [
+                    'role-1'
+                ],
+                companyId: 'company-1'
+            });
+            expect(result.data).toEqual({
+                added: 1,
+                removed: 0,
+                total: 1
+            });
+        });
+        it('rejects assignment when the caller has no access to the target company', async ()=>{
+            mockConfig.isCompanyFeatureEnabled.mockReturnValue(true);
+            const user = (0, _loggedusermock.buildMockUser)({
+                companyId: 'company-1'
+            });
+            await expect(controller.assignUserRoles({
+                userId: 'user-2',
+                roleIds: [
+                    'role-1'
+                ],
+                companyId: 'company-2'
+            }, user)).rejects.toThrow(_common.ForbiddenException);
+            expect(mockPermissionService.assignUserRoles).not.toHaveBeenCalled();
+        });
+    });
+    describe('getUserRoles', ()=>{
+        it('returns roles assigned to the user scoped by branch and company', async ()=>{
+            const user = (0, _loggedusermock.buildMockUser)({
+                companyId: 'company-1'
+            });
+            mockPermissionService.getUserRoles.mockResolvedValue([
+                {
+                    roleId: 'role-1'
+                }
+            ]);
+            const result = await controller.getUserRoles({
+                userId: 'user-2',
+                branchId: 'branch-1',
+                companyId: 'company-1'
+            }, user);
+            expect(mockPermissionService.getUserRoles).toHaveBeenCalledWith('user-2', 'branch-1', 'company-1');
+            expect(result.data).toEqual([
+                {
+                    roleId: 'role-1'
+                }
+            ]);
+        });
+    });
+});

package/cjs/controllers/role.controller.spec.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _loggedusermock = require("@test-utils/mocks/logged-user.mock");
+const _rolecontroller = require("./role.controller");
+function buildRole(overrides = {}) {
+    return {
+        id: 'role-1',
+        name: 'Admin',
+        description: null,
+        isActive: true,
+        readOnly: false,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        ...overrides
+    };
+}
+describe('RoleController', ()=>{
+    let controller;
+    let mockRoleService;
+    beforeEach(()=>{
+        mockRoleService = {
+            insert: jest.fn(),
+            findById: jest.fn(),
+            getAll: jest.fn(),
+            update: jest.fn(),
+            delete: jest.fn()
+        };
+        controller = new _rolecontroller.RoleController(mockRoleService);
+    });
+    it('wires the injected service onto the generated controller base', ()=>{
+        expect(controller.roleService).toBe(mockRoleService);
+        expect(controller.service).toBe(mockRoleService);
+    });
+    describe('insert', ()=>{
+        it('creates a role and returns the mapped response', async ()=>{
+            const user = (0, _loggedusermock.buildMockUser)();
+            mockRoleService.insert.mockResolvedValue(buildRole());
+            const result = await controller.insert({
+                name: 'Admin'
+            }, user);
+            expect(mockRoleService.insert).toHaveBeenCalledWith({
+                name: 'Admin'
+            }, user);
+            expect(result.success).toBe(true);
+            expect(result.data).toEqual(expect.objectContaining({
+                id: 'role-1',
+                name: 'Admin'
+            }));
+        });
+    });
+    describe('getAll', ()=>{
+        it('paginates roles and maps the response list', async ()=>{
+            mockRoleService.getAll.mockResolvedValue({
+                data: [
+                    buildRole()
+                ],
+                total: 1
+            });
+            const result = await controller.getAll({}, (0, _loggedusermock.buildMockUser)(), '');
+            expect(mockRoleService.getAll).toHaveBeenCalledWith('', {}, (0, _loggedusermock.buildMockUser)());
+            expect(result.data).toHaveLength(1);
+        });
+    });
+    describe('delete', ()=>{
+        it('delegates soft-delete to the service', async ()=>{
+            mockRoleService.delete.mockResolvedValue({
+                count: 1
+            });
+            const result = await controller.delete({
+                id: [
+                    'role-1'
+                ],
+                type: 'delete'
+            }, (0, _loggedusermock.buildMockUser)());
+            expect(mockRoleService.delete).toHaveBeenCalledWith({
+                id: [
+                    'role-1'
+                ],
+                type: 'delete'
+            }, (0, _loggedusermock.buildMockUser)());
+            expect(result.success).toBe(true);
+        });
+    });
+});

package/cjs/controllers/user-action-permission.controller.js

@@ -58,7 +58,7 @@ let UserActionPermissionController = class UserActionPermissionController {
         };
     }
     async getUserActions(dto, user) {
-        const actions = await this.permissionService.getUserActions(dto.userId, dto.branchId, dto.companyId);
+        const actions = await this.permissionService.getUserActions(dto.userId, dto.companyId, dto.branchId);
         return {
             success: true,
             message: 'User actions retrieved successfully',

package/cjs/controllers/user-action-permission.controller.spec.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _loggedusermock = require("@test-utils/mocks/logged-user.mock");
+const _useractionpermissioncontroller = require("./user-action-permission.controller");
+describe('UserActionPermissionController', ()=>{
+    let controller;
+    let mockPermissionService;
+    let mockConfig;
+    beforeEach(()=>{
+        mockPermissionService = {
+            assignUserActions: jest.fn(),
+            getUserActions: jest.fn()
+        };
+        mockConfig = {};
+        controller = new _useractionpermissioncontroller.UserActionPermissionController(mockPermissionService, mockConfig);
+    });
+    describe('assignUserActions', ()=>{
+        it('assigns direct action permissions to a user', async ()=>{
+            const user = (0, _loggedusermock.buildMockUser)();
+            mockPermissionService.assignUserActions.mockResolvedValue({
+                added: 1,
+                removed: 0,
+                total: 1
+            });
+            const result = await controller.assignUserActions({
+                userId: 'user-2',
+                actionIds: [
+                    'action-1'
+                ]
+            }, user);
+            expect(mockPermissionService.assignUserActions).toHaveBeenCalledWith({
+                userId: 'user-2',
+                actionIds: [
+                    'action-1'
+                ]
+            });
+            expect(result.success).toBe(true);
+            expect(result.data).toEqual({
+                added: 1,
+                removed: 0,
+                total: 1
+            });
+        });
+    });
+    describe('getUserActions', ()=>{
+        it('returns direct action permissions for a user scoped by branch/company', async ()=>{
+            const user = (0, _loggedusermock.buildMockUser)();
+            mockPermissionService.getUserActions.mockResolvedValue([
+                {
+                    actionId: 'action-1'
+                }
+            ]);
+            const result = await controller.getUserActions({
+                userId: 'user-2',
+                branchId: 'branch-1',
+                companyId: 'company-1'
+            }, user);
+            expect(mockPermissionService.getUserActions).toHaveBeenCalledWith('user-2', 'company-1', 'branch-1');
+            expect(result.data).toEqual([
+                {
+                    actionId: 'action-1'
+                }
+            ]);
+        });
+    });
+});

package/cjs/docs/iam-swagger.config.spec.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _iamswaggerconfig = require("./iam-swagger.config");
+const _permissiontypeenum = require("../enums/permission-type.enum");
+describe('iamSwaggerConfig', ()=>{
+    it('should default to company disabled, FULL mode, single database', ()=>{
+        const config = (0, _iamswaggerconfig.iamSwaggerConfig)();
+        expect(config.title).toBe('IAM API');
+        expect(config.path).toBe('api/docs/iam');
+        expect(config.bearerAuth).toBe(true);
+        // enableCompanyFeature defaults to false, so company-scoped exclusions apply
+        expect(config.excludeSchemaProperties?.length).toBeGreaterThan(0);
+        expect(config.excludeQueryParameters?.length).toBeGreaterThan(0);
+        expect(config.description).not.toContain('Multi-Tenant Mode');
+    });
+    it('should always exclude auth-related tags regardless of configuration', ()=>{
+        const config = (0, _iamswaggerconfig.iamSwaggerConfig)(true, _permissiontypeenum.IAMPermissionMode.FULL);
+        expect(config.excludeTags).toEqual(expect.arrayContaining([
+            'Authentication',
+            'Users',
+            'Companies',
+            'Branches'
+        ]));
+    });
+    it('should exclude company-scoped schema properties and query params when company feature is off', ()=>{
+        const config = (0, _iamswaggerconfig.iamSwaggerConfig)(false);
+        expect(config.excludeSchemaProperties).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                schemaName: 'AssignUserActionsDto',
+                properties: [
+                    'companyId',
+                    'branchId'
+                ]
+            })
+        ]));
+        expect(config.excludeQueryParameters).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                pathPattern: '/iam/permissions/user-actions/*',
+                method: 'get'
+            })
+        ]));
+        expect(config.excludeTags).toContain('IAM - Company Action Permissions');
+    });
+    it('should not exclude company-scoped schema properties, query params, or tags when company feature is on', ()=>{
+        const config = (0, _iamswaggerconfig.iamSwaggerConfig)(true);
+        expect(config.excludeSchemaProperties).toEqual([]);
+        expect(config.excludeQueryParameters).toEqual([]);
+        expect(config.excludeTags).not.toContain('IAM - Company Action Permissions');
+    });
+    it('should hide DIRECT-mode tags in RBAC mode', ()=>{
+        const config = (0, _iamswaggerconfig.iamSwaggerConfig)(false, _permissiontypeenum.IAMPermissionMode.RBAC);
+        expect(config.excludeTags).toContain('IAM - Permissions (Direct)');
+        expect(config.excludeTags).not.toContain('IAM - Permissions (RBAC)');
+        expect(config.excludeTags).not.toContain('IAM - Roles');
+    });
+    it('should hide RBAC-mode tags (including Roles) in DIRECT mode', ()=>{
+        const config = (0, _iamswaggerconfig.iamSwaggerConfig)(false, _permissiontypeenum.IAMPermissionMode.DIRECT);
+        expect(config.excludeTags).toContain('IAM - Permissions (RBAC)');
+        expect(config.excludeTags).toContain('IAM - Roles');
+        expect(config.excludeTags).not.toContain('IAM - Permissions (Direct)');
+    });
+    it('should hide neither RBAC nor DIRECT tags in FULL mode', ()=>{
+        const config = (0, _iamswaggerconfig.iamSwaggerConfig)(false, _permissiontypeenum.IAMPermissionMode.FULL);
+        expect(config.excludeTags).not.toContain('IAM - Permissions (RBAC)');
+        expect(config.excludeTags).not.toContain('IAM - Permissions (Direct)');
+        expect(config.excludeTags).not.toContain('IAM - Roles');
+    });
+    it('should mention multi-tenant mode in the description only for multi-tenant database mode', ()=>{
+        const multiTenant = (0, _iamswaggerconfig.iamSwaggerConfig)(false, _permissiontypeenum.IAMPermissionMode.FULL, 'multi-tenant');
+        const single = (0, _iamswaggerconfig.iamSwaggerConfig)(false, _permissiontypeenum.IAMPermissionMode.FULL, 'single');
+        expect(multiTenant.description).toContain('Multi-Tenant Mode');
+        expect(single.description).not.toContain('Multi-Tenant Mode');
+    });
+    it('should describe RBAC as active and DIRECT as disabled in the endpoints summary for RBAC mode', ()=>{
+        const config = (0, _iamswaggerconfig.iamSwaggerConfig)(false, _permissiontypeenum.IAMPermissionMode.RBAC);
+        expect(config.description).toContain('**Roles**: CRUD operations');
+        expect(config.description).toContain('❌ **User-Actions**: Disabled (DIRECT mode not active)');
+    });
+    it('should describe DIRECT as active and Roles as disabled in the endpoints summary for DIRECT mode', ()=>{
+        const config = (0, _iamswaggerconfig.iamSwaggerConfig)(false, _permissiontypeenum.IAMPermissionMode.DIRECT);
+        expect(config.description).toContain('✅ **User-Actions**: Direct action assignment to users');
+        expect(config.description).toContain('❌ **Roles**: Disabled (RBAC mode not active)');
+    });
+    it('should describe company features as active only when company feature is enabled', ()=>{
+        const withCompany = (0, _iamswaggerconfig.iamSwaggerConfig)(true, _permissiontypeenum.IAMPermissionMode.FULL);
+        const withoutCompany = (0, _iamswaggerconfig.iamSwaggerConfig)(false, _permissiontypeenum.IAMPermissionMode.FULL);
+        expect(withCompany.description).toContain('Company Features (Active)');
+        expect(withCompany.description).toContain('✅ **Company-Actions**: Whitelist actions for companies');
+        expect(withoutCompany.description).not.toContain('Company Features (Active)');
+        expect(withoutCompany.description).toContain('❌ **Company-Actions**: Disabled (company feature not enabled)');
+    });
+    it('should describe the current permission mode label correctly for each mode', ()=>{
+        expect((0, _iamswaggerconfig.iamSwaggerConfig)(false, _permissiontypeenum.IAMPermissionMode.RBAC).description).toContain('**RBAC** (Role-Based Access Control)');
+        expect((0, _iamswaggerconfig.iamSwaggerConfig)(false, _permissiontypeenum.IAMPermissionMode.DIRECT).description).toContain('**DIRECT** (Direct User Permissions)');
+        expect((0, _iamswaggerconfig.iamSwaggerConfig)(false, _permissiontypeenum.IAMPermissionMode.FULL).description).toContain('**FULL** (RBAC + Direct)');
+    });
+});

package/cjs/dtos/permission.dto.js

@@ -351,6 +351,7 @@ let UserActionResponseDto = class UserActionResponseDto {
         _define_property(this, "actionId", void 0);
         _define_property(this, "actionCode", void 0);
         _define_property(this, "actionName", void 0);
+        _define_property(this, "companyId", void 0);
         _define_property(this, "branchId", void 0);
         _define_property(this, "createdAt", void 0);
     }
@@ -385,6 +386,12 @@ _ts_decorate([
     }),
     _ts_metadata("design:type", String)
 ], UserActionResponseDto.prototype, "actionName", void 0);
+_ts_decorate([
+    (0, _swagger.ApiPropertyOptional)({
+        description: 'Company ID (null = global)'
+    }),
+    _ts_metadata("design:type", Object)
+], UserActionResponseDto.prototype, "companyId", void 0);
 _ts_decorate([
     (0, _swagger.ApiPropertyOptional)({
         description: 'Branch ID (null = company-wide)'