@friggframework/core 2.0.0-next.43 → 2.0.0-next.45

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/integration-base.js

@@ -22,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: {
@@ -130,6 +132,14 @@ 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,
+            },
         };
     }
 
@@ -294,7 +304,9 @@ class IntegrationBase {
         await this.updateIntegrationStatus.execute(integrationId, 'ENABLED');
     }
 
-    async onUpdate(params) {}
+    async onUpdate(params) {
+        return this.validateConfig();
+    }
 
     async onDelete(params) {}
 
@@ -357,6 +369,50 @@ 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
+        console.log('Webhook received:', data);
+    }
+
+    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() {
@@ -403,8 +459,14 @@ class IntegrationBase {
         return this.userId.toString() === userId.toString();
     }
 
+    registerEventHandlers() {
+        this.on = {
+            ...this.defaultEvents,
+            ...this.events,
+        };
+    }
+
     async initialize() {
-        // Load dynamic user actions
         try {
             const additionalUserActions = await this.loadDynamicUserActions();
             this.events = { ...this.events, ...additionalUserActions };
@@ -412,7 +474,16 @@ class IntegrationBase {
             this.addError(e);
         }
 
-        // Event handlers are no longer registered here - handled by IntegrationEventDispatcher
+        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() {

package/integrations/repositories/process-repository-factory.js

@@ -0,0 +1,46 @@
+const { ProcessRepositoryMongo } = require('./process-repository-mongo');
+const { ProcessRepositoryPostgres } = require('./process-repository-postgres');
+const config = require('../../database/config');
+
+/**
+ * Process Repository Factory
+ * Creates the appropriate repository adapter based on database type
+ *
+ * This implements the Factory pattern for Hexagonal Architecture:
+ * - Reads database type from app definition (backend/index.js)
+ * - Returns correct adapter (MongoDB or PostgreSQL)
+ * - Provides clear error for unsupported databases
+ *
+ * Usage:
+ * ```javascript
+ * const repository = createProcessRepository();
+ * await repository.create({ userId, integrationId, name, type, state });
+ * ```
+ *
+ * @returns {ProcessRepositoryInterface} Configured repository adapter
+ * @throws {Error} If database type is not supported
+ */
+function createProcessRepository() {
+    const dbType = config.DB_TYPE;
+
+    switch (dbType) {
+        case 'mongodb':
+            return new ProcessRepositoryMongo();
+
+        case 'postgresql':
+            return new ProcessRepositoryPostgres();
+
+        default:
+            throw new Error(
+                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'postgresql'`
+            );
+    }
+}
+
+module.exports = {
+    createProcessRepository,
+    // Export adapters for direct testing
+    ProcessRepositoryMongo,
+    ProcessRepositoryPostgres,
+};
+

package/integrations/repositories/process-repository-interface.js

@@ -0,0 +1,90 @@
+/**
+ * ProcessRepository Interface
+ * 
+ * Defines the contract for Process data access operations.
+ * Implementations must provide concrete methods for all operations.
+ * 
+ * This interface supports the Hexagonal Architecture pattern by:
+ * - Defining clear boundaries between domain logic and data access
+ * - Allowing multiple implementations (MongoDB, PostgreSQL, in-memory)
+ * - Enabling dependency injection and testability
+ */
+class ProcessRepositoryInterface {
+    /**
+     * Create a new process record
+     * @param {Object} processData - Process data to create
+     * @param {string} processData.userId - User ID
+     * @param {string} processData.integrationId - Integration ID
+     * @param {string} processData.name - Process name
+     * @param {string} processData.type - Process type
+     * @param {string} processData.state - Initial state
+     * @param {Object} [processData.context] - Process context
+     * @param {Object} [processData.results] - Process results
+     * @param {string[]} [processData.childProcesses] - Child process IDs
+     * @param {string} [processData.parentProcessId] - Parent process ID
+     * @returns {Promise<Object>} Created process record
+     */
+    async create(processData) {
+        throw new Error('Method create() must be implemented');
+    }
+
+    /**
+     * Find a process by ID
+     * @param {string} processId - Process ID to find
+     * @returns {Promise<Object|null>} Process record or null if not found
+     */
+    async findById(processId) {
+        throw new Error('Method findById() must be implemented');
+    }
+
+    /**
+     * Update a process record
+     * @param {string} processId - Process ID to update
+     * @param {Object} updates - Fields to update
+     * @returns {Promise<Object>} Updated process record
+     */
+    async update(processId, updates) {
+        throw new Error('Method update() must be implemented');
+    }
+
+    /**
+     * Find processes by integration and type
+     * @param {string} integrationId - Integration ID
+     * @param {string} type - Process type
+     * @returns {Promise<Array>} Array of process records
+     */
+    async findByIntegrationAndType(integrationId, type) {
+        throw new Error('Method findByIntegrationAndType() must be implemented');
+    }
+
+    /**
+     * Find active processes (not in excluded states)
+     * @param {string} integrationId - Integration ID
+     * @param {string[]} [excludeStates=['COMPLETED', 'ERROR']] - States to exclude
+     * @returns {Promise<Array>} Array of active process records
+     */
+    async findActiveProcesses(integrationId, excludeStates = ['COMPLETED', 'ERROR']) {
+        throw new Error('Method findActiveProcesses() must be implemented');
+    }
+
+    /**
+     * Find a process by name (most recent)
+     * @param {string} name - Process name
+     * @returns {Promise<Object|null>} Most recent process with given name, or null
+     */
+    async findByName(name) {
+        throw new Error('Method findByName() must be implemented');
+    }
+
+    /**
+     * Delete a process by ID
+     * @param {string} processId - Process ID to delete
+     * @returns {Promise<void>}
+     */
+    async deleteById(processId) {
+        throw new Error('Method deleteById() must be implemented');
+    }
+}
+
+module.exports = { ProcessRepositoryInterface };
+

package/integrations/repositories/process-repository-mongo.js

@@ -0,0 +1,190 @@
+const { prisma } = require('../../database/prisma');
+const { ProcessRepositoryInterface } = require('./process-repository-interface');
+
+/**
+ * MongoDB Process Repository Adapter
+ * Handles process persistence using Prisma with MongoDB
+ *
+ * MongoDB-specific characteristics:
+ * - Uses scalar fields for relations (userId, integrationId)
+ * - IDs are strings with @db.ObjectId
+ * - JSON fields for flexible context and results storage
+ * - Array field for childProcesses references
+ *
+ * Design Philosophy:
+ * - Generic Process model supports any type of long-running operation
+ * - Context and results stored as JSON for maximum flexibility
+ * - Integration-specific logic lives in use cases and services
+ */
+class ProcessRepositoryMongo extends ProcessRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    /**
+     * Create a new process record
+     * @param {Object} processData - Process data to create
+     * @returns {Promise<Object>} Created process record
+     */
+    async create(processData) {
+        const process = await this.prisma.process.create({
+            data: {
+                userId: processData.userId,
+                integrationId: processData.integrationId,
+                name: processData.name,
+                type: processData.type,
+                state: processData.state || 'INITIALIZING',
+                context: processData.context || {},
+                results: processData.results || {},
+                childProcesses: processData.childProcesses || [],
+                parentProcessId: processData.parentProcessId || null,
+            },
+        });
+
+        return this._toPlainObject(process);
+    }
+
+    /**
+     * Find a process by ID
+     * @param {string} processId - Process ID to find
+     * @returns {Promise<Object|null>} Process record or null if not found
+     */
+    async findById(processId) {
+        const process = await this.prisma.process.findUnique({
+            where: { id: processId },
+        });
+
+        return process ? this._toPlainObject(process) : null;
+    }
+
+    /**
+     * Update a process record
+     * @param {string} processId - Process ID to update
+     * @param {Object} updates - Fields to update
+     * @returns {Promise<Object>} Updated process record
+     */
+    async update(processId, updates) {
+        // Prepare update data, excluding undefined values
+        const updateData = {};
+
+        if (updates.state !== undefined) {
+            updateData.state = updates.state;
+        }
+        if (updates.context !== undefined) {
+            updateData.context = updates.context;
+        }
+        if (updates.results !== undefined) {
+            updateData.results = updates.results;
+        }
+        if (updates.childProcesses !== undefined) {
+            updateData.childProcesses = updates.childProcesses;
+        }
+        if (updates.parentProcessId !== undefined) {
+            updateData.parentProcessId = updates.parentProcessId;
+        }
+
+        const process = await this.prisma.process.update({
+            where: { id: processId },
+            data: updateData,
+        });
+
+        return this._toPlainObject(process);
+    }
+
+    /**
+     * Find processes by integration and type
+     * @param {string} integrationId - Integration ID
+     * @param {string} type - Process type
+     * @returns {Promise<Array>} Array of process records
+     */
+    async findByIntegrationAndType(integrationId, type) {
+        const processes = await this.prisma.process.findMany({
+            where: {
+                integrationId,
+                type,
+            },
+            orderBy: {
+                createdAt: 'desc',
+            },
+        });
+
+        return processes.map((p) => this._toPlainObject(p));
+    }
+
+    /**
+     * Find active processes (not in excluded states)
+     * @param {string} integrationId - Integration ID
+     * @param {string[]} [excludeStates=['COMPLETED', 'ERROR']] - States to exclude
+     * @returns {Promise<Array>} Array of active process records
+     */
+    async findActiveProcesses(integrationId, excludeStates = ['COMPLETED', 'ERROR']) {
+        const processes = await this.prisma.process.findMany({
+            where: {
+                integrationId,
+                state: {
+                    notIn: excludeStates,
+                },
+            },
+            orderBy: {
+                createdAt: 'desc',
+            },
+        });
+
+        return processes.map((p) => this._toPlainObject(p));
+    }
+
+    /**
+     * Find a process by name (most recent)
+     * @param {string} name - Process name
+     * @returns {Promise<Object|null>} Most recent process with given name, or null
+     */
+    async findByName(name) {
+        const process = await this.prisma.process.findFirst({
+            where: { name },
+            orderBy: {
+                createdAt: 'desc',
+            },
+        });
+
+        return process ? this._toPlainObject(process) : null;
+    }
+
+    /**
+     * Delete a process by ID
+     * @param {string} processId - Process ID to delete
+     * @returns {Promise<void>}
+     */
+    async deleteById(processId) {
+        await this.prisma.process.delete({
+            where: { id: processId },
+        });
+    }
+
+    /**
+     * Convert Prisma model to plain JavaScript object
+     * Ensures consistent API across repository implementations
+     * @private
+     * @param {Object} process - Prisma process model
+     * @returns {Object} Plain process object
+     */
+    _toPlainObject(process) {
+        return {
+            id: process.id,
+            userId: process.userId,
+            integrationId: process.integrationId,
+            name: process.name,
+            type: process.type,
+            state: process.state,
+            context: process.context,
+            results: process.results,
+            childProcesses: process.childProcesses,
+            parentProcessId: process.parentProcessId,
+            createdAt: process.createdAt,
+            updatedAt: process.updatedAt,
+        };
+    }
+}
+
+module.exports = { ProcessRepositoryMongo };
+