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

package/integrations/repositories/process-repository-interface.js

@@ -0,0 +1,90 @@
+/**
+ * ProcessRepository Interface
+ * 
+ * Defines the contract for Process data access operations.
+ * Implementations must provide concrete methods for all operations.
+ * 
+ * This interface supports the Hexagonal Architecture pattern by:
+ * - Defining clear boundaries between domain logic and data access
+ * - Allowing multiple implementations (MongoDB, PostgreSQL, in-memory)
+ * - Enabling dependency injection and testability
+ */
+class ProcessRepositoryInterface {
+    /**
+     * Create a new process record
+     * @param {Object} processData - Process data to create
+     * @param {string} processData.userId - User ID
+     * @param {string} processData.integrationId - Integration ID
+     * @param {string} processData.name - Process name
+     * @param {string} processData.type - Process type
+     * @param {string} processData.state - 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
+     */
+    async create(processData) {
+        throw new Error('Method create() must be implemented');
+    }
+
+    /**
+     * Find a process by ID
+     * @param {string} processId - Process ID to find
+     * @returns {Promise<Object|null>} Process record or null if not found
+     */
+    async findById(processId) {
+        throw new Error('Method findById() must be implemented');
+    }
+
+    /**
+     * Update a process record
+     * @param {string} processId - Process ID to update
+     * @param {Object} updates - Fields to update
+     * @returns {Promise<Object>} Updated process record
+     */
+    async update(processId, updates) {
+        throw new Error('Method update() must be implemented');
+    }
+
+    /**
+     * Find processes by integration and type
+     * @param {string} integrationId - Integration ID
+     * @param {string} type - Process type
+     * @returns {Promise<Array>} Array of process records
+     */
+    async findByIntegrationAndType(integrationId, type) {
+        throw new Error('Method findByIntegrationAndType() must be implemented');
+    }
+
+    /**
+     * Find active processes (not in excluded states)
+     * @param {string} integrationId - Integration ID
+     * @param {string[]} [excludeStates=['COMPLETED', 'ERROR']] - States to exclude
+     * @returns {Promise<Array>} Array of active process records
+     */
+    async findActiveProcesses(integrationId, excludeStates = ['COMPLETED', 'ERROR']) {
+        throw new Error('Method findActiveProcesses() must be implemented');
+    }
+
+    /**
+     * Find a process by name (most recent)
+     * @param {string} name - Process name
+     * @returns {Promise<Object|null>} Most recent process with given name, or null
+     */
+    async findByName(name) {
+        throw new Error('Method findByName() must be implemented');
+    }
+
+    /**
+     * Delete a process by ID
+     * @param {string} processId - Process ID to delete
+     * @returns {Promise<void>}
+     */
+    async deleteById(processId) {
+        throw new Error('Method deleteById() must be implemented');
+    }
+}
+
+module.exports = { ProcessRepositoryInterface };
+

package/integrations/repositories/process-repository-mongo.js

