@friggframework/core 2.0.0--canary.688.87a9bf3.0 → 2.0.0--canary.689.386395c.0

package/CLAUDE.md

@@ -206,11 +206,41 @@ 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) and entities of another user
+  (`ENTITY_USER_MISMATCH`, 403). 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`. Three traps:
+  (1) `IntegrationBase` keys modules by module name, so `this.<moduleKey>`
+  holds only the last entity's module: pick the account's entity from
+  `this.entities` by `externalId`.
+  (2) `findIntegrationByEntityExternalId` counts every entity with that
+  externalId, attached or not: 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 integration only for the exact same entity
+  set, so after an attach a second `createIntegration` with the original
+  entities creates a new integration: re-authorization must update the
+  existing integration, not create one.
 - `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,24 +1,12 @@
 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 {
@@ -78,7 +66,16 @@ function createEntityCommands() {
 
                 const entity = await moduleRepo.createEntity(entityData);
 
-                return toEntityDto(entity);
+                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,
+                };
             } catch (error) {
                 return mapErrorToResponse(error);
             }
@@ -112,7 +109,16 @@ function createEntityCommands() {
                     return null;
                 }
 
-                return toEntityDto(entity);
+                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,
+                };
             } catch (error) {
                 return mapErrorToResponse(error);
             }
@@ -133,7 +139,16 @@ function createEntityCommands() {
 
                 const entities = await moduleRepo.findEntitiesByUserId(userId);
 
-                return entities.map((entity) => toEntityDto(entity));
+                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,
+                }));
             } catch (error) {
                 if (error.code) {
                     return mapErrorToResponse(error);
@@ -165,7 +180,16 @@ function createEntityCommands() {
                         moduleName
                     );
 
-                return entities.map((entity) => toEntityDto(entity));
+                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,
+                }));
             } catch (error) {
                 if (error.code) {
                     return mapErrorToResponse(error);
@@ -189,7 +213,16 @@ function createEntityCommands() {
 
                 const entity = await moduleRepo.findEntityById(entityId);
 
-                return toEntityDto(entity);
+                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,
+                };
             } catch (error) {
                 return mapErrorToResponse(error);
             }
@@ -217,7 +250,16 @@ function createEntityCommands() {
                     throw error;
                 }
 
-                return toEntityDto(entity);
+                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,
+                };
             } 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,9 @@ 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,
 };
 
 function mapErrorToResponse(error) {
@@ -163,6 +172,16 @@ function createIntegrationCommands({ integrationClass } = {}) {
         integrationRepository,
     });
 
+    const addEntitiesToIntegrationUseCase = new AddEntitiesToIntegration({
+        integrationRepository,
+        moduleRepository,
+    });
+
+    const removeEntitiesFromIntegrationUseCase =
+        new RemoveEntitiesFromIntegration({
+            integrationRepository,
+        });
+
     return {
         findIntegrationById,
         listIntegrations,
@@ -307,6 +326,45 @@ function createIntegrationCommands({ integrationClass } = {}) {
             }
         },
 
+        /**
+         * Attach entities to an existing integration. Every entity must
+         * exist and belong to the integration's user; 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.
+         * @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,73 @@
+const {
+    assertEntityIdsInput,
+    integrationNotFound,
+} = 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 and belong to the integration's user. 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 this.integrationRepository
+            .findIntegrationById(integrationId)
+            .catch(() => null);
+        if (!integration) throw integrationNotFound(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 updated =
+            await this.integrationRepository.addEntitiesToIntegration(
+                integrationId,
+                entityIds
+            );
+        if (!updated) throw integrationNotFound(integrationId);
+        return updated;
+    }
+}
+
+module.exports = { AddEntitiesToIntegration };

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

@@ -0,0 +1,38 @@
+const {
+    assertEntityIdsInput,
+    integrationNotFound,
+} = require('../utils/assert-entity-ids-input');
+
+/**
+ * Detaches entities from an integration. Entities that are not attached are
+ * ignored, and detached entities are not deleted.
+ * @class RemoveEntitiesFromIntegration
+ */
+class RemoveEntitiesFromIntegration {
+    /**
+     * @param {Object} params
+     * @param {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface} params.integrationRepository
+     */
+    constructor({ integrationRepository }) {
+        this.integrationRepository = integrationRepository;
+    }
+
+    /**
+     * @param {string} integrationId
+     * @param {string[]} entityIds
+     * @returns {Promise<Object>} The updated integration record.
+     */
+    async execute(integrationId, entityIds) {
+        assertEntityIdsInput(integrationId, entityIds);
+
+        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,23 @@
+/**
+ * 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;
+}
+
+module.exports = { assertEntityIdsInput, integrationNotFound };

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

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

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.688.87a9bf3.0",
+    "version": "2.0.0--canary.689.386395c.0",
     "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--canary.688.87a9bf3.0",
-        "@friggframework/prettier-config": "2.0.0--canary.688.87a9bf3.0",
-        "@friggframework/test": "2.0.0--canary.688.87a9bf3.0",
+        "@friggframework/eslint-config": "2.0.0--canary.689.386395c.0",
+        "@friggframework/prettier-config": "2.0.0--canary.689.386395c.0",
+        "@friggframework/test": "2.0.0--canary.689.386395c.0",
         "@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": "87a9bf3315fc2daa2b7f38b7b1ddd5bbcb323b20"
+    "gitHead": "386395c1f89690e6098b761e2b343db6c7c3dc59"
 }

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

@@ -1,14 +0,0 @@
-/**
- * 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 };