@friggframework/core 2.0.0-next.97 → 2.0.0-next.99

package/integrations/use-cases/create-integration.js

@@ -22,23 +22,158 @@ class CreateIntegration {
     }
 
     /**
-     * Executes the integration creation process.
+     * Executes the integration creation process. Reuses an existing
+     * integration when one already exists for the same userId, config.type,
+     * and entity set, instead of creating a duplicate.
      * @async
      * @param {string[]} entities - Array of entity IDs to associate with the integration.
      * @param {string} userId - ID of the user creating the integration.
      * @param {Object} config - Configuration object for the integration.
      * @param {string} config.type - Type of integration to create.
-     * @returns {Promise<Object>} The created integration DTO.
+     * @returns {Promise<Object>} The created or reused integration DTO.
      * @throws {Error} When integration class is not found for the specified type.
      */
     async execute(entities, userId, config) {
+        console.log(
+            `[Frigg] Creating ${config?.type} integration for user ${userId} with entities [${entities}]`
+        );
+
+        const existing = await this._findDuplicate(
+            userId,
+            config?.type,
+            entities
+        );
+        if (existing) {
+            console.log(
+                `[Frigg] Found existing integration ${existing.id} for the same user, type, and entities — reusing it`
+            );
+            return this._reuseExisting(existing, config);
+        }
+
         const integrationRecord =
             await this.integrationRepository.createIntegration(
                 entities,
                 userId,
                 config
             );
+        console.log(
+            `[Frigg] Created integration ${integrationRecord.id} for user ${userId}`
+        );
+
+        // A concurrent request may have created a matching row between the
+        // lookup above and this insert; re-check before any side effects run.
+        const survivor = await this._findDuplicate(
+            userId,
+            config?.type,
+            entities
+        );
+        if (survivor && String(survivor.id) !== String(integrationRecord.id)) {
+            console.log(
+                `[Frigg] Concurrent create detected — deleting duplicate ${integrationRecord.id} and reusing ${survivor.id}`
+            );
+            await this.integrationRepository.deleteIntegrationById(
+                integrationRecord.id
+            );
+            return this._reuseExisting(survivor, config);
+        }
+
+        const integrationInstance = await this._buildInstance(
+            integrationRecord
+        );
+        console.log(
+            `[Frigg] Sending ON_CREATE for integration ${integrationRecord.id}`
+        );
+        await integrationInstance.send('ON_CREATE', {
+            integrationId: integrationRecord.id,
+        });
+
+        return mapIntegrationClassToIntegrationDTO(integrationInstance);
+    }
+
+    async _reuseExisting(integrationRecord, config) {
+        // The caller may be reconnecting with changed settings. Persist the
+        // requested config onto the reused row as a shallow patch, so new
+        // values take effect while keys added during the original create
+        // (webhook ids, secrets) survive. `type` is re-written to the same
+        // value it dedupe-matched on, which is a harmless no-op.
+        if (config && Object.keys(config).length > 0) {
+            integrationRecord =
+                await this.integrationRepository.patchIntegrationConfig(
+                    integrationRecord.id,
+                    config
+                );
+        }
+
+        const integrationInstance = await this._buildInstance(
+            integrationRecord
+        );
+
+        if (integrationInstance.status === 'IN_CREATION') {
+            // ON_CREATE never finished for this row (crashed mid-setup or is
+            // still running concurrently). Re-firing ON_CREATE here would
+            // risk re-registering a webhook a partially-completed attempt
+            // already created — unsafe without idempotent setup, which is a
+            // separate, larger change. Surfaced loudly rather than silently
+            // reused as if healthy, so it's diagnosable; testAuth below still
+            // runs and can at least surface bad credentials as ERROR.
+            console.warn(
+                `[Frigg] Integration ${integrationInstance.id} is still IN_CREATION on reuse — setup never completed`
+            );
+        }
+
+        // User is actively trying to reconnect; here if the integration is
+        // disabled, we can enable it again.
+        const authPassed = await integrationInstance.testAuth();
+        await integrationInstance.reconcileAuthStatus(authPassed);
+        if (integrationInstance.status === 'DISABLED') {
+            console.log(
+                `[Frigg] Integration ${integrationInstance.id} changed status from DISABLED to ENABLED`
+            );
+            await integrationInstance.persistStatus('ENABLED');
+        }
+
+        return mapIntegrationClassToIntegrationDTO(integrationInstance);
+    }
+
+    async _findDuplicate(userId, type, entityIds) {
+        const candidates =
+            await this.integrationRepository.findIntegrationsByUserId(userId);
+        const target = [...(entityIds ?? [])].map(String).sort();
 
+        const matches = candidates.filter((integration) => {
+            // An IN_DELETION row is either mid-teardown or a zombie left
+            // behind by a failed deleteIntegrationById call — never a live
+            // integration. Treating it as a duplicate would hand a reinstall
+            // attempt a row nothing will ever move out of IN_DELETION,
+            // silently discarded by the queue worker forever. Let a fresh
+            // create proceed instead; the zombie is cleaned up out-of-band,
+            // matching how teardown failures are already handled here.
+            if (integration.status === 'IN_DELETION') return false;
+            if (integration.config?.type !== type) return false;
+            const current = [...(integration.entitiesIds ?? [])]
+                .map(String)
+                .sort();
+            return (
+                current.length === target.length &&
+                current.every((id, index) => id === target[index])
+            );
+        });
+
+        return matches.length ? this._pickOldest(matches) : null;
+    }
+
+    _pickOldest(records) {
+        return [...records].sort((a, b) => {
+            const diff =
+                new Date(a.createdAt ?? 0) - new Date(b.createdAt ?? 0);
+            if (diff !== 0) return diff;
+            return String(a.id).localeCompare(String(b.id), 'en', {
+                numeric: true,
+            });
+        })[0];
+    }
+
+    async _buildInstance(integrationRecord) {
         const integrationClass = this.integrationClasses.find(
             (integrationClass) =>
                 integrationClass.Definition.name ===
@@ -72,11 +207,8 @@ class CreateIntegration {
         });
 
         await integrationInstance.initialize();
-        await integrationInstance.send('ON_CREATE', {
-            integrationId: integrationRecord.id,
-        });
 
-        return mapIntegrationClassToIntegrationDTO(integrationInstance);
+        return integrationInstance;
     }
 }
 

