@friggframework/core 2.0.0-next.44 → 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-postgres.js

@@ -1,5 +1,7 @@
 const { prisma } = require('../../database/prisma');
-const { ProcessRepositoryInterface } = require('./process-repository-interface');
+const {
+    ProcessRepositoryInterface,
+} = require('./process-repository-interface');
 
 /**
  * PostgreSQL Process Repository Adapter
@@ -22,6 +24,22 @@ class ProcessRepositoryPostgres extends ProcessRepositoryInterface {
         this.prisma = prisma;
     }
 
+    /**
+     * Convert string ID to integer for PostgreSQL queries
+     * @private
+     * @param {string|number|null|undefined} id - ID to convert
+     * @returns {number|null|undefined} Integer ID or null/undefined
+     * @throws {Error} If ID cannot be converted to integer
+     */
+    _convertId(id) {
+        if (id === null || id === undefined) return id;
+        const parsed = parseInt(id, 10);
+        if (isNaN(parsed)) {
+            throw new Error(`Invalid ID: ${id} cannot be converted to integer`);
+        }
+        return parsed;
+    }
+
     /**
      * Create a new process record
      * @param {Object} processData - Process data to create
@@ -30,15 +48,14 @@ class ProcessRepositoryPostgres extends ProcessRepositoryInterface {
     async create(processData) {
         const process = await this.prisma.process.create({
             data: {
-                userId: processData.userId,
-                integrationId: processData.integrationId,
+                userId: this._convertId(processData.userId),
+                integrationId: this._convertId(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,
+                parentProcessId: this._convertId(processData.parentProcessId),
             },
         });
 
@@ -52,7 +69,7 @@ class ProcessRepositoryPostgres extends ProcessRepositoryInterface {
      */
     async findById(processId) {
         const process = await this.prisma.process.findUnique({
-            where: { id: processId },
+            where: { id: this._convertId(processId) },
         });
 
         return process ? this._toPlainObject(process) : null;
@@ -77,15 +94,14 @@ class ProcessRepositoryPostgres extends ProcessRepositoryInterface {
         if (updates.results !== undefined) {
             updateData.results = updates.results;
         }
-        if (updates.childProcesses !== undefined) {
-            updateData.childProcesses = updates.childProcesses;
-        }
         if (updates.parentProcessId !== undefined) {
-            updateData.parentProcessId = updates.parentProcessId;
+            updateData.parentProcessId = this._convertId(
+                updates.parentProcessId
+            );
         }
 
         const process = await this.prisma.process.update({
-            where: { id: processId },
+            where: { id: this._convertId(processId) },
             data: updateData,
         });
 
@@ -101,7 +117,7 @@ class ProcessRepositoryPostgres extends ProcessRepositoryInterface {
     async findByIntegrationAndType(integrationId, type) {
         const processes = await this.prisma.process.findMany({
             where: {
-                integrationId,
+                integrationId: this._convertId(integrationId),
                 type,
             },
             orderBy: {
@@ -118,10 +134,13 @@ class ProcessRepositoryPostgres extends ProcessRepositoryInterface {
      * @param {string[]} [excludeStates=['COMPLETED', 'ERROR']] - States to exclude
      * @returns {Promise<Array>} Array of active process records
      */
-    async findActiveProcesses(integrationId, excludeStates = ['COMPLETED', 'ERROR']) {
+    async findActiveProcesses(
+        integrationId,
+        excludeStates = ['COMPLETED', 'ERROR']
+    ) {
         const processes = await this.prisma.process.findMany({
             where: {
-                integrationId,
+                integrationId: this._convertId(integrationId),
                 state: {
                     notIn: excludeStates,
                 },
@@ -157,7 +176,7 @@ class ProcessRepositoryPostgres extends ProcessRepositoryInterface {
      */
     async deleteById(processId) {
         await this.prisma.process.delete({
-            where: { id: processId },
+            where: { id: this._convertId(processId) },
         });
     }
 
@@ -179,11 +198,16 @@ class ProcessRepositoryPostgres extends ProcessRepositoryInterface {
             context: process.context,
             results: process.results,
             childProcesses: Array.isArray(process.childProcesses)
-                ? (process.childProcesses.length > 0 && typeof process.childProcesses[0] === 'object' && process.childProcesses[0] !== null
-                    ? process.childProcesses.map(child => String(child.id))
-                    : process.childProcesses)
+                ? process.childProcesses.length > 0 &&
+                  typeof process.childProcesses[0] === 'object' &&
+                  process.childProcesses[0] !== null
+                    ? process.childProcesses.map((child) => String(child.id))
+                    : process.childProcesses
                 : [],
-            parentProcessId: process.parentProcessId !== null ? String(process.parentProcessId) : null,
+            parentProcessId:
+                process.parentProcessId !== null
+                    ? String(process.parentProcessId)
+                    : null,
             createdAt: process.createdAt,
             updatedAt: process.updatedAt,
         };
@@ -191,4 +215,3 @@ class ProcessRepositoryPostgres extends ProcessRepositoryInterface {
 }
 
 module.exports = { ProcessRepositoryPostgres };
-

package/integrations/tests/doubles/dummy-integration-class.js

@@ -47,23 +47,16 @@ class DummyIntegration extends IntegrationBase {
         this.updateIntegrationMessages = {
             execute: jest.fn().mockResolvedValue({})
         };
-
-        this.registerEventHandlers();
     }
 
     async loadDynamicUserActions() {
         return {};
     }
 
-    async registerEventHandlers() {
-        super.registerEventHandlers();
-        return;
-    }
-
     async send(event, data) {
         this.sendSpy(event, data);
         this.eventCallHistory.push({ event, data, timestamp: Date.now() });
-        return super.send(event, data);
+        return { event, data };
     }
 
     async initialize() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@friggframework/core",
   "prettier": "@friggframework/prettier-config",
-  "version": "2.0.0-next.44",
+  "version": "2.0.0-next.45",
   "dependencies": {
     "@hapi/boom": "^10.0.1",
     "@prisma/client": "^6.16.3",
@@ -23,9 +23,9 @@
     "uuid": "^9.0.1"
   },
   "devDependencies": {
-    "@friggframework/eslint-config": "2.0.0-next.44",
-    "@friggframework/prettier-config": "2.0.0-next.44",
-    "@friggframework/test": "2.0.0-next.44",
+    "@friggframework/eslint-config": "2.0.0-next.45",
+    "@friggframework/prettier-config": "2.0.0-next.45",
+    "@friggframework/test": "2.0.0-next.45",
     "@types/lodash": "4.17.15",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "chai": "^4.3.6",
@@ -64,5 +64,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "87c8479d50810d28eb7dc73c347e0117d872273a"
+  "gitHead": "996a15bcdfaa4252b9891a33f1b1c84548d66bbc"
 }

package/queues/queuer-util.js

@@ -14,6 +14,16 @@ AWS.config.update(awsConfigOptions());
 const sqs = new AWS.SQS();
 
 const QueuerUtil = {
+    send: async (message, queueUrl) => {
+        console.log(`Enqueuing message to SQS queue ${queueUrl}`);
+        return sqs
+            .sendMessage({
+                MessageBody: JSON.stringify(message),
+                QueueUrl: queueUrl,
+            })
+            .promise();
+    },
+
     batchSend: async (entries = [], queueUrl) => {
         console.log(
             `Enqueuing ${entries.length} entries on SQS to queue ${queueUrl}`

package/user/repositories/user-repository-mongo.js

@@ -1,4 +1,4 @@
-//todo: this repository is tightly coupled to the token repository.
+const bcrypt = require('bcryptjs');
 const { prisma } = require('../../database/prisma');
 const {
     createTokenRepository,
@@ -95,19 +95,38 @@ class UserRepositoryMongo extends UserRepositoryInterface {
      * Replaces: IndividualUser.create(params)
      *
      * @param {Object} params - User creation parameters
+     * @param {string} [params.hashword] - Plain text password (will be bcrypt hashed automatically)
      * @returns {Promise<Object>} Created user object with string IDs
      */
     async createIndividualUser(params) {
-        return await this.prisma.user.create({
-            data: {
-                type: 'INDIVIDUAL',
-                email: params.email,
-                username: params.username,
-                hashword: params.hashword,
-                appUserId: params.appUserId,
-                organizationId: params.organization || params.organizationId,
-            },
-        });
+        const data = {
+            type: 'INDIVIDUAL',
+            email: params.email,
+            username: params.username,
+            appUserId: params.appUserId,
+            organizationId: params.organization || params.organizationId,
+        };
+
+        if (
+            params.hashword !== undefined &&
+            params.hashword !== null &&
+            params.hashword !== ''
+        ) {
+            if (typeof params.hashword !== 'string') {
+                throw new Error('Password must be a string');
+            }
+
+            // Prevent double-hashing: bcrypt hashes start with $2a$ or $2b$
+            if (params.hashword.startsWith('$2')) {
+                throw new Error(
+                    'Password appears to be already hashed. Pass plain text password only.'
+                );
+            }
+
+            data.hashword = await bcrypt.hash(params.hashword, 10);
+        }
+
+        return await this.prisma.user.create({ data });
     }
 
     /**
@@ -204,12 +223,34 @@ class UserRepositoryMongo extends UserRepositoryInterface {
      * Update individual user
      * @param {string} userId - User ID
      * @param {Object} updates - Fields to update
+     * @param {string} [updates.hashword] - Plain text password (will be bcrypt hashed automatically)
      * @returns {Promise<Object>} Updated user object with string IDs
      */
     async updateIndividualUser(userId, updates) {
+        const data = { ...updates };
+
+        if (
+            data.hashword !== undefined &&
+            data.hashword !== null &&
+            data.hashword !== ''
+        ) {
+            if (typeof data.hashword !== 'string') {
+                throw new Error('Password must be a string');
+            }
+
+            // Prevent double-hashing: bcrypt hashes start with $2a$ or $2b$
+            if (data.hashword.startsWith('$2')) {
+                throw new Error(
+                    'Password appears to be already hashed. Pass plain text password only.'
+                );
+            }
+
+            data.hashword = await bcrypt.hash(data.hashword, 10);
+        }
+
         return await this.prisma.user.update({
             where: { id: userId },
-            data: updates,
+            data,
         });
     }
 

package/user/repositories/user-repository-postgres.js

@@ -1,4 +1,4 @@
-//todo: this repository is tightly coupled to the token repository.
+const bcrypt = require('bcryptjs');
 const { prisma } = require('../../database/prisma');
 const {
     createTokenRepository,
@@ -130,21 +130,40 @@ class UserRepositoryPostgres extends UserRepositoryInterface {
      * Replaces: IndividualUser.create(params)
      *
      * @param {Object} params - User creation parameters (with string IDs from application layer)
+     * @param {string} [params.hashword] - Plain text password (will be bcrypt hashed automatically)
      * @returns {Promise<Object>} Created user object with string IDs
      */
     async createIndividualUser(params) {
-        const user = await this.prisma.user.create({
-            data: {
-                type: 'INDIVIDUAL',
-                email: params.email,
-                username: params.username,
-                hashword: params.hashword,
-                appUserId: params.appUserId,
-                organizationId: this._convertId(
-                    params.organization || params.organizationId
-                ),
-            },
-        });
+        const data = {
+            type: 'INDIVIDUAL',
+            email: params.email,
+            username: params.username,
+            appUserId: params.appUserId,
+            organizationId: this._convertId(
+                params.organization || params.organizationId
+            ),
+        };
+
+        if (
+            params.hashword !== undefined &&
+            params.hashword !== null &&
+            params.hashword !== ''
+        ) {
+            if (typeof params.hashword !== 'string') {
+                throw new Error('Password must be a string');
+            }
+
+            // Prevent double-hashing: bcrypt hashes start with $2a$ or $2b$
+            if (params.hashword.startsWith('$2')) {
+                throw new Error(
+                    'Password appears to be already hashed. Pass plain text password only.'
+                );
+            }
+
+            data.hashword = await bcrypt.hash(params.hashword, 10);
+        }
+
+        const user = await this.prisma.user.create({ data });
         return this._convertUserIds(user);
     }
 
@@ -249,13 +268,14 @@ class UserRepositoryPostgres extends UserRepositoryInterface {
      * Update individual user
      * @param {string} userId - User ID (string from application layer)
      * @param {Object} updates - Fields to update (with string IDs from application layer)
+     * @param {string} [updates.hashword] - Plain text password (will be bcrypt hashed automatically)
      * @returns {Promise<Object>} Updated user object with string IDs
      */
     async updateIndividualUser(userId, updates) {
         const intId = this._convertId(userId);
 
-        // Convert organizationId if present in updates
         const data = { ...updates };
+
         if (data.organizationId !== undefined) {
             data.organizationId = this._convertId(data.organizationId);
         }
@@ -264,6 +284,25 @@ class UserRepositoryPostgres extends UserRepositoryInterface {
             delete data.organization;
         }
 
+        if (
+            data.hashword !== undefined &&
+            data.hashword !== null &&
+            data.hashword !== ''
+        ) {
+            if (typeof data.hashword !== 'string') {
+                throw new Error('Password must be a string');
+            }
+
+            // Prevent double-hashing: bcrypt hashes start with $2a$ or $2b$
+            if (data.hashword.startsWith('$2')) {
+                throw new Error(
+                    'Password appears to be already hashed. Pass plain text password only.'
+                );
+            }
+
+            data.hashword = await bcrypt.hash(data.hashword, 10);
+        }
+
         const user = await this.prisma.user.update({
             where: { id: intId },
             data,