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

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/repositories/report-id.js

@@ -0,0 +1,13 @@
+/**
+ * Coerces an id to an integer, rejecting partially-numeric input ('12abc',
+ * '12.9') that parseInt would silently truncate to 12 and read the wrong record.
+ */
+function strictIntId(id) {
+    const str = String(id).trim();
+    if (!/^-?\d+$/.test(str)) {
+        throw new TypeError(`Invalid ID: ${id} cannot be converted to integer`);
+    }
+    return Number.parseInt(str, 10);
+}
+
+module.exports = { strictIntId };

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