@flusys/nestjs-shared 1.1.0-beta → 1.2.0-rc.1

package/fesm/classes/api-controller.class.js

@@ -25,14 +25,16 @@ function _ts_param(paramIndex, decorator) {
         decorator(target, key, paramIndex);
     };
 }
-import { CurrentUser, Public, RequirePermission, RequireAnyPermission, RequirePermissionCondition } from '@flusys/nestjs-shared/decorators';
-import { DeleteDto, FilterAndPaginationDto, GetByIdBodyDto } from '@flusys/nestjs-shared/dtos';
-import { JwtAuthGuard, PermissionGuard } from '@flusys/nestjs-shared/guards';
-import { IdempotencyInterceptor, SetCreatedByOnBody, SetDeletedByOnBody, SetUpdateByOnBody, Slug } from '@flusys/nestjs-shared/interceptors';
 import { applyDecorators, Body, HttpCode, HttpStatus, Param, Post, Query, UseGuards, UseInterceptors, Version, VERSION_NEUTRAL } from '@nestjs/common';
-import { ApiBearerAuth, ApiBody, ApiHeader, ApiOperation, ApiParam, ApiQuery, ApiResponse } from '@nestjs/swagger';
+import { ApiBearerAuth, ApiBody, ApiExcludeEndpoint, ApiHeader, ApiOperation, ApiParam, ApiQuery, ApiResponse } from '@nestjs/swagger';
 import { plainToInstance } from 'class-transformer';
+import { ERROR_MESSAGES } from '../constants/message-keys';
+import { CurrentUser, Public, RequireAnyPermission, RequirePermission, RequirePermissionLogic } from '../decorators';
 import { ApiResponseDto } from '../decorators/api-response.decorator';
+import { DeleteDto, FilterAndPaginationDto, GetByIdBodyDto, GetByIdsDto } from '../dtos';
+import { BaseAppException, NotFoundException } from '../exceptions';
+import { JwtAuthGuard, PermissionGuard } from '../guards';
+import { IdempotencyInterceptor, SetCreatedByOnBody, SetDeletedByOnBody, SetUpdateByOnBody, Slug } from '../interceptors';
 /**
  * Helper to normalize security config
  */ function normalizeSecurity(config) {
@@ -44,6 +46,24 @@ import { ApiResponseDto } from '../decorators/api-response.decorator';
     };
     return config;
 }
