@friggframework/core 2.0.0-next.12 → 2.0.0-next.120

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

@@ -0,0 +1,219 @@
+/**
+ * Integration Repository Interface
+ * Abstract base class defining the contract for integration persistence adapters
+ *
+ * This follows the Port in Hexagonal Architecture:
+ * - Domain layer depends on this abstraction
+ * - Concrete adapters (MongoDB, PostgreSQL) implement this interface
+ * - Use cases receive repositories via dependency injection
+ *
+ * @abstract
+ */
+class IntegrationRepositoryInterface {
+    /**
+     * Find all integrations for a user
+     *
+     * @param {string|number} userId - User ID
+     * @returns {Promise<Array>} Array of integration objects
+     * @abstract
+     */
+    async findIntegrationsByUserId(userId) {
+        throw new Error('Method findIntegrationsByUserId must be implemented by subclass');
+    }
+
+    /**
+     * Find integrations, optionally filtered by config type and/or status.
+     * With no filter, returns every integration.
+     *
+     * @param {Object} [filter={}]
+     * @param {string} [filter.type] - Integration type (config.type)
+     * @param {string} [filter.status] - Integration status
+     * @returns {Promise<Array>} Array of integration objects (possibly empty)
+     * @abstract
+     */
+    async findIntegrations(filter = {}) {
+        throw new Error('Method findIntegrations must be implemented by subclass');
+    }
+
+    /**
+     * Find every integration in a report-shaped projection, optionally
+     * filtered by status and/or owning user. Adapters must drain the full
+     * result set (no first-batch truncation) since this powers a
+     * deployment-wide scan.
+     *
+     * @param {Object} [filter={}]
+     * @param {string} [filter.status] - Integration status
+     * @param {string|number} [filter.userId] - Owning user ID
+     * @returns {Promise<Array<{id, type, status, userId, version, errorCount, moduleCount, createdAt, updatedAt}>>}
+     * @abstract
+     */
+    async findAllForReport(filter = {}) {
+        throw new Error('Method findAllForReport must be implemented by subclass');
+    }
+
+    /**
+     * Delete integration by ID
+     *
+     * @param {string|number} integrationId - Integration ID
+     * @returns {Promise<Object>} Deletion result
+     * @abstract
+     */
+    async deleteIntegrationById(integrationId) {
+        throw new Error('Method deleteIntegrationById must be implemented by subclass');
+    }
+
+    /**
+     * Find integration by name
+     *
+     * @param {string} name - Integration type name
+     * @returns {Promise<Object>} Integration object
+     * @abstract
+     */
+    async findIntegrationByName(name) {
+        throw new Error('Method findIntegrationByName must be implemented by subclass');
+    }
+
+    /**
+     * Find integration by ID
+     *
+     * @param {string|number} id - Integration ID
+     * @returns {Promise<Object>} Integration object
+     * @abstract
+     */
+    async findIntegrationById(id) {
+        throw new Error('Method findIntegrationById must be implemented by subclass');
+    }
+
+    /**
+     * Update integration status
+     *
+     * @param {string|number} integrationId - Integration ID
+     * @param {string} status - New status
+     * @returns {Promise<boolean>} Success indicator
+     * @abstract
+     */
+    async updateIntegrationStatus(integrationId, status) {
+        throw new Error('Method updateIntegrationStatus must be implemented by subclass');
+    }
+
+    /**
+     * Update integration messages
+     *
+     * @param {string|number} integrationId - Integration ID
+     * @param {string} messageType - Type of message (errors, warnings, info, logs)
+     * @param {string} messageTitle - Message title
+     * @param {string} messageBody - Message body
+     * @param {Date} messageTimestamp - Message timestamp
+     * @returns {Promise<boolean>} Success indicator
+     * @abstract
+     */
+    async updateIntegrationMessages(
+        integrationId,
+        messageType,
+        messageTitle,
+        messageBody,
+        messageTimestamp
+    ) {
+        throw new Error('Method updateIntegrationMessages must be implemented by subclass');
+    }
+
+    /**
+     * Create a new integration
+     *
+     * @param {Array<string|number>} entities - Array of entity IDs
+     * @param {string|number} userId - User ID
+     * @param {Object} config - Integration configuration
+     * @returns {Promise<Object>} Created integration object
+     * @abstract
+     */
+    async createIntegration(entities, userId, config) {
+        throw new Error('Method createIntegration must be implemented by subclass');
+    }
+
+    /**
+     * Find integration by user ID (returns single integration)
+     *
+     * @param {string|number} userId - User ID
+     * @returns {Promise<Object|null>} Integration object or null
+     * @abstract
+     */
+    async findIntegrationByUserId(userId) {
+        throw new Error('Method findIntegrationByUserId must be implemented by subclass');
+    }
+
+    /**
+     * Update integration configuration
+     *
+     * @param {string|number} integrationId - Integration ID
+     * @param {Object} config - Updated configuration object
+     * @returns {Promise<Object>} Updated integration object
+     * @abstract
+     */
+    async updateIntegrationConfig(integrationId, config) {
+        throw new Error('Method updateIntegrationConfig must be implemented by subclass');
+    }
+
+    /**
+     * Atomically merge a partial update into an integration's config. Keys
+     * not present in the patch are left untouched; concurrent patches with
+     * disjoint keys must both persist. Patch values may not be null or
+     * undefined — key deletion is only supported via updateIntegrationConfig.
+     *
+     * @param {string|number} integrationId - Integration ID
+     * @param {Object} patch - Keys to merge into the existing config
+     * @returns {Promise<Object>} Updated integration object
+     * @abstract
+     */
+    async patchIntegrationConfig(integrationId, patch) {
+        throw new Error('Method patchIntegrationConfig must be implemented by subclass');
+    }
+
+    /**
+     * Find all integrations whose entity set includes the given entity ID.
+     *
+     * Used by the authorization callback flow to walk up from a re-authorized
+     * entity to its parent integrations so that any in a broken state (ERROR,
+     * DISABLED) can be restored to ENABLED.
+     *
+     * @param {string|number} entityId - Entity ID
+     * @returns {Promise<Array>} Array of integration objects (possibly empty)
+     * @abstract
+     */
+    async findIntegrationsByEntityId(entityId) {
+        throw new Error(
+            '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 };