@flusys/nestjs-iam 7.0.2 → 8.0.0-beta.1

package/fesm/docs/iam-swagger.config.js

@@ -1,199 +0,0 @@
-import { IAMPermissionMode } from '../enums/permission-type.enum';
-/** Auth-related tags that should always be excluded from IAM API docs */ const AUTH_RELATED_TAGS = [
-    'Authentication',
-    'Users',
-    'Companies',
-    'Branches',
-    'User Permissions',
-    'Company Selection'
-];
-export function iamSwaggerConfig(enableCompanyFeature = false, permissionMode = IAMPermissionMode.FULL, databaseMode = 'single') {
-    const multiTenantNote = databaseMode === 'multi-tenant' ? `\n> **Multi-Tenant Mode**: Include \`x-tenant-id\` header to target a specific tenant database.\n` : '';
-    const excludeSchemaProperties = enableCompanyFeature ? [] : [
-        // DTOs with companyId and branchId
-        {
-            schemaName: 'AssignUserActionsDto',
-            properties: [
-                'companyId',
-                'branchId'
-            ]
-        },
-        {
-            schemaName: 'AssignUserRolesDto',
-            properties: [
-                'companyId',
-                'branchId'
-            ]
-        },
-        {
-            schemaName: 'GetUserActionsDto',
-            properties: [
-                'companyId',
-                'branchId'
-            ]
-        },
-        {
-            schemaName: 'GetUserRolesDto',
-            properties: [
-                'companyId',
-                'branchId'
-            ]
-        },
-        {
-            schemaName: 'ActionTreeForPermissionDto',
-            properties: [
-                'companyId'
-            ]
-        },
-        // Response DTOs with branchId
-        {
-            schemaName: 'UserActionResponseDto',
-            properties: [
-                'branchId'
-            ]
-        },
-        {
-            schemaName: 'UserRoleResponseDto',
-            properties: [
-                'branchId'
-            ]
-        },
-        // Company-related DTOs (entire schemas hidden via tag exclusion, but just in case)
-        {
-            schemaName: 'AssignCompanyActionsDto',
-            properties: [
-                'companyId'
-            ]
-        },
-        {
-            schemaName: 'CompanyActionResponseDto',
-            properties: [
-                'companyId'
-            ]
-        }
-    ];
-    // Hide query parameters for GET endpoints when company feature is disabled
-    const excludeQueryParameters = enableCompanyFeature ? [] : [
-        {
-            pathPattern: '/iam/permissions/user-actions/*',
-            method: 'get',
-            parameters: [
-                'companyId',
-                'branchId'
-            ]
-        },
-        {
-            pathPattern: '/iam/permissions/user-roles/*',
-            method: 'get',
-            parameters: [
-                'companyId',
-                'branchId'
-            ]
-        }
-    ];
-    // Build exclude tags list: always exclude Auth tags + conditionally exclude based on permission mode
-    const excludeTags = [
-        ...AUTH_RELATED_TAGS
-    ];
-    // Hide company-related IAM endpoints when company feature is disabled
-    if (!enableCompanyFeature) {
-        excludeTags.push('IAM - Company Action Permissions');
-    }
-    // Conditionally exclude endpoints based on permission mode
-    if (permissionMode === IAMPermissionMode.RBAC) {
-        // RBAC only - hide direct user action endpoints
-        excludeTags.push('IAM - Permissions (Direct)');
-    } else if (permissionMode === IAMPermissionMode.DIRECT) {
-        // Direct only - hide RBAC endpoints
-        excludeTags.push('IAM - Permissions (RBAC)');
-        excludeTags.push('IAM - Roles'); // Roles are only used in RBAC
-    }
-    return {
-        title: 'IAM API',
-        description: `
-## Identity & Access Management API
-${multiTenantNote}
-Advanced permission system with flexible modes: RBAC, Direct Permissions, or both.
-
-### Current Configuration
-- **Permission Mode**: ${permissionMode === IAMPermissionMode.RBAC ? '**RBAC** (Role-Based Access Control)' : permissionMode === IAMPermissionMode.DIRECT ? '**DIRECT** (Direct User Permissions)' : '**FULL** (RBAC + Direct)'}${enableCompanyFeature ? '\n- **Company Feature**: Enabled (Multi-tenant with company/branch scoping)' : '\n- **Company Feature**: Disabled'}
-
-### Features Based on Mode
-
-${permissionMode === IAMPermissionMode.RBAC || permissionMode === IAMPermissionMode.FULL ? `#### RBAC Features (Active)
-- **Roles**: Create company-scoped roles${enableCompanyFeature ? ' (auto-filtered by user company)' : ''}
-- **Role-Actions**: Assign actions to roles
-- **User-Roles**: Assign roles to users${enableCompanyFeature ? ' at branch level' : ''}
-` : ''}${permissionMode === IAMPermissionMode.DIRECT || permissionMode === IAMPermissionMode.FULL ? `#### Direct Permission Features (Active)
-- **User-Actions**: Direct action assignment to users${enableCompanyFeature ? ' at branch level' : ''}
-` : ''}${enableCompanyFeature ? `#### Company Features (Active)
-- **Company-Action Whitelist**: Control which actions are available per company
-- **Branch-Based Scoping**: Permissions scoped to specific branches
-- **Auto-Filtering**: Roles automatically filtered by user's company
-- **Action Tree Filtering**: Available actions filtered by company whitelist
-` : ''}
-### Core Concepts
-
-#### Actions
-Represent permissions in the system. Can be hierarchical.
-
-**Action Types:**
-- \`menu\` - Menu visibility (actions with type='menu' are used as menus)
-- \`endpoint\` - API endpoint access
-- \`frontend\` - Frontend feature toggles
-${permissionMode === IAMPermissionMode.RBAC || permissionMode === IAMPermissionMode.FULL ? `
-#### Roles
-Collections of actions that can be assigned to users.${enableCompanyFeature ? ' Scoped to companies.' : ' Global across the system.'}
-` : ''}${enableCompanyFeature ? `
-#### Company-Action Whitelist
-Controls which actions are available to a company. Users/roles can only use whitelisted actions.
-
-**Flow:**
-1. Admin assigns actions to company (whitelist)
-2. Only whitelisted actions appear in permission assignment UIs
-3. Users/roles cannot be assigned non-whitelisted actions
-` : ''}
-### Permission Resolution
-
-${permissionMode === IAMPermissionMode.FULL ? `1. **Company-Action Whitelist** - Filter by company (if enabled)
-2. **UserAction (DENY)** - Explicit denials take precedence
-3. **UserAction (GRANT)** - Direct user grants
-4. **UserRole → RoleAction** - Inherited from assigned roles
-5. **Action Permission Logic** - Complex AND/OR rules` : permissionMode === IAMPermissionMode.RBAC ? `1. **Company-Action Whitelist** - Filter by company (if enabled)
-2. **UserRole → RoleAction** - Actions inherited from roles
-3. **Action Permission Logic** - Complex AND/OR rules` : `1. **Company-Action Whitelist** - Filter by company (if enabled)
-2. **UserAction (DENY)** - Explicit denials take precedence
-3. **UserAction (GRANT)** - Direct user grants
-4. **Action Permission Logic** - Complex AND/OR rules`}
-
-### API Endpoints Summary
-
-#### Available Endpoints
-- ✅ **Actions**: CRUD operations, tree view${enableCompanyFeature ? ', filtered tree for permissions' : ''}${permissionMode === IAMPermissionMode.RBAC || permissionMode === IAMPermissionMode.FULL ? `
-- ✅ **Roles**: CRUD operations${enableCompanyFeature ? ' (auto-filtered by company)' : ''}
-- ✅ **Role-Actions**: Assign actions to roles, get role actions
-- ✅ **User-Roles**: Assign roles to users, get user roles` : `
-- ❌ **Roles**: Disabled (RBAC mode not active)`}${permissionMode === IAMPermissionMode.DIRECT || permissionMode === IAMPermissionMode.FULL ? `
-- ✅ **User-Actions**: Direct action assignment to users` : `
-- ❌ **User-Actions**: Disabled (DIRECT mode not active)`}${enableCompanyFeature ? `
-- ✅ **Company-Actions**: Whitelist actions for companies` : `
-- ❌ **Company-Actions**: Disabled (company feature not enabled)`}
-- ✅ **My Permissions**: Get current user's complete permissions (includes menu-type actions)
-
-### Best Practices
-
-1. **Action Codes**: Use meaningful codes like \`user.create\`, \`order.view\`
-2. **Hierarchical Actions**: Group related actions (use parentId for hierarchy)${permissionMode === IAMPermissionMode.RBAC || permissionMode === IAMPermissionMode.FULL ? `
-3. **Role Design**: Create roles for common permission patterns` : ''}${permissionMode === IAMPermissionMode.DIRECT || permissionMode === IAMPermissionMode.FULL ? `
-${permissionMode === IAMPermissionMode.FULL ? '4' : '3'}. **Direct Actions**: Use sparingly for exceptions` : ''}${enableCompanyFeature ? `
-${permissionMode === IAMPermissionMode.FULL ? '5' : '4'}. **Company Whitelisting**: Set up action whitelist before assigning permissions
-${permissionMode === IAMPermissionMode.FULL ? '6' : '5'}. **Branch Scoping**: Use branches for location-based access control` : ''}
-  `,
-        version: '1.0',
-        path: 'api/docs/iam',
-        bearerAuth: true,
-        excludeSchemaProperties,
-        excludeTags,
-        excludeQueryParameters
-    };
-}

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

