@friggframework/core 2.0.0-next.10 → 2.0.0-next.101

package/integrations/repositories/process-update-ops-shared.js

@@ -0,0 +1,112 @@
+/**
+ * Shared helpers for ProcessRepository.applyProcessUpdate() validation.
+ *
+ * These utilities are backend-agnostic: they enforce invariants on the
+ * `ProcessUpdateOps` shape BEFORE each adapter emits any SQL or database
+ * command. Keeping validation here means any bug we fix (e.g. tighter
+ * path regex, size cap) fixes all three adapters in one place.
+ *
+ * Imported by the Postgres, MongoDB, and DocumentDB adapters.
+ */
+
+/**
+ * Allowed dot-path shape. Root must be `context` or `results`, and each
+ * segment after the first must be a JS-identifier-style token. Numeric
+ * segments (array indices) and bracket syntax are intentionally
+ * disallowed — array element mutation is exclusively handled via
+ * `pushSlice`, which targets a whole array at a path.
+ */
+const PATH_REGEX = /^(context|results)(\.[a-zA-Z_][a-zA-Z0-9_]*)+$/;
+
+/**
+ * Normalizes and validates a `ProcessUpdateOps` object. Returns a frozen
+ * copy with defaults applied and every key pre-validated. Throws synchronously
+ * on any shape error so adapters can fail fast before touching the DB.
+ *
+ * @param {Object} ops
+ * @returns {{
+ *   increment: Record<string, number>,
+ *   set: Record<string, unknown>,
+ *   pushSlice: Record<string, { values: unknown[]; keepLast: number }>,
+ *   newState: string|null,
+ * }}
+ */
+function validateOps(ops) {
+    if (!ops || typeof ops !== 'object' || Array.isArray(ops)) {
+        throw new Error('applyProcessUpdate: ops must be an object');
+    }
+
+    const increment = ops.increment || {};
+    const set = ops.set || {};
+    const pushSlice = ops.pushSlice || {};
+    const newState = ops.newState ?? null;
+
+    for (const [path, delta] of Object.entries(increment)) {
+        assertPath(path, 'increment');
+        if (typeof delta !== 'number' || !Number.isFinite(delta)) {
+            throw new Error(
+                `applyProcessUpdate: increment['${path}'] must be a finite number, got ${typeof delta}`
+            );
+        }
+    }
+
+    for (const path of Object.keys(set)) {
+        assertPath(path, 'set');
+    }
+
+    for (const [path, spec] of Object.entries(pushSlice)) {
+        assertPath(path, 'pushSlice');
+        if (
+            !spec ||
+            typeof spec !== 'object' ||
+            !Array.isArray(spec.values) ||
+            typeof spec.keepLast !== 'number' ||
+            !Number.isInteger(spec.keepLast) ||
+            spec.keepLast <= 0
+        ) {
+            throw new Error(
+                `applyProcessUpdate: pushSlice['${path}'] must be { values: [], keepLast: positive integer }`
+            );
+        }
+    }
+
+    if (newState !== null && typeof newState !== 'string') {
+        throw new Error('applyProcessUpdate: newState must be a string');
+    }
+
+    const hasAnyOp =
+        Object.keys(increment).length > 0 ||
+        Object.keys(set).length > 0 ||
+        Object.keys(pushSlice).length > 0 ||
+        newState !== null;
+    if (!hasAnyOp) {
+        throw new Error(
+            'applyProcessUpdate: at least one of increment/set/pushSlice/newState must be provided'
+        );
+    }
+
+    return Object.freeze({ increment, set, pushSlice, newState });
+}
+
+function assertPath(path, opName) {
+    if (!PATH_REGEX.test(path)) {
+        throw new Error(
+            `applyProcessUpdate: invalid path '${path}' in ${opName} (must match ${PATH_REGEX})`
+        );
+    }
+}
+
+/**
+ * Splits a validated path into `{ column, segments }`.
+ * `'context.pagination.pageCount'` → `{ column: 'context', segments: ['pagination', 'pageCount'] }`.
+ */
+function splitPath(path) {
+    const [column, ...segments] = path.split('.');
+    return { column, segments };
+}
+
+module.exports = {
+    PATH_REGEX,
+    validateOps,
+    splitPath,
+};

package/integrations/tests/doubles/config-capturing-integration.js

