@friggframework/core 2.0.0-next.6 → 2.0.0-next.61

package/integrations/tests/doubles/test-integration-repository.js

@@ -0,0 +1,99 @@
+const { v4: uuid } = require('uuid');
+
+class TestIntegrationRepository {
+    constructor() {
+        this.store = new Map();
+        this.operationHistory = [];
+    }
+
+    async createIntegration(entities, userId, config) {
+        const id = uuid();
+        const record = {
+            id,
+            _id: id,
+            entitiesIds: entities,
+            userId: userId,
+            config,
+            version: '0.0.0',
+            status: 'NEW',
+            messages: {},
+        };
+        this.store.set(id, record);
+        this.operationHistory.push({ operation: 'create', id, userId, config });
+        return record;
+    }
+
+    async findIntegrationById(id) {
+        const rec = this.store.get(id);
+        this.operationHistory.push({ operation: 'findById', id, found: !!rec });
+        if (!rec) return null;
+        return rec;
+    }
+
+    async findIntegrationsByUserId(userId) {
+        const results = Array.from(this.store.values()).filter(r => r.userId === userId);
+        this.operationHistory.push({ operation: 'findByUserId', userId, count: results.length });
+        return results;
+    }
+
+    async findIntegrationByUserId(userId) {
+        const record = Array.from(this.store.values()).find((r) => r.userId === userId);
+        this.operationHistory.push({
+            operation: 'findSingleByUserId',
+            userId,
+            found: !!record,
+        });
+        return record || null;
+    }
+
+    async updateIntegrationMessages(id, type, title, body, timestamp) {
+        const rec = this.store.get(id);
+        if (!rec) {
+            this.operationHistory.push({ operation: 'updateMessages', id, success: false });
+            return false;
+        }
+        if (!rec.messages[type]) rec.messages[type] = [];
+        rec.messages[type].push({ title, message: body, timestamp });
+        this.operationHistory.push({ operation: 'updateMessages', id, type, success: true });
+        return true;
+    }
+
+    async updateIntegrationConfig(id, config) {
+        const rec = this.store.get(id);
+        if (!rec) {
+            this.operationHistory.push({ operation: 'updateConfig', id, success: false });
+            throw new Error(`Integration with id ${id} not found`);
+        }
+        rec.config = config;
+        this.operationHistory.push({ operation: 'updateConfig', id, success: true });
+        return rec;
+    }
+
+    async deleteIntegrationById(id) {
+        const existed = this.store.has(id);
+        const result = this.store.delete(id);
+        this.operationHistory.push({ operation: 'delete', id, existed, success: result });
+        return result;
+    }
+
+    async updateIntegrationStatus(id, status) {
+        const rec = this.store.get(id);
+        if (rec) {
+            rec.status = status;
+            this.operationHistory.push({ operation: 'updateStatus', id, status, success: true });
+        } else {
+            this.operationHistory.push({ operation: 'updateStatus', id, status, success: false });
+        }
+        return !!rec;
+    }
+
+    getOperationHistory() {
+        return [...this.operationHistory];
+    }
+
+    clearHistory() {
+        this.operationHistory = [];
+    }
+}
+
+module.exports = { TestIntegrationRepository }; 

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

