@friggframework/core 2.0.0--canary.405.1f6792c.0 → 2.0.0--canary.396.6862738.0

package/integrations/integration.js

@@ -0,0 +1,233 @@
+const { Options } = require('./options');
+
+/**
+ * Integration (Domain Aggregate-Root)
+ * ----------------------------------
+ * This class represents a *configured* integration instance at runtime. It is
+ * deliberately split into **two layers**:
+ *   1.  A *data snapshot* of the persisted record (id, userId, config, etc.).
+ *   2.  A *behaviour* object: a concrete class supplied by the app developer
+ *       that extends `IntegrationBase` and implements event handlers, user
+ *       actions, custom routes, etc.
+ *
+ * The two layers are glued together via a **JavaScript `Proxy`**.  When a
+ * property is requested on an `Integration` instance we:
+ *   • Check if the property exists on the wrapper itself (data-layer).
+ *   • Fallback to the behaviour instance (logic-layer).
+ *   • If the value is a function we `.bind(this)` so that the function's
+ *     `this` always points to the *wrapper* – giving it access to both data
+ *     and behaviour transparently.
+ *
+ * This means you can treat a hydrated Integration as if it *were* the custom
+ * class:
+ *
+ * ```js
+ * const integration = await getIntegration.execute(id, userId);
+ * // `send` actually lives on IntegrationBase but is accessible here
+ * const actions = await integration.send('GET_USER_ACTIONS');
+ * ```
+ *
+ * A corollary benefit is that **circular references stay internal**: the heavy
+ * `Module → Api → delegate` graph is never exposed when we later serialise the
+ * object to JSON – we map it to a DTO first.
+ */
+
+/**
+ * Integration Domain Entity
+ * Represents a configured integration with its data and behavior
+ * Uses the strategy pattern to delegate behavior to the integration class
+ * This is the main class that is used to interact with integrations
+ */
+class Integration {
+    constructor({
+        id,
+        userId,
+        entities,
+        config,
+        status,
+        version,
+        messages,
+        integrationClass,
+        modules = {}
+    }) {
+        // Data from record
+        this.id = id;
+        this.userId = userId;
+        this.entities = entities;
+        this.config = config;
+        this.status = status;
+        this.version = version;
+        this.messages = messages;
+
+        // Integration behavior (strategy pattern)
+        this.integrationClass = integrationClass;
+
+        // Loaded modules
+        this.modules = modules;
+
+        // Initialize basic behavior (sync parts only)
+        this._initializeBasicBehavior();
+
+        // --- Behaviour delegation via Proxy --------------------------------
+        // The Proxy merges the *data layer* (this wrapper) with the *behaviour
+        // layer* (custom IntegrationBase subclass).  Consumers don't have to
+        // know (or care) where a method/property is defined.
+        return new Proxy(this, {
+            get(target, prop) {
+                // First, check if property exists on Integration entity
+                if (prop in target) {
+                    return target[prop];
+                }
+
+                // Then, check if it exists on the behavior instance
+                if (target.behavior && prop in target.behavior) {
+                    const value = target.behavior[prop];
+
+                    // If it's a function, bind the context to the Integration entity
+                    if (typeof value === 'function') {
+                        return value.bind(target);
+                    }
+
+                    return value;
+                }
+
+                // Return undefined for non-existent properties
+                return undefined;
+            }
+        });
+    }
+
+    _initializeBasicBehavior() {
+        // Initialize basic behavior (sync parts only)
+        if (this.integrationClass) {
+            // Create instance for behavior delegation
+            this.behavior = new this.integrationClass({
+                userId: this.userId,
+                integrationId: this.id
+            });
+
+            // Copy events
+            this.events = this.behavior.events || {};
+            this.defaultEvents = this.behavior.defaultEvents || {};
+
+
+            // Expose behaviour instance methods directly on the wrapper so that
+            // early-bound handlers (created before behaviour existed) can still
+            // access them without falling back through the Proxy. This prevents
+            // `undefined` errors for methods like `loadDynamicUserActions` that
+            // may be invoked inside default event-handlers.
+            const proto = Object.getPrototypeOf(this.behavior);
+            for (const key of Object.getOwnPropertyNames(proto)) {
+                if (key === 'constructor') continue;
+                if (typeof proto[key] === 'function' && this[key] === undefined) {
+                    // Bind to behaviour so internal `this` remains correct.
+                    this[key] = proto[key].bind(this.behavior);
+                }
+            }
+        }
+    }
+
+    async initialize() {
+        // Complete async initialization
+        if (this.behavior) {
+            // Load dynamic user actions
+            try {
+                const additionalUserActions = await this.loadDynamicUserActions();
+                this.events = { ...this.events, ...additionalUserActions };
+            } catch (e) {
+                this.addError(e);
+            }
+
+            // Register event handlers
+            await this.registerEventHandlers();
+        }
+    }
+
+    // Core methods that should always be on Integration entity
+    // These override any behavior methods with the same name
+
+    // Module access helpers
+    getModule(key) {
+        return this.modules[key];
+    }
+
+    setModule(key, module) {
+        this.modules[key] = module;
+        // Also set on behavior for backward compatibility
+        if (this.behavior) {
+            this.behavior[key] = module;
+        }
+    }
+
+    // State management
+    addError(error) {
+        if (!this.messages.errors) {
+            this.messages.errors = [];
+        }
+        this.messages.errors.push(error);
+        this.status = 'ERROR';
+    }
+
+    addWarning(warning) {
+        if (!this.messages.warnings) {
+            this.messages.warnings = [];
+        }
+        this.messages.warnings.push(warning);
+    }
+
+    // Domain methods
+    isActive() {
+        return this.status === 'ENABLED' || this.status === 'ACTIVE';
+    }
+
+    needsConfiguration() {
+        return this.status === 'NEEDS_CONFIG';
+    }
+
+    hasErrors() {
+        return this.status === 'ERROR';
+    }
+
+    belongsToUser(userId) {
+        return this.userId.toString() === userId.toString();
+    }
+
+    // Get the underlying behavior instance (useful for debugging or special cases)
+    getBehavior() {
+        return this.behavior;
+    }
+
+    // Check if a method exists (either on entity or behavior)
+    hasMethod(methodName) {
+        return methodName in this || (this.behavior && methodName in this.behavior);
+    }
+
+    getOptionDetails() {
+        const options = new Options({
+            module: Object.values(this.integrationClass.Definition.modules)[0], // This is a placeholder until we revamp the frontend
+            ...this.integrationClass.Definition,
+        });
+        return options.get();
+    }
+
+    /**
+     * Custom JSON serializer to prevent circular references (e.g. Module → Api → delegate)
+     * and to keep API responses lightweight.
+     * Only primitive, serialisable data needed by clients is returned.
+     */
+    toJSON() {
+        return {
+            id: this.id,
+            userId: this.userId,
+            entities: this.entities,
+            config: this.config,
+            status: this.status,
+            version: this.version,
+            messages: this.messages,
+            // Expose userActions if they were loaded/attached elsewhere
+            userActions: this.userActions,
+        };
+    }
+}
+
+module.exports = { Integration }; 

