@friggframework/core 2.0.0-next.12 → 2.0.0-next.120

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,294 @@
+const { Module } = require('../module');
+const { ModuleConstants } = require('../ModuleConstants');
+const { getLogger } = require('../../logs');
+
+const log = getLogger('frigg.modules.authorization_callback');
+
+// 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) {
+        log.debug('Authorization callback started', {
+            eventName: `${log.name}.started`,
+            userId,
+            entityType,
+            hasCode: Boolean(params && params.code),
+        });
+
+        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) {
+            log.debug('Existing entity found', {
+                eventName: `${log.name}.existing_entity_found`,
+                entityId: existingEntity.id,
+                credentialId: existingEntity.credential?.id,
+            });
+        }
+
+        const module = new Module({
+            userId,
+            entity: existingEntity,
+            definition: moduleDefinition,
+        });
+
+        const authType = module.apiClass.requesterType;
+        log.debug('Module created', {
+            eventName: `${log.name}.module_created`,
+            moduleName: module.getName(),
+            authType,
+        });
+
+        let tokenResponse;
+        if (authType === ModuleConstants.authType.oauth2) {
+            log.debug('Exchanging authorization code for token', {
+                eventName: `${log.name}.token_exchanging`,
+            });
+            tokenResponse = await moduleDefinition.requiredAuthMethods.getToken(
+                module.api,
+                params
+            );
+            log.debug('Token exchange completed', {
+                eventName: `${log.name}.token_exchanged`,
+                tokenKeys: Object.keys(tokenResponse || {}),
+            });
+            // 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 {
+            log.debug('Setting auth params', {
+                eventName: `${log.name}.auth_params_setting`,
+            });
+            tokenResponse =
+                await moduleDefinition.requiredAuthMethods.setAuthParams(
+                    module.api,
+                    params
+                );
+            await this.onTokenUpdate(module, moduleDefinition, userId);
+        }
+
+        log.debug('Credential persisted', {
+            eventName: `${log.name}.credential_persisted`,
+            credentialId: module.credential?.id,
+            authIsValid: module.credential?.authIsValid,
+        });
+
+        log.debug('Testing auth', { eventName: `${log.name}.auth_testing` });
+        const authRes = await module.testAuth();
+        if (!authRes) {
+            throw new Error('Authorization failed');
+        }
+        log.debug('Auth test passed', {
+            eventName: `${log.name}.auth_test_passed`,
+        });
+
+        log.debug('Fetching entity details', {
+            eventName: `${log.name}.entity_details_fetching`,
+        });
+        const entityDetails =
+            await moduleDefinition.requiredAuthMethods.getEntityDetails(
+                module.api,
+                params,
+                tokenResponse,
+                userId
+            );
+        log.debug('Entity details received', {
+            eventName: `${log.name}.entity_details_received`,
+            externalId: entityDetails.identifiers?.externalId,
+        });
+
+        Object.assign(
+            entityDetails.details,
+            module.apiParamsFromEntity(module.api)
+        );
+
+        log.debug('Finding or creating entity', {
+            eventName: `${log.name}.entity_resolving`,
+        });
+        const persistedEntity = await this.findOrCreateEntity(
+            entityDetails,
+            entityType,
+            module.credential.id
+        );
+        log.debug('Authorization callback completed', {
+            eventName: `${log.name}.completed`,
+            entityId: persistedEntity.id,
+            credentialId: 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
+            );
+            log.debug('Integrations restored', {
+                eventName: `${log.name}.integrations_restored`,
+                entityId: persistedEntity.id,
+                restoredCount,
+            });
+        } catch (err) {
+            log.error('Failed to restore integrations after re-auth', {
+                eventName: `${log.name}.integrations_restore_failed`,
+                entityId: persistedEntity.id,
+                error: 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)) {
+                log.info('Integration restored to ENABLED after re-auth', {
+                    eventName: `${log.name}.integration_restored`,
+                    integrationId: integration.id,
+                    previousStatus: integration.status,
+                    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)
+            ) {
+                log.info('Entity credential repointed after re-auth', {
+                    eventName: `${log.name}.entity_credential_repointed`,
+                    entityId: existingEntity.id,
+                    previousCredentialId: existingCredentialId,
+                    credentialId,
+                });
+                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 };