package/integrations/use-cases/delete-integration-for-user.js

@@ -92,7 +92,25 @@ class DeleteIntegrationForUser {
 
         // Complete async initialization (load dynamic actions, register handlers)
         await integrationInstance.initialize();
-        await integrationInstance.send('ON_DELETE');
+
+        await integrationInstance.persistStatus('IN_DELETION');
+        try {
+            await integrationInstance.send('ON_DELETE');
+        } catch (error) {
+            const reason = error?.message ?? String(error);
+            console.error(
+                `[Integration Deletion] onDelete failed for integration ${integrationId}, leaving it IN_DELETION:`,
+                reason
+            );
+            await integrationInstance.updateIntegrationMessages.execute(
+                integrationId,
+                'errors',
+                'Integration Deletion Error',
+                `Deletion did not complete: ${reason}`,
+                Date.now()
+            );
+            throw error;
+        }
 
         await this.integrationRepository.deleteIntegrationById(integrationId);
     }

package/integrations/use-cases/patch-integration-config.js

@@ -0,0 +1,39 @@
+/**
+ * Use case for atomically merging a partial update into an integration's
+ * configuration, leaving keys not present in the patch untouched.
+ *
+ * The merge is shallow: only top-level config keys are affected, and each
+ * key in the patch replaces its existing value wholesale (a nested object is
+ * overwritten as a block, not deep-merged). To change one field inside a
+ * nested object without dropping its siblings, pass the whole updated object
+ * as that key's value. A `null` value sets the key to null (clears the field
+ * without removing it); to remove a key entirely, use a full replace via
+ * UpdateIntegrationConfig instead.
+ * @class PatchIntegrationConfig
+ */
+class PatchIntegrationConfig {
+    /**
+     * Creates a new PatchIntegrationConfig instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface} params.integrationRepository - Repository for integration data operations.
+     */
+    constructor({ integrationRepository }) {
+        this.integrationRepository = integrationRepository;
+    }
+
+    /**
+     * Executes the config patch.
+     * @async
+     * @param {string} integrationId - ID of the integration to update.
+     * @param {Object} patch - Keys to merge into the existing config.
+     * @returns {Promise<Object>} The updated integration record.
+     */
+    async execute(integrationId, patch) {
+        return this.integrationRepository.patchIntegrationConfig(
+            integrationId,
+            patch
+        );
+    }
+}
+
+module.exports = { PatchIntegrationConfig };

