@friggframework/core 2.0.0-next.1 → 2.0.0-next.100

package/integrations/options.js

@@ -1,6 +1,5 @@
 const { RequiredPropertyError } = require('../errors');
-const { get, getAndVerifyType } = require('../assertions');
-const { ModuleManager } = require('../module-plugin');
+const { get } = require('../assertions');
 
 class Options {
     constructor(params) {
@@ -18,7 +17,7 @@ class Options {
         }
 
         this.display = {};
-        this.display.name = get(params.display, 'name');
+        this.display.name = get(params.display, 'label');
         this.display.description = get(params.display, 'description');
         this.display.detailsUrl = get(params.display, 'detailsUrl');
         this.display.icon = get(params.display, 'icon');
@@ -26,7 +25,7 @@ class Options {
 
     get() {
         return {
-            type: this.module.getName(),
+            type: this.module.definition.getName(),
 
             // Flag for if the User can configure any settings
             hasUserConfig: this.hasUserConfig,

package/integrations/repositories/config-patch-shared.js

@@ -0,0 +1,43 @@
+/**
+ * Shared validation for IntegrationRepository.patchIntegrationConfig().
+ *
+ * A patch is an atomic shallow merge into Integration.config: every key in
+ * the patch is written, every other existing key is left untouched. This
+ * contract is enforced here, before any adapter emits a query, so a bug fix
+ * (or a tighter rule) fixes all three backends in one place.
+ *
+ * Keys may not contain '.' or start with '$' — both are reserved by the
+ * MongoDB/DocumentDB update-command syntax the mongo and documentdb adapters
+ * use to address `config.<key>` paths. A value of `null` is allowed and sets
+ * the key to null — the only way to clear a config field over the PATCH HTTP
+ * endpoint (it sets the value, it does not remove the key). `undefined` is
+ * rejected: it can't arrive over JSON and signals a programming error, not an
+ * intent. Removing a key entirely still requires a full replace via updateConfig.
+ */
+function validateConfigPatch(patch) {
+    if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+        throw new Error('patchIntegrationConfig: patch must be a non-null object');
+    }
+
+    const keys = Object.keys(patch);
+    if (keys.length === 0) {
+        throw new Error(
+            'patchIntegrationConfig: patch must contain at least one key'
+        );
+    }
+
+    for (const key of keys) {
+        if (key.includes('.') || key.startsWith('$')) {
+            throw new Error(
+                `patchIntegrationConfig: patch key '${key}' cannot contain '.' or start with '$'`
+            );
+        }
+        if (patch[key] === undefined) {
+            throw new Error(
+                `patchIntegrationConfig: patch['${key}'] cannot be undefined`
+            );
+        }
+    }
+}
+
+module.exports = { validateConfigPatch };

package/integrations/repositories/integration-mapping-repository-documentdb.js

@@ -0,0 +1,280 @@
+const { prisma } = require('../../database/prisma');
+const {
+    toObjectId,
+    fromObjectId,
+    findMany,
+    findOne,
+    insertOne,
+    updateOne,
+    deleteOne,
+    deleteMany,
+} = require('../../database/documentdb-utils');
+const {
+    IntegrationMappingRepositoryInterface,
+} = require('./integration-mapping-repository-interface');
+const {
+    DocumentDBEncryptionService,
+} = require('../../database/documentdb-encryption-service');
+class IntegrationMappingRepositoryDocumentDB extends IntegrationMappingRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+        this.encryptionService = new DocumentDBEncryptionService();
+    }
+
+    async findMappingBy(integrationId, sourceId) {
+        const filter = this._compositeFilter(integrationId, sourceId);
+        const doc = await findOne(this.prisma, 'IntegrationMapping', filter);
+        if (!doc) return null;
+
+        const decryptedMapping = await this.encryptionService.decryptFields(
+            'IntegrationMapping',
+            doc
+        );
+        return this._mapMapping(decryptedMapping);
+    }
+
+    async upsertMapping(integrationId, sourceId, mapping) {
+        const filter = this._compositeFilter(integrationId, sourceId);
+        const existing = await findOne(
+            this.prisma,
+            'IntegrationMapping',
+            filter
+        );
+        const now = new Date();
+
+        if (existing) {
+            const decryptedExisting =
+                await this.encryptionService.decryptFields(
+                    'IntegrationMapping',
+                    existing
+                );
+
+            const updateDocument = {
+                mapping,
+                updatedAt: now,
+            };
+
+            const encryptedUpdate = await this.encryptionService.encryptFields(
+                'IntegrationMapping',
+                { mapping: updateDocument.mapping }
+            );
+
+            await updateOne(
+                this.prisma,
+                'IntegrationMapping',
+                { _id: existing._id },
+                {
+                    $set: {
+                        mapping: encryptedUpdate.mapping,
+                        updatedAt: updateDocument.updatedAt,
+                    },
+                }
+            );
+
+            const updated = await findOne(this.prisma, 'IntegrationMapping', {
+                _id: existing._id,
+            });
+            if (!updated) {
+                console.error(
+                    '[IntegrationMappingRepositoryDocumentDB] Mapping not found after update',
+                    {
+                        mappingId: fromObjectId(existing._id),
+                        integrationId,
+                        sourceId,
+                    }
+                );
+                throw new Error(
+                    'Failed to update mapping: Document not found after update. ' +
+                        'This indicates a database consistency issue.'
+                );
+            }
+            const decryptedMapping = await this.encryptionService.decryptFields(
+                'IntegrationMapping',
+                updated
+            );
+            return this._mapMapping(decryptedMapping);
+        }
+
+        const plainDocument = {
+            integrationId: integrationId,
+            sourceId:
+                sourceId === null || sourceId === undefined
+                    ? null
+                    : String(sourceId),
+            mapping,
+            createdAt: now,
+            updatedAt: now,
+        };
+
+        const encryptedDocument = await this.encryptionService.encryptFields(
+            'IntegrationMapping',
+            plainDocument
+        );
+
+        const insertedId = await insertOne(
+            this.prisma,
+            'IntegrationMapping',
+            encryptedDocument
+        );
+
+        const created = await findOne(this.prisma, 'IntegrationMapping', {
+            _id: insertedId,
+        });
+        if (!created) {
+            console.error(
+                '[IntegrationMappingRepositoryDocumentDB] Mapping not found after insert',
+                {
+                    insertedId: fromObjectId(insertedId),
+                    integrationId,
+                    sourceId,
+                }
+            );
+            throw new Error(
+                'Failed to create mapping: Document not found after insert. ' +
+                    'This indicates a database consistency issue.'
+            );
+        }
+        const decryptedMapping = await this.encryptionService.decryptFields(
+            'IntegrationMapping',
+            created
+        );
+        return this._mapMapping(decryptedMapping);
+    }
+
+    async findMappingsByIntegration(integrationId) {
+        const filter = {};
+        if (integrationId) filter.integrationId = integrationId;
+        const docs = await findMany(this.prisma, 'IntegrationMapping', filter);
+
+        const decryptedDocs = await Promise.all(
+            docs.map((doc) =>
+                this.encryptionService.decryptFields('IntegrationMapping', doc)
+            )
+        );
+
+        return decryptedDocs.map((doc) => this._mapMapping(doc));
+    }
+
+    async deleteMapping(integrationId, sourceId) {
+        const filter = this._compositeFilter(integrationId, sourceId);
+        const result = await deleteOne(
+            this.prisma,
+            'IntegrationMapping',
+            filter
+        );
+        const deleted = result?.n ?? 0;
+        return { acknowledged: true, deletedCount: deleted };
+    }
+
+    async deleteMappingsByIntegration(integrationId) {
+        if (!integrationId) {
+            return { acknowledged: true, deletedCount: 0 };
+        }
+        const result = await deleteMany(this.prisma, 'IntegrationMapping', {
+            integrationId: integrationId,
+        });
+        const deleted = result?.n ?? 0;
+        return { acknowledged: true, deletedCount: deleted };
+    }
+
+    async findMappingById(id) {
+        const objectId = toObjectId(id);
+        if (!objectId) return null;
+        const doc = await findOne(this.prisma, 'IntegrationMapping', {
+            _id: objectId,
+        });
+        if (!doc) return null;
+
+        const decryptedMapping = await this.encryptionService.decryptFields(
+            'IntegrationMapping',
+            doc
+        );
+        return this._mapMapping(decryptedMapping);
+    }
+
+    async updateMapping(id, updates) {
+        const objectId = toObjectId(id);
+        if (!objectId) return null;
+
+        const existing = await findOne(this.prisma, 'IntegrationMapping', {
+            _id: objectId,
+        });
+        if (!existing) return null;
+
+        const decryptedExisting = await this.encryptionService.decryptFields(
+            'IntegrationMapping',
+            existing
+        );
+
+        const mergedMapping =
+            updates.mapping !== undefined
+                ? updates.mapping
+                : decryptedExisting.mapping;
+
+        const updateDocument = {
+            ...updates,
+            updatedAt: new Date(),
+        };
+
+        if (mergedMapping !== undefined) {
+            const encryptedUpdate = await this.encryptionService.encryptFields(
+                'IntegrationMapping',
+                { mapping: mergedMapping }
+            );
+            updateDocument.mapping = encryptedUpdate.mapping;
+        }
+
+        await updateOne(
+            this.prisma,
+            'IntegrationMapping',
+            { _id: objectId },
+            {
+                $set: updateDocument,
+            }
+        );
+
+        const updated = await findOne(this.prisma, 'IntegrationMapping', {
+            _id: objectId,
+        });
+        if (!updated) {
+            console.error(
+                '[IntegrationMappingRepositoryDocumentDB] Mapping not found after update',
+                {
+                    mappingId: fromObjectId(objectId),
+                }
+            );
+            throw new Error(
+                'Failed to update mapping: Document not found after update. ' +
+                    'This indicates a database consistency issue.'
+            );
+        }
+        const decryptedMapping = await this.encryptionService.decryptFields(
+            'IntegrationMapping',
+            updated
+        );
+        return this._mapMapping(decryptedMapping);
+    }
+
+    _compositeFilter(integrationId, sourceId) {
+        const filter = {};
+        if (integrationId) filter.integrationId = integrationId;
+        if (sourceId !== undefined) {
+            filter.sourceId = sourceId === null ? null : String(sourceId);
+        }
+        return filter;
+    }
+
+    _mapMapping(doc) {
+        return {
+            id: fromObjectId(doc?._id),
+            integrationId: doc?.integrationId ?? null,
+            sourceId: doc?.sourceId ?? null,
+            mapping: doc?.mapping ?? null,
+            createdAt: doc?.createdAt,
+            updatedAt: doc?.updatedAt,
+        };
+    }
+}
+
+module.exports = { IntegrationMappingRepositoryDocumentDB };

package/integrations/repositories/integration-mapping-repository-factory.js

@@ -0,0 +1,57 @@
+const {
+    IntegrationMappingRepositoryMongo,
+} = require('./integration-mapping-repository-mongo');
+const {
+    IntegrationMappingRepositoryPostgres,
+} = require('./integration-mapping-repository-postgres');
+const {
+    IntegrationMappingRepositoryDocumentDB,
+} = require('./integration-mapping-repository-documentdb');
+const config = require('../../database/config');
+
+/**
+ * Integration Mapping Repository Factory
+ * Creates the appropriate repository adapter based on database type
+ *
+ * Database-specific implementations:
+ * - MongoDB: Uses String IDs (ObjectId), no conversion needed
+ * - PostgreSQL: Uses Int IDs, converts String ↔ Int
+ *
+ * All repository methods return String IDs regardless of database type,
+ * ensuring application layer consistency.
+ *
+ * Usage:
+ * ```javascript
+ * const repository = createIntegrationMappingRepository();
+ * const mapping = await repository.findMappingBy(integrationId, sourceId);
+ * ```
+ *
+ * @returns {IntegrationMappingRepositoryInterface} Configured repository adapter
+ */
+function createIntegrationMappingRepository() {
+    const dbType = config.DB_TYPE;
+
+    switch (dbType) {
+        case 'mongodb':
+            return new IntegrationMappingRepositoryMongo();
+
+        case 'postgresql':
+            return new IntegrationMappingRepositoryPostgres();
+
+        case 'documentdb':
+            return new IntegrationMappingRepositoryDocumentDB();
+
+        default:
+            throw new Error(
+                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
+            );
+    }
+}
+
+module.exports = {
+    createIntegrationMappingRepository,
+    // Export adapters for direct testing
+    IntegrationMappingRepositoryMongo,
+    IntegrationMappingRepositoryPostgres,
+    IntegrationMappingRepositoryDocumentDB,
+};

package/integrations/repositories/integration-mapping-repository-interface.js

@@ -0,0 +1,106 @@
+/**
+ * Integration Mapping Repository Interface
+ * Abstract base class defining the contract for integration mapping persistence adapters
+ *
+ * This follows the Port in Hexagonal Architecture:
+ * - Domain layer depends on this abstraction
+ * - Concrete adapters implement this interface
+ * - Use cases receive repositories via dependency injection
+ *
+ * Note: Currently, IntegrationMapping model has identical structure across MongoDB and PostgreSQL,
+ * so IntegrationMappingRepository serves both. This interface exists for consistency and
+ * future-proofing if database-specific implementations become needed.
+ *
+ * @abstract
+ */
+class IntegrationMappingRepositoryInterface {
+    /**
+     * Find mapping by integration ID and source ID
+     *
+     * @param {string|number} integrationId - The integration ID
+     * @param {string} sourceId - The source ID for lookup
+     * @returns {Promise<Object|null>} The mapping object or null
+     * @abstract
+     */
+    async findMappingBy(integrationId, sourceId) {
+        throw new Error('Method findMappingBy must be implemented by subclass');
+    }
+
+    /**
+     * Create or update a mapping
+     *
+     * @param {string|number} integrationId - The integration ID
+     * @param {string} sourceId - The source ID for lookup
+     * @param {Object} mapping - The mapping data
+     * @returns {Promise<Object>} The created or updated mapping document
+     * @abstract
+     */
+    async upsertMapping(integrationId, sourceId, mapping) {
+        throw new Error('Method upsertMapping must be implemented by subclass');
+    }
+
+    /**
+     * Find all mappings for an integration
+     *
+     * @param {string|number} integrationId - The integration ID
+     * @returns {Promise<Array>} Array of mapping objects
+     * @abstract
+     */
+    async findMappingsByIntegration(integrationId) {
+        throw new Error(
+            'Method findMappingsByIntegration must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Delete a specific mapping
+     *
+     * @param {string|number} integrationId - The integration ID
+     * @param {string} sourceId - The source ID
+     * @returns {Promise<Object>} Deletion result
+     * @abstract
+     */
+    async deleteMapping(integrationId, sourceId) {
+        throw new Error('Method deleteMapping must be implemented by subclass');
+    }
+
+    /**
+     * Delete all mappings for an integration
+     *
+     * @param {string|number} integrationId - The integration ID
+     * @returns {Promise<Object>} Deletion result
+     * @abstract
+     */
+    async deleteMappingsByIntegration(integrationId) {
+        throw new Error(
+            'Method deleteMappingsByIntegration must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Find mapping by ID
+     *
+     * @param {string|number} id - The mapping ID
+     * @returns {Promise<Object|null>} The mapping object or null
+     * @abstract
+     */
+    async findMappingById(id) {
+        throw new Error(
+            'Method findMappingById must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Update a mapping by ID
+     *
+     * @param {string|number} id - The mapping ID
+     * @param {Object} updates - Fields to update
+     * @returns {Promise<Object>} Updated mapping object
+     * @abstract
+     */
+    async updateMapping(id, updates) {
+        throw new Error('Method updateMapping must be implemented by subclass');
+    }
+}
+
+module.exports = { IntegrationMappingRepositoryInterface };

package/integrations/repositories/integration-mapping-repository-mongo.js

@@ -0,0 +1,161 @@
+const { prisma } = require('../../database/prisma');
+const {
+    IntegrationMappingRepositoryInterface,
+} = require('./integration-mapping-repository-interface');
+
+/**
+ * MongoDB Integration Mapping Repository Adapter
+ * Handles persistence of integration mappings used for data transformation
+ *
+ * MongoDB-specific characteristics:
+ * - Uses String IDs (ObjectId)
+ * - No ID conversion needed (IDs are already strings)
+ * - mapping data stored in JSON field
+ */
+class IntegrationMappingRepositoryMongo extends IntegrationMappingRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    /**
+     * Convert any value to string (handles null/undefined)
+     * @private
+     * @param {*} value - Value to convert
+     * @returns {string|null|undefined} String value or null/undefined
+     */
+    _toString(value) {
+        if (value === null || value === undefined) return value;
+        return String(value);
+    }
+
+    /**
+     * Find mapping by integration ID and source ID
+     * Replaces: IntegrationMapping.findBy(integrationId, sourceId)
+     *
+     * @param {string} integrationId - The integration ID
+     * @param {string} sourceId - The source ID for lookup
+     * @returns {Promise<Object|null>} The mapping object with string IDs or null
+     */
+    async findMappingBy(integrationId, sourceId) {
+        return await this.prisma.integrationMapping.findFirst({
+            where: {
+                integrationId,
+                sourceId: this._toString(sourceId),
+            },
+        });
+    }
+
+    /**
+     * Create or update a mapping
+     * Replaces: IntegrationMapping.upsert(integrationId, sourceId, mapping)
+     *
+     * @param {string} integrationId - The integration ID
+     * @param {string} sourceId - The source ID for lookup
+     * @param {Object} mapping - The mapping data
+     * @returns {Promise<Object>} The created or updated mapping document with string IDs
+     */
+    async upsertMapping(integrationId, sourceId, mapping) {
+        return await this.prisma.integrationMapping.upsert({
+            where: {
+                integrationId_sourceId: {
+                    integrationId,
+                    sourceId: this._toString(sourceId),
+                },
+            },
+            update: {
+                mapping,
+            },
+            create: {
+                integrationId,
+                sourceId: this._toString(sourceId),
+                mapping,
+            },
+        });
+    }
+
+    /**
+     * Find all mappings for an integration
+     * Replaces: IntegrationMapping.find({ integration: integrationId })
+     *
+     * @param {string} integrationId - The integration ID
+     * @returns {Promise<Array>} Array of mapping documents with string IDs
+     */
+    async findMappingsByIntegration(integrationId) {
+        return await this.prisma.integrationMapping.findMany({
+            where: { integrationId },
+        });
+    }
+
+    /**
+     * Delete a mapping by integration and source ID
+     * Replaces: IntegrationMapping.deleteOne({ integration, sourceId })
+     *
+     * @param {string} integrationId - The integration ID
+     * @param {string} sourceId - The source ID
+     * @returns {Promise<Object>} The deletion result
+     */
+    async deleteMapping(integrationId, sourceId) {
+        try {
+            await this.prisma.integrationMapping.delete({
+                where: {
+                    integrationId_sourceId: {
+                        integrationId,
+                        sourceId: this._toString(sourceId),
+                    },
+                },
+            });
+            return { acknowledged: true, deletedCount: 1 };
+        } catch (error) {
+            if (error.code === 'P2025') {
+                // Record not found
+                return { acknowledged: true, deletedCount: 0 };
+            }
+            throw error;
+        }
+    }
+
+    /**
+     * Delete all mappings for an integration
+     * Replaces: IntegrationMapping.deleteMany({ integration: integrationId })
+     *
+     * @param {string} integrationId - The integration ID
+     * @returns {Promise<Object>} The deletion result
+     */
+    async deleteMappingsByIntegration(integrationId) {
+        const result = await this.prisma.integrationMapping.deleteMany({
+            where: { integrationId },
+        });
+
+        return {
+            acknowledged: true,
+            deletedCount: result.count,
+        };
+    }
+
+    /**
+     * Find mapping by ID
+     * @param {string} id - Mapping ID
+     * @returns {Promise<Object|null>} Mapping object with string IDs or null
+     */
+    async findMappingById(id) {
+        return await this.prisma.integrationMapping.findUnique({
+            where: { id },
+        });
+    }
+
+    /**
+     * Update mapping by ID
+     * @param {string} id - Mapping ID
+     * @param {Object} updates - Fields to update
+     * @returns {Promise<Object>} Updated mapping object with string IDs
+     */
+    async updateMapping(id, updates) {
+        return await this.prisma.integrationMapping.update({
+            where: { id },
+            data: updates,
+        });
+    }
+}
+
+module.exports = { IntegrationMappingRepositoryMongo };