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

package/integrations/use-cases/remove-entities-from-integration.js

@@ -0,0 +1,70 @@
+const {
+    assertEntityIdsInput,
+    integrationNotFound,
+    loadIntegration,
+} = require('../utils/assert-entity-ids-input');
+
+/**
+ * Detaches entities from an integration. Entities that are not attached are
+ * ignored, and detached entities are not deleted. Every module the
+ * integration holds must keep at least one entity, so the integration can
+ * still hydrate each of its modules.
+ * @class RemoveEntitiesFromIntegration
+ */
+class RemoveEntitiesFromIntegration {
+    /**
+     * @param {Object} params
+     * @param {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface} params.integrationRepository
+     * @param {import('../../modules/repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
+     */
+    constructor({ integrationRepository, moduleRepository }) {
+        this.integrationRepository = integrationRepository;
+        this.moduleRepository = moduleRepository;
+    }
+
+    /**
+     * @param {string} integrationId
+     * @param {string[]} entityIds
+     * @returns {Promise<Object>} The updated integration record.
+     */
+    async execute(integrationId, entityIds) {
+        assertEntityIdsInput(integrationId, entityIds);
+
+        const integration = await loadIntegration(
+            this.integrationRepository,
+            integrationId
+        );
+
+        const removing = new Set(entityIds.map(String));
+        const attached = await this.moduleRepository.findEntitiesByIds(
+            integration.entitiesIds ?? []
+        );
+        const emptied = [...new Set(attached.map((e) => e.moduleName))].filter(
+            (moduleName) =>
+                !attached.some(
+                    (e) =>
+                        e.moduleName === moduleName &&
+                        !removing.has(String(e.id))
+                )
+        );
+        if (emptied.length > 0) {
+            const error = new Error(
+                `Removing these entities would leave no entity for module(s): ${emptied.join(
+                    ', '
+                )}`
+            );
+            error.code = 'LAST_ENTITY_OF_MODULE';
+            throw error;
+        }
+
+        const updated =
+            await this.integrationRepository.removeEntitiesFromIntegration(
+                integrationId,
+                entityIds
+            );
+        if (!updated) throw integrationNotFound(integrationId);
+        return updated;
+    }
+}
+
+module.exports = { RemoveEntitiesFromIntegration };

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

@@ -0,0 +1,32 @@
+/**
+ * Use case for replacing an integration's entire configuration. Keys not
+ * present in the new config are deleted — use PatchIntegrationConfig to
+ * merge a partial update without losing untouched keys.
+ * @class UpdateIntegrationConfig
+ */
+class UpdateIntegrationConfig {
+    /**
+     * Creates a new UpdateIntegrationConfig 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 full config replace.
+     * @async
+     * @param {string} integrationId - ID of the integration to update.
+     * @param {Object} config - The new configuration object.
+     * @returns {Promise<Object>} The updated integration record.
+     */
+    async execute(integrationId, config) {
+        return this.integrationRepository.updateIntegrationConfig(
+            integrationId,
+            config
+        );
+    }
+}
+
+module.exports = { UpdateIntegrationConfig };

package/integrations/use-cases/update-integration-messages.js

@@ -0,0 +1,44 @@
+/**
+ * Use case for updating messages associated with an integration.
+ * @class UpdateIntegrationMessages
+ */
+class UpdateIntegrationMessages {
+    /**
+     * Creates a new UpdateIntegrationMessages 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 integration messages update.
+     * @async
+     * @param {string} integrationId - ID of the integration to update.
+     * @param {string} messageType - Type of message: 'errors', 'warnings', 'info', or 'logs'.
+     * @param {string} messageTitle - Title of the message.
+     * @param {string} messageBody - Body content of the message.
+     * @param {string} messageTimestamp - Timestamp when the message was created.
+     * @returns {Promise<Object>} The updated integration record.
+     */
+    async execute(
+        integrationId,
+        messageType,
+        messageTitle,
+        messageBody,
+        messageTimestamp
+    ) {
+        const integration =
+            await this.integrationRepository.updateIntegrationMessages(
+                integrationId,
+                messageType,
+                messageTitle,
+                messageBody,
+                messageTimestamp
+            );
+        return integration;
+    }
+}
+
+module.exports = { UpdateIntegrationMessages };

package/integrations/use-cases/update-integration-status.js

@@ -0,0 +1,32 @@
+/**
+ * Use case for updating the status of an integration.
+ * @class UpdateIntegrationStatus
+ */
+class UpdateIntegrationStatus {
+    /**
+     * Creates a new UpdateIntegrationStatus 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 integration status update.
+     * @async
+     * @param {string} integrationId - ID of the integration to update.
+     * @param {string} status - New status for the integration (e.g., 'ENABLED', 'DISABLED', 'ERROR').
+     * @returns {Promise<Object>} The updated integration record.
+     */
+    async execute(integrationId, status) {
+        const integration =
+            await this.integrationRepository.updateIntegrationStatus(
+                integrationId,
+                status
+            );
+        return integration;
+    }
+}
+
+module.exports = { UpdateIntegrationStatus };

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