+/**
+ * Helper to check if endpoint is enabled
+ */ function isEndpointEnabled(endpoint, enabledEndpoints) {
+    if (!enabledEndpoints || enabledEndpoints === 'all') return true;
+    return enabledEndpoints.includes(endpoint);
+}
+/**
+ * Helper to conditionally exclude endpoint from Swagger if disabled
+ */ function createEndpointDecorators(security, endpoint, enabledEndpoints) {
+    const decorators = [];
+    // Add security decorators
+    decorators.push(createSecurityDecorators(security));
+    // Exclude from Swagger if endpoint is disabled
+    if (!isEndpointEnabled(endpoint, enabledEndpoints)) {
+        decorators.push(ApiExcludeEndpoint());
+    }
+    return applyDecorators(...decorators);
+}
 /**
  * Creates security decorators based on configuration
  */ function createSecurityDecorators(security) {
@@ -62,11 +82,11 @@ import { ApiResponseDto } from '../decorators/api-response.decorator';
             // Apply PermissionGuard to check permissions from cache
             decorators.push(UseGuards(JwtAuthGuard, PermissionGuard));
             decorators.push(ApiBearerAuth());
-            // Check for complex nested condition first
-            if (security.condition) {
-                decorators.push(RequirePermissionCondition(security.condition));
+            // Check for complex logic first
+            if (security.logic) {
+                decorators.push(RequirePermissionLogic(security.logic));
             } else if (security.permissions && security.permissions.length > 0) {
-                if (security.operator === 'or') {
+                if (security.operator === 'OR') {
                     decorators.push(RequireAnyPermission(...security.permissions));
                 } else {
                     // AND is default and most secure
@@ -78,13 +98,24 @@ import { ApiResponseDto } from '../decorators/api-response.decorator';
     return applyDecorators(...decorators);
 }
 /** Creates an API Controller with standardized CRUD endpoints (POST-only RPC pattern) */ export function createApiController(createDtoClass, updateDtoClass, responseDtoClass, options = {}) {
+    const excludeExtraneousValues = options.excludeExtraneousValues ?? true;
+    function toDto(cls, input) {
+        return plainToInstance(cls, input, {
+            excludeExtraneousValues
+        });
+    }
+    // Entity name for message keys (defaults to 'item')
+    const entityName = options.entityName ?? 'item';
     // Determine if security is global (applies to all) or per-endpoint
     const securityConfig = options.security;
     const endpointKeys = [
         'insert',
         'insertMany',
         'getById',
+        'getByIds',
         'getAll',
+        'bulkUpsert',
+        'getByFilter',
         'update',
         'updateMany',
         'delete'
@@ -94,34 +125,68 @@ import { ApiResponseDto } from '../decorators/api-response.decorator';
     // 2. It's an object with 'level' property but no endpoint keys
     const isGlobalSecurity = typeof securityConfig === 'string' || securityConfig && typeof securityConfig === 'object' && 'level' in securityConfig && !endpointKeys.some((key)=>key in securityConfig);
     // Normalize security config for each endpoint
+    // IMPORTANT: When per-endpoint security is specified, default to 'jwt' for unconfigured endpoints
+    // to prevent accidentally exposing endpoints without authentication
     const defaultSecurity = isGlobalSecurity ? normalizeSecurity(securityConfig) : {
-        level: 'public'
+        level: 'jwt'
     };
     const security = {
         insert: isGlobalSecurity ? defaultSecurity : normalizeSecurity(securityConfig?.insert),
         insertMany: isGlobalSecurity ? defaultSecurity : normalizeSecurity(securityConfig?.insertMany),
         getById: isGlobalSecurity ? defaultSecurity : normalizeSecurity(securityConfig?.getById),
+        getByIds: isGlobalSecurity ? defaultSecurity : normalizeSecurity(securityConfig?.getByIds),
         getAll: isGlobalSecurity ? defaultSecurity : normalizeSecurity(securityConfig?.getAll),
+        getByFilter: isGlobalSecurity ? defaultSecurity : normalizeSecurity(securityConfig?.getByFilter),
+        bulkUpsert: isGlobalSecurity ? defaultSecurity : normalizeSecurity(securityConfig?.bulkUpsert),
         update: isGlobalSecurity ? defaultSecurity : normalizeSecurity(securityConfig?.update),
         updateMany: isGlobalSecurity ? defaultSecurity : normalizeSecurity(securityConfig?.updateMany),
         delete: isGlobalSecurity ? defaultSecurity : normalizeSecurity(securityConfig?.delete)
     };
     let ApiController = class ApiController {
+        isEnabled(endpoint) {
+            if (this.enabledEndpoints === 'all') return true;
+            return Array.isArray(this.enabledEndpoints) && this.enabledEndpoints.includes(endpoint);
+        }
         async insert(addDto, user) {
+            if (!this.isEnabled('insert')) {
+                throw new BaseAppException({
+                    message: `Endpoint 'insert' is disabled`,
+                    messageKey: ERROR_MESSAGES.ENDPOINT_DISABLED,
+                    messageVariables: {
+                        endpoint: 'insert'
+                    },
+                    status: HttpStatus.FORBIDDEN
+                });
+            }
             const entity = await this.service.insert(addDto, user);
-            const data = plainToInstance(responseDtoClass, entity);
+            const data = toDto(responseDtoClass, entity);
             return {
                 success: true,
-                message: 'Item created successfully',
+                message: `${entityName.charAt(0).toUpperCase() + entityName.slice(1)} created successfully`,
+                messageKey: `${entityName}.create.success`,
                 data
             };
         }
         async insertMany(addDto, user) {
+            if (!this.isEnabled('insertMany')) {
+                throw new BaseAppException({
+                    message: `Endpoint 'insertMany' is disabled`,
+                    messageKey: ERROR_MESSAGES.ENDPOINT_DISABLED,
+                    messageVariables: {
+                        endpoint: 'insertMany'
+                    },
+                    status: HttpStatus.FORBIDDEN
+                });
+            }
             const entities = await this.service.insertMany(addDto, user);
-            const data = entities.map((item)=>plainToInstance(responseDtoClass, item));
+            const data = entities.map((item)=>toDto(responseDtoClass, item));
             return {
                 success: true,
-                message: `${data.length} items created successfully`,
+                message: `${data.length} ${entityName}s created successfully`,
+                messageKey: `${entityName}.create.many.success`,
+                messageVariables: {
+                    count: data.length
+                },
                 data,
                 meta: {
                     count: data.length,
@@ -131,29 +196,92 @@ import { ApiResponseDto } from '../decorators/api-response.decorator';
             };
         }
         async getById(id, body, user) {
+            if (!this.isEnabled('getById')) {
+                throw new BaseAppException({
+                    message: `Endpoint 'getById' is disabled`,
+                    messageKey: ERROR_MESSAGES.ENDPOINT_DISABLED,
+                    messageVariables: {
+                        endpoint: 'getById'
+                    },
+                    status: HttpStatus.FORBIDDEN
+                });
+            }
             const entity = await this.service.findById(id, user, body?.select);
-            const data = plainToInstance(responseDtoClass, entity);
+            const data = toDto(responseDtoClass, entity);
             return {
                 success: true,
-                message: 'Item retrieved successfully',
+                message: `${entityName.charAt(0).toUpperCase() + entityName.slice(1)} retrieved successfully`,
+                messageKey: `${entityName}.get.success`,
                 data
             };
         }
+        async getByIds(body, user) {
+            if (!this.isEnabled('getByIds')) {
+                throw new BaseAppException({
+                    message: `Endpoint 'getByIds' is disabled`,
+                    messageKey: ERROR_MESSAGES.ENDPOINT_DISABLED,
+                    messageVariables: {
+                        endpoint: 'getByIds'
+                    },
+                    status: HttpStatus.FORBIDDEN
+                });
+            }
+            const entities = await this.service.findByIds(body.ids, user, body?.select);
+            const data = entities.map((item)=>toDto(responseDtoClass, item));
+            return {
+                success: true,
+                message: `${data.length} ${entityName}${data.length !== 1 ? 's' : ''} retrieved successfully`,
+                messageKey: `${entityName}.get.by.ids.success`,
+                data,
+                meta: {
+                    total: data.length,
+                    page: 0,
+                    pageSize: data.length,
+                    count: data.length,
+                    totalPages: 1
+                }
+            };
+        }
         async update(updateDto, user) {
+            if (!this.isEnabled('update')) {
+                throw new BaseAppException({
+                    message: `Endpoint 'update' is disabled`,
+                    messageKey: ERROR_MESSAGES.ENDPOINT_DISABLED,
+                    messageVariables: {
+                        endpoint: 'update'
+                    },
+                    status: HttpStatus.FORBIDDEN
+                });
+            }
             const entity = await this.service.update(updateDto, user);
-            const data = plainToInstance(responseDtoClass, entity);
+            const data = toDto(responseDtoClass, entity);
             return {
                 success: true,
-                message: 'Item updated successfully',
+                message: `${entityName.charAt(0).toUpperCase() + entityName.slice(1)} updated successfully`,
+                messageKey: `${entityName}.update.success`,
                 data
             };
         }
         async updateMany(updateDtos, user) {
+            if (!this.isEnabled('updateMany')) {
+                throw new BaseAppException({
+                    message: `Endpoint 'updateMany' is disabled`,
+                    messageKey: ERROR_MESSAGES.ENDPOINT_DISABLED,
+                    messageVariables: {
+                        endpoint: 'updateMany'
+                    },
+                    status: HttpStatus.FORBIDDEN
+                });
+            }
             const entities = await this.service.updateMany(updateDtos, user);
-            const data = plainToInstance(responseDtoClass, entities);
+            const data = entities.map((item)=>toDto(responseDtoClass, item));
             return {
                 success: true,
-                message: `${data.length} items updated successfully`,
+                message: `${data.length} ${entityName}s updated successfully`,
+                messageKey: `${entityName}.update.many.success`,
+                messageVariables: {
+                    count: data.length
+                },
                 data,
                 meta: {
                     count: data.length,
@@ -162,15 +290,93 @@ import { ApiResponseDto } from '../decorators/api-response.decorator';
                 }
             };
         }
+        async bulkUpsert(dtos, user) {
+            if (!this.isEnabled('bulkUpsert')) {
+                throw new BaseAppException({
+                    message: `Endpoint 'bulkUpsert' is disabled`,
+                    messageKey: ERROR_MESSAGES.ENDPOINT_DISABLED,
+                    messageVariables: {
+                        endpoint: 'bulkUpsert'
+                    },
+                    status: HttpStatus.FORBIDDEN
+                });
+            }
+            const toInsert = [];
+            const toUpdate = [];
+            for (const dto of dtos){
+                if ('id' in dto && dto.id) {
+                    toUpdate.push(dto);
+                } else {
+                    toInsert.push(dto);
+                }
+            }
+            const allEntities = await this.service.bulkUpsert(toInsert, toUpdate, user);
+            const data = allEntities.map((item)=>toDto(responseDtoClass, item));
+            return {
+                success: true,
+                message: `${data.length} ${entityName}s upserted successfully`,
+                messageKey: `${entityName}.upsert.many.success`,
+                messageVariables: {
+                    count: data.length
+                },
+                data,
+                meta: {
+                    count: data.length,
+                    total: dtos.length,
+                    failed: dtos.length - data.length
+                }
+            };
+        }
+        async getByFilter(filter, user) {
+            if (!this.isEnabled('getByFilter')) {
+                throw new BaseAppException({
+                    message: `Endpoint 'getByFilter' is disabled`,
+                    messageKey: ERROR_MESSAGES.ENDPOINT_DISABLED,
+                    messageVariables: {
+                        endpoint: 'getByFilter'
+                    },
+                    status: HttpStatus.FORBIDDEN
+                });
+            }
+            const result = await this.service.getAll('', {
+                filter,
+                pagination: {
+                    currentPage: 0,
+                    pageSize: 1
+                }
+            }, user);
+            if (!result.data || result.data.length === 0) {
+                throw new NotFoundException(entityName);
+            }
+            const entity = result.data[0];
+            const data = toDto(responseDtoClass, entity);
+            return {
+                success: true,
+                message: `${entityName.charAt(0).toUpperCase() + entityName.slice(1)} retrieved successfully`,
+                messageKey: `${entityName}.get.by.filter.success`,
+                data
+            };
+        }
         async getAll(filterAndPaginationDto, user, search) {
+            if (!this.isEnabled('getAll')) {
+                throw new BaseAppException({
+                    message: `Endpoint 'getAll' is disabled`,
+                    messageKey: ERROR_MESSAGES.ENDPOINT_DISABLED,
+                    messageVariables: {
+                        endpoint: 'getAll'
+                    },
+                    status: HttpStatus.FORBIDDEN
+                });
+            }
             const result = await this.service.getAll(search ?? '', filterAndPaginationDto, user);
-            const data = plainToInstance(responseDtoClass, result.data);
+            const data = result.data.map((item)=>toDto(responseDtoClass, item));
             const page = filterAndPaginationDto.pagination?.currentPage ?? 0;
             const pageSize = filterAndPaginationDto.pagination?.pageSize ?? data.length;
             const totalPages = pageSize > 0 ? Math.ceil(result.total / pageSize) : 1;
             return {
                 success: true,
-                message: 'Data retrieved successfully',
+                message: `${entityName.charAt(0).toUpperCase() + entityName.slice(1)}s retrieved successfully`,
+                messageKey: `${entityName}.get.all.success`,
                 data,
                 meta: {
                     total: result.total,
@@ -183,21 +389,37 @@ import { ApiResponseDto } from '../decorators/api-response.decorator';
             };
         }
         async delete(deleteDto, user) {
+            if (!this.isEnabled('delete')) {
+                throw new BaseAppException({
+                    message: `Endpoint 'delete' is disabled`,
+                    messageKey: ERROR_MESSAGES.ENDPOINT_DISABLED,
+                    messageVariables: {
+                        endpoint: 'delete'
+                    },
+                    status: HttpStatus.FORBIDDEN
+                });
+            }
             await this.service.delete(deleteDto, user);
             const count = Array.isArray(deleteDto.id) ? deleteDto.id.length : 1;
-            const action = deleteDto.type === 'restore' ? 'restored' : 'deleted';
+            const action = deleteDto.type === 'restore' ? 'restore' : 'delete';
             return {
                 success: true,
-                message: `${count} item${count > 1 ? 's' : ''} ${action} successfully`
+                message: `${count} ${entityName}${count > 1 ? 's' : ''} ${action}d successfully`,
+                messageKey: `${entityName}.${action}.success`,
+                messageVariables: {
+                    count
+                }
             };
         }
         constructor(service){
             _define_property(this, "service", void 0);
+            _define_property(this, "enabledEndpoints", void 0);
             this.service = service;
+            this.enabledEndpoints = options.enabledEndpoints ?? 'all';
         }
     };
     _ts_decorate([
-        createSecurityDecorators(security.insert),
+        createEndpointDecorators(security.insert, 'insert', options.enabledEndpoints),
         Version(VERSION_NEUTRAL),
         Post('insert'),
         HttpCode(HttpStatus.CREATED),
@@ -225,7 +447,7 @@ import { ApiResponseDto } from '../decorators/api-response.decorator';
         _ts_metadata("design:returntype", Promise)
     ], ApiController.prototype, "insert", null);
     _ts_decorate([
-        createSecurityDecorators(security.insertMany),
+        createEndpointDecorators(security.insertMany, 'insertMany', options.enabledEndpoints),
         Version(VERSION_NEUTRAL),
         Post('insert-many'),
         HttpCode(HttpStatus.CREATED),
@@ -254,7 +476,7 @@ import { ApiResponseDto } from '../decorators/api-response.decorator';
         _ts_metadata("design:returntype", Promise)
     ], ApiController.prototype, "insertMany", null);
     _ts_decorate([
-        createSecurityDecorators(security.getById),
+        createEndpointDecorators(security.getById, 'getById', options.enabledEndpoints),
         Version(VERSION_NEUTRAL),
         Post('get/:id'),
         HttpCode(HttpStatus.OK),
@@ -284,7 +506,29 @@ import { ApiResponseDto } from '../decorators/api-response.decorator';
         _ts_metadata("design:returntype", Promise)
     ], ApiController.prototype, "getById", null);
     _ts_decorate([
-        createSecurityDecorators(security.update),
+        createEndpointDecorators(security.getByIds, 'getByIds', options.enabledEndpoints),
+        Version(VERSION_NEUTRAL),
+        Post('get-by-ids'),
+        HttpCode(HttpStatus.OK),
+        ApiOperation({
+            summary: 'Get items by IDs',
+            description: 'Retrieves multiple items by their IDs. Optionally specify fields to select.'
+        }),
+        ApiBody({
+            type: GetByIdsDto
+        }),
+        ApiResponseDto(responseDtoClass, true, 'list'),
+        _ts_param(0, Body()),
+        _ts_param(1, CurrentUser()),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            typeof GetByIdsDto === "undefined" ? Object : GetByIdsDto,
+            Object
+        ]),
+        _ts_metadata("design:returntype", Promise)
+    ], ApiController.prototype, "getByIds", null);
+    _ts_decorate([
+        createEndpointDecorators(security.update, 'update', options.enabledEndpoints),
         Version(VERSION_NEUTRAL),
         Post('update'),
         HttpCode(HttpStatus.OK),
@@ -307,7 +551,7 @@ import { ApiResponseDto } from '../decorators/api-response.decorator';
         _ts_metadata("design:returntype", Promise)
     ], ApiController.prototype, "update", null);
     _ts_decorate([
-        createSecurityDecorators(security.updateMany),
+        createEndpointDecorators(security.updateMany, 'updateMany', options.enabledEndpoints),
         Version(VERSION_NEUTRAL),
         Post('update-many'),
         HttpCode(HttpStatus.OK),
@@ -331,22 +575,62 @@ import { ApiResponseDto } from '../decorators/api-response.decorator';
         _ts_metadata("design:returntype", Promise)
     ], ApiController.prototype, "updateMany", null);
     _ts_decorate([
-        createSecurityDecorators(security.getAll),
+        createEndpointDecorators(security.bulkUpsert, 'bulkUpsert', options.enabledEndpoints),
+        Version(VERSION_NEUTRAL),
+        Post('bulk-upsert'),
+        HttpCode(HttpStatus.OK),
+        ApiOperation({
+            summary: 'Create or update multiple items',
+            description: 'Bulk upsert: items without ID are created, items with ID are updated.'
+        }),
+        ApiResponseDto(responseDtoClass, true, 'bulk'),
+        ApiBody({
+            type: createDtoClass,
+            isArray: true
+        }),
+        UseInterceptors(SetCreatedByOnBody, SetUpdateByOnBody, Slug),
+        _ts_param(0, Body()),
+        _ts_param(1, CurrentUser()),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            Array,
+            Object
+        ]),
+        _ts_metadata("design:returntype", Promise)
+    ], ApiController.prototype, "bulkUpsert", null);
+    _ts_decorate([
+        createEndpointDecorators(security.getByFilter, 'getByFilter', options.enabledEndpoints),
+        Version(VERSION_NEUTRAL),
+        Post('get-by-filter'),
+        HttpCode(HttpStatus.OK),
+        ApiOperation({
+            summary: 'Get single item by filter',
+            description: 'Retrieves a single item matching the provided filter criteria. Returns first match if multiple exist.'
+        }),
+        ApiBody({
+            schema: {
+                type: 'object',
+                description: 'Filter criteria'
+            }
+        }),
+        ApiResponseDto(responseDtoClass),
+        _ts_param(0, Body()),
+        _ts_param(1, CurrentUser()),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            typeof Record === "undefined" ? Object : Record,
+            Object
+        ]),
+        _ts_metadata("design:returntype", Promise)
+    ], ApiController.prototype, "getByFilter", null);
+    _ts_decorate([
+        createEndpointDecorators(security.getAll, 'getAll', options.enabledEndpoints),
         Version(VERSION_NEUTRAL),
         Post('get-all'),
         HttpCode(HttpStatus.OK),
         ApiOperation({
             summary: 'Get all items with filters and pagination',
-            description: `
-Retrieves items with support for:
-- **filter**: Apply field-based filters (e.g., \`{ "isActive": true }\`)
-- **pagination**: Control page and page size
-- **sort**: Order by any field (e.g., \`{ "createdAt": "DESC" }\`)
-- **select**: Choose specific fields to return
-- **withDeleted**: Include soft-deleted items
-- **extraKey**: Include additional relations
-- **q** (query param): Global text search
-      `
+            description: 'Supports filter, pagination, sort, select, withDeleted, and q (search) params'
         }),
         ApiQuery({
             name: 'q',
@@ -369,21 +653,13 @@ Retrieves items with support for:
         _ts_metadata("design:returntype", Promise)
     ], ApiController.prototype, "getAll", null);
     _ts_decorate([
-        createSecurityDecorators(security.delete),
+        createEndpointDecorators(security.delete, 'delete', options.enabledEndpoints),
         Version(VERSION_NEUTRAL),
         Post('delete'),
         HttpCode(HttpStatus.OK),
         ApiOperation({
             summary: 'Delete, restore, or permanently remove items',
-            description: `
-Performs one of three actions:
-
-- **"delete"** (soft delete): Marks items as deleted but keeps in database
-- **"restore"**: Reverts soft-deleted items to active
-- **"permanent"**: Completely removes items from database
-
-Supports single ID or array of IDs for batch operations.
-      `
+            description: 'Types: delete (soft), restore, permanent. Supports batch IDs.'
         }),
         ApiResponse({
             status: 200,