package/integrations/use-cases/update-integration-config.js

@@ -0,0 +1,32 @@
+/**
+ * Use case for replacing an integration's entire configuration. Keys not
+ * present in the new config are deleted — use PatchIntegrationConfig to
+ * merge a partial update without losing untouched keys.
+ * @class UpdateIntegrationConfig
+ */
+class UpdateIntegrationConfig {
+    /**
+     * Creates a new UpdateIntegrationConfig instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface} params.integrationRepository - Repository for integration data operations.
+     */
+    constructor({ integrationRepository }) {
+        this.integrationRepository = integrationRepository;
+    }
+
+    /**
+     * Executes the full config replace.
+     * @async
+     * @param {string} integrationId - ID of the integration to update.
+     * @param {Object} config - The new configuration object.
+     * @returns {Promise<Object>} The updated integration record.
+     */
+    async execute(integrationId, config) {
+        return this.integrationRepository.updateIntegrationConfig(
+            integrationId,
+            config
+        );
+    }
+}
+
+module.exports = { UpdateIntegrationConfig };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0-next.97",
+    "version": "2.0.0-next.99",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -38,9 +38,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0-next.97",
-        "@friggframework/prettier-config": "2.0.0-next.97",
-        "@friggframework/test": "2.0.0-next.97",
+        "@friggframework/eslint-config": "2.0.0-next.99",
+        "@friggframework/prettier-config": "2.0.0-next.99",
+        "@friggframework/test": "2.0.0-next.99",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -80,5 +80,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "5595f797e6f65bb5a66dc96bfa1154f0d4c39504"
+    "gitHead": "a1f801371a7b6a06fc04819bfe08408a5165b75d"
 }

package/prisma-mongodb/schema.prisma

