@friggframework/core 2.0.0--canary.398.a314355.0 → 2.0.0--canary.397.4957a89.0

package/integrations/integration.js

@@ -0,0 +1,233 @@
+const { Options } = require('./options');
+
+/**
+ * Integration (Domain Aggregate-Root)
+ * ----------------------------------
+ * This class represents a *configured* integration instance at runtime. It is
+ * deliberately split into **two layers**:
+ *   1.  A *data snapshot* of the persisted record (id, userId, config, etc.).
+ *   2.  A *behaviour* object: a concrete class supplied by the app developer
+ *       that extends `IntegrationBase` and implements event handlers, user
+ *       actions, custom routes, etc.
+ *
+ * The two layers are glued together via a **JavaScript `Proxy`**.  When a
+ * property is requested on an `Integration` instance we:
+ *   • Check if the property exists on the wrapper itself (data-layer).
+ *   • Fallback to the behaviour instance (logic-layer).
+ *   • If the value is a function we `.bind(this)` so that the function's
+ *     `this` always points to the *wrapper* – giving it access to both data
+ *     and behaviour transparently.
+ *
+ * This means you can treat a hydrated Integration as if it *were* the custom
+ * class:
+ *
+ * ```js
+ * const integration = await getIntegration.execute(id, userId);
+ * // `send` actually lives on IntegrationBase but is accessible here
+ * const actions = await integration.send('GET_USER_ACTIONS');
+ * ```
+ *
+ * A corollary benefit is that **circular references stay internal**: the heavy
+ * `Module → Api → delegate` graph is never exposed when we later serialise the
+ * object to JSON – we map it to a DTO first.
+ */
+
+/**
+ * Integration Domain Entity
+ * Represents a configured integration with its data and behavior
+ * Uses the strategy pattern to delegate behavior to the integration class
+ * This is the main class that is used to interact with integrations
+ */
+class Integration {
+    constructor({
+        id,
+        userId,
+        entities,
+        config,
+        status,
+        version,
+        messages,
+        integrationClass,
+        modules = {}
+    }) {
+        // Data from record
+        this.id = id;
+        this.userId = userId;
+        this.entities = entities;
+        this.config = config;
+        this.status = status;
+        this.version = version;
+        this.messages = messages;
+
+        // Integration behavior (strategy pattern)
+        this.integrationClass = integrationClass;
+
+        // Preserve the provided Module instances (array). We'll attach them
+        // as keyed modules after the behaviour instance is created so that
+        // `this.hubspot`, `this.salesforce`, etc. reference the fully-
+        // initialised objects with credentials.
+        this._moduleInstances = Array.isArray(modules) ? modules : [];
+
+        // Normalised map of modules keyed by module name (filled later)
+        this.modules = {};
+
+        // Initialize basic behavior (sync parts only)
+        this._initializeBasicBehavior();
+
+        // --- Behaviour delegation via Proxy --------------------------------
+        // The Proxy merges the *data layer* (this wrapper) with the *behaviour
+        // layer* (custom IntegrationBase subclass).  Consumers don't have to
+        // know (or care) where a method/property is defined.
+        return new Proxy(this, {
+            get(target, prop) {
+                // First, check if property exists on Integration entity
+                if (prop in target) {
+                    return target[prop];
+                }
+
+                // Then, check if it exists on the behavior instance
+                if (target.behavior && prop in target.behavior) {
+                    const value = target.behavior[prop];
+
+                    // If it's a function, bind the context to the Integration entity
+                    if (typeof value === 'function') {
+                        return value.bind(target);
+                    }
+
+                    return value;
+                }
+
+                // Return undefined for non-existent properties
+                return undefined;
+            }
+        });
+    }
+
+    _initializeBasicBehavior() {
+        // Initialize basic behavior (sync parts only)
+        if (this.integrationClass) {
+            // Create instance for behavior delegation
+            this.behavior = new this.integrationClass({
+                userId: this.userId,
+                integrationId: this.id
+            });
+
+            // Copy events
+            this.events = this.behavior.events || {};
+            this.defaultEvents = this.behavior.defaultEvents || {};
+
+            // -----------------------------------------------------------------
+            // Inject the real Module instances (with credentials) so that any
+            // behaviour code accessing `this.<moduleName>.api` hits the
+            // correctly authenticated requester created by ModuleFactory.
+            // -----------------------------------------------------------------
+            for (const mod of this._moduleInstances) {
+                const key = typeof mod.getName === 'function' ? mod.getName() : mod.name;
+                if (!key) continue;
+                this.setModule(key, mod);
+            }
+
+            // `undefined` errors for methods like `loadDynamicUserActions` that
+            // may be invoked inside default event-handlers.
+            let proto = Object.getPrototypeOf(this.behavior);
+            while (proto && proto !== Object.prototype) {
+                for (const key of Object.getOwnPropertyNames(proto)) {
+                    if (key === 'constructor') continue;
+                    if (typeof proto[key] === 'function' && this[key] === undefined) {
+                        this[key] = proto[key].bind(this.behavior);
+                    }
+                }
+                proto = Object.getPrototypeOf(proto);
+            }
+        }
+    }
+
+    async initialize() {
+        // Complete async initialization
+        if (this.behavior) {
+            // Load dynamic user actions
+            try {
+                const additionalUserActions = await this.loadDynamicUserActions();
+                this.events = { ...this.events, ...additionalUserActions };
+            } catch (e) {
+                this.addError(e);
+            }
+
+            // Register event handlers
+            await this.registerEventHandlers();
+        }
+    }
+
+    // Core methods that should always be on Integration entity
+    // These override any behavior methods with the same name
+
+    getConfig() {
+        return this.config;
+    }
+
+    // Module access helpers
+    getModule(key) {
+        return this.modules[key];
+    }
+
+    setModule(key, module) {
+        this.modules[key] = module;
+        // Also set on behavior for backward compatibility
+        if (this.behavior) {
+            this.behavior[key] = module;
+        }
+    }
+
+    // State management
+    addError(error) {
+        if (!this.messages.errors) {
+            this.messages.errors = [];
+        }
+        this.messages.errors.push(error);
+        this.status = 'ERROR';
+    }
+
+    addWarning(warning) {
+        if (!this.messages.warnings) {
+            this.messages.warnings = [];
+        }
+        this.messages.warnings.push(warning);
+    }
+
+    // Domain methods
+    isActive() {
+        return this.status === 'ENABLED' || this.status === 'ACTIVE';
+    }
+
+    needsConfiguration() {
+        return this.status === 'NEEDS_CONFIG';
+    }
+
+    hasErrors() {
+        return this.status === 'ERROR';
+    }
+
+    belongsToUser(userId) {
+        return this.userId.toString() === userId.toString();
+    }
+
+    // Get the underlying behavior instance (useful for debugging or special cases)
+    getBehavior() {
+        return this.behavior;
+    }
+
+    // Check if a method exists (either on entity or behavior)
+    hasMethod(methodName) {
+        return methodName in this || (this.behavior && methodName in this.behavior);
+    }
+
+    getOptionDetails() {
+        const options = new Options({
+            module: Object.values(this.integrationClass.Definition.modules)[0], // This is a placeholder until we revamp the frontend
+            ...this.integrationClass.Definition,
+        });
+        return options.get();
+    }
+}
+
+module.exports = { Integration };

