@friggframework/core 2.0.0-next.43 → 2.0.0-next.45

package/integrations/repositories/process-repository-postgres.js

@@ -0,0 +1,217 @@
+const { prisma } = require('../../database/prisma');
+const {
+    ProcessRepositoryInterface,
+} = require('./process-repository-interface');
+
+/**
+ * PostgreSQL Process Repository Adapter
+ * Handles process persistence using Prisma with PostgreSQL
+ *
+ * PostgreSQL-specific characteristics:
+ * - Uses foreign key constraints for relations
+ * - JSONB type for context and results (efficient querying)
+ * - Array type for childProcesses references
+ * - Transactional support available if needed
+ *
+ * Design Philosophy:
+ * - Same interface as MongoDB repository
+ * - Prisma abstracts away most database-specific details
+ * - Minor differences in JSON handling internally managed by Prisma
+ */
+class ProcessRepositoryPostgres extends ProcessRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    /**
+     * Convert string ID to integer for PostgreSQL queries
+     * @private
+     * @param {string|number|null|undefined} id - ID to convert
+     * @returns {number|null|undefined} Integer ID or null/undefined
+     * @throws {Error} If ID cannot be converted to integer
+     */
+    _convertId(id) {
+        if (id === null || id === undefined) return id;
+        const parsed = parseInt(id, 10);
+        if (isNaN(parsed)) {
+            throw new Error(`Invalid ID: ${id} cannot be converted to integer`);
+        }
+        return parsed;
+    }
+
+    /**
+     * Create a new process record
+     * @param {Object} processData - Process data to create
+     * @returns {Promise<Object>} Created process record
+     */
+    async create(processData) {
+        const process = await this.prisma.process.create({
+            data: {
+                userId: this._convertId(processData.userId),
+                integrationId: this._convertId(processData.integrationId),
+                name: processData.name,
+                type: processData.type,
+                state: processData.state || 'INITIALIZING',
+                context: processData.context || {},
+                results: processData.results || {},
+                parentProcessId: this._convertId(processData.parentProcessId),
+            },
+        });
+
+        return this._toPlainObject(process);
+    }
+
+    /**
+     * Find a process by ID
+     * @param {string} processId - Process ID to find
+     * @returns {Promise<Object|null>} Process record or null if not found
+     */
+    async findById(processId) {
+        const process = await this.prisma.process.findUnique({
+            where: { id: this._convertId(processId) },
+        });
+
+        return process ? this._toPlainObject(process) : null;
+    }
+
+    /**
+     * Update a process record
+     * @param {string} processId - Process ID to update
+     * @param {Object} updates - Fields to update
+     * @returns {Promise<Object>} Updated process record
+     */
+    async update(processId, updates) {
+        // Prepare update data, excluding undefined values
+        const updateData = {};
+
+        if (updates.state !== undefined) {
+            updateData.state = updates.state;
+        }
+        if (updates.context !== undefined) {
+            updateData.context = updates.context;
+        }
+        if (updates.results !== undefined) {
+            updateData.results = updates.results;
+        }
+        if (updates.parentProcessId !== undefined) {
+            updateData.parentProcessId = this._convertId(
+                updates.parentProcessId
+            );
+        }
+
+        const process = await this.prisma.process.update({
+            where: { id: this._convertId(processId) },
+            data: updateData,
+        });
+
+        return this._toPlainObject(process);
+    }
+
+    /**
+     * Find processes by integration and type
+     * @param {string} integrationId - Integration ID
+     * @param {string} type - Process type
+     * @returns {Promise<Array>} Array of process records
+     */
+    async findByIntegrationAndType(integrationId, type) {
+        const processes = await this.prisma.process.findMany({
+            where: {
+                integrationId: this._convertId(integrationId),
+                type,
+            },
+            orderBy: {
+                createdAt: 'desc',
+            },
+        });
+
+        return processes.map((p) => this._toPlainObject(p));
+    }
+
+    /**
+     * Find active processes (not in excluded states)
+     * @param {string} integrationId - Integration ID
+     * @param {string[]} [excludeStates=['COMPLETED', 'ERROR']] - States to exclude
+     * @returns {Promise<Array>} Array of active process records
+     */
+    async findActiveProcesses(
+        integrationId,
+        excludeStates = ['COMPLETED', 'ERROR']
+    ) {
+        const processes = await this.prisma.process.findMany({
+            where: {
+                integrationId: this._convertId(integrationId),
+                state: {
+                    notIn: excludeStates,
+                },
+            },
+            orderBy: {
+                createdAt: 'desc',
+            },
+        });
+
+        return processes.map((p) => this._toPlainObject(p));
+    }
+
+    /**
+     * Find a process by name (most recent)
+     * @param {string} name - Process name
+     * @returns {Promise<Object|null>} Most recent process with given name, or null
+     */
+    async findByName(name) {
+        const process = await this.prisma.process.findFirst({
+            where: { name },
+            orderBy: {
+                createdAt: 'desc',
+            },
+        });
+
+        return process ? this._toPlainObject(process) : null;
+    }
+
+    /**
+     * Delete a process by ID
+     * @param {string} processId - Process ID to delete
+     * @returns {Promise<void>}
+     */
+    async deleteById(processId) {
+        await this.prisma.process.delete({
+            where: { id: this._convertId(processId) },
+        });
+    }
+
+    /**
+     * Convert Prisma model to plain JavaScript object
+     * Ensures consistent API across repository implementations
+     * @private
+     * @param {Object} process - Prisma process model
+     * @returns {Object} Plain process object
+     */
+    _toPlainObject(process) {
+        return {
+            id: String(process.id),
+            userId: String(process.userId),
+            integrationId: String(process.integrationId),
+            name: process.name,
+            type: process.type,
+            state: process.state,
+            context: process.context,
+            results: process.results,
+            childProcesses: Array.isArray(process.childProcesses)
+                ? process.childProcesses.length > 0 &&
+                  typeof process.childProcesses[0] === 'object' &&
+                  process.childProcesses[0] !== null
+                    ? process.childProcesses.map((child) => String(child.id))
+                    : process.childProcesses
+                : [],
+            parentProcessId:
+                process.parentProcessId !== null
+                    ? String(process.parentProcessId)
+                    : null,
+            createdAt: process.createdAt,
+            updatedAt: process.updatedAt,
+        };
+    }
+}
+
+module.exports = { ProcessRepositoryPostgres };

