@friggframework/core 2.0.0--canary.396.0dd37aa.0 → 2.0.0--canary.397.216d54b.0

package/integrations/integration-router.js

@@ -2,7 +2,6 @@ const express = require('express');
 const { get } = require('../assertions');
 const Boom = require('@hapi/boom');
 const catchAsyncError = require('express-async-handler');
-const { debug } = require('../logs');
 const { IntegrationRepository } = require('./integration-repository');
 const { DeleteIntegrationForUser } = require('./use-cases/delete-integration-for-user');
 const { GetIntegrationsForUser } = require('./use-cases/get-integrations-for-user');
@@ -12,54 +11,42 @@ const { CreateIntegration } = require('./use-cases/create-integration');
 const { ModuleService } = require('../module-plugin/module-service');
 const { ModuleRepository } = require('../module-plugin/module-repository');
 const { GetEntitiesForUser } = require('../module-plugin/use-cases/get-entities-for-user');
-const {
-    loadAppDefinition,
-} = require('../handlers/app-definition-loader');
-const { GetIntegration } = require('./use-cases/get-integration');
+const { loadAppDefinition } = require('../handlers/app-definition-loader');
+const { GetIntegrationInstance } = require('./use-cases/get-integration-instance');
+const { UpdateIntegration } = require('./use-cases/update-integration');
+const { getModulesDefinitionFromIntegrationClasses } = require('./utils/map-integration-dto');
+const { GetModuleInstanceFromType } = require('../module-plugin/use-cases/get-module-instance-from-type');
+const { GetEntityOptionsByType } = require('../module-plugin/use-cases/get-entity-options-by-type');
+const { TestModuleAuth } = require('../module-plugin/use-cases/test-module-auth');
+const { GetModule } = require('../module-plugin/use-cases/get-module');
+const { GetEntityOptionsById } = require('../module-plugin/use-cases/get-entity-options-by-id');
+const { RefreshEntityOptions } = require('../module-plugin/use-cases/refresh-entity-options');
 
-// todo: dont send moduleFactory and integrationFactory as a factory object, instead send them as separate params.
-// todo: this could be a use case class
 /**
  * Creates an Express router with integration and entity routes configured
  * @param {Object} params - Configuration parameters for the router
  * @param {express.Router} [params.router] - Optional Express router instance, creates new one if not provided
- * @param {Object} params.factory - Factory object containing moduleFactory and integrationFactory
- * @param {Object} params.factory.moduleFactory - Factory for creating and managing API modules
- * @param {Object} params.factory.integrationFactory - Factory for creating and managing integrations
  * @param {import('../user/use-cases/get-user-from-bearer-token').GetUserFromBearerToken} params.getUserFromBearerToken - Use case for retrieving a user from a bearer token
  * @returns {express.Router} Configured Express router with integration and entity routes
  */
 function createIntegrationRouter(params) {
-    const { integrations } = loadAppDefinition();
+    const { integrations: integrationClasses } = loadAppDefinition();
     const moduleRepository = new ModuleRepository();
     const integrationRepository = new IntegrationRepository();
     const credentialRepository = new CredentialRepository();
 
-    // todo: move this into a utils file
-    const getModules = () => {
-        return [
-            ...new Set(
-                integrations
-                    .map((integration) =>
-                        Object.values(integration.Definition.modules).map(
-                            (module) => module.definition
-                        )
-                    )
-                    .flat()
-            ),
-        ];
-    };
     const moduleService = new ModuleService({
         moduleRepository,
-        moduleDefinitions: getModules(),
+        moduleDefinitions: getModulesDefinitionFromIntegrationClasses(integrationClasses),
     });
     const deleteIntegrationForUser = new DeleteIntegrationForUser({
         integrationRepository,
+        integrationClasses,
     });
 
     const getIntegrationsForUser = new GetIntegrationsForUser({
         integrationRepository,
-        integrationClasses: integrations,
+        integrationClasses,
         moduleService,
         moduleRepository,
     });
@@ -68,35 +55,74 @@ function createIntegrationRouter(params) {
     });
     const createIntegration = new CreateIntegration({
         integrationRepository,
-        integrationClasses: integrations,
+        integrationClasses,
         moduleService,
     });
 