@@ -0,0 +1,81 @@
+const { IntegrationBase } = require('../../integration-base');
+
+class ConfigCapturingModule {
+    static definition = {
+        getName: () => 'config-capturing-module'
+    };
+}
+
+class ConfigCapturingIntegration extends IntegrationBase {
+    static Definition = {
+        name: 'config-capturing',
+        version: '1.0.0',
+        modules: {
+            primary: ConfigCapturingModule
+        },
+        display: {
+            label: 'Config Capturing Integration',
+            description: 'Test double for capturing config state during updates',
+            detailsUrl: 'https://example.com',
+            icon: 'test-icon'
+        }
+    };
+
+    static _capturedOnUpdateState = null;
+
+    static resetCaptures() {
+        this._capturedOnUpdateState = null;
+    }
+
+    static getCapturedOnUpdateState() {
+        return this._capturedOnUpdateState;
+    }
+
+    constructor(params) {
+        super(params);
+        this.integrationRepository = {
+            updateIntegrationById: jest.fn().mockResolvedValue({}),
+            findIntegrationById: jest.fn().mockResolvedValue({}),
+        };
+        this.updateIntegrationStatus = {
+            execute: jest.fn().mockResolvedValue({})
+        };
+        this.updateIntegrationMessages = {
+            execute: jest.fn().mockResolvedValue({})
+        };
+    }
+
+    async initialize() {
+        this.registerEventHandlers();
+    }
+
+    async onUpdate(params) {
+        ConfigCapturingIntegration._capturedOnUpdateState = {
+            thisConfig: JSON.parse(JSON.stringify(this.config)),
+            paramsConfig: params.config
+        };
+
+        this.config = this._deepMerge(this.config, params.config);
+    }
+
+    _deepMerge(target, source) {
+        const result = { ...target };
+        for (const key of Object.keys(source)) {
+            if (
+                source[key] !== null &&
+                typeof source[key] === 'object' &&
+                !Array.isArray(source[key]) &&
+                target[key] !== null &&
+                typeof target[key] === 'object' &&
+                !Array.isArray(target[key])
+            ) {
+                result[key] = this._deepMerge(target[key], source[key]);
+            } else {
+                result[key] = source[key];
+            }
+        }
+        return result;
+    }
+}
+
+module.exports = { ConfigCapturingIntegration };

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

@@ -0,0 +1,113 @@
+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.testAuthSpy = 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({})
+        };
+    }
+
+    async loadDynamicUserActions() {
+        return {};
+    }
+
+    async send(event, data) {
+        this.sendSpy(event, data);
+        this.eventCallHistory.push({ event, data, timestamp: Date.now() });
+        if (event === 'ON_UPDATE') {
+            await this.onUpdate(data);
+        }
+        if (event === 'ON_DELETE') {
+            await this.onDelete(data);
+        }
+        return { event, data };
+    }
+
+    async initialize() {
+        return;
+    }
+
+    async testAuth() {
+        this.testAuthSpy();
+    }
+
+    async onCreate({ integrationId }) {
+        return;
+    }
+
+    async onUpdate(params) {
+        this.config = this._deepMerge(this.config, params.config);
+    }
+
+    _deepMerge(target, source) {
+        const result = { ...target };
+        for (const key of Object.keys(source)) {
+            if (
+                source[key] !== null &&
+                typeof source[key] === 'object' &&
+                !Array.isArray(source[key]) &&
+                target[key] !== null &&
+                typeof target[key] === 'object' &&
+                !Array.isArray(target[key])
+            ) {
+                result[key] = this._deepMerge(target[key], source[key]);
+            } else {
+                result[key] = source[key];
+            }
+        }
+        return result;
+    }
+
+    async onDelete(params) {
+        return;
+    }
+
+    getConfig() {
+        return this.config || {};
+    }
+}
+
+module.exports = { DummyIntegration }; 

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

