@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/base-classes/services/controllers/abstract-controller.backend.service.js

@@ -0,0 +1,280 @@
+var __decorate = (this && this.__decorate) || function (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;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import 'reflect-metadata';
+import { injectable, inject } from 'inversify';
+import { Router } from 'express';
+import { LoggerService } from '../../../monitoring/logger/services/logger.service.js';
+import { ErrorBuilderBackendService } from '../../../errors/services/error-builder.backend.service.js';
+import { ErrorHandlerService } from '../../../errors/services/error-handler.backend.service.js';
+import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
+/**
+ * Abstract Controller Backend Service
+ *
+ * Base class for implementing custom controllers that can be registered
+ * with the HTTP server. Provides common functionality for route setup,
+ * logging, error handling, and Express router management.
+ *
+ * Features:
+ * - Abstract route setup pattern
+ * - Integrated logging with debug support
+ * - Express router management
+ * - Unified error handling with ErrorBuilderBackendService
+ * - Express error handler middleware integration
+ * - Async route handler utilities
+ * - Request/response utilities
+ *
+ * Usage:
+ * ```typescript
+ * @injectable()
+ * export class MyCustomController extends AbstractControllerBackendService {
+ *   constructor(
+ *     @inject(SAAS_SERVICE_TYPES.Logger) logger: LoggerService,
+ *     @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) errorBuilder: ErrorBuilderBackendService,
+ *     @inject(SAAS_SERVICE_TYPES.ErrorHandlerService) errorHandler: ErrorHandlerService,
+ *     // ... other dependencies
+ *   ) {
+ *     super(logger, errorBuilder, errorHandler, 'MyCustomController');
+ *   }
+ *
+ *   protected setupRoutes(): void {
+ *     this.router.get('/my-route', this.asyncHandler(this.handleMyRoute.bind(this)));
+ *   }
+ *
+ *   private async handleMyRoute(req: Request, res: Response, next: NextFunction) {
+ *     // Route implementation
+ *   }
+ * }
+ * ```
+ */
+let AbstractControllerBackendService = class AbstractControllerBackendService {
+    router;
+    logger;
+    errorBuilder;
+    errorHandler;
+    logDebug;
+    controllerName;
+    constructor(logger, errorBuilder, errorHandler, controllerName) {
+        this.logger = logger;
+        this.errorBuilder = errorBuilder;
+        this.errorHandler = errorHandler;
+        this.controllerName = controllerName;
+        this.router = Router();
+        this.logDebug = this.logger.debugByType(controllerName);
+        // Enable debug logging for custom controllers
+        this.logger.setDebugTypeLogging(controllerName, false);
+        this.logDebug('Custom controller initialized', {
+            controllerName
+        });
+        // Setup routes after construction
+        this.setupRoutes();
+        // Apply unified error handler middleware after all routes
+        this.router.use(this.errorHandler.expressErrorHandler());
+        this.logDebug('Custom controller initialized with unified error handler', {
+            controllerName
+        });
+    }
+    /**
+     * Get the Express router with all configured routes
+     */
+    getRouter() {
+        return this.router;
+    }
+    /**
+     * Get the controller name
+     */
+    getControllerName() {
+        return this.controllerName;
+    }
+    /**
+     * Indicates whether this controller handles streaming requests.
+     *
+     * Streaming controllers are mounted BEFORE body parsing middleware,
+     * so their routes receive the raw request stream (req is a Readable).
+     * This enables true streaming uploads without memory buffering.
+     *
+     * Override to return `true` for controllers that need raw stream access.
+     *
+     * @returns true if controller handles streaming requests (default: false)
+     *
+     * @example
+     * ```typescript
+     * public isStreamingController(): boolean {
+     *   return true;  // All routes in this controller receive raw streams
+     * }
+     * ```
+     */
+    isStreamingController() {
+        return false;
+    }
+    /**
+     * Utility method to send successful JSON response
+     *
+     * Note: When parsing API responses (from axios/HTTP calls) that contain date fields,
+     * use ResourcesConfigOperationsDtosBuilderUtils.createApiParsingSchema() to transform
+     * database schemas (with z.date()) to API parsing schemas (with z.coerce.date()).
+     * This ensures date strings from JSON are properly coerced to Date objects.
+     *
+     * Example:
+     * ```typescript
+     * const apiSchema = ResourcesConfigOperationsDtosBuilderUtils.createApiParsingSchema(MySchema);
+     * const parsed = apiSchema.parse(response.data);
+     * ```
+     */
+    jsonSuccess(res, data, statusCode = 200) {
+        res.status(statusCode).json(data);
+    }
+    /**
+     * Utility method to handle errors using unified WildoError system.
+     *
+     * If `next` is provided as the third argument, the built `WildoError_Backend`
+     * will be forwarded to the Express error middleware. Otherwise, a unified
+     * error response will be sent immediately.
+     */
+    jsonError(res, error, nextOrStatus) {
+        const maybeNext = typeof nextOrStatus === 'function' ? nextOrStatus : undefined;
+        // Normalize to WildoError_Backend
+        let wildoError;
+        const isAlreadyWildoError = (err) => !!err && typeof err === 'object' && 'statusCode' in err && 'type' in err;
+        if (isAlreadyWildoError(error)) {
+            wildoError = error;
+        }
+        else if (typeof error === 'string') {
+            wildoError = this.errorBuilder.buildFromStandardError(new Error(error));
+        }
+        else {
+            wildoError = this.errorBuilder.buildFromStandardError(error);
+        }
+        this.logger.error('Controller error', {
+            controller: this.controllerName,
+            error: wildoError.message ?? undefined,
+            type: wildoError.type,
+            statusCode: wildoError.statusCode,
+        });
+        // Prefer delegating to the centralized error middleware if available
+        if (maybeNext) {
+            return maybeNext(wildoError);
+        }
+        // Fallback: send a unified error response directly
+        const response = {
+            error: {
+                type: wildoError.type,
+                severity: wildoError.severity,
+                message: wildoError.customMessageReference,
+                customMessage: wildoError.customMessageReference,
+                operationPath: wildoError.operationPathKey,
+                timestamp: wildoError.timestamp.toISOString(),
+                initiatorIds: wildoError.initiatorIds,
+                ...(wildoError.context && { details: wildoError.context }),
+            },
+        };
+        res.status(wildoError.statusCode).json(response);
+    }
+    /**
+     * Utility method to create async route handler with error catching
+     */
+    asyncHandler(handler) {
+        return async (req, res, next) => {
+            try {
+                await handler(req, res, next);
+            }
+            catch (error) {
+                this.handleAsyncError(error, req, res, next);
+            }
+        };
+    }
+    /**
+     * Handle async errors in route handlers
+     */
+    handleAsyncError(error, req, res, next) {
+        // Check if error is already a WildoError_Backend
+        const isAlreadyWildoError = (err) => !!err && typeof err === 'object' && 'statusCode' in err && 'type' in err;
+        let wildoError;
+        let errorMessage;
+        if (isAlreadyWildoError(error)) {
+            wildoError = error;
+            errorMessage = error.customMessageReference || 'WildoError';
+        }
+        else {
+            const standardError = error instanceof Error ? error : new Error(this.serializeError(error));
+            wildoError = this.errorBuilder.buildFromStandardError(standardError);
+            errorMessage = standardError.message;
+        }
+        this.logger.error('Async route handler error', {
+            controller: this.controllerName,
+            method: req.method,
+            path: req.path,
+            error: errorMessage,
+            stack: wildoError.stack,
+        });
+        // Pass WildoError to unified Express error handler middleware
+        next(wildoError);
+    }
+    /**
+     * Serialize error objects to meaningful string representations
+     */
+    serializeError(error) {
+        if (error === null)
+            return 'null';
+        if (error === undefined)
+            return 'undefined';
+        if (typeof error === 'string')
+            return error;
+        if (typeof error === 'number' || typeof error === 'boolean')
+            return String(error);
+        // Handle objects (including arrays)
+        if (typeof error === 'object') {
+            try {
+                return JSON.stringify(error, null, 2);
+            }
+            catch (jsonError) {
+                // Fallback for circular references or non-serializable objects
+                return `[Object: ${Object.prototype.toString.call(error)}]`;
+            }
+        }
+        return String(error);
+    }
+    /**
+     * Get route information for debugging
+     */
+    getRouteInfo() {
+        // Note: Express doesn't provide a direct way to enumerate routes,
+        // so this would need to be tracked manually if needed
+        return {
+            controllerName: this.controllerName,
+            routeCount: 0, // Would need manual tracking
+            routes: [] // Would need manual tracking
+        };
+    }
+    /**
+     * Log route registration for debugging
+     */
+    logRouteRegistration(method, path, description) {
+        this.logDebug('Route registered', {
+            method: method.toUpperCase(),
+            path,
+            description,
+            controller: this.controllerName
+        });
+    }
+};
+AbstractControllerBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __param(2, inject(SAAS_SERVICE_TYPES.ErrorHandlerService)),
+    __metadata("design:paramtypes", [LoggerService,
+        ErrorBuilderBackendService,
+        ErrorHandlerService, String])
+], AbstractControllerBackendService);
+export { AbstractControllerBackendService };
+//# sourceMappingURL=abstract-controller.backend.service.js.map

