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

package/modules/module.js

@@ -0,0 +1,274 @@
+const { Delegate } = require('../core');
+const _ = require('lodash');
+const { flushDebugLog } = require('../logs');
+const { ModuleConstants } = require('./ModuleConstants');
+const {
+    createCredentialRepository,
+} = require('../credential/repositories/credential-repository-factory');
+const {
+    createModuleRepository,
+} = require('./repositories/module-repository-factory');
+
+// 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
+     * @param {string} [params.state] Optional OAuth state value forwarded to the API client (round-trips through the OAuth provider).
+     */
+    constructor({ definition, userId = null, entity: entityObj = null, state = 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;
+
+        this.credentialRepository = createCredentialRepository();
+        this.moduleRepository = createModuleRepository();
+
+        // Module → parent delegate (typically IntegrationBase) events
+        this.DLGT_CREDENTIAL_INVALIDATED = 'CREDENTIAL_INVALIDATED';
+        this.delegateTypes.push(this.DLGT_CREDENTIAL_INVALIDATED);
+        this.DLGT_CREDENTIAL_VALIDATED = 'CREDENTIAL_VALIDATED';
+        this.delegateTypes.push(this.DLGT_CREDENTIAL_VALIDATED);
+
+        Object.assign(this, this.definition.requiredAuthMethods);
+
+        const apiParams = {
+            ...this.definition.env,
+            delegate: this,
+            ...(state ? { state } : {}),
+            ...(this.credential?.data
+                ? this.apiParamsFromCredential(this.credential.data)
+                : {}), // Handle case when credential is undefined
+            ...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);
+    }
+
+    validateAuthorizationRequirements() {
+        const requirements = this.getAuthorizationRequirements();
+        let valid = true;
+        if (
+            ['oauth1', 'oauth2'].includes(requirements.type) &&
+            !requirements.url
+        ) {
+            valid = false;
+        }
+        return valid;
+    }
+
+    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
+        );
+        const apiParams = this.apiParamsFromCredential(this.api);
+
+        if (!apiParams.refresh_token && this.api.isRefreshable) {
+            console.warn(
+                `[Frigg] No refresh_token in apiParams for module ${this.name}.`
+            );
+        }
+
+        Object.assign(credentialDetails.details, apiParams);
+        credentialDetails.details.authIsValid = true;
+
+        const persisted = await this.credentialRepository.upsertCredential(
+            credentialDetails
+        );
+        this.credential = persisted;
+
+        if (this.credential?.id) {
+            try {
+                await this.notify(this.DLGT_CREDENTIAL_VALIDATED, {
+                    credentialId: this.credential.id,
+                    moduleName: this.name,
+                });
+            } catch (err) {
+                console.error(
+                    `[Frigg] Failed to propagate CREDENTIAL_VALIDATED for module ${this.name}:`,
+                    err?.message || err
+                );
+            }
+        }
+    }
+
+    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;
+
+        if (!this.credential.id) return;
+
+        await this.credentialRepository.updateAuthenticationStatus(
+            this.credential.id,
+            false
+        );
+
+        // Keep the in-memory snapshot consistent so that callers can read the
+        // updated state without another fetch.
+        this.credential.authIsValid = false;
+
+        // Propagate upward so a parent delegate (e.g. IntegrationBase) can
+        // react — for instance by flipping Integration.status to DISABLED.
+        // Delegate.notify is a silent no-op when this.delegate is null, so
+        // Module instances constructed outside of an Integration context
+        // (e.g. during ProcessAuthorizationCallback) remain unaffected.
+        //
+        // Best-effort: this method is invoked from the OAuth2Requester 401
+        // refresh catch block, which depends on us NOT throwing. A DB hiccup
+        // in the downstream status flip must not alter refreshAuth's
+        // documented `return false` contract. The credential has already
+        // been persisted as invalid; integrations left un-flipped can be
+        // recovered by the next retry or by operator intervention.
+        try {
+            await this.notify(this.DLGT_CREDENTIAL_INVALIDATED, {
+                credentialId: this.credential.id,
+                moduleName: this.name,
+            });
+        } catch (err) {
+            console.error(
+                `[Frigg] Failed to propagate CREDENTIAL_INVALIDATED for module ${this.name}:`,
+                err?.message || err
+            );
+        }
+    }
+
+    async deauthorize() {
+        //todo: Check if this is correct, we're instantiating a new api without params (credentials, tokens, etc...)
+        this.api = new this.apiClass();
+
+        // Remove persisted credential (if any)
+        if (this.entity?.credential) {
+            const credentialId =
+                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;
+            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/modules/repositories/module-repository-documentdb.js

@@ -0,0 +1,350 @@
+const { prisma } = require('../../database/prisma');
+const {
+    toObjectId,
+    fromObjectId,
+    findMany,
+    findOne,
+    insertOne,
+    updateOne,
+    deleteOne,
+} = require('../../database/documentdb-utils');
+const { ModuleRepositoryInterface } = require('./module-repository-interface');
+const { DocumentDBEncryptionService } = require('../../database/documentdb-encryption-service');
+
+/**
+ * Module/Entity repository for DocumentDB.
+ * Uses DocumentDBEncryptionService for credential decryption.
+ *
+ * Encrypted fields: Credential.data.*
+ *
+ * Note: This repository only reads credentials. CredentialRepository
+ * handles credential creation/updates with encryption.
+ *
+ * @see DocumentDBEncryptionService
+ * @see CredentialRepositoryDocumentDB
+ */
+class ModuleRepositoryDocumentDB extends ModuleRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+        this.encryptionService = new DocumentDBEncryptionService();
+    }
+
+    async findEntityById(entityId) {
+        const objectId = toObjectId(entityId);
+        if (!objectId) {
+            throw new Error(`Entity ${entityId} not found`);
+        }
+        const doc = await findOne(this.prisma, 'Entity', { _id: objectId });
+        if (!doc) {
+            throw new Error(`Entity ${entityId} not found`);
+        }
+        const credential = await this._fetchCredential(doc.credentialId);
+        return this._mapEntity(doc, credential);
+    }
+
+    async findEntitiesByUserId(userId) {
+        const objectId = toObjectId(userId);
+        if (!objectId) {
+            throw new Error(`Invalid userId: ${userId}`);
+        }
+        const filter = { userId: objectId };
+        const docs = await findMany(this.prisma, 'Entity', filter);
+        const credentialMap = await this._fetchCredentialsBulk(docs.map((doc) => doc.credentialId));
+        return docs.map((doc) => this._mapEntity(doc, credentialMap.get(fromObjectId(doc.credentialId)) || null));
+    }
+
+    async findEntitiesByIds(entitiesIds) {
+        const ids = (entitiesIds || []).map((id) => toObjectId(id)).filter(Boolean);
+        if (ids.length === 0) return [];
+        const docs = await findMany(this.prisma, 'Entity', { _id: { $in: ids } });
+        const credentialMap = await this._fetchCredentialsBulk(docs.map((doc) => doc.credentialId));
+        return docs.map((doc) => this._mapEntity(doc, credentialMap.get(fromObjectId(doc.credentialId)) || null));
+    }
+
+    async findEntitiesByUserIdAndModuleName(userId, moduleName) {
+        const objectId = toObjectId(userId);
+        if (!objectId) {
+            throw new Error(`Invalid userId: ${userId}`);
+        }
+        const filter = {
+            userId: objectId,
+            moduleName,
+        };
+        const docs = await findMany(this.prisma, 'Entity', filter);
+        const credentialMap = await this._fetchCredentialsBulk(docs.map((doc) => doc.credentialId));
+        return docs.map((doc) => this._mapEntity(doc, credentialMap.get(fromObjectId(doc.credentialId)) || null));
+    }
+
+    async unsetCredential(entityId) {
+        const objectId = toObjectId(entityId);
+        if (!objectId) return false;
+        await updateOne(
+            this.prisma,
+            'Entity',
+            { _id: objectId },
+            {
+                $set: {
+                    credentialId: null,
+                },
+            }
+        );
+        return true;
+    }
+
+    async findEntity(filter) {
+        const query = this._buildFilter(filter);
+        const doc = await findOne(this.prisma, 'Entity', query);
+        if (!doc) return null;
+        const credential = await this._fetchCredential(doc.credentialId);
+        return this._mapEntity(doc, credential);
+    }
+
+    async findEntities(filter) {
+        const query = this._buildFilter(filter);
+        const docs = await findMany(this.prisma, 'Entity', query);
+        if (!docs || docs.length === 0) return [];
+        const credentialMap = await this._fetchCredentialsBulk(
+            docs.map((doc) => doc.credentialId)
+        );
+        return docs.map((doc) =>
+            this._mapEntity(
+                doc,
+                credentialMap.get(fromObjectId(doc.credentialId)) || null
+            )
+        );
+    }
+
+    async createEntity(entityData) {
+        const {
+            user,
+            userId,
+            credential,
+            credentialId,
+            name,
+            moduleName,
+            externalId,
+            ...dynamicData
+        } = entityData;
+
+        const document = {
+            userId: toObjectId(userId || user),
+            credentialId: toObjectId(credentialId || credential) || null,
+            name: name ?? null,
+            moduleName: moduleName ?? null,
+            externalId: externalId ?? null,
+            data: dynamicData,
+        };
+        const insertedId = await insertOne(this.prisma, 'Entity', document);
+        const created = await findOne(this.prisma, 'Entity', { _id: insertedId });
+        const credentialObj = await this._fetchCredential(created?.credentialId);
+        return this._mapEntity(created, credentialObj);
+    }
+
+    async updateEntity(entityId, updates) {
+        const objectId = toObjectId(entityId);
+        if (!objectId) return null;
+
+        const existing = await findOne(this.prisma, 'Entity', { _id: objectId });
+        if (!existing) return null;
+
+        const {
+            user,
+            userId,
+            credential,
+            credentialId,
+            name,
+            moduleName,
+            externalId,
+            ...dynamicData
+        } = updates;
+
+        const updatePayload = {};
+        if (user !== undefined || userId !== undefined) {
+            updatePayload.userId = toObjectId(userId || user) || null;
+        }
+        if (credential !== undefined || credentialId !== undefined) {
+            updatePayload.credentialId = toObjectId(credentialId || credential) || null;
+        }
+        if (name !== undefined) updatePayload.name = name;
+        if (moduleName !== undefined) updatePayload.moduleName = moduleName;
+        if (externalId !== undefined) updatePayload.externalId = externalId;
+
+        if (Object.keys(dynamicData).length > 0) {
+            updatePayload.data = { ...(existing.data || {}), ...dynamicData };
+        }
+
+        await updateOne(
+            this.prisma,
+            'Entity',
+            { _id: objectId },
+            { $set: updatePayload }
+        );
+        const updated = await findOne(this.prisma, 'Entity', { _id: objectId });
+        if (!updated) return null;
+        const credentialObj = await this._fetchCredential(updated?.credentialId);
+        return this._mapEntity(updated, credentialObj);
+    }
+
+    async deleteEntity(entityId) {
+        const objectId = toObjectId(entityId);
+        if (!objectId) return false;
+        const result = await deleteOne(this.prisma, 'Entity', { _id: objectId });
+        const deleted = result?.n ?? 0;
+        return deleted > 0;
+    }
+
+    async _fetchCredential(credentialId) {
+        const id = fromObjectId(credentialId);
+        if (!id) return null;
+
+        try {
+            // Convert to ObjectId for raw query
+            const objectId = toObjectId(id);
+            if (!objectId) return null;
+
+            // Use raw findOne to bypass Prisma encryption extension
+            const rawCredential = await findOne(this.prisma, 'Credential', {
+                _id: objectId
+            });
+
+            if (!rawCredential) return null;
+
+            // Decrypt sensitive fields using service
+            const decryptedCredential = await this.encryptionService.decryptFields('Credential', rawCredential);
+
+            // Return in same format
+            const credential = {
+                id: fromObjectId(decryptedCredential._id),
+                userId: fromObjectId(decryptedCredential.userId),
+                externalId: decryptedCredential.externalId ?? null,
+                authIsValid: decryptedCredential.authIsValid ?? null,
+                createdAt: decryptedCredential.createdAt,
+                updatedAt: decryptedCredential.updatedAt,
+                data: decryptedCredential.data
+            };
+
+            return this._convertCredentialIds(credential);
+        } catch (error) {
+            console.error(`Failed to fetch/decrypt credential ${id}:`, error.message);
+            // Return null instead of throwing to allow graceful degradation
+            // This repository is read-only (doesn't create/update credentials)
+            // Entities can still be loaded even if their credential is corrupted/unreadable
+            // The entity will have null credential, which calling code must handle
+            // This is intentional behavior: prefer partial data over complete failure
+            return null;
+        }
+    }
+
+    async _fetchCredentialsBulk(credentialIds) {
+        const ids = (credentialIds || [])
+            .map((value) => fromObjectId(value))
+            .filter((value) => value !== null && value !== undefined);
+        if (ids.length === 0) return new Map();
+
+        try {
+            // Convert string IDs to ObjectIds for bulk query
+            const objectIds = ids.map(id => toObjectId(id)).filter(Boolean);
+            if (objectIds.length === 0) return new Map();
+
+            // Use raw findMany to bypass Prisma encryption extension
+            const rawCredentials = await findMany(this.prisma, 'Credential', {
+                _id: { $in: objectIds }
+            });
+
+            // Decrypt all credentials in parallel
+            const decryptionPromises = rawCredentials.map(async (rawCredential) => {
+                try {
+                    // Decrypt sensitive fields using service
+                    const decryptedCredential = await this.encryptionService.decryptFields('Credential', rawCredential);
+
+                    // Build credential object in same format as Prisma would return
+                    const credential = {
+                        id: fromObjectId(decryptedCredential._id),
+                        userId: fromObjectId(decryptedCredential.userId),
+                        externalId: decryptedCredential.externalId ?? null,
+                        authIsValid: decryptedCredential.authIsValid ?? null,
+                        createdAt: decryptedCredential.createdAt,
+                        updatedAt: decryptedCredential.updatedAt,
+                        data: decryptedCredential.data
+                    };
+
+                    return this._convertCredentialIds(credential);
+                } catch (error) {
+                    const credId = fromObjectId(rawCredential._id);
+                    console.error(`Failed to decrypt credential ${credId}:`, error.message);
+                    return null;
+                }
+            });
+
+            // Wait for all decryptions to complete
+            const decryptedCredentials = await Promise.all(decryptionPromises);
+
+            // Build Map from results, filtering out nulls
+            const map = new Map();
+            decryptedCredentials.forEach(credential => {
+                if (credential) {
+                    map.set(credential.id, credential);
+                }
+            });
+
+            return map;
+        } catch (error) {
+            console.error('Failed to fetch credentials bulk:', error.message);
+            return new Map();
+        }
+    }
+
+    /**
+     * Convert credential object IDs to strings for application layer
+     * Ensures consistent credential format across database adapters
+     * @private
+     * @param {Object|null} credential - Credential object from database
+     * @returns {Object|null} Credential with properly formatted IDs
+     */
+    _convertCredentialIds(credential) {
+        if (!credential) return credential;
+        return {
+            ...credential,
+            id: credential.id ? String(credential.id) : null,
+            userId: credential.userId ? String(credential.userId) : null,
+        };
+    }
+
+    _buildFilter(filter) {
+        const query = {};
+        if (!filter) return query;
+        if (filter._id || filter.id) {
+            const idObj = toObjectId(filter._id || filter.id);
+            if (idObj) query._id = idObj;
+        }
+        if (filter.user || filter.userId) {
+            const userObj = toObjectId(filter.user || filter.userId);
+            if (userObj) query.userId = userObj;
+        }
+        if (filter.credential || filter.credentialId) {
+            const credObj = toObjectId(filter.credential || filter.credentialId);
+            if (credObj) query.credentialId = credObj;
+        }
+        if (filter.name) query.name = filter.name;
+        if (filter.moduleName) query.moduleName = filter.moduleName;
+        if (filter.externalId) query.externalId = filter.externalId;
+        return query;
+    }
+
+    _mapEntity(doc, credential) {
+        const dynamicData = doc?.data || {};
+        return {
+            id: fromObjectId(doc?._id),
+            credential,
+            userId: fromObjectId(doc?.userId),
+            name: doc?.name ?? null,
+            externalId: doc?.externalId ?? null,
+            moduleName: doc?.moduleName ?? null,
+            ...dynamicData,
+        };
+    }
+}
+
+module.exports = { ModuleRepositoryDocumentDB };
+

package/modules/repositories/module-repository-factory.js

@@ -0,0 +1,40 @@
+const { ModuleRepositoryMongo } = require('./module-repository-mongo');
+const { ModuleRepositoryPostgres } = require('./module-repository-postgres');
+const {
+    ModuleRepositoryDocumentDB,
+} = require('./module-repository-documentdb');
+const config = require('../../database/config');
+
+/**
+ * Module Repository Factory
+ * Creates the appropriate repository adapter based on database type
+ *
+ * @returns {ModuleRepositoryInterface} Configured repository adapter
+ */
+function createModuleRepository() {
+    const dbType = config.DB_TYPE;
+
+    switch (dbType) {
+        case 'mongodb':
+            return new ModuleRepositoryMongo();
+
+        case 'postgresql':
+            return new ModuleRepositoryPostgres();
+
+        case 'documentdb':
+            return new ModuleRepositoryDocumentDB();
+
+        default:
+            throw new Error(
+                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
+            );
+    }
+}
+
+module.exports = {
+    createModuleRepository,
+    // Export adapters for direct testing
+    ModuleRepositoryMongo,
+    ModuleRepositoryPostgres,
+    ModuleRepositoryDocumentDB,
+};