@friggframework/core 2.0.0-next.42 → 2.0.0-next.44

package/integrations/use-cases/create-process.test.js

@@ -0,0 +1,178 @@
+/**
+ * CreateProcess Use Case Tests
+ * 
+ * Tests process creation with validation and error handling.
+ */
+
+const { CreateProcess } = require('./create-process');
+
+describe('CreateProcess', () => {
+    let createProcessUseCase;
+    let mockProcessRepository;
+
+    beforeEach(() => {
+        mockProcessRepository = {
+            create: jest.fn(),
+        };
+        createProcessUseCase = new CreateProcess({
+            processRepository: mockProcessRepository,
+        });
+    });
+
+    describe('constructor', () => {
+        it('should require processRepository', () => {
+            expect(() => new CreateProcess({})).toThrow('processRepository is required');
+        });
+
+        it('should initialize with processRepository', () => {
+            expect(createProcessUseCase.processRepository).toBe(mockProcessRepository);
+        });
+    });
+
+    describe('execute', () => {
+        const validProcessData = {
+            userId: 'user-123',
+            integrationId: 'integration-456',
+            name: 'test-crm-contact-sync',
+            type: 'CRM_SYNC',
+        };
+
+        it('should create a process with minimal required data', async () => {
+            const mockCreatedProcess = { id: 'process-789', ...validProcessData };
+            mockProcessRepository.create.mockResolvedValue(mockCreatedProcess);
+
+            const result = await createProcessUseCase.execute(validProcessData);
+
+            expect(mockProcessRepository.create).toHaveBeenCalledWith({
+                userId: 'user-123',
+                integrationId: 'integration-456',
+                name: 'test-crm-contact-sync',
+                type: 'CRM_SYNC',
+                state: 'INITIALIZING',
+                context: {},
+                results: {},
+                childProcesses: [],
+                parentProcessId: null,
+            });
+            expect(result).toEqual(mockCreatedProcess);
+        });
+
+        it('should create a process with all optional data', async () => {
+            const processDataWithOptions = {
+                ...validProcessData,
+                state: 'FETCHING_TOTAL',
+                context: { syncType: 'INITIAL', totalRecords: 100 },
+                results: { aggregateData: { totalSynced: 0 } },
+                childProcesses: ['child-1', 'child-2'],
+                parentProcessId: 'parent-123',
+            };
+
+            const mockCreatedProcess = { id: 'process-789', ...processDataWithOptions };
+            mockProcessRepository.create.mockResolvedValue(mockCreatedProcess);
+
+            const result = await createProcessUseCase.execute(processDataWithOptions);
+
+            expect(mockProcessRepository.create).toHaveBeenCalledWith(processDataWithOptions);
+            expect(result).toEqual(mockCreatedProcess);
+        });
+
+        it('should throw error if userId is missing', async () => {
+            const invalidData = { integrationId: 'int-123', name: 'test', type: 'CRM_SYNC' };
+
+            await expect(createProcessUseCase.execute(invalidData))
+                .rejects.toThrow('Missing required fields for process creation: userId');
+        });
+
+        it('should throw error if integrationId is missing', async () => {
+            const invalidData = { userId: 'user-123', name: 'test', type: 'CRM_SYNC' };
+
+            await expect(createProcessUseCase.execute(invalidData))
+                .rejects.toThrow('Missing required fields for process creation: integrationId');
+        });
+
+        it('should throw error if name is missing', async () => {
+            const invalidData = { userId: 'user-123', integrationId: 'int-123', type: 'CRM_SYNC' };
+
+            await expect(createProcessUseCase.execute(invalidData))
+                .rejects.toThrow('Missing required fields for process creation: name');
+        });
+
+        it('should throw error if type is missing', async () => {
+            const invalidData = { userId: 'user-123', integrationId: 'int-123', name: 'test' };
+
+            await expect(createProcessUseCase.execute(invalidData))
+                .rejects.toThrow('Missing required fields for process creation: type');
+        });
+
+        it('should throw error if userId is not a string', async () => {
+            const invalidData = { ...validProcessData, userId: 123 };
+
+            await expect(createProcessUseCase.execute(invalidData))
+                .rejects.toThrow('userId must be a string');
+        });
+
+        it('should throw error if integrationId is not a string', async () => {
+            const invalidData = { ...validProcessData, integrationId: 456 };
+
+            await expect(createProcessUseCase.execute(invalidData))
+                .rejects.toThrow('integrationId must be a string');
+        });
+
+        it('should throw error if name is not a string', async () => {
+            const invalidData = { ...validProcessData, name: 789 };
+
+            await expect(createProcessUseCase.execute(invalidData))
+                .rejects.toThrow('name must be a string');
+        });
+
+        it('should throw error if type is not a string', async () => {
+            const invalidData = { ...validProcessData, type: 999 };
+
+            await expect(createProcessUseCase.execute(invalidData))
+                .rejects.toThrow('type must be a string');
+        });
+
+        it('should throw error if state is provided but not a string', async () => {
+            const invalidData = { ...validProcessData, state: 123 };
+
+            await expect(createProcessUseCase.execute(invalidData))
+                .rejects.toThrow('state must be a string');
+        });
+
+        it('should throw error if context is provided but not an object', async () => {
+            const invalidData = { ...validProcessData, context: 'invalid' };
+
+            await expect(createProcessUseCase.execute(invalidData))
+                .rejects.toThrow('context must be an object');
+        });
+
+        it('should throw error if results is provided but not an object', async () => {
+            const invalidData = { ...validProcessData, results: 'invalid' };
+
+            await expect(createProcessUseCase.execute(invalidData))
+                .rejects.toThrow('results must be an object');
+        });
+
+        it('should throw error if childProcesses is provided but not an array', async () => {
+            const invalidData = { ...validProcessData, childProcesses: 'invalid' };
+
+            await expect(createProcessUseCase.execute(invalidData))
+                .rejects.toThrow('childProcesses must be an array');
+        });
+
+        it('should throw error if parentProcessId is provided but not a string', async () => {
+            const invalidData = { ...validProcessData, parentProcessId: 123 };
+
+            await expect(createProcessUseCase.execute(invalidData))
+                .rejects.toThrow('parentProcessId must be a string');
+        });
+
+        it('should handle repository errors', async () => {
+            const repositoryError = new Error('Database connection failed');
+            mockProcessRepository.create.mockRejectedValue(repositoryError);
+
+            await expect(createProcessUseCase.execute(validProcessData))
+                .rejects.toThrow('Failed to create process: Database connection failed');
+        });
+    });
+});

