@friggframework/core 2.0.0-next.44 → 2.0.0-next.46

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

@@ -56,6 +56,18 @@ const {
 const {
     GetUserFromBearerToken,
 } = require('../user/use-cases/get-user-from-bearer-token');
+const {
+    GetUserFromXFriggHeaders,
+} = require('../user/use-cases/get-user-from-x-frigg-headers');
+const {
+    GetUserFromAdopterJwt,
+} = require('../user/use-cases/get-user-from-adopter-jwt');
+const {
+    AuthenticateWithSharedSecret,
+} = require('../user/use-cases/authenticate-with-shared-secret');
+const {
+    AuthenticateUser,
+} = require('../user/use-cases/authenticate-user');
 const {
     ProcessAuthorizationCallback,
 } = require('../modules/use-cases/process-authorization-callback');
@@ -73,6 +85,26 @@ function createIntegrationRouter() {
         userConfig,
     });
 
+    const getUserFromXFriggHeaders = new GetUserFromXFriggHeaders({
+        userRepository,
+        userConfig,
+    });
+
+    const getUserFromAdopterJwt = new GetUserFromAdopterJwt({
+        userRepository,
+        userConfig,
+    });
+
+    const authenticateWithSharedSecret = new AuthenticateWithSharedSecret();
+
+    const authenticateUser = new AuthenticateUser({
+        getUserFromBearerToken,
+        getUserFromXFriggHeaders,
+        getUserFromAdopterJwt,
+        authenticateWithSharedSecret,
+        userConfig,
+    });
+
     const moduleFactory = new ModuleFactory({
         moduleRepository,
         moduleDefinitions:
@@ -165,7 +197,7 @@ function createIntegrationRouter() {
 
     const router = express();
 
-    setIntegrationRoutes(router, getUserFromBearerToken, {
+    setIntegrationRoutes(router, authenticateUser, {
         createIntegration,
         deleteIntegrationForUser,
         getIntegrationsForUser,
@@ -174,7 +206,7 @@ function createIntegrationRouter() {
         updateIntegration,
         getPossibleIntegrations,
     });
-    setEntityRoutes(router, getUserFromBearerToken, {
+    setEntityRoutes(router, authenticateUser, {
         getCredentialForUser,
         getModuleInstanceFromType,
         getEntityOptionsByType,
@@ -201,10 +233,8 @@ function checkRequiredParams(params, requiredKeys) {
 
     if (missingKeys.length > 0) {
         throw Boom.badRequest(
-            `Missing Parameter${
-                missingKeys.length === 1 ? '' : 's'
-            }: ${missingKeys.join(', ')} ${
-                missingKeys.length === 1 ? 'is' : 'are'
+            `Missing Parameter${missingKeys.length === 1 ? '' : 's'
+            }: ${missingKeys.join(', ')} ${missingKeys.length === 1 ? 'is' : 'are'
             } required.`
         );
     }
@@ -214,10 +244,10 @@ function checkRequiredParams(params, requiredKeys) {
 /**
  * Sets up integration-related routes on the provided Express router
  * @param {express.Router} router - Express router instance to add routes to
- * @param {import('../user/use-cases/get-user-from-bearer-token').GetUserFromBearerToken} getUserFromBearerToken - Use case for retrieving a user from a bearer token
+ * @param {import('../user/use-cases/authenticate-user').AuthenticateUser} authenticateUser - Use case for multi-mode user authentication
  * @param {Object} useCases - use cases for integration management
  */
-function setIntegrationRoutes(router, getUserFromBearerToken, useCases) {
+function setIntegrationRoutes(router, authenticateUser, useCases) {
     const {
         createIntegration,
         deleteIntegrationForUser,
@@ -229,9 +259,7 @@ function setIntegrationRoutes(router, getUserFromBearerToken, useCases) {
     } = useCases;
     router.route('/api/integrations').get(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const userId = user.getId();
             const integrations = await getIntegrationsForUser.execute(userId);
             const results = {
@@ -248,9 +276,7 @@ function setIntegrationRoutes(router, getUserFromBearerToken, useCases) {
 
     router.route('/api/integrations').post(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const userId = user.getId();
             const params = checkRequiredParams(req.body, [
                 'entities',
@@ -271,9 +297,7 @@ function setIntegrationRoutes(router, getUserFromBearerToken, useCases) {
 
     router.route('/api/integrations/:integrationId').patch(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const userId = user.getId();
             const params = checkRequiredParams(req.body, ['config']);
 
@@ -288,9 +312,7 @@ function setIntegrationRoutes(router, getUserFromBearerToken, useCases) {
 
     router.route('/api/integrations/:integrationId').delete(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const params = checkRequiredParams(req.params, ['integrationId']);
             await deleteIntegrationForUser.execute(
                 params.integrationId,
@@ -302,9 +324,7 @@ function setIntegrationRoutes(router, getUserFromBearerToken, useCases) {
 
     router.route('/api/integrations/:integrationId/config/options').get(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const params = checkRequiredParams(req.params, ['integrationId']);
             const integration = await getIntegrationInstance.execute(
                 params.integrationId,
@@ -318,9 +338,7 @@ function setIntegrationRoutes(router, getUserFromBearerToken, useCases) {
         .route('/api/integrations/:integrationId/config/options/refresh')
         .post(
             catchAsyncError(async (req, res) => {
-                const user = await getUserFromBearerToken.execute(
-                    req.headers.authorization
-                );
+                const user = await authenticateUser.execute(req);
                 const params = checkRequiredParams(req.params, [
                     'integrationId',
                 ]);
@@ -336,9 +354,7 @@ function setIntegrationRoutes(router, getUserFromBearerToken, useCases) {
         );
     router.route('/api/integrations/:integrationId/actions').all(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const params = checkRequiredParams(req.params, ['integrationId']);
             const integration = await getIntegrationInstance.execute(
                 params.integrationId,
@@ -352,9 +368,7 @@ function setIntegrationRoutes(router, getUserFromBearerToken, useCases) {
         .route('/api/integrations/:integrationId/actions/:actionId/options')
         .all(
             catchAsyncError(async (req, res) => {
-                const user = await getUserFromBearerToken.execute(
-                    req.headers.authorization
-                );
+                const user = await authenticateUser.execute(req);
                 const params = checkRequiredParams(req.params, [
                     'integrationId',
                     'actionId',
@@ -379,9 +393,7 @@ function setIntegrationRoutes(router, getUserFromBearerToken, useCases) {
         )
         .post(
             catchAsyncError(async (req, res) => {
-                const user = await getUserFromBearerToken.execute(
-                    req.headers.authorization
-                );
+                const user = await authenticateUser.execute(req);
                 const params = checkRequiredParams(req.params, [
                     'integrationId',
                     'actionId',
@@ -402,9 +414,7 @@ function setIntegrationRoutes(router, getUserFromBearerToken, useCases) {
 
     router.route('/api/integrations/:integrationId/actions/:actionId').post(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const params = checkRequiredParams(req.params, [
                 'integrationId',
                 'actionId',
@@ -419,9 +429,7 @@ function setIntegrationRoutes(router, getUserFromBearerToken, useCases) {
 
     router.route('/api/integrations/:integrationId').get(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
 
             if (!user) {
                 throw Boom.forbidden('User not found');
@@ -446,9 +454,7 @@ function setIntegrationRoutes(router, getUserFromBearerToken, useCases) {
 
     router.route('/api/integrations/:integrationId/test-auth').get(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const params = checkRequiredParams(req.params, ['integrationId']);
             const instance = await getIntegrationInstance.execute(
                 params.integrationId,
@@ -478,9 +484,9 @@ function setIntegrationRoutes(router, getUserFromBearerToken, useCases) {
 /**
  * Sets up entity-related routes for the integration router
  * @param {Object} router - Express router instance
- * @param {import('../user/use-cases/get-user-from-bearer-token').GetUserFromBearerToken} getUserFromBearerToken - Use case for retrieving a user from a bearer token
+ * @param {import('../user/use-cases/authenticate-user').AuthenticateUser} authenticateUser - Use case for multi-mode user authentication
  */
-function setEntityRoutes(router, getUserFromBearerToken, useCases) {
+function setEntityRoutes(router, authenticateUser, useCases) {
     const {
         getCredentialForUser,
         getModuleInstanceFromType,
@@ -494,9 +500,7 @@ function setEntityRoutes(router, getUserFromBearerToken, useCases) {
 
     router.route('/api/authorize').get(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const userId = user.getId();
             const params = checkRequiredParams(req.query, ['entityType']);
             const module = await getModuleInstanceFromType.execute(
@@ -517,9 +521,7 @@ function setEntityRoutes(router, getUserFromBearerToken, useCases) {
 
     router.route('/api/authorize').post(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const userId = user.getId();
             const params = checkRequiredParams(req.body, [
                 'entityType',
@@ -538,9 +540,7 @@ function setEntityRoutes(router, getUserFromBearerToken, useCases) {
 
     router.route('/api/entity').post(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const userId = user.getId();
             const params = checkRequiredParams(req.body, [
                 'entityType',
@@ -575,9 +575,7 @@ function setEntityRoutes(router, getUserFromBearerToken, useCases) {
 
     router.route('/api/entity/options/:credentialId').get(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const userId = user.getId();
             // TODO May want to pass along the user ID as well so credential ID's can't be fished???
             // TODO **flagging this for review** -MW
@@ -601,9 +599,7 @@ function setEntityRoutes(router, getUserFromBearerToken, useCases) {
 
     router.route('/api/entities/:entityId/test-auth').get(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const userId = user.getId();
             const params = checkRequiredParams(req.params, ['entityId']);
             const testAuthResponse = await testModuleAuth.execute(
@@ -630,9 +626,7 @@ function setEntityRoutes(router, getUserFromBearerToken, useCases) {
 
     router.route('/api/entities/:entityId').get(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const userId = user.getId();
             const params = checkRequiredParams(req.params, ['entityId']);
             const module = await getModule.execute(params.entityId, userId);
@@ -643,9 +637,7 @@ function setEntityRoutes(router, getUserFromBearerToken, useCases) {
 
     router.route('/api/entities/:entityId/options').post(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const userId = user.getId();
             const params = checkRequiredParams(req.params, ['entityId']);
 
@@ -660,9 +652,7 @@ function setEntityRoutes(router, getUserFromBearerToken, useCases) {
 
     router.route('/api/entities/:entityId/options/refresh').post(
         catchAsyncError(async (req, res) => {
-            const user = await getUserFromBearerToken.execute(
-                req.headers.authorization
-            );
+            const user = await authenticateUser.execute(req);
             const userId = user.getId();
             const params = checkRequiredParams(req.params, ['entityId']);
             const updatedOptions = await refreshEntityOptions.execute(

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

@@ -110,6 +110,18 @@ class IntegrationRepositoryInterface {
     async findIntegrationByUserId(userId) {
         throw new Error('Method findIntegrationByUserId must be implemented by subclass');
     }
+
+    /**
+     * Update integration configuration
+     *
+     * @param {string|number} integrationId - Integration ID
+     * @param {Object} config - Updated configuration object
+     * @returns {Promise<Object>} Updated integration object
+     * @abstract
+     */
+    async updateIntegrationConfig(integrationId, config) {
+        throw new Error('Method updateIntegrationConfig must be implemented by subclass');
+    }
 }
 
 module.exports = { IntegrationRepositoryInterface };

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

@@ -266,6 +266,38 @@ class IntegrationRepositoryMongo extends IntegrationRepositoryInterface {
             messages: integration.messages,
         };
     }
+
+    /**
+     * Update integration configuration
+     * Replaces: IntegrationModel.updateOne({ _id: integrationId }, { config })
+     *
+     * @param {string} integrationId - Integration ID (MongoDB ObjectId as string)
+     * @param {Object} config - Updated configuration object
+     * @returns {Promise<Object>} Updated integration object
+     */
+    async updateIntegrationConfig(integrationId, config) {
+        if (config === null || config === undefined) {
+            throw new Error('Config parameter is required');
+        }
+
+        const integration = await this.prisma.integration.update({
+            where: { id: integrationId },
+            data: { config },
+            include: {
+                entities: true,
+            },
+        });
+
+        return {
+            id: integration.id,
+            entitiesIds: integration.entities.map((e) => e.id),
+            userId: integration.userId,
+            config: integration.config,
+            version: integration.version,
+            status: integration.status,
+            messages: integration.messages,
+        };
+    }
 }
 
 module.exports = { IntegrationRepositoryMongo };

package/integrations/repositories/integration-repository-postgres.js

@@ -314,6 +314,39 @@ class IntegrationRepositoryPostgres extends IntegrationRepositoryInterface {
             messages: converted.messages,
         };
     }
+
+    /**
+     * Update integration configuration
+     *
+     * @param {string} integrationId - Integration ID (string from application layer)
+     * @param {Object} config - Updated configuration object
+     * @returns {Promise<Object>} Updated integration object with string IDs
+     */
+    async updateIntegrationConfig(integrationId, config) {
+        if (config === null || config === undefined) {
+            throw new Error('Config parameter is required');
+        }
+
+        const intId = this._convertId(integrationId);
+        const integration = await this.prisma.integration.update({
+            where: { id: intId },
+            data: { config },
+            include: {
+                entities: true,
+            },
+        });
+
+        const converted = this._convertIntegrationIds(integration);
+        return {
+            id: converted.id,
+            entitiesIds: converted.entities.map((e) => e.id),
+            userId: converted.userId,
+            config: converted.config,
+            version: converted.version,
+            status: converted.status,
+            messages: converted.messages,
+        };
+    }
 }
 
 module.exports = { IntegrationRepositoryPostgres };