@friggframework/core 2.0.0--canary.585.8f515e1.0 → 2.0.0--canary.590.0836cf9.0

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,209 @@
+# 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) {
+                    // Core helper is generic; the extension wraps it in
+                    // HubSpot vocabulary for its own readability:
+                    //   findIntegrationByPortalId(portalId) =
+                    //     findIntegrationByEntityExternalId(portalId, 'hubspot')
+                    const integrationId =
+                        await this.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 inherited helpers:
+
+```javascript
+// Throws on ambiguous resolution. Use when one externalId is expected
+// to map to exactly one integration.
+const integrationId = await this.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.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 helper 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 core helpers 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(portalId) {
+    // thin wrapper — reads as self-documenting HubSpot code,
+    // delegates to the platform-neutral core primitive
+    return this.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: '',
@@ -504,6 +508,226 @@ 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);
+            }
+        }
+    }
+
+    /**
+     * Reverse-lookup helper: find a single integration ID by the externalId of
+     * one of its module entities.
+     *
+     * Used by extension default handlers (HubSpot's `portalId`, Slack's `team_id`,
+     * Asana's `workspace_id`, etc.) to resolve an inbound app-level event to the
+     * specific per-account integration record that should handle it.
+     *
+     * The helper is intentionally platform-neutral. Platform-vocabulary wrappers
+     * (e.g. `findIntegrationByPortalId(portalId)`) belong in the api-module's
+     * own extension, where they read as self-documenting for that platform's
+     * developers and where naming collisions across providers are impossible.
+     *
+     * **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 here is a cross-tenant routing risk. Callers that
+     * legitimately expect a one-to-many relationship must use
+     * {@link listIntegrationsByEntityExternalId} instead.
+     *
+     * @param {string} externalId - Provider's stable identifier for the account/portal/workspace.
+     * @param {string} [moduleName] - Disambiguates when multiple modules in the same app could carry colliding externalIds.
+     * @returns {Promise<string|null>} The integration ID, or null if no entity or no owning integration matches.
+     * @throws {Error} If the (externalId, moduleName) tuple matches multiple entities, or if the matched entity is owned by multiple integrations.
+     */
+    async findIntegrationByEntityExternalId(externalId, moduleName) {
+        if (!externalId) return null;
+
+        const entities = await this._findEntitiesByExternalId(
+            externalId,
+            moduleName
+        );
+        if (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;
+    }
+
+    /**
+     * List all integration IDs whose module entities match an externalId.
+     *
+     * Use this instead of {@link findIntegrationByEntityExternalId} when a single
+     * externalId is *expected* to map to multiple integrations (e.g. an
+     * 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.
+     *
+     * @param {string} externalId - Provider's stable identifier for the account/portal/workspace.
+     * @param {string} [moduleName] - Disambiguates when multiple modules in the same app could carry colliding externalIds.
+     * @returns {Promise<Array<string>>} Array of integration IDs (empty if no entity or no owning integrations).
+     */
+    async listIntegrationsByEntityExternalId(externalId, moduleName) {
+        if (!externalId) return [];
+
+        const entities = await this._findEntitiesByExternalId(
+            externalId,
+            moduleName
+        );
+        if (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);
+    }
+
+    /**
+     * Internal: load entities matching an externalId (+ optional moduleName).
+     * Pulled out so the single-result and list-result helpers share lookup logic.
+     *
+     * @private
+     */
+    async _findEntitiesByExternalId(externalId, moduleName) {
+        const {
+            createModuleRepository,
+        } = require('../modules/repositories/module-repository-factory');
+        const moduleRepository = createModuleRepository();
+
+        const filter = { externalId: String(externalId) };
+        if (moduleName) filter.moduleName = moduleName;
+
+        const entities = await moduleRepository.findEntities(filter);
+        return entities || [];
+    }
+
     async initialize() {
         try {
             const additionalUserActions = await this.loadDynamicUserActions();
@@ -512,6 +736,7 @@ class IntegrationBase {
             this.addError(e);
         }
 
+        this._mergeExtensions();
         this.registerEventHandlers();
     }
 
@@ -560,13 +785,25 @@ class IntegrationBase {
      * @returns {Promise<void>}
      */
     async receiveNotification(notifier, delegateString, object = null) {
-        if (delegateString !== 'CREDENTIAL_INVALIDATED') return;
         if (!this.id) return;
-        console.log(
-            `[Frigg] Module ${notifier?.name || '?'} reported invalid credentials for integration ${this.id} — marking ERROR`
-        );
-        await this.updateIntegrationStatus.execute(this.id, 'ERROR');
-        this.status = 'ERROR';
+
+        if (delegateString === 'CREDENTIAL_INVALIDATED') {
+            console.log(
+                `[Frigg] Module ${notifier?.name || '?'} reported invalid credentials for integration ${this.id} — marking ERROR`
+            );
+            await this.updateIntegrationStatus.execute(this.id, 'ERROR');
+            this.status = 'ERROR';
+            return;
+        }
+
+        if (delegateString === 'CREDENTIAL_VALIDATED') {
+            if (this.status !== 'ERROR') return;
+            console.log(
+                `[Frigg] Module ${notifier?.name || '?'} reported valid credentials for integration ${this.id} — clearing ERROR → ENABLED`
+            );
+            await this.updateIntegrationStatus.execute(this.id, 'ENABLED');
+            this.status = 'ENABLED';
+        }
     }
 }
 

package/integrations/use-cases/update-process-metrics.js

@@ -28,8 +28,9 @@
  * const updateMetrics = new UpdateProcessMetrics({ processRepository, websocketService });
  * await updateMetrics.execute(processId, {
  *   processed: 100,
- *   success: 95,
+ *   success: 92,
  *   errors: 5,
+ *   skipped: 3,
  *   errorDetails: [{ contactId: 'abc', error: 'Missing email', timestamp: '...' }]
  * });
  */
@@ -54,6 +55,11 @@ class UpdateProcessMetrics {
      * @param {number} [metricsUpdate.processed=0] - Records processed in this batch
      * @param {number} [metricsUpdate.success=0] - Successful records
      * @param {number} [metricsUpdate.errors=0] - Failed records
+     * @param {number} [metricsUpdate.skipped=0] - Intentionally-skipped
+     *     records (hash-match, dedupe, loop protection, etc.). Increments
+     *     `results.aggregateData.totalSkipped`. Distinct from errors so the
+     *     UI can show `processed = synced + failed + skipped` without
+     *     conflating intentional skips with failures.
      * @param {Array} [metricsUpdate.errorDetails=[]] - Error details array
      * @returns {Promise<Object>} Updated process record
      * @throws {Error} If process not found or update fails
@@ -71,9 +77,11 @@ class UpdateProcessMetrics {
         const processed = metricsUpdate.processed || 0;
         const success = metricsUpdate.success || 0;
         const errors = metricsUpdate.errors || 0;
+        const skipped = metricsUpdate.skipped || 0;
         if (processed) increment['context.processedRecords'] = processed;
         if (success) increment['results.aggregateData.totalSynced'] = success;
         if (errors) increment['results.aggregateData.totalFailed'] = errors;
+        if (skipped) increment['results.aggregateData.totalSkipped'] = skipped;
 
         const pushSlice = {};
         if (
@@ -191,6 +199,7 @@ class UpdateProcessMetrics {
                     total: context.totalRecords || 0,
                     successCount: aggregateData.totalSynced || 0,
                     errorCount: aggregateData.totalFailed || 0,
+                    skippedCount: aggregateData.totalSkipped || 0,
                     recordsPerSecond: aggregateData.recordsPerSecond || 0,
                     estimatedCompletion: context.estimatedCompletion || null,
                     timestamp: new Date().toISOString(),

package/modules/module.js

@@ -41,6 +41,8 @@ class Module extends Delegate {
         // Module → parent delegate (typically IntegrationBase) events
         this.DLGT_CREDENTIAL_INVALIDATED = 'CREDENTIAL_INVALIDATED';
         this.delegateTypes.push(this.DLGT_CREDENTIAL_INVALIDATED);
+        this.DLGT_CREDENTIAL_VALIDATED = 'CREDENTIAL_VALIDATED';
+        this.delegateTypes.push(this.DLGT_CREDENTIAL_VALIDATED);
 
         Object.assign(this, this.definition.requiredAuthMethods);
 
@@ -123,6 +125,20 @@ class Module extends Delegate {
             credentialDetails
         );
         this.credential = persisted;
+
+        if (this.credential?.id) {
+            try {
+                await this.notify(this.DLGT_CREDENTIAL_VALIDATED, {
+                    credentialId: this.credential.id,
+                    moduleName: this.name,
+                });
+            } catch (err) {
+                console.error(
+                    `[Frigg] Failed to propagate CREDENTIAL_VALIDATED for module ${this.name}:`,
+                    err?.message || err
+                );
+            }
+        }
     }
 
     async receiveNotification(notifier, delegateString, object = null) {

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/modules/requester/requester.js

@@ -151,9 +151,9 @@ class Requester extends Delegate {
                 await new Promise((resolve) => setTimeout(resolve, delay));
                 return this._request(url, options, i + 1);
             } else if (status === 401) {
-                if (!this.isRefreshable || this.refreshCount > 0) {
+                if (!this.isRefreshable) {
                     await this.notify(this.DLGT_INVALID_AUTH);
-                } else {
+                } else if (this.refreshCount === 0) {
                     this.refreshCount++;
                     const refreshSucceeded = await this.refreshAuth();
                     if (refreshSucceeded) {
@@ -178,6 +178,11 @@ class Requester extends Delegate {
                 );
             }
 
+            // Successful response: reset the per-instance refresh budget so
+            // a later 401 in the same Requester lifetime can attempt refresh
+            // again instead of silently falling through.
+            this.refreshCount = 0;
+
             // parsedBody consumes the response body stream. If the server
             // stalls mid-stream the timer (still armed) aborts it.
             return options.returnFullRes

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.585.8f515e1.0",
+    "version": "2.0.0--canary.590.0836cf9.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.585.8f515e1.0",
-        "@friggframework/prettier-config": "2.0.0--canary.585.8f515e1.0",
-        "@friggframework/test": "2.0.0--canary.585.8f515e1.0",
+        "@friggframework/eslint-config": "2.0.0--canary.590.0836cf9.0",
+        "@friggframework/prettier-config": "2.0.0--canary.590.0836cf9.0",
+        "@friggframework/test": "2.0.0--canary.590.0836cf9.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": "8f515e128f7c2f34f69acb14476a9189879417ec"
+    "gitHead": "0836cf99aa6b9d273e19c4fcc890b4d98d7bc05b"
 }