@friggframework/core 2.0.0--canary.702.ef0dc8c.0 → 2.0.0--canary.710.7cfcf12.0

package/database/prisma.js

@@ -1,7 +1,10 @@
 const {
     createEncryptionExtension,
 } = require('./encryption/prisma-encryption-extension');
-const { loadCustomEncryptionSchema } = require('./encryption/encryption-schema-registry');
+const {
+    loadCustomEncryptionSchema,
+    EncryptionSchemaError,
+} = require('./encryption/encryption-schema-registry');
 const { logger } = require('./encryption/logger');
 const { Cryptor } = require('../encrypt/Cryptor');
 const config = require('./config');
@@ -125,6 +128,12 @@ const prismaClientSingleton = () => {
                 `Field-level encryption enabled using ${encryptionConfig.method.toUpperCase()}`
             );
         } catch (error) {
+            // An invalid encryption configuration must fail startup: carrying
+            // on without the extension would write encrypted fields in
+            // plaintext.
+            if (error instanceof EncryptionSchemaError) {
+                throw error;
+            }
             logger.error(
                 'Failed to initialize encryption extension:',
                 error

package/handlers/app-definition-loader.js

@@ -1,9 +1,6 @@
 const { findNearestBackendPackageJson } = require('@friggframework/core/utils');
 const path = require('node:path');
 const fs = require('fs-extra');
-const {
-    applyAppDefinitionDefaults,
-} = require('@friggframework/schemas/app-definition');
 const { resolveTelemetryConfig } = require('../telemetry/telemetry-config');
 const { registerDeniedKeys } = require('../logs/denied-keys');
 const {
@@ -36,9 +33,7 @@ function registerCredentialLogKeys(appDefinition, integrations) {
  * @function loadAppDefinition
  * @description Searches for the nearest backend package.json, loads the corresponding index.js file,
  * and extracts the application definition containing integrations and user configuration.
- * The defaults declared in the app-definition schema are applied first (ADR-051), so
- * `userConfig` always holds a complete user config, also when the app omits `user`.
- * @returns {{integrations: Array<object>, userConfig: object, adminScripts: Array<object>, reports: Array<object>, admin: object, telemetry: object, logging: object | null}} An object containing the application definition.
+ * @returns {{integrations: Array<object>, userConfig: object | null, adminScripts: Array<object>, reports: Array<object>, admin: object, telemetry: object, logging: object | null}} An object containing the application definition.
  * @throws {Error} Throws error if backend package.json cannot be found.
  * @throws {Error} Throws error if index.js file cannot be found in the backend directory.
  * @example
@@ -58,9 +53,7 @@ function loadAppDefinition() {
     }
 
     const backendJsFile = require(backendFilePath);
-    // The one place schema defaults are applied at runtime (ADR-051): a
-    // default in app-definition.schema.json is the value core sees.
-    const appDefinition = applyAppDefinitionDefaults(backendJsFile.Definition);
+    const appDefinition = backendJsFile.Definition;
 
     const {
         integrations = [],

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

@@ -164,6 +164,38 @@ class IntegrationRepositoryDocumentDB extends IntegrationRepositoryInterface {
         return this._mapIntegration(created);
     }
 
+    async addEntitiesToIntegration(integrationId, entityIds) {
+        const objectId = toObjectId(integrationId);
+        if (!objectId) return null;
+        const result = await updateOne(
+            this.prisma,
+            'Integration',
+            { _id: objectId },
+            {
+                $addToSet: { entityIds: { $each: toObjectIdArray(entityIds) } },
+                $set: { updatedAt: { $date: new Date().toISOString() } },
+            }
+        );
+        if (!result?.n) return null;
+        return this.findIntegrationById(integrationId);
+    }
+
+    async removeEntitiesFromIntegration(integrationId, entityIds) {
+        const objectId = toObjectId(integrationId);
+        if (!objectId) return null;
+        const result = await updateOne(
+            this.prisma,
+            'Integration',
+            { _id: objectId },
+            {
+                $pullAll: { entityIds: toObjectIdArray(entityIds) },
+                $set: { updatedAt: { $date: new Date().toISOString() } },
+            }
+        );
+        if (!result?.n) return null;
+        return this.findIntegrationById(integrationId);
+    }
+
     async findIntegrationByUserId(userId) {
         const objectId = toObjectId(userId);
         if (!objectId) return null;

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

@@ -184,6 +184,36 @@ class IntegrationRepositoryInterface {
             'Method findIntegrationsByEntityId must be implemented by subclass'
         );
     }
+
+    /**
+     * Attach entities to an existing integration. Entities that are already
+     * attached are left as they are.
+     *
+     * @param {string|number} integrationId - Integration ID
+     * @param {Array<string|number>} entityIds - Entity IDs to attach
+     * @returns {Promise<Object|null>} Updated integration, or null when the integration does not exist
+     * @abstract
+     */
+    async addEntitiesToIntegration(integrationId, entityIds) {
+        throw new Error(
+            'Method addEntitiesToIntegration must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Detach entities from an integration. Entities that are not attached
+     * are ignored; the entities themselves are not deleted.
+     *
+     * @param {string|number} integrationId - Integration ID
+     * @param {Array<string|number>} entityIds - Entity IDs to detach
+     * @returns {Promise<Object|null>} Updated integration, or null when the integration does not exist
+     * @abstract
+     */
+    async removeEntitiesFromIntegration(integrationId, entityIds) {
+        throw new Error(
+            'Method removeEntitiesFromIntegration must be implemented by subclass'
+        );
+    }
 }
 
 module.exports = { IntegrationRepositoryInterface };

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

@@ -338,6 +338,58 @@ class IntegrationRepositoryMongo extends IntegrationRepositoryInterface {
         };
     }
 
+    /**
+     * Attach entities to an existing integration. Entities already attached
+     * are left as they are.
+     *
+     * @param {string} integrationId - Integration ID
+     * @param {Array<string>} entityIds - Entity IDs to attach
+     * @returns {Promise<Object|null>} Updated integration, or null when the integration does not exist
+     */
+    async addEntitiesToIntegration(integrationId, entityIds) {
+
+        try {
+            await this.prisma.integration.update({
+                where: { id: integrationId },
+                data: {
+                    entities: {
+                        connect: entityIds.map((id) => ({ id })),
+                    },
+                },
+            });
+        } catch (error) {
+            if (error.code === 'P2025') return null;
+            throw error;
+        }
+        return this.findIntegrationById(integrationId);
+    }
+
+    /**
+     * Detach entities from an integration. Entities that are not attached
+     * are ignored. The entities themselves are not deleted.
+     *
+     * @param {string} integrationId - Integration ID
+     * @param {Array<string>} entityIds - Entity IDs to detach
+     * @returns {Promise<Object|null>} Updated integration, or null when the integration does not exist
+     */
+    async removeEntitiesFromIntegration(integrationId, entityIds) {
+
+        try {
+            await this.prisma.integration.update({
+                where: { id: integrationId },
+                data: {
+                    entities: {
+                        disconnect: entityIds.map((id) => ({ id })),
+                    },
+                },
+            });
+        } catch (error) {
+            if (error.code === 'P2025') return null;
+            throw error;
+        }
+        return this.findIntegrationById(integrationId);
+    }
+
     /**
      * Find integration by user ID (returns single integration)
      * Replaces: IntegrationModel.findOne({ user: userId }).populate('entities')

package/integrations/repositories/integration-repository-postgres.js

@@ -365,6 +365,64 @@ class IntegrationRepositoryPostgres extends IntegrationRepositoryInterface {
         };
     }
 
+    /**
+     * Attach entities to an existing integration. Entities already attached
+     * are left as they are.
+     *
+     * @param {string} integrationId - Integration ID (string from application layer)
+     * @param {Array<string>} entityIds - Entity IDs to attach
+     * @returns {Promise<Object|null>} Updated integration, or null when the integration does not exist
+     */
+    async addEntitiesToIntegration(integrationId, entityIds) {
+        const intId = this._convertId(integrationId);
+
+        try {
+            await this.prisma.integration.update({
+                where: { id: intId },
+                data: {
+                    entities: {
+                        connect: entityIds.map((id) => ({
+                            id: this._convertId(id),
+                        })),
+                    },
+                },
+            });
+        } catch (error) {
+            if (error.code === 'P2025') return null;
+            throw error;
+        }
+        return this.findIntegrationById(integrationId);
+    }
+
+    /**
+     * Detach entities from an integration. Entities that are not attached
+     * are ignored. The entities themselves are not deleted.
+     *
+     * @param {string} integrationId - Integration ID (string from application layer)
+     * @param {Array<string>} entityIds - Entity IDs to detach
+     * @returns {Promise<Object|null>} Updated integration, or null when the integration does not exist
+     */
+    async removeEntitiesFromIntegration(integrationId, entityIds) {
+        const intId = this._convertId(integrationId);
+
+        try {
+            await this.prisma.integration.update({
+                where: { id: intId },
+                data: {
+                    entities: {
+                        disconnect: entityIds.map((id) => ({
+                            id: this._convertId(id),
+                        })),
+                    },
+                },
+            });
+        } catch (error) {
+            if (error.code === 'P2025') return null;
+            throw error;
+        }
+        return this.findIntegrationById(integrationId);
+    }
+
     /**
      * Find integration by user ID (returns single integration)
      *

package/integrations/use-cases/add-entities-to-integration.js

@@ -0,0 +1,92 @@
+const {
+    assertEntityIdsInput,
+    integrationNotFound,
+    loadIntegration,
+} = require('../utils/assert-entity-ids-input');
+
+/**
+ * Attaches entities to an existing integration, e.g. when a user grants
+ * access to more accounts after the integration was created. Every entity
+ * must exist, belong to the integration's user, and be of a module the
+ * integration already holds (so hydration can load it). Entities that are
+ * already attached are left as they are.
+ * @class AddEntitiesToIntegration
+ */
+class AddEntitiesToIntegration {
+    /**
+     * @param {Object} params
+     * @param {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface} params.integrationRepository
+     * @param {import('../../modules/repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
+     */
+    constructor({ integrationRepository, moduleRepository }) {
+        this.integrationRepository = integrationRepository;
+        this.moduleRepository = moduleRepository;
+    }
+
+    /**
+     * @param {string} integrationId
+     * @param {string[]} entityIds
+     * @returns {Promise<Object>} The updated integration record.
+     */
+    async execute(integrationId, entityIds) {
+        assertEntityIdsInput(integrationId, entityIds);
+
+        const integration = await loadIntegration(
+            this.integrationRepository,
+            integrationId
+        );
+
+        const entities = await this.moduleRepository.findEntitiesByIds(
+            entityIds
+        );
+        const foundIds = new Set(entities.map((e) => String(e.id)));
+        const missing = entityIds.filter((id) => !foundIds.has(String(id)));
+        if (missing.length > 0) {
+            const error = new Error(
+                `Entities not found: ${missing.join(', ')}`
+            );
+            error.code = 'ENTITIES_NOT_FOUND';
+            throw error;
+        }
+
+        const foreign = entities.filter(
+            (e) => String(e.userId) !== String(integration.userId)
+        );
+        if (foreign.length > 0) {
+            const error = new Error(
+                `Entities do not belong to the integration's user: ${foreign
+                    .map((e) => e.id)
+                    .join(', ')}`
+            );
+            error.code = 'ENTITY_USER_MISMATCH';
+            throw error;
+        }
+
+        const attached = await this.moduleRepository.findEntitiesByIds(
+            integration.entitiesIds ?? []
+        );
+        const heldModules = new Set(attached.map((e) => e.moduleName));
+        const otherModules = entities.filter(
+            (e) => !heldModules.has(e.moduleName)
+        );
+        if (otherModules.length > 0) {
+            const error = new Error(
+                `Entities belong to a module the integration does not hold: ${otherModules
+                    .map((e) => `${e.id} (${e.moduleName})`)
+                    .join(', ')}`
+            );
+            error.code = 'ENTITY_MODULE_MISMATCH';
+            throw error;
+        }
+
+        const updated =
+            await this.integrationRepository.addEntitiesToIntegration(
+                integrationId,
+                entityIds
+            );
+        if (!updated) throw integrationNotFound(integrationId);
+        return updated;
+    }
+}
+
+module.exports = { AddEntitiesToIntegration };

package/integrations/use-cases/create-integration.js

@@ -62,7 +62,7 @@ class CreateIntegration {
 
         // A concurrent request may have created a matching row between the
         // lookup above and this insert; re-check before any side effects run.
-        const survivor = await this._findDuplicate(
+        const survivor = await this._findSurvivor(
             userId,
             config?.type,
             entities
@@ -135,30 +135,68 @@ class CreateIntegration {
         return mapIntegrationClassToIntegrationDTO(integrationInstance);
     }
 
-    async _findDuplicate(userId, type, entityIds) {
+    async _findMatches(userId, type, entityIds) {
         const candidates =
             await this.integrationRepository.findIntegrationsByUserId(userId);
-        const target = [...(entityIds ?? [])].map(String).sort();
-
-        const matches = candidates.filter((integration) => {
-            // An IN_DELETION row is either mid-teardown or a zombie left
-            // behind by a failed deleteIntegrationById call — never a live
-            // integration. Treating it as a duplicate would hand a reinstall
-            // attempt a row nothing will ever move out of IN_DELETION,
-            // silently discarded by the queue worker forever. Let a fresh
-            // create proceed instead; the zombie is cleaned up out-of-band,
-            // matching how teardown failures are already handled here.
-            if (integration.status === 'IN_DELETION') return false;
-            if (integration.config?.type !== type) return false;
-            const current = [...(integration.entitiesIds ?? [])]
-                .map(String)
-                .sort();
+        const target = new Set((entityIds ?? []).map(String));
+
+        const live = candidates.filter(
+            (integration) =>
+                // An IN_DELETION row is either mid-teardown or a zombie left
+                // behind by a failed deleteIntegrationById call — never a live
+                // integration. Treating it as a duplicate would hand a
+                // reinstall attempt a row nothing will ever move out of
+                // IN_DELETION, silently discarded by the queue worker forever.
+                // Let a fresh create proceed instead; the zombie is cleaned up
+                // out-of-band, matching how teardown failures are already
+                // handled here.
+                integration.status !== 'IN_DELETION' &&
+                integration.config?.type === type
+        );
+        const entitySet = (integration) =>
+            new Set((integration.entitiesIds ?? []).map(String));
+
+        const exact = live.filter((integration) => {
+            const current = entitySet(integration);
             return (
-                current.length === target.length &&
-                current.every((id, index) => id === target[index])
+                current.size === target.size &&
+                [...target].every((id) => current.has(id))
             );
         });
 
+        // Entities may have been attached after create (addEntitiesToIntegration),
+        // so a reconnect that sends the original entities must still find the
+        // integration that now holds them, instead of creating a second one
+        // that would share those entities.
+        const supersets = live.filter((integration) => {
+            const current = entitySet(integration);
+            return [...target].every((id) => current.has(id));
+        });
+        return { exact, supersets: target.size ? supersets : [] };
+    }
+
+    async _findDuplicate(userId, type, entityIds) {
+        const { exact, supersets } = await this._findMatches(
+            userId,
+            type,
+            entityIds
+        );
+        if (exact.length) return this._pickOldest(exact);
+        return supersets.length ? this._pickOldest(supersets) : null;
+    }
+
+    // After an insert the new row is itself an exact match, so the survivor
+    // is the oldest of every exact or superset match (the new row included):
+    // an older integration that already holds these entities always wins.
+    async _findSurvivor(userId, type, entityIds) {
+        const { exact, supersets } = await this._findMatches(
+            userId,
+            type,
+            entityIds
+        );
+        // supersets includes the exact matches; it is empty only for an
+        // empty entity set, where exact matching alone applies.
+        const matches = supersets.length ? supersets : exact;
         return matches.length ? this._pickOldest(matches) : null;
     }
 

package/integrations/use-cases/remove-entities-from-integration.js

@@ -0,0 +1,70 @@
+const {
+    assertEntityIdsInput,
+    integrationNotFound,
+    loadIntegration,
+} = require('../utils/assert-entity-ids-input');
+
+/**
+ * Detaches entities from an integration. Entities that are not attached are
+ * ignored, and detached entities are not deleted. Every module the
+ * integration holds must keep at least one entity, so the integration can
+ * still hydrate each of its modules.
+ * @class RemoveEntitiesFromIntegration
+ */
+class RemoveEntitiesFromIntegration {
+    /**
+     * @param {Object} params
+     * @param {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface} params.integrationRepository
+     * @param {import('../../modules/repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
+     */
+    constructor({ integrationRepository, moduleRepository }) {
+        this.integrationRepository = integrationRepository;
+        this.moduleRepository = moduleRepository;
+    }
+
+    /**
+     * @param {string} integrationId
+     * @param {string[]} entityIds
+     * @returns {Promise<Object>} The updated integration record.
+     */
+    async execute(integrationId, entityIds) {
+        assertEntityIdsInput(integrationId, entityIds);
+
+        const integration = await loadIntegration(
+            this.integrationRepository,
+            integrationId
+        );
+
+        const removing = new Set(entityIds.map(String));
+        const attached = await this.moduleRepository.findEntitiesByIds(
+            integration.entitiesIds ?? []
+        );
+        const emptied = [...new Set(attached.map((e) => e.moduleName))].filter(
+            (moduleName) =>
+                !attached.some(
+                    (e) =>
+                        e.moduleName === moduleName &&
+                        !removing.has(String(e.id))
+                )
+        );
+        if (emptied.length > 0) {
+            const error = new Error(
+                `Removing these entities would leave no entity for module(s): ${emptied.join(
+                    ', '
+                )}`
+            );
+            error.code = 'LAST_ENTITY_OF_MODULE';
+            throw error;
+        }
+
+        const updated =
+            await this.integrationRepository.removeEntitiesFromIntegration(
+                integrationId,
+                entityIds
+            );
+        if (!updated) throw integrationNotFound(integrationId);
+        return updated;
+    }
+}
+
+module.exports = { RemoveEntitiesFromIntegration };

package/integrations/utils/assert-entity-ids-input.js

@@ -0,0 +1,42 @@
+/**
+ * Throws INVALID_INTEGRATION_DATA unless an integration id and a non-empty
+ * list of entity ids are given.
+ * @param {string} integrationId
+ * @param {string[]} entityIds
+ */
+function assertEntityIdsInput(integrationId, entityIds) {
+    if (!integrationId || !Array.isArray(entityIds) || entityIds.length === 0) {
+        const error = new Error(
+            'integrationId and a non-empty entityIds array are required'
+        );
+        error.code = 'INVALID_INTEGRATION_DATA';
+        throw error;
+    }
+}
+
+function integrationNotFound(integrationId) {
+    const error = new Error(`Integration ${integrationId} not found`);
+    error.code = 'INTEGRATION_NOT_FOUND';
+    return error;
+}
+
+/**
+ * Loads an integration, mapping the repositories' "not found" error to
+ * INTEGRATION_NOT_FOUND. Any other failure (connection, invalid id) is
+ * rethrown unchanged.
+ * @param {Object} integrationRepository
+ * @param {string} integrationId
+ * @returns {Promise<Object>} The integration record.
+ */
+async function loadIntegration(integrationRepository, integrationId) {
+    try {
+        return await integrationRepository.findIntegrationById(integrationId);
+    } catch (error) {
+        if (/^Integration with id .* not found$/.test(error?.message)) {
+            throw integrationNotFound(integrationId);
+        }
+        throw error;
+    }
+}
+
+module.exports = { assertEntityIdsInput, integrationNotFound, loadIntegration };

package/jest-setup.js

@@ -1,2 +1,13 @@
-const {globalSetup} = require('@friggframework/test');
-module.exports = globalSetup;
+// Core's unit suites must not need a database, so this global setup only
+// sets the test environment. It deliberately does not start an in-memory
+// MongoDB (as @friggframework/test's globalSetup does): nothing in the default
+// suite talks to a live server, and a binary that failed to start used to stop
+// every core suite from running. Suites that need a real database are
+// `*.db.test.js` files, run by `npm run test:db` (see jest.db.config.js).
+const { overrideEnvironment } = require('@friggframework/test');
+
+module.exports = async function () {
+    if (!process.env.STAGE) {
+        overrideEnvironment({ STAGE: 'dev' });
+    }
+};

package/jest-teardown.js

@@ -1,2 +1,5 @@
-const {globalTeardown} = require('@friggframework/test');
-module.exports = globalTeardown;
+const { restoreEnvironment } = require('@friggframework/test');
+
+module.exports = async function () {
+    restoreEnvironment();
+};

package/jest.config.js

@@ -20,4 +20,8 @@ module.exports = {
     globalTeardown: './jest-teardown.js',
 
     setupFilesAfterEnv: ['./logs/jest-logger-setup.js'],
+
+    // `*.db.test.js` suites talk to a real MongoDB replica set / PostgreSQL
+    // and run separately via `npm run test:db` (jest.db.config.js).
+    testPathIgnorePatterns: ['/node_modules/', '\\.db\\.test\\.js$'],
 };

package/jest.db.config.js

@@ -0,0 +1,23 @@
+/*
+ * Database integration suites (`*.db.test.js`).
+ *
+ * These talk to real databases instead of mocking Prisma, so they are kept
+ * out of the default `npm test` run and executed with `npm run test:db`.
+ * They need generated Prisma clients (`npm run prisma:generate`) and:
+ *   - a MongoDB replica set (Prisma requires one for MongoDB writes):
+ *     FRIGG_TEST_MONGODB_URL, default
+ *     mongodb://localhost:27017/frigg?replicaSet=rs0
+ *   - PostgreSQL with the prisma-postgresql migrations applied:
+ *     FRIGG_TEST_POSTGRES_URL, default
+ *     postgresql://postgres:postgres@localhost:5432/frigg?schema=public
+ * The repository parity suites skip themselves unless their own URLs are
+ * set (INTEGRATION_ENTITIES_PARITY_* / QUERY_MAPPINGS_PARITY_*).
+ */
+const base = require('./jest.config');
+
+module.exports = {
+    ...base,
+    coverageThreshold: undefined,
+    testMatch: ['**/*.db.test.js'],
+    testPathIgnorePatterns: ['/node_modules/'],
+};

package/modules/utils/map-module-dto.js

@@ -1,3 +1,5 @@
+const { toCredentialId } = require('./to-credential-id');
+
 /**
  * @param {import('../module').Module} moduleInstance
  * Convert a Module domain instance to a plain DTO suitable for JSON responses.
@@ -10,9 +12,9 @@ function mapModuleClassToModuleDTO(moduleInstance) {
         name: moduleInstance.name,
         userId: moduleInstance.userId,
         entity: moduleInstance.entity,
-        credentialId: moduleInstance.credential?._id?.toString(),
-        type: moduleInstance.getName()
+        credentialId: toCredentialId(moduleInstance.credential),
+        type: moduleInstance.getName(),
     };
 }
 
-module.exports = { mapModuleClassToModuleDTO }; 
+module.exports = { mapModuleClassToModuleDTO };

package/modules/utils/to-credential-id.js

@@ -0,0 +1,14 @@
+/**
+ * Resolve the credential id from an entity's or module's `credential`, which
+ * repositories return as the decrypted credential object (or a bare id).
+ * @param {Object|string|number|null|undefined} credential
+ * @returns {string|null}
+ */
+function toCredentialId(credential) {
+    if (credential && typeof credential === 'object') {
+        return credential.id?.toString() ?? null;
+    }
+    return credential?.toString() ?? null;
+}
+
+module.exports = { toCredentialId };