@@ -0,0 +1,83 @@
+// Removed Integration wrapper - using IntegrationBase directly
+const {
+    mapIntegrationClassToIntegrationDTO,
+} = require('../utils/map-integration-dto');
+
+/**
+ * Use case for creating a new integration instance.
+ * @class CreateIntegration
+ */
+class CreateIntegration {
+    /**
+     * Creates a new CreateIntegration instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface} params.integrationRepository - Repository for integration data operations.
+     * @param {import('../integration-classes').IntegrationClasses} params.integrationClasses - Array of available integration classes.
+     * @param {import('../../modules/module-factory').ModuleFactory} params.moduleFactory - Service for module instantiation and management.
+     */
+    constructor({ integrationRepository, integrationClasses, moduleFactory }) {
+        this.integrationRepository = integrationRepository;
+        this.integrationClasses = integrationClasses;
+        this.moduleFactory = moduleFactory;
+    }
+
+    /**
+     * Executes the integration creation process.
+     * @async
+     * @param {string[]} entities - Array of entity IDs to associate with the integration.
+     * @param {string} userId - ID of the user creating the integration.
+     * @param {Object} config - Configuration object for the integration.
+     * @param {string} config.type - Type of integration to create.
+     * @returns {Promise<Object>} The created integration DTO.
+     * @throws {Error} When integration class is not found for the specified type.
+     */
+    async execute(entities, userId, config) {
+        const integrationRecord =
+            await this.integrationRepository.createIntegration(
+                entities,
+                userId,
+                config
+            );
+
+        const integrationClass = this.integrationClasses.find(
+            (integrationClass) =>
+                integrationClass.Definition.name ===
+                integrationRecord.config.type
+        );
+
+        if (!integrationClass) {
+            throw new Error(
+                `No integration class found for type: ${integrationRecord.config.type}`
+            );
+        }
+
+        const modules = [];
+        for (const entityId of integrationRecord.entitiesIds) {
+            const moduleInstance = await this.moduleFactory.getModuleInstance(
+                entityId,
+                integrationRecord.userId
+            );
+            modules.push(moduleInstance);
+        }
+
+        const integrationInstance = new integrationClass({
+            id: integrationRecord.id,
+            userId: integrationRecord.userId,
+            entities: integrationRecord.entitiesIds,
+            config: integrationRecord.config,
+            status: integrationRecord.status,
+            version: integrationRecord.version,
+            messages: integrationRecord.messages,
+            modules,
+        });
+
+        await integrationInstance.initialize();
+        await integrationInstance.send('ON_CREATE', {
+            integrationId: integrationRecord.id,
+        });
+
+        return mapIntegrationClassToIntegrationDTO(integrationInstance);
+    }
+}
+
+module.exports = { CreateIntegration };

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/delete-integration-for-user.js

@@ -0,0 +1,101 @@
+const Boom = require('@hapi/boom');
+// Removed Integration wrapper - using IntegrationBase directly
+
+/**
+ * Use case for deleting an integration for a specific user.
+ * @class DeleteIntegrationForUser
+ */
+class DeleteIntegrationForUser {
+    /**
+     * Creates a new DeleteIntegrationForUser instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface} params.integrationRepository - Repository for integration data operations.
+     * @param {Array<import('../integration').Integration>} params.integrationClasses - Array of available integration classes.
+     * @param {import('../../modules/module-factory').ModuleFactory} params.moduleFactory - Service for module instantiation and management.
+     */
+    constructor({ integrationRepository, integrationClasses, moduleFactory }) {
+        /**
+         * @type {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface}
+         */
+        this.integrationRepository = integrationRepository;
+        this.integrationClasses = integrationClasses;
+        this.moduleFactory = moduleFactory;
+    }
+
+    /**
+     * Executes the deletion of an integration for a user.
+     * @async
+     * @param {string} integrationId - ID of the integration to delete.
+     * @param {string} userId - ID of the user requesting the deletion.
+     * @returns {Promise<void>} Resolves when the integration is successfully deleted.
+     * @throws {Boom.notFound} When integration with the specified ID does not exist.
+     * @throws {Error} When the integration doesn't belong to the specified user.
+     */
+    async execute(integrationId, userId) {
+        const integrationRecord =
+            await this.integrationRepository.findIntegrationById(integrationId);
+
+        if (!integrationRecord) {
+            throw Boom.notFound(
+                `Integration with id of ${integrationId} does not exist`
+            );
+        }
+
+        const integrationClass = this.integrationClasses.find(
+            (integrationClass) =>
+                integrationClass.Definition.name ===
+                integrationRecord.config.type
+        );
+
+        if (integrationRecord.userId !== userId) {
+            throw new Error(
+                `Integration ${integrationId} does not belong to User ${userId}`
+            );
+        }
+
+        // Load modules with API clients for webhook deletion
+        const modules = [];
+        const failedModuleLoads = [];
+
+        for (const entityId of integrationRecord.entitiesIds) {
+            try {
+                const moduleInstance = await this.moduleFactory.getModuleInstance(
+                    entityId,
+                    integrationRecord.userId
+                );
+                modules.push(moduleInstance);
+            } catch (error) {
+                console.error(
+                    `[Integration Deletion] Failed to load module for entity ${entityId}:`,
+                    error.message
+                );
+                failedModuleLoads.push({ entityId, error: error.message });
+            }
+        }
+
+        if (failedModuleLoads.length > 0) {
+            console.warn(
+                `[Integration Deletion] ${failedModuleLoads.length}/${integrationRecord.entitiesIds.length} module(s) failed to load. Webhooks for these modules may require manual cleanup.`
+            );
+        }
+
+        const integrationInstance = new integrationClass({
+            id: integrationRecord.id,
+            userId: integrationRecord.userId,
+            entities: integrationRecord.entitiesIds,
+            config: integrationRecord.config,
+            status: integrationRecord.status,
+            version: integrationRecord.version,
+            messages: integrationRecord.messages,
+            modules,
+        });
+
+        // Complete async initialization (load dynamic actions, register handlers)
+        await integrationInstance.initialize();
+        await integrationInstance.send('ON_DELETE');
+
+        await this.integrationRepository.deleteIntegrationById(integrationId);
+    }
+}
+
+module.exports = { DeleteIntegrationForUser };

