@friggframework/core 2.0.0-next.9 → 2.0.0-next.91

package/integrations/integration-base.js

@@ -1,5 +1,18 @@
-const { IntegrationMapping } = require('./integration-mapping');
+const {
+    createIntegrationMappingRepository,
+} = require('./repositories/integration-mapping-repository-factory');
 const { Options } = require('./options');
+const {
+    UpdateIntegrationStatus,
+} = require('./use-cases/update-integration-status');
+const {
+    createIntegrationRepository,
+} = require('./repositories/integration-repository-factory');
+const {
+    UpdateIntegrationMessages,
+} = require('./use-cases/update-integration-messages');
+const { validateExtensionBinding } = require('./extension');
+
 const constantsToBeMigrated = {
     defaultEvents: {
         ON_CREATE: 'ON_CREATE',
@@ -10,6 +23,8 @@ const constantsToBeMigrated = {
         GET_USER_ACTIONS: 'GET_USER_ACTIONS',
         GET_USER_ACTION_OPTIONS: 'GET_USER_ACTION_OPTIONS',
         REFRESH_USER_ACTION_OPTIONS: 'REFRESH_USER_ACTION_OPTIONS',
+        WEBHOOK_RECEIVED: 'WEBHOOK_RECEIVED', // HTTP handler, no DB
+        ON_WEBHOOK: 'ON_WEBHOOK', // Queue worker, DB-connected
         // etc...
     },
     types: {
@@ -19,6 +34,16 @@ const constantsToBeMigrated = {
 };
 
 class IntegrationBase {
+    // todo: maybe we can pass this as Dependency Injection in the sub-class constructor
+    integrationRepository = createIntegrationRepository();
+    integrationMappingRepository = createIntegrationMappingRepository();
+    updateIntegrationStatus = new UpdateIntegrationStatus({
+        integrationRepository: this.integrationRepository,
+    });
+    updateIntegrationMessages = new UpdateIntegrationMessages({
+        integrationRepository: this.integrationRepository,
+    });
+
     static getOptionDetails() {
         const options = new Options({
             module: Object.values(this.Definition.modules)[0], // This is a placeholder until we revamp the frontend
@@ -26,6 +51,7 @@ class IntegrationBase {
         });
         return options.get();
     }
+
     /**
      * CHILDREN SHOULD SPECIFY A DEFINITION FOR THE INTEGRATION
      */
@@ -35,6 +61,9 @@ class IntegrationBase {
         supportedVersions: [], // Eventually usable for deprecation and future test version purposes
 
         modules: {},
+        // Tier 3 Integration Extensions — see packages/core/integrations/EXTENSIONS.md
+        // Shape: { [bindingName]: { extension, handlers?: { [eventName]: methodName } } }
+        extensions: {},
         display: {
             name: 'Integration Name',
             logo: '',
@@ -50,29 +79,30 @@ class IntegrationBase {
     static getCurrentVersion() {
         return this.Definition.version;
     }
-    loadModules() {
-        // Load all the modules defined in Definition.modules
-        const moduleNames = Object.keys(this.constructor.Definition.modules);
-        for (const moduleName of moduleNames) {
-            const { definition } =
-                this.constructor.Definition.modules[moduleName];
-            if (typeof definition.API === 'function') {
-                this[moduleName] = { api: new definition.API() };
-            } else {
-                throw new Error(
-                    `Module ${moduleName} must be a function that extends IntegrationModule`
-                );
-            }
+
+    // REMOVED: registerEventHandlers() - Event handling is now done by IntegrationEventDispatcher
+
+    constructor(params = {}) {
+        this.modules = {};
+        this.events = this.events || {};
+        this.messages = { errors: [], warnings: [] };
+        this._isHydrated = false;
+
+        if (params && Object.keys(params).length > 0) {
+            this.setIntegrationRecord({
+                record: {
+                    id: params.id,
+                    userId: params.userId,
+                    entities: params.entities,
+                    config: params.config,
+                    status: params.status,
+                    version: params.version,
+                    messages: params.messages,
+                },
+                modules: params.modules || [],
+            });
         }
-    }
-    registerEventHandlers() {
-        this.on = {
-            ...this.defaultEvents,
-            ...this.events,
-        };
-    }
 
-    constructor(params) {
         this.defaultEvents = {
             [constantsToBeMigrated.defaultEvents.ON_CREATE]: {
                 type: constantsToBeMigrated.types.LIFE_CYCLE_EVENT,
@@ -106,22 +136,139 @@ class IntegrationBase {
                 type: constantsToBeMigrated.types.LIFE_CYCLE_EVENT,
                 handler: this.refreshActionOptions,
             },
+            [constantsToBeMigrated.defaultEvents.WEBHOOK_RECEIVED]: {
+                type: constantsToBeMigrated.types.LIFE_CYCLE_EVENT,
+                handler: this.onWebhookReceived,
+            },
+            [constantsToBeMigrated.defaultEvents.ON_WEBHOOK]: {
+                type: constantsToBeMigrated.types.LIFE_CYCLE_EVENT,
+                handler: this.onWebhook,
+            },
         };
-        this.loadModules();
     }
 
-    async send(event, object) {
-        if (!this.on[event]) {
-            throw new Error(
-                `Event ${event} is not defined in the Integration event object`
-            );
+    // todo: debate wether we want to keep this pattern to set the record or not.
+    /**
+     * Persist the database record and module instances onto this integration instance.
+     * Accepts either a plain object containing the persisted fields or an object with
+     * a `record` property plus a `modules` collection.
+     * @param {Object} payload
+     * @param {Object} [payload.record]
+     * @param {Array} [payload.modules]
+     */
+    setIntegrationRecord(payload = {}) {
+        if (!payload || Object.keys(payload).length === 0) {
+            throw new Error('setIntegrationRecord requires integration data');
         }
-        return this.on[event].handler.call(this, object);
+
+        const integrationRecord = payload.record;
+        const integrationModules = payload.modules ?? [];
+
+        if (!integrationRecord) {
+            throw new Error('Integration record not provided');
+        }
+
+        const { id, userId, entities, config, status, version, messages } =
+            integrationRecord;
+
+        this.id = id;
+        this.userId = userId;
+        this.entities = entities;
+        this.config = config;
+        this.status = status;
+        this.version = version;
+        this.messages = messages || { errors: [], warnings: [] };
+
+        this.modules = this._appendModules(integrationModules);
+
+        this.record = {
+            id: this.id,
+            userId: this.userId,
+            entities: this.entities,
+            config: this.config,
+            status: this.status,
+            version: this.version,
+            messages: this.messages,
+        };
+
+        this._isHydrated = Boolean(this.id);
+        return this;
+    }
+
+    get isHydrated() {
+        return this._isHydrated;
+    }
+
+    assertHydrated(message = 'Integration instance is not hydrated') {
+        if (!this.isHydrated) {
+            throw new Error(message);
+        }
+    }
+
+    /**
+     * Returns the modules as object with keys as module names.
+     * Uses the keys from Definition.modules to attach modules correctly.
+     * 
+     * Example:
+     *   Definition.modules = { attio: {...}, quo: { definition: { getName: () => 'quo-attio' } } }
+     *   Module with getName()='quo-attio' gets attached as this.quo (not this['quo-attio'])
+     * 
+     * @private
+     * @param {Array} integrationModules - Array of module instances
+     * @returns {Object} The modules object
+     */
+    _appendModules(integrationModules) {
+        const modules = {};
+
+        // Build reverse mapping: definition.getName() → referenceKey
+        // e.g., 'quo-attio' → 'quo', 'attio' → 'attio'
+        const moduleNameToKey = {};
+        if (this.constructor.Definition?.modules) {
+            for (const [key, moduleConfig] of Object.entries(this.constructor.Definition.modules)) {
+                const definition = moduleConfig.definition;
+                if (definition) {
+                    // Use getName() if available, fallback to moduleName
+                    const definitionName = typeof definition.getName === 'function'
+                        ? definition.getName()
+                        : definition.moduleName;
+                    if (definitionName) {
+                        moduleNameToKey[definitionName] = key;
+                    }
+                }
+            }
+        }
+
+        for (const module of integrationModules) {
+            const moduleName =
+                typeof module.getName === 'function'
+                    ? module.getName()
+                    : module.name;
+
+            // Use the reference key from Definition.modules if available,
+            // otherwise fall back to moduleName
+            const key = moduleNameToKey[moduleName] || moduleName;
+
+            if (key) {
+                modules[key] = module;
+                this[key] = module;
+            }
+
+            // Wire the Delegate pattern so Module can notify this integration
+            // of events it cannot handle itself (e.g. credential invalidation
+            // needing an Integration.status flip). Without this, Module.notify
+            // silently no-ops and Integration.status never updates on auth
+            // failure.
+            if (module && typeof module === 'object') {
+                module.delegate = this;
+            }
+        }
+
+        return modules;
     }
 
     async validateConfig() {
         const configOptions = await this.getConfigOptions();
-        const currentConfig = this.record.config;
+        const currentConfig = this.getConfig();
         let needsConfig = false;
         for (const option of configOptions) {
             if (option.required) {
@@ -133,56 +280,62 @@ class IntegrationBase {
                     )
                 ) {
                     needsConfig = true;
-                    this.record.messages.warnings.push({
-                        title: 'Config Validation Error',
-                        message: `Missing required field of ${option.label}`,
-                        timestamp: Date.now(),
-                    });
+                    await this.updateIntegrationMessages.execute(
+                        this.id,
+                        'warnings',
+                        'Config Validation Error',
+                        `Missing required field of ${option.label}`,
+                        Date.now()
+                    );
                 }
             }
         }
         if (needsConfig) {
-            this.record.status = 'NEEDS_CONFIG';
-            await this.record.save();
+            await this.updateIntegrationStatus.execute(this.id, 'NEEDS_CONFIG');
         }
     }
 
     async testAuth() {
         let didAuthPass = true;
 
-        for (const module of Object.keys(IntegrationBase.Definition.modules)) {
+        for (const module of Object.keys(this.constructor.Definition.modules)) {
             try {
                 await this[module].testAuth();
             } catch {
                 didAuthPass = false;
-                this.record.messages.errors.push({
-                    title: 'Authentication Error',
-                    message: `There was an error with your ${this[
+                await this.updateIntegrationMessages.execute(
+                    this.id,
+                    'errors',
+                    'Authentication Error',
+                    `There was an error with your ${this[
                         module
                     ].constructor.getName()} Entity.
                 Please reconnect/re-authenticate, or reach out to Support for assistance.`,
-                    timestamp: Date.now(),
-                });
+                    Date.now()
+                );
             }
         }
 
         if (!didAuthPass) {
-            this.record.status = 'ERROR';
-            this.record.markModified('messages.error');
-            await this.record.save();
+            await this.updateIntegrationStatus.execute(this.id, 'ERROR');
         }
     }
 
     async getMapping(sourceId) {
-        return IntegrationMapping.findBy(this.record.id, sourceId);
+        // todo: not sure we should call the repository directly from here
+        return this.integrationMappingRepository.findMappingBy(
+            this.id,
+            sourceId
+        );
     }
 
     async upsertMapping(sourceId, mapping) {
         if (!sourceId) {
             throw new Error(`sourceId must be set`);
         }
-        return await IntegrationMapping.upsert(
-            this.record.id,
+        // todo: not sure we should call the repository directly from here
+        return await this.integrationMappingRepository.upsertMapping(
+            this.id,
             sourceId,
             mapping
         );
@@ -191,13 +344,13 @@ class IntegrationBase {
     /**
      * CHILDREN CAN OVERRIDE THESE CONFIGURATION METHODS
      */
-    async onCreate(params) {
-        this.record.status = 'ENABLED';
-        await this.record.save();
-        return this.record;
+    async onCreate({ integrationId }) {
+        await this.updateIntegrationStatus.execute(integrationId, 'ENABLED');
     }
 
-    async onUpdate(params) {}
+    async onUpdate(params) {
+        return this.validateConfig();
+    }
 
     async onDelete(params) {}
 
@@ -224,7 +377,6 @@ class IntegrationBase {
         return {};
     }
     async loadUserActions({ actionType } = {}) {
-        console.log('loadUserActions called with actionType:', actionType);
         const userActions = {};
         for (const [key, event] of Object.entries(this.events)) {
             if (event.type === constantsToBeMigrated.types.USER_ACTION) {
@@ -259,6 +411,286 @@ class IntegrationBase {
         };
         return options;
     }
+
+    /**
+     * WEBHOOK EVENT HANDLERS
+     */
+    async onWebhookReceived({ req, res }) {
+        // Default: queue webhook for processing
+        const body = req.body;
+        const integrationId = req.params.integrationId || null;
+
+        await this.queueWebhook({
+            integrationId,
+            body,
+            headers: req.headers,
+            query: req.query,
+        });
+
+        res.status(200).json({ received: true });
+    }
+
+    async onWebhook({ data }) {
+        // Default: no-op, integrations override this
+    }
+
+    /**
+     * Queue a webhook for asynchronous worker dispatch.
+     *
+     * The dispatch event defaults to `ON_WEBHOOK` for backward compatibility
+     * with the `Definition.webhooks: true` path. Extensions (and any caller
+     * that needs the worker to invoke a specific bound handler) can override
+     * by passing `event` in the payload — it's stripped from the payload and
+     * used as the SQS message's dispatch event.
+     *
+     * @param {Object} data - Webhook payload. May include `event` to override
+     *   the default `ON_WEBHOOK` dispatch event. All other fields are passed
+     *   through to the worker as the `data` field of the SQS message.
+     */
+    async queueWebhook(data) {
+        const { QueuerUtil } = require('../queues');
+
+        const queueName = `${this.constructor.Definition.name
+            .toUpperCase()
+            .replace(/-/g, '_')}_QUEUE_URL`;
+        const queueUrl = process.env[queueName];
+
+        if (!queueUrl) {
+            throw new Error(`Queue URL not found for ${queueName}`);
+        }
+
+        const { event: dispatchEvent, ...payload } = data || {};
+
+        return QueuerUtil.send(
+            {
+                event: dispatchEvent || 'ON_WEBHOOK',
+                data: payload,
+            },
+            queueUrl
+        );
+    }
+
+    // === Domain Methods (moved from Integration.js) ===
+
+    getConfig() {
+        return this.config;
+    }
+
+    getModule(key) {
+        return this.modules[key];
+    }
+
+    setModule(key, module) {
+        this.modules[key] = module;
+        this[key] = module;
+    }
+
+    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);
+    }
+
+    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();
+    }
+
+    registerEventHandlers() {
+        this.on = {
+            ...this.defaultEvents,
+            ...this.events,
+        };
+    }
+
+    /**
+     * Merge Tier 3 Integration Extension events into `this.events`.
+     *
+     * For each binding declared on `static Definition.extensions`, this method:
+     *   1. Validates the extension bundle shape and binding handlers
+     *   2. For each event the extension declares, resolves the handler in priority order:
+     *      a. Subclass-defined `this.events[eventName]` (set in the constructor) — wins; if a
+     *         binding tried to override that event with `handlers`, we log a warning so the
+     *         author knows their override is shadowed.
+     *      b. A method-name string in `binding.handlers[eventName]` → method on this instance
+     *      c. The extension's own default `handler` function
+     *      d. Otherwise throw — neither side provided a handler
+     *   3. Binds the resolved function to this instance and writes it to `this.events[eventName]`
+     *
+     * Two bindings declaring the same event throw a deterministic conflict error — silent
+     * "first/last writer wins" makes routing bugs nearly impossible to diagnose.
+     *
+     * @private
+     */
+    _mergeExtensions() {
+        const extensions = this.constructor.Definition?.extensions || {};
+        const integrationName = this.constructor.Definition?.name;
+        // Tracks which event names have been claimed by an extension binding during
+        // this merge — distinct from subclass-defined events on `this.events`.
+        const mergedByExtension = new Map();
+
+        for (const [bindingName, binding] of Object.entries(extensions)) {
+            if (!binding || typeof binding !== 'object') {
+                throw new Error(
+                    `Integration "${integrationName}" extension binding "${bindingName}" must be an object`
+                );
+            }
+            const { extension, handlers = {} } = binding;
+            validateExtensionBinding(
+                extension,
+                bindingName,
+                integrationName,
+                binding
+            );
+
+            const extEvents = extension.events || {};
+            for (const [eventName, eventDef] of Object.entries(extEvents)) {
+                // Conflict detection: another extension binding already claimed this event name.
+                if (mergedByExtension.has(eventName)) {
+                    const prev = mergedByExtension.get(eventName);
+                    throw new Error(
+                        `Integration "${integrationName}" extension event conflict: ` +
+                            `event "${eventName}" is declared by both binding "${prev}" and binding "${bindingName}" — ` +
+                            `use distinct event names per binding or omit duplicates`
+                    );
+                }
+
+                // Subclass shadowing: if the subclass set this.events[eventName] before initialize(),
+                // it wins. Warn if the binding tried to wire an override that's now ignored.
+                if (this.events[eventName]) {
+                    if (typeof handlers[eventName] === 'string') {
+                        console.warn(
+                            `[Frigg] Integration "${integrationName}" binding "${bindingName}": ` +
+                                `handler "${handlers[eventName]}" for event "${eventName}" is ignored because ` +
+                                `this.events["${eventName}"] was already set (subclass constructor or earlier merge)`
+                        );
+                    }
+                    continue;
+                }
+
+                let fn;
+                const override = handlers[eventName];
+                if (typeof override === 'string') {
+                    if (typeof this[override] !== 'function') {
+                        throw new Error(
+                            `Integration "${integrationName}" extension binding "${bindingName}": handler method "${override}" not found on instance`
+                        );
+                    }
+                    fn = this[override];
+                } else if (typeof eventDef.handler === 'function') {
+                    fn = eventDef.handler;
+                } else {
+                    throw new Error(
+                        `Extension "${extension.name}" event "${eventName}" has no default handler and binding "${bindingName}" did not provide one`
+                    );
+                }
+
+                this.events[eventName] = {
+                    type: eventDef.type,
+                    handler: fn.bind(this),
+                };
+                mergedByExtension.set(eventName, bindingName);
+            }
+        }
+    }
+
+    async initialize() {
+        try {
+            const additionalUserActions = await this.loadDynamicUserActions();
+            this.events = { ...this.events, ...additionalUserActions };
+        } catch (e) {
+            this.addError(e);
+        }
+
+        this._mergeExtensions();
+        this.registerEventHandlers();
+    }
+
+    async send(event, object) {
+        if (!this.on[event]) {
+            throw new Error(
+                `Event ${event} is not defined in the Integration event object`
+            );
+        }
+        return this.on[event].handler.call(this, object);
+    }
+
+    getOptionDetails() {
+        const options = new Options({
+            module: Object.values(this.constructor.Definition.modules)[0],
+            ...this.constructor.Definition,
+        });
+        return options.get();
+    }
+
+    // Legacy method for backward compatibility
+    async loadModules() {
+        // This method was used in the old architecture for loading modules
+        // In the new architecture, modules are injected via constructor
+        // For backward compatibility, this is a no-op
+        return;
+    }
+
+    /**
+     * Receives notifications from modules (the Delegate pattern) when
+     * something integration-level needs attention. Today this catches the
+     * `CREDENTIAL_INVALIDATED` event Module fires from `markCredentialsInvalid`
+     * and flips this integration's status to DISABLED so the queue worker
+     * stops processing further webhooks until the user re-authorizes.
+     *
+     * Modules are wired to this delegate in `_appendModules()`, which runs
+     * during `setIntegrationRecord()` — this covers every construction path
+     * (HTTP read, queue worker, create/update/delete flows, etc.).
+     *
+     * The delegate string below must match `Module.DLGT_CREDENTIAL_INVALIDATED`
+     * in `packages/core/modules/module.js`.
+     *
+     * @param {Object} notifier - The module that fired the event
+     * @param {string} delegateString - Event type string
+     * @param {Object} [object] - Optional event payload
+     * @returns {Promise<void>}
+     */
+    async receiveNotification(notifier, delegateString, object = null) {
+        if (!this.id) return;
+
+        if (delegateString === 'CREDENTIAL_INVALIDATED') {
+            console.log(
+                `[Frigg] Module ${notifier?.name || '?'} reported invalid credentials for integration ${this.id} — marking ERROR`
+            );
+            await this.updateIntegrationStatus.execute(this.id, 'ERROR');
+            this.status = 'ERROR';
+            return;
+        }
+
+        if (delegateString === 'CREDENTIAL_VALIDATED') {
+            if (this.status !== 'ERROR') return;
+            console.log(
+                `[Frigg] Module ${notifier?.name || '?'} reported valid credentials for integration ${this.id} — clearing ERROR → ENABLED`
+            );
+            await this.updateIntegrationStatus.execute(this.id, 'ENABLED');
+            this.status = 'ENABLED';
+        }
+    }
 }
 
 module.exports = { IntegrationBase };