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

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

@@ -0,0 +1,253 @@
+// 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. Reuses an existing
+     * integration when one already exists for the same userId, config.type,
+     * and entity set, instead of creating a duplicate.
+     * @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 or reused integration DTO.
+     * @throws {Error} When integration class is not found for the specified type.
+     */
+    async execute(entities, userId, config) {
+        console.log(
+            `[Frigg] Creating ${config?.type} integration for user ${userId} with entities [${entities}]`
+        );
+
+        const existing = await this._findDuplicate(
+            userId,
+            config?.type,
+            entities
+        );
+        if (existing) {
+            console.log(
+                `[Frigg] Found existing integration ${existing.id} for the same user, type, and entities — reusing it`
+            );
+            return this._reuseExisting(existing, config);
+        }
+
+        const integrationRecord =
+            await this.integrationRepository.createIntegration(
+                entities,
+                userId,
+                config
+            );
+        console.log(
+            `[Frigg] Created integration ${integrationRecord.id} for user ${userId}`
+        );
+
+        // A concurrent request may have created a matching row between the
+        // lookup above and this insert; re-check before any side effects run.
+        const survivor = await this._findSurvivor(
+            userId,
+            config?.type,
+            entities
+        );
+        if (survivor && String(survivor.id) !== String(integrationRecord.id)) {
+            console.log(
+                `[Frigg] Concurrent create detected — deleting duplicate ${integrationRecord.id} and reusing ${survivor.id}`
+            );
+            await this.integrationRepository.deleteIntegrationById(
+                integrationRecord.id
+            );
+            return this._reuseExisting(survivor, config);
+        }
+
+        const integrationInstance = await this._buildInstance(
+            integrationRecord
+        );
+        console.log(
+            `[Frigg] Sending ON_CREATE for integration ${integrationRecord.id}`
+        );
+        await integrationInstance.send('ON_CREATE', {
+            integrationId: integrationRecord.id,
+        });
+
+        return mapIntegrationClassToIntegrationDTO(integrationInstance);
+    }
+
+    async _reuseExisting(integrationRecord, config) {
+        // The caller may be reconnecting with changed settings. Persist the
+        // requested config onto the reused row as a shallow patch, so new
+        // values take effect while keys added during the original create
+        // (webhook ids, secrets) survive. `type` is re-written to the same
+        // value it dedupe-matched on, which is a harmless no-op.
+        if (config && Object.keys(config).length > 0) {
+            integrationRecord =
+                await this.integrationRepository.patchIntegrationConfig(
+                    integrationRecord.id,
+                    config
+                );
+        }
+
+        const integrationInstance = await this._buildInstance(
+            integrationRecord
+        );
+
+        if (integrationInstance.status === 'IN_CREATION') {
+            // ON_CREATE never finished for this row (crashed mid-setup or is
+            // still running concurrently). Re-firing ON_CREATE here would
+            // risk re-registering a webhook a partially-completed attempt
+            // already created — unsafe without idempotent setup, which is a
+            // separate, larger change. Surfaced loudly rather than silently
+            // reused as if healthy, so it's diagnosable; testAuth below still
+            // runs and can at least surface bad credentials as ERROR.
+            console.warn(
+                `[Frigg] Integration ${integrationInstance.id} is still IN_CREATION on reuse — setup never completed`
+            );
+        }
+
+        // User is actively trying to reconnect; here if the integration is
+        // disabled, we can enable it again.
+        const authPassed = await integrationInstance.testAuth();
+        await integrationInstance.reconcileAuthStatus(authPassed);
+        if (integrationInstance.status === 'DISABLED') {
+            console.log(
+                `[Frigg] Integration ${integrationInstance.id} changed status from DISABLED to ENABLED`
+            );
+            await integrationInstance.persistStatus('ENABLED');
+        }
+
+        return mapIntegrationClassToIntegrationDTO(integrationInstance);
+    }
+
+    async _findMatches(userId, type, entityIds) {
+        const candidates =
+            await this.integrationRepository.findIntegrationsByUserId(userId);
+        const target = new Set((entityIds ?? []).map(String));
+
+        const live = candidates.filter(
+            (integration) =>
+                // An IN_DELETION row is either mid-teardown or a zombie left
+                // behind by a failed deleteIntegrationById call — never a live
+                // integration. Treating it as a duplicate would hand a
+                // reinstall attempt a row nothing will ever move out of
+                // IN_DELETION, silently discarded by the queue worker forever.
+                // Let a fresh create proceed instead; the zombie is cleaned up
+                // out-of-band, matching how teardown failures are already
+                // handled here.
+                integration.status !== 'IN_DELETION' &&
+                integration.config?.type === type
+        );
+        const entitySet = (integration) =>
+            new Set((integration.entitiesIds ?? []).map(String));
+
+        const exact = live.filter((integration) => {
+            const current = entitySet(integration);
+            return (
+                current.size === target.size &&
+                [...target].every((id) => current.has(id))
+            );
+        });
+
+        // Entities may have been attached after create (addEntitiesToIntegration),
+        // so a reconnect that sends the original entities must still find the
+        // integration that now holds them, instead of creating a second one
+        // that would share those entities.
+        const supersets = live.filter((integration) => {
+            const current = entitySet(integration);
+            return [...target].every((id) => current.has(id));
+        });
+        return { exact, supersets: target.size ? supersets : [] };
+    }
+
+    async _findDuplicate(userId, type, entityIds) {
+        const { exact, supersets } = await this._findMatches(
+            userId,
+            type,
+            entityIds
+        );
+        if (exact.length) return this._pickOldest(exact);
+        return supersets.length ? this._pickOldest(supersets) : null;
+    }
+
+    // After an insert the new row is itself an exact match, so the survivor
+    // is the oldest of every exact or superset match (the new row included):
+    // an older integration that already holds these entities always wins.
+    async _findSurvivor(userId, type, entityIds) {
+        const { exact, supersets } = await this._findMatches(
+            userId,
+            type,
+            entityIds
+        );
+        // supersets includes the exact matches; it is empty only for an
+        // empty entity set, where exact matching alone applies.
+        const matches = supersets.length ? supersets : exact;
+        return matches.length ? this._pickOldest(matches) : null;
+    }
+
+    _pickOldest(records) {
+        return [...records].sort((a, b) => {
+            const diff =
+                new Date(a.createdAt ?? 0) - new Date(b.createdAt ?? 0);
+            if (diff !== 0) return diff;
+            return String(a.id).localeCompare(String(b.id), 'en', {
+                numeric: true,
+            });
+        })[0];
+    }
+
+    async _buildInstance(integrationRecord) {
+        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();
+
+        return integrationInstance;
+    }
+}
+
+module.exports = { CreateIntegration };

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

