@friggframework/core 2.0.0-next.117 → 2.0.0-next.119

package/CLAUDE.md

@@ -206,11 +206,51 @@ packages/core/
 - `delete-integration-for-user.js` - Remove integration
 - `get-integration-instance.js` - Load integration with modules
 - `load-integration-context.js` - Full integration context loading
+- `add-entities-to-integration.js` / `remove-entities-from-integration.js` - Attach or detach entities on an existing integration
 
 **Repositories**:
 - `integration-repository-factory.js` - Creates database-specific repositories
 - `integration-repository-mongo.js` - MongoDB implementation
 - `integration-repository-postgres.js` - PostgreSQL implementation
+- `addEntitiesToIntegration(integrationId, entityIds)` /
+  `removeEntitiesFromIntegration(integrationId, entityIds)` change the entity
+  set of an existing integration (all three adapters; `null` for an unknown
+  integration). Reach them through the `addEntitiesToIntegration` /
+  `removeEntitiesFromIntegration` commands. The add use case
+  (`add-entities-to-integration.js`) rejects unknown entities
+  (`ENTITIES_NOT_FOUND`, 404), entities of another user
+  (`ENTITY_USER_MISMATCH`, 403) and entities of a module the integration does
+  not already hold (`ENTITY_MODULE_MISMATCH`, 400). The remove use case
+  (`remove-entities-from-integration.js`) refuses to leave a module with no
+  entity (`LAST_ENTITY_OF_MODULE`, 409). Re-adding an attached entity or
+  removing a detached one changes nothing; a detached entity is not deleted.
+  `integration-repository-entities-parity.test.js` runs every adapter against
+  real databases when `INTEGRATION_ENTITIES_PARITY_MONGO_URL` /
+  `INTEGRATION_ENTITIES_PARITY_POSTGRES_URL` are set. The DocumentDB adapter
+  writes only `Integration.entityIds` (as its `createIntegration` does), not
+  `Entity.integrationIds`.
+  **One credential, many accounts**: when one credential covers several
+  provider accounts, give each account its own entity (externalId = account
+  id) and attach them all to one integration; webhooks then route with
+  `findIntegrationByEntityExternalId`. Traps:
+  (1) `IntegrationBase` keys modules by module name, so `this.<moduleKey>`
+  holds only one entity's module, and on the queue/webhook path
+  (`get-integration-instance.js`) `this.entities` holds entity **ids**, not
+  records. For per-account work (a webhook for one account, teardown of every
+  account in `onDelete`), load
+  `this.commands.loadIntegrationContextById(this.id)` and use
+  `context.modules`: one module per entity, each with its record on
+  `module.entity` (pick by `module.entity.externalId`).
+  (2) `findIntegrationByEntityExternalId` counts every entity with that
+  externalId, attached or not, across users: reuse an existing entity
+  (`findEntity`) when an account comes back, or delete it when it is revoked,
+  never create a second one.
+  (3) `createIntegration` reuses an existing integration of the same user
+  and type whose entities include all requested ones (an exact match wins),
+  so a reconnect that sends the original entities finds the integration that
+  now holds more.
+  (4) Every module's delegate is the integration: an auth failure on any
+  account marks the shared credential invalid and the integration ERROR.
 - `integration-mapping-repository-*.js` - Mapping data persistence.
   `queryMappings(integrationId, { where, orderBy, skip, take, omit })`
   returns `{ mappings, total }`: one filtered, ordered page of an

package/application/commands/entity-commands.js

@@ -1,12 +1,24 @@
 const {
     createModuleRepository,
 } = require('../../modules/repositories/module-repository-factory');
+const { toCredentialId } = require('../../modules/utils/to-credential-id');
 
 const ERROR_CODE_MAP = {
     ENTITY_NOT_FOUND: 404,
     INVALID_ENTITY_DATA: 400,
 };
 