package/integrations/options.js

@@ -1,5 +1,5 @@
 const { RequiredPropertyError } = require('../errors');
-const { get, getAndVerifyType } = require('../assertions');
+const { get } = require('../assertions');
 
 class Options {
     constructor(params) {

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

@@ -0,0 +1,58 @@
+const { Integration } = require('../integration');
+const { mapIntegrationClassToIntegrationDTO } = require('../utils/map-integration-dto');
+
+class CreateIntegration {
+    /**
+     * @param {Object} params
+     * @param {import('../integration-repository').IntegrationRepository} params.integrationRepository
+     * @param {import('../integration-classes').IntegrationClasses} params.integrationClasses
+     * @param {import('../../module-plugin/module-service').ModuleService} params.moduleService
+     */
+    constructor({ integrationRepository, integrationClasses, moduleService }) {
+        this.integrationRepository = integrationRepository;
+        this.integrationClasses = integrationClasses;
+        this.moduleService = moduleService;
+    }
+
+    async execute(entities, userId, config) {
+        const integrationRecord = await this.integrationRepository.createIntegration(entities, userId, config);
+
+
+        // 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}`);
+        }
+
+        const modules = [];
+        for (const entityId of integrationRecord.entitiesIds) {
+            const moduleInstance = await this.moduleService.getModuleInstance(
+                entityId,
+                integrationRecord.userId
+            );
+            modules.push(moduleInstance);
+        }
+
+        const integrationInstance = new Integration({
+            id: integrationRecord.id,
+            userId: integrationRecord.userId,
+            entities: integrationRecord.entitiesIds,
+            config: integrationRecord.config,
+            status: integrationRecord.status,
+            version: integrationRecord.version,
+            messages: integrationRecord.messages,
+            integrationClass: integrationClass,
+            modules
+        });
+
+        await integrationInstance.initialize();
+        await integrationInstance.send('ON_CREATE', {});
+
+        return mapIntegrationClassToIntegrationDTO(integrationInstance);
+    }
+}
+
+module.exports = { CreateIntegration }; 

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

@@ -0,0 +1,53 @@
+const Boom = require('@hapi/boom');
+
+class DeleteIntegrationForUser {
+    constructor({ integrationRepository, integrationClasses }) {
+
+        /**
+         * @type {import('../integration-repository').IntegrationRepository}
+         */
+        this.integrationRepository = integrationRepository;
+        this.integrationClasses = integrationClasses;
+    }
+
+    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}`
+            );
+        }
+
+        const integrationInstance = new Integration({
+            id: integrationRecord.id,
+            userId: integrationRecord.userId,
+            entities: integrationRecord.entitiesIds,
+            config: integrationRecord.config,
+            status: integrationRecord.status,
+            version: integrationRecord.version,
+            messages: integrationRecord.messages,
+            integrationClass: integrationClass,
+            modules: [],
+        });
+
+        // 6. Complete async initialization (load dynamic actions, register handlers)
+        await integrationInstance.initialize();
+        await integrationInstance.send('ON_DELETE');
+
+        await this.integrationRepository.deleteIntegrationById(integrationId);
+
+    }
+}
+
+module.exports = { DeleteIntegrationForUser }; 

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

@@ -0,0 +1,63 @@
+const { Integration } = require('../integration');
+const { mapIntegrationClassToIntegrationDTO } = require('../utils/map-integration-dto');
+
+class GetIntegrationForUser {
+    constructor({ integrationRepository, integrationClasses, moduleService, moduleRepository }) {
+
+        /**
+         * @type {import('../integration-repository').IntegrationRepository}
+         */
+        this.integrationRepository = integrationRepository;
+        this.integrationClasses = integrationClasses;
+        this.moduleService = moduleService;
+        this.moduleRepository = moduleRepository;
+    }
+
+    /**
+     * @param {string} integrationId
+     * @param {string} userId
+     * @returns {Promise<Integration>}
+     */
+    async execute(integrationId, userId) {
+        const integrationRecord = await this.integrationRepository.findIntegrationById(integrationId);
+        const entities = await this.moduleRepository.findEntitiesByIds(integrationRecord.entitiesIds);
+
+        if (!integrationRecord) {
+            throw Boom.notFound(`Integration with id of ${integrationId} does not exist`);
+        }
+
+        if (integrationRecord.user.toString() !== userId.toString()) {
+            throw Boom.forbidden('User does not have access to this integration');
+        }
+
+        const integrationClass = this.integrationClasses.find(
+            (integrationClass) => integrationClass.Definition.name === integrationRecord.config.type
+        );
+
+        const modules = [];
+        for (const entity of entities) {
+            const moduleInstance = await this.moduleService.getModuleInstance(
+                entity._id,
+                integrationRecord.user
+            );
+            modules.push(moduleInstance);
+        }
+
+        const integrationInstance = new Integration({
+            id: integrationRecord._id,
+            userId: integrationRecord.user,
+            entities: entities,
+            config: integrationRecord.config,
+            status: integrationRecord.status,
+            version: integrationRecord.version,
+            messages: integrationRecord.messages,
+            entityReference: integrationRecord.entityReference,
+            integrationClass: integrationClass,
+            modules
+        });
+
+        return mapIntegrationClassToIntegrationDTO(integrationInstance);
+    }
+}
+
+module.exports = { GetIntegrationForUser }; 

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

@@ -0,0 +1,73 @@
+const { Integration } = require('../integration');
+
+class GetIntegrationInstance {
+
+    /**
+     * @class GetIntegrationInstance
+     * @description Use case for retrieving a single integration instance by ID and user.
+     * @param {Object} params
+     * @param {import('../integration-repository').IntegrationRepository} params.integrationRepository - Repository for integration data access
+     * @param {Array<import('../integration').Integration>} params.integrationClasses - Array of available integration classes
+     * @param {import('../module-plugin/module-service').ModuleService} params.moduleService - Service for module instantiation and management
+     */
+    constructor({
+        integrationRepository,
+        integrationClasses,
+        moduleService,
+    }) {
+        this.integrationRepository = integrationRepository;
+        this.integrationClasses = integrationClasses;
+        this.moduleService = moduleService;
+    }
+
+    async execute(integrationId, userId) {
+        const integrationRecord = await this.integrationRepository.findIntegrationById(integrationId);
+
+        if (!integrationRecord) {
+            throw new Error(`No integration found by the ID of ${integrationId}`);
+        }
+
+        const integrationClass = this.integrationClasses.find(
+            (integrationClass) => integrationClass.Definition.name === integrationRecord.config.type
+        );
+
+        if (!integrationClass) {
+            throw new Error(`No integration class found for type: ${integrationRecord.config.type}`);
+        }
+
+        if (integrationRecord.userId !== userId) {
+            throw new Error(
+                `Integration ${integrationId} does not belong to User ${userId}`
+            );
+        }
+
+
+        const modules = [];
+        for (const entityId of integrationRecord.entitiesIds) {
+            const moduleInstance = await this.moduleService.getModuleInstance(
+                entityId,
+                integrationRecord.userId
+            );
+            modules.push(moduleInstance);
+        }
+
+        const integrationInstance = new Integration({
+            id: integrationRecord.id,
+            userId: integrationRecord.userId,
+            entities: integrationRecord.entitiesIds,
+            config: integrationRecord.config,
+            status: integrationRecord.status,
+            version: integrationRecord.version,
+            messages: integrationRecord.messages,
+            integrationClass: integrationClass,
+            modules
+        });
+
+
+        await integrationInstance.initialize();
+
+        return integrationInstance;
+    }
+}
+
+module.exports = { GetIntegrationInstance }; 

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

@@ -0,0 +1,64 @@
+const { Integration } = require('../integration');
+const { mapIntegrationClassToIntegrationDTO } = require('../utils/map-integration-dto');
+
+class GetIntegrationsForUser {
+    constructor({ integrationRepository, integrationClasses, moduleService, moduleRepository }) {
+
+        /**
+         * @type {import('../integration-repository').IntegrationRepository}
+         */
+        this.integrationRepository = integrationRepository;
+        this.integrationClasses = integrationClasses;
+        this.moduleService = moduleService;
+        this.moduleRepository = moduleRepository;
+    }
+
+    /**
+     * @param {string} userId
+     * @returns {Promise<Integration[]>}
+     */
+    async execute(userId) {
+        const integrationRecords = await this.integrationRepository.findIntegrationsByUserId(userId);
+
+        const integrations = []
+
+        for (const integrationRecord of integrationRecords) {
+            const entities = await this.moduleRepository.findEntitiesByIds(integrationRecord.entitiesIds);
+
+            const integrationClass = this.integrationClasses.find(
+                (integrationClass) => integrationClass.Definition.name === integrationRecord.config.type
+            );
+
+            const modules = [];
+            for (const entity of entities) {
+                const moduleInstance = await this.moduleService.getModuleInstance(
+                    entity.id,
+                    integrationRecord.userId
+                );
+                modules.push(moduleInstance);
+            }
+
+            const integrationInstance = new Integration({
+                id: integrationRecord.id,
+                userId: integrationRecord.user,
+                entities: entities,
+                config: integrationRecord.config,
+                status: integrationRecord.status,
+                version: integrationRecord.version,
+                messages: integrationRecord.messages,
+                entityReference: integrationRecord.entityReference,
+                integrationClass: integrationClass,
+                modules
+            });
+
+            integrations.push(
+                mapIntegrationClassToIntegrationDTO(integrationInstance)
+            );
+
+        }
+
+        return integrations;
+    }
+}
+
+module.exports = { GetIntegrationsForUser }; 

package/integrations/use-cases/index.js

@@ -0,0 +1,11 @@
+const { GetIntegrationsForUser } = require('./get-integrations-for-user');
+const { DeleteIntegrationForUser } = require('./delete-integration-for-user');
+const { CreateIntegration } = require('./create-integration');
+const { GetIntegration } = require('./get-integration');
+
+module.exports = {
+    GetIntegrationsForUser,
+    DeleteIntegrationForUser,
+    CreateIntegration,
+    GetIntegration,
+}; 

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

@@ -0,0 +1,81 @@
+const { Integration } = require('../integration');
+const { mapIntegrationClassToIntegrationDTO } = require('../utils/map-integration-dto');
+
+
+class UpdateIntegration {
+
+    /**
+     * @class UpdateIntegration
+     * @description Use case for updating a single integration by ID and user.
+     * @param {Object} params
+     * @param {import('../integration-repository').IntegrationRepository} params.integrationRepository - Repository for integration data access
+     * @param {Array<import('../integration').Integration>} params.integrationClasses - Array of available integration classes
+     * @param {import('../module-plugin/module-service').ModuleService} params.moduleService - Service for module instantiation and management
+     */
+    constructor({
+        integrationRepository,
+        integrationClasses,
+        moduleService,
+    }) {
+        this.integrationRepository = integrationRepository;
+        this.integrationClasses = integrationClasses;
+        this.moduleService = moduleService;
+    }
+
+    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.moduleService.getModuleInstance(
+                entityId,
+                integrationRecord.userId
+            );
+            modules.push(moduleInstance);
+        }
+
+        // 4. Create the Integration domain entity with modules
+        const integrationInstance = new Integration({
+            id: integrationRecord.id,
+            userId: integrationRecord.userId,
+            entities: integrationRecord.entitiesIds,
+            config: integrationRecord.config,
+            status: integrationRecord.status,
+            version: integrationRecord.version,
+            messages: integrationRecord.messages,
+            integrationClass: integrationClass,
+            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/utils/map-integration-dto.js

@@ -0,0 +1,37 @@
+/**
+ * @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,
+        entityReference: integration.entityReference,
+        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 };