@friggframework/core 2.0.0--canary.590.094a71b.0 → 2.0.0--canary.590.ffb7d1b.0

package/integrations/EXTENSIONS.md

@@ -104,10 +104,15 @@ module.exports = {
                 // verify signature, look up integration by portalId, queue
                 await verifyHubSpotSignature(req);
                 for (const evt of req.body) {
-                    const integrationId = await this.findIntegrationByPortalId(
-                        evt.portalId,
-                        'hubspot'
-                    );
+                    // 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,
@@ -155,15 +160,47 @@ At `initialize()`, the framework validates each binding:
 
 Validation failures throw at boot with a message identifying the integration, binding, and field.
 
-## Reverse-lookup helper
+## Reverse-lookup helpers
 
-For app-level webhooks (HubSpot, Slack, etc.) where one URL serves many accounts, extension default handlers commonly need to resolve the inbound external ID (portalId, team_id, workspace_id) to a Frigg integration record. Use the inherited helper:
+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
-const integrationId = await this.findIntegrationByPortalId(externalId, 'hubspot');
+// 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'
+);
 ```
 
-Returns the integration ID (or `null`) for the first matching entity. The second arg disambiguates when multiple modules in the same app could carry colliding external IDs.
+`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
 

package/integrations/integration-base.js

@@ -434,6 +434,19 @@ class IntegrationBase {
         // Default: no-op, integrations override this
     }
 
+    /**
+     * Queue a webhook for asynchronous worker dispatch.
+     *
+     * The dispatch event defaults to `ON_WEBHOOK` for backward compatibility
+     * with the `Definition.webhooks: true` path. Extensions (and any caller
+     * that needs the worker to invoke a specific bound handler) can override
+     * by passing `event` in the payload — it's stripped from the payload and
+     * used as the SQS message's dispatch event.
+     *
+     * @param {Object} data - Webhook payload. May include `event` to override
+     *   the default `ON_WEBHOOK` dispatch event. All other fields are passed
+     *   through to the worker as the `data` field of the SQS message.
+     */
     async queueWebhook(data) {
         const { QueuerUtil } = require('../queues');
 
@@ -446,10 +459,12 @@ class IntegrationBase {
             throw new Error(`Queue URL not found for ${queueName}`);
         }
 
+        const { event: dispatchEvent, ...payload } = data || {};
+
         return QueuerUtil.send(
             {
-                event: 'ON_WEBHOOK',
-                data,
+                event: dispatchEvent || 'ON_WEBHOOK',
+                data: payload,
             },
             queueUrl
         );
@@ -600,66 +615,134 @@ class IntegrationBase {
     }
 
     /**
-     * Reverse-lookup helper: find an integration ID by a module entity's externalId.
+     * 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.
      *
-     * Used by extension default handlers (e.g. HubSpot webhook receiver) that need
-     * to resolve an incoming app-level event to a specific per-account integration
-     * record. The external ID is provided by the upstream system (HubSpot portalId,
-     * Slack team_id, etc.) — this helper looks up which Frigg integration owns the
-     * entity carrying that external ID.
+     * 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.
      *
-     * Throws on ambiguous resolution. A single externalId mapping to multiple
-     * integrations is a cross-tenant routing risk (e.g. two users connecting the
-     * same HubSpot portal): we refuse to silently pick `[0]`. Callers that
-     * legitimately need to fan out to multiple integrations should use the
-     * lower-level repository call directly.
+     * **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
      *
-     * @param {string} externalId - The provider's stable identifier for the account/portal/workspace.
-     * @param {string} [moduleName] - Optional module name to disambiguate when multiple modules in the same app could carry colliding externalIds.
-     * @returns {Promise<string|null>} The integration ID, or null if no match.
-     * @throws {Error} If more than one integration is found for the (externalId, moduleName) tuple.
+     * 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 findIntegrationByPortalId(externalId, moduleName) {
+    async findIntegrationByEntityExternalId(externalId, moduleName) {
         if (!externalId) return null;
-        const {
-            createModuleRepository,
-        } = require('../modules/repositories/module-repository-factory');
-        const moduleRepository = createModuleRepository();
 
-        const filter = { externalId: String(externalId) };
-        if (moduleName) filter.moduleName = moduleName;
-
-        const entity = await moduleRepository.findEntity(filter);
-        if (!entity) {
+        const entities = await this._findEntitiesByExternalId(
+            externalId,
+            moduleName
+        );
+        if (entities.length === 0) {
             console.log(
-                `[Frigg] findIntegrationByPortalId: no entity for externalId=${externalId}${
+                `[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] findIntegrationByPortalId: entity ${entity.id} has no owning integrations (orphan)`
+                `[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(
-                `findIntegrationByPortalId: ambiguous resolution — externalId=${externalId}` +
+                `findIntegrationByEntityExternalId: ambiguous resolution — externalId=${externalId}` +
                     `${moduleName ? ` moduleName=${moduleName}` : ''} maps to ${integrations.length} integrations [${ids}]. ` +
-                    `Refusing to pick one to avoid cross-tenant routing.`
+                    `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();

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

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

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

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

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

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

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

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

package/modules/repositories/module-repository.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.590.094a71b.0",
+    "version": "2.0.0--canary.590.ffb7d1b.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.094a71b.0",
-        "@friggframework/prettier-config": "2.0.0--canary.590.094a71b.0",
-        "@friggframework/test": "2.0.0--canary.590.094a71b.0",
+        "@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",
         "@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": "094a71baaac437d208e2ad749bc3c79a9b0c15bb"
+    "gitHead": "ffb7d1bc294080aa9e9a3611dd30e21a4b800542"
 }