@@ -0,0 +1,190 @@
+const { prisma } = require('../../database/prisma');
+const { ProcessRepositoryInterface } = require('./process-repository-interface');
+
+/**
+ * MongoDB Process Repository Adapter
+ * Handles process persistence using Prisma with MongoDB
+ *
+ * MongoDB-specific characteristics:
+ * - Uses scalar fields for relations (userId, integrationId)
+ * - IDs are strings with @db.ObjectId
+ * - JSON fields for flexible context and results storage
+ * - Array field for childProcesses references
+ *
+ * Design Philosophy:
+ * - Generic Process model supports any type of long-running operation
+ * - Context and results stored as JSON for maximum flexibility
+ * - Integration-specific logic lives in use cases and services
+ */
+class ProcessRepositoryMongo extends ProcessRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    /**
+     * Create a new process record
+     * @param {Object} processData - Process data to create
+     * @returns {Promise<Object>} Created process record
+     */
+    async create(processData) {
+        const process = await this.prisma.process.create({
+            data: {
+                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,
+            },
+        });
+
+        return this._toPlainObject(process);
+    }
+
+    /**
+     * Find a process by ID
+     * @param {string} processId - Process ID to find
+     * @returns {Promise<Object|null>} Process record or null if not found
+     */
+    async findById(processId) {
+        const process = await this.prisma.process.findUnique({
+            where: { id: processId },
+        });
+
+        return process ? this._toPlainObject(process) : null;
+    }
+
+    /**
+     * Update a process record
+     * @param {string} processId - Process ID to update
+     * @param {Object} updates - Fields to update
+     * @returns {Promise<Object>} Updated process record
+     */
+    async update(processId, updates) {
+        // Prepare update data, excluding undefined values
+        const updateData = {};
+
+        if (updates.state !== undefined) {
+            updateData.state = updates.state;
+        }
+        if (updates.context !== undefined) {
+            updateData.context = updates.context;
+        }
+        if (updates.results !== undefined) {
+            updateData.results = updates.results;
+        }
+        if (updates.childProcesses !== undefined) {
+            updateData.childProcesses = updates.childProcesses;
+        }
+        if (updates.parentProcessId !== undefined) {
+            updateData.parentProcessId = updates.parentProcessId;
+        }
+
+        const process = await this.prisma.process.update({
+            where: { id: processId },
+            data: updateData,
+        });
+
+        return this._toPlainObject(process);
+    }
+
+    /**
+     * Find processes by integration and type
+     * @param {string} integrationId - Integration ID
+     * @param {string} type - Process type
+     * @returns {Promise<Array>} Array of process records
+     */
+    async findByIntegrationAndType(integrationId, type) {
+        const processes = await this.prisma.process.findMany({
+            where: {
+                integrationId,
+                type,
+            },
+            orderBy: {
+                createdAt: 'desc',
+            },
+        });
+
+        return processes.map((p) => this._toPlainObject(p));
+    }
+
+    /**
+     * Find active processes (not in excluded states)
+     * @param {string} integrationId - Integration ID
+     * @param {string[]} [excludeStates=['COMPLETED', 'ERROR']] - States to exclude
+     * @returns {Promise<Array>} Array of active process records
+     */
+    async findActiveProcesses(integrationId, excludeStates = ['COMPLETED', 'ERROR']) {
+        const processes = await this.prisma.process.findMany({
+            where: {
+                integrationId,
+                state: {
+                    notIn: excludeStates,
+                },
+            },
+            orderBy: {
+                createdAt: 'desc',
+            },
+        });
+
+        return processes.map((p) => this._toPlainObject(p));
+    }
+
+    /**
+     * Find a process by name (most recent)
+     * @param {string} name - Process name
+     * @returns {Promise<Object|null>} Most recent process with given name, or null
+     */
+    async findByName(name) {
+        const process = await this.prisma.process.findFirst({
+            where: { name },
+            orderBy: {
+                createdAt: 'desc',
+            },
+        });
+
+        return process ? this._toPlainObject(process) : null;
+    }
+
+    /**
+     * Delete a process by ID
+     * @param {string} processId - Process ID to delete
+     * @returns {Promise<void>}
+     */
+    async deleteById(processId) {
+        await this.prisma.process.delete({
+            where: { id: processId },
+        });
+    }
+
+    /**
+     * Convert Prisma model to plain JavaScript object
+     * Ensures consistent API across repository implementations
+     * @private
+     * @param {Object} process - Prisma process model
+     * @returns {Object} Plain process object
+     */
+    _toPlainObject(process) {
+        return {
+            id: process.id,
+            userId: process.userId,
+            integrationId: process.integrationId,
+            name: process.name,
+            type: process.type,
+            state: process.state,
+            context: process.context,
+            results: process.results,
+            childProcesses: process.childProcesses,
+            parentProcessId: process.parentProcessId,
+            createdAt: process.createdAt,
+            updatedAt: process.updatedAt,
+        };
+    }
+}
+
+module.exports = { ProcessRepositoryMongo };
+

