@friggframework/core 2.0.0--canary.398.a314355.0 → 2.0.0--canary.397.4957a89.0

package/modules/module.js

@@ -0,0 +1,221 @@
+const { Delegate } = require('../core');
+const _ = require('lodash');
+const { flushDebugLog } = require('../logs');
+const { ModuleConstants } = require('./ModuleConstants');
+
+// todo: this class should be a Domain class, and the Delegate function is preventing us from
+// doing that, we probably have to get rid of the Delegate class as well as the event based 
+// calls since they go against the Domain Driven Design principles (eg. a domain class should not call repository methods or use cases)
+class Module extends Delegate {
+
+    //todo: entity should be replaced with actual entity properties
+    /**
+     * 
+     * @param {Object} params
+     * @param {Object} params.definition The definition of the Api Module
+     * @param {string} params.userId The user id
+     * @param {Object} params.entity The entity record from the database
+     */
+    constructor({ definition, userId = null, entity: entityObj = null }) {
+        super({ definition, userId, entity: entityObj });
+
+        this.validateDefinition(definition);
+
+        this.userId = userId;
+        this.entity = entityObj;
+        this.credential = entityObj?.credential;
+        this.definition = definition;
+        this.name = this.definition.moduleName;
+        this.modelName = this.definition.modelName;
+        this.apiClass = this.definition.API;
+
+        // Repository used for persistence operations related to credentials.
+        const { CredentialRepository } = require('../credential/credential-repository');
+        this.credentialRepository = new CredentialRepository();
+
+        // Repository responsible for entity persistence actions
+        const { ModuleRepository } = require('./module-repository');
+        this.moduleRepository = new ModuleRepository();
+
+        Object.assign(this, this.definition.requiredAuthMethods);
+
+        const apiParams = {
+            ...this.definition.env,
+            delegate: this,
+            ...this.apiParamsFromCredential(this.credential),
+            ...this.apiParamsFromEntity(this.entity),
+        };
+        this.api = new this.apiClass(apiParams);
+    }
+
+    getName() {
+        return this.name;
+    }
+
+    getEntityOptions() {
+        return this.definition.getEntityOptions()
+    }
+
+    async refreshEntityOptions(options) {
+        await this.definition.refreshEntityOptions(options);
+        return this.getEntityOptions();
+    }
+
+    apiParamsFromCredential(credential) {
+        return _.pick(credential, ...this.apiPropertiesToPersist?.credential);
+    }
+
+    apiParamsFromEntity(entity) {
+        return _.pick(entity, ...this.apiPropertiesToPersist?.entity);
+    }
+
+    async validateAuthorizationRequirements() {
+        const requirements = await this.getAuthorizationRequirements();
+        let valid = true;
+        if (
+            ['oauth1', 'oauth2'].includes(requirements.type) &&
+            !requirements.url
+        ) {
+            valid = false;
+        }
+        return valid;
+    }
+
+    async getAuthorizationRequirements(params) {
+        return this.api.getAuthorizationRequirements();
+    }
+
+    async testAuth() {
+        let validAuth = false;
+        try {
+            if (await this.testAuthRequest(this.api)) validAuth = true;
+        } catch (e) {
+            flushDebugLog(e);
+        }
+        return validAuth;
+    }
+
+    async onTokenUpdate() {
+        const credentialDetails = await this.getCredentialDetails(
+            this.api,
+            this.userId
+        );
+        Object.assign(
+            credentialDetails.details,
+            this.apiParamsFromCredential(this.api)
+        );
+        credentialDetails.details.auth_is_valid = true;
+
+        const persisted = await this.credentialRepository.upsertCredential(credentialDetails);
+        this.credential = persisted;
+    }
+
+    async receiveNotification(notifier, delegateString, object = null) {
+        if (delegateString === this.api.DLGT_TOKEN_UPDATE) {
+            await this.onTokenUpdate();
+        } else if (delegateString === this.api.DLGT_TOKEN_DEAUTHORIZED) {
+            await this.deauthorize();
+        } else if (delegateString === this.api.DLGT_INVALID_AUTH) {
+            await this.markCredentialsInvalid();
+        }
+    }
+
+    async markCredentialsInvalid() {
+        if (!this.credential) return;
+
+        // Persist flag change through repository – works even when the
+        // credential object is a plain JavaScript object (lean query).
+        const credentialId = this.credential._id || this.credential.id;
+        if (!credentialId) return;
+
+        await this.credentialRepository.updateAuthenticationStatus(
+            credentialId,
+            false
+        );
+
+        // Keep the in-memory snapshot consistent so that callers can read the
+        // updated state without another fetch.
+        this.credential.auth_is_valid = false;
+    }
+
+    async deauthorize() {
+        this.api = new this.apiClass();
+
+        // Remove persisted credential (if any)
+        if (this.entity?.credential) {
+            const credentialId =
+                this.entity.credential._id || this.entity.credential.id || this.entity.credential;
+
+            // Delete credential via repository
+            await this.credentialRepository.deleteCredentialById(credentialId);
+
+            // Unset credential reference on the Entity document
+            const entityId = this.entity._id || this.entity.id;
+            if (entityId) {
+                await this.moduleRepository.unsetCredential(entityId);
+            }
+
+            // Keep in-memory snapshot consistent
+            this.entity.credential = undefined;
+        }
+    }
+
+    // todo: check if all these props are still up to date
+    validateDefinition(definition) {
+        if (!definition) {
+            throw new Error('Module definition is required');
+        }
+        if (!definition.moduleName) {
+            throw new Error('Module definition requires moduleName');
+        }
+        if (!definition.API) {
+            throw new Error('Module definition requires API class');
+        }
+        if (!definition.requiredAuthMethods) {
+            throw new Error('Module definition requires requiredAuthMethods');
+        } else {
+            if (
+                definition.API.requesterType ===
+                ModuleConstants.authType.oauth2 &&
+                !definition.requiredAuthMethods.getToken
+            ) {
+                throw new Error(
+                    'Module definition requires requiredAuthMethods.getToken'
+                );
+            }
+            if (!definition.requiredAuthMethods.getEntityDetails) {
+                throw new Error(
+                    'Module definition requires requiredAuthMethods.getEntityDetails'
+                );
+            }
+            if (!definition.requiredAuthMethods.getCredentialDetails) {
+                throw new Error(
+                    'Module definition requires requiredAuthMethods.getCredentialDetails'
+                );
+            }
+            if (!definition.requiredAuthMethods.apiPropertiesToPersist) {
+                throw new Error(
+                    'Module definition requires requiredAuthMethods.apiPropertiesToPersist'
+                );
+            } else if (definition.Credential) {
+                for (const prop of definition.requiredAuthMethods
+                    .apiPropertiesToPersist?.credential) {
+                    if (
+                        !definition.Credential.schema.paths.hasOwnProperty(prop)
+                    ) {
+                        throw new Error(
+                            `Module definition requires Credential schema to have property ${prop}`
+                        );
+                    }
+                }
+            }
+            if (!definition.requiredAuthMethods.testAuthRequest) {
+                throw new Error(
+                    'Module definition requires requiredAuthMethods.testAuth'
+                );
+            }
+        }
+    }
+}
+
+module.exports = { Module }; 

