@friggframework/core 2.0.0--canary.550.b8b9a2b.0 → 2.0.0--canary.545.e256e95.0

package/handlers/WEBHOOKS.md

@@ -5,31 +5,36 @@ This document explains how to implement webhook handling for your Frigg integrat
 ## Overview
 
 Frigg provides a scalable webhook architecture that:
-- **Receives webhooks without database connections** for fast response times
-- **Queues webhooks to SQS** for async processing
-- **Processes webhooks with fully hydrated integrations** (with DB and API modules loaded)
-- **Supports custom signature verification** for security
-- **Throttles database connections** using SQS to handle webhook bursts
+
+-   **Receives webhooks without database connections** for fast response times
+-   **Queues webhooks to SQS** for async processing
+-   **Processes webhooks with fully hydrated integrations** (with DB and API modules loaded)
+-   **Supports custom signature verification** for security
+-   **Throttles database connections** using SQS to handle webhook bursts
 
 ## Architecture
 
 The webhook flow consists of two stages:
 
 ### Stage 1: HTTP Webhook Receiver (No DB)
+
 ```
 Webhook → Lambda → WEBHOOK_RECEIVED event → Queue to SQS → 200 OK Response
 ```
-- Fast response (no database query)
-- Optional signature verification
-- Messages queued for processing
+
+-   Fast response (no database query)
+-   Optional signature verification
+-   Messages queued for processing
 
 ### Stage 2: Queue Worker (DB-Connected)
+
 ```
 SQS Queue → Lambda Worker → ON_WEBHOOK event → Process with hydrated integration
 ```
-- Full database access
-- API modules loaded
-- Can use integration context
+
+-   Full database access
+-   API modules loaded
+-   Can use integration context
 
 ## Enabling Webhooks
 
