@friggframework/core 2.0.0--canary.606.7fde0eb.0 → 2.0.0--canary.608.03436383054a.0

package/handlers/routers/reporting.js

@@ -0,0 +1,9 @@
+const { createReportingRouter } = require('@friggframework/core');
+const { createAppHandler } = require('./../app-handler-helpers');
+
+const router = createReportingRouter();
+
+// true → eager-connect Prisma; the reporting endpoints read the DB.
+const handler = createAppHandler('HTTP Event: Reporting', router, true);
+
+module.exports = { handler, router };

package/handlers/workers/user-action-worker.js

@@ -0,0 +1,155 @@
+const { Worker } = require('../../core/Worker');
+const {
+    GetIntegrationInstance,
+} = require('../../integrations/use-cases/get-integration-instance');
+const { ModuleFactory } = require('../../modules/module-factory');
+const {
+    createIntegrationRepository,
+} = require('../../integrations/repositories/integration-repository-factory');
+const {
+    createModuleRepository,
+} = require('../../modules/repositories/module-repository-factory');
+const {
+    getModulesDefinitionFromIntegrationClasses,
+} = require('../../integrations/utils/map-integration-dto');
+
+/**
+ * App-level worker for events dispatched with `dispatch: 'queue'`.
+ *
+ * A single Lambda serves every integration: messages arrive on the FIFO queue
+ * serialized per `MessageGroupId = integrationId`, so concurrent mutations for
+ * one integration run one-at-a-time. The worker re-hydrates the integration by
+ * id + owning user and runs `instance.send(event, data)` — byte-identical to
+ * the in-process (sync) path it replaces.
+ *
+ * Failure handling:
+ *  - missing ids / un-hydratable / id mismatch → HaltError (discard, no retry)
+ *  - handler throw → record ERROR status + a warning message, then rethrow so
+ *    SQS retries and ultimately routes to the FIFO DLQ.
+ *
+ * DISABLED/ERROR integrations are NOT discarded — these are user-initiated
+ * mutations (including ERROR recovery), unlike webhook/cron traffic.
+ */
+class UserActionWorker extends Worker {
+    constructor({ getIntegrationInstance } = {}) {
+        super();
+        this._getIntegrationInstance = getIntegrationInstance || null;
+    }
+
+    _validateParams(params) {
+        this._verifyParamExists(params, 'event');
+        this._verifyParamExists(params, 'data');
+    }
+
+    _resolveGetIntegrationInstance() {
+        if (this._getIntegrationInstance) return this._getIntegrationInstance;
+
+        const { loadAppDefinition } = require('../app-definition-loader');
+        const { integrations: integrationClasses } = loadAppDefinition();
+        const integrationRepository = createIntegrationRepository();
+        const moduleRepository = createModuleRepository();
+        const moduleFactory = new ModuleFactory({
+            moduleRepository,
+            moduleDefinitions:
+                getModulesDefinitionFromIntegrationClasses(integrationClasses),
+        });
+
+        this._getIntegrationInstance = new GetIntegrationInstance({
+            integrationRepository,
+            integrationClasses,
+            moduleFactory,
+        });
+        return this._getIntegrationInstance;
+    }
+
+    async _run(params) {
+        // Routing metadata is at the envelope top level; `data` is the exact
+        // handler payload (byte-identical to the sync path).
+        const { event, data = {}, integrationId, userId, requestId } = params;
+        const logCtx = { event, integrationId, userId, requestId };
+
+        if (!integrationId || !userId) {
+            const err = new Error(
+                '[UserActionWorker] message missing integrationId/userId'
+            );
+            err.isHaltError = true;
+            console.error(err.message, logCtx);
+            throw err;
+        }
+
+        const getIntegrationInstance = this._resolveGetIntegrationInstance();
+
+        let instance;
+        try {
+            instance = await getIntegrationInstance.execute(
+                integrationId,
+                userId
+            );
+        } catch (error) {
+            // Discard ONLY terminal failures (gone / not owned / unknown class)
+            // — no retry can ever succeed. Transient failures (DB blip, Prisma
+            // timeout, KMS throttle during credential decrypt) are NOT marked
+            // terminal, so they retry and ultimately reach the FIFO DLQ instead
+            // of being silently dropped.
+            if (error.isTerminal) {
+                error.isHaltError = true;
+                console.warn(
+                    `[UserActionWorker] integration ${integrationId} gone/invalid — discarding`,
+                    { ...logCtx, reason: error.message }
+                );
+            } else {
+                console.error(
+                    `[UserActionWorker] transient hydration failure for ${integrationId} — will retry`,
+                    { ...logCtx, reason: error.message }
+                );
+            }
+            throw error;
+        }
+
+        if (String(instance.id) !== String(integrationId)) {
+            const err = new Error(
+                `[UserActionWorker] hydrated id ${instance.id} != message integrationId ${integrationId}`
+            );
+            err.isHaltError = true;
+            console.error(err.message, logCtx);
+            throw err;
+        }
+
+        try {
+            console.log(`[UserActionWorker] dispatching ${event}`, logCtx);
+            const result = await instance.send(event, data);
+            console.log(`[UserActionWorker] ${event} ok`, logCtx);
+            return result;
+        } catch (error) {
+            try {
+                await instance.updateIntegrationStatus.execute(
+                    integrationId,
+                    'ERROR'
+                );
+                await instance.updateIntegrationMessages.execute(
+                    integrationId,
+                    'warnings',
+                    `Queued ${event} failed`,
+                    error.message,
+                    new Date().toISOString()
+                );
+            } catch (statusErr) {
+                console.error(
+                    '[UserActionWorker] failed to record error status/messages',
+                    { ...logCtx, statusErr: statusErr.message }
+                );
+            }
+            console.error(`[UserActionWorker] ${event} failed`, {
+                ...logCtx,
+                error: error.message,
+            });
+            throw error; // → SQS retry → FIFO DLQ
+        }
+    }
+}
+
+async function userActionQueueWorker(event, context) {
+    return new UserActionWorker().run(event, context);
+}
+
+module.exports = { UserActionWorker, userActionQueueWorker };