@@ -157,7 +157,7 @@ model Integration {
   id     String            @id @default(auto()) @map("_id") @db.ObjectId
   userId String?           @db.ObjectId
   user   User?             @relation(fields: [userId], references: [id], onDelete: Cascade)
-  status IntegrationStatus @default(ENABLED)
+  status IntegrationStatus @default(IN_CREATION)
 
   // Configuration and version
   config  Json? // Integration configuration object
@@ -193,6 +193,8 @@ enum IntegrationStatus {
   PROCESSING
   DISABLED
   ERROR
+  IN_CREATION
+  IN_DELETION
 }
 
 /// Integration-specific data mappings

package/prisma-postgresql/migrations/20260703000000_add_integration_status_in_creation_in_deletion/migration.sql

@@ -0,0 +1,11 @@
+-- Add IN_CREATION and IN_DELETION to the IntegrationStatus enum.
+-- Kept separate from the default change (next migration) because Postgres does
+-- not allow a newly added enum value to be referenced in the same transaction
+-- that adds it. Requires Postgres >= 12 (ADD VALUE ... IF NOT EXISTS).
+--
+-- Rollback note: once any row is written with status IN_CREATION or
+-- IN_DELETION, rolling the app back to a version whose Prisma client predates
+-- this migration will fail to read that row (unknown enum value). Backfill
+-- any such rows to a known status (e.g. ENABLED/ERROR) before rolling back.
+ALTER TYPE "IntegrationStatus" ADD VALUE IF NOT EXISTS 'IN_CREATION';
+ALTER TYPE "IntegrationStatus" ADD VALUE IF NOT EXISTS 'IN_DELETION';

package/prisma-postgresql/migrations/20260703000001_integration_status_default_in_creation/migration.sql

@@ -0,0 +1,8 @@
+-- New integrations are born IN_CREATION and transition to ENABLED / NEEDS_CONFIG
+-- once onCreate completes. Metadata-only change; existing rows are untouched.
+--
+-- Deploy-order note: if this app runs migrations via a post-deploy step (e.g.
+-- an explicit POST /db-migrate call) rather than pre-deploy, code that writes
+-- IN_CREATION/IN_DELETION will error on the enum value until both migrations
+-- in this pair have applied. Transient and retryable, not data-destructive.
+ALTER TABLE "Integration" ALTER COLUMN "status" SET DEFAULT 'IN_CREATION';

package/prisma-postgresql/schema.prisma

@@ -150,7 +150,7 @@ model Integration {
   id     Int               @id @default(autoincrement())
   userId Int?
   user   User?             @relation(fields: [userId], references: [id], onDelete: Cascade)
-  status IntegrationStatus @default(ENABLED)
+  status IntegrationStatus @default(IN_CREATION)
 
   // Configuration and version
   config  Json? // Integration configuration object
@@ -184,6 +184,8 @@ enum IntegrationStatus {
   PROCESSING
   DISABLED
   ERROR
+  IN_CREATION
+  IN_DELETION
 }
 
 /// Integration-specific data mappings

package/reporting/README.md

@@ -0,0 +1,86 @@
+# Reporting
+
+Read-only, deployment-wide reporting endpoints for `@friggframework/core`.
+Gated by a dedicated reporting API key — **not** the per-user auth used by the
+rest of the Management API.
+
+## Auth
+
+Send the reporting key in the `x-frigg-reporting-api-key` header. It is validated
+against the `REPORTING_API_KEY` environment variable. Missing or wrong key → `401`.
+
+## Endpoints
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `GET` | `/api/v2/reports` | Index of available reports. |
+| `GET` | `/api/v2/reports/integrations` | Integrations report (see below). |
+
+### `GET /api/v2/reports/integrations`
+
+Optional query params (all strings): `status` (an `IntegrationStatus`), `type`
+(`config.type` slug), `userId`.
+
+## Response shape
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "service": "frigg-core-api",
+  "generatedAt": "2026-06-29T20:45:05.142Z",
+  "filters": { "status": null, "type": null, "userId": null },
+  "metrics": {
+    "total": 12,
+    "byStatus": { "ENABLED": 9, "ERROR": 2, "NEEDS_CONFIG": 1, "PROCESSING": 0, "DISABLED": 0 },
+    "byType": [
+      {
+        "type": "hubspot",
+        "label": "HubSpot CRM",
+        "total": 5,
+        "byStatus": { "ENABLED": 4, "ERROR": 1, "NEEDS_CONFIG": 0, "PROCESSING": 0, "DISABLED": 0 }
+      }
+    ],
+    "typeLabels": { "hubspot": "HubSpot CRM" },
+    "integrations": [ /* lightweight per-integration rows */ ]
+  }
+}
+```
+
+## Field reference
+
+- `schemaVersion` — contract version; branch on it. Additive changes do **not** bump it.
+- `filters` — echoes the applied filters (nulls when omitted).
+- `metrics.total` — count of integrations matching the filters.
+- `metrics.byStatus` — counts keyed by `IntegrationStatus` value.
+- `metrics.byType[]` — per `type` breakdown: `{ type, label, total, byStatus }`.
+  - `type` — the `config.type` slug. Integrations with no type bucket as `"unknown"`.
+  - `label` — human-readable name from the integration class's
+    `Definition.display.label`. Falls back to the `type` slug when no registered
+    class supplies a label (e.g. an integration that was removed, or run on an
+    older app that doesn't register it). Additive — `type` is unchanged.
+- `metrics.typeLabels` — map of `type` slug → human-readable label, so callers can
+  label `integrations[].type` rows without bloating each row. Contains only types
+  whose registered class supplies a non-default `display.label` (classes still
+  carrying the IntegrationBase default `'Integration Name'` are excluded).
+- `metrics.integrations[]` — lightweight per-integration rows (`id`, `type`,
+  `status`, `userId`, `version`, `moduleCount`, `errorCount`, `mappedRecordCount`,
+  `createdAt`, `updatedAt`). These rows carry `type` only — resolve display names
+  via `metrics.typeLabels`.
+
+## How labels are sourced
+
+`createReportingRouter()` loads the app's registered integration classes via
+`loadAppDefinition()` and builds a `{ slug → label }` map from each class's
+`Definition.display.label`. Loading is wrapped in try/catch, so reporting still
+works (labels fall back to slugs) if the app definition can't be loaded. The
+`ListIntegrationsReport` use case stays storage-agnostic — it just reads the
+injected `typeLabels` map, so all database adapters (PostgreSQL, MongoDB,
+DocumentDB) get labels with zero adapter changes.
+
+## Caveats
+
+- The response is sensitive (exposes integration types, counts, user IDs, versions).
+  Treat the reporting key as an admin secret.
+- Read-only — no mutation endpoints.
+- Labels only appear once the deployment runs a `@friggframework/core` version that
+  includes this field and the app registers the integration classes.

package/reporting/reporting-router.js

@@ -4,11 +4,40 @@ const {
     createReportingRepository,
 } = require('./repositories/reporting-repository-factory');
 const { ListIntegrationsReport } = require('./use-cases/list-integrations-report');
+const { loadAppDefinition } = require('../handlers/app-definition-loader');
+
+// IntegrationBase.Definition default — skip it so the slug is used instead.
+const PLACEHOLDER_DISPLAY_NAME = 'Integration Name';
+
+// Map each integration's config.type slug to its human-readable display label.
+// Wrapped so reporting still works if the app definition fails to load.
+function buildTypeLabels() {
+    try {
+        const { integrations = [] } = loadAppDefinition();
+        const labels = {};
+        for (const IntegrationClass of integrations) {
+            const def = IntegrationClass?.Definition;
+            if (!def?.name) continue;
+            const label = def.display?.label;
+            if (label && label !== PLACEHOLDER_DISPLAY_NAME) {
+                labels[def.name] = label;
+            }
+        }
+        return labels;
+    } catch (error) {
+        console.error(
+            'Reporting: failed to load integration labels:',
+            error.message
+        );
+        return {};
+    }
+}
 
 function createReportingRouter() {
     const reportingRepository = createReportingRepository();
     const listIntegrationsReport = new ListIntegrationsReport({
         reportingRepository,
+        typeLabels: buildTypeLabels(),
     });
 
     const router = express.Router();

package/reporting/use-cases/list-integrations-report.js

@@ -6,19 +6,22 @@ const SERVICE = 'frigg-core-api';
 // Seeded so every known status appears (even at 0); unknown values added to
 // the schema later are still counted dynamically.
 const KNOWN_STATUSES = [
+    'IN_CREATION',
     'ENABLED',
     'ERROR',
     'NEEDS_CONFIG',
     'PROCESSING',
+    'IN_DELETION',
     'DISABLED',
 ];
 
 class ListIntegrationsReport {
-    constructor({ reportingRepository } = {}) {
+    constructor({ reportingRepository, typeLabels = {} } = {}) {
         if (!reportingRepository) {
             throw new Error('reportingRepository is required');
         }
         this.reportingRepository = reportingRepository;
+        this.typeLabels = typeLabels;
     }
 
     async execute(query = {}) {
@@ -64,6 +67,7 @@ class ListIntegrationsReport {
             if (!byTypeMap.has(integration.type)) {
                 byTypeMap.set(integration.type, {
                     type: integration.type,
+                    label: this.typeLabels[integration.type] || integration.type,
                     total: 0,
                     byStatus: emptyStatusCounts(),
                 });
@@ -86,6 +90,7 @@ class ListIntegrationsReport {
                 total: integrations.length,
                 byStatus,
                 byType: Array.from(byTypeMap.values()),
+                typeLabels: { ...this.typeLabels },
                 integrations,
             },
         };