@@ -0,0 +1,92 @@
+const {
+    mapIntegrationClassToIntegrationDTO,
+} = require('../utils/map-integration-dto');
+
+/**
+ * Use case for updating a single integration by ID and user.
+ * @class UpdateIntegration
+ */
+class UpdateIntegration {
+    /**
+     * Creates a new UpdateIntegration 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 integration update process.
+     * @async
+     * @param {string} integrationId - ID of the integration to update.
+     * @param {string} userId - ID of the user requesting the update.
+     * @param {Object} config - New configuration object for the integration.
+     * @returns {Promise<Object>} The updated integration DTO.
+     * @throws {Error} When integration is not found, doesn't belong to user, or integration class is not found.
+     */
+    async execute(integrationId, userId, config) {
+        // 1. Get integration record from repository
+        const integrationRecord =
+            await this.integrationRepository.findIntegrationById(integrationId);
+
+        if (!integrationRecord) {
+            throw new Error(
+                `No integration found by the ID of ${integrationId}`
+            );
+        }
+
+        // 2. Get the correct Integration class by type
+        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}`
+            );
+        }
+
+        // 3. Load modules based on entity references
+        const modules = [];
+        for (const entityId of integrationRecord.entitiesIds) {
+            const moduleInstance = await this.moduleFactory.getModuleInstance(
+                entityId,
+                integrationRecord.userId
+            );
+            modules.push(moduleInstance);
+        }
+
+        // 4. Create the Integration domain entity with modules and existing config
+        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,
+        });
+
+        // 5. Complete async initialization and trigger update event
+        await integrationInstance.initialize();
+        await integrationInstance.send('ON_UPDATE', { config });
+
+        return mapIntegrationClassToIntegrationDTO(integrationInstance);
+    }
+}
+
+module.exports = { UpdateIntegration };

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

@@ -0,0 +1,222 @@
+/**
+ * UpdateProcessMetrics Use Case
+ *
+ * Updates process metrics atomically via
+ * `processRepository.applyProcessUpdate`. This is the race-safe
+ * replacement for the original read-modify-write implementation — the
+ * long-standing TODO about lost updates under concurrent writers is
+ * now resolved.
+ *
+ * Split into two phases:
+ *
+ *   1. Atomic phase — counters and bounded error history. Uses
+ *      $inc / $push+$slice (Mongo/DocumentDB) or jsonb_set with
+ *      arithmetic expressions (Postgres) in a single UPDATE ... RETURNING
+ *      so concurrent callers serialize at the DB layer.
+ *
+ *   2. Derived-fields phase — duration, recordsPerSecond,
+ *      estimatedCompletion. Computed from the post-atomic snapshot and
+ *      written through the same atomic primitive, scoped to only those
+ *      three paths. The values themselves stay best-effort (under
+ *      concurrent writers they reflect "whichever handler wrote last"),
+ *      but the write can no longer clobber another caller's counters.
+ *      Writing the full context/results blob here — as the legacy
+ *      `update()` path did — replayed phase 1's snapshot over the row and
+ *      permanently discarded increments landed in between.
+ *
+ * Optionally broadcasts progress via WebSocket service if provided.
+ *
+ * @example
+ * const updateMetrics = new UpdateProcessMetrics({ processRepository, websocketService });
+ * await updateMetrics.execute(processId, {
+ *   processed: 100,
+ *   success: 92,
+ *   errors: 5,
+ *   skipped: 3,
+ *   errorDetails: [{ contactId: 'abc', error: 'Missing email', timestamp: '...' }]
+ * });
+ */
+const { invalidProcessData, processNotFound } = require('./process-errors');
+
+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] - Records processed in this batch
+     * @param {number} [metricsUpdate.success=0] - Successful records
+     * @param {number} [metricsUpdate.errors=0] - Failed records
+     * @param {number} [metricsUpdate.skipped=0] - Intentionally-skipped
+     *     records (hash-match, dedupe, loop protection, etc.). Increments
+     *     `results.aggregateData.totalSkipped`. Distinct from errors so the
+     *     UI can show `processed = synced + failed + skipped` without
+     *     conflating intentional skips with failures.
+     * @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) {
+        if (!processId || typeof processId !== 'string') {
+            throw invalidProcessData('processId must be a non-empty string');
+        }
+        if (!metricsUpdate || typeof metricsUpdate !== 'object') {
+            throw invalidProcessData('metricsUpdate must be an object');
+        }
+
+        // Phase 1: atomic increments + bounded error history.
+        const increment = {};
+        const processed = metricsUpdate.processed || 0;
+        const success = metricsUpdate.success || 0;
+        const errors = metricsUpdate.errors || 0;
+        const skipped = metricsUpdate.skipped || 0;
+        if (processed) increment['context.processedRecords'] = processed;
+        if (success) increment['results.aggregateData.totalSynced'] = success;
+        if (errors) increment['results.aggregateData.totalFailed'] = errors;
+        if (skipped) increment['results.aggregateData.totalSkipped'] = skipped;
+
+        const pushSlice = {};
+        if (
+            Array.isArray(metricsUpdate.errorDetails) &&
+            metricsUpdate.errorDetails.length > 0
+        ) {
+            pushSlice['results.aggregateData.errors'] = {
+                values: metricsUpdate.errorDetails,
+                keepLast: 100,
+            };
+        }
+
+        const hasAtomicWork =
+            Object.keys(increment).length > 0 ||
+            Object.keys(pushSlice).length > 0;
+
+        let updatedProcess;
+        try {
+            if (hasAtomicWork) {
+                updatedProcess = await this.processRepository.applyProcessUpdate(
+                    processId,
+                    { increment, pushSlice }
+                );
+            } else {
+                // All-zero update (e.g., empty batch) — nothing to persist;
+                // just read current state for the derived-fields pass.
+                updatedProcess = await this.processRepository.findById(
+                    processId
+                );
+            }
+        } catch (error) {
+            throw new Error(
+                `Failed to update process metrics: ${error.message}`
+            );
+        }
+
+        if (!updatedProcess) {
+            throw processNotFound(`Process not found: ${processId}`);
+        }
+
+        // Phase 2: derived metrics. Written through the SAME atomic path
+        // as phase 1, touching ONLY the paths this phase owns. Writing the
+        // whole context/results blob here (as the legacy `update()` did)
+        // replayed phase 1's snapshot over the row and silently discarded
+        // any increment a concurrent caller had landed in between.
+        const context = updatedProcess.context || {};
+
+        if (context.processedRecords > 0 || context.totalRecords > 0) {
+            const startTime = new Date(
+                context.startTime || updatedProcess.createdAt
+            );
+            const elapsed = Date.now() - startTime.getTime();
+
+            const recordsPerSecond =
+                elapsed > 0 && context.processedRecords > 0
+                    ? context.processedRecords / (elapsed / 1000)
+                    : 0;
+
+            const set = {
+                'results.aggregateData.duration': elapsed,
+                'results.aggregateData.recordsPerSecond': recordsPerSecond,
+            };
+
+            if (
+                context.totalRecords > 0 &&
+                context.processedRecords > 0 &&
+                recordsPerSecond > 0
+            ) {
+                const remaining =
+                    context.totalRecords - context.processedRecords;
+                const etaMs = (remaining / recordsPerSecond) * 1000;
+                set['context.estimatedCompletion'] = new Date(
+                    Date.now() + etaMs
+                ).toISOString();
+            }
+
+            try {
+                const withDerived =
+                    await this.processRepository.applyProcessUpdate(processId, {
+                        set,
+                    });
+                if (withDerived) updatedProcess = withDerived;
+            } catch (error) {
+                // Derived-field write failures are NON-FATAL — atomic
+                // counters from phase 1 already landed. Log and return the
+                // post-atomic snapshot.
+                console.error(
+                    '[UpdateProcessMetrics] derived-fields write failed (non-fatal):',
+                    error.message
+                );
+            }
+        }
+
+        if (this.websocketService) {
+            await this._broadcastProgress(updatedProcess);
+        }
+
+        return updatedProcess;
+    }
+
+    /**
+     * Broadcast progress update via WebSocket
+     * @private
+     */
+    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,
+                    skippedCount: aggregateData.totalSkipped || 0,
+                    recordsPerSecond: aggregateData.recordsPerSecond || 0,
+                    estimatedCompletion: context.estimatedCompletion || null,
+                    timestamp: new Date().toISOString(),
+                },
+            });
+        } catch (error) {
+            console.error('Failed to broadcast process progress:', error);
+        }
+    }
+}
+
+module.exports = { UpdateProcessMetrics };

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

@@ -0,0 +1,163 @@
+/**
+ * UpdateProcessState Use Case
+ * 
+ * Updates the state of a process and optionally merges context updates.
+ * Handles state transitions in the process state machine.
+ * 
+ * Design Philosophy:
+ * - State transitions are explicit and tracked
+ * - Context updates are merged (not replaced) to preserve data
+ * - Repository handles persistence, use case handles business logic
+ * 
+ * State Machine (CRM Sync Example):
+ * INITIALIZING → FETCHING_TOTAL → QUEUING_PAGES → PROCESSING_BATCHES → 
+ * COMPLETING → COMPLETED
+ * 
+ * Any state can transition to ERROR on failure.
+ * 
+ * @example
+ * const updateProcessState = new UpdateProcessState({ processRepository });
+ * await updateProcessState.execute(processId, 'FETCHING_TOTAL', {
+ *   currentPage: 1,
+ *   pagination: { pageSize: 100 }
+ * });
+ */
+const { invalidProcessData, processNotFound } = require('./process-errors');
+
+class UpdateProcessState {
+    /**
+     * @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 update process state
+     * @param {string} processId - Process ID to update
+     * @param {string} newState - New state value
+     * @param {Object} [contextUpdates={}] - Context fields to merge
+     * @returns {Promise<Object>} Updated process record
+     * @throws {Error} If process not found or update fails
+     */
+    async execute(processId, newState, contextUpdates = {}) {
+        // Validate inputs
+        if (!processId || typeof processId !== 'string') {
+            throw invalidProcessData('processId must be a non-empty string');
+        }
+        if (!newState || typeof newState !== 'string') {
+            throw invalidProcessData('newState must be a non-empty string');
+        }
+        if (contextUpdates && typeof contextUpdates !== 'object') {
+            throw invalidProcessData('contextUpdates must be an object');
+        }
+
+        // Route through the atomic path when the repo supports it AND we
+        // have context keys to set. The atomic path writes the state
+        // column + the context field-sets in one DB round trip without
+        // read-modify-write, so a concurrent counter bump from
+        // UpdateProcessMetrics can't clobber our flags (e.g. `fetchDone`)
+        // or vice versa.
+        //
+        // Each context update key becomes a `set` at path
+        // `context.<key>` — matching the prior semantics of a shallow
+        // top-level merge (sub-objects were and still are replaced
+        // whole, not deep-merged).
+        const hasContextKeys =
+            contextUpdates && Object.keys(contextUpdates).length > 0;
+
+        if (
+            hasContextKeys &&
+            typeof this.processRepository.applyProcessUpdate === 'function'
+        ) {
+            const set = {};
+            for (const [key, value] of Object.entries(contextUpdates)) {
+                set[`context.${key}`] = value;
+            }
+            try {
+                const updated = await this.processRepository.applyProcessUpdate(
+                    processId,
+                    { set, newState }
+                );
+                if (!updated) {
+                    throw processNotFound(`Process not found: ${processId}`);
+                }
+                return updated;
+            } catch (error) {
+                if (error.code === 'PROCESS_NOT_FOUND') {
+                    throw error;
+                }
+                throw new Error(
+                    `Failed to update process state: ${error.message}`
+                );
+            }
+        }
+
+        // Legacy path (no contextUpdates or repo lacks applyProcessUpdate):
+        // preserve the original read-merge-write semantics for backward
+        // compatibility with any custom repos. Wrap the full read+write
+        // in try/catch so a findById error surfaces under the same
+        // "Failed to update process state" message as a write failure.
+        try {
+            const process = await this.processRepository.findById(processId);
+            if (!process) {
+                throw processNotFound(`Process not found: ${processId}`);
+            }
+
+            const updates = { state: newState };
+            if (hasContextKeys) {
+                updates.context = {
+                    ...process.context,
+                    ...contextUpdates,
+                };
+            }
+
+            return await this.processRepository.update(processId, updates);
+        } catch (error) {
+            // Re-throw "Process not found" as-is; wrap other errors.
+            if (error.code === 'PROCESS_NOT_FOUND') {
+                throw error;
+            }
+            throw new Error(`Failed to update process state: ${error.message}`);
+        }
+    }
+
+    /**
+     * Helper method to update state without context changes
+     * @param {string} processId - Process ID to update
+     * @param {string} newState - New state value
+     * @returns {Promise<Object>} Updated process record
+     */
+    async updateStateOnly(processId, newState) {
+        return this.execute(processId, newState, {});
+    }
+
+    /**
+     * Helper method to update context without changing state
+     * @param {string} processId - Process ID to update
+     * @param {Object} contextUpdates - Context fields to merge
+     * @returns {Promise<Object>} Updated process record
+     */
+    async updateContextOnly(processId, contextUpdates) {
+        const process = await this.processRepository.findById(processId);
+        if (!process) {
+            throw processNotFound(`Process not found: ${processId}`);
+        }
+
+        const updates = {
+            context: {
+                ...process.context,
+                ...contextUpdates,
+            },
+        };
+
+        return this.processRepository.update(processId, updates);
+    }
+}
+
+module.exports = { UpdateProcessState };
+