package/integrations/options.js

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

package/integrations/tests/doubles/dummy-integration-class.js

@@ -0,0 +1,90 @@
+const { IntegrationBase } = require('../../integration-base');
+
+class DummyModule {
+    static definition = {
+        getName: () => 'dummy'
+    };
+}
+
+class DummyIntegration extends IntegrationBase {
+    static Definition = {
+        name: 'dummy',
+        version: '1.0.0',
+        modules: {
+            dummy: DummyModule
+        },
+        display: {
+            label: 'Dummy Integration',
+            description: 'A dummy integration for testing',
+            detailsUrl: 'https://example.com',
+            icon: 'dummy-icon'
+        }
+    };
+
+    static getOptionDetails() {
+        return {
+            name: this.Definition.name,
+            version: this.Definition.version,
+            display: this.Definition.display
+        };
+    }
+
+    constructor(params) {
+        super(params);
+        this.sendSpy = jest.fn();
+        this.eventCallHistory = [];
+        this.events = {};
+
+        this.integrationRepository = {
+            updateIntegrationById: jest.fn().mockResolvedValue({}),
+            findIntegrationById: jest.fn().mockResolvedValue({}),
+        };
+
+        this.updateIntegrationStatus = {
+            execute: jest.fn().mockResolvedValue({})
+        };
+
+        this.updateIntegrationMessages = {
+            execute: jest.fn().mockResolvedValue({})
+        };
+
+        this.registerEventHandlers();
+    }
+
+    async loadDynamicUserActions() {
+        return {};
+    }
+
+    async registerEventHandlers() {
+        super.registerEventHandlers();
+        return;
+    }
+
+    async send(event, data) {
+        this.sendSpy(event, data);
+        this.eventCallHistory.push({ event, data, timestamp: Date.now() });
+        return super.send(event, data);
+    }
+
+    async initialize() {
+        return;
+    }
+
+    async onCreate({ integrationId }) {
+        return;
+    }
+
+    async onUpdate(params) {
+        return;
+    }
+
+    async onDelete(params) {
+        return;
+    }
+
+    getConfig() {
+        return this.config || {};
+    }
+}
+
+module.exports = { DummyIntegration }; 