package/integrations/repositories/process-repository-postgres.js

@@ -0,0 +1,217 @@
+const { prisma } = require('../../database/prisma');
+const {
+    ProcessRepositoryInterface,
+} = require('./process-repository-interface');
+
+/**
+ * PostgreSQL Process Repository Adapter
+ * Handles process persistence using Prisma with PostgreSQL
+ *
+ * PostgreSQL-specific characteristics:
+ * - Uses foreign key constraints for relations
+ * - JSONB type for context and results (efficient querying)
+ * - Array type for childProcesses references
+ * - Transactional support available if needed
+ *
+ * Design Philosophy:
+ * - Same interface as MongoDB repository
+ * - Prisma abstracts away most database-specific details
+ * - Minor differences in JSON handling internally managed by Prisma
+ */
+class ProcessRepositoryPostgres extends ProcessRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    /**
+     * Convert string ID to integer for PostgreSQL queries
+     * @private
+     * @param {string|number|null|undefined} id - ID to convert
+     * @returns {number|null|undefined} Integer ID or null/undefined
+     * @throws {Error} If ID cannot be converted to integer
+     */
+    _convertId(id) {
+        if (id === null || id === undefined) return id;
+        const parsed = parseInt(id, 10);
+        if (isNaN(parsed)) {
+            throw new Error(`Invalid ID: ${id} cannot be converted to integer`);
+        }
+        return parsed;
+    }
+
+    /**
+     * Create a new process record
+     * @param {Object} processData - Process data to create
+     * @returns {Promise<Object>} Created process record
+     */
+    async create(processData) {
+        const process = await this.prisma.process.create({
+            data: {
+                userId: this._convertId(processData.userId),
+                integrationId: this._convertId(processData.integrationId),
+                name: processData.name,
+                type: processData.type,
+                state: processData.state || 'INITIALIZING',
+                context: processData.context || {},
+                results: processData.results || {},
+                parentProcessId: this._convertId(processData.parentProcessId),
+            },
+        });
+
+        return this._toPlainObject(process);
+    }
+
+    /**
+     * Find a process by ID
+     * @param {string} processId - Process ID to find
+     * @returns {Promise<Object|null>} Process record or null if not found
+     */
+    async findById(processId) {
+        const process = await this.prisma.process.findUnique({
+            where: { id: this._convertId(processId) },
+        });
+
+        return process ? this._toPlainObject(process) : null;
+    }
+
+    /**
+     * Update a process record
+     * @param {string} processId - Process ID to update
+     * @param {Object} updates - Fields to update
+     * @returns {Promise<Object>} Updated process record
+     */
+    async update(processId, updates) {
+        // Prepare update data, excluding undefined values
+        const updateData = {};
+
+        if (updates.state !== undefined) {
+            updateData.state = updates.state;
+        }
+        if (updates.context !== undefined) {
+            updateData.context = updates.context;
+        }
+        if (updates.results !== undefined) {
+            updateData.results = updates.results;
+        }
+        if (updates.parentProcessId !== undefined) {
+            updateData.parentProcessId = this._convertId(
+                updates.parentProcessId
+            );
+        }
+
+        const process = await this.prisma.process.update({
+            where: { id: this._convertId(processId) },
+            data: updateData,
+        });
+
+        return this._toPlainObject(process);
+    }
+
+    /**
+     * Find processes by integration and type
+     * @param {string} integrationId - Integration ID
+     * @param {string} type - Process type
+     * @returns {Promise<Array>} Array of process records
+     */
+    async findByIntegrationAndType(integrationId, type) {
+        const processes = await this.prisma.process.findMany({
+            where: {
+                integrationId: this._convertId(integrationId),
+                type,
+            },
+            orderBy: {
+                createdAt: 'desc',
+            },
+        });
+
+        return processes.map((p) => this._toPlainObject(p));
+    }
+
+    /**
+     * Find active processes (not in excluded states)
+     * @param {string} integrationId - Integration ID
+     * @param {string[]} [excludeStates=['COMPLETED', 'ERROR']] - States to exclude
+     * @returns {Promise<Array>} Array of active process records
+     */
+    async findActiveProcesses(
+        integrationId,
+        excludeStates = ['COMPLETED', 'ERROR']
+    ) {
+        const processes = await this.prisma.process.findMany({
+            where: {
+                integrationId: this._convertId(integrationId),
+                state: {
+                    notIn: excludeStates,
+                },
+            },
+            orderBy: {
+                createdAt: 'desc',
+            },
+        });
+
+        return processes.map((p) => this._toPlainObject(p));
+    }
+
+    /**
+     * Find a process by name (most recent)
+     * @param {string} name - Process name
+     * @returns {Promise<Object|null>} Most recent process with given name, or null
+     */
+    async findByName(name) {
+        const process = await this.prisma.process.findFirst({
+            where: { name },
+            orderBy: {
+                createdAt: 'desc',
+            },
+        });
+
+        return process ? this._toPlainObject(process) : null;
+    }
+
+    /**
+     * Delete a process by ID
+     * @param {string} processId - Process ID to delete
+     * @returns {Promise<void>}
+     */
+    async deleteById(processId) {
+        await this.prisma.process.delete({
+            where: { id: this._convertId(processId) },
+        });
+    }
+
+    /**
+     * Convert Prisma model to plain JavaScript object
+     * Ensures consistent API across repository implementations
+     * @private
+     * @param {Object} process - Prisma process model
+     * @returns {Object} Plain process object
+     */
+    _toPlainObject(process) {
+        return {
+            id: String(process.id),
+            userId: String(process.userId),
+            integrationId: String(process.integrationId),
+            name: process.name,
+            type: process.type,
+            state: process.state,
+            context: process.context,
+            results: process.results,
+            childProcesses: Array.isArray(process.childProcesses)
+                ? process.childProcesses.length > 0 &&
+                    typeof process.childProcesses[0] === 'object' &&
+                    process.childProcesses[0] !== null
+                    ? process.childProcesses.map((child) => String(child.id))
+                    : process.childProcesses
+                : [],
+            parentProcessId:
+                process.parentProcessId !== null
+                    ? String(process.parentProcessId)
+                    : null,
+            createdAt: process.createdAt,
+            updatedAt: process.updatedAt,
+        };
+    }
+}
+
+module.exports = { ProcessRepositoryPostgres };

