@friggframework/core 2.0.0-next.11 → 2.0.0-next.110

package/integrations/options.js

@@ -1,5 +1,5 @@
 const { RequiredPropertyError } = require('../errors');
-const { get, getAndVerifyType } = require('../assertions');
+const { get } = require('../assertions');
 
 class Options {
     constructor(params) {

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,303 @@
+const { prisma } = require('../../database/prisma');
+const {
+    toObjectId,
+    fromObjectId,
+    findMany,
+    findOne,
+    insertOne,
+    updateOne,
+    deleteOne,
+    deleteMany,
+    aggregateDrained,
+} = 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();
+    }
+
+    /**
+     * integrationId is stored as a string in DocumentDB, so ids are matched as
+     * strings (an ObjectId $in would never match). Drains the grouped cursor so
+     * a deployment-wide count is not truncated at the first batch.
+     */
+    async countByIntegrationIds(ids = []) {
+        const counts = new Map();
+        if (!ids || ids.length === 0) return counts;
+
+        const stringIds = ids.map(String);
+        const rows = await aggregateDrained(this.prisma, 'IntegrationMapping', [
+            { $match: { integrationId: { $in: stringIds } } },
+            { $group: { _id: '$integrationId', count: { $sum: 1 } } },
+        ]);
+
+        for (const row of rows) {
+            counts.set(String(row?._id), row?.count ?? 0);
+        }
+        return counts;
+    }
+
+    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,120 @@
+/**
+ * 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'
+        );
+    }
+
+    /**
+     * Count mappings grouped by integration id, for a bounded set of ids.
+     * Adapters must drain the full grouped result (a deployment can have more
+     * than one first-batch of distinct integration ids).
+     *
+     * @returns {Promise<Map<string, number>>} Map of integrationId (string) → count
+     * @abstract
+     */
+    async countByIntegrationIds(ids) {
+        throw new Error(
+            'Method countByIntegrationIds 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 };