@friggframework/core 2.0.0-next.94 → 2.0.0-next.95

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/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 {
@@ -139,6 +143,10 @@ module.exports = {
     UpdateProcessMetrics,
     GetProcess,
 
+    // reporting
+    createReportingRouter,
+    createReportingRepository,
+
     // application - Command factories for integration developers
     application,
     createFriggCommands: application.createFriggCommands,

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0-next.94",
+    "version": "2.0.0-next.95",
     "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.94",
-        "@friggframework/prettier-config": "2.0.0-next.94",
-        "@friggframework/test": "2.0.0-next.94",
+        "@friggframework/eslint-config": "2.0.0-next.95",
+        "@friggframework/prettier-config": "2.0.0-next.95",
+        "@friggframework/test": "2.0.0-next.95",
         "@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": "c56f6a892e1861d5f495bf15d1008834a9258a1d"
+    "gitHead": "18d7e66ce7f397ad6e96d9006d81118cd96445ec"
 }

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 };