package/integrations/use-cases/get-process.js

@@ -0,0 +1,87 @@
+/**
+ * GetProcess Use Case
+ * 
+ * Retrieves a process by ID with proper error handling.
+ * Simple use case that delegates to repository.
+ * 
+ * Design Philosophy:
+ * - Use cases provide consistent error handling
+ * - Business logic layer between controllers and repositories
+ * - Return null for not found vs throwing error (configurable)
+ * 
+ * @example
+ * const getProcess = new GetProcess({ processRepository });
+ * const process = await getProcess.execute(processId);
+ * // or
+ * const process = await getProcess.executeOrThrow(processId);
+ */
+class GetProcess {
+    /**
+     * @param {Object} params
+     * @param {ProcessRepositoryInterface} params.processRepository - Repository for process data access
+     */
+    constructor({ processRepository }) {
+        if (!processRepository) {
+            throw new Error('processRepository is required');
+        }
+        this.processRepository = processRepository;
+    }
+
+    /**
+     * Execute the use case to get a process by ID
+     * @param {string} processId - Process ID to retrieve
+     * @returns {Promise<Object|null>} Process record or null if not found
+     * @throws {Error} If processId is invalid
+     */
+    async execute(processId) {
+        // Validate input
+        if (!processId || typeof processId !== 'string') {
+            throw new Error('processId must be a non-empty string');
+        }
+
+        // Delegate to repository
+        try {
+            const process = await this.processRepository.findById(processId);
+            return process;
+        } catch (error) {
+            throw new Error(`Failed to retrieve process: ${error.message}`);
+        }
+    }
+
+    /**
+     * Execute and throw if process not found
+     * @param {string} processId - Process ID to retrieve
+     * @returns {Promise<Object>} Process record
+     * @throws {Error} If process not found or retrieval fails
+     */
+    async executeOrThrow(processId) {
+        const process = await this.execute(processId);
+
+        if (!process) {
+            throw new Error(`Process not found: ${processId}`);
+        }
+
+        return process;
+    }
+
+    /**
+     * Get multiple processes by IDs
+     * @param {string[]} processIds - Array of process IDs
+     * @returns {Promise<Array>} Array of process records (excludes not found)
+     */
+    async executeMany(processIds) {
+        if (!Array.isArray(processIds)) {
+            throw new Error('processIds must be an array');
+        }
+
+        const processes = await Promise.all(
+            processIds.map(id => this.execute(id))
+        );
+
+        // Filter out nulls (not found)
+        return processes.filter(p => p !== null);
+    }
+}
+
+module.exports = { GetProcess };
+