@@ -59,7 +64,9 @@ class MyIntegration extends IntegrationBase {
     static Definition = {
         name: 'my-integration',
         version: '1.0.0',
-        modules: { /* ... */ },
+        modules: {
+            /* ... */
+        },
         webhooks: {
             enabled: true,
             // Future options will be added here
@@ -73,20 +80,24 @@ class MyIntegration extends IntegrationBase {
 When webhooks are enabled, two routes are automatically created:
 
 ### General Webhook
+
 ```
 POST /api/{integrationName}-integration/webhooks
 ```
-- No integration ID required
-- Useful for system-wide events
-- Creates unhydrated integration instance
+
+-   No integration ID required
+-   Useful for system-wide events
+-   Creates unhydrated integration instance
 
 ### Integration-Specific Webhook
+
 ```
 POST /api/{integrationName}-integration/webhooks/:integrationId
 ```
-- Includes integration ID in URL
-- Worker loads full integration with DB and modules
-- Recommended for most use cases
+
+-   Includes integration ID in URL
+-   Worker loads full integration with DB and modules
+-   Recommended for most use cases
 
 ## Event Handlers
 
@@ -95,6 +106,7 @@ POST /api/{integrationName}-integration/webhooks/:integrationId
 Triggered when a webhook HTTP request is received (no database connection).
 
 #### Default Behavior
+
 Queues the webhook to SQS and responds with `200 OK`:
 
 ```javascript
@@ -125,7 +137,7 @@ class MyIntegration extends IntegrationBase {
         // Verify webhook signature
         const signature = req.headers['x-webhook-signature'];
         const expectedSignature = this.calculateSignature(req.body);
-        
+
         if (signature !== expectedSignature) {
             return res.status(401).json({ error: 'Invalid signature' });
         }
@@ -156,6 +168,7 @@ class MyIntegration extends IntegrationBase {
 Triggered by the queue worker (with database connection and hydrated integration).
 
 #### Default Behavior
+
 Logs the webhook data (override this!):
 
 ```javascript
@@ -262,27 +275,26 @@ class SlackIntegration extends IntegrationBase {
         const crypto = require('crypto');
         const signingSecret = process.env.SLACK_SIGNING_SECRET;
         const timestamp = req.headers['x-slack-request-timestamp'];
-        
+
         // Validate timestamp is recent (within 5 minutes)
         const currentTime = Math.floor(Date.now() / 1000);
         if (Math.abs(currentTime - parseInt(timestamp)) > 300) {
             return false; // Request is older than 5 minutes
         }
-        
+
         const hmac = crypto.createHmac('sha256', signingSecret);
         hmac.update(`v0:${timestamp}:${JSON.stringify(req.body)}`);
         const expected = `v0=${hmac.digest('hex')}`;
-        
+
         // Check lengths first to avoid errors in timingSafeEqual
-        const expectedBuffer = Buffer.from(expected)
-        const signatureBuffer = Buffer.from(signature)
-        
+        const expectedBuffer = Buffer.from(expected);
+        const signatureBuffer = Buffer.from(signature);
+
         if (expectedBuffer.length !== signatureBuffer.length) {
-            return false
+            return false;
         }
-        
-        return crypto.timingSafeEqual(expectedBuffer, signatureBuffer)
 
+        return crypto.timingSafeEqual(expectedBuffer, signatureBuffer);
     }
 }
 ```
@@ -445,6 +457,7 @@ describe('MyIntegration Webhooks', () => {
 ## Best Practices
 
 ### 1. Always Verify Signatures
+
 ```javascript
 async onWebhookReceived({ req, res }) {
     // Verify before queueing
@@ -457,14 +470,17 @@ async onWebhookReceived({ req, res }) {
 ```
 
 ### 2. Respond Quickly
+
 The `WEBHOOK_RECEIVED` handler should complete in < 3 seconds:
-- Verify signature
-- Queue message
-- Return 200 OK
+
+-   Verify signature
+-   Queue message
+-   Return 200 OK
 
 Heavy processing goes in `ON_WEBHOOK`.
 
 ### 3. Handle Idempotency
+
 ```javascript
 async onWebhook({ data }) {
     const { body } = data;
@@ -484,6 +500,7 @@ async onWebhook({ data }) {
 ```
 
 ### 4. Error Handling
+
 ```javascript
 async onWebhook({ data }) {
     try {
@@ -491,7 +508,7 @@ async onWebhook({ data }) {
     } catch (error) {
         // Log error - message will go to DLQ after retries
         console.error('Webhook processing failed:', error);
-        
+
         // Update integration status if needed
         await this.updateIntegrationMessages.execute(
             this.id,
@@ -500,7 +517,7 @@ async onWebhook({ data }) {
             error.message,
             Date.now()
         );
-        
+
         throw error; // Re-throw for retry/DLQ
     }
 }
@@ -513,18 +530,20 @@ async onWebhook({ data }) {
 When `webhooks: true` is set, the Frigg infrastructure automatically creates:
 
 1. **HTTP Lambda Function**
-   - Handler: `integration-webhook-routers.js`
-   - No database connection
-   - Fast cold start
+
+    - Handler: `integration-webhook-routers.js`
+    - No database connection
+    - Fast cold start
 
 2. **Webhook Routes**
-   - `POST /api/{name}-integration/webhooks`
-   - `POST /api/{name}-integration/webhooks/:integrationId`
 
-3. **Queue Worker**  
-   - Processes from existing integration queue
-   - Handles `ON_WEBHOOK` events
-   - Full database access
+    - `POST /api/{name}-integration/webhooks`
+    - `POST /api/{name}-integration/webhooks/:integrationId`
+
+3. **Queue Worker**
+    - Processes from existing integration queue
+    - Handles `ON_WEBHOOK` events
+    - Full database access
 
 ### Serverless Configuration (Automatic)
 
@@ -532,22 +551,22 @@ The following is generated automatically in `serverless.yml`:
 
 ```yaml
 functions:
-  myintegrationWebhook:
-    handler: node_modules/@friggframework/core/handlers/routers/integration-webhook-routers.handlers.myintegrationWebhook.handler
-    events:
-      - httpApi:
-          path: /api/myintegration-integration/webhooks
-          method: POST
-      - httpApi:
-          path: /api/myintegration-integration/webhooks/{integrationId}
-          method: POST
-
-  myintegrationQueueWorker:
-    handler: node_modules/@friggframework/core/handlers/workers/integration-defined-workers.handlers.myintegration.queueWorker
-    events:
-      - sqs:
-          arn: !GetAtt MyintegrationQueue.Arn
-          batchSize: 1
+    myintegrationWebhook:
+        handler: node_modules/@friggframework/core/handlers/routers/integration-webhook-routers.handlers.myintegrationWebhook.handler
+        events:
+            - httpApi:
+                  path: /api/myintegration-integration/webhooks
+                  method: POST
+            - httpApi:
+                  path: /api/myintegration-integration/webhooks/{integrationId}
+                  method: POST
+
+    myintegrationQueueWorker:
+        handler: node_modules/@friggframework/core/handlers/workers/integration-defined-workers.handlers.myintegration.queueWorker
+        events:
+            - sqs:
+                  arn: !GetAtt MyintegrationQueue.Arn
+                  batchSize: 1
 ```
 
 ## Event Handler Reference
@@ -560,13 +579,14 @@ functions:
 **Must:** Respond to `res` with status code
 
 **Parameters:**
-- `req` - Express request object
-  - `req.body` - Webhook payload
-  - `req.params.integrationId` - Integration ID (if in URL)
-  - `req.headers` - HTTP headers
-  - `req.query` - Query parameters
-- `res` - Express response object
-  - Call `res.status(code).json(data)` to respond
+
+-   `req` - Express request object
+    -   `req.body` - Webhook payload
+    -   `req.params.integrationId` - Integration ID (if in URL)
+    -   `req.headers` - HTTP headers
+    -   `req.query` - Query parameters
+-   `res` - Express response object
+    -   Call `res.status(code).json(data)` to respond
 
 ### onWebhook({ data, context })
 
@@ -576,12 +596,13 @@ functions:
 **Can:** Use `this.modules`, `this.config`, DB operations
 
 **Parameters:**
-- `data` - Queued webhook data
-  - `data.integrationId` - Integration ID (if provided)
-  - `data.body` - Original webhook payload
-  - `data.headers` - Original HTTP headers
-  - `data.query` - Original query parameters
-- `context` - Lambda context object
+
+-   `data` - Queued webhook data
+    -   `data.integrationId` - Integration ID (if provided)
+    -   `data.body` - Original webhook payload
+    -   `data.headers` - Original HTTP headers
+    -   `data.query` - Original query parameters
+-   `context` - Lambda context object
 
 ## Queue Helper
 
@@ -608,6 +629,7 @@ Automatically uses the correct SQS queue URL based on integration name.
 **Error:** `Queue URL not found for {NAME}_QUEUE_URL`
 
 **Solution:** Ensure environment variable is set:
+
 ```bash
 export MY_INTEGRATION_QUEUE_URL=https://sqs.us-east-1.amazonaws.com/...
 ```
@@ -615,6 +637,7 @@ export MY_INTEGRATION_QUEUE_URL=https://sqs.us-east-1.amazonaws.com/...
 ### Webhook Not Responding
 
 **Check:**
+
 1. Is `webhooks: true` in Definition?
 2. Is webhook endpoint deployed?
 3. Are you sending POST requests?
@@ -623,6 +646,7 @@ export MY_INTEGRATION_QUEUE_URL=https://sqs.us-east-1.amazonaws.com/...
 ### Worker Not Processing
 
 **Check:**
+
 1. Is SQS queue receiving messages?
 2. Is queue worker Lambda function deployed?
 3. Check CloudWatch logs for worker errors
@@ -638,16 +662,15 @@ export MY_INTEGRATION_QUEUE_URL=https://sqs.us-east-1.amazonaws.com/...
 
 ## Performance
 
-- **HTTP Response:** < 100ms (signature check + queue)
-- **Worker Processing:** Based on your logic
-- **Concurrency:** Controlled by SQS worker `reservedConcurrency: 5`
-- **Burst Handling:** Unlimited HTTP, throttled processing
+-   **HTTP Response:** < 100ms (signature check + queue)
+-   **Worker Processing:** Based on your logic
+-   **Concurrency:** Controlled by SQS worker `reservedConcurrency: 5`
+-   **Burst Handling:** Unlimited HTTP, throttled processing
 
 ## Related Files
 
-- `packages/core/integrations/integration-base.js` - Event definitions and default handlers
-- `packages/core/handlers/routers/integration-webhook-routers.js` - HTTP webhook routes
-- `packages/core/handlers/backend-utils.js` - Queue worker with hydration logic
-- `packages/core/handlers/integration-event-dispatcher.js` - Event dispatching
-- `packages/devtools/infrastructure/serverless-template.js` - Automatic infrastructure generation
-
+-   `packages/core/integrations/integration-base.js` - Event definitions and default handlers
+-   `packages/core/handlers/routers/integration-webhook-routers.js` - HTTP webhook routes
+-   `packages/core/handlers/backend-utils.js` - Queue worker with hydration logic
+-   `packages/core/handlers/integration-event-dispatcher.js` - Event dispatching
+-   `packages/devtools/infrastructure/serverless-template.js` - Automatic infrastructure generation

package/handlers/app-definition-loader.js

@@ -3,18 +3,60 @@ const path = require('node:path');
 const fs = require('fs-extra');
 
 /**
- * Loads the App definition from the nearest backend package
+ * Cached app definition, set via setAppDefinition().
+ * When set, loadAppDefinition() returns this instead of discovering
+ * the backend via process.cwd().
+ */
+let cachedAppDefinition = null;
+
+/**
+ * Pre-set the app definition so loadAppDefinition() can return it
+ * without needing process.cwd()-based discovery.
+ *
+ * This is critical for platforms like Netlify where:
+ * - nft/esbuild traces static require() calls to determine bundle contents
+ * - process.cwd() at runtime points to /var/task/, not the backend directory
+ * - The caller can use a static require('../../backend/index.js') to make
+ *   the backend traceable, then pass the definition here
+ *
+ * @param {Object} definition - The app definition object (backend's Definition export)
+ */
+function setAppDefinition(definition) {
+    cachedAppDefinition = definition;
+}
+
+/**
+ * Loads the App definition from the nearest backend package.
+ *
+ * If setAppDefinition() was called, returns the cached definition
+ * immediately (no filesystem discovery needed).
+ *
+ * Otherwise, discovers the backend via process.cwd() traversal.
+ *
+ * Returns the full appDefinition object plus convenience destructured fields
+ * for backward compatibility (integrations, userConfig).
+ *
  * @function loadAppDefinition
- * @description Searches for the nearest backend package.json, loads the corresponding index.js file,
- * and extracts the application definition containing integrations and user configuration.
- * @returns {{integrations: Array<object>, userConfig: object | null}} An object containing the application definition.
- * @throws {Error} Throws error if backend package.json cannot be found.
- * @throws {Error} Throws error if index.js file cannot be found in the backend directory.
+ * @returns {{
+ *   integrations: Array<object>,
+ *   userConfig: object | null,
+ *   appDefinition: object
+ * }}
+ * @throws {Error} If backend package.json or index.js cannot be found.
  * @example
- * const { integrations, userConfig } = loadAppDefinition();
- * console.log(`Found ${integrations.length} integrations`);
+ *   // Existing callers still work:
+ *   const { integrations, userConfig } = loadAppDefinition();
+ *
+ *   // New callers can access the full definition:
+ *   const { appDefinition } = loadAppDefinition();
+ *   console.log(appDefinition.provider); // 'aws' | 'netlify'
  */
 function loadAppDefinition() {
+    if (cachedAppDefinition) {
+        const { integrations = [], user: userConfig = null } = cachedAppDefinition;
+        return { integrations, userConfig, appDefinition: cachedAppDefinition };
+    }
+
     const backendPath = findNearestBackendPackageJson();
     if (!backendPath) {
         throw new Error('Could not find backend package.json');
@@ -30,9 +72,10 @@ function loadAppDefinition() {
     const appDefinition = backendJsFile.Definition;
 
     const { integrations = [], user: userConfig = null } = appDefinition;
-    return { integrations, userConfig };
+    return { integrations, userConfig, appDefinition };
 }
 
 module.exports = {
     loadAppDefinition,
-}; 
+    setAppDefinition,
+};

package/handlers/app-handler-helpers.js

@@ -3,6 +3,7 @@ const express = require('express');
 const bodyParser = require('body-parser');
 const cors = require('cors');
 const Boom = require('@hapi/boom');
+const loadUserManager = require('./routers/middleware/loadUser');
 const serverlessHttp = require('serverless-http');
 
 const createApp = (applyMiddleware) => {
@@ -19,6 +20,8 @@ const createApp = (applyMiddleware) => {
         })
     );
 
+    app.use(loadUserManager);
+
     if (applyMiddleware) applyMiddleware(app);
 
     // Handle sending error response and logging server errors to console
@@ -32,7 +35,6 @@ const createApp = (applyMiddleware) => {
             flushDebugLog(boomError);
             res.status(statusCode).json({ error: 'Internal Server Error' });
         } else {
-            console.warn(`[Frigg] ${req.method} ${req.path} -> ${statusCode}: ${err.message}`);
             res.status(statusCode).json({ error: err.message });
         }
     });
@@ -40,9 +42,18 @@ const createApp = (applyMiddleware) => {
     return app;
 };
 
-function createAppHandler(eventName, router, shouldUseDatabase = true) {
+function createAppHandler(
+    eventName,
+    router,
+    shouldUseDatabase = true,
+    basePath = null
+) {
     const app = createApp((app) => {
-        app.use(router);
+        if (basePath) {
+            app.use(basePath, router);
+        } else {
+            app.use(router);
+        }
     });
     return createHandler({
         eventName,

package/handlers/backend-utils.js

@@ -88,16 +88,9 @@ const loadIntegrationForWebhook = async (integrationId) => {
         moduleFactory,
     });
 
-    let integrationRecord;
-    try {
-        integrationRecord =
-            await integrationRepository.findIntegrationById(integrationId);
-    } catch (error) {
-        if (error.message?.includes('not found')) {
-            return null;
-        }
-        throw error;
-    }
+    const integrationRecord = await integrationRepository.findIntegrationById(
+        integrationId
+    );
 
     const instance = await getIntegrationInstance.execute(
         integrationId,
@@ -108,7 +101,6 @@ const loadIntegrationForWebhook = async (integrationId) => {
 };
 
 const loadIntegrationForProcess = async (processId, integrationClass) => {
-
     const { processRepository, integrationRepository, moduleRepository } =
         initializeRepositories();
 
@@ -158,12 +150,6 @@ const createQueueWorker = (integrationClass) => {
                     integrationInstance = await loadIntegrationForWebhook(
                         params.data.integrationId
                     );
-                    if (!integrationInstance) {
-                        console.warn(
-                            `[${integrationClass.Definition.name}] Integration ${params.data.integrationId} no longer exists. Discarding ${params.event} message.`
-                        );
-                        return;
-                    }
                 } else {
                     // Instantiates a DRY integration class without database records.
                     // There will be cases where we need to use helpers that the api modules can export.