package/dist/esm/base-classes/services/controllers/abstract-controller.backend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-controller.backend.service.js","sourceRoot":"","sources":["../../../../../src/base-classes/services/controllers/abstract-controller.backend.service.ts"],"names":[],"mappings":"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"}

package/dist/esm/base-classes/services/controllers/controller-resource.backend.service.d.ts

@@ -0,0 +1,147 @@
+import 'reflect-metadata';
+import { Router } from 'express';
+import { z } from 'zod';
+import type { ResourceType, ResourceConfiguration_Operation_UrlInitiatorInfo } from '@wildo-ai/saas-models';
+import { EnumLikeType } from '@wildo-ai/zod-decorators';
+import { CoreResourceOperation } from '@wildo-ai/saas-models';
+import { LoggerService } from '../../../monitoring/logger/services/logger.service.js';
+import { ServicesRegistryHandlerBackendService } from '../../../base-classes/services/services/services-registry-handler.backend.service.js';
+import { RepositoriesRegistryHandlerBackendService } from '../../../base-classes/services/repositories/repositories-registry-handler.backend.service.js';
+import { ErrorBuilderBackendService } from '../../../errors/services/error-builder.backend.service.js';
+import { ErrorHandlerService } from '../../../errors/services/error-handler.backend.service.js';
+import { JwtBackendService } from '../../../security/jwt/services/jwt.backend.service.js';
+import { AuthorizationsBackendService } from '../../../security/authorizations/services/authorizations.backend.service.js';
+import { ExecutionContextCreatorBackendService } from '../../../runtime/services/execution-context-creator.backend.service.js';
+import { ResourceFileUploadHandlerBackendService } from '../../../files/handlers/resource-file-upload-handler.backend.service.js';
+import { FileFieldDetectionBackendService } from '../../../files/services/file-field-detection.backend.service.js';
+import { ResourcesRegistryBackendService } from '../../../resources/services/resources-registry.backend.service.js';
+import { ExecutionContextHandlerBackendService } from '../../../runtime/services/execution-context-handler.backend.service.js';
+import { ResourceOperationHelperBackendService } from '../../../base-classes/services/resource-operations-helper.backend.service.js';
+import { AuditLogsBackendService } from '../../../compliance/audit-trails/services/audit-logs.backend.service.js';
+import { AnonymousSessionBackendService } from '../../../security/authentications/services/anonymous-session.backend.service.js';
+import { AppConfigurationService } from '../../../config/services/app-configuration.backend.service.js';
+export declare function shouldSkipImplicitRequestValidation(effectiveOperation: string, hasExplicitRequestDto: boolean): boolean;
+export declare function shouldAuthorizeCollectionOperation(effectiveOperation: string): boolean;
+export declare function isContextAddressedReadOperation(effectiveOperation: string, resourceFieldIdentifier: string, initiatorInfo: Pick<ResourceConfiguration_Operation_UrlInitiatorInfo, 'parameters'>, matchedParameterFieldIdentifiers?: string[]): boolean;
+export declare class ControllerResourceBackendService<TCustomOperationEnum extends EnumLikeType | undefined = undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined, TMainSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+    private readonly logger;
+    private readonly errorBuilder;
+    private readonly errorHandler;
+    private readonly jwtService;
+    private readonly authorizationsService;
+    private readonly resourcesRegistry;
+    private readonly executionContextCreator;
+    private readonly executionContextHandler;
+    private readonly repositoriesRegistry;
+    private readonly resourceOperationHelper;
+    private readonly servicesRegistry;
+    private readonly fileFieldDetection;
+    private readonly fileUploadHandler;
+    private readonly auditLogsService;
+    private readonly anonymousSessionService;
+    private readonly appConfigService;
+    private readonly resourceConfiguration;
+    private readonly operationsMap;
+    private readonly router;
+    protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+    constructor(resourceType: ResourceType, logger: LoggerService, errorBuilder: ErrorBuilderBackendService, errorHandler: ErrorHandlerService, jwtService: JwtBackendService, authorizationsService: AuthorizationsBackendService, resourcesRegistry: ResourcesRegistryBackendService, executionContextCreator: ExecutionContextCreatorBackendService, executionContextHandler: ExecutionContextHandlerBackendService, repositoriesRegistry: RepositoriesRegistryHandlerBackendService, resourceOperationHelper: ResourceOperationHelperBackendService, servicesRegistry: ServicesRegistryHandlerBackendService, fileFieldDetection: FileFieldDetectionBackendService, fileUploadHandler: ResourceFileUploadHandlerBackendService, auditLogsService: AuditLogsBackendService, anonymousSessionService: AnonymousSessionBackendService, appConfigService: AppConfigurationService);
+    getRouter(): Router;
+    static createInstance<TCustomOperationEnum extends EnumLikeType | undefined = undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined, TMainSchema extends z.ZodTypeAny = z.ZodTypeAny>(resourceType: ResourceType, logger: LoggerService, errorBuilder: ErrorBuilderBackendService, errorHandler: ErrorHandlerService, jwtService: JwtBackendService, authorizationsService: AuthorizationsBackendService, resourcesRegistry: ResourcesRegistryBackendService, executionContextCreator: ExecutionContextCreatorBackendService, executionContextHandler: ExecutionContextHandlerBackendService, repositoriesRegistry: RepositoriesRegistryHandlerBackendService, resourceOperationHelper: ResourceOperationHelperBackendService, servicesRegistry: ServicesRegistryHandlerBackendService, fileFieldDetection: FileFieldDetectionBackendService, fileUploadHandler: ResourceFileUploadHandlerBackendService, auditLogsService: AuditLogsBackendService, anonymousSessionService: AnonymousSessionBackendService, appConfigService: AppConfigurationService): ControllerResourceBackendService<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>;
+    private initializeOperationsMap;
+    private initializeRoutes;
+    /**
+     * Initialize file upload routes for resources with file fields.
+     * Creates routes:
+     * - POST /api/v1/.../resourceType/files/:fieldName (CREATE)
+     * - POST /api/v1/.../resourceType/:resourceId/files/:fieldName (UPDATE)
+     */
+    /**
+     * L12 Audit (Phase I):
+     * - Authorization: registered upload routes now build the execution context and
+     *   perform `authorizeInController()` before Multer and before the async upload
+     *   handler runs, so unauthorized requests are rejected before temp-disk writes,
+     *   storage upload, or DB write.
+     * - Parent resource params: `initiatorInfo.parameters` is correctly passed to the execution context
+     *   creator, ensuring parent resource FK authorization matches non-file routes.
+     * - Multer errors: Request-body parsing failures still flow through the unified
+     *   error handler, and request-size violations are classified as validation
+     *   errors rather than generic internal failures.
+     * - Route order: the controller-specific authorization middleware runs before
+     *   Multer for registered upload routes, so unauthenticated callers are
+     *   rejected before temp-disk parsing starts. Multer still runs before the
+     *   async upload handler itself, which is why file-type/size failures surface
+     *   as middleware-layer errors rather than handler exceptions.
+     */
+    private initializeFileUploadRoutes;
+    /**
+     * Authorize file uploads before Multer touches request bodies.
+     *
+     * Resource upload routes are intentionally protected at the same semantic
+     * execution-context layer as the actual upload handler. Running that auth step
+     * first avoids unauthenticated callers forcing temp-disk writes through Multer
+     * while still reusing the exact same execution context for the later upload.
+     */
+    private createFileUploadAuthorizationMiddleware;
+    /**
+     * Initialize validate-field routes for resources with unique fields.
+     * Delegates to the validate-field handler module.
+     *
+     * Creates route: POST /api/v1/.../:resourceType/validate-field
+     * Authorization uses CREATE operation rights (collection-level).
+     */
+    private initializeValidateFieldRoutes;
+    /**
+     * Async handler wrapper for Express route handlers.
+     * Ensures errors are properly passed to Express error handler.
+     */
+    private asyncHandler;
+    private createRouteForOperation;
+    private convertUrlPatternToExpressPath;
+    private doOperation;
+    private enrichVersionConflictError;
+    private buildVersionConflictDetails;
+    private shapeCanonicalConflictCurrentValues;
+    private resolveCanonicalConflictReadOperation;
+    private normalizeCollectionQueryRequestData;
+    private buildCollectionQueryRequestDtoInput;
+    private validateRequestData;
+    /**
+     * Phase 3.7: Extract DataMode from execution context or query parameters.
+     * DataMode determines which DTO variant to use (SUMMARY, CONTEXT, or RAW).
+     *
+     * Priority:
+     * 1. Query parameter `dataMode` (if provided)
+     * 2. Operation variantKey (set at factory time)
+     * 3. Default to RAW (responseDto)
+     */
+    private extractDataMode;
+    private resolveExecutionContextForAuthorization;
+    private resolveOperationForAuthorizationDataMode;
+    /**
+     * Phase 3.7: Select the appropriate response DTO based on DataMode.
+     * Uses structure-aware utility method that handles LIST/SEARCH pagination wrappers.
+     *
+     * - Variant operations: Uses `responseDto` (already variant-specific)
+     * - SUMMARY mode: Uses `summaryDto` (wrapped in pagination for LIST/SEARCH)
+     * - CONTEXT mode: Uses `contextDto` (wrapped in pagination for LIST/SEARCH)
+     * - RAW mode: Uses `responseDto` (default)
+     */
+    private selectResponseDto;
+    private sendResponse;
+    /**
+     * Phase 3.10 + Q4: Log audit access for sensitive backend-only fields.
+     * Two independent triggers:
+     * - CREATE operations: fields with `isReturnedAtCreation: true` (Phase 3.10)
+     * - Any operation: fields with `auditAccess: true` (Q4)
+     *
+     * @param operation - The operation being executed
+     * @param executionContext - Execution context with initiator information
+     * @param responseData - The validated response data (may be array or single object)
+     * @param originalResult - The original result before validation (to get _id for CREATE operations)
+     * @param selectedDto - The selected response DTO schema that was used for validation
+     */
+    private logAuditAccessForFields;
+    private getHttpMethodForOperation;
+    private getStatusCodeForOperation;
+}
+//# sourceMappingURL=controller-resource.backend.service.d.ts.map

package/dist/esm/base-classes/services/controllers/controller-resource.backend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller-resource.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/base-classes/services/controllers/controller-resource.backend.service.ts"],"names":[],"mappings":"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"}