@@ -0,0 +1,146 @@
+const { v4: uuid } = require('uuid');
+const { validateConfigPatch } = require('../../repositories/config-patch-shared');
+
+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: 'IN_CREATION',
+            messages: {},
+            createdAt: new Date(),
+        };
+        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 findIntegrations(filter = {}) {
+        const { type, status } = filter;
+        const results = Array.from(this.store.values()).filter((r) => {
+            if (type && r.config?.type !== type) return false;
+            if (status && r.status !== status) return false;
+            return true;
+        });
+        this.operationHistory.push({ operation: 'findAll', count: results.length });
+        return results;
+    }
+
+    async findIntegrationByUserId(userId) {
+        const record = Array.from(this.store.values()).find((r) => r.userId === userId);
+        this.operationHistory.push({
+            operation: 'findSingleByUserId',
+            userId,
+            found: !!record,
+        });
+        return record || null;
+    }
+
+    async findIntegrationsByEntityId(entityId) {
+        const target = String(entityId);
+        const results = Array.from(this.store.values()).filter((r) =>
+            (r.entitiesIds || []).map(String).includes(target)
+        );
+        this.operationHistory.push({
+            operation: 'findByEntityId',
+            entityId: target,
+            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) {
+        if (config === null || config === undefined) {
+            throw new Error('Config parameter is required');
+        }
+        const rec = this.store.get(id);
+        if (!rec) {
+            this.operationHistory.push({ operation: 'updateConfig', id, success: false });
+            throw new Error(`Integration with id ${id} not found`);
+        }
+        rec.config = config;
+        this.operationHistory.push({ operation: 'updateConfig', id, success: true });
+        return rec;
+    }
+
+    async patchIntegrationConfig(id, patch) {
+        validateConfigPatch(patch);
+        if (!this.store.has(id)) {
+            this.operationHistory.push({ operation: 'patchConfig', id, success: false });
+            throw new Error(`Integration with id ${id} not found`);
+        }
+        // Simulates the DB round trip real adapters make: the merge reads
+        // the record fresh at write time rather than off a snapshot taken
+        // before the await, so concurrent patches to the same id can't lose
+        // each other's keys — same guarantee as `config || $1::jsonb` in
+        // postgres or a mongo/documentdb findAndModify.
+        await Promise.resolve();
+        const rec = this.store.get(id);
+        rec.config = { ...rec.config, ...patch };
+        this.operationHistory.push({ operation: 'patchConfig', id, success: true });
+        return rec;
+    }
+
+    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/use-cases/create-integration.js

@@ -0,0 +1,215 @@
+// Removed Integration wrapper - using IntegrationBase directly
+const {
+    mapIntegrationClassToIntegrationDTO,
+} = require('../utils/map-integration-dto');
+
+/**
+ * Use case for creating a new integration instance.
+ * @class CreateIntegration
+ */
+class CreateIntegration {
+    /**
+     * Creates a new CreateIntegration instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface} params.integrationRepository - Repository for integration data operations.
+     * @param {import('../integration-classes').IntegrationClasses} params.integrationClasses - Array of available integration classes.
+     * @param {import('../../modules/module-factory').ModuleFactory} params.moduleFactory - Service for module instantiation and management.
+     */
+    constructor({ integrationRepository, integrationClasses, moduleFactory }) {
+        this.integrationRepository = integrationRepository;
+        this.integrationClasses = integrationClasses;
+        this.moduleFactory = moduleFactory;
+    }
+
+    /**
+     * Executes the integration creation process. Reuses an existing
+     * integration when one already exists for the same userId, config.type,
+     * and entity set, instead of creating a duplicate.
+     * @async
+     * @param {string[]} entities - Array of entity IDs to associate with the integration.
+     * @param {string} userId - ID of the user creating the integration.
+     * @param {Object} config - Configuration object for the integration.
+     * @param {string} config.type - Type of integration to create.
+     * @returns {Promise<Object>} The created or reused integration DTO.
+     * @throws {Error} When integration class is not found for the specified type.
+     */
+    async execute(entities, userId, config) {
+        console.log(
+            `[Frigg] Creating ${config?.type} integration for user ${userId} with entities [${entities}]`
+        );
+
+        const existing = await this._findDuplicate(
+            userId,
+            config?.type,
+            entities
+        );
+        if (existing) {
+            console.log(
+                `[Frigg] Found existing integration ${existing.id} for the same user, type, and entities — reusing it`
+            );
+            return this._reuseExisting(existing, config);
+        }
+
+        const integrationRecord =
+            await this.integrationRepository.createIntegration(
+                entities,
+                userId,
+                config
+            );
+        console.log(
+            `[Frigg] Created integration ${integrationRecord.id} for user ${userId}`
+        );
+
+        // 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(
+            userId,
+            config?.type,
+            entities
+        );
+        if (survivor && String(survivor.id) !== String(integrationRecord.id)) {
+            console.log(
+                `[Frigg] Concurrent create detected — deleting duplicate ${integrationRecord.id} and reusing ${survivor.id}`
+            );
+            await this.integrationRepository.deleteIntegrationById(
+                integrationRecord.id
+            );
+            return this._reuseExisting(survivor, config);
+        }
+
+        const integrationInstance = await this._buildInstance(
+            integrationRecord
+        );
+        console.log(
+            `[Frigg] Sending ON_CREATE for integration ${integrationRecord.id}`
+        );
+        await integrationInstance.send('ON_CREATE', {
+            integrationId: integrationRecord.id,
+        });
+
+        return mapIntegrationClassToIntegrationDTO(integrationInstance);
+    }
+
+    async _reuseExisting(integrationRecord, config) {
+        // The caller may be reconnecting with changed settings. Persist the
+        // requested config onto the reused row as a shallow patch, so new
+        // values take effect while keys added during the original create
+        // (webhook ids, secrets) survive. `type` is re-written to the same
+        // value it dedupe-matched on, which is a harmless no-op.
+        if (config && Object.keys(config).length > 0) {
+            integrationRecord =
+                await this.integrationRepository.patchIntegrationConfig(
+                    integrationRecord.id,
+                    config
+                );
+        }
+
+        const integrationInstance = await this._buildInstance(
+            integrationRecord
+        );
+
+        if (integrationInstance.status === 'IN_CREATION') {
+            // ON_CREATE never finished for this row (crashed mid-setup or is
+            // still running concurrently). Re-firing ON_CREATE here would
+            // risk re-registering a webhook a partially-completed attempt
+            // already created — unsafe without idempotent setup, which is a
+            // separate, larger change. Surfaced loudly rather than silently
+            // reused as if healthy, so it's diagnosable; testAuth below still
+            // runs and can at least surface bad credentials as ERROR.
+            console.warn(
+                `[Frigg] Integration ${integrationInstance.id} is still IN_CREATION on reuse — setup never completed`
+            );
+        }
+
+        // User is actively trying to reconnect; here if the integration is
+        // disabled, we can enable it again.
+        const authPassed = await integrationInstance.testAuth();
+        await integrationInstance.reconcileAuthStatus(authPassed);
+        if (integrationInstance.status === 'DISABLED') {
+            console.log(
+                `[Frigg] Integration ${integrationInstance.id} changed status from DISABLED to ENABLED`
+            );
+            await integrationInstance.persistStatus('ENABLED');
+        }
+
+        return mapIntegrationClassToIntegrationDTO(integrationInstance);
+    }
+
+    async _findDuplicate(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();
+            return (
+                current.length === target.length &&
+                current.every((id, index) => id === target[index])
+            );
+        });
+
+        return matches.length ? this._pickOldest(matches) : null;
+    }
+
+    _pickOldest(records) {
+        return [...records].sort((a, b) => {
+            const diff =
+                new Date(a.createdAt ?? 0) - new Date(b.createdAt ?? 0);
+            if (diff !== 0) return diff;
+            return String(a.id).localeCompare(String(b.id), 'en', {
+                numeric: true,
+            });
+        })[0];
+    }
+
+    async _buildInstance(integrationRecord) {
+        const integrationClass = this.integrationClasses.find(
+            (integrationClass) =>
+                integrationClass.Definition.name ===
+                integrationRecord.config.type
+        );
+
+        if (!integrationClass) {
+            throw new Error(
+                `No integration class found for type: ${integrationRecord.config.type}`
+            );
+        }
+
+        const modules = [];
+        for (const entityId of integrationRecord.entitiesIds) {
+            const moduleInstance = await this.moduleFactory.getModuleInstance(
+                entityId,
+                integrationRecord.userId
+            );
+            modules.push(moduleInstance);
+        }
+
+        const integrationInstance = new integrationClass({
+            id: integrationRecord.id,
+            userId: integrationRecord.userId,
+            entities: integrationRecord.entitiesIds,
+            config: integrationRecord.config,
+            status: integrationRecord.status,
+            version: integrationRecord.version,
+            messages: integrationRecord.messages,
+            modules,
+        });
+
+        await integrationInstance.initialize();
+
+        return integrationInstance;
+    }
+}
+
+module.exports = { CreateIntegration };