package/integrations/tests/doubles/test-integration-repository.js

@@ -0,0 +1,89 @@
+const { v4: uuid } = require('uuid');
+
+class TestIntegrationRepository {
+    constructor() {
+        this.store = new Map();
+        this.operationHistory = [];
+    }
+
+    async createIntegration(entities, userId, config) {
+        const id = uuid();
+        const record = {
+            id,
+            _id: id,
+            entitiesIds: entities,
+            userId: userId,
+            config,
+            version: '0.0.0',
+            status: 'NEW',
+            messages: {},
+        };
+        this.store.set(id, record);
+        this.operationHistory.push({ operation: 'create', id, userId, config });
+        return record;
+    }
+
+    async findIntegrationById(id) {
+        const rec = this.store.get(id);
+        this.operationHistory.push({ operation: 'findById', id, found: !!rec });
+        if (!rec) return null;
+        return rec;
+    }
+
+    async findIntegrationsByUserId(userId) {
+        const results = Array.from(this.store.values()).filter(r => r.userId === userId);
+        this.operationHistory.push({ operation: 'findByUserId', userId, count: results.length });
+        return results;
+    }
+
+    async updateIntegrationMessages(id, type, title, body, timestamp) {
+        const rec = this.store.get(id);
+        if (!rec) {
+            this.operationHistory.push({ operation: 'updateMessages', id, success: false });
+            return false;
+        }
+        if (!rec.messages[type]) rec.messages[type] = [];
+        rec.messages[type].push({ title, message: body, timestamp });
+        this.operationHistory.push({ operation: 'updateMessages', id, type, success: true });
+        return true;
+    }
+
+    async updateIntegrationConfig(id, config) {
+        const rec = this.store.get(id);
+        if (!rec) {
+            this.operationHistory.push({ operation: 'updateConfig', id, success: false });
+            return false;
+        }
+        rec.config = config;
+        this.operationHistory.push({ operation: 'updateConfig', id, success: true });
+        return true;
+    }
+
+    async deleteIntegrationById(id) {
+        const existed = this.store.has(id);
+        const result = this.store.delete(id);
+        this.operationHistory.push({ operation: 'delete', id, existed, success: result });
+        return result;
+    }
+
+    async updateIntegrationStatus(id, status) {
+        const rec = this.store.get(id);
+        if (rec) {
+            rec.status = status;
+            this.operationHistory.push({ operation: 'updateStatus', id, status, success: true });
+        } else {
+            this.operationHistory.push({ operation: 'updateStatus', id, status, success: false });
+        }
+        return !!rec;
+    }
+
+    getOperationHistory() {
+        return [...this.operationHistory];
+    }
+
+    clearHistory() {
+        this.operationHistory = [];
+    }
+}
+
+module.exports = { TestIntegrationRepository }; 

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

