@friggframework/core 2.0.0--canary.590.c1af198.0 → 2.0.0--canary.596.97a5c6b.0

package/application/commands/integration-commands.js

@@ -31,7 +31,8 @@ const ERROR_CODE_MAP = {
     ENTITY_NOT_FOUND: 401,
     ENTITY_USER_NOT_FOUND: 401,
     INTEGRATION_NOT_FOUND: 404,
-    EXTERNAL_ENTITY_ID_REQUIRED: 400,
+    EXTERNAL_ID_REQUIRED: 400,
+    TYPE_REQUIRED: 400,
     INTEGRATION_RECORD_NOT_FOUND: 404,
 };
 
@@ -101,14 +102,20 @@ function createIntegrationCommands({ integrationClass }) {
     });
 
     return {
-        async findIntegrationContextByExternalEntityId(externalEntityId) {
+        /**
+         * Find integration context by external entity ID and type
+         * @param {Object} params
+         * @param {string} params.externalId - External ID of the entity
+         * @param {string} params.type - Integration type (config.type)
+         * @returns {Promise<Object>} Integration context, entity, and record
+         */
+        async findIntegrationContextByExternalEntityId({ externalId, type }) {
             try {
-                const { context } = await findByExternalEntityIdUseCase.execute(
-                    {
-                        externalEntityId,
-                    }
-                );
-                return { context };
+                const result = await findByExternalEntityIdUseCase.execute({
+                    externalId,
+                    type,
+                });
+                return result;
             } catch (error) {
                 return mapErrorToResponse(error);
             }
@@ -250,11 +257,12 @@ function createIntegrationCommands({ integrationClass }) {
 
 async function findIntegrationContextByExternalEntityId({
     integrationClass,
-    externalEntityId,
+    externalId,
+    type,
 } = {}) {
     const commands = createIntegrationCommands({ integrationClass });
 
-    return commands.findIntegrationContextByExternalEntityId(externalEntityId);
+    return commands.findIntegrationContextByExternalEntityId({ externalId, type });
 }
 
 module.exports = {

package/core/create-handler.js

@@ -49,6 +49,7 @@ const createHandler = (optionByName = {}) => {
         eventName = 'Event',
         isUserFacingResponse = true,
         method,
+        shouldUseDatabase = true,
     } = optionByName;
 
     if (!method) {
@@ -79,6 +80,15 @@ const createHandler = (optionByName = {}) => {
             // If enabled (i.e. if SECRET_ARN is set in process.env) Fetch secrets from AWS Secrets Manager, and set them as environment variables.
             await secretsToEnv();
 
+            // Open the database connection up front when the handler needs it.
+            // Lazy-required so DB-free handlers (e.g. extension webhook
+            // receivers with useDatabase:false) never load the Prisma client.
+            // $connect is idempotent, so this safely reuses a warm connection.
+            if (shouldUseDatabase) {
+                const { connectPrisma } = require('../database/prisma');
+                await connectPrisma();
+            }
+
             // Helps reuse the database connection.  Lowers response times.
             context.callbackWaitsForEmptyEventLoop = false;
 

package/handlers/routers/health.js

@@ -511,6 +511,10 @@ router.get('/health/ready', async (_req, res) => {
     });
 });
 
-const handler = createAppHandler('HTTP Event: Health', router);
+// shouldUseDatabase: false — health must NOT eagerly open a DB connection.
+// /health/live is a pure liveness probe (no DB), and /health/ready probes the
+// DB itself and degrades to 503 gracefully. Eager-connect at handler entry
+// would turn a DB outage into a 500 for both (killing healthy containers).
+const handler = createAppHandler('HTTP Event: Health', router, false);
 
 module.exports = { handler, router };

package/handlers/routers/integration-defined-routers.js

@@ -12,6 +12,9 @@ const { integrations: integrationClasses } = loadAppDefinition();
 
 const routeKey = (method, path) => `${(method || 'ANY').toUpperCase()} ${path}`;
 
+// Serverless function keys must be alphanumeric; binding keys are developer-chosen.
+const sanitizeBindingKey = (name) => String(name).replace(/[^A-Za-z0-9]/g, '');
+
 //todo: this should be in a use case class
 for (const IntegrationClass of integrationClasses) {
     const router = Router();
@@ -53,20 +56,32 @@ for (const IntegrationClass of integrationClasses) {
         }
     }
 
-    // Tier 3 Integration Extension routes — see EXTENSIONS.md
+    // Tier 3 Integration Extension routes — each binding gets a dedicated
+    // handler, namespaced under /{bindingName}, so multiple modules' extensions
+    // can declare the same relative path (e.g. two /webhooks) without colliding.
+    // Each per-binding handler carries its own shouldUseDatabase (resolved from
+    // the extension/binding `useDatabase`, default false → DB-free receiver).
+    const bindingGroups = new Map();
     for (const extRoute of getExtensionRoutes(IntegrationClass)) {
+        const namespacedPath = `/${extRoute.bindingName}${extRoute.path}`;
         claim(
             extRoute.method,
-            extRoute.path,
+            namespacedPath,
             `extension "${extRoute.extensionName}" (binding "${extRoute.bindingName}")`
         );
-        router.use(
-            basePath,
+        if (!bindingGroups.has(extRoute.bindingName)) {
+            bindingGroups.set(extRoute.bindingName, {
+                router: Router(),
+                useDatabase: extRoute.useDatabase,
+            });
+        }
+        const group = bindingGroups.get(extRoute.bindingName);
+        group.router.use(
+            `${basePath}/${extRoute.bindingName}`,
             loadRouterFromObject(IntegrationClass, extRoute)
         );
-        const method = extRoute.method.toUpperCase();
         console.log(
-            `│ ${method} ${basePath}${extRoute.path}  (extension: ${extRoute.extensionName})`
+            `│ ${extRoute.method.toUpperCase()} ${basePath}/${extRoute.bindingName}${extRoute.path}  (extension: ${extRoute.extensionName}, useDatabase: ${extRoute.useDatabase})`
         );
     }
     console.log('│');
@@ -77,6 +92,33 @@ for (const IntegrationClass of integrationClasses) {
             router
         ),
     };
+
+    for (const [bindingName, group] of bindingGroups) {
+        // The function key is the wire contract with the devtools serverless
+        // generator (integration-builder.js builds the identical key). Keep
+        // the derivation here and there IN SYNC.
+        const fnKey = `${IntegrationClass.Definition.name}__${sanitizeBindingKey(
+            bindingName
+        )}`;
+        // Two binding keys that sanitize to the same value (e.g. "hub-spot"
+        // and "hubspot") would silently overwrite each other's handler. The
+        // namespaced-path claim() above can't catch it (the paths differ), so
+        // fail loud here.
+        if (Object.prototype.hasOwnProperty.call(handlers, fnKey)) {
+            throw new Error(
+                `Integration "${IntegrationClass.Definition.name}" extension handler conflict: ` +
+                    `binding "${bindingName}" sanitizes to "${fnKey}", which is already taken. ` +
+                    `Use binding keys that are distinct after stripping non-alphanumeric characters.`
+            );
+        }
+        handlers[fnKey] = {
+            handler: createAppHandler(
+                `HTTP Event: ${IntegrationClass.Definition.name} extension ${bindingName}`,
+                group.router,
+                group.useDatabase
+            ),
+        };
+    }
 }
 
 module.exports = { handlers };

package/integrations/EXTENSIONS.md

@@ -24,6 +24,8 @@ class HubSpotIntegration extends IntegrationBase {
             hubspotWebhooks: {
                 extension: hubspot.extensions.webhooks,
                 handlers: { HUBSPOT_WEBHOOK: 'onHubSpotEvent' },
+                // optional: override the extension's declared useDatabase
+                // useDatabase: true,
             },
         },
     };
@@ -39,19 +41,42 @@ class HubSpotIntegration extends IntegrationBase {
 }
 ```
 
-The binding key (`hubspotWebhooks`) is your local name. The extension reference (`hubspot.extensions.webhooks`) is whatever the API module exports.
+The binding key (`hubspotWebhooks`) is your local name. It is also the **URL namespace** for the extension's routes (see below), so pick something readable — `hubspot` yields a cleaner URL than `hubspotWebhooks`. The extension reference (`hubspot.extensions.webhooks`) is whatever the API module exports.
 
 ## Step 2: Deploy
 
-The framework auto-mounts each extension's routes at the integration's base path. Boot logs show:
+Each extension binding is mounted under its **binding key**, on its own dedicated handler/Lambda function. This means two modules' extensions (e.g. a HubSpot and a Clockwork webhooks extension on the same integration) never collide — each lives at a distinct namespaced path. Boot logs show:
 
 ```
 │ Configuring routes for hubspot Integration:
-│ POST /api/hubspot-integration/webhooks  (extension: hubspot-webhooks)
+│ POST /api/hubspot-integration/hubspotWebhooks/webhooks  (extension: hubspot-webhooks, useDatabase: false)
 │
 ```
 
-Hit that URL and the bound method (`onHubSpotEvent`) fires on the resolved per-account integration instance.
+So the full URL is `/api/{integration-name}-integration/{bindingKey}{route.path}`. Register that URL with the upstream provider (e.g. paste it into your HubSpot app's webhook settings). Hit it and the bound method (`onHubSpotEvent`) fires on the resolved per-account integration instance.
+
+> **⚠️ Breaking:** extension routes used to mount un-namespaced (`/api/{x}-integration/webhooks`). They are now namespaced under the binding key. Any provider webhook already registered against the old path must be re-pointed at the new `/{bindingKey}` URL — and for signature schemes that sign the full URL (e.g. HubSpot v3), the old registration will also fail verification until updated.
+
+## `useDatabase` — does the receiver open a DB connection?
+
+Each extension declares whether its route handler should open a database connection:
+
+```javascript
+// in the extension bundle (api-module side)
+module.exports = {
+    name: 'hubspot-webhooks',
+    useDatabase: false,   // default — the receiver is DB-free
+    routes: [ /* ... */ ],
+    events: { /* ... */ },
+};
+```
+
+- **Default is `false`** — a webhook receiver that only verifies a signature and enqueues should not pay for a DB connection (faster cold start; at build time its Lambda doesn't get the Prisma layer).
+- Set `useDatabase: true` at the **extension level** if the receiver itself needs the DB. A binding may override it locally (`extensions: { x: { extension, useDatabase: true } }`), though that's rarely needed.
+- Resolution order: `binding.useDatabase ?? extension.useDatabase ?? false`.
+- Scope note: `false` is the default **for extension routes**. `createHandler` itself still defaults `shouldUseDatabase: true` for the integration's own catch-all handler and the legacy `Definition.webhooks: true` path — those connect as before. The `false` default applies only to the per-binding extension handler.
+
+If `useDatabase` is `false`, the receiver must not touch the database. Work that needs the DB (e.g. resolving `portalId → integrationId`) belongs in the queue worker that processes the dispatched event, not in the receiver.
 
 ## How handler binding works
 
@@ -84,7 +109,7 @@ This means **binding the same extension twice only works if the extension itself
 
 Subclass overrides via `this.events[eventName]` (set in the constructor) take precedence over extension-declared events. If a binding tried to wire a handler that's now shadowed, the framework logs a warning naming the integration, binding, and ignored method.
 
-Route path conflicts (two extensions declaring the same `method + path`, or an extension colliding with a `Definition.routes` entry) also throw at boot.
+**Routes do not collide across bindings** — each binding's routes are namespaced under its binding key (`/{bindingKey}{route.path}`), so two extensions can both declare `POST /webhooks` and live at distinct URLs. A route conflict only throws at boot if a *single* binding declares two routes with the same `method + path` (or a `Definition.routes` entry exactly matches an extension's namespaced path). Note this is independent of event-name conflicts above: namespacing disambiguates URLs, but two bindings still must use distinct **event** names since events are merged into one `this.events` map.
 
 ## Authoring an extension (for API module authors)
 

package/integrations/extension.js

@@ -70,6 +70,24 @@ function validateExtensionBinding(extension, bindingName, integrationName, bindi
         throw new Error(`${ctx}: extension is missing required "name" field`);
     }
 
+    if (
+        extension.useDatabase !== undefined &&
+        typeof extension.useDatabase !== 'boolean'
+    ) {
+        throw new Error(
+            `${ctx}: extension "${extension.name}" "useDatabase" must be a boolean`
+        );
+    }
+    if (
+        binding &&
+        binding.useDatabase !== undefined &&
+        typeof binding.useDatabase !== 'boolean'
+    ) {
+        throw new Error(
+            `${ctx}: binding "useDatabase" must be a boolean`
+        );
+    }
+
     const events = extension.events || {};
     if (typeof events !== 'object' || Array.isArray(events)) {
         throw new Error(
@@ -181,6 +199,10 @@ function getExtensionRoutes(IntegrationClass) {
             integrationName,
             binding
         );
+        // useDatabase is resolved at the binding level, falling back to the
+        // extension's declared value, then to false (DB-free by default).
+        const useDatabase =
+            binding.useDatabase ?? binding.extension.useDatabase ?? false;
         const routes = binding.extension.routes || [];
         for (const route of routes) {
             flat.push({
@@ -189,6 +211,7 @@ function getExtensionRoutes(IntegrationClass) {
                 path: route.path,
                 method: route.method,
                 event: route.event,
+                useDatabase,
             });
         }
     }

package/integrations/use-cases/find-integration-context-by-external-entity-id.js

@@ -19,39 +19,43 @@ class FindIntegrationContextByExternalEntityIdUseCase {
         this.loadIntegrationContextUseCase = loadIntegrationContextUseCase;
     }
 
-    async execute({ externalEntityId }) {
-        if (!externalEntityId) {
-            const error = new Error('externalEntityId is required');
-            error.code = 'EXTERNAL_ENTITY_ID_REQUIRED';
+    async execute({ externalId, type }) {
+        if (!externalId) {
+            const error = new Error('externalId is required');
+            error.code = 'EXTERNAL_ID_REQUIRED';
+            throw error;
+        }
+
+        if (!type) {
+            const error = new Error('type is required');
+            error.code = 'TYPE_REQUIRED';
             throw error;
         }
 
         const entity = await this.moduleRepository.findEntity({
-            externalId: externalEntityId,
+            externalId,
         });
 
         if (!entity) {
             const error = new Error(
-                `Entity not found for externalId: ${externalEntityId}`
+                `Entity not found for externalId: ${externalId}`
             );
             error.code = 'ENTITY_NOT_FOUND';
             throw error;
         }
 
-        if (!entity.userId) {
-            const error = new Error('Entity does not have an associated user');
-            error.code = 'ENTITY_USER_NOT_FOUND';
-            throw error;
-        }
-
-        const integrationRecord =
-            await this.integrationRepository.findIntegrationByUserId(
-                entity.userId
+        const integrations =
+            await this.integrationRepository.findIntegrationsByEntityId(
+                entity.id
             );
 
+        const integrationRecord = integrations?.find(
+            (i) => i.config?.type === type
+        );
+
         if (!integrationRecord) {
             const error = new Error(
-                `Integration not found for user: ${entity.userId}`
+                `Integration of type '${type}' not found for entity: ${entity.id}`
             );
             error.code = 'INTEGRATION_NOT_FOUND';
             throw error;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.590.c1af198.0",
+    "version": "2.0.0--canary.596.97a5c6b.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -38,9 +38,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.590.c1af198.0",
-        "@friggframework/prettier-config": "2.0.0--canary.590.c1af198.0",
-        "@friggframework/test": "2.0.0--canary.590.c1af198.0",
+        "@friggframework/eslint-config": "2.0.0--canary.596.97a5c6b.0",
+        "@friggframework/prettier-config": "2.0.0--canary.596.97a5c6b.0",
+        "@friggframework/test": "2.0.0--canary.596.97a5c6b.0",
         "@prisma/client": "^6.17.0",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -80,5 +80,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "c1af198e54a9e8986a69a91653b6134b9f26251c"
+    "gitHead": "97a5c6bc4217a0fcaaa6e6fa7baeb4b179f06d41"
 }