@wildo-ai/saas-backend-lib 1.0.1

package/src/base-classes/services/resource-operations-helper.backend.service.ts

@@ -0,0 +1,468 @@
+import 'reflect-metadata';
+import { injectable, inject, optional } from 'inversify';
+import { createOrUpdateMandatoryDiscardFields, CoreResourceOperation, ErrorType, ErrorCustomMessageReference, Resources_SharedUtils } from '@wildo-ai/saas-models';
+import { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { IdOrIdsOrFilterType, RepositoryOptions } from '~wildo-backend-lib/base-classes/models/repositories.backend.schemas';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import type { ResourceIdBackendService } from '~wildo-backend-lib/resources/services/resource-id.backend.service';
+import { z } from 'zod';
+import {
+  extractFlattenedPathsFromZodSchema,
+  getZodObjectShape,
+  getZodType,
+  isDiscriminatorField,
+  getZodDefArrayProperty,
+  unwrapSchema
+} from '@wildo-ai/zod-decorators';
+
+/**
+ * Resource Operation Helper Backend Service
+ *
+ * Shared helper service for common repository and service operations.
+ * Contains reusable methods for:
+ * - Execution context ID extraction
+ * - Input data cleaning
+ * - Initiator ID mapping
+ * - Data enrichment with context
+ * - Zod schema analysis and path extraction
+ *
+ * This service is injected into both RepositoryResourceBackendService
+ * and ServicesRegistryHandlerBackendService to eliminate code duplication.
+ */
+@injectable()
+export class ResourceOperationHelperBackendService {
+
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.ResourceIdBackendService) @optional() private readonly resourceIdService?: ResourceIdBackendService
+  ) {
+    this.logDebug = this.logger.debugByType('ResourceOperationHelper');
+    this.logger.setDebugTypeLogging('ResourceOperationHelper', false);
+  }
+
+  /**
+   * Extract IDs from execution context based on resource field identifier
+   * @param executionContext - The execution context containing resource IDs
+   * @param resourceFieldIdentifier - The field identifier to extract IDs for
+   * @returns Extracted IDs as IdOrIdsOrFilterType or undefined if no relevant IDs found
+   */
+  extractIdsFromExecutionContext(executionContext: ExecutionContext<any>, resourceFieldIdentifier: string): IdOrIdsOrFilterType {
+    if (!executionContext || !resourceFieldIdentifier) {
+      return undefined;
+    }
+
+    // Get context resource IDs from execution context
+    const contextResourceIds = executionContext.getContextResourceIds();
+
+    if (!contextResourceIds || contextResourceIds.size === 0) {
+      return undefined;
+    }
+
+    // Look for the specific resource field identifier
+    const resourceId = contextResourceIds.get(resourceFieldIdentifier);
+
+    if (resourceId) {
+      return resourceId;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Get initiator ID from execution context
+   * @param executionContext - The execution context
+   * @param initiatorType - Type of initiator to extract ('user', 'organization', 'application')
+   * @returns The initiator ID or undefined if not found
+   */
+  getInitiatorId(executionContext: ExecutionContext<any>, initiatorType: 'user' | 'organization' | 'application'): string | undefined {
+    const initiatorIds = executionContext.initiatorIds;
+
+    if (!initiatorIds) {
+      return undefined;
+    }
+
+    switch (initiatorType) {
+      case 'user':
+        return initiatorIds.userId;
+      case 'organization':
+        return initiatorIds.organizationId;
+      case 'application':
+        return initiatorIds.applicationId;
+      default:
+        return undefined;
+    }
+  }
+
+  /**
+   * Clean input data by removing mandatory discard fields
+   * @param data - The data to clean
+   * @param operation - The operation being performed (affects which fields to keep/discard)
+   * @returns Cleaned data with discard fields removed
+   */
+  cleanInputData(data: any, operation?: CoreResourceOperation): any {
+    if (!data || typeof data !== 'object') {
+      return data;
+    }
+
+    // Create a copy to avoid mutating the original
+    const cleanedData = { ...data };
+
+    // Remove mandatory discard fields
+    createOrUpdateMandatoryDiscardFields.forEach(field => {
+      if (operation === CoreResourceOperation.UPDATE_MANY && field === '_id') {
+        return; // Skip removing _id for updateMany
+      }
+      delete cleanedData[field];
+    });
+
+    this.logDebug('Data cleaned', {
+      operation,
+      originalKeys: Object.keys(data),
+      cleanedKeys: Object.keys(cleanedData),
+      removedFields: createOrUpdateMandatoryDiscardFields.filter(field =>
+        !(operation === CoreResourceOperation.UPDATE_MANY && field === '_id')
+      )
+    });
+
+    return cleanedData;
+  }
+
+  /**
+   * Cleans array of input data by removing mandatory discard fields
+   * @param dataArray - The array of data to clean
+   * @param operation - The operation being performed (affects which fields to keep/discard)
+   * @returns Cleaned array with discard fields removed from each item
+   */
+  cleanInputDataArray(dataArray: any[], operation?: CoreResourceOperation): any[] {
+    if (!Array.isArray(dataArray)) {
+      return dataArray;
+    }
+
+    return dataArray.map(data => this.cleanInputData(data, operation));
+  }
+
+  /**
+   * Enrich data with execution context information
+   * @param data - The data to enrich
+   * @param executionContext - The execution context containing IDs and user info
+   * @param zodSchema - The zod schema for field path validation
+   * @param resourceFieldIdentifier - The resource field identifier to exclude self-references
+   * @param operation - The operation being performed
+   * @param options - Repository options containing exclusion rules
+   * @returns Enriched data with context information
+   */
+  public enrichDataWithContext(data: any, executionContext: ExecutionContext<any>, zodSchema: z.ZodTypeAny, resourceFieldIdentifier: string, operation?: CoreResourceOperation, options?: RepositoryOptions): any {
+    if (!data || typeof data !== 'object') {
+      return data;
+    }
+
+    const enrichedData = { ...data };
+
+    // Check if context enrichment should be excluded
+    if (options?.excludeContextEnrichment === true) {
+      // Skip all context enrichment if explicitly disabled
+      return enrichedData;
+    }
+
+    // Determine blacklisted fields
+    const blacklistedFields = new Set<string>();
+
+    // Always exclude the resource's own resourceFieldIdentifier to avoid self-reference
+    blacklistedFields.add(resourceFieldIdentifier);
+
+    // Add custom blacklisted fields if provided
+    if (Array.isArray(options?.excludeContextEnrichment)) {
+      options.excludeContextEnrichment.forEach(field => blacklistedFields.add(field));
+    }
+
+    // Add context resource IDs (with nested path support, schema validation and blacklist filtering)
+    const contextResourceIds = executionContext.getContextResourceIds();
+    contextResourceIds.forEach((resourceId, fieldIdentifier) => {
+      // Skip if field is blacklisted
+      if (blacklistedFields.has(fieldIdentifier)) {
+        this.logDebug('Skipping blacklisted field in context enrichment', { fieldIdentifier });
+        return;
+      }
+
+      // Find all schema paths that end with this field identifier (including nested paths)
+      const matchingPaths = this.findRequiredNestedFieldPathsFromZodSchema(
+        zodSchema,
+        fieldIdentifier,
+        executionContext,
+        {
+          reason: 'context_enrichment',
+          message: `Execution context field '${fieldIdentifier}' is missing from the target schema during context enrichment`,
+        }
+      );
+
+      // Process each matching path
+      matchingPaths.forEach(fullPath => {
+        // Only add if not already present in data (check nested path)
+        if (!this.hasNestedPath(enrichedData, fullPath)) {
+          this.setNestedValue(enrichedData, fullPath, resourceId);
+          this.logDebug('Added context resource ID to nested path', { fieldIdentifier, fullPath, resourceId });
+        } else {
+          this.logDebug('Skipping context field - already present in data', { fieldIdentifier, fullPath });
+        }
+      });
+    });
+
+    return enrichedData;
+  }
+
+  /**
+   * Inject non-discriminator literal field values from the schema into the data.
+   *
+   * Non-discriminator literals are fixed values defined in the schema (e.g., `z.literal("ORGANIZATION")`)
+   * that are NOT used for variant discrimination. These values are excluded from CREATE DTOs
+   * (since users shouldn't/can't change them) but must be injected before persistence.
+   *
+   * Handles wrapped types (optional, default, etc.) by unwrapping before type check.
+   *
+   * @param data - The data object to enrich
+   * @param zodSchema - The zod schema containing literal field definitions
+   * @returns Data with non-discriminator literal values injected
+   */
+  public injectNonDiscriminatorLiteralValues(data: any, zodSchema: z.ZodTypeAny): any {
+    if (!data || typeof data !== 'object') {
+      return data;
+    }
+
+    const enrichedData = { ...data };
+    const shape = getZodObjectShape(zodSchema);
+
+    if (!shape) {
+      return enrichedData;
+    }
+
+    for (const [fieldName, fieldSchema] of Object.entries(shape)) {
+      // Unwrap to handle z.literal("value").optional() etc.
+      const unwrapped = unwrapSchema(fieldSchema);
+      const zodType = getZodType(unwrapped);
+
+      // Only process literal types that are NOT discriminators
+      // isDiscriminatorField already handles unwrapping via getMetadataRecursive
+      if (zodType === 'literal' && !isDiscriminatorField(fieldSchema)) {
+        // Only inject if not already present in data
+        if (!(fieldName in enrichedData)) {
+          // Extract literal value from UNWRAPPED schema.def.values (Zod 4 stores as array)
+          const literalValues = getZodDefArrayProperty(unwrapped, 'values');
+          if (literalValues && literalValues.length > 0) {
+            enrichedData[fieldName] = literalValues[0];
+            this.logDebug('Injected non-discriminator literal value', { fieldName, value: literalValues[0] });
+          }
+        }
+      }
+    }
+
+    return enrichedData;
+  }
+
+  /**
+   * Find all schema field paths that end with the given field identifier from a zod schema
+   * @param zodSchema - The zod schema to analyze for field paths
+   * @param fieldIdentifier - The field identifier to search for
+   * @returns Array of full field paths that end with the identifier
+   */
+  public findNestedFieldPathsFromZodSchema(zodSchema: z.ZodTypeAny, fieldIdentifier: string): string[] {
+    const flattenedPaths = extractFlattenedPathsFromZodSchema(zodSchema);
+
+    const matchingPaths: string[] = [];
+
+    flattenedPaths.forEach(path => {
+      // Check if the path ends with the field identifier
+      if (path === fieldIdentifier || path.endsWith(`.${fieldIdentifier}`)) {
+        matchingPaths.push(path);
+      }
+    });
+
+    this.logDebug('Found nested field paths from zod schema', { fieldIdentifier, matchingPaths, totalPaths: flattenedPaths.length });
+    return matchingPaths;
+  }
+
+  /**
+   * Resolve schema paths for a field identifier and fail closed when configuration drift
+   * would otherwise silently skip context/FK enforcement.
+   */
+  public findRequiredNestedFieldPathsFromZodSchema(
+    zodSchema: z.ZodTypeAny,
+    fieldIdentifier: string,
+    executionContext: ExecutionContext<any> | undefined,
+    details: {
+      reason: 'context_enrichment' | 'context_filter' | 'fk_filter';
+      message: string;
+      resourceIdentifier?: string;
+    }
+  ): string[] {
+    const matchingPaths = this.findNestedFieldPathsFromZodSchema(zodSchema, fieldIdentifier);
+
+    if (matchingPaths.length > 0) {
+      return matchingPaths;
+    }
+
+    throw this.errorBuilder.buildError(
+      ErrorType.INTERNAL,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+        context: {
+          fieldIdentifier,
+          reason: details.reason,
+          resourceIdentifier: details.resourceIdentifier,
+          message: details.message,
+        }
+      }
+    );
+  }
+
+  /**
+   * Set a value at a nested object path
+   * @param obj - The object to modify
+   * @param path - The dot-notation path (e.g., 'aSub.organizationId')
+   * @param value - The value to set
+   */
+  public setNestedValue(obj: any, path: string, value: any): void {
+    const keys = path.split('.');
+    let current = obj;
+
+    // Navigate to the parent object
+    for (let i = 0; i < keys.length - 1; i++) {
+      const key = keys[i];
+      if (!current[key] || typeof current[key] !== 'object') {
+        current[key] = {};
+      }
+      current = current[key];
+    }
+
+    // Set the final value
+    const finalKey = keys[keys.length - 1];
+    current[finalKey] = value;
+  }
+
+  /**
+   * Check if a nested path exists in an object
+   * @param obj - The object to check
+   * @param path - The dot-notation path (e.g., 'aSub.organizationId')
+   * @returns True if the path exists and has a value
+   */
+  public hasNestedPath(obj: any, path: string): boolean {
+    const keys = path.split('.');
+    let current = obj;
+
+    for (const key of keys) {
+      if (!current || typeof current !== 'object' || !(key in current)) {
+        return false;
+      }
+      current = current[key];
+    }
+
+    return current !== undefined && current !== null;
+  }
+
+  /**
+   * Validate that a resourceId is a valid resource identifier.
+   * Supports both MongoDB ObjectId (24 hex characters) and UUID formats.
+   *
+   * When `resourceType` is provided and `ResourceIdBackendService` is available,
+   * validates against the specific format expected for that resource's persistence adapter.
+   *
+   * Checks that the value is:
+   * - Not null
+   * - Not undefined
+   * - A string
+   * - A valid MongoDB ObjectId OR UUID format (or specific format for resourceType)
+   *
+   * @param resourceId - The resource ID to validate
+   * @param executionContext - Optional execution context for error handling
+   * @param fieldName - Optional field name for error messages (defaults to 'resourceId')
+   * @param resourceType - Optional resource type for format-aware validation
+   * @returns True if valid, throws WildoError_Backend if invalid
+   * @throws WildoError_Backend if validation fails
+   */
+  public validateResourceId(
+    resourceId: unknown,
+    executionContext?: ExecutionContext<any>,
+    fieldName: string = 'resourceId',
+    resourceType?: string
+  ): boolean {
+    // Check for null or undefined
+    if (resourceId === null || resourceId === undefined) {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.RESOURCE_ID_VALIDATION_FAILED,
+          context: {
+            fieldName,
+            reason: 'null_or_undefined',
+            message: `${fieldName} cannot be null or undefined`
+          }
+        }
+      );
+    }
+
+    // Check if it's a string
+    if (typeof resourceId !== 'string') {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.RESOURCE_ID_VALIDATION_FAILED,
+          context: {
+            fieldName,
+            reason: 'not_string',
+            actualType: typeof resourceId,
+            message: `${fieldName} must be a string, got ${typeof resourceId}`
+          }
+        }
+      );
+    }
+
+    // Use format-aware validation if resourceType is provided and service is available
+    if (resourceType && this.resourceIdService) {
+      if (!this.resourceIdService.validateForResource(resourceId, resourceType)) {
+        const expectedFormat = this.resourceIdService.getFormatForResource(resourceType);
+        throw this.errorBuilder.buildError(
+          ErrorType.VALIDATION,
+          executionContext,
+          {
+            customMessageReference: ErrorCustomMessageReference.RESOURCE_ID_VALIDATION_FAILED,
+            context: {
+              fieldName,
+              reason: 'invalid_format',
+              value: resourceId,
+              expectedFormat,
+              resourceType,
+              message: `${fieldName} must be a valid ${expectedFormat} for resource ${resourceType}, got invalid format`
+            }
+          }
+        );
+      }
+      return true;
+    }
+
+    // Fallback to generic validation (supports both MongoDB ObjectId and UUID)
+    if (!Resources_SharedUtils.isValidResourceId(resourceId)) {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.RESOURCE_ID_VALIDATION_FAILED,
+          context: {
+            fieldName,
+            reason: 'invalid_format',
+            value: resourceId,
+            message: `${fieldName} must be a valid resource ID (MongoDB ObjectId or UUID), got invalid format`
+          }
+        }
+      );
+    }
+
+    return true;
+  }
+}

