@friggframework/core 2.0.0--canary.590.ffb7d1b.0 → 2.0.0--canary.593.a7bacab.0

package/handlers/backend-utils.js

@@ -31,9 +31,6 @@ 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
             );
@@ -215,9 +212,6 @@ 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,47 +2,24 @@ const { createAppHandler } = require('./../app-handler-helpers');
 const {
     loadAppDefinition,
 } = require('../app-definition-loader');
-const express = require('express');
-const { Router } = express;
+const { Router } = require('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:`);
 
-    const routes = IntegrationClass.Definition.routes || [];
-    for (const routeDef of routes) {
+    for (const routeDef of IntegrationClass.Definition.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)
@@ -50,25 +27,11 @@ 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,13 +1,6 @@
 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/index.js

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

package/integrations/integration-base.js

@@ -11,7 +11,6 @@ const {
 const {
     UpdateIntegrationMessages,
 } = require('./use-cases/update-integration-messages');
-const { validateExtensionBinding } = require('./extension');
 
 const constantsToBeMigrated = {
     defaultEvents: {
@@ -61,9 +60,6 @@ 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: '',
@@ -434,19 +430,6 @@ 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');
 
@@ -459,12 +442,10 @@ class IntegrationBase {
             throw new Error(`Queue URL not found for ${queueName}`);
         }
 
-        const { event: dispatchEvent, ...payload } = data || {};
-
         return QueuerUtil.send(
             {
-                event: dispatchEvent || 'ON_WEBHOOK',
-                data: payload,
+                event: 'ON_WEBHOOK',
+                data,
             },
             queueUrl
         );
@@ -523,226 +504,6 @@ 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();
@@ -751,7 +512,6 @@ class IntegrationBase {
             this.addError(e);
         }
 
-        this._mergeExtensions();
         this.registerEventHandlers();
     }
 

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/modules/repositories/module-repository-documentdb.js

@@ -100,21 +100,6 @@ 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,22 +91,6 @@ 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,34 +234,6 @@ 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,34 +275,6 @@ 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,30 +172,6 @@ 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--canary.590.ffb7d1b.0",
+    "version": "2.0.0--canary.593.a7bacab.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -38,9 +38,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.590.ffb7d1b.0",
-        "@friggframework/prettier-config": "2.0.0--canary.590.ffb7d1b.0",
-        "@friggframework/test": "2.0.0--canary.590.ffb7d1b.0",
+        "@friggframework/eslint-config": "2.0.0--canary.593.a7bacab.0",
+        "@friggframework/prettier-config": "2.0.0--canary.593.a7bacab.0",
+        "@friggframework/test": "2.0.0--canary.593.a7bacab.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": "ffb7d1bc294080aa9e9a3611dd30e21a4b800542"
+    "gitHead": "a7bacab2557a3bd8ee3baf6887cd6940a8a2cea4"
 }

package/integrations/EXTENSIONS.md

@@ -1,209 +0,0 @@
-# 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

@@ -1,233 +0,0 @@
-/**
- * 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,
-};