@friggframework/core 2.0.0-next.86 → 2.0.0-next.88

package/application/commands/integration-commands.js

@@ -11,6 +11,12 @@ const {
 const {
     FindIntegrationContextByExternalEntityIdUseCase,
 } = require('../../integrations/use-cases/find-integration-context-by-external-entity-id');
+const {
+    FindIntegrationByEntityExternalIdUseCase,
+} = require('../../integrations/use-cases/find-integration-by-entity-external-id');
+const {
+    ListIntegrationsByEntityExternalIdUseCase,
+} = require('../../integrations/use-cases/list-integrations-by-entity-external-id');
 const {
     GetIntegrationsForUser,
 } = require('../../integrations/use-cases/get-integrations-for-user');
@@ -25,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,
 };
 
@@ -69,6 +76,18 @@ function createIntegrationCommands({ integrationClass }) {
             loadIntegrationContextUseCase: loadIntegrationContextUseCase,
         });
 
+    const findIntegrationByEntityExternalIdUseCase =
+        new FindIntegrationByEntityExternalIdUseCase({
+            integrationRepository,
+            moduleRepository,
+        });
+
+    const listIntegrationsByEntityExternalIdUseCase =
+        new ListIntegrationsByEntityExternalIdUseCase({
+            integrationRepository,
+            moduleRepository,
+        });
+
     const getIntegrationsForUserUseCase = new GetIntegrationsForUser({
         integrationRepository,
         integrationClasses: [integrationClass],
@@ -83,19 +102,60 @@ 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);
             }
         },
 