package/src/base-classes/services/services/__tests__/mock-services-registry-handler.service.ts

@@ -0,0 +1,21 @@
+import 'reflect-metadata';
+import { injectable } from 'inversify';
+import { vi } from 'vitest';
+
+@injectable()
+export class MockServicesRegistryHandlerBackendService {
+  read = vi.fn(async () => null);
+
+  list = vi.fn(async () => []);
+
+  create = vi.fn(async () => null);
+
+  update = vi.fn(async () => undefined);
+
+  reset(): void {
+    this.read.mockClear();
+    this.list.mockClear();
+    this.create.mockClear();
+    this.update.mockClear();
+  }
+}

package/src/base-classes/services/services/__tests__/services-registry-handler.notifications.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from 'vitest';
+import { CoreResourceOperation } from '@wildo-ai/saas-models';
+import { dispatchPostOperationNotificationsBestEffort } from '../services-registry-handler.backend.service';
+
+describe('ServicesRegistryHandlerBackendService notification dispatch split', () => {
+  it('still dispatches resource-room notifications when computation-context preparation fails', async () => {
+    const dispatchResourceRoomNotifications = vi.fn().mockResolvedValue(undefined);
+    const dispatchConfiguredNotifications = vi.fn();
+    const analyzeContextNeeds = vi.fn().mockReturnValue({});
+    const fetchComputationContext = vi.fn().mockRejectedValue(new Error('population failed'));
+    const loggerError = vi.fn();
+
+    await dispatchPostOperationNotificationsBestEffort(
+      {
+        notificationDispatcher: {
+          dispatchResourceRoomNotifications,
+          dispatchConfiguredNotifications,
+        } as any,
+        populationService: {
+          analyzeContextNeeds,
+          fetchComputationContext,
+        } as any,
+        logger: {
+          error: loggerError,
+        } as any,
+        logDebug: vi.fn(),
+      },
+      {
+        operation: {
+          resourceIdentifier: 'documents',
+          operationIdentifier: CoreResourceOperation.UPDATE,
+        },
+        initiatorIds: {
+          userId: 'user-1',
+        },
+      },
+      { title: 'next' },
+      { _id: 'doc-1', _version: 2, title: 'next' },
+    );
+
+    expect(dispatchResourceRoomNotifications).toHaveBeenCalledWith(
+      expect.objectContaining({
+        operation: expect.objectContaining({
+          resourceIdentifier: 'documents',
+          operationIdentifier: CoreResourceOperation.UPDATE,
+        }),
+      }),
+      expect.objectContaining({
+        inputDto: { title: 'next' },
+        currentObject: { _id: 'doc-1', _version: 2, title: 'next' },
+        initiatorIds: { userId: 'user-1' },
+      }),
+    );
+    expect(analyzeContextNeeds).toHaveBeenCalledWith('documents');
+    expect(fetchComputationContext).toHaveBeenCalled();
+    expect(dispatchConfiguredNotifications).not.toHaveBeenCalled();
+    expect(loggerError).toHaveBeenCalledWith(
+      'Failed to dispatch configured notifications',
+      expect.objectContaining({
+        resourceIdentifier: 'documents',
+        operationIdentifier: CoreResourceOperation.UPDATE,
+      }),
+    );
+  });
+});