package/integrations/tests/doubles/dummy-integration-class.js

@@ -47,23 +47,16 @@ class DummyIntegration extends IntegrationBase {
         this.updateIntegrationMessages = {
             execute: jest.fn().mockResolvedValue({})
         };
-
-        this.registerEventHandlers();
     }
 
     async loadDynamicUserActions() {
         return {};
     }
 
-    async registerEventHandlers() {
-        super.registerEventHandlers();
-        return;
-    }
-
     async send(event, data) {
         this.sendSpy(event, data);
         this.eventCallHistory.push({ event, data, timestamp: Date.now() });
-        return super.send(event, data);
+        return { event, data };
     }
 
     async initialize() {

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

@@ -0,0 +1,128 @@
+/**
+ * CreateProcess Use Case
+ * 
+ * Creates a new process record for tracking long-running operations.
+ * Validates required fields and delegates persistence to the repository.
+ * 
+ * Design Philosophy:
+ * - Use cases encapsulate business logic
+ * - Validation happens at the use case layer
+ * - Repositories handle only data access
+ * - Process model is generic and reusable
+ * 
+ * @example
+ * const createProcess = new CreateProcess({ processRepository });
+ * const process = await createProcess.execute({
+ *   userId: 'user123',
+ *   integrationId: 'integration456',
+ *   name: 'zoho-crm-contact-sync',
+ *   type: 'CRM_SYNC',
+ *   state: 'INITIALIZING',
+ *   context: { syncType: 'INITIAL', totalRecords: 0 },
+ *   results: { aggregateData: { totalSynced: 0, totalFailed: 0 } }
+ * });
+ */
+class CreateProcess {
+    /**
+     * @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 create a process
+     * @param {Object} processData - Process data to create
+     * @param {string} processData.userId - User ID (required)
+     * @param {string} processData.integrationId - Integration ID (required)
+     * @param {string} processData.name - Process name (required)
+     * @param {string} processData.type - Process type (required)
+     * @param {string} [processData.state='INITIALIZING'] - Initial state
+     * @param {Object} [processData.context={}] - Process context
+     * @param {Object} [processData.results={}] - Process results
+     * @param {string[]} [processData.childProcesses=[]] - Child process IDs
+     * @param {string} [processData.parentProcessId] - Parent process ID
+     * @returns {Promise<Object>} Created process record
+     * @throws {Error} If validation fails or creation errors
+     */
+    async execute(processData) {
+        // Validate required fields
+        this._validateProcessData(processData);
+
+        // Set defaults for optional fields
+        const processToCreate = {
+            userId: processData.userId,
+            integrationId: processData.integrationId,
+            name: processData.name,
+            type: processData.type,
+            state: processData.state || 'INITIALIZING',
+            context: processData.context || {},
+            results: processData.results || {},
+            childProcesses: processData.childProcesses || [],
+            parentProcessId: processData.parentProcessId || null,
+        };
+
+        // Delegate to repository
+        try {
+            const createdProcess = await this.processRepository.create(processToCreate);
+            return createdProcess;
+        } catch (error) {
+            throw new Error(`Failed to create process: ${error.message}`);
+        }
+    }
+
+    /**
+     * Validate process data
+     * @private
+     * @param {Object} processData - Process data to validate
+     * @throws {Error} If validation fails
+     */
+    _validateProcessData(processData) {
+        const requiredFields = ['userId', 'integrationId', 'name', 'type'];
+        const missingFields = requiredFields.filter(field => !processData[field]);
+
+        if (missingFields.length > 0) {
+            throw new Error(
+                `Missing required fields for process creation: ${missingFields.join(', ')}`
+            );
+        }
+
+        // Validate field types
+        if (typeof processData.userId !== 'string') {
+            throw new Error('userId must be a string');
+        }
+        if (typeof processData.integrationId !== 'string') {
+            throw new Error('integrationId must be a string');
+        }
+        if (typeof processData.name !== 'string') {
+            throw new Error('name must be a string');
+        }
+        if (typeof processData.type !== 'string') {
+            throw new Error('type must be a string');
+        }
+
+        // Validate optional fields if provided
+        if (processData.state && typeof processData.state !== 'string') {
+            throw new Error('state must be a string');
+        }
+        if (processData.context && typeof processData.context !== 'object') {
+            throw new Error('context must be an object');
+        }
+        if (processData.results && typeof processData.results !== 'object') {
+            throw new Error('results must be an object');
+        }
+        if (processData.childProcesses && !Array.isArray(processData.childProcesses)) {
+            throw new Error('childProcesses must be an array');
+        }
+        if (processData.parentProcessId && typeof processData.parentProcessId !== 'string') {
+            throw new Error('parentProcessId must be a string');
+        }
+    }
+}
+
+module.exports = { CreateProcess };
+

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 };
+