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

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.98",
     "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.98",
+        "@friggframework/prettier-config": "2.0.0-next.98",
+        "@friggframework/test": "2.0.0-next.98",
         "@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": "da2c1977216b9f939121b18d8461cc4e8a5b2b94"
 }

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

@@ -14,11 +14,12 @@ const KNOWN_STATUSES = [
 ];
 
 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 +65,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 +88,7 @@ class ListIntegrationsReport {
                 total: integrations.length,
                 byStatus,
                 byType: Array.from(byTypeMap.values()),
+                typeLabels: { ...this.typeLabels },
                 integrations,
             },
         };