@@ -0,0 +1,124 @@
+const { CreateIntegration } = require('../../use-cases/create-integration');
+const { TestIntegrationRepository } = require('../doubles/test-integration-repository');
+const { TestModuleFactory } = require('../../../modules/tests/doubles/test-module-factory');
+const { DummyIntegration } = require('../doubles/dummy-integration-class');
+
+describe('CreateIntegration Use-Case', () => {
+    let integrationRepository;
+    let moduleFactory;
+    let useCase;
+
+    beforeEach(() => {
+        integrationRepository = new TestIntegrationRepository();
+        moduleFactory = new TestModuleFactory();
+        useCase = new CreateIntegration({
+            integrationRepository,
+            integrationClasses: [DummyIntegration],
+            moduleFactory,
+        });
+    });
+
+    describe('happy path', () => {
+        it('creates an integration and returns DTO', async () => {
+            const entities = ['entity-1'];
+            const userId = 'user-1';
+            const config = { type: 'dummy', foo: 'bar' };
+
+            const dto = await useCase.execute(entities, userId, config);
+
+            expect(dto.id).toBeDefined();
+            expect(dto.config).toEqual(config);
+            expect(dto.userId).toBe(userId);
+            expect(dto.entities).toEqual(entities);
+            expect(dto.status).toBe('NEW');
+        });
+
+        it('triggers ON_CREATE event with correct payload', async () => {
+            const entities = ['entity-1'];
+            const userId = 'user-1';
+            const config = { type: 'dummy', foo: 'bar' };
+
+            const dto = await useCase.execute(entities, userId, config);
+
+            const record = await integrationRepository.findIntegrationById(dto.id);
+            expect(record).toBeTruthy();
+
+            const history = integrationRepository.getOperationHistory();
+            const createOperation = history.find(op => op.operation === 'create');
+            expect(createOperation).toEqual({
+                operation: 'create',
+                id: dto.id,
+                userId,
+                config
+            });
+        });
+
+        it('loads modules for each entity', async () => {
+            const entities = ['entity-1', 'entity-2'];
+            const userId = 'user-1';
+            const config = { type: 'dummy' };
+
+            const dto = await useCase.execute(entities, userId, config);
+
+            expect(dto.entities).toEqual(entities);
+        });
+    });
+
+    describe('error cases', () => {
+        it('throws error when integration class is not found', async () => {
+            const entities = ['entity-1'];
+            const userId = 'user-1';
+            const config = { type: 'unknown-type' };
+
+            await expect(useCase.execute(entities, userId, config))
+                .rejects
+                .toThrow('No integration class found for type: unknown-type');
+        });
+
+        it('throws error when no integration classes provided', async () => {
+            const useCaseWithoutClasses = new CreateIntegration({
+                integrationRepository,
+                integrationClasses: [],
+                moduleFactory,
+            });
+
+            const entities = ['entity-1'];
+            const userId = 'user-1';
+            const config = { type: 'dummy' };
+
+            await expect(useCaseWithoutClasses.execute(entities, userId, config))
+                .rejects
+                .toThrow('No integration class found for type: dummy');
+        });
+    });
+
+    describe('edge cases', () => {
+        it('handles empty entities array', async () => {
+            const entities = [];
+            const userId = 'user-1';
+            const config = { type: 'dummy' };
+
+            const dto = await useCase.execute(entities, userId, config);
+
+            expect(dto.entities).toEqual([]);
+            expect(dto.id).toBeDefined();
+        });
+
+        it('handles complex config objects', async () => {
+            const entities = ['entity-1'];
+            const userId = 'user-1';
+            const config = {
+                type: 'dummy',
+                nested: {
+                    value: 123,
+                    array: [1, 2, 3],
+                    bool: true
+                }
+            };
+
+            const dto = await useCase.execute(entities, userId, config);
+
+            expect(dto.config).toEqual(config);
+        });
+    });
+}); 

package/integrations/tests/use-cases/delete-integration-for-user.test.js

