@friggframework/core 2.0.0-next.9 → 2.0.0-next.90

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

@@ -1,22 +1,26 @@
 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 },
+                identifiers: { externalId: userDetails.portalId, userId },
                 details: { name: userDetails.hub_domain },
             }
         },
@@ -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 },
+                identifiers: { externalId: userDetails.portalId, 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,39 @@
+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));
+    }
+
+    async findEntity(filter) {
+        if (!filter || typeof filter !== 'object') {
+            return null;
+        }
+
+        if (filter.id && this.entities.has(filter.id)) {
+            return this.entities.get(filter.id);
+        }
+
+        if (filter.externalId) {
+            for (const entity of this.entities.values()) {
+                if (entity.externalId === filter.externalId) {
+                    return entity;
+                }
+            }
+        }
+
+        return null;
+    }
+}
+
+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.moduleName, 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,71 @@
+const { Module } = require('../module');
+
+class GetEntityOptionsById {
+    /**
+     * @param {Object} params
+     * @param {import('../repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
+     * @param {} params.moduleDefinitions
+     */
+    constructor({ moduleRepository, moduleDefinitions }) {
+        this.moduleRepository = moduleRepository;
+        this.moduleDefinitions = moduleDefinitions;
+    }
+
+    /**
+     * Retrieve entity options for a given entity
+     *
+     * @param {string|number} entityId - Entity ID to retrieve options for
+     * @param {string|number|import('../../user/user').User} userIdOrUser - User ID or User object for validation
+     * @returns {Promise<Object>} Entity options
+     */
+    async execute(entityId, userIdOrUser) {
+        // Support both userId (backward compatible) and User object (new pattern)
+        const userId = typeof userIdOrUser === 'object' && userIdOrUser?.getId
+            ? userIdOrUser.getId()
+            : userIdOrUser;
+
+        const entity = await this.moduleRepository.findEntityById(
+            entityId,
+            userId
+        );
+
+        if (!entity) {
+            throw new Error(`Entity ${entityId} not found`);
+        }
+
+        // Validate entity ownership
+        const isOwned = typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
+            ? userIdOrUser.ownsUserId(entity.userId)
+            : entity.userId?.toString() === userId?.toString();
+
+        if (!isOwned) {
+            throw new Error(
+                `Entity ${entityId} does not belong to user ${userId}`
+            );
+        }
+
+        const entityType = entity.moduleName;
+        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,34 @@
+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")
+     * @param {Object} [options]
+     * @param {string} [options.state] – optional OAuth state value to be forwarded to the API client (round-trips through the OAuth provider).
+     */
+    async execute(userId, type, options = {}) {
+        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,
+            state: options.state,
+        });
+    }
+}
+
+module.exports = { GetModuleInstanceFromType };

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