@@ -1,95 +0,0 @@
-import { iamSwaggerConfig } from './iam-swagger.config';
-import { IAMPermissionMode } from '../enums/permission-type.enum';
-describe('iamSwaggerConfig', ()=>{
-    it('should default to company disabled, FULL mode, single database', ()=>{
-        const config = 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 = iamSwaggerConfig(true, 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 = 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 = 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 = iamSwaggerConfig(false, 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 = iamSwaggerConfig(false, 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 = iamSwaggerConfig(false, 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 = iamSwaggerConfig(false, IAMPermissionMode.FULL, 'multi-tenant');
-        const single = iamSwaggerConfig(false, 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 = iamSwaggerConfig(false, 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 = iamSwaggerConfig(false, 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 = iamSwaggerConfig(true, IAMPermissionMode.FULL);
-        const withoutCompany = iamSwaggerConfig(false, 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(iamSwaggerConfig(false, IAMPermissionMode.RBAC).description).toContain('**RBAC** (Role-Based Access Control)');
-        expect(iamSwaggerConfig(false, IAMPermissionMode.DIRECT).description).toContain('**DIRECT** (Direct User Permissions)');
-        expect(iamSwaggerConfig(false, IAMPermissionMode.FULL).description).toContain('**FULL** (RBAC + Direct)');
-    });
-});

package/fesm/dtos/action.dto.js

@@ -1,252 +0,0 @@
-function _define_property(obj, key, value) {
-    if (key in obj) {
-        Object.defineProperty(obj, key, {
-            value: value,
-            enumerable: true,
-            configurable: true,
-            writable: true
-        });
-    } else {
-        obj[key] = value;
-    }
-    return obj;
-}
-function _ts_decorate(decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-function _ts_metadata(k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-import { IdentityResponseDto } from '@flusys/nestjs-shared/dtos';
-import { ApiProperty, PartialType } from '@nestjs/swagger';
-import { Expose } from 'class-transformer';
-import { IsBoolean, IsEnum, IsInt, IsNotEmpty, IsOptional, IsString, IsUUID, MaxLength } from 'class-validator';
-import { ActionType } from '../enums';
-import { LogicNode } from '../types';
-export class CreateActionDto {
-    constructor(){
-        _define_property(this, "name", void 0);
-        _define_property(this, "description", void 0);
-        _define_property(this, "code", void 0);
-        _define_property(this, "actionType", void 0);
-        _define_property(this, "permissionLogic", void 0);
-        _define_property(this, "parentId", void 0);
-        _define_property(this, "serial", void 0);
-        _define_property(this, "isActive", void 0);
-    }
-}
-_ts_decorate([
-    ApiProperty({
-        description: 'Action name',
-        example: 'View Users'
-    }),
-    IsString(),
-    IsNotEmpty(),
-    MaxLength(255),
-    _ts_metadata("design:type", String)
-], CreateActionDto.prototype, "name", void 0);
-_ts_decorate([
-    ApiProperty({
-        description: 'Action description',
-        example: 'Permission to view user list',
-        required: false
-    }),
-    IsString(),
-    IsOptional(),
-    MaxLength(500),
-    _ts_metadata("design:type", String)
-], CreateActionDto.prototype, "description", void 0);
-_ts_decorate([
-    ApiProperty({
-        description: 'Unique code for programmatic reference',
-        example: 'user.view',
-        required: false
-    }),
-    IsString(),
-    IsOptional(),
-    MaxLength(255),
-    _ts_metadata("design:type", String)
-], CreateActionDto.prototype, "code", void 0);
-_ts_decorate([
-    ApiProperty({
-        description: 'Action type (backend for API endpoints, frontend for UI features)',
-        enum: ActionType,
-        example: ActionType.BACKEND,
-        default: ActionType.BACKEND,
-        required: false
-    }),
-    IsEnum(ActionType),
-    IsOptional(),
-    _ts_metadata("design:type", typeof ActionType === "undefined" ? Object : ActionType)
-], CreateActionDto.prototype, "actionType", void 0);
-_ts_decorate([
-    ApiProperty({
-        description: 'Permission logic (AND/OR rules)',
-        required: false
-    }),
-    IsOptional(),
-    _ts_metadata("design:type", typeof LogicNode === "undefined" ? Object : LogicNode)
-], CreateActionDto.prototype, "permissionLogic", void 0);
-_ts_decorate([
-    ApiProperty({
-        description: 'Parent action ID for hierarchy',
-        example: '123e4567-e89b-12d3-a456-426614174000',
-        required: false
-    }),
-    IsUUID(),
-    IsOptional(),
-    _ts_metadata("design:type", String)
-], CreateActionDto.prototype, "parentId", void 0);
-_ts_decorate([
-    ApiProperty({
-        description: 'Display order',
-        required: false
-    }),
-    IsInt(),
-    IsOptional(),
-    _ts_metadata("design:type", Number)
-], CreateActionDto.prototype, "serial", void 0);
-_ts_decorate([
-    ApiProperty({
-        description: 'Active status',
-        default: true,
-        required: false
-    }),
-    IsBoolean(),
-    IsOptional(),
-    _ts_metadata("design:type", Boolean)
-], CreateActionDto.prototype, "isActive", void 0);
-export class UpdateActionDto extends PartialType(CreateActionDto) {
-    constructor(...args){
-        super(...args), _define_property(this, "id", void 0);
-    }
-}
-_ts_decorate([
-    ApiProperty({
-        description: 'Action ID',
-        example: '123e4567-e89b-12d3-a456-426614174000'
-    }),
-    IsUUID(),
-    IsNotEmpty(),
-    _ts_metadata("design:type", String)
-], UpdateActionDto.prototype, "id", void 0);
-export class ActionResponseDto extends IdentityResponseDto {
-    constructor(...args){
-        super(...args), _define_property(this, "readOnly", void 0), _define_property(this, "name", void 0), _define_property(this, "description", void 0), _define_property(this, "code", void 0), _define_property(this, "actionType", void 0), _define_property(this, "permissionLogic", void 0), _define_property(this, "parentId", void 0), _define_property(this, "serial", void 0), _define_property(this, "isActive", void 0);
-    }
-}
-_ts_decorate([
-    Expose(),
-    ApiProperty(),
-    _ts_metadata("design:type", Boolean)
-], ActionResponseDto.prototype, "readOnly", void 0);
-_ts_decorate([
-    Expose(),
-    ApiProperty(),
-    _ts_metadata("design:type", String)
-], ActionResponseDto.prototype, "name", void 0);
-_ts_decorate([
-    Expose(),
-    ApiProperty(),
-    _ts_metadata("design:type", Object)
-], ActionResponseDto.prototype, "description", void 0);
-_ts_decorate([
-    Expose(),
-    ApiProperty(),
-    _ts_metadata("design:type", Object)
-], ActionResponseDto.prototype, "code", void 0);
-_ts_decorate([
-    Expose(),
-    ApiProperty({
-        enum: ActionType
-    }),
-    _ts_metadata("design:type", typeof ActionType === "undefined" ? Object : ActionType)
-], ActionResponseDto.prototype, "actionType", void 0);
-_ts_decorate([
-    Expose(),
-    ApiProperty(),
-    _ts_metadata("design:type", Object)
-], ActionResponseDto.prototype, "permissionLogic", void 0);
-_ts_decorate([
-    Expose(),
-    ApiProperty(),
-    _ts_metadata("design:type", Object)
-], ActionResponseDto.prototype, "parentId", void 0);
-_ts_decorate([
-    Expose(),
-    ApiProperty(),
-    _ts_metadata("design:type", Object)
-], ActionResponseDto.prototype, "serial", void 0);
-_ts_decorate([
-    Expose(),
-    ApiProperty(),
-    _ts_metadata("design:type", Boolean)
-], ActionResponseDto.prototype, "isActive", void 0);
-export class ActionTreeDto extends ActionResponseDto {
-    constructor(...args){
-        super(...args), _define_property(this, "children", void 0);
-    }
-}
-_ts_decorate([
-    Expose(),
-    ApiProperty({
-        type: ()=>[
-                ActionTreeDto
-            ]
-    }),
-    _ts_metadata("design:type", Array)
-], ActionTreeDto.prototype, "children", void 0);
-export class ActionTreeForPermissionDto {
-    constructor(){
-        _define_property(this, "companyId", void 0);
-    }
-}
-_ts_decorate([
-    ApiProperty({
-        description: 'Company to scope the action whitelist to. Defaults to the current user session company when omitted.',
-        required: false
-    }),
-    IsUUID(),
-    IsOptional(),
-    _ts_metadata("design:type", String)
-], ActionTreeForPermissionDto.prototype, "companyId", void 0);
-export class ActionTreeQueryDto {
-    constructor(){
-        _define_property(this, "search", void 0);
-        _define_property(this, "isActive", void 0);
-        _define_property(this, "withDeleted", void 0);
-    }
-}
-_ts_decorate([
-    ApiProperty({
-        description: 'Search by name or code',
-        example: 'user',
-        required: false
-    }),
-    IsString(),
-    IsOptional(),
-    _ts_metadata("design:type", String)
-], ActionTreeQueryDto.prototype, "search", void 0);
-_ts_decorate([
-    ApiProperty({
-        description: 'Filter by active status',
-        example: true,
-        required: false
-    }),
-    IsBoolean(),
-    IsOptional(),
-    _ts_metadata("design:type", Boolean)
-], ActionTreeQueryDto.prototype, "isActive", void 0);
-_ts_decorate([
-    ApiProperty({
-        description: 'Include deleted actions',
-        default: false,
-        required: false
-    }),
-    IsBoolean(),
-    IsOptional(),
-    _ts_metadata("design:type", Boolean)
-], ActionTreeQueryDto.prototype, "withDeleted", void 0);