package/integrations/use-cases/get-process.test.js

@@ -0,0 +1,190 @@
+/**
+ * GetProcess Use Case Tests
+ * 
+ * Tests process retrieval with error handling.
+ */
+
+const { GetProcess } = require('./get-process');
+
+describe('GetProcess', () => {
+    let getProcessUseCase;
+    let mockProcessRepository;
+
+    beforeEach(() => {
+        mockProcessRepository = {
+            findById: jest.fn(),
+        };
+        getProcessUseCase = new GetProcess({
+            processRepository: mockProcessRepository,
+        });
+    });
+
+    describe('constructor', () => {
+        it('should require processRepository', () => {
+            expect(() => new GetProcess({})).toThrow('processRepository is required');
+        });
+
+        it('should initialize with processRepository', () => {
+            expect(getProcessUseCase.processRepository).toBe(mockProcessRepository);
+        });
+    });
+
+    describe('execute', () => {
+        const processId = 'process-123';
+        const mockProcess = {
+            id: processId,
+            userId: 'user-456',
+            integrationId: 'integration-789',
+            name: 'test-sync',
+            type: 'CRM_SYNC',
+            state: 'PROCESSING_BATCHES',
+            context: {
+                syncType: 'INITIAL',
+                totalRecords: 1000,
+                processedRecords: 500,
+            },
+            results: {
+                aggregateData: {
+                    totalSynced: 480,
+                    totalFailed: 20,
+                    duration: 120000,
+                    recordsPerSecond: 4.17,
+                },
+            },
+            createdAt: new Date('2024-01-01T10:00:00Z'),
+            updatedAt: new Date('2024-01-01T10:02:00Z'),
+        };
+
+        it('should retrieve a process by ID', async () => {
+            mockProcessRepository.findById.mockResolvedValue(mockProcess);
+
+            const result = await getProcessUseCase.execute(processId);
+
+            expect(mockProcessRepository.findById).toHaveBeenCalledWith(processId);
+            expect(result).toEqual(mockProcess);
+        });
+
+        it('should return null if process not found', async () => {
+            mockProcessRepository.findById.mockResolvedValue(null);
+
+            const result = await getProcessUseCase.execute(processId);
+
+            expect(mockProcessRepository.findById).toHaveBeenCalledWith(processId);
+            expect(result).toBeNull();
+        });
+
+        it('should throw error if processId is missing', async () => {
+            await expect(getProcessUseCase.execute(''))
+                .rejects.toThrow('processId must be a non-empty string');
+        });
+
+        it('should throw error if processId is not a string', async () => {
+            await expect(getProcessUseCase.execute(123))
+                .rejects.toThrow('processId must be a non-empty string');
+        });
+
+        it('should handle repository errors', async () => {
+            const repositoryError = new Error('Database connection failed');
+            mockProcessRepository.findById.mockRejectedValue(repositoryError);
+
+            await expect(getProcessUseCase.execute(processId))
+                .rejects.toThrow('Failed to retrieve process: Database connection failed');
+        });
+    });
+
+    describe('executeOrThrow', () => {
+        const processId = 'process-123';
+        const mockProcess = {
+            id: processId,
+            userId: 'user-456',
+            integrationId: 'integration-789',
+            name: 'test-sync',
+            type: 'CRM_SYNC',
+            state: 'COMPLETED',
+        };
+
+        it('should return process if found', async () => {
+            mockProcessRepository.findById.mockResolvedValue(mockProcess);
+
+            const result = await getProcessUseCase.executeOrThrow(processId);
+
+            expect(result).toEqual(mockProcess);
+        });
+
+        it('should throw error if process not found', async () => {
+            mockProcessRepository.findById.mockResolvedValue(null);
+
+            await expect(getProcessUseCase.executeOrThrow(processId))
+                .rejects.toThrow('Process not found: process-123');
+        });
+
+        it('should propagate repository errors', async () => {
+            const repositoryError = new Error('Database connection failed');
+            mockProcessRepository.findById.mockRejectedValue(repositoryError);
+
+            await expect(getProcessUseCase.executeOrThrow(processId))
+                .rejects.toThrow('Failed to retrieve process: Database connection failed');
+        });
+    });
+
+    describe('executeMany', () => {
+        const processIds = ['process-1', 'process-2', 'process-3'];
+        const mockProcesses = [
+            { id: 'process-1', name: 'sync-1', state: 'COMPLETED' },
+            { id: 'process-2', name: 'sync-2', state: 'PROCESSING' },
+            // process-3 will not be found
+        ];
+
+        it('should retrieve multiple processes', async () => {
+            mockProcessRepository.findById
+                .mockResolvedValueOnce(mockProcesses[0])  // process-1 found
+                .mockResolvedValueOnce(mockProcesses[1])  // process-2 found
+                .mockResolvedValueOnce(null);             // process-3 not found
+
+            const result = await getProcessUseCase.executeMany(processIds);
+
+            expect(mockProcessRepository.findById).toHaveBeenCalledTimes(3);
+            expect(mockProcessRepository.findById).toHaveBeenCalledWith('process-1');
+            expect(mockProcessRepository.findById).toHaveBeenCalledWith('process-2');
+            expect(mockProcessRepository.findById).toHaveBeenCalledWith('process-3');
+            
+            // Should return only found processes
+            expect(result).toEqual([mockProcesses[0], mockProcesses[1]]);
+        });
+
+        it('should return empty array if no processes found', async () => {
+            mockProcessRepository.findById
+                .mockResolvedValueOnce(null)
+                .mockResolvedValueOnce(null)
+                .mockResolvedValueOnce(null);
+
+            const result = await getProcessUseCase.executeMany(processIds);
+
+            expect(result).toEqual([]);
+        });
+
+        it('should throw error if processIds is not an array', async () => {
+            await expect(getProcessUseCase.executeMany('not-an-array'))
+                .rejects.toThrow('processIds must be an array');
+        });
+
+        it('should handle mixed success and failure', async () => {
+            const repositoryError = new Error('Database error');
+            mockProcessRepository.findById
+                .mockResolvedValueOnce(mockProcesses[0])  // process-1 found
+                .mockRejectedValueOnce(repositoryError)   // process-2 error
+                .mockResolvedValueOnce(null);             // process-3 not found
+
+            // Should propagate the repository error
+            await expect(getProcessUseCase.executeMany(processIds))
+                .rejects.toThrow('Failed to retrieve process: Database error');
+        });
+
+        it('should handle empty array', async () => {
+            const result = await getProcessUseCase.executeMany([]);
+
+            expect(mockProcessRepository.findById).not.toHaveBeenCalled();
+            expect(result).toEqual([]);
+        });
+    });
+});