@@ -0,0 +1,74 @@
+const { Module } = require('../module');
+
+class GetModule {
+    constructor({ moduleRepository, moduleDefinitions }) {
+        this.moduleRepository = moduleRepository;
+        this.moduleDefinitions = moduleDefinitions;
+    }
+
+    /**
+     * Get module instance for an entity
+     *
+     * @param {string|number} entityId - Entity ID to retrieve
+     * @param {string|number|import('../../user/user').User} userIdOrUser - User ID or User object for validation
+     * @returns {Promise<Object>} Module details
+     */
+    async execute(entityId, userIdOrUser) {
+        // Support both userId (backward compatible) and User object (new pattern)
+        const userId = typeof userIdOrUser === 'object' && userIdOrUser?.getId
+            ? userIdOrUser.getId()
+            : userIdOrUser;
+
+        const entity = await this.moduleRepository.findEntityById(
+            entityId,
+            userId
+        );
+
+        if (!entity) {
+            throw new Error(`Entity ${entityId} not found`);
+        }
+
+        // Validate entity ownership
+        // If User object provided, use ownsUserId to check linked users
+        // Otherwise fall back to simple equality check
+        const isOwned = typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
+            ? userIdOrUser.ownsUserId(entity.userId)
+            : entity.userId?.toString() === userId?.toString();
+
+        if (!isOwned) {
+            throw new Error(
+                `Entity ${entityId} does not belong to user ${userId}`
+            );
+        }
+
+        const entityType = entity.moduleName;
+        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,
+            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,243 @@
+const { Module } = require('../module');
+const { ModuleConstants } = require('../ModuleConstants');
+
+// Statuses considered "broken" for an integration whose credentials have just
+// been successfully re-authorized. Both ERROR (system-driven auth failure) and
+// DISABLED (user paused the integration) are flipped back to ENABLED when the
+// user completes a new authorization flow.
+const STATUSES_RESET_ON_REAUTH = ['ERROR', 'DISABLED'];
+
+class ProcessAuthorizationCallback {
+    /**
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../repositories/module-repository-factory').ModuleRepositoryInterface} params.moduleRepository - Repository for module data operations.
+     * @param {import('../../credential/repositories/credential-repository-factory').CredentialRepositoryInterface} params.credentialRepository - Repository for credential data operations.
+     * @param {Array<Object>} params.moduleDefinitions - Array of module definitions.
+     * @param {import('../../integrations/repositories/integration-repository-interface').IntegrationRepositoryInterface} [params.integrationRepository] - Repository for integration data operations. When provided, integrations in a broken state linked to the re-authorized entity are restored to ENABLED.
+     */
+    constructor({
+        moduleRepository,
+        credentialRepository,
+        moduleDefinitions,
+        integrationRepository,
+    }) {
+        this.moduleRepository = moduleRepository;
+        this.credentialRepository = credentialRepository;
+        this.moduleDefinitions = moduleDefinitions;
+        this.integrationRepository = integrationRepository;
+    }
+
+    async execute(userId, entityType, params) {
+        const hasCode = Boolean(params && params.code);
+        console.log(
+            `[Frigg] processAuthorizationCallback start userId=${userId} entityType=${entityType} hasCode=${hasCode}`
+        );
+
+        const moduleDefinition = this.moduleDefinitions.find((def) => {
+            return entityType === def.moduleName;
+        });
+
+        if (!moduleDefinition) {
+            throw new Error(
+                `Module definition not found for entity type: ${entityType}`
+            );
+        }
+
+        // Bootstrap the Module with the existing entity (if any) so the API
+        // requester is preloaded with prior tokens. This enables a refresh
+        // fallback when callers lack a fresh OAuth code, and lets us match a
+        // re-auth back to the existing credential record by id.
+        const existingEntities =
+            await this.moduleRepository.findEntitiesByUserIdAndModuleName(
+                userId,
+                entityType
+            );
+        const existingEntity =
+            existingEntities && existingEntities.length > 0
+                ? existingEntities[0]
+                : null;
+
+        if (existingEntity) {
+            console.log(
+                `[Frigg] processAuthorizationCallback found existing entity id=${existingEntity.id} credentialId=${existingEntity.credential?.id}`
+            );
+        }
+
+        const module = new Module({
+            userId,
+            entity: existingEntity,
+            definition: moduleDefinition,
+        });
+
+        let tokenResponse;
+        if (module.apiClass.requesterType === ModuleConstants.authType.oauth2) {
+            tokenResponse = await moduleDefinition.requiredAuthMethods.getToken(
+                module.api,
+                params
+            );
+            console.log(
+                `[Frigg] processAuthorizationCallback OAuth getToken complete userId=${userId} entityType=${entityType}`
+            );
+            // Belt-and-suspenders: persist tokens explicitly here rather than
+            // relying solely on the DLGT_TOKEN_UPDATE notification chain
+            // inside setTokens. The notification path remains in place but
+            // has been observed to no-op silently in some prod paths,
+            // leaving newly-issued tokens unsaved while the user-visible
+            // OAuth flow appears to succeed.
+            await this.onTokenUpdate(module, moduleDefinition, userId);
+        } else {
+            tokenResponse =
+                await moduleDefinition.requiredAuthMethods.setAuthParams(
+                    module.api,
+                    params
+                );
+            await this.onTokenUpdate(module, moduleDefinition, userId);
+        }
+
+        console.log(
+            `[Frigg] processAuthorizationCallback credential persisted credentialId=${module.credential?.id} authIsValid=${module.credential?.authIsValid}`
+        );
+
+        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,
+            module.credential.id
+        );
+
+        // Best-effort: a hiccup here must not fail a successful re-auth whose
+        // credential + entity are already persisted. Operators can recover
+        // stuck integrations manually.
+        try {
+            const restoredCount = await this.restoreIntegrationsForEntity(
+                persistedEntity.id
+            );
+            console.log(
+                `[Frigg] processAuthorizationCallback restored ${restoredCount} integration(s) for entityId=${persistedEntity.id}`
+            );
+        } catch (err) {
+            console.error(
+                `[Frigg] Failed to restore integrations for entity ${persistedEntity.id} after successful re-auth — manual intervention may be needed`,
+                err
+            );
+        }
+
+        return {
+            credential_id: module.credential.id,
+            entity_id: persistedEntity.id,
+            type: module.getName(),
+        };
+    }
+
+    async restoreIntegrationsForEntity(entityId) {
+        if (!this.integrationRepository) return 0;
+        const integrations =
+            await this.integrationRepository.findIntegrationsByEntityId(
+                entityId
+            );
+        let restored = 0;
+        for (const integration of integrations) {
+            if (STATUSES_RESET_ON_REAUTH.includes(integration.status)) {
+                console.log(
+                    `[Frigg] Restoring integration ${integration.id} from ${integration.status} to ENABLED after successful re-auth (entityId=${entityId})`
+                );
+                await this.integrationRepository.updateIntegrationStatus(
+                    integration.id,
+                    'ENABLED'
+                );
+                restored++;
+            }
+        }
+        return restored;
+    }
+
+    async onTokenUpdate(module, moduleDefinition, userId) {
+        const credentialDetails =
+            await moduleDefinition.requiredAuthMethods.getCredentialDetails(
+                module.api,
+                userId
+            );
+
+        Object.assign(
+            credentialDetails.details,
+            module.apiParamsFromCredential(module.api)
+        );
+        credentialDetails.details.authIsValid = true;
+
+        const persisted = await this.credentialRepository.upsertCredential(credentialDetails);
+        module.credential = persisted;
+    }
+
+    async findOrCreateEntity(entityDetails, moduleName, credentialId) {
+        const { identifiers, details } = entityDetails;
+
+        // Support both 'user' and 'userId' field names from module definitions
+        // Some modules use 'user' (legacy), others use 'userId' (newer pattern)
+        const userId = identifiers.user || identifiers.userId;
+
+        if (!userId) {
+            throw new Error(
+                `Module definition for ${moduleName} must return 'user' or 'userId' in identifiers from getEntityDetails(). ` +
+                    `Without userId, entity lookup would match across all users (security issue).`
+            );
+        }
+
+        const existingEntity = await this.moduleRepository.findEntity({
+            externalId: identifiers.externalId,
+            user: userId,
+            moduleName: moduleName,
+        });
+
+        if (existingEntity) {
+            // Repoint the entity's credentialId when re-auth produced a
+            // different credential than the one currently linked. This
+            // happens when the user re-authenticates against a different
+            // workspace/account of the same provider — `upsertCredential`
+            // matches/creates a credential keyed by externalId, but
+            // findEntity matches the entity by its own externalId, leaving
+            // the entity still linked to the prior workspace's credential
+            // unless we explicitly update the link.
+            const existingCredentialId = existingEntity.credential?.id;
+            if (
+                credentialId &&
+                String(existingCredentialId) !== String(credentialId)
+            ) {
+                console.log(
+                    `[Frigg] Repointing entity ${existingEntity.id} credentialId ${existingCredentialId} -> ${credentialId} after re-auth`
+                );
+                const updated = await this.moduleRepository.updateEntity(
+                    existingEntity.id,
+                    { credential: credentialId }
+                );
+                if (updated) return updated;
+            }
+            return existingEntity;
+        }
+
+        return await this.moduleRepository.createEntity({
+            ...identifiers,
+            ...details,
+            moduleName: moduleName,
+            credential: credentialId,
+        });
+    }
+}
+
+module.exports = { ProcessAuthorizationCallback };

package/modules/use-cases/refresh-entity-options.js

@@ -0,0 +1,72 @@
+const { Module } = require('../module');
+
+class RefreshEntityOptions {
+    /**
+     * @param {Object} params
+     * @param {import('../repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
+     * @param {} params.moduleDefinitions
+     */
+    constructor({ moduleRepository, moduleDefinitions }) {
+        this.moduleRepository = moduleRepository;
+        this.moduleDefinitions = moduleDefinitions;
+    }
+
+    /**
+     * Refresh entity options for a given entity
+     *
+     * @param {string|number} entityId - Entity ID to refresh
+     * @param {string|number|import('../../user/user').User} userIdOrUser - User ID or User object for validation
+     * @param {Object} options - Refresh options
+     * @returns {Promise<Object>} Updated entity options
+     */
+    async execute(entityId, userIdOrUser, options) {
+        // Support both userId (backward compatible) and User object (new pattern)
+        const userId = typeof userIdOrUser === 'object' && userIdOrUser?.getId
+            ? userIdOrUser.getId()
+            : userIdOrUser;
+
+        const entity = await this.moduleRepository.findEntityById(
+            entityId,
+            userId
+        );
+
+        if (!entity) {
+            throw new Error(`Entity ${entityId} not found`);
+        }
+
+        // Validate entity ownership
+        const isOwned = typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
+            ? userIdOrUser.ownsUserId(entity.userId)
+            : entity.userId?.toString() === userId?.toString();
+
+        if (!isOwned) {
+            throw new Error(
+                `Entity ${entityId} does not belong to user ${userId}`
+            );
+        }
+
+        const entityType = entity.moduleName;
+        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,
+        });
+
+        await module.refreshEntityOptions(options);
+        return module.getEntityOptions();
+    }
+}
+
+module.exports = { RefreshEntityOptions };