@@ -0,0 +1,143 @@
+const { DeleteIntegrationForUser } = require('../../use-cases/delete-integration-for-user');
+const { TestIntegrationRepository } = require('../doubles/test-integration-repository');
+const { DummyIntegration } = require('../doubles/dummy-integration-class');
+
+describe('DeleteIntegrationForUser Use-Case', () => {
+    let integrationRepository;
+    let useCase;
+
+    beforeEach(() => {
+        integrationRepository = new TestIntegrationRepository();
+        useCase = new DeleteIntegrationForUser({
+            integrationRepository,
+            integrationClasses: [DummyIntegration],
+        });
+    });
+
+    describe('happy path', () => {
+        it('deletes integration successfully', async () => {
+            const record = await integrationRepository.createIntegration(['e1'], 'user-1', { type: 'dummy' });
+
+            await useCase.execute(record.id, 'user-1');
+
+            const found = await integrationRepository.findIntegrationById(record.id);
+            expect(found).toBeNull();
+        });
+
+        it('tracks delete operation', async () => {
+            const record = await integrationRepository.createIntegration(['e1'], 'user-1', { type: 'dummy' });
+            integrationRepository.clearHistory();
+
+            await useCase.execute(record.id, 'user-1');
+
+            const history = integrationRepository.getOperationHistory();
+            const deleteOperation = history.find(op => op.operation === 'delete');
+            expect(deleteOperation).toEqual({
+                operation: 'delete',
+                id: record.id,
+                existed: true,
+                success: true
+            });
+        });
+
+        it('deletes integration with multiple entities', async () => {
+            const record = await integrationRepository.createIntegration(['e1', 'e2', 'e3'], 'user-1', { type: 'dummy' });
+
+            await useCase.execute(record.id, 'user-1');
+
+            const found = await integrationRepository.findIntegrationById(record.id);
+            expect(found).toBeNull();
+        });
+    });
+
+    describe('error cases', () => {
+        it('throws error when integration not found', async () => {
+            const nonExistentId = 'non-existent-id';
+
+            await expect(useCase.execute(nonExistentId, 'user-1'))
+                .rejects
+                .toThrow(`Integration with id of ${nonExistentId} does not exist`);
+        });
+
+        it('throws error when user does not own integration', async () => {
+            const record = await integrationRepository.createIntegration(['e1'], 'user-1', { type: 'dummy' });
+
+            await expect(useCase.execute(record.id, 'different-user'))
+                .rejects
+                .toThrow(`Integration ${record.id} does not belong to User different-user`);
+        });
+
+        it('throws error when integration class not found', async () => {
+            const useCaseWithoutClasses = new DeleteIntegrationForUser({
+                integrationRepository,
+                integrationClasses: [],
+            });
+
+            const record = await integrationRepository.createIntegration(['e1'], 'user-1', { type: 'dummy' });
+
+            await expect(useCaseWithoutClasses.execute(record.id, 'user-1'))
+                .rejects
+                .toThrow();
+        });
+
+        it('tracks failed delete operation for non-existent integration', async () => {
+            const nonExistentId = 'non-existent-id';
+            integrationRepository.clearHistory();
+
+            try {
+                await useCase.execute(nonExistentId, 'user-1');
+            } catch (error) {
+                const history = integrationRepository.getOperationHistory();
+                const findOperation = history.find(op => op.operation === 'findById');
+                expect(findOperation).toEqual({
+                    operation: 'findById',
+                    id: nonExistentId,
+                    found: false
+                });
+            }
+        });
+    });
+
+    describe('edge cases', () => {
+        it('handles deletion of already deleted integration', async () => {
+            const record = await integrationRepository.createIntegration(['e1'], 'user-1', { type: 'dummy' });
+
+            await useCase.execute(record.id, 'user-1');
+
+            await expect(useCase.execute(record.id, 'user-1'))
+                .rejects
+                .toThrow(`Integration with id of ${record.id} does not exist`);
+        });
+
+        it('handles integration with complex config during deletion', async () => {
+            const complexConfig = {
+                type: 'dummy',
+                settings: { nested: { deep: 'value' } },
+                credentials: { encrypted: true }
+            };
+
+            const record = await integrationRepository.createIntegration(['e1'], 'user-1', complexConfig);
+
+            await useCase.execute(record.id, 'user-1');
+
+            const found = await integrationRepository.findIntegrationById(record.id);
+            expect(found).toBeNull();
+        });
+
+        it('handles null userId gracefully', async () => {
+            const record = await integrationRepository.createIntegration(['e1'], 'user-1', { type: 'dummy' });
+
+            await expect(useCase.execute(record.id, null))
+                .rejects
+                .toThrow(`Integration ${record.id} does not belong to User null`);
+        });
+
+        it('handles undefined userId gracefully', async () => {
+            const record = await integrationRepository.createIntegration(['e1'], 'user-1', { type: 'dummy' });
+
+            await expect(useCase.execute(record.id, undefined))
+                .rejects
+                .toThrow(`Integration ${record.id} does not belong to User undefined`);
+        });
+    });
+});