@@ -0,0 +1,130 @@
+/**
+ * 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 } }
+ * });
+ */
+const { invalidProcessData } = require('./process-errors');
+
+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 invalidProcessData(
+                `Missing required fields for process creation: ${missingFields.join(', ')}`
+            );
+        }
+
+        // Validate field types
+        if (typeof processData.userId !== 'string') {
+            throw invalidProcessData('userId must be a string');
+        }
+        if (typeof processData.integrationId !== 'string') {
+            throw invalidProcessData('integrationId must be a string');
+        }
+        if (typeof processData.name !== 'string') {
+            throw invalidProcessData('name must be a string');
+        }
+        if (typeof processData.type !== 'string') {
+            throw invalidProcessData('type must be a string');
+        }
+
+        // Validate optional fields if provided
+        if (processData.state && typeof processData.state !== 'string') {
+            throw invalidProcessData('state must be a string');
+        }
+        if (processData.context && typeof processData.context !== 'object') {
+            throw invalidProcessData('context must be an object');
+        }
+        if (processData.results && typeof processData.results !== 'object') {
+            throw invalidProcessData('results must be an object');
+        }
+        if (processData.childProcesses && !Array.isArray(processData.childProcesses)) {
+            throw invalidProcessData('childProcesses must be an array');
+        }
+        if (processData.parentProcessId && typeof processData.parentProcessId !== 'string') {
+            throw invalidProcessData('parentProcessId must be a string');
+        }
+    }
+}
+
+module.exports = { CreateProcess };
+

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

@@ -0,0 +1,130 @@
+const Boom = require('@hapi/boom');
+const { getLogger } = require('../../logs');
+
+const log = getLogger('frigg.integrations');
+// 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) {
+                log.warn('Failed to load module for deletion', {
+                    eventName: 'frigg.integrations.delete_module_load_failed',
+                    integrationId,
+                    entityId,
+                    error,
+                });
+                failedModuleLoads.push({ entityId, error: error.message });
+            }
+        }
+
+        if (failedModuleLoads.length > 0) {
+            log.warn(
+                'Some modules failed to load. Webhooks for these modules may require manual cleanup.',
+                {
+                    eventName: 'frigg.integrations.delete_modules_incomplete',
+                    integrationId,
+                    failedCount: failedModuleLoads.length,
+                    totalCount: integrationRecord.entitiesIds.length,
+                }
+            );
+        }
+
+        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.persistStatus('IN_DELETION');
+        try {
+            await integrationInstance.send('ON_DELETE');
+        } catch (error) {
+            // The error text can echo a request with its credentials and
+            // messages reach end users; the boundary logs the cause once.
+            await integrationInstance.updateIntegrationMessages.execute(
+                integrationId,
+                'errors',
+                'Integration Deletion Error',
+                'Deletion did not complete. Contact support.',
+                Date.now()
+            );
+            throw new Error(
+                `Integration ${integrationId} deletion did not complete`,
+                { cause: error }
+            );
+        }
+
+        await this.integrationRepository.deleteIntegrationById(integrationId);
+    }
+}
+
+module.exports = { DeleteIntegrationForUser };

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