package/index.js

@@ -71,6 +71,10 @@ const {
     getModulesDefinitionFromIntegrationClasses,
     LoadIntegrationContextUseCase,
 } = require('./integrations/index');
+const {
+    createReportingRouter,
+    createReportingRepository,
+} = require('./reporting/index');
 const { TimeoutCatcher } = require('./lambda/index');
 const { debug, initDebugLog, flushDebugLog } = require('./logs/index');
 const {
@@ -87,6 +91,12 @@ const application = require('./application');
 const utils = require('./utils');
 
 const { QueuerUtil } = require('./queues');
+const {
+    dispatchIntegrationEvent,
+} = require('./integrations/use-cases/dispatch-integration-event');
+const {
+    userActionQueueWorker,
+} = require('./handlers/workers/user-action-worker');
 
 module.exports = {
     // assertions
@@ -133,12 +143,17 @@ module.exports = {
     checkRequiredParams,
     createIntegrationRouter,
     getModulesDefinitionFromIntegrationClasses,
+    dispatchIntegrationEvent,
     LoadIntegrationContextUseCase,
     CreateProcess,
     UpdateProcessState,
     UpdateProcessMetrics,
     GetProcess,
 
+    // reporting
+    createReportingRouter,
+    createReportingRepository,
+
     // application - Command factories for integration developers
     application,
     createFriggCommands: application.createFriggCommands,
@@ -172,6 +187,9 @@ module.exports = {
     // queues
     QueuerUtil,
 
+    // workers
+    userActionQueueWorker,
+
     // utils
     ...utils,
 };

package/integrations/integration-base.js

@@ -31,6 +31,13 @@ const constantsToBeMigrated = {
         LIFE_CYCLE_EVENT: 'LIFE_CYCLE_EVENT',
         USER_ACTION: 'USER_ACTION',
     },
+    // Per-event dispatch mode. 'sync' (default) runs the handler in-process and
+    // returns its result; 'queue' routes the event through the framework-owned
+    // FIFO queue, serialized by integrationId, returning a 202 ack.
+    dispatch: {
+        SYNC: 'sync',
+        QUEUE: 'queue',
+    },
 };
 
 class IntegrationBase {
@@ -521,6 +528,21 @@ class IntegrationBase {
             ...this.defaultEvents,
             ...this.events,
         };
+
+        // Apply Definition.eventDispatch onto the resolved handler entries. This
+        // lets a default lifecycle event (e.g. ON_UPDATE) be marked 'queue'
+        // without re-declaring its handler. An inline `dispatch` on the event
+        // entry always wins; unknown event names are ignored (a typo stays sync
+        // rather than crashing initialize()).
+        const eventDispatch = this.constructor.Definition?.eventDispatch || {};
+        for (const [eventName, mode] of Object.entries(eventDispatch)) {
+            if (this.on[eventName] && this.on[eventName].dispatch === undefined) {
+                this.on[eventName] = {
+                    ...this.on[eventName],
+                    dispatch: mode,
+                };
+            }
+        }
     }
 
     /**
@@ -608,6 +630,9 @@ class IntegrationBase {
                 this.events[eventName] = {
                     type: eventDef.type,
                     handler: fn.bind(this),
+                    ...(eventDef.dispatch !== undefined && {
+                        dispatch: eventDef.dispatch,
+                    }),
                 };
                 mergedByExtension.set(eventName, bindingName);
             }

package/integrations/integration-router.js

@@ -30,6 +30,9 @@ const {
     GetIntegrationInstance,
 } = require('./use-cases/get-integration-instance');
 const { UpdateIntegration } = require('./use-cases/update-integration');
+const {
+    dispatchIntegrationEvent,
+} = require('./use-cases/dispatch-integration-event');
 const {
     getModulesDefinitionFromIntegrationClasses,
 } = require('./utils/map-integration-dto');
@@ -293,6 +296,9 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
                 params.config
             );
 
+            if (integration?.queued) {
+                return res.status(202).json(integration);
+            }
             res.status(201).json(integration);
         })
     );
@@ -308,6 +314,9 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
                 userId,
                 params.config
             );
+            if (integration?.queued) {
+                return res.status(202).json(integration);
+            }
             res.json(integration);
         })
     );
@@ -425,7 +434,21 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
                 params.integrationId,
                 user.getId()
             );
-            res.json(await integration.send(params.actionId, req.body));
+            const outcome = await dispatchIntegrationEvent({
+                instance: integration,
+                event: params.actionId,
+                data: req.body,
+                userId: user.getId(),
+            });
+            if (outcome.queued) {
+                return res.status(202).json({
+                    queued: true,
+                    integrationId: integration.id,
+                    messageId: outcome.messageId,
+                    requestId: outcome.requestId,
+                });
+            }
+            res.json(outcome.result);
         })
     );
 

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

@@ -2,6 +2,7 @@
 const {
     mapIntegrationClassToIntegrationDTO,
 } = require('../utils/map-integration-dto');
+const { dispatchIntegrationEvent } = require('./dispatch-integration-event');
 
 /**
  * Use case for creating a new integration instance.
@@ -71,11 +72,26 @@ class CreateIntegration {
             modules,
         });
 
+        // ON_CREATE runs in-process by default. Routed through the dispatch
+        // helper so an integration can opt into dispatch:'queue' if desired;
+        // when queued, an ack is returned instead of the DTO.
         await integrationInstance.initialize();
-        await integrationInstance.send('ON_CREATE', {
-            integrationId: integrationRecord.id,
+        const outcome = await dispatchIntegrationEvent({
+            instance: integrationInstance,
+            event: 'ON_CREATE',
+            data: { integrationId: integrationRecord.id },
+            userId,
         });
 
+        if (outcome.queued) {
+            return {
+                queued: true,
+                integrationId: integrationInstance.id,
+                messageId: outcome.messageId,
+                requestId: outcome.requestId,
+            };
+        }
+
         return mapIntegrationClassToIntegrationDTO(integrationInstance);
     }
 }

package/integrations/use-cases/dispatch-integration-event.js

@@ -0,0 +1,76 @@
+const { v4: uuid } = require('uuid');
+const { QueuerUtil } = require('../../queues');
+
+const SCHEMA_VERSION = 1;
+
+// Default lifecycle events that MUTATE and may therefore be routed to the queue.
+// Read-shaped defaults (GET_*/REFRESH_*/WEBHOOK_RECEIVED) must never be queued —
+// a queued read would return a 202 ack instead of the data the caller expects.
+const MUTATING_DEFAULT_EVENTS = new Set([
+    'ON_CREATE',
+    'ON_UPDATE',
+    'ON_DELETE',
+]);
+
+// Custom user actions (events not present in defaultEvents) are mutating by
+// intent; only default events are filtered against the allowlist above.
+function isMutatingEvent(instance, event) {
+    if (!instance.defaultEvents || !instance.defaultEvents[event]) {
+        return true;
+    }
+    return MUTATING_DEFAULT_EVENTS.has(event);
+}
+
+/**
+ * Central producer decision for dispatching an integration event.
+ *
+ * If the event opts into `dispatch: 'queue'`, is a mutating event, and the
+ * framework queue is configured, the event is enqueued on the app-level FIFO
+ * queue (serialized per integrationId) and a `{ queued }` ack is returned.
+ * Otherwise the handler runs in-process and its result is returned. When the
+ * queue URL is missing we degrade gracefully to in-process execution.
+ *
+ * @param {Object} args
+ * @param {Object} args.instance - Initialized integration instance (has `on`, `id`, `send`).
+ * @param {string} args.event - Event name to dispatch.
+ * @param {Object} args.data - Payload passed to the handler / placed in the envelope.
+ * @param {string} args.userId - Owning user id (used by the worker to re-hydrate).
+ * @returns {Promise<{queued:true, messageId:string, requestId:string} | {result:any}>}
+ */
+async function dispatchIntegrationEvent({ instance, event, data, userId }) {
+    const mode = instance.on?.[event]?.dispatch;
+    const queueUrl = process.env.USER_ACTION_QUEUE_URL;
+
+    const eligible = mode === 'queue' && isMutatingEvent(instance, event);
+
+    if (eligible && !queueUrl) {
+        console.warn(
+            `[dispatchIntegrationEvent] event "${event}" requested dispatch:'queue' ` +
+                `but USER_ACTION_QUEUE_URL is not set — running in-process (sync)`
+        );
+    }
+
+    if (eligible && queueUrl) {
+        const requestId = uuid();
+        // Routing metadata lives at the envelope top level (alongside event),
+        // NOT inside `data`. `data` stays the exact handler payload the sync
+        // path passes, so the worker's send(event, data) is byte-identical.
+        const envelope = {
+            schemaVersion: SCHEMA_VERSION,
+            event,
+            integrationId: instance.id,
+            userId,
+            requestId,
+            data,
+        };
+        const result = await QueuerUtil.send(envelope, queueUrl, {
+            messageGroupId: instance.id,
+            messageDeduplicationId: requestId,
+        });
+        return { queued: true, messageId: result?.MessageId, requestId };
+    }
+
+    return { result: await instance.send(event, data) };
+}
+
+module.exports = { dispatchIntegrationEvent, SCHEMA_VERSION };

package/integrations/use-cases/get-integration-instance.js

@@ -31,9 +31,12 @@ class GetIntegrationInstance {
             await this.integrationRepository.findIntegrationById(integrationId);
 
         if (!integrationRecord) {
-            throw new Error(
+            const error = new Error(
                 `No integration found by the ID of ${integrationId}`
             );
+            // Terminal: the integration does not exist — no retry can succeed.
+            error.isTerminal = true;
+            throw error;
         }
 
         const integrationClass = this.integrationClasses.find(
@@ -43,15 +46,21 @@ class GetIntegrationInstance {
         );
 
         if (!integrationClass) {
-            throw new Error(
+            const error = new Error(
                 `No integration class found for type: ${integrationRecord.config.type}`
             );
+            // Terminal: the integration type is not registered — no retry helps.
+            error.isTerminal = true;
+            throw error;
         }
 
         if (integrationRecord.userId !== userId) {
-            throw new Error(
+            const error = new Error(
                 `Integration ${integrationId} does not belong to User ${userId}`
             );
+            // Terminal: ownership mismatch — no retry can succeed.
+            error.isTerminal = true;
+            throw error;
         }
 
         const modules = [];

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

@@ -1,6 +1,7 @@
 const {
     mapIntegrationClassToIntegrationDTO,
 } = require('../utils/map-integration-dto');
+const { dispatchIntegrationEvent } = require('./dispatch-integration-event');
 
 /**
  * Use case for updating a single integration by ID and user.
@@ -81,9 +82,26 @@ class UpdateIntegration {
             modules,
         });
 
-        // 5. Complete async initialization and trigger update event
+        // 5. Complete async initialization and dispatch the update event.
+        // When ON_UPDATE is marked dispatch:'queue', the update is enqueued
+        // (serialized per integration) and an ack is returned; otherwise it
+        // runs in-process and the updated DTO is returned (unchanged behavior).
         await integrationInstance.initialize();
-        await integrationInstance.send('ON_UPDATE', { config });
+        const outcome = await dispatchIntegrationEvent({
+            instance: integrationInstance,
+            event: 'ON_UPDATE',
+            data: { config },
+            userId,
+        });
+
+        if (outcome.queued) {
+            return {
+                queued: true,
+                integrationId: integrationInstance.id,
+                messageId: outcome.messageId,
+                requestId: outcome.requestId,
+            };
+        }
 
         return mapIntegrationClassToIntegrationDTO(integrationInstance);
     }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.606.7fde0eb.0",
+    "version": "2.0.0--canary.608.03436383054a.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.606.7fde0eb.0",
-        "@friggframework/prettier-config": "2.0.0--canary.606.7fde0eb.0",
-        "@friggframework/test": "2.0.0--canary.606.7fde0eb.0",
+        "@friggframework/eslint-config": "2.0.0--canary.608.03436383054a.0",
+        "@friggframework/prettier-config": "2.0.0--canary.608.03436383054a.0",
+        "@friggframework/test": "2.0.0--canary.608.03436383054a.0",
         "@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": "7fde0eb1c5ed7a7be35cb02b07dcba85ffef5b1c"
+    "gitHead": "03436383054a3ee70bd4de8f13a1907890a627da"
 }

package/queues/queuer-util.js

@@ -90,10 +90,19 @@ const inspectBatchResult = (result, queueUrl, buffer) => {
 };
 
 const QueuerUtil = {
-    send: async (message, queueUrl) => {
+    // `messageGroupId`/`messageDeduplicationId` are only used for FIFO queues.
+    // Standard sends omit them, so the command is byte-identical to before.
+    // FIFO queues require a deduplication id whenever ContentBasedDeduplication
+    // is off — we default to a uuid so every send is treated as distinct (two
+    // distinct requests with identical bodies must both run, not be dropped).
+    send: async (message, queueUrl, { messageGroupId, messageDeduplicationId } = {}) => {
         const command = new SendMessageCommand({
             MessageBody: JSON.stringify(message),
             QueueUrl: queueUrl,
+            ...(messageGroupId !== undefined && {
+                MessageGroupId: messageGroupId,
+                MessageDeduplicationId: messageDeduplicationId || uuid(),
+            }),
         });
         const result = await sqs.send(command);
         console.log(

package/reporting/index.js

@@ -0,0 +1,17 @@
+const { createReportingRouter } = require('./reporting-router');
+const {
+    createReportingRepository,
+    ReportingRepositoryMongo,
+    ReportingRepositoryPostgres,
+    ReportingRepositoryDocumentDB,
+} = require('./repositories/reporting-repository-factory');
+const { ListIntegrationsReport } = require('./use-cases');
+
+module.exports = {
+    createReportingRouter,
+    createReportingRepository,
+    ReportingRepositoryMongo,
+    ReportingRepositoryPostgres,
+    ReportingRepositoryDocumentDB,
+    ListIntegrationsReport,
+};

package/reporting/reporting-router.js

@@ -0,0 +1,48 @@
+const express = require('express');
+const catchAsyncError = require('express-async-handler');
+const {
+    createReportingRepository,
+} = require('./repositories/reporting-repository-factory');
+const { ListIntegrationsReport } = require('./use-cases/list-integrations-report');
+
+function createReportingRouter() {
+    const reportingRepository = createReportingRepository();
+    const listIntegrationsReport = new ListIntegrationsReport({
+        reportingRepository,
+    });
+
+    const router = express.Router();
+    router.use(validateApiKey);
+
+    router.get('/api/v2/reports', (_req, res) => {
+        res.json({ service: 'frigg-core-api', reports: ['integrations'] });
+    });
+
+    router.get(
+        '/api/v2/reports/integrations',
+        catchAsyncError(async (req, res) => {
+            const { status, type, userId } = req.query;
+            res.json(
+                await listIntegrationsReport.execute({ status, type, userId })
+            );
+        })
+    );
+
+    return router;
+}
+
+function validateApiKey(req, res, next) {
+    const apiKey = req.headers['x-frigg-reporting-api-key'];
+
+    if (!apiKey || apiKey !== process.env.REPORTING_API_KEY) {
+        console.error('Unauthorized access attempt to reporting endpoint');
+        return res.status(401).json({
+            status: 'error',
+            message: 'Unauthorized - x-frigg-reporting-api-key header required',
+        });
+    }
+
+    next();
+}
+
+module.exports = { createReportingRouter, validateApiKey };

package/reporting/repositories/reporting-repository-documentdb.js

@@ -0,0 +1,127 @@
+const { prisma } = require('../../database/prisma');
+const { toObjectId, fromObjectId } = require('../../database/documentdb-utils');
+const {
+    ReportingRepositoryInterface,
+} = require('./reporting-repository-interface');
+
+const DRAIN_BATCH_SIZE = 1000;
+const MAX_BATCHES = 100000;
+
+// Drains cursors via getMore rather than reusing documentdb-utils.findMany/
+// aggregate, which return only the first batch (~101 docs) and would silently
+// truncate a deployment-wide report.
+class ReportingRepositoryDocumentDB extends ReportingRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    async findIntegrationsForReport({ status, userId } = {}) {
+        const filter = {};
+        if (status) filter.status = status;
+        if (userId !== undefined && userId !== null) {
+            const objectId = toObjectId(userId);
+            // An invalid userId means no matches — must not fall through to an
+            // unfiltered query that returns the whole deployment.
+            if (!objectId) return [];
+            filter.userId = objectId;
+        }
+
+        const docs = await this._findDrained('Integration', filter);
+
+        return docs.map((doc) => {
+            const errors = this._extractErrors(doc);
+            return {
+                id: fromObjectId(doc?._id),
+                type: doc?.config?.type ?? null,
+                status: doc?.status ?? null,
+                userId: fromObjectId(doc?.userId) ?? null,
+                version: doc?.version ?? null,
+                errorCount: Array.isArray(errors) ? errors.length : 0,
+                moduleCount: Array.isArray(doc?.entityIds)
+                    ? doc.entityIds.length
+                    : 0,
+                createdAt: doc?.createdAt ?? null,
+                updatedAt: doc?.updatedAt ?? null,
+            };
+        });
+    }
+
+    async countMappingsByIntegrationIds(ids = []) {
+        const counts = new Map();
+        if (!ids || ids.length === 0) return counts;
+
+        // IntegrationMapping.integrationId is stored as a string in DocumentDB,
+        // so match by string — an ObjectId $in would never match (always 0).
+        const stringIds = ids.map(String);
+
+        const rows = await this._aggregateDrained('IntegrationMapping', [
+            { $match: { integrationId: { $in: stringIds } } },
+            { $group: { _id: '$integrationId', count: { $sum: 1 } } },
+        ]);
+
+        for (const row of rows) {
+            counts.set(String(row?._id), row?.count ?? 0);
+        }
+        return counts;
+    }
+
+    async _findDrained(collection, filter) {
+        const first = await this.prisma.$runCommandRaw({
+            find: collection,
+            filter,
+            batchSize: DRAIN_BATCH_SIZE,
+        });
+        return this._drain(collection, first);
+    }
+
+    async _aggregateDrained(collection, pipeline) {
+        const first = await this.prisma.$runCommandRaw({
+            aggregate: collection,
+            pipeline,
+            cursor: { batchSize: DRAIN_BATCH_SIZE },
+        });
+        return this._drain(collection, first);
+    }
+
+    async _drain(collection, firstResult) {
+        const cursor = firstResult?.cursor || {};
+        const docs = [...(cursor.firstBatch || [])];
+        let cursorId = cursor.id;
+        let batches = 0;
+
+        while (this._cursorOpen(cursorId) && batches < MAX_BATCHES) {
+            batches += 1;
+            const next = await this.prisma.$runCommandRaw({
+                getMore: cursorId,
+                collection,
+                batchSize: DRAIN_BATCH_SIZE,
+            });
+            const nextCursor = next?.cursor || {};
+            const nextBatch = nextCursor.nextBatch || [];
+            docs.push(...nextBatch);
+            cursorId = nextCursor.id;
+            if (nextBatch.length === 0) break;
+        }
+        return docs;
+    }
+
+    _cursorOpen(id) {
+        if (id === undefined || id === null) return false;
+        if (typeof id === 'number') return id !== 0;
+        if (typeof id === 'bigint') return id !== 0n;
+        // Extended JSON can surface a 64-bit cursor id as { $numberLong: "..." }.
+        if (typeof id === 'object' && id.$numberLong !== undefined) {
+            return id.$numberLong !== '0';
+        }
+        return String(id) !== '0';
+    }
+
+    _extractErrors(doc) {
+        if (Array.isArray(doc?.errors)) return doc.errors;
+        if (Array.isArray(doc?.messages?.errors)) return doc.messages.errors;
+        return [];
+    }
+}
+
+module.exports = { ReportingRepositoryDocumentDB };

package/reporting/repositories/reporting-repository-factory.js

@@ -0,0 +1,35 @@
+const { ReportingRepositoryMongo } = require('./reporting-repository-mongo');
+const {
+    ReportingRepositoryPostgres,
+} = require('./reporting-repository-postgres');
+const {
+    ReportingRepositoryDocumentDB,
+} = require('./reporting-repository-documentdb');
+const config = require('../../database/config');
+
+function createReportingRepository() {
+    const dbType = config.DB_TYPE;
+
+    switch (dbType) {
+        case 'mongodb':
+            return new ReportingRepositoryMongo();
+
+        case 'postgresql':
+            return new ReportingRepositoryPostgres();
+
+        case 'documentdb':
+            return new ReportingRepositoryDocumentDB();
+
+        default:
+            throw new Error(
+                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
+            );
+    }
+}
+
+module.exports = {
+    createReportingRepository,
+    ReportingRepositoryMongo,
+    ReportingRepositoryPostgres,
+    ReportingRepositoryDocumentDB,
+};

package/reporting/repositories/reporting-repository-interface.js

@@ -0,0 +1,16 @@
+class ReportingRepositoryInterface {
+    // returns: [{ id, type, status, userId, version, errorCount, moduleCount, createdAt, updatedAt }]
+    async findIntegrationsForReport(filter) {
+        throw new Error(
+            'Method findIntegrationsForReport must be implemented by subclass'
+        );
+    }
+
+    async countMappingsByIntegrationIds(ids) {
+        throw new Error(
+            'Method countMappingsByIntegrationIds must be implemented by subclass'
+        );
+    }
+}
+
+module.exports = { ReportingRepositoryInterface };

package/reporting/repositories/reporting-repository-mongo.js

@@ -0,0 +1,54 @@
+const { prisma } = require('../../database/prisma');
+const {
+    ReportingRepositoryInterface,
+} = require('./reporting-repository-interface');
+
+class ReportingRepositoryMongo extends ReportingRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    async findIntegrationsForReport({ status, userId } = {}) {
+        const where = {};
+        if (status) where.status = status;
+        if (userId !== undefined && userId !== null) where.userId = userId;
+
+        const integrations = await this.prisma.integration.findMany({
+            where,
+            include: { entities: { select: { id: true } } },
+        });
+
+        return integrations.map((integration) => ({
+            id: integration.id,
+            type: integration.config?.type ?? null,
+            status: integration.status ?? null,
+            userId: integration.userId ?? null,
+            version: integration.version ?? null,
+            errorCount: Array.isArray(integration.errors)
+                ? integration.errors.length
+                : 0,
+            moduleCount: integration.entities?.length ?? 0,
+            createdAt: integration.createdAt ?? null,
+            updatedAt: integration.updatedAt ?? null,
+        }));
+    }
+
+    async countMappingsByIntegrationIds(ids = []) {
+        const counts = new Map();
+        if (!ids || ids.length === 0) return counts;
+
+        const groups = await this.prisma.integrationMapping.groupBy({
+            by: ['integrationId'],
+            where: { integrationId: { in: ids } },
+            _count: { _all: true },
+        });
+
+        for (const group of groups) {
+            counts.set(group.integrationId, group._count._all);
+        }
+        return counts;
+    }
+}
+
+module.exports = { ReportingRepositoryMongo };

package/reporting/repositories/reporting-repository-postgres.js

@@ -0,0 +1,70 @@
+const { prisma } = require('../../database/prisma');
+const {
+    ReportingRepositoryInterface,
+} = require('./reporting-repository-interface');
+
+class ReportingRepositoryPostgres extends ReportingRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    async findIntegrationsForReport({ status, userId } = {}) {
+        const where = {};
+        if (status) where.status = status;
+        if (userId !== undefined && userId !== null) {
+            where.userId = this._convertId(userId);
+        }
+
+        const integrations = await this.prisma.integration.findMany({
+            where,
+            include: { entities: { select: { id: true } } },
+        });
+
+        return integrations.map((integration) => ({
+            id: integration.id?.toString(),
+            type: integration.config?.type ?? null,
+            status: integration.status ?? null,
+            userId: integration.userId?.toString() ?? null,
+            version: integration.version ?? null,
+            errorCount: Array.isArray(integration.errors)
+                ? integration.errors.length
+                : 0,
+            moduleCount: integration.entities?.length ?? 0,
+            createdAt: integration.createdAt ?? null,
+            updatedAt: integration.updatedAt ?? null,
+        }));
+    }
+
+    async countMappingsByIntegrationIds(ids = []) {
+        const counts = new Map();
+        if (!ids || ids.length === 0) return counts;
+
+        const intIds = ids.map((id) => this._convertId(id));
+        const groups = await this.prisma.integrationMapping.groupBy({
+            by: ['integrationId'],
+            where: { integrationId: { in: intIds } },
+            _count: { _all: true },
+        });
+
+        for (const group of groups) {
+            counts.set(group.integrationId?.toString(), group._count._all);
+        }
+        return counts;
+    }
+
+    _convertId(id) {
+        if (id === null || id === undefined) return id;
+        // Reject anything that isn't an exact integer — parseInt would coerce
+        // '12abc'/'12.9' to 12 and return the wrong record.
+        const str = String(id).trim();
+        if (!/^-?\d+$/.test(str)) {
+            throw new TypeError(
+                `Invalid ID: ${id} cannot be converted to integer`
+            );
+        }
+        return Number.parseInt(str, 10);
+    }
+}
+
+module.exports = { ReportingRepositoryPostgres };

package/reporting/use-cases/index.js

@@ -0,0 +1,6 @@
+const {
+    ListIntegrationsReport,
+    SCHEMA_VERSION,
+} = require('./list-integrations-report');
+
+module.exports = { ListIntegrationsReport, SCHEMA_VERSION };

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

@@ -0,0 +1,137 @@
+const Boom = require('@hapi/boom');
+
+const SCHEMA_VERSION = 1;
+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 = [
+    'ENABLED',
+    'ERROR',
+    'NEEDS_CONFIG',
+    'PROCESSING',
+    'DISABLED',
+];
+
+class ListIntegrationsReport {
+    constructor({ reportingRepository } = {}) {
+        if (!reportingRepository) {
+            throw new Error('reportingRepository is required');
+        }
+        this.reportingRepository = reportingRepository;
+    }
+
+    async execute(query = {}) {
+        const { status, type, userId } = this._validateQuery(query);
+
+        const rows = await this.reportingRepository.findIntegrationsForReport({
+            status,
+            userId,
+        });
+
+        // type lives in config.type (a JSON path not portably groupable across
+        // DBs), so it is filtered here rather than in the repository query.
+        const filtered =
+            type === undefined
+                ? rows
+                : rows.filter((row) => (row.type ?? 'unknown') === type);
+
+        const ids = filtered.map((row) => row.id);
+        const mappingCounts = ids.length
+            ? await this.reportingRepository.countMappingsByIntegrationIds(ids)
+            : new Map();
+
+        const integrations = filtered.map((row) => ({
+            id: row.id,
+            type: row.type ?? 'unknown',
+            status: row.status ?? null,
+            userId: row.userId ?? null,
+            version: row.version ?? null,
+            moduleCount: row.moduleCount ?? 0,
+            errorCount: row.errorCount ?? 0,
+            mappedRecordCount: mappingCounts.get(row.id) ?? 0,
+            createdAt: toIso(row.createdAt),
+            updatedAt: toIso(row.updatedAt),
+        }));
+
+        const byStatus = emptyStatusCounts();
+        const byTypeMap = new Map();
+        for (const integration of integrations) {
+            // sentinel so a missing status never becomes a literal "null" key
+            const statusKey = integration.status ?? 'UNKNOWN';
+            byStatus[statusKey] = (byStatus[statusKey] ?? 0) + 1;
+
+            if (!byTypeMap.has(integration.type)) {
+                byTypeMap.set(integration.type, {
+                    type: integration.type,
+                    total: 0,
+                    byStatus: emptyStatusCounts(),
+                });
+            }
+            const bucket = byTypeMap.get(integration.type);
+            bucket.total += 1;
+            bucket.byStatus[statusKey] = (bucket.byStatus[statusKey] ?? 0) + 1;
+        }
+
+        return {
+            schemaVersion: SCHEMA_VERSION,
+            service: SERVICE,
+            generatedAt: new Date().toISOString(),
+            filters: {
+                status: status ?? null,
+                type: type ?? null,
+                userId: userId ?? null,
+            },
+            metrics: {
+                total: integrations.length,
+                byStatus,
+                byType: Array.from(byTypeMap.values()),
+                integrations,
+            },
+        };
+    }
+
+    _validateQuery({ status, type, userId } = {}) {
+        for (const [key, value] of Object.entries({ status, type, userId })) {
+            if (value !== undefined && value !== null && typeof value !== 'string') {
+                throw Boom.badRequest(
+                    `Invalid query parameter '${key}': expected a string`
+                );
+            }
+        }
+        const normalize = (value) => value || undefined;
+        const normalized = {
+            status: normalize(status),
+            type: normalize(type),
+            userId: normalize(userId),
+        };
+        if (normalized.status && !KNOWN_STATUSES.includes(normalized.status)) {
+            throw Boom.badRequest(
+                `Invalid status '${normalized.status}'. Expected one of: ${KNOWN_STATUSES.join(
+                    ', '
+                )}`
+            );
+        }
+        return normalized;
+    }
+}
+
+function emptyStatusCounts() {
+    return KNOWN_STATUSES.reduce((acc, status) => {
+        acc[status] = 0;
+        return acc;
+    }, {});
+}
+
+function toIso(value) {
+    if (!value) return null;
+    if (value instanceof Date) return value.toISOString();
+    // DocumentDB raw reads surface dates as { $date: ... }
+    if (typeof value === 'object' && value.$date) {
+        const date = new Date(value.$date);
+        return Number.isNaN(date.getTime()) ? null : date.toISOString();
+    }
+    return String(value);
+}
+
+module.exports = { ListIntegrationsReport, SCHEMA_VERSION };