package/integrations/use-cases/index.js

@@ -2,10 +2,18 @@ const { GetIntegrationsForUser } = require('./get-integrations-for-user');
 const { DeleteIntegrationForUser } = require('./delete-integration-for-user');
 const { CreateIntegration } = require('./create-integration');
 const { GetIntegration } = require('./get-integration');
+const { CreateProcess } = require('./create-process');
+const { UpdateProcessState } = require('./update-process-state');
+const { UpdateProcessMetrics } = require('./update-process-metrics');
+const { GetProcess } = require('./get-process');
 
 module.exports = {
     GetIntegrationsForUser,
     DeleteIntegrationForUser,
     CreateIntegration,
     GetIntegration,
+    CreateProcess,
+    UpdateProcessState,
+    UpdateProcessMetrics,
+    GetProcess,
 }; 

package/integrations/use-cases/update-process-metrics.js

@@ -0,0 +1,201 @@
+/** 
+ TODO:
+ This implementation contains a race condition in the `execute` method. When multiple concurrent processes call this method on the same process record, they'll each read the current state, modify it independently, and then save - potentially overwriting each other's changes.
+
+For example:
+```
+Thread 1: reads process with totalSynced=100
+Thread 2: reads process with totalSynced=100
+Thread 1: adds 50 → writes totalSynced=150
+Thread 2: adds 30 → writes totalSynced=130 (overwrites Thread 1's update!)
+```
+
+Consider implementing one of these patterns:
+1. Database transactions with row locking
+2. Optimistic concurrency control with version numbers
+3. Atomic update operations (e.g., `$inc` in MongoDB)
+4. A FIFO queue for process updates (as described in the PROCESS_MANAGEMENT_QUEUE_SPEC.md)
+
+The current approach will lead to lost updates and inconsistent metrics during concurrent processing.
+
+ */
+
+/**
+ * UpdateProcessMetrics Use Case
+ *
+ * Updates process metrics, calculates aggregates, and computes estimated completion time.
+ * Optionally broadcasts progress via WebSocket service if provided.
+ *
+ * Design Philosophy:
+ * - Metrics are cumulative (add to existing counts)
+ * - Performance metrics calculated automatically (duration, records/sec)
+ * - ETA computed based on current progress
+ * - Error history limited to last 100 entries
+ * - WebSocket broadcasting is optional (DI pattern)
+ *
+ * @example
+ * const updateMetrics = new UpdateProcessMetrics({ processRepository, websocketService });
+ * await updateMetrics.execute(processId, {
+ *   processed: 100,
+ *   success: 95,
+ *   errors: 5,
+ *   errorDetails: [{ contactId: 'abc', error: 'Missing email', timestamp: '...' }]
+ * });
+ */
+class UpdateProcessMetrics {
+    /**
+     * @param {Object} params
+     * @param {ProcessRepositoryInterface} params.processRepository - Repository for process data access
+     * @param {Object} [params.websocketService] - Optional WebSocket service for progress broadcasting
+     */
+    constructor({ processRepository, websocketService }) {
+        if (!processRepository) {
+            throw new Error('processRepository is required');
+        }
+        this.processRepository = processRepository;
+        this.websocketService = websocketService;
+    }
+
+    /**
+     * Execute the use case to update process metrics
+     * @param {string} processId - Process ID to update
+     * @param {Object} metricsUpdate - Metrics to add/update
+     * @param {number} [metricsUpdate.processed=0] - Number of records processed in this batch
+     * @param {number} [metricsUpdate.success=0] - Number of successful records
+     * @param {number} [metricsUpdate.errors=0] - Number of failed records
+     * @param {Array} [metricsUpdate.errorDetails=[]] - Error details array
+     * @returns {Promise<Object>} Updated process record
+     * @throws {Error} If process not found or update fails
+     */
+    async execute(processId, metricsUpdate) {
+        // Validate inputs
+        if (!processId || typeof processId !== 'string') {
+            throw new Error('processId must be a non-empty string');
+        }
+        if (!metricsUpdate || typeof metricsUpdate !== 'object') {
+            throw new Error('metricsUpdate must be an object');
+        }
+
+        // Retrieve current process
+        const process = await this.processRepository.findById(processId);
+        if (!process) {
+            throw new Error(`Process not found: ${processId}`);
+        }
+
+        // Get current context and results
+        const context = process.context || {};
+        const results = process.results || { aggregateData: {} };
+
+        // Initialize nested objects if not present
+        if (!results.aggregateData) {
+            results.aggregateData = {};
+        }
+
+        // Update context counters (cumulative)
+        context.processedRecords =
+            (context.processedRecords || 0) + (metricsUpdate.processed || 0);
+
+        // Update results aggregates (cumulative)
+        results.aggregateData.totalSynced =
+            (results.aggregateData.totalSynced || 0) +
+            (metricsUpdate.success || 0);
+        results.aggregateData.totalFailed =
+            (results.aggregateData.totalFailed || 0) +
+            (metricsUpdate.errors || 0);
+
+        // Append error details (limited to last 100)
+        if (
+            metricsUpdate.errorDetails &&
+            metricsUpdate.errorDetails.length > 0
+        ) {
+            results.aggregateData.errors = [
+                ...(results.aggregateData.errors || []),
+                ...metricsUpdate.errorDetails,
+            ].slice(-100); // Keep only last 100 errors
+        }
+
+        // Calculate performance metrics
+        const startTime = new Date(context.startTime || process.createdAt);
+        const elapsed = Date.now() - startTime.getTime();
+        results.aggregateData.duration = elapsed;
+
+        if (elapsed > 0 && context.processedRecords > 0) {
+            results.aggregateData.recordsPerSecond =
+                context.processedRecords / (elapsed / 1000);
+        } else {
+            results.aggregateData.recordsPerSecond = 0;
+        }
+
+        // Calculate ETA if we know total
+        if (context.totalRecords > 0 && context.processedRecords > 0) {
+            const remaining = context.totalRecords - context.processedRecords;
+            if (results.aggregateData.recordsPerSecond > 0) {
+                const etaMs =
+                    (remaining / results.aggregateData.recordsPerSecond) * 1000;
+                const eta = new Date(Date.now() + etaMs);
+                context.estimatedCompletion = eta.toISOString();
+            }
+        }
+
+        // Prepare updates
+        const updates = {
+            context,
+            results,
+        };
+
+        // Persist updates
+        let updatedProcess;
+        try {
+            updatedProcess = await this.processRepository.update(
+                processId,
+                updates
+            );
+        } catch (error) {
+            throw new Error(
+                `Failed to update process metrics: ${error.message}`
+            );
+        }
+
+        // Broadcast progress via WebSocket (if service provided)
+        if (this.websocketService) {
+            await this._broadcastProgress(updatedProcess);
+        }
+
+        return updatedProcess;
+    }
+
+    /**
+     * Broadcast progress update via WebSocket
+     * @private
+     * @param {Object} process - Updated process record
+     */
+    async _broadcastProgress(process) {
+        try {
+            const context = process.context || {};
+            const results = process.results || { aggregateData: {} };
+            const aggregateData = results.aggregateData || {};
+
+            await this.websocketService.broadcast({
+                type: 'PROCESS_PROGRESS',
+                data: {
+                    processId: process.id,
+                    processName: process.name,
+                    processType: process.type,
+                    state: process.state,
+                    processed: context.processedRecords || 0,
+                    total: context.totalRecords || 0,
+                    successCount: aggregateData.totalSynced || 0,
+                    errorCount: aggregateData.totalFailed || 0,
+                    recordsPerSecond: aggregateData.recordsPerSecond || 0,
+                    estimatedCompletion: context.estimatedCompletion || null,
+                    timestamp: new Date().toISOString(),
+                },
+            });
+        } catch (error) {
+            // Log but don't fail the update if WebSocket broadcast fails
+            console.error('Failed to broadcast process progress:', error);
+        }
+    }
+}
+
+module.exports = { UpdateProcessMetrics };