package/integrations/use-cases/find-integration-context-by-external-entity-id.js

@@ -0,0 +1,72 @@
+class FindIntegrationContextByExternalEntityIdUseCase {
+    constructor({
+        integrationRepository,
+        moduleRepository,
+        loadIntegrationContextUseCase,
+    } = {}) {
+        if (!integrationRepository) {
+            throw new Error('integrationRepository is required');
+        }
+        if (!moduleRepository) {
+            throw new Error('moduleRepository is required');
+        }
+        if (!loadIntegrationContextUseCase) {
+            throw new Error('loadIntegrationContextUseCase is required');
+        }
+
+        this.integrationRepository = integrationRepository;
+        this.moduleRepository = moduleRepository;
+        this.loadIntegrationContextUseCase = loadIntegrationContextUseCase;
+    }
+
+    async execute({ externalEntityId }) {
+        if (!externalEntityId) {
+            const error = new Error('externalEntityId is required');
+            error.code = 'EXTERNAL_ENTITY_ID_REQUIRED';
+            throw error;
+        }
+
+        const entity = await this.moduleRepository.findEntity({
+            externalId: externalEntityId,
+        });
+
+        if (!entity) {
+            const error = new Error(
+                `Entity not found for externalId: ${externalEntityId}`
+            );
+            error.code = 'ENTITY_NOT_FOUND';
+            throw error;
+        }
+
+        if (!entity.userId) {
+            const error = new Error('Entity does not have an associated user');
+            error.code = 'ENTITY_USER_NOT_FOUND';
+            throw error;
+        }
+
+        const integrationRecord =
+            await this.integrationRepository.findIntegrationByUserId(
+                entity.userId
+            );
+
+        if (!integrationRecord) {
+            const error = new Error(
+                `Integration not found for user: ${entity.userId}`
+            );
+            error.code = 'INTEGRATION_NOT_FOUND';
+            throw error;
+        }
+
+        const context = await this.loadIntegrationContextUseCase.execute({
+            integrationRecord,
+        });
+
+        return {
+            context,
+            entity,
+            record: integrationRecord,
+        };
+    }
+}
+
+module.exports = { FindIntegrationContextByExternalEntityIdUseCase };

package/integrations/use-cases/get-integration-for-user.js

