@friggframework/core 2.0.0-next.5 → 2.0.0-next.50

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

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

@@ -0,0 +1,119 @@
+/**
+ * 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 }
+ * });
+ */
+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 new Error('processId must be a non-empty string');
+        }
+        if (!newState || typeof newState !== 'string') {
+            throw new Error('newState must be a non-empty string');
+        }
+        if (contextUpdates && typeof contextUpdates !== 'object') {
+            throw new Error('contextUpdates must be an object');
+        }
+
+        // Retrieve current process
+        const process = await this.processRepository.findById(processId);
+        if (!process) {
+            throw new Error(`Process not found: ${processId}`);
+        }
+
+        // Prepare updates
+        const updates = {
+            state: newState,
+        };
+
+        // Merge context updates if provided
+        if (contextUpdates && Object.keys(contextUpdates).length > 0) {
+            updates.context = {
+                ...process.context,
+                ...contextUpdates,
+            };
+        }
+
+        // Persist updates
+        try {
+            const updatedProcess = await this.processRepository.update(processId, updates);
+            return updatedProcess;
+        } catch (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 new Error(`Process not found: ${processId}`);
+        }
+
+        const updates = {
+            context: {
+                ...process.context,
+                ...contextUpdates,
+            },
+        };
+
+        return this.processRepository.update(processId, updates);
+    }
+}
+
+module.exports = { UpdateProcessState };
+

package/integrations/utils/map-integration-dto.js

@@ -0,0 +1,36 @@
+/**
+ * @param {import('../integration').Integration} integration
+ * Convert an Integration domain instance to a plain DTO suitable for JSON responses.
+ */
+function mapIntegrationClassToIntegrationDTO(integration) {
+    if (!integration) return null;
+
+    return {
+        id: integration.id,
+        userId: integration.userId,
+        entities: integration.entities,
+        config: integration.config,
+        status: integration.status,
+        version: integration.version,
+        messages: integration.messages,
+        userActions: integration.userActions,
+        options: integration.getOptionDetails(),
+    };
+}
+
+
+const getModulesDefinitionFromIntegrationClasses = (integrationClasses) => {
+    return [
+        ...new Set(
+            integrationClasses
+                .map((integration) =>
+                    Object.values(integration.Definition.modules).map(
+                        (module) => module.definition
+                    )
+                )
+                .flat()
+        ),
+    ];
+};
+
+module.exports = { mapIntegrationClassToIntegrationDTO, getModulesDefinitionFromIntegrationClasses }; 

package/jest-global-setup-noop.js

@@ -0,0 +1,3 @@
+module.exports = async function noopGlobalSetup() {
+    // No global setup required for unit tests.
+};

package/jest-global-teardown-noop.js

@@ -0,0 +1,3 @@
+module.exports = async function noopGlobalTeardown() {
+    // No global teardown required for unit tests.
+};

package/logs/logger.js

@@ -1,5 +1,4 @@
 const util = require('util');
-const aws = require('aws-sdk');
 
 // Except in some outlier circumstances, for example steam or event error handlers, this should be the only place that calls `console.*`.  That way, this file can be modified to log everything properly on a variety of platforms because all the logging code is here in one place.
 /* eslint-disable no-console */
@@ -7,9 +6,6 @@ const aws = require('aws-sdk');
 const logs = [];
 let flushCalled = false;
 
-// Log AWS SDK calls
-aws.config.logger = { log: debug };
-
 function debug(...messages) {
     if (messages.length) {
         const date = new Date();

package/{module-plugin → modules}/entity.js

@@ -6,13 +6,13 @@ const schema = new mongoose.Schema(
             ref: 'Credential',
             required: false,
         },
-        subType: { type: String },
         user: {
             type: mongoose.Schema.Types.ObjectId,
             ref: 'User',
             required: false,
         },
         name: { type: String },
+        moduleName: { type: String },
         externalId: { type: String },
     },
     { timestamps: true }

package/{module-plugin → modules}/index.js

@@ -1,25 +1,17 @@
-const { Credential } = require('./credential');
-const { EntityManager } = require('./entity-manager');
 const { Entity } = require('./entity');
-const { ModuleManager } = require('./manager');
 const { ApiKeyRequester } = require('./requester/api-key');
 const { BasicAuthRequester } = require('./requester/basic');
 const { OAuth2Requester } = require('./requester/oauth-2');
 const { Requester } = require('./requester/requester');
 const { ModuleConstants } = require('./ModuleConstants');
 const { ModuleFactory } = require('./module-factory');
-const { Auther } = require('./auther');
 
 module.exports = {
-    Credential,
-    EntityManager,
     Entity,
-    ModuleManager,
     ApiKeyRequester,
     BasicAuthRequester,
     OAuth2Requester,
     Requester,
     ModuleConstants,
     ModuleFactory,
-    Auther
 };