package/{module-plugin → modules}/test/mock-api/api.js

@@ -1,5 +1,5 @@
-const { get } = require('../../assertions');
-const { OAuth2Requester } = require('../../module-plugin');
+const { get } = require('../../../assertions');
+const { OAuth2Requester } = require('../..');
 
 class Api extends OAuth2Requester {
     constructor(params) {
@@ -23,7 +23,12 @@ class Api extends OAuth2Requester {
         return this.authorizationUri;
     }
 
-
+    getAuthorizationRequirements() {
+        return {
+            url: this.getAuthUri(),
+            type: 'oauth2',
+        };
+    }
 }
 
 module.exports = { Api };

package/{module-plugin → modules}/test/mock-api/definition.js

@@ -1,19 +1,23 @@
 require('dotenv').config();
-const {Api} = require('./api');
-const {get} = require('../../assertions');
-const config = {name: 'anapi'}
+const { Api } = require('./api');
+const { get } = require('../../../assertions');
+const config = { name: 'anapi' }
 
 const Definition = {
     API: Api,
-    getName: function() {return config.name},
+    getAuthorizationRequirements: () => ({
+        url: 'http://localhost:3000/redirect/anapi',
+        type: 'oauth2',
+    }),
+    getName: function () { return config.name },
     moduleName: config.name,
     modelName: 'AnApi',
     requiredAuthMethods: {
-        getToken: async function(api, params){
+        getToken: async function (api, params) {
             const code = get(params.data, 'code');
             return api.getTokenFromCode(code);
         },
-        getEntityDetails: async function(api, callbackParams, tokenResponse, userId) {
+        getEntityDetails: async function (api, callbackParams, tokenResponse, userId) {
             const userDetails = await api.getUserDetails();
             return {
                 identifiers: { externalId: userDetails.portalId, user: userId },
@@ -26,14 +30,14 @@ const Definition = {
             ],
             entity: [],
         },
-        getCredentialDetails: async function(api, userId) {
+        getCredentialDetails: async function (api, userId) {
             const userDetails = await api.getUserDetails();
             return {
                 identifiers: { externalId: userDetails.portalId, user: userId },
                 details: {}
             };
         },
-        testAuthRequest: async function(api){
+        testAuthRequest: async function (api) {
             return api.getUserDetails()
         },
     },

package/modules/tests/doubles/test-module-factory.js

@@ -0,0 +1,16 @@
+class TestModuleFactory {
+    constructor() { }
+
+    async getModuleInstance(entityId, userId) {
+        // return minimal stub module with getName and api property
+        return {
+            getName() { return 'stubModule'; },
+            api: {},
+            entityId,
+            userId,
+            testAuth: async () => true,
+        };
+    }
+}
+
+module.exports = { TestModuleFactory }; 

package/modules/tests/doubles/test-module-repository.js

@@ -0,0 +1,19 @@
+class TestModuleRepository {
+    constructor() {
+        this.entities = new Map();
+    }
+
+    addEntity(entity) {
+        this.entities.set(entity.id, entity);
+    }
+
+    async findEntityById(id) {
+        return this.entities.get(id);
+    }
+
+    async findEntitiesByIds(ids) {
+        return ids.map((id) => this.entities.get(id));
+    }
+}
+
+module.exports = { TestModuleRepository }; 

package/modules/use-cases/get-entities-for-user.js

@@ -0,0 +1,32 @@
+const { Module } = require('../module');
+const { mapModuleClassToModuleDTO } = require('../utils/map-module-dto');
+
+class GetEntitiesForUser {
+    constructor({ moduleRepository, moduleDefinitions }) {
+        this.moduleRepository = moduleRepository;
+
+        this.definitionMap = new Map();
+        for (const definition of moduleDefinitions) {
+            this.definitionMap.set(definition.modelName, definition);
+        }
+    }
+
+    async execute(userId) {
+        const entities = await this.moduleRepository.findEntitiesByUserId(
+            userId
+        );
+
+        return entities.map((entity) => {
+            const definition = this.definitionMap.get(entity.moduleName);
+
+            const moduleInstance = new Module({
+                userId,
+                definition: definition,
+                entity: entity,
+            });
+            return mapModuleClassToModuleDTO(moduleInstance);
+        });
+    }
+}
+
+module.exports = { GetEntitiesForUser }; 

package/modules/use-cases/get-entity-options-by-id.js

@@ -0,0 +1,58 @@
+const { Module } = require('../module');
+
+class GetEntityOptionsById {
+    /**
+     * @param {Object} params
+     * @param {import('../module-repository').ModuleRepository} params.moduleRepository
+     * @param {} params.moduleDefinitions
+     */
+    constructor({ moduleRepository, moduleDefinitions }) {
+        this.moduleRepository = moduleRepository;
+        this.moduleDefinitions = moduleDefinitions;
+    }
+
+    /**
+     * Retrieve a Module instance for a given user and entity/module type.
+     * @param {string} userId
+     * @param {string} entityId
+     */
+    async execute(entityId, userId) {
+        const entity = await this.moduleRepository.findEntityById(
+            entityId,
+            userId
+        );
+
+        if (!entity) {
+            throw new Error(`Entity ${entityId} not found`);
+        }
+
+        if (entity.userId !== userId) {
+            throw new Error(
+                `Entity ${entityId} does not belong to user ${userId}`
+            );
+        }
+
+        const entityType = entity.type;
+        const moduleDefinition = this.moduleDefinitions.find((def) => {
+            const modelName = Module.getEntityModelFromDefinition(def).modelName;
+            return entityType === modelName;
+        });
+
+        if (!moduleDefinition) {
+            throw new Error(
+                `Module definition not found for entity type: ${entityType}`
+            );
+        }
+
+        const module = new Module({
+            userId,
+            entity,
+            definition: moduleDefinition,
+        });
+
+        const entityOptions = await module.getEntityOptions();
+        return entityOptions;
+    }
+}
+
+module.exports = { GetEntityOptionsById };

package/modules/use-cases/get-entity-options-by-type.js

@@ -0,0 +1,34 @@
+const { Module } = require('../module');
+
+class GetEntityOptionsByType {
+    /**
+     * @param {Object} params
+     * @param {} params.moduleDefinitions
+     */
+    constructor({ moduleDefinitions }) {
+        this.moduleDefinitions = moduleDefinitions;
+    }
+
+    /**
+     * Retrieve a Module instance for a given user and entity/module type.
+     * @param {string} userId
+     * @param {string} type – human-readable module/entity type (e.g. "Hubspot")
+     */
+    async execute(userId, type) {
+        const moduleDefinition = this.moduleDefinitions.find(
+            (def) => def.getName() === type
+        );
+        if (!moduleDefinition) {
+            throw new Error(`Module definition not found for type: ${type}`);
+        }
+        const moduleInstance = new Module({
+            userId,
+            definition: moduleDefinition,
+        });
+
+        const entityOptions = await moduleInstance.getEntityOptions();
+        return entityOptions;
+    }
+}
+
+module.exports = { GetEntityOptionsByType };

package/modules/use-cases/get-module-instance-from-type.js

@@ -0,0 +1,31 @@
+const { Module } = require('../module');
+
+class GetModuleInstanceFromType {
+    /**
+     * @param {Object} params
+     * @param {} params.moduleDefinitions
+     */
+    constructor({ moduleDefinitions }) {
+        this.moduleDefinitions = moduleDefinitions;
+    }
+
+    /**
+     * Retrieve a Module instance for a given user and entity/module type.
+     * @param {string} userId
+     * @param {string} type – human-readable module/entity type (e.g. "Hubspot")
+     */
+    async execute(userId, type) {
+        const moduleDefinition = this.moduleDefinitions.find(
+            (def) => def.getName() === type
+        );
+        if (!moduleDefinition) {
+            throw new Error(`Module definition not found for type: ${type}`);
+        }
+        return new Module({
+            userId,
+            definition: moduleDefinition,
+        });
+    }
+}
+
+module.exports = { GetModuleInstanceFromType };

package/modules/use-cases/get-module.js

@@ -0,0 +1,56 @@
+const { Module } = require('../module');
+
+class GetModule {
+    constructor({ moduleRepository, moduleDefinitions }) {
+        this.moduleRepository = moduleRepository;
+        this.moduleDefinitions = moduleDefinitions;
+    }
+
+    async execute(entityId, userId) {
+        const entity = await this.moduleRepository.findEntityById(
+            entityId,
+            userId
+        );
+
+        if (!entity) {
+            throw new Error(`Entity ${entityId} not found`);
+        }
+
+        if (entity.userId !== userId) {
+            throw new Error(
+                `Entity ${entityId} does not belong to user ${userId}`
+            );
+        }
+
+        const entityType = entity.type;
+        const moduleDefinition = this.moduleDefinitions.find((def) => {
+            const modelName = Module.getEntityModelFromDefinition(def).modelName;
+            return entityType === modelName;
+        });
+
+        if (!moduleDefinition) {
+            throw new Error(
+                `Module definition not found for entity type: ${entityType}`
+            );
+        }
+
+        const module = new Module({
+            userId,
+            entity,
+            definition: moduleDefinition,
+        });
+
+        // todo: this properties should be methods in the Module class
+        return {
+            id: module.entity.id,
+            name: module.entity.name,
+            type: module.entity.moduleName,
+            moduleName: module.entity.moduleName,
+            credential: module.credential,
+            externalId: module.entity.externalId,
+            userId: module.entity.user.toString(),
+        }
+    }
+}
+
+module.exports = { GetModule };

package/modules/use-cases/process-authorization-callback.js

@@ -0,0 +1,114 @@
+const { Module } = require('../module');
+const { ModuleConstants } = require('../ModuleConstants');
+
+class ProcessAuthorizationCallback {
+    /**
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../module-repository').ModuleRepository} params.moduleRepository - Repository for module data operations.
+     * @param {import('../../credential/credential-repository').CredentialRepository} params.credentialRepository - Repository for credential data operations.
+     * @param {Array<Object>} params.moduleDefinitions - Array of module definitions.
+     */
+    constructor({ moduleRepository, credentialRepository, moduleDefinitions }) {
+        this.moduleRepository = moduleRepository;
+        this.credentialRepository = credentialRepository;
+        this.moduleDefinitions = moduleDefinitions;
+    }
+
+    async execute(userId, entityType, params, credentialId = null) {
+        const moduleDefinition = this.moduleDefinitions.find((def) => {
+            return entityType === def.modelName;
+        });
+
+        if (!moduleDefinition) {
+            throw new Error(
+                `Module definition not found for entity type: ${entityType}`
+            );
+        }
+
+        let credential = null;
+        let entity = null;
+
+        if (credentialId) {
+            credential = await this.credentialRepository.findCredentialById(credentialId);
+            if (!credential) {
+                throw new Error(`Credential ${credentialId} not found`);
+            }
+        }
+
+        const module = new Module({
+            userId,
+            entity,
+            definition: moduleDefinition,
+        });
+
+        let tokenResponse;
+        if (module.apiClass.requesterType === ModuleConstants.authType.oauth2) {
+            tokenResponse = await moduleDefinition.requiredAuthMethods.getToken(module.api, params);
+        } else {
+            tokenResponse = await moduleDefinition.requiredAuthMethods.setAuthParams(module.api, params);
+            await this.onTokenUpdate(module, moduleDefinition, userId);
+        }
+
+        const authRes = await module.testAuth();
+        if (!authRes) {
+            throw new Error('Authorization failed');
+        }
+
+        const entityDetails = await moduleDefinition.requiredAuthMethods.getEntityDetails(
+            module.api,
+            params,
+            tokenResponse,
+            userId
+        );
+
+        Object.assign(
+            entityDetails.details,
+            module.apiParamsFromEntity(module.api)
+        );
+
+        const persistedEntity = await this.findOrCreateEntity(entityDetails, entityType);
+
+        return {
+            credential_id: module.credential.id,
+            entity_id: persistedEntity.id,
+            type: module.getName(),
+        };
+    }
+
+    async onTokenUpdate(module, moduleDefinition, userId) {
+        const credentialDetails = await moduleDefinition.requiredAuthMethods.getCredentialDetails(
+            module.api,
+            userId
+        );
+
+        Object.assign(
+            credentialDetails.details,
+            module.apiParamsFromCredential(module.api)
+        );
+        credentialDetails.details.auth_is_valid = true;
+
+        await this.credentialRepository.upsertCredential(credentialDetails);
+    }
+
+    async findOrCreateEntity(entityDetails, entityType) {
+        const { identifiers, details } = entityDetails;
+
+        const existingEntity = await this.moduleRepository.findEntity({
+            externalId: identifiers.externalId,
+            user: identifiers.user,
+            __t: entityType
+        });
+
+        if (existingEntity) {
+            return existingEntity;
+        }
+
+        return await this.moduleRepository.createEntity({
+            ...identifiers,
+            ...details,
+            __t: entityType
+        });
+    }
+}
+
+module.exports = { ProcessAuthorizationCallback };