-    const getEntitiesForUserUseCase = new GetEntitiesForUser({
+    const getEntitiesForUser = new GetEntitiesForUser({
         moduleRepository,
-        moduleDefinitions: getModules(),
+        moduleDefinitions: getModulesDefinitionFromIntegrationClasses(integrationClasses),
     });
 
-    const getIntegration = new GetIntegration({
+    const getIntegrationInstance = new GetIntegrationInstance({
         integrationRepository,
-        integrationClasses: integrations,
+        integrationClasses,
         moduleService,
     });
 
+    const updateIntegration = new UpdateIntegration({
+        integrationRepository,
+        integrationClasses,
+        moduleService,
+    });
+
+    const getModuleInstanceFromType = new GetModuleInstanceFromType({
+        moduleDefinitions: getModulesDefinitionFromIntegrationClasses(integrationClasses),
+    });
+
+    const getEntityOptionsByType = new GetEntityOptionsByType({
+        moduleDefinitions: getModulesDefinitionFromIntegrationClasses(integrationClasses),
+    });
+
+    const testModuleAuth = new TestModuleAuth({
+        moduleRepository,
+        moduleDefinitions: getModulesDefinitionFromIntegrationClasses(integrationClasses),
+    });
+
+    const getModule = new GetModule({
+        moduleRepository,
+        moduleDefinitions: getModulesDefinitionFromIntegrationClasses(integrationClasses),
+    });
+
+    const getEntityOptionsById = new GetEntityOptionsById({
+        moduleRepository,
+        moduleDefinitions: getModulesDefinitionFromIntegrationClasses(integrationClasses),
+    });
+
+    const refreshEntityOptions = new RefreshEntityOptions({
+        moduleRepository,
+        moduleDefinitions: getModulesDefinitionFromIntegrationClasses(integrationClasses),
+    });
+
     const router = get(params, 'router', express());
-    const factory = get(params, 'factory');
     const getUserFromBearerToken = get(params, 'getUserFromBearerToken');
 
-    // todo: moduleFactory in factory is not used here anymore, remove it
-    setIntegrationRoutes(router, factory, getUserFromBearerToken, integrations, {
+    setIntegrationRoutes(router, getUserFromBearerToken, {
         createIntegration,
         deleteIntegrationForUser,
         getIntegrationsForUser,
-        getEntitiesForUserUseCase,
-        getIntegration,
+        getEntitiesForUser,
+        getIntegrationInstance,
+        updateIntegration,
     });
-    setEntityRoutes(router, factory, getUserFromBearerToken, {
+    setEntityRoutes(router, getUserFromBearerToken, {
         getCredentialForUser,
+        getModuleInstanceFromType,
+        getEntityOptionsByType,
+        testModuleAuth,
+        getModule,
+        getEntityOptionsById,
+        refreshEntityOptions,
     });
     return router;
 }
@@ -126,19 +152,17 @@ function checkRequiredParams(params, requiredKeys) {
 /**
  * Sets up integration-related routes on the provided Express router
  * @param {express.Router} router - Express router instance to add routes to
- * @param {Object} factory - Factory object containing moduleFactory and integrationFactory
- * @param {Object} factory.moduleFactory - Factory for creating and managing API modules
- * @param {Object} factory.integrationFactory - Factory for creating and managing integrations
  * @param {import('../user/use-cases/get-user-from-bearer-token').GetUserFromBearerToken} getUserFromBearerToken - Use case for retrieving a user from a bearer token
+ * @param {Object} useCases - use cases for integration management
  */
-function setIntegrationRoutes(router, factory, getUserFromBearerToken, integrationClasses, useCases) {
-    const { integrationFactory } = factory;
+function setIntegrationRoutes(router, getUserFromBearerToken, useCases) {
     const {
         createIntegration,
         deleteIntegrationForUser,
         getIntegrationsForUser,
-        getEntitiesForUserUseCase,
-        getIntegration,
+        getEntitiesForUser,
+        getIntegrationInstance,
+        updateIntegration,
     } = useCases;
     router.route('/api/integrations').get(
         catchAsyncError(async (req, res) => {
@@ -152,7 +176,7 @@ function setIntegrationRoutes(router, factory, getUserFromBearerToken, integrati
                     options: integrations.map((integration) =>
                         integration.options
                     ),
-                    authorized: await getEntitiesForUserUseCase.execute(userId),
+                    authorized: await getEntitiesForUser.execute(userId),
                 },
                 integrations: integrations,
             }
@@ -171,27 +195,16 @@ function setIntegrationRoutes(router, factory, getUserFromBearerToken, integrati
                 'entities',
                 'config',
             ]);
-            // throw if not value
+
             get(params.config, 'type');
 
-            // create integration
             const integration = await createIntegration.execute(
                 params.entities,
                 userId,
                 params.config
             );
 
-            // post integration initialization
-            debug(
-                `Calling onCreate on the ${integration?.constructor?.Config?.name} Integration with no arguments`
-            );
-            await integration.send('ON_CREATE', {});
-
-            res.status(201).json(
-                await integrationFactory.getFormattedIntegration(
-                    integration.record
-                )
-            );
+            res.status(201).json(integration);
         })
     );
 
@@ -203,23 +216,8 @@ function setIntegrationRoutes(router, factory, getUserFromBearerToken, integrati
             const userId = user.getId();
             const params = checkRequiredParams(req.body, ['config']);
 
-            const integration =
-                await integrationFactory.getInstanceFromIntegrationId({
-                    integrationId: req.params.integrationId,
-                    userId,
-                });
-
-            debug(
-                `Calling onUpdate on the ${integration?.constructor?.Config?.name} Integration arguments: `,
-                params
-            );
-            await integration.send('ON_UPDATE', params);
-
-            res.json(
-                await integrationFactory.getFormattedIntegration(
-                    integration.record
-                )
-            );
+            const integration = await updateIntegration.execute(req.params.integrationId, userId, params.config);
+            res.json(integration);
         })
     );
 
@@ -229,18 +227,7 @@ function setIntegrationRoutes(router, factory, getUserFromBearerToken, integrati
                 req.headers.authorization
             );
             const params = checkRequiredParams(req.params, ['integrationId']);
-            const integration =
-                await integrationFactory.getInstanceFromIntegrationId({
-                    userId: user.getId(),
-                    integrationId: params.integrationId,
-                });
-
-            debug(
-                `Calling onUpdate on the ${integration?.constructor?.Definition?.name} Integration with no arguments`
-            );
-            await integration.send('ON_DELETE');
             await deleteIntegrationForUser.execute(params.integrationId, user.getId());
-
             res.status(204).json({});
         })
     );
@@ -251,11 +238,7 @@ function setIntegrationRoutes(router, factory, getUserFromBearerToken, integrati
                 req.headers.authorization
             );
             const params = checkRequiredParams(req.params, ['integrationId']);
-            const integration =
-                await integrationFactory.getInstanceFromIntegrationId({
-                    integrationId: params.integrationId,
-                    userId: user.getId(),
-                });
+            const integration = await getIntegrationInstance.execute(params.integrationId, user.getId());
             res.json(await integration.send('GET_CONFIG_OPTIONS'));
         })
     );