+function toEntityDto(entity) {
+    return {
+        id: entity.id,
+        userId: entity.userId,
+        externalId: entity.externalId,
+        name: entity.name,
+        moduleName: entity.moduleName,
+        credentialId: toCredentialId(entity.credential),
+    };
+}
+
 function mapErrorToResponse(error) {
     const status = ERROR_CODE_MAP[error?.code] || 500;
     return {
@@ -66,16 +78,7 @@ function createEntityCommands() {
 
                 const entity = await moduleRepo.createEntity(entityData);
 
-                return {
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                };
+                return toEntityDto(entity);
             } catch (error) {
                 return mapErrorToResponse(error);
             }
@@ -109,16 +112,7 @@ function createEntityCommands() {
                     return null;
                 }
 
-                return {
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                };
+                return toEntityDto(entity);
             } catch (error) {
                 return mapErrorToResponse(error);
             }
@@ -139,16 +133,7 @@ function createEntityCommands() {
 
                 const entities = await moduleRepo.findEntitiesByUserId(userId);
 
-                return entities.map((entity) => ({
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                }));
+                return entities.map((entity) => toEntityDto(entity));
             } catch (error) {
                 if (error.code) {
                     return mapErrorToResponse(error);
@@ -180,16 +165,7 @@ function createEntityCommands() {
                         moduleName
                     );
 
-                return entities.map((entity) => ({
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                }));
+                return entities.map((entity) => toEntityDto(entity));
             } catch (error) {
                 if (error.code) {
                     return mapErrorToResponse(error);
@@ -213,16 +189,7 @@ function createEntityCommands() {
 
                 const entity = await moduleRepo.findEntityById(entityId);
 
-                return {
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                };
+                return toEntityDto(entity);
             } catch (error) {
                 return mapErrorToResponse(error);
             }
@@ -250,16 +217,7 @@ function createEntityCommands() {
                     throw error;
                 }
 
-                return {
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                };
+                return toEntityDto(entity);
             } catch (error) {
                 return mapErrorToResponse(error);
             }

package/application/commands/integration-commands.js

@@ -29,6 +29,12 @@ const {
 const {
     PatchIntegrationConfig,
 } = require('../../integrations/use-cases/patch-integration-config');
+const {
+    AddEntitiesToIntegration,
+} = require('../../integrations/use-cases/add-entities-to-integration');
+const {
+    RemoveEntitiesFromIntegration,
+} = require('../../integrations/use-cases/remove-entities-from-integration');
 const {
     getModulesDefinitionFromIntegrationClasses,
 } = require('../../integrations/utils/map-integration-dto');
@@ -40,6 +46,11 @@ const ERROR_CODE_MAP = {
     EXTERNAL_ID_REQUIRED: 400,
     TYPE_REQUIRED: 400,
     INTEGRATION_RECORD_NOT_FOUND: 404,
+    INVALID_INTEGRATION_DATA: 400,
+    ENTITIES_NOT_FOUND: 404,
+    ENTITY_USER_MISMATCH: 403,
+    ENTITY_MODULE_MISMATCH: 400,
+    LAST_ENTITY_OF_MODULE: 409,
 };
 
 function mapErrorToResponse(error) {
@@ -163,6 +174,17 @@ function createIntegrationCommands({ integrationClass } = {}) {
         integrationRepository,
     });
 
+    const addEntitiesToIntegrationUseCase = new AddEntitiesToIntegration({
+        integrationRepository,
+        moduleRepository,
+    });
+
+    const removeEntitiesFromIntegrationUseCase =
+        new RemoveEntitiesFromIntegration({
+            integrationRepository,
+            moduleRepository,
+        });
+
     return {
         findIntegrationById,
         listIntegrations,
@@ -307,6 +329,47 @@ function createIntegrationCommands({ integrationClass } = {}) {
             }
         },
 
+        /**
+         * Attach entities to an existing integration. Every entity must
+         * exist, belong to the integration's user, and be of a module the
+         * integration already holds; entities that are already attached are
+         * left as they are.
+         * @param {Object} params
+         * @param {string} params.integrationId - Integration ID
+         * @param {Array<string>} params.entityIds - Entity IDs to attach
+         * @returns {Promise<Object>} Updated integration
+         */
+        async addEntitiesToIntegration({ integrationId, entityIds }) {
+            try {
+                return await addEntitiesToIntegrationUseCase.execute(
+                    integrationId,
+                    entityIds
+                );
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Detach entities from an integration. Entities that are not
+         * attached are ignored; detached entities are not deleted. Each
+         * module must keep at least one entity.
+         * @param {Object} params
+         * @param {string} params.integrationId - Integration ID
+         * @param {Array<string>} params.entityIds - Entity IDs to detach
+         * @returns {Promise<Object>} Updated integration
+         */
+        async removeEntitiesFromIntegration({ integrationId, entityIds }) {
+            try {
+                return await removeEntitiesFromIntegrationUseCase.execute(
+                    integrationId,
+                    entityIds
+                );
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
         /**
          * Delete an integration by ID
          * @param {string} integrationId - Integration ID to delete

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/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 };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0-next.117",
+    "version": "2.0.0-next.119",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -47,9 +47,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0-next.117",
-        "@friggframework/prettier-config": "2.0.0-next.117",
-        "@friggframework/test": "2.0.0-next.117",
+        "@friggframework/eslint-config": "2.0.0-next.119",
+        "@friggframework/prettier-config": "2.0.0-next.119",
+        "@friggframework/test": "2.0.0-next.119",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -89,5 +89,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "27771927dd746cc517d0c09189ce63b6e859e8bc"
+    "gitHead": "470470c1956365ae1e8fffd24ab013d7906ffc10"
 }