@friggframework/core 2.0.0-next.7 → 2.0.0-next.70

package/integrations/WEBHOOK-QUICKSTART.md

@@ -0,0 +1,151 @@
+# Webhook Quick Start Guide
+
+Get webhooks working in your Frigg integration in 3 simple steps.
+
+## Step 1: Enable Webhooks
+
+Add `webhooks: true` to your Integration Definition:
+
+```javascript
+class MyIntegration extends IntegrationBase {
+    static Definition = {
+        name: 'my-integration',
+        version: '1.0.0',
+        modules: {
+            myapi: { definition: MyApiDefinition },
+        },
+        webhooks: true,  // ← Add this line
+    };
+}
+```
+
+## Step 2: Handle Webhook Processing
+
+Override the `onWebhook` handler to process webhooks:
+
+```javascript
+class MyIntegration extends IntegrationBase {
+    // ... Definition ...
+
+    async onWebhook({ data }) {
+        const { body } = data;
+
+        // You have full access to:
+        // - this.myapi (your API modules)
+        // - this.config (integration config)
+        // - Database operations
+
+        if (body.event === 'item.created') {
+            await this.myapi.api.createItem(body.data);
+        }
+
+        return { processed: true };
+    }
+}
+```
+
+## Step 3: Deploy
+
+Deploy your Frigg app - webhook routes are automatically created:
+
+```bash
+POST /api/my-integration-integration/webhooks/:integrationId
+```
+
+## That's It!
+
+The default behavior handles:
+- ✅ Receiving webhooks (instant 200 OK response)
+- ✅ Queuing to SQS
+- ✅ Loading your integration with DB and API modules
+- ✅ Calling your `onWebhook` handler
+
+## Optional: Custom Signature Verification
+
+Override `onWebhookReceived` for custom signature checks:
+
+```javascript
+async onWebhookReceived({ req, res }) {
+    // Verify signature
+    const signature = req.headers['x-webhook-signature'];
+    if (!this.verifySignature(req.body, signature)) {
+        return res.status(401).json({ error: 'Invalid signature' });
+    }
+
+    // Queue for processing (default behavior)
+    await this.queueWebhook({
+        integrationId: req.params.integrationId,
+        body: req.body,
+    });
+
+    res.status(200).json({ received: true });
+}
+```
+
+## Two Webhook Routes
+
+### With Integration ID (Recommended)
+```
+POST /api/{name}-integration/webhooks/:integrationId
+```
+- Full integration loaded in worker
+- Access to DB, config, and API modules
+- Use `this.myapi`, `this.config`, etc.
+
+### Without Integration ID
+```
+POST /api/{name}-integration/webhooks
+```
+- Unhydrated integration
+- Useful for system-wide events
+- Limited context
+
+## Need Help?
+
+See full documentation: `packages/core/handlers/WEBHOOKS.md`
+
+## Common Patterns
+
+### Slack
+```javascript
+async onWebhookReceived({ req, res }) {
+    if (req.body.type === 'url_verification') {
+        return res.json({ challenge: req.body.challenge });
+    }
+    // ... verify signature, queue ...
+}
+```
+
+### Stripe
+```javascript
+async onWebhookReceived({ req, res }) {
+    const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
+    const event = stripe.webhooks.constructEvent(
+        JSON.stringify(req.body),
+        req.headers['stripe-signature'],
+        process.env.STRIPE_WEBHOOK_SECRET
+    );
+    await this.queueWebhook({ body: event });
+    res.status(200).json({ received: true });
+}
+```
+
+### GitHub
+```javascript
+async onWebhookReceived({ req, res }) {
+    const crypto = require('crypto');
+    const signature = req.headers['x-hub-signature-256'];
+    const hash = crypto
+        .createHmac('sha256', process.env.GITHUB_WEBHOOK_SECRET)
+        .update(JSON.stringify(req.body))
+        .digest('hex');
+    
+    if (`sha256=${hash}` !== signature) {
+        return res.status(401).json({ error: 'Invalid signature' });
+    }
+    
+    await this.queueWebhook({ integrationId: req.params.integrationId, body: req.body });
+    res.status(200).json({ received: true });
+}
+```
+

package/integrations/index.js

@@ -1,19 +1,21 @@
 const { IntegrationBase } = require('./integration-base');
-const { IntegrationModel } = require('./integration-model');
 const { Options } = require('./options');
-const { IntegrationMapping } = require('./integration-mapping');
-const { IntegrationFactory, IntegrationHelper } = require('./integration-factory');
-const { createIntegrationRouter, checkRequiredParams } = require('./integration-router');
-const { createFriggBackend } = require('./create-frigg-backend');
+const {
+    createIntegrationRouter,
+    checkRequiredParams,
+} = require('./integration-router');
+const {
+    getModulesDefinitionFromIntegrationClasses,
+} = require('./utils/map-integration-dto');
+const {
+    LoadIntegrationContextUseCase,
+} = require('./use-cases/load-integration-context');
 
 module.exports = {
     IntegrationBase,
-    IntegrationModel,
     Options,
-    IntegrationMapping,
-    IntegrationFactory,
-    IntegrationHelper,
     createIntegrationRouter,
     checkRequiredParams,
-    createFriggBackend
+    getModulesDefinitionFromIntegrationClasses,
+    LoadIntegrationContextUseCase,
 };

package/integrations/integration-base.js

@@ -1,5 +1,17 @@
-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 constantsToBeMigrated = {
     defaultEvents: {
         ON_CREATE: 'ON_CREATE',
@@ -10,6 +22,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 +33,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 +50,7 @@ class IntegrationBase {
         });
         return options.get();
     }
+
     /**
      * CHILDREN SHOULD SPECIFY A DEFINITION FOR THE INTEGRATION
      */
@@ -50,29 +75,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 +132,130 @@ 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');
+        }
+
+        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);
         }
-        return this.on[event].handler.call(this, object);
+    }
+
+    /**
+     * 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;
+            }
+        }
+
+        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 +267,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 +331,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 +364,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 +398,138 @@ 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
+    }
+
+    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}`);
+        }
+
+        return QueuerUtil.send(
+            {
+                event: 'ON_WEBHOOK',
+                data,
+            },
+            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,
+        };
+    }
+
+    async initialize() {
+        try {
+            const additionalUserActions = await this.loadDynamicUserActions();
+            this.events = { ...this.events, ...additionalUserActions };
+        } catch (e) {
+            this.addError(e);
+        }
+
+        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;
+    }
 }
 
 module.exports = { IntegrationBase };