+        /**
+         * Resolve an externalId (e.g. HubSpot portalId, Slack team_id) to a
+         * single integration ID. Throws on ambiguous resolution at either the
+         * entity or integration layer — cross-tenant routing is refused.
+         *
+         * @param {string|number} externalId - Provider's stable identifier.
+         * @param {string} [moduleName] - Disambiguates when multiple modules in
+         *     the same app could carry colliding externalIds.
+         * @returns {Promise<string|null>} Integration ID, or null on no match.
+         * @throws {Error} On ambiguous resolution (multiple entities or
+         *     multiple owning integrations).
+         */
+        async findIntegrationByEntityExternalId(externalId, moduleName) {
+            return findIntegrationByEntityExternalIdUseCase.execute({
+                externalId,
+                moduleName,
+            });
+        },
+
+        /**
+         * List all integration IDs whose module entities match an externalId.
+         * Use when one externalId is expected to map to multiple integrations
+         * (intentional fan-out). Does not throw on ambiguity.
+         *
+         * @param {string|number} externalId - Provider's stable identifier.
+         * @param {string} [moduleName] - Disambiguates across modules.
+         * @returns {Promise<Array<string>>} Array of integration IDs (possibly empty).
+         */
+        async listIntegrationsByEntityExternalId(externalId, moduleName) {
+            return listIntegrationsByEntityExternalIdUseCase.execute({
+                externalId,
+                moduleName,
+            });
+        },
+
         async loadIntegrationContextById(integrationId) {
             try {
                 const context = await loadIntegrationContextUseCase.execute({
@@ -197,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/handlers/backend-utils.js

@@ -31,6 +31,9 @@ const loadRouterFromObject = (IntegrationClass, routerObject) => {
     router[method.toLowerCase()](path, async (req, res, next) => {
         try {
             const integrationInstance = new IntegrationClass();
+            // initialize() registers dynamic user actions AND merges any Tier 3
+            // Integration Extension events into instance.events before dispatch.
+            await integrationInstance.initialize();
             const dispatcher = new IntegrationEventDispatcher(
                 integrationInstance
             );
@@ -212,6 +215,9 @@ const createQueueWorker = (integrationClass) => {
                         logCtx
                     );
                     integrationInstance = new integrationClass();
+                    // Merge Tier 3 Integration Extension events into instance.events
+                    // so extension-contributed queue events can be dispatched.
+                    await integrationInstance.initialize();
                 }
 
                 const dispatcher = new IntegrationEventDispatcher(

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

@@ -2,24 +2,47 @@ const { createAppHandler } = require('./../app-handler-helpers');
 const {
     loadAppDefinition,
 } = require('../app-definition-loader');
-const { Router } = require('express');
+const express = require('express');
+const { Router } = express;
 const { loadRouterFromObject } = require('../backend-utils');
+const { getExtensionRoutes } = require('../../integrations/extension');
 
 const handlers = {};
 const { integrations: integrationClasses } = loadAppDefinition();
 
+const routeKey = (method, path) => `${(method || 'ANY').toUpperCase()} ${path}`;
+
 //todo: this should be in a use case class
 for (const IntegrationClass of integrationClasses) {
     const router = Router();
     const basePath = `/api/${IntegrationClass.Definition.name}-integration`;
+    // Track (method, path) tuples to fail fast on conflicts between Definition.routes,
+    // extension routes, or two extensions claiming the same path.
+    const claimedRoutes = new Map();
+    const claim = (method, path, source) => {
+        const key = routeKey(method, path);
+        if (claimedRoutes.has(key)) {
+            const prev = claimedRoutes.get(key);
+            throw new Error(
+                `Integration "${IntegrationClass.Definition.name}" route conflict: ` +
+                    `${key} declared by ${prev} and ${source}`
+            );
+        }
+        claimedRoutes.set(key, source);
+    };
 
     console.log(`\n│ Configuring routes for ${IntegrationClass.Definition.name} Integration:`);
 
-    for (const routeDef of IntegrationClass.Definition.routes) {
+    const routes = IntegrationClass.Definition.routes || [];
+    for (const routeDef of routes) {
         if (typeof routeDef === 'function') {
             router.use(basePath, routeDef(IntegrationClass));
             console.log(`│ ANY ${basePath}/* (function handler)`);
+        } else if (routeDef instanceof express.Router) {
+            router.use(basePath, routeDef);
+            console.log(`│ ANY ${basePath}/* (express router)`);
         } else if (typeof routeDef === 'object') {
+            claim(routeDef.method, routeDef.path, 'Definition.routes');
             router.use(
                 basePath,
                 loadRouterFromObject(IntegrationClass, routeDef)
@@ -27,11 +50,25 @@ for (const IntegrationClass of integrationClasses) {
             const method = (routeDef.method || 'ANY').toUpperCase();
             const fullPath = `${basePath}${routeDef.path}`;
             console.log(`│ ${method} ${fullPath}`);
-        } else if (routeDef instanceof express.Router) {
-            router.use(basePath, routeDef);
-            console.log(`│ ANY ${basePath}/* (express router)`);
         }
     }
+
+    // Tier 3 Integration Extension routes — see EXTENSIONS.md
+    for (const extRoute of getExtensionRoutes(IntegrationClass)) {
+        claim(
+            extRoute.method,
+            extRoute.path,
+            `extension "${extRoute.extensionName}" (binding "${extRoute.bindingName}")`
+        );
+        router.use(
+            basePath,
+            loadRouterFromObject(IntegrationClass, extRoute)
+        );
+        const method = extRoute.method.toUpperCase();
+        console.log(
+            `│ ${method} ${basePath}${extRoute.path}  (extension: ${extRoute.extensionName})`
+        );
+    }
     console.log('│');
 
     handlers[`${IntegrationClass.Definition.name}`] = {

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

@@ -1,6 +1,13 @@
 const { createHandler } = require('@friggframework/core');
 const { loadAppDefinition } = require('../app-definition-loader');
 const { createQueueWorker } = require('../backend-utils');
+// TODO(Phase 2): mount extension-declared workers in addition to the per-integration
+// default queue worker. Today, getExtensionWorkers(IntegrationClass) returns the
+// declared workers but they are not yet bound to dedicated SQS sources. Extension-
+// contributed *events* still flow through the default queue worker below because
+// _mergeExtensions() registers them in instance.events, so end-to-end webhook
+// delivery for Tier 3 extensions works without this Phase 2 work.
+// const { getExtensionWorkers } = require('../../integrations/extension');
 
 const handlers = {};
 const { integrations: integrationClasses } = loadAppDefinition();

package/integrations/EXTENSIONS.md

@@ -0,0 +1,215 @@
+# Integration Extensions Quick Start
+
+Tier 3 **Integration Extensions** let an API module ship reusable handler bundles — receiver routes, event handlers, queues, workers — that an integration consumes declaratively via `Definition.extensions`. See [ADR-EXTENSIONS](../../../docs/architecture/ADR-EXTENSIONS.md) for the full taxonomy.
+
+## When to use this vs `Definition.webhooks: true`
+
+| Use `webhooks: true` ([WEBHOOK-QUICKSTART](./WEBHOOK-QUICKSTART.md)) | Use `extensions: {...}` |
+|---|---|
+| Per-account webhooks scoped to one integration record | App-level webhooks fanned out to many account records by external ID lookup |
+| You'll write the receiver, signature check, and queue dispatch yourself | The API module ships the receiver, signature check, and queue dispatch already |
+| One pattern, one endpoint | Multiple bundles (webhooks + CRM cards + timeline) declared together |
+
+## Step 1: Bind the extension on your Integration's Definition
+
+```javascript
+const hubspot = require('@friggframework/api-module-hubspot');
+
+class HubSpotIntegration extends IntegrationBase {
+    static Definition = {
+        name: 'hubspot',
+        version: '1.0.0',
+        modules: { hubspot: { definition: hubspot.Definition } },
+        extensions: {
+            hubspotWebhooks: {
+                extension: hubspot.extensions.webhooks,
+                handlers: { HUBSPOT_WEBHOOK: 'onHubSpotEvent' },
+            },
+        },
+    };
+
+    async onHubSpotEvent({ data }) {
+        // pure business logic — signature verification, portalId lookup,
+        // and queue dispatch are all done by the extension's default handlers
+        const { subscriptionType, objectId } = data.body;
+        if (subscriptionType === 'contact.creation') {
+            await this.upsertContact(objectId);
+        }
+    }
+}
+```
+
+The binding key (`hubspotWebhooks`) is your local name. 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:
+
+```
+│ Configuring routes for hubspot Integration:
+│ POST /api/hubspot-integration/webhooks  (extension: hubspot-webhooks)
+│
+```
+
+Hit that URL and the bound method (`onHubSpotEvent`) fires on the resolved per-account integration instance.
+
+## How handler binding works
+
+Each binding can map extension event names to method names on your integration:
+
+```javascript
+extensions: {
+    hubspotWebhooks: {
+        extension: hubspot.extensions.webhooks,
+        handlers: {
+            HUBSPOT_WEBHOOK: 'onHubSpotEvent',          // method on `this`
+        },
+    },
+},
+```
+
+Resolution priority per event:
+
+1. `binding.handlers[eventName]` → resolves to `this[methodName]`, bound to the instance
+2. Extension's own default handler from `extension.events[eventName].handler`, bound to the instance
+3. Otherwise → `initialize()` throws with a message naming the integration, binding, and event
+
+Strings (not function refs) are intentional: it dodges the `this`-in-static-Definition bootstrapping problem and centralizes binding inside the framework. The framework resolves the method against the live integration instance at startup.
+
+## Event-name conflicts (and binding the same extension twice)
+
+If two bindings in your integration's `extensions` map declare the same event name, the framework **throws at `initialize()`** with a clear conflict error — no silent first/last-writer pick, no surprise routing. The fix is to use distinct event names per binding.
+
+This means **binding the same extension twice only works if the extension itself defines disjoint event sets per use-case** (rare). For the common "two webhooks, two handlers" pattern, an API module should ship two distinct extensions instead — for example `hubspot.extensions.webhooks` and `hubspot.extensions.sandboxWebhooks`, each with its own event names.
+
+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.
+
+## Authoring an extension (for API module authors)
+
+An extension bundle is a plain object exported from your api-module:
+
+```javascript
+// @friggframework/api-module-hubspot/extensions/webhooks/index.js
+module.exports = {
+    name: 'hubspot-webhooks',
+    routes: [
+        { path: '/webhooks', method: 'POST', event: 'HUBSPOT_WEBHOOK_RECEIVED' },
+    ],
+    events: {
+        HUBSPOT_WEBHOOK_RECEIVED: {
+            type: 'LIFE_CYCLE_EVENT',
+            handler: async function ({ req, res }) {
+                // verify signature, look up integration by portalId, queue
+                await verifyHubSpotSignature(req);
+                for (const evt of req.body) {
+                    // Reverse-lookup is exposed via friggCommands, the
+                    // canonical access pattern for cross-cutting lookups.
+                    // The HubSpot-named wrapper lives in the api-module's
+                    // extension package.
+                    const integrationId =
+                        await this.commands.findIntegrationByEntityExternalId(
+                            evt.portalId,
+                            'hubspot'
+                        );
+                    if (!integrationId) continue;
+                    await this.queueWebhook({
+                        integrationId,
+                        body: evt,
+                        event: 'HUBSPOT_WEBHOOK',
+                    });
+                }
+                res.status(200).json({ received: req.body.length });
+            },
+        },
+        HUBSPOT_WEBHOOK: {
+            type: 'LIFE_CYCLE_EVENT',
+            handler: async function ({ data }) {
+                // default no-op; integrations override via binding.handlers
+            },
+        },
+    },
+};
+```
+
+Then expose it on your api-module's index:
+
+```javascript
+// @friggframework/api-module-hubspot/index.js
+module.exports = {
+    Definition: require('./api-module-definition'),
+    extensions: {
+        webhooks: require('./extensions/webhooks'),
+        crmCards: require('./extensions/crm-cards'),
+        timeline: require('./extensions/timeline'),
+    },
+};
+```
+
+## Contract enforced by the framework
+
+At `initialize()`, the framework validates each binding:
+
+- `extension` must be an object with a `name`
+- `extension.events` must be an object keyed by event name (if present)
+- `extension.routes` must be an array (if present)
+- Every route's `event` must exist in `extension.events`
+- Every route's `method` must be a known HTTP verb
+- For each event, either `binding.handlers[eventName]` resolves to an instance method, OR `extension.events[eventName].handler` is a function
+
+Validation failures throw at boot with a message identifying the integration, binding, and field.
+
+## Reverse-lookup helpers
+
+For app-level webhooks (HubSpot, Slack, Asana, Microsoft Teams, etc.) where one URL serves many accounts, extension default handlers need to resolve the inbound external ID (HubSpot `portalId`, Slack `team_id`, Asana `workspace_id`, Teams `tenant_id`) to a Frigg integration record. Two helpers are exposed via [`createFriggCommands`](../application/index.js) — the canonical access pattern for cross-cutting lookups:
+
+```javascript
+// inside an integration class
+this.commands = createFriggCommands({ integrationClass: MyIntegration });
+
+// Throws on ambiguous resolution. Use when one externalId is expected
+// to map to exactly one integration.
+const integrationId = await this.commands.findIntegrationByEntityExternalId(
+    externalId,
+    'hubspot' // optional moduleName
+);
+
+// Returns array. Use when one externalId may legitimately fan out to
+// multiple integrations (e.g. one upstream account broadcasting to
+// several Frigg integration records).
+const integrationIds = await this.commands.listIntegrationsByEntityExternalId(
+    externalId,
+    'hubspot'
+);
+```
+
+`findIntegrationByEntityExternalId` throws if:
+- the (externalId, moduleName) tuple matches more than one Entity row, OR
+- the matched entity is owned by more than one Integration record
+
+A silent first-match at either layer is a cross-tenant routing risk; the command refuses to pick. The second argument (moduleName) disambiguates when multiple modules in the same app could carry colliding external IDs — pass it whenever an api-module knows its own moduleName.
+
+### Where platform-named wrappers belong
+
+The commands are intentionally platform-neutral. Platform-vocabulary wrappers (`findIntegrationByPortalId`, `findIntegrationByTeamId`, `findIntegrationByWorkspaceId`, etc.) belong **inside the api-module's own extension**, not in core:
+
+```javascript
+// inside @friggframework/api-module-hubspot/extensions/webhooks
+async function findIntegrationByPortalId(integration, portalId) {
+    // thin wrapper — reads as self-documenting HubSpot code,
+    // delegates to the platform-neutral command
+    return integration.commands.findIntegrationByEntityExternalId(
+        portalId,
+        'hubspot'
+    );
+}
+```
+
+This keeps core platform-neutral and reusable while keeping the api-module code self-documenting for the platform's developers. The same rule applies to any helper that can be named in a single platform's vocabulary.
+
+## See also
+
+- [ADR-EXTENSIONS](../../../docs/architecture/ADR-EXTENSIONS.md) — the three-tier taxonomy (Core Plugins / Application Extensions / Integration Extensions)
+- [WEBHOOK-QUICKSTART](./WEBHOOK-QUICKSTART.md) — per-account `Definition.webhooks: true` pattern
+- `extension.js` — the validation + flattening helpers (`validateExtensionBinding`, `getExtensionRoutes`, `getExtensionWorkers`)

package/integrations/extension.js

@@ -0,0 +1,233 @@
+/**
+ * Tier 3 — Integration Extensions
+ *
+ * An Integration Extension is a reusable bundle exported by an API module (or a
+ * shared extensions library) that contributes routes, events, queues, and workers
+ * to a consumer integration. The integration binds the bundle declaratively via
+ * `static Definition.extensions` and the framework merges its contributions into
+ * the integration's effective definition at instantiation time.
+ *
+ * Extension bundle shape:
+ *
+ *     {
+ *         name: string,                       // required, unique within the API module
+ *         routes?: Array<{                    // optional, mounted alongside Definition.routes
+ *             path: string,
+ *             method: 'GET' | 'POST' | 'PUT' | 'DELETE' | ...,
+ *             event: string                   // must exist in `events` below
+ *         }>,
+ *         events?: {                          // optional, merged into instance.events
+ *             [eventName]: {
+ *                 type?: string,              // e.g. 'LIFE_CYCLE_EVENT'
+ *                 handler: Function           // default handler; integration may override per-binding
+ *             }
+ *         },
+ *         queues?: Array<Object>,             // reserved — Phase 2
+ *         workers?: Array<Object>             // reserved — Phase 2
+ *     }
+ *
+ * Integration binding shape (on the integration's static Definition.extensions):
+ *
+ *     extensions: {
+ *         hubspotWebhooks: {                  // local binding name (developer's choice)
+ *             extension: hubspot.extensions.webhooks,
+ *             handlers: {                     // optional override map
+ *                 HUBSPOT_WEBHOOK: 'onHubSpotEvent'  // event → method name on the integration
+ *             }
+ *         }
+ *     }
+ *
+ * The same extension may be bound multiple times under different local names; the
+ * binding key is the developer-controlled local handle, not a global registry key.
+ */
+
+const KNOWN_HTTP_METHODS = new Set([
+    'get',
+    'post',
+    'put',
+    'patch',
+    'delete',
+    'options',
+    'head',
+]);
+
+/**
+ * Validate the shape of an extension bundle and its binding.
+ *
+ * @param {Object} extension - The extension bundle to validate.
+ * @param {string} bindingName - The local binding key (for error context).
+ * @param {string} integrationName - The integration's Definition.name (for error context).
+ * @param {Object} [binding] - Optional full binding object; if provided, also validates binding.handlers.
+ * @throws {Error} If the extension is missing required fields or is internally inconsistent.
+ */
+function validateExtensionBinding(extension, bindingName, integrationName, binding) {
+    const ctx = `Integration "${integrationName}" extension binding "${bindingName}"`;
+
+    if (!extension || typeof extension !== 'object') {
+        throw new Error(`${ctx}: extension must be an object`);
+    }
+    if (!extension.name || typeof extension.name !== 'string') {
+        throw new Error(`${ctx}: extension is missing required "name" field`);
+    }
+
+    const events = extension.events || {};
+    if (typeof events !== 'object' || Array.isArray(events)) {
+        throw new Error(
+            `${ctx}: extension "${extension.name}" "events" must be an object keyed by event name`
+        );
+    }
+
+    // Validate each event's shape — handler, when present, must be a function.
+    for (const [eventName, eventDef] of Object.entries(events)) {
+        if (!eventDef || typeof eventDef !== 'object') {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" event "${eventName}" must be an object`
+            );
+        }
+        if (
+            eventDef.handler !== undefined &&
+            typeof eventDef.handler !== 'function'
+        ) {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" event "${eventName}" "handler" must be a function`
+            );
+        }
+    }
+
+    const routes = extension.routes || [];
+    if (!Array.isArray(routes)) {
+        throw new Error(
+            `${ctx}: extension "${extension.name}" "routes" must be an array`
+        );
+    }
+
+    for (const route of routes) {
+        if (!route || typeof route !== 'object') {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" has a malformed route entry`
+            );
+        }
+        if (typeof route.path !== 'string' || route.path.length === 0) {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" route is missing "path"`
+            );
+        }
+        if (typeof route.method !== 'string') {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" route "${route.path}" is missing "method"`
+            );
+        }
+        if (!KNOWN_HTTP_METHODS.has(route.method.toLowerCase())) {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" route "${route.path}" has unsupported method "${route.method}"`
+            );
+        }
+        if (typeof route.event !== 'string' || route.event.length === 0) {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" route "${route.path}" is missing "event"`
+            );
+        }
+        if (!Object.prototype.hasOwnProperty.call(events, route.event)) {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" route "${route.path}" references event "${route.event}" which is not declared in extension.events`
+            );
+        }
+    }
+
+    // Validate binding.handlers if a binding was supplied.
+    if (binding && binding.handlers !== undefined) {
+        if (
+            typeof binding.handlers !== 'object' ||
+            Array.isArray(binding.handlers) ||
+            binding.handlers === null
+        ) {
+            throw new Error(
+                `${ctx}: "handlers" must be an object keyed by event name`
+            );
+        }
+        for (const [eventName, methodRef] of Object.entries(binding.handlers)) {
+            if (typeof methodRef !== 'string' || methodRef.length === 0) {
+                throw new Error(
+                    `${ctx}: handler for event "${eventName}" must be a non-empty method name string (got ${typeof methodRef})`
+                );
+            }
+            if (!Object.prototype.hasOwnProperty.call(events, eventName)) {
+                throw new Error(
+                    `${ctx}: binding.handlers references event "${eventName}" which is not declared in extension "${extension.name}".events — check for typos`
+                );
+            }
+        }
+    }
+}
+
+/**
+ * Get the flattened list of extension-contributed routes for an integration class.
+ * Each route carries the binding name and extension name alongside the route fields
+ * so the router builder can produce useful boot-time logs.
+ *
+ * @param {Function} IntegrationClass - A class extending IntegrationBase.
+ * @returns {Array<{bindingName: string, extensionName: string, path: string, method: string, event: string}>}
+ */
+function getExtensionRoutes(IntegrationClass) {
+    const extensions = IntegrationClass?.Definition?.extensions || {};
+    const integrationName = IntegrationClass?.Definition?.name;
+    const flat = [];
+    for (const [bindingName, binding] of Object.entries(extensions)) {
+        // Fail fast: surface bad bindings at boot, not at first request.
+        // Mirrors the validation that _mergeExtensions does at instance time.
+        validateExtensionBinding(
+            binding && binding.extension,
+            bindingName,
+            integrationName,
+            binding
+        );
+        const routes = binding.extension.routes || [];
+        for (const route of routes) {
+            flat.push({
+                bindingName,
+                extensionName: binding.extension.name,
+                path: route.path,
+                method: route.method,
+                event: route.event,
+            });
+        }
+    }
+    return flat;
+}
+
+/**
+ * Get the flattened list of extension-contributed workers for an integration class.
+ * Reserved for Phase 2 — today the per-integration QueueWorker handles all events
+ * by name, so extension-contributed events flow through it without a dedicated worker.
+ *
+ * @param {Function} IntegrationClass - A class extending IntegrationBase.
+ * @returns {Array<Object>}
+ */
+function getExtensionWorkers(IntegrationClass) {
+    const extensions = IntegrationClass?.Definition?.extensions || {};
+    const integrationName = IntegrationClass?.Definition?.name;
+    const flat = [];
+    for (const [bindingName, binding] of Object.entries(extensions)) {
+        validateExtensionBinding(
+            binding && binding.extension,
+            bindingName,
+            integrationName,
+            binding
+        );
+        const workers = binding.extension.workers || [];
+        for (const worker of workers) {
+            flat.push({
+                bindingName,
+                extensionName: binding.extension.name,
+                ...worker,
+            });
+        }
+    }
+    return flat;
+}
+
+module.exports = {
+    validateExtensionBinding,
+    getExtensionRoutes,
+    getExtensionWorkers,
+};

package/integrations/index.js

@@ -10,6 +10,11 @@ const {
 const {
     LoadIntegrationContextUseCase,
 } = require('./use-cases/load-integration-context');
+const {
+    validateExtensionBinding,
+    getExtensionRoutes,
+    getExtensionWorkers,
+} = require('./extension');
 
 module.exports = {
     IntegrationBase,
@@ -18,4 +23,7 @@ module.exports = {
     checkRequiredParams,
     getModulesDefinitionFromIntegrationClasses,
     LoadIntegrationContextUseCase,
+    validateExtensionBinding,
+    getExtensionRoutes,
+    getExtensionWorkers,
 };

package/integrations/integration-base.js

@@ -11,6 +11,7 @@ const {
 const {
     UpdateIntegrationMessages,
 } = require('./use-cases/update-integration-messages');
+const { validateExtensionBinding } = require('./extension');
 
 const constantsToBeMigrated = {
     defaultEvents: {
@@ -60,6 +61,9 @@ class IntegrationBase {
         supportedVersions: [], // Eventually usable for deprecation and future test version purposes
 
         modules: {},
+        // Tier 3 Integration Extensions — see packages/core/integrations/EXTENSIONS.md
+        // Shape: { [bindingName]: { extension, handlers?: { [eventName]: methodName } } }
+        extensions: {},
         display: {
             name: 'Integration Name',
             logo: '',
@@ -430,6 +434,19 @@ class IntegrationBase {
         // Default: no-op, integrations override this
     }
 
+    /**
+     * Queue a webhook for asynchronous worker dispatch.
+     *
+     * The dispatch event defaults to `ON_WEBHOOK` for backward compatibility
+     * with the `Definition.webhooks: true` path. Extensions (and any caller
+     * that needs the worker to invoke a specific bound handler) can override
+     * by passing `event` in the payload — it's stripped from the payload and
+     * used as the SQS message's dispatch event.
+     *
+     * @param {Object} data - Webhook payload. May include `event` to override
+     *   the default `ON_WEBHOOK` dispatch event. All other fields are passed
+     *   through to the worker as the `data` field of the SQS message.
+     */
     async queueWebhook(data) {
         const { QueuerUtil } = require('../queues');
 
@@ -442,10 +459,12 @@ class IntegrationBase {
             throw new Error(`Queue URL not found for ${queueName}`);
         }
 
+        const { event: dispatchEvent, ...payload } = data || {};
+
         return QueuerUtil.send(
             {
-                event: 'ON_WEBHOOK',
-                data,
+                event: dispatchEvent || 'ON_WEBHOOK',
+                data: payload,
             },
             queueUrl
         );
@@ -504,6 +523,97 @@ class IntegrationBase {
         };
     }
 
+    /**
+     * Merge Tier 3 Integration Extension events into `this.events`.
+     *
+     * For each binding declared on `static Definition.extensions`, this method:
+     *   1. Validates the extension bundle shape and binding handlers
+     *   2. For each event the extension declares, resolves the handler in priority order:
+     *      a. Subclass-defined `this.events[eventName]` (set in the constructor) — wins; if a
+     *         binding tried to override that event with `handlers`, we log a warning so the
+     *         author knows their override is shadowed.
+     *      b. A method-name string in `binding.handlers[eventName]` → method on this instance
+     *      c. The extension's own default `handler` function
+     *      d. Otherwise throw — neither side provided a handler
+     *   3. Binds the resolved function to this instance and writes it to `this.events[eventName]`
+     *
+     * Two bindings declaring the same event throw a deterministic conflict error — silent
+     * "first/last writer wins" makes routing bugs nearly impossible to diagnose.
+     *
+     * @private
+     */
+    _mergeExtensions() {
+        const extensions = this.constructor.Definition?.extensions || {};
+        const integrationName = this.constructor.Definition?.name;
+        // Tracks which event names have been claimed by an extension binding during
+        // this merge — distinct from subclass-defined events on `this.events`.
+        const mergedByExtension = new Map();
+
+        for (const [bindingName, binding] of Object.entries(extensions)) {
+            if (!binding || typeof binding !== 'object') {
+                throw new Error(
+                    `Integration "${integrationName}" extension binding "${bindingName}" must be an object`
+                );
+            }
+            const { extension, handlers = {} } = binding;
+            validateExtensionBinding(
+                extension,
+                bindingName,
+                integrationName,
+                binding
+            );
+
+            const extEvents = extension.events || {};
+            for (const [eventName, eventDef] of Object.entries(extEvents)) {
+                // Conflict detection: another extension binding already claimed this event name.
+                if (mergedByExtension.has(eventName)) {
+                    const prev = mergedByExtension.get(eventName);
+                    throw new Error(
+                        `Integration "${integrationName}" extension event conflict: ` +
+                            `event "${eventName}" is declared by both binding "${prev}" and binding "${bindingName}" — ` +
+                            `use distinct event names per binding or omit duplicates`
+                    );
+                }
+
+                // Subclass shadowing: if the subclass set this.events[eventName] before initialize(),
+                // it wins. Warn if the binding tried to wire an override that's now ignored.
+                if (this.events[eventName]) {
+                    if (typeof handlers[eventName] === 'string') {
+                        console.warn(
+                            `[Frigg] Integration "${integrationName}" binding "${bindingName}": ` +
+                                `handler "${handlers[eventName]}" for event "${eventName}" is ignored because ` +
+                                `this.events["${eventName}"] was already set (subclass constructor or earlier merge)`
+                        );
+                    }
+                    continue;
+                }
+
+                let fn;
+                const override = handlers[eventName];
+                if (typeof override === 'string') {
+                    if (typeof this[override] !== 'function') {
+                        throw new Error(
+                            `Integration "${integrationName}" extension binding "${bindingName}": handler method "${override}" not found on instance`
+                        );
+                    }
+                    fn = this[override];
+                } else if (typeof eventDef.handler === 'function') {
+                    fn = eventDef.handler;
+                } else {
+                    throw new Error(
+                        `Extension "${extension.name}" event "${eventName}" has no default handler and binding "${bindingName}" did not provide one`
+                    );
+                }
+
+                this.events[eventName] = {
+                    type: eventDef.type,
+                    handler: fn.bind(this),
+                };
+                mergedByExtension.set(eventName, bindingName);
+            }
+        }
+    }
+
     async initialize() {
         try {
             const additionalUserActions = await this.loadDynamicUserActions();
@@ -512,6 +622,7 @@ class IntegrationBase {
             this.addError(e);
         }
 
+        this._mergeExtensions();
         this.registerEventHandlers();
     }
 

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

@@ -0,0 +1,74 @@
+/**
+ * Reverse-lookup use case: resolve an externalId (e.g. HubSpot portalId,
+ * Slack team_id, Asana workspace_id) to a single integration ID.
+ *
+ * Refuses to pick on ambiguous resolution at either layer:
+ *   - more than one matching Entity row for the (externalId, moduleName) tuple
+ *   - more than one Integration owning the matched entity
+ *
+ * A silent first-match in either case is a cross-tenant routing risk.
+ * Callers that expect a one-to-many fan-out should use
+ * {@link ListIntegrationsByEntityExternalIdUseCase} instead.
+ */
+class FindIntegrationByEntityExternalIdUseCase {
+    constructor({ integrationRepository, moduleRepository } = {}) {
+        if (!integrationRepository) {
+            throw new Error('integrationRepository is required');
+        }
+        if (!moduleRepository) {
+            throw new Error('moduleRepository is required');
+        }
+        this.integrationRepository = integrationRepository;
+        this.moduleRepository = moduleRepository;
+    }
+
+    async execute({ externalId, moduleName } = {}) {
+        if (!externalId) return null;
+
+        const filter = { externalId: String(externalId) };
+        if (moduleName) filter.moduleName = moduleName;
+
+        const entities = await this.moduleRepository.findEntities(filter);
+        if (!entities || entities.length === 0) {
+            console.log(
+                `[Frigg] findIntegrationByEntityExternalId: no entity for externalId=${externalId}${
+                    moduleName ? ` moduleName=${moduleName}` : ''
+                }`
+            );
+            return null;
+        }
+        if (entities.length > 1) {
+            const ids = entities.map((e) => e.id).join(', ');
+            throw new Error(
+                `findIntegrationByEntityExternalId: ambiguous resolution — externalId=${externalId}` +
+                    `${moduleName ? ` moduleName=${moduleName}` : ''} matches ${entities.length} entities [${ids}]. ` +
+                    `Refusing to pick one to avoid cross-tenant routing. ` +
+                    `Pass a moduleName, or use listIntegrationsByEntityExternalId if multiple integrations are expected.`
+            );
+        }
+
+        const entity = entities[0];
+        const integrations =
+            await this.integrationRepository.findIntegrationsByEntityId(
+                entity.id
+            );
+        if (!integrations || integrations.length === 0) {
+            console.log(
+                `[Frigg] findIntegrationByEntityExternalId: entity ${entity.id} has no owning integrations (orphan)`
+            );
+            return null;
+        }
+        if (integrations.length > 1) {
+            const ids = integrations.map((i) => i.id).join(', ');
+            throw new Error(
+                `findIntegrationByEntityExternalId: ambiguous resolution — externalId=${externalId}` +
+                    `${moduleName ? ` moduleName=${moduleName}` : ''} maps to ${integrations.length} integrations [${ids}]. ` +
+                    `Refusing to pick one to avoid cross-tenant routing. ` +
+                    `Use listIntegrationsByEntityExternalId if a one-to-many fan-out is intended.`
+            );
+        }
+        return integrations[0].id;
+    }
+}
+
+module.exports = { FindIntegrationByEntityExternalIdUseCase };

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/integrations/use-cases/list-integrations-by-entity-external-id.js

@@ -0,0 +1,46 @@
+/**
+ * List all integration IDs whose module entities match an externalId.
+ *
+ * Use this instead of {@link FindIntegrationByEntityExternalIdUseCase} when a
+ * single externalId is *expected* to map to multiple integrations (intentional
+ * fan-out: one upstream account broadcasting to several Frigg integration
+ * records, possibly across tenants).
+ *
+ * Does not throw on ambiguous resolution — that's the whole point.
+ */
+class ListIntegrationsByEntityExternalIdUseCase {
+    constructor({ integrationRepository, moduleRepository } = {}) {
+        if (!integrationRepository) {
+            throw new Error('integrationRepository is required');
+        }
+        if (!moduleRepository) {
+            throw new Error('moduleRepository is required');
+        }
+        this.integrationRepository = integrationRepository;
+        this.moduleRepository = moduleRepository;
+    }
+
+    async execute({ externalId, moduleName } = {}) {
+        if (!externalId) return [];
+
+        const filter = { externalId: String(externalId) };
+        if (moduleName) filter.moduleName = moduleName;
+
+        const entities = await this.moduleRepository.findEntities(filter);
+        if (!entities || entities.length === 0) return [];
+
+        const integrationIds = new Set();
+        for (const entity of entities) {
+            const owners =
+                await this.integrationRepository.findIntegrationsByEntityId(
+                    entity.id
+                );
+            for (const integration of owners || []) {
+                integrationIds.add(integration.id);
+            }
+        }
+        return Array.from(integrationIds);
+    }
+}
+
+module.exports = { ListIntegrationsByEntityExternalIdUseCase };

package/modules/repositories/module-repository-documentdb.js

@@ -100,6 +100,21 @@ class ModuleRepositoryDocumentDB extends ModuleRepositoryInterface {
         return this._mapEntity(doc, credential);
     }
 
+    async findEntities(filter) {
+        const query = this._buildFilter(filter);
+        const docs = await findMany(this.prisma, 'Entity', query);
+        if (!docs || docs.length === 0) return [];
+        const credentialMap = await this._fetchCredentialsBulk(
+            docs.map((doc) => doc.credentialId)
+        );
+        return docs.map((doc) =>
+            this._mapEntity(
+                doc,
+                credentialMap.get(fromObjectId(doc.credentialId)) || null
+            )
+        );
+    }
+
     async createEntity(entityData) {
         const {
             user,

package/modules/repositories/module-repository-interface.js

@@ -91,6 +91,22 @@ class ModuleRepositoryInterface {
         throw new Error('Method findEntity must be implemented by subclass');
     }
 
+    /**
+     * Find all entities matching a filter.
+     *
+     * Symmetric with findEntity but returns the full match set. Use this when
+     * a single externalId may correspond to more than one Entity row
+     * (e.g. shared upstream account across tenants) and the caller needs to
+     * detect/handle the multi-match case explicitly.
+     *
+     * @param {Object} filter - Filter criteria
+     * @returns {Promise<Array>} Array of entity objects (empty if no match)
+     * @abstract
+     */
+    async findEntities(filter) {
+        throw new Error('Method findEntities must be implemented by subclass');
+    }
+
     /**
      * Create a new entity
      *

package/modules/repositories/module-repository-mongo.js

@@ -234,6 +234,34 @@ class ModuleRepositoryMongo extends ModuleRepositoryInterface {
         };
     }
 
+    /**
+     * Find all entities matching a filter.
+     *
+     * @param {Object} filter - Filter criteria
+     * @returns {Promise<Array>} Array of entity objects with string IDs (empty if no match)
+     */
+    async findEntities(filter) {
+        const where = this._convertFilterToWhere(filter);
+        const entities = await this.prisma.entity.findMany({
+            where,
+        });
+
+        const credentialIds = entities
+            .map((e) => e.credentialId)
+            .filter(Boolean);
+        const credentialMap = await this._fetchCredentialsBulk(credentialIds);
+
+        return entities.map((e) => ({
+            id: e.id,
+            credential: credentialMap.get(e.credentialId) || null,
+            userId: e.userId,
+            name: e.name,
+            externalId: e.externalId,
+            moduleName: e.moduleName,
+            ...(e.data || {}),
+        }));
+    }
+
     /**
      * Create a new entity
      * Replaces: Entity.create(entityData)

package/modules/repositories/module-repository-postgres.js

@@ -275,6 +275,34 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
         };
     }
 
+    /**
+     * Find all entities matching a filter.
+     *
+     * @param {Object} filter - Filter criteria
+     * @returns {Promise<Array>} Array of entity objects with string IDs (empty if no match)
+     */
+    async findEntities(filter) {
+        const where = this._convertFilterToWhere(filter);
+        const entities = await this.prisma.entity.findMany({
+            where,
+        });
+
+        const credentialIds = entities
+            .map((e) => e.credentialId)
+            .filter(Boolean);
+        const credentialMap = await this._fetchCredentialsBulk(credentialIds);
+
+        return entities.map((e) => ({
+            id: e.id.toString(),
+            credential: credentialMap.get(e.credentialId) || null,
+            userId: e.userId?.toString(),
+            name: e.name,
+            externalId: e.externalId,
+            moduleName: e.moduleName,
+            ...(e.data || {}),
+        }));
+    }
+
     /**
      * Create a new entity
      * Replaces: Entity.create(entityData)

package/modules/repositories/module-repository.js

@@ -172,6 +172,30 @@ class ModuleRepository extends ModuleRepositoryInterface {
         };
     }
 
+    /**
+     * Find all entities matching a filter.
+     *
+     * @param {Object} filter - Filter criteria
+     * @returns {Promise<Array>} Array of entity objects (empty if no match)
+     */
+    async findEntities(filter) {
+        const where = this._convertFilterToWhere(filter);
+        const entities = await this.prisma.entity.findMany({
+            where,
+            include: { credential: true },
+        });
+
+        return entities.map((e) => ({
+            id: e.id,
+            credential: e.credential,
+            userId: e.userId,
+            name: e.name,
+            externalId: e.externalId,
+            moduleName: e.moduleName,
+            ...(e.data || {}),
+        }));
+    }
+
     /**
      * Create a new entity
      * Replaces: Entity.create(entityData)

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0-next.86",
+    "version": "2.0.0-next.88",
     "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-next.86",
-        "@friggframework/prettier-config": "2.0.0-next.86",
-        "@friggframework/test": "2.0.0-next.86",
+        "@friggframework/eslint-config": "2.0.0-next.88",
+        "@friggframework/prettier-config": "2.0.0-next.88",
+        "@friggframework/test": "2.0.0-next.88",
         "@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": "8862a43e3aa4be518fa1b35da41b76129b617a2e"
+    "gitHead": "613b1c6f878086fadaf5a400c4227e4911a06d3e"
 }