@@ -270,13 +253,7 @@ function setIntegrationRoutes(router, factory, getUserFromBearerToken, integrati
                 const params = checkRequiredParams(req.params, [
                     'integrationId',
                 ]);
-                const integration =
-                    await integrationFactory.getInstanceFromIntegrationId(
-                        {
-                            integrationId: params.integrationId,
-                            userId: user.getId(),
-                        }
-                    );
+                const integration = await getIntegrationInstance.execute(params.integrationId, user.getId());
 
                 res.json(
                     await integration.send('REFRESH_CONFIG_OPTIONS', req.body)
@@ -289,7 +266,7 @@ function setIntegrationRoutes(router, factory, getUserFromBearerToken, integrati
                 req.headers.authorization
             );
             const params = checkRequiredParams(req.params, ['integrationId']);
-            const integration = await getIntegration.execute(params.integrationId, user.getId());
+            const integration = await getIntegrationInstance.execute(params.integrationId, user.getId());
             res.json(await integration.send('GET_USER_ACTIONS', req.body));
         })
     );
@@ -305,13 +282,7 @@ function setIntegrationRoutes(router, factory, getUserFromBearerToken, integrati
                     'integrationId',
                     'actionId',
                 ]);
-                const integration =
-                    await integrationFactory.getInstanceFromIntegrationId(
-                        {
-                            integrationId: params.integrationId,
-                            userId: user.getId(),
-                        }
-                    );
+                const integration = await getIntegrationInstance.execute(params.integrationId, user.getId());
 
                 res.json(
                     await integration.send('GET_USER_ACTION_OPTIONS', {
@@ -335,13 +306,7 @@ function setIntegrationRoutes(router, factory, getUserFromBearerToken, integrati
                     'integrationId',
                     'actionId',
                 ]);
-                const integration =
-                    await integrationFactory.getInstanceFromIntegrationId(
-                        {
-                            integrationId: params.integrationId,
-                            userId: user.getId(),
-                        }
-                    );
+                const integration = await getIntegrationInstance.execute(params.integrationId, user.getId());
 
                 res.json(
                     await integration.send('REFRESH_USER_ACTION_OPTIONS', {
@@ -361,12 +326,7 @@ function setIntegrationRoutes(router, factory, getUserFromBearerToken, integrati
                 'integrationId',
                 'actionId',
             ]);
-            const integration =
-                await integrationFactory.getInstanceFromIntegrationId({
-                    integrationId: params.integrationId,
-                    userId: user.getId(),
-                });
-
+            const integration = await getIntegrationInstance.execute(params.integrationId, user.getId());
             res.json(await integration.send(params.actionId, req.body));
         })
     );
@@ -400,13 +360,8 @@ function setIntegrationRoutes(router, factory, getUserFromBearerToken, integrati
             const user = await getUserFromBearerToken.execute(
                 req.headers.authorization
             );
-            const userId = user.getId();
             const params = checkRequiredParams(req.params, ['integrationId']);
-            const instance =
-                await integrationFactory.getInstanceFromIntegrationId({
-                    userId,
-                    integrationId: params.integrationId,
-                });
+            const instance = await getIntegrationInstance.execute(params.integrationId, user.getId());
 
             if (!instance) {
                 throw Boom.notFound();
@@ -432,25 +387,18 @@ function setIntegrationRoutes(router, factory, getUserFromBearerToken, integrati
 /**
  * Sets up entity-related routes for the integration router
  * @param {Object} router - Express router instance
- * @param {Object} factory - Factory object containing moduleFactory
  * @param {import('../user/use-cases/get-user-from-bearer-token').GetUserFromBearerToken} getUserFromBearerToken - Use case for retrieving a user from a bearer token
  */
-function setEntityRoutes(router, factory, getUserFromBearerToken, useCases) {
-    const { moduleFactory } = factory;
-    const { getCredentialForUser } = useCases;
-    const getModuleInstance = async (userId, entityType) => {
-        if (!moduleFactory.checkIsValidType(entityType)) {
-            throw Boom.badRequest(
-                `Error: Invalid entity type of ${entityType}, options are ${moduleFactory.moduleTypes.join(
-                    ', '
-                )}`
-            );
-        }
-        return await moduleFactory.getInstanceFromTypeName(
-            entityType,
-            userId
-        );
-    };
+function setEntityRoutes(router, getUserFromBearerToken, useCases) {
+    const {
+        getCredentialForUser,
+        getModuleInstanceFromType,
+        getEntityOptionsByType,
+        testModuleAuth,
+        getModule,
+        getEntityOptionsById,
+        refreshEntityOptions,
+    } = useCases;
 
     router.route('/api/authorize').get(
         catchAsyncError(async (req, res) => {
@@ -459,7 +407,7 @@ function setEntityRoutes(router, factory, getUserFromBearerToken, useCases) {
             );
             const userId = user.getId();
             const params = checkRequiredParams(req.query, ['entityType']);
-            const module = await getModuleInstance(userId, params.entityType);
+            const module = await getModuleInstanceFromType.execute(userId, params.entityType);
             const areRequirementsValid =
                 module.validateAuthorizationRequirements();
             if (!areRequirementsValid) {
@@ -482,7 +430,7 @@ function setEntityRoutes(router, factory, getUserFromBearerToken, useCases) {
                 'entityType',
                 'data',
             ]);
-            const module = await getModuleInstance(userId, params.entityType);
+            const module = await getModuleInstanceFromType.execute(userId, params.entityType);
 
             res.json(
                 await module.processAuthorizationCallback({
@@ -515,7 +463,7 @@ function setEntityRoutes(router, factory, getUserFromBearerToken, useCases) {
                 throw Boom.badRequest('Invalid credential ID');
             }
 
-            const module = await getModuleInstance(userId, params.entityType);
+            const module = await getModuleInstanceFromType.execute(userId, params.entityType);
             const entityDetails = await module.getEntityDetails(
                 module.api,
                 null,
@@ -544,9 +492,9 @@ function setEntityRoutes(router, factory, getUserFromBearerToken, useCases) {
             }
 
             const params = checkRequiredParams(req.query, ['entityType']);
-            const module = await getModuleInstance(userId, params.entityType);
+            const entityOptions = await getEntityOptionsByType.execute(userId, params.entityType);
 
-            res.json(await module.getEntityOptions());
+            res.json(entityOptions);
         })
     );
 
@@ -557,17 +505,11 @@ function setEntityRoutes(router, factory, getUserFromBearerToken, useCases) {
             );
             const userId = user.getId();
             const params = checkRequiredParams(req.params, ['entityId']);
-            const module = await moduleFactory.getModuleInstanceFromEntityId(
+            const testAuthResponse = await testModuleAuth.execute(
                 params.entityId,
                 userId
             );
 
-            if (!module) {
-                throw Boom.notFound();
-            }
-
-            const testAuthResponse = await module.testAuth();
-
             if (!testAuthResponse) {
                 res.status(400);
                 res.json({
@@ -592,16 +534,12 @@ function setEntityRoutes(router, factory, getUserFromBearerToken, useCases) {
             );
             const userId = user.getId();
             const params = checkRequiredParams(req.params, ['entityId']);
-            const module = await moduleFactory.getModuleInstanceFromEntityId(
+            const module = await getModule.execute(
                 params.entityId,
                 userId
             );
 
-            if (!module) {
-                throw Boom.notFound();
-            }
-
-            res.json(module.entity);
+            res.json(module);
         })
     );
 
@@ -614,16 +552,10 @@ function setEntityRoutes(router, factory, getUserFromBearerToken, useCases) {
             const params = checkRequiredParams(req.params, [
                 'entityId',
             ]);
-            const module = await moduleFactory.getModuleInstanceFromEntityId(
-                params.entityId,
-                userId
-            );
 
-            if (!module) {
-                throw Boom.notFound();
-            }
+            const entityOptions = await getEntityOptionsById.execute(params.entityId, userId);
 
-            res.json(await module.getEntityOptions());
+            res.json(entityOptions);
         })
     );
 
@@ -636,16 +568,13 @@ function setEntityRoutes(router, factory, getUserFromBearerToken, useCases) {
             const params = checkRequiredParams(req.params, [
                 'entityId',
             ]);
-            const module = await moduleFactory.getModuleInstanceFromEntityId(
+            const updatedOptions = await refreshEntityOptions.execute(
                 params.entityId,
-                userId
+                userId,
+                req.body
             );
 
-            if (!module) {
-                throw Boom.notFound();
-            }
-
-            res.json(await module.refreshEntityOptions(req.body));
+            res.json(updatedOptions);
         })
     );
 }

package/integrations/integration.js

@@ -1,5 +1,37 @@
 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
@@ -15,7 +47,6 @@ class Integration {
         status,
         version,
         messages,
-        entityReference,
         integrationClass,
         modules = {}
     }) {
@@ -27,7 +58,6 @@ class Integration {
         this.status = status;
         this.version = version;
         this.messages = messages;
-        this.entityReference = entityReference;
 
         // Integration behavior (strategy pattern)
         this.integrationClass = integrationClass;
@@ -38,7 +68,10 @@ class Integration {
         // Initialize basic behavior (sync parts only)
         this._initializeBasicBehavior();
 
-        // Return a Proxy to handle dynamic method delegation
+        // --- 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
@@ -76,6 +109,21 @@ class Integration {
             // 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);
+                }
+            }
         }
     }
 
@@ -176,7 +224,6 @@ class Integration {
             status: this.status,
             version: this.version,
             messages: this.messages,
-            entityReference: this.entityReference,
             // Expose userActions if they were loaded/attached elsewhere
             userActions: this.userActions,
         };

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

@@ -17,29 +17,39 @@ class CreateIntegration {
     async execute(entities, userId, config) {
         const integrationRecord = await this.integrationRepository.createIntegration(entities, userId, config);
 
-        const modules = {};
-        for (const [key, entity] of Object.entries(integrationRecord.entities)) {
+
+        // 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(
-                entity._id,
-                integrationRecord.user
+                entityId,
+                integrationRecord.userId
             );
-            modules[key] = moduleInstance;
+            modules.push(moduleInstance);
         }
 
         const integrationInstance = new Integration({
-            id: integrationRecord._id.toString(),
-            userId: integrationRecord.user,
-            entities: integrationRecord.entities,
+            id: integrationRecord.id,
+            userId: integrationRecord.userId,
+            entities: integrationRecord.entitiesIds,
             config: integrationRecord.config,
             status: integrationRecord.status,
             version: integrationRecord.version,
             messages: integrationRecord.messages,
-            entityReference: integrationRecord.entityReference,
-            integrationClass: this.integrationClasses[integrationRecord.config.type], // todo: check if this is correct
+            integrationClass: integrationClass,
             modules
         });
 
         await integrationInstance.initialize();
+        await integrationInstance.send('ON_CREATE', {});
 
         return mapIntegrationClassToIntegrationDTO(integrationInstance);
     }