@friggframework/core 2.0.0-next.12 → 2.0.0-next.121

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

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

@@ -0,0 +1,83 @@
+// Removed Integration wrapper - using IntegrationBase directly
+
+/**
+ * Use case for retrieving a single integration instance by ID and user.
+ * @class GetIntegrationInstance
+ */
+class GetIntegrationInstance {
+    /**
+     * Creates a new GetIntegrationInstance instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface} params.integrationRepository - Repository for integration data access
+     * @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 }) {
+        this.integrationRepository = integrationRepository;
+        this.integrationClasses = integrationClasses;
+        this.moduleFactory = moduleFactory;
+    }
+
+    /**
+     * Executes the retrieval of a single integration instance.
+     * @async
+     * @param {string} integrationId - ID of the integration to retrieve.
+     * @param {string} userId - ID of the user requesting the integration.
+     * @returns {Promise<Integration>} The fully initialized integration instance.
+     * @throws {Error} When integration is not found, doesn't belong to user, or integration class is not found.
+     */
+    async execute(integrationId, userId) {
+        const integrationRecord =
+            await this.integrationRepository.findIntegrationById(integrationId);
+
+        if (!integrationRecord) {
+            throw new Error(
+                `No integration found by the ID of ${integrationId}`
+            );
+        }
+
+        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}`
+            );
+        }
+
+        if (integrationRecord.userId !== userId) {
+            throw new Error(
+                `Integration ${integrationId} does not belong to User ${userId}`
+            );
+        }
+
+        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();
+
+        return integrationInstance;
+    }
+}
+
+module.exports = { GetIntegrationInstance };

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

@@ -0,0 +1,88 @@
+// Removed Integration wrapper - using IntegrationBase directly
+const {
+    mapIntegrationClassToIntegrationDTO,
+} = require('../utils/map-integration-dto');
+
+/**
+ * Use case for retrieving all integrations for a specific user.
+ * @class GetIntegrationsForUser
+ */
+class GetIntegrationsForUser {
+    /**
+     * Creates a new GetIntegrationsForUser 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.
+     * @param {import('../../modules/repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository - Repository for module and entity data operations.
+     */
+    constructor({
+        integrationRepository,
+        integrationClasses,
+        moduleFactory,
+        moduleRepository,
+    }) {
+        /**
+         * @type {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface}
+         */
+        this.integrationRepository = integrationRepository;
+        this.integrationClasses = integrationClasses;
+        this.moduleFactory = moduleFactory;
+        this.moduleRepository = moduleRepository;
+    }
+
+    /**
+     * Executes the retrieval of all integrations for a user.
+     * @async
+     * @param {string} userId - ID of the user whose integrations to retrieve.
+     * @returns {Promise<Object[]>} Array of integration DTOs for the specified user.
+     */
+    async execute(userId) {
+        const integrationRecords =
+            await this.integrationRepository.findIntegrationsByUserId(userId);
+
+        const integrations = [];
+
+        for (const integrationRecord of integrationRecords) {
+            const entities = await this.moduleRepository.findEntitiesByIds(
+                integrationRecord.entitiesIds
+            );
+
+            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 integrationData = {
+                id: integrationRecord.id,
+                userId: integrationRecord.userId,
+                entities: entities,
+                config: integrationRecord.config,
+                status: integrationRecord.status,
+                version: integrationRecord.version,
+                messages: integrationRecord.messages || { errors: [], warnings: [] },
+                modules,
+                options: integrationClass.getOptionDetails(),
+            };
+
+            integrations.push(
+                mapIntegrationClassToIntegrationDTO(integrationData)
+            );
+        }
+
+        return integrations;
+    }
+}
+
+module.exports = { GetIntegrationsForUser };

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

@@ -0,0 +1,27 @@
+/**
+ * Use case for retrieving all possible integration types that can be created.
+ * @class GetPossibleIntegrations
+ */
+class GetPossibleIntegrations {
+    /**
+     * Creates a new GetPossibleIntegrations instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {Array<import('../integration').Integration>} params.integrationClasses - Array of available integration classes.
+     */
+    constructor({ integrationClasses }) {
+        this.integrationClasses = integrationClasses;
+    }
+
+    /**
+     * Executes the retrieval of all possible integration types.
+     * @async
+     * @returns {Promise<Object[]>} Array of integration option details for all available integration types.
+     */
+    async execute() {
+        return this.integrationClasses.map((integrationClass) =>
+            integrationClass.getOptionDetails()
+        );
+    }
+}
+
+module.exports = { GetPossibleIntegrations };

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

@@ -0,0 +1,89 @@
+/**
+ * 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);
+ */
+const { invalidProcessData, processNotFound } = require('./process-errors');
+
+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 invalidProcessData('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 processNotFound(`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 invalidProcessData('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/index.js

@@ -0,0 +1,19 @@
+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/list-integrations-by-entity-external-id.js

@@ -0,0 +1,46 @@
+/**
+ * List all integration IDs whose module entities match an externalId.
+ *
+ * Use this instead of {@link FindIntegrationByEntityExternalIdUseCase} when a
+ * single externalId is *expected* to map to multiple integrations (intentional
+ * fan-out: one upstream account broadcasting to several Frigg integration
+ * records, possibly across tenants).
+ *
+ * Does not throw on ambiguous resolution — that's the whole point.
+ */
+class ListIntegrationsByEntityExternalIdUseCase {
+    constructor({ integrationRepository, moduleRepository } = {}) {
+        if (!integrationRepository) {
+            throw new Error('integrationRepository is required');
+        }
+        if (!moduleRepository) {
+            throw new Error('moduleRepository is required');
+        }
+        this.integrationRepository = integrationRepository;
+        this.moduleRepository = moduleRepository;
+    }
+
+    async execute({ externalId, moduleName } = {}) {
+        if (!externalId) return [];
+
+        const filter = { externalId: String(externalId) };
+        if (moduleName) filter.moduleName = moduleName;
+
+        const entities = await this.moduleRepository.findEntities(filter);
+        if (!entities || entities.length === 0) return [];
+
+        const integrationIds = new Set();
+        for (const entity of entities) {
+            const owners =
+                await this.integrationRepository.findIntegrationsByEntityId(
+                    entity.id
+                );
+            for (const integration of owners || []) {
+                integrationIds.add(integration.id);
+            }
+        }
+        return Array.from(integrationIds);
+    }
+}
+
+module.exports = { ListIntegrationsByEntityExternalIdUseCase };

package/integrations/use-cases/load-integration-context.js

@@ -0,0 +1,71 @@
+class LoadIntegrationContextUseCase {
+    constructor({
+        integrationRepository,
+        moduleRepository,
+        moduleFactory,
+    }) {
+        if (!integrationRepository) {
+            throw new Error('integrationRepository is required');
+        }
+        if (!moduleRepository) {
+            throw new Error('moduleRepository is required');
+        }
+        if (!moduleFactory) {
+            throw new Error('moduleFactory is required');
+        }
+
+        this.integrationRepository = integrationRepository;
+        this.moduleRepository = moduleRepository;
+        this.moduleFactory = moduleFactory;
+    }
+
+    async execute({ integrationId, integrationRecord }) {
+        const record = integrationRecord
+            ? integrationRecord
+            : await this.integrationRepository.findIntegrationById(
+                  integrationId
+              );
+
+        if (!record) {
+            const error = new Error('Integration record not found');
+            error.code = 'INTEGRATION_RECORD_NOT_FOUND';
+            throw error;
+        }
+
+        if (
+            !Array.isArray(record.entitiesIds) ||
+            record.entitiesIds.length === 0
+        ) {
+            return {
+                record: {
+                    ...record,
+                    entities: [],
+                },
+                modules: [],
+            };
+        }
+
+        const entities = await this.moduleRepository.findEntitiesByIds(
+            record.entitiesIds
+        );
+
+        const modules = [];
+        for (const entity of entities) {
+            const moduleInstance = await this.moduleFactory.getModuleInstance(
+                entity.id,
+                record.userId
+            );
+            modules.push(moduleInstance);
+        }
+
+        return {
+            record: {
+                ...record,
+                entities,
+            },
+            modules,
+        };
+    }
+}
+
+module.exports = { LoadIntegrationContextUseCase };

package/integrations/use-cases/patch-integration-config.js

@@ -0,0 +1,39 @@
+/**
+ * Use case for atomically merging a partial update into an integration's
+ * configuration, leaving keys not present in the patch untouched.
+ *
+ * The merge is shallow: only top-level config keys are affected, and each
+ * key in the patch replaces its existing value wholesale (a nested object is
+ * overwritten as a block, not deep-merged). To change one field inside a
+ * nested object without dropping its siblings, pass the whole updated object
+ * as that key's value. A `null` value sets the key to null (clears the field
+ * without removing it); to remove a key entirely, use a full replace via
+ * UpdateIntegrationConfig instead.
+ * @class PatchIntegrationConfig
+ */
+class PatchIntegrationConfig {
+    /**
+     * Creates a new PatchIntegrationConfig instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface} params.integrationRepository - Repository for integration data operations.
+     */
+    constructor({ integrationRepository }) {
+        this.integrationRepository = integrationRepository;
+    }
+
+    /**
+     * Executes the config patch.
+     * @async
+     * @param {string} integrationId - ID of the integration to update.
+     * @param {Object} patch - Keys to merge into the existing config.
+     * @returns {Promise<Object>} The updated integration record.
+     */
+    async execute(integrationId, patch) {
+        return this.integrationRepository.patchIntegrationConfig(
+            integrationId,
+            patch
+        );
+    }
+}
+
+module.exports = { PatchIntegrationConfig };

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

@@ -0,0 +1,28 @@
+/**
+ * Process Error Helpers
+ *
+ * Constructs Errors carrying a stable `code` so the application layer
+ * (`createProcessCommands` → `mapErrorToResponse`) can translate domain
+ * failures into HTTP statuses:
+ *   - INVALID_PROCESS_DATA → 400 (caller-supplied data is invalid)
+ *   - PROCESS_NOT_FOUND    → 404 (the referenced process does not exist)
+ *
+ * Repository/infrastructure failures are intentionally left uncoded so
+ * they surface as 500s.
+ */
+
+function createCodedError(message, code) {
+    const error = new Error(message);
+    error.code = code;
+    return error;
+}
+
+function invalidProcessData(message) {
+    return createCodedError(message, 'INVALID_PROCESS_DATA');
+}
+
+function processNotFound(message) {
+    return createCodedError(message, 'PROCESS_NOT_FOUND');
+}
+
+module.exports = { invalidProcessData, processNotFound };