package/integrations/tests/doubles/config-capturing-integration.js

@@ -0,0 +1,81 @@
+const { IntegrationBase } = require('../../integration-base');
+
+class ConfigCapturingModule {
+    static definition = {
+        getName: () => 'config-capturing-module'
+    };
+}
+
+class ConfigCapturingIntegration extends IntegrationBase {
+    static Definition = {
+        name: 'config-capturing',
+        version: '1.0.0',
+        modules: {
+            primary: ConfigCapturingModule
+        },
+        display: {
+            label: 'Config Capturing Integration',
+            description: 'Test double for capturing config state during updates',
+            detailsUrl: 'https://example.com',
+            icon: 'test-icon'
+        }
+    };
+
+    static _capturedOnUpdateState = null;
+
+    static resetCaptures() {
+        this._capturedOnUpdateState = null;
+    }
+
+    static getCapturedOnUpdateState() {
+        return this._capturedOnUpdateState;
+    }
+
+    constructor(params) {
+        super(params);
+        this.integrationRepository = {
+            updateIntegrationById: jest.fn().mockResolvedValue({}),
+            findIntegrationById: jest.fn().mockResolvedValue({}),
+        };
+        this.updateIntegrationStatus = {
+            execute: jest.fn().mockResolvedValue({})
+        };
+        this.updateIntegrationMessages = {
+            execute: jest.fn().mockResolvedValue({})
+        };
+    }
+
+    async initialize() {
+        this.registerEventHandlers();
+    }
+
+    async onUpdate(params) {
+        ConfigCapturingIntegration._capturedOnUpdateState = {
+            thisConfig: JSON.parse(JSON.stringify(this.config)),
+            paramsConfig: params.config
+        };
+
+        this.config = this._deepMerge(this.config, params.config);
+    }
+
+    _deepMerge(target, source) {
+        const result = { ...target };
+        for (const key of Object.keys(source)) {
+            if (
+                source[key] !== null &&
+                typeof source[key] === 'object' &&
+                !Array.isArray(source[key]) &&
+                target[key] !== null &&
+                typeof target[key] === 'object' &&
+                !Array.isArray(target[key])
+            ) {
+                result[key] = this._deepMerge(target[key], source[key]);
+            } else {
+                result[key] = source[key];
+            }
+        }
+        return result;
+    }
+}
+
+module.exports = { ConfigCapturingIntegration };