@@ -0,0 +1,78 @@
+// Removed Integration wrapper - using IntegrationBase directly
+const { mapIntegrationClassToIntegrationDTO } = require('../utils/map-integration-dto');
+const Boom = require('@hapi/boom');
+
+/**
+ * Use case for retrieving a single integration for a specific user.
+ * @class GetIntegrationForUser
+ */
+class GetIntegrationForUser {
+    /**
+     * Creates a new GetIntegrationForUser instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../integration-repository-interface').IntegrationRepositoryInterface} params.integrationRepository - Repository for integration data operations.
+     * @param {Array<import('../integration').Integration>} params.integrationClasses - Array of available integration classes.
+     * @param {import('../../modules/module-factory').ModuleFactory} params.moduleFactory - Service for module instantiation and management.
+     * @param {import('../../modules/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository - Repository for module and entity data operations.
+     */
+    constructor({ integrationRepository, integrationClasses, moduleFactory, moduleRepository }) {
+
+        /**
+         * @type {import('../integration-repository-interface').IntegrationRepositoryInterface}
+         */
+        this.integrationRepository = integrationRepository;
+        this.integrationClasses = integrationClasses;
+        this.moduleFactory = moduleFactory;
+        this.moduleRepository = moduleRepository;
+    }
+
+    /**
+     * Executes the retrieval of a single integration for a user.
+     * @async
+     * @param {string} integrationId - ID of the integration to retrieve.
+     * @param {string} userId - ID of the user requesting the integration.
+     * @returns {Promise<Object>} The integration DTO for the specified user.
+     * @throws {Boom.notFound} When integration with the specified ID does not exist.
+     * @throws {Boom.forbidden} When user does not have access to the integration.
+     */
+    async execute(integrationId, userId) {
+        const integrationRecord = await this.integrationRepository.findIntegrationById(integrationId);
+        const entities = await this.moduleRepository.findEntitiesByIds(integrationRecord.entitiesIds);
+
+        if (!integrationRecord) {
+            throw Boom.notFound(`Integration with id of ${integrationId} does not exist`);
+        }
+
+        if (integrationRecord.userId.toString() !== userId.toString()) {
+            throw Boom.forbidden('User does not have access to this integration');
+        }
+
+        const integrationClass = this.integrationClasses.find(
+            (integrationClass) => integrationClass.Definition.name === integrationRecord.config.type
+        );
+
+        const modules = [];
+        for (const entity of entities) {
+            const moduleInstance = await this.moduleFactory.getModuleInstance(
+                entity._id,
+                integrationRecord.userId
+            );
+            modules.push(moduleInstance);
+        }
+
+        const integrationInstance = new integrationClass({
+            id: integrationRecord._id,
+            userId: integrationRecord.userId,
+            entities: entities,
+            config: integrationRecord.config,
+            status: integrationRecord.status,
+            version: integrationRecord.version,
+            messages: integrationRecord.messages,
+            modules
+        });
+
+        return mapIntegrationClassToIntegrationDTO(integrationInstance);
+    }
+}
+
+module.exports = { GetIntegrationForUser }; 

package/integrations/use-cases/get-integration-instance-by-definition.js

@@ -0,0 +1,67 @@
+// Removed Integration wrapper - using IntegrationBase directly
+const Boom = require('@hapi/boom');
+
+/**
+ * Use case for retrieving a single integration by definition.
+ * @class GetIntegrationByDefinition
+ */
+class GetIntegrationInstanceByDefinition {
+    /**
+     * Creates a new GetIntegrationByDefinition instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../integration-repository-interface').IntegrationRepositoryInterface} params.integrationRepository - Repository for integration data operations.
+     * @param {import('../../modules/module-factory').ModuleFactory} params.moduleFactory - Service for module instantiation and management.
+     * @param {import('../../modules/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository - Repository for module and entity data operations.
+     */
+    constructor({ integrationRepository, moduleFactory, moduleRepository }) {
+
+        /**
+         * @type {import('../integration-repository-interface').IntegrationRepositoryInterface}
+         */
+        this.integrationRepository = integrationRepository;
+        this.moduleFactory = moduleFactory;
+        this.moduleRepository = moduleRepository;
+    }
+
+    /**
+     * Executes the retrieval of a single integration by definition.
+     * @async
+     * @returns {Promise<Object>} The integration DTO for the specified definition.
+     * @throws {Boom.notFound} When integration with the specified definition does not exist.
+     */
+    async execute(integrationClass) {
+        const integrationRecord = await this.integrationRepository.findIntegrationByName(integrationClass.Definition.name);
+
+        if (!integrationRecord) {
+            throw Boom.notFound(`Integration with name of ${integrationClass.Definition.name} does not exist`);
+        }
+
+        const entities = await this.moduleRepository.findEntitiesByIds(integrationRecord.entitiesIds);
+
+        const modules = [];
+        for (const entity of entities) {
+            const moduleInstance = await this.moduleFactory.getModuleInstance(
+                entity.id,
+                integrationRecord.userId
+            );
+            modules.push(moduleInstance);
+        }
+
+        const integrationInstance = new integrationClass({
+            id: integrationRecord.id,
+            userId: integrationRecord.userId,
+            entities: entities,
+            config: integrationRecord.config,
+            status: integrationRecord.status,
+            version: integrationRecord.version,
+            messages: integrationRecord.messages,
+            modules
+        });
+
+        await integrationInstance.initialize();
+
+        return integrationInstance
+    }
+}
+
+module.exports = { GetIntegrationInstanceByDefinition };