@@ -0,0 +1,74 @@
+/**
+ * Reverse-lookup use case: resolve an externalId (e.g. HubSpot portalId,
+ * Slack team_id, Asana workspace_id) to a single integration ID.
+ *
+ * Refuses to pick on ambiguous resolution at either layer:
+ *   - more than one matching Entity row for the (externalId, moduleName) tuple
+ *   - more than one Integration owning the matched entity
+ *
+ * A silent first-match in either case is a cross-tenant routing risk.
+ * Callers that expect a one-to-many fan-out should use
+ * {@link ListIntegrationsByEntityExternalIdUseCase} instead.
+ */
+class FindIntegrationByEntityExternalIdUseCase {
+    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 null;
+
+        const filter = { externalId: String(externalId) };
+        if (moduleName) filter.moduleName = moduleName;
+
+        const entities = await this.moduleRepository.findEntities(filter);
+        if (!entities || entities.length === 0) {
+            console.log(
+                `[Frigg] findIntegrationByEntityExternalId: no entity for externalId=${externalId}${
+                    moduleName ? ` moduleName=${moduleName}` : ''
+                }`
+            );
+            return null;
+        }
+        if (entities.length > 1) {
+            const ids = entities.map((e) => e.id).join(', ');
+            throw new Error(
+                `findIntegrationByEntityExternalId: ambiguous resolution — externalId=${externalId}` +
+                    `${moduleName ? ` moduleName=${moduleName}` : ''} matches ${entities.length} entities [${ids}]. ` +
+                    `Refusing to pick one to avoid cross-tenant routing. ` +
+                    `Pass a moduleName, or use listIntegrationsByEntityExternalId if multiple integrations are expected.`
+            );
+        }
+
+        const entity = entities[0];
+        const integrations =
+            await this.integrationRepository.findIntegrationsByEntityId(
+                entity.id
+            );
+        if (!integrations || integrations.length === 0) {
+            console.log(
+                `[Frigg] findIntegrationByEntityExternalId: entity ${entity.id} has no owning integrations (orphan)`
+            );
+            return null;
+        }
+        if (integrations.length > 1) {
+            const ids = integrations.map((i) => i.id).join(', ');
+            throw new Error(
+                `findIntegrationByEntityExternalId: ambiguous resolution — externalId=${externalId}` +
+                    `${moduleName ? ` moduleName=${moduleName}` : ''} maps to ${integrations.length} integrations [${ids}]. ` +
+                    `Refusing to pick one to avoid cross-tenant routing. ` +
+                    `Use listIntegrationsByEntityExternalId if a one-to-many fan-out is intended.`
+            );
+        }
+        return integrations[0].id;
+    }
+}
+
+module.exports = { FindIntegrationByEntityExternalIdUseCase };

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

@@ -0,0 +1,76 @@
+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({ externalId, type }) {
+        if (!externalId) {
+            const error = new Error('externalId is required');
+            error.code = 'EXTERNAL_ID_REQUIRED';
+            throw error;
+        }
+
+        if (!type) {
+            const error = new Error('type is required');
+            error.code = 'TYPE_REQUIRED';
+            throw error;
+        }
+
+        const entity = await this.moduleRepository.findEntity({
+            externalId,
+        });
+
+        if (!entity) {
+            const error = new Error(
+                `Entity not found for externalId: ${externalId}`
+            );
+            error.code = 'ENTITY_NOT_FOUND';
+            throw error;
+        }
+
+        const integrations =
+            await this.integrationRepository.findIntegrationsByEntityId(
+                entity.id
+            );
+
+        const integrationRecord = integrations?.find(
+            (i) => i.config?.type === type
+        );
+
+        if (!integrationRecord) {
+            const error = new Error(
+                `Integration of type '${type}' not found for entity: ${entity.id}`
+            );
+            error.code = 'INTEGRATION_NOT_FOUND';
+            throw error;
+        }
+
+        const context = await this.loadIntegrationContextUseCase.execute({
+            integrationRecord,
+        });
+
+        return {
+            context,
+            entity,
+            record: integrationRecord,
+        };
+    }
+}
+
+module.exports = { FindIntegrationContextByExternalEntityIdUseCase };