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

package/application/commands/integration-commands.js

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

package/integrations/EXTENSIONS.md

@@ -104,12 +104,12 @@ module.exports = {
                 // 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')
+                    // Reverse-lookup is exposed via friggCommands, the
+                    // canonical access pattern for cross-cutting lookups.
+                    // The HubSpot-named wrapper lives in the api-module's
+                    // extension package.
                     const integrationId =
-                        await this.findIntegrationByEntityExternalId(
+                        await this.commands.findIntegrationByEntityExternalId(
                             evt.portalId,
                             'hubspot'
                         );
@@ -162,12 +162,15 @@ Validation failures throw at boot with a message identifying the integration, bi
 
 ## 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:
+For app-level webhooks (HubSpot, Slack, Asana, Microsoft Teams, etc.) where one URL serves many accounts, extension default handlers need to resolve the inbound external ID (HubSpot `portalId`, Slack `team_id`, Asana `workspace_id`, Teams `tenant_id`) to a Frigg integration record. Two helpers are exposed via [`createFriggCommands`](../application/index.js) — the canonical access pattern for cross-cutting lookups:
 
 ```javascript
+// inside an integration class
+this.commands = createFriggCommands({ integrationClass: MyIntegration });
+
 // Throws on ambiguous resolution. Use when one externalId is expected
 // to map to exactly one integration.
-const integrationId = await this.findIntegrationByEntityExternalId(
+const integrationId = await this.commands.findIntegrationByEntityExternalId(
     externalId,
     'hubspot' // optional moduleName
 );
@@ -175,7 +178,7 @@ const integrationId = await this.findIntegrationByEntityExternalId(
 // 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(
+const integrationIds = await this.commands.listIntegrationsByEntityExternalId(
     externalId,
     'hubspot'
 );
@@ -185,18 +188,21 @@ const integrationIds = await this.listIntegrationsByEntityExternalId(
 - 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.
+A silent first-match at either layer is a cross-tenant routing risk; the command refuses to pick. The second argument (moduleName) disambiguates when multiple modules in the same app could carry colliding external IDs — pass it whenever an api-module knows its own moduleName.
 
 ### Where platform-named wrappers belong
 
-The core helpers are intentionally platform-neutral. Platform-vocabulary wrappers (`findIntegrationByPortalId`, `findIntegrationByTeamId`, `findIntegrationByWorkspaceId`, etc.) belong **inside the api-module's own extension**, not in core:
+The commands are intentionally platform-neutral. Platform-vocabulary wrappers (`findIntegrationByPortalId`, `findIntegrationByTeamId`, `findIntegrationByWorkspaceId`, etc.) belong **inside the api-module's own extension**, not in core:
 
 ```javascript
 // inside @friggframework/api-module-hubspot/extensions/webhooks
-async function findIntegrationByPortalId(portalId) {
+async function findIntegrationByPortalId(integration, portalId) {
     // thin wrapper — reads as self-documenting HubSpot code,
-    // delegates to the platform-neutral core primitive
-    return this.findIntegrationByEntityExternalId(portalId, 'hubspot');
+    // delegates to the platform-neutral command
+    return integration.commands.findIntegrationByEntityExternalId(
+        portalId,
+        'hubspot'
+    );
 }
 ```
 

package/integrations/integration-base.js

@@ -614,135 +614,6 @@ class IntegrationBase {
         }
     }
 
-    /**
-     * 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();

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

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

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

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

package/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.590.b2cd5e2.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.590.b2cd5e2.0",
+        "@friggframework/prettier-config": "2.0.0--canary.590.b2cd5e2.0",
+        "@friggframework/test": "2.0.0--canary.590.b2cd5e2.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": "b2cd5e23078cc2c77f49d498bedef06862e28fbc"
 }