package/integrations/tests/doubles/dummy-integration-class.js

@@ -0,0 +1,105 @@
+const { IntegrationBase } = require('../../integration-base');
+
+class DummyModule {
+    static definition = {
+        getName: () => 'dummy'
+    };
+}
+
+class DummyIntegration extends IntegrationBase {
+    static Definition = {
+        name: 'dummy',
+        version: '1.0.0',
+        modules: {
+            dummy: DummyModule
+        },
+        display: {
+            label: 'Dummy Integration',
+            description: 'A dummy integration for testing',
+            detailsUrl: 'https://example.com',
+            icon: 'dummy-icon'
+        }
+    };
+
+    static getOptionDetails() {
+        return {
+            name: this.Definition.name,
+            version: this.Definition.version,
+            display: this.Definition.display
+        };
+    }
+
+    constructor(params) {
+        super(params);
+        this.sendSpy = jest.fn();
+        this.eventCallHistory = [];
+        this.events = {};
+
+        this.integrationRepository = {
+            updateIntegrationById: jest.fn().mockResolvedValue({}),
+            findIntegrationById: jest.fn().mockResolvedValue({}),
+        };
+
+        this.updateIntegrationStatus = {
+            execute: jest.fn().mockResolvedValue({})
+        };
+
+        this.updateIntegrationMessages = {
+            execute: jest.fn().mockResolvedValue({})
+        };
+    }
+
+    async loadDynamicUserActions() {
+        return {};
+    }
+
+    async send(event, data) {
+        this.sendSpy(event, data);
+        this.eventCallHistory.push({ event, data, timestamp: Date.now() });
+        if (event === 'ON_UPDATE') {
+            await this.onUpdate(data);
+        }
+        return { event, data };
+    }
+
+    async initialize() {
+        return;
+    }
+
+    async onCreate({ integrationId }) {
+        return;
+    }
+
+    async onUpdate(params) {
+        this.config = this._deepMerge(this.config, params.config);
+    }
+
+    _deepMerge(target, source) {
+        const result = { ...target };
+        for (const key of Object.keys(source)) {
+            if (
+                source[key] !== null &&
+                typeof source[key] === 'object' &&
+                !Array.isArray(source[key]) &&
+                target[key] !== null &&
+                typeof target[key] === 'object' &&
+                !Array.isArray(target[key])
+            ) {
+                result[key] = this._deepMerge(target[key], source[key]);
+            } else {
+                result[key] = source[key];
+            }
+        }
+        return result;
+    }
+
+    async onDelete(params) {
+        return;
+    }
+
+    getConfig() {
+        return this.config || {};
+    }
+}
+
+module.exports = { DummyIntegration };