@friggframework/core 2.0.0--canary.548.c8ae0ca.0 → 2.0.0--canary.545.c40eca4.0

package/handlers/routers/db-migration.js

@@ -4,12 +4,14 @@
  * HTTP API for triggering and monitoring database migrations.
  *
  * Endpoints:
- * - GET /db-migrate/status - Check if migrations are pending
- * - POST /db-migrate - Trigger async migration (queues job)
- * - GET /db-migrate/:processId - Check migration status
+ * - GET /admin/db-migrate/status - Check if migrations are pending
+ * - POST /admin/db-migrate - Trigger async migration (queues job)
+ * - GET /admin/db-migrate/:processId - Check migration status
+ * - POST /admin/db-migrate/resolve - Resolve failed migration
  *
  * Security:
- * - Requires ADMIN_API_KEY header for all requests
+ * - Requires x-frigg-admin-api-key header for all requests
+ * - Uses shared validateAdminApiKey middleware
  *
  * Architecture:
  * - Router (Adapter Layer) → Use Cases (Domain) → Repositories (Infrastructure)
@@ -18,7 +20,8 @@
 
 const { Router } = require('express');
 const catchAsyncError = require('express-async-handler');
-const { MigrationStatusRepositoryS3 } = require('../../database/repositories/migration-status-repository-s3');
+const { validateAdminApiKey } = require('../middleware/admin-auth');
+const { resolveProvider } = require('../../providers/resolve-provider');
 const {
     TriggerDatabaseMigrationUseCase,
     ValidationError: TriggerValidationError,
@@ -28,57 +31,77 @@ const {
     ValidationError: GetValidationError,
     NotFoundError,
 } = require('../../database/use-cases/get-migration-status-use-case');
-const { LambdaInvoker } = require('../../database/adapters/lambda-invoker');
 const {
     GetDatabaseStateViaWorkerUseCase,
 } = require('../../database/use-cases/get-database-state-via-worker-use-case');
 
 const router = Router();
 
-// Dependency injection
-// Use S3 repository to avoid User table dependency (chicken-and-egg problem)
-const bucketName = process.env.S3_BUCKET_NAME || process.env.MIGRATION_STATUS_BUCKET;
-const migrationStatusRepository = new MigrationStatusRepositoryS3(bucketName);
-
-const triggerMigrationUseCase = new TriggerDatabaseMigrationUseCase({
-    migrationStatusRepository,
-    // Note: QueuerUtil is used directly in the use case (static utility)
-});
-const getStatusUseCase = new GetMigrationStatusUseCase({ migrationStatusRepository });
-
-// Lambda invocation for database state check (keeps router lightweight)
-const lambdaInvoker = new LambdaInvoker();
-const workerFunctionName = process.env.WORKER_FUNCTION_NAME ||
-    `${process.env.SERVICE || 'unknown'}-${process.env.STAGE || 'production'}-dbMigrationWorker`;
-
-const getDatabaseStateUseCase = new GetDatabaseStateViaWorkerUseCase({
-    lambdaInvoker,
-    workerFunctionName,
-});
+// Dependency injection — lazy-initialized on first request.
+// Uses resolveProvider() to get the correct adapters for the active platform.
+let _migrationStatusRepository = null;
+let _triggerMigrationUseCase = null;
+let _getStatusUseCase = null;
+let _functionInvoker = null;
+
+function getMigrationDeps() {
+    if (!_migrationStatusRepository) {
+        const provider = resolveProvider();
+
+        // Migration status storage (AWS: S3, others: provider-specific)
+        const MigrationStatusRepository = provider.MigrationStatusRepositoryS3;
+        if (!MigrationStatusRepository) {
+            throw new Error(
+                `Provider '${provider.name}' does not export a MigrationStatusRepository`
+            );
+        }
+        const bucketName =
+            process.env.S3_BUCKET_NAME || process.env.MIGRATION_STATUS_BUCKET;
+        _migrationStatusRepository = new MigrationStatusRepository(bucketName);
+        _triggerMigrationUseCase = new TriggerDatabaseMigrationUseCase({
+            migrationStatusRepository: _migrationStatusRepository,
+        });
+        _getStatusUseCase = new GetMigrationStatusUseCase({
+            migrationStatusRepository: _migrationStatusRepository,
+        });
 
-/**
- * Admin API key validation middleware
- * Matches pattern from health.js:72-88
- */
-const validateApiKey = (req, res, next) => {
-    const apiKey = req.headers['x-frigg-admin-api-key'];
-
-    if (!apiKey || apiKey !== process.env.ADMIN_API_KEY) {
-        console.error('Unauthorized access attempt to db-migrate endpoint');
-        return res.status(401).json({
-            status: 'error',
-            message: 'Unauthorized - x-frigg-admin-api-key header required',
+        // Function invoker (AWS: LambdaInvoker, Netlify: HTTP-based)
+        _functionInvoker = provider.invokeFunctionAdapter;
+        if (!_functionInvoker) {
+            throw new Error(
+                `Provider '${provider.name}' does not export an invokeFunctionAdapter`
+            );
+        }
+    }
+    return {
+        migrationStatusRepository: _migrationStatusRepository,
+        triggerMigrationUseCase: _triggerMigrationUseCase,
+        getStatusUseCase: _getStatusUseCase,
+        lambdaInvoker: _functionInvoker,
+    };
+}
+let _getDatabaseStateUseCase = null;
+function getDatabaseStateUseCaseInstance() {
+    if (!_getDatabaseStateUseCase) {
+        const { lambdaInvoker } = getMigrationDeps();
+        const workerFunctionName =
+            process.env.WORKER_FUNCTION_NAME ||
+            `${process.env.SERVICE || 'unknown'}-${
+                process.env.STAGE || 'production'
+            }-dbMigrationWorker`;
+        _getDatabaseStateUseCase = new GetDatabaseStateViaWorkerUseCase({
+            lambdaInvoker,
+            workerFunctionName,
         });
     }
+    return _getDatabaseStateUseCase;
+}
 
-    next();
-};
-
-// Apply API key validation to all routes
-router.use(validateApiKey);
+// Apply admin API key validation to all routes (shared middleware)
+router.use(validateAdminApiKey);
 
 /**
- * POST /db-migrate
+ * POST /admin/db-migrate
  *
  * Trigger database migration (async via SQS queue)
  *
@@ -99,17 +122,21 @@ router.use(validateApiKey);
  * }
  */
 router.post(
-    '/db-migrate',
+    '/admin/db-migrate',
     catchAsyncError(async (req, res) => {
         const dbType = req.body.dbType || process.env.DB_TYPE || 'postgresql';
         const { stage } = req.body;
         // TODO: Extract userId from JWT token when auth is implemented
         const userId = req.body.userId || 'admin';
 
-        console.log(`Migration trigger request: dbType=${dbType}, stage=${stage || 'auto-detect'}, userId=${userId}`);
+        console.log(
+            `Migration trigger request: dbType=${dbType}, stage=${
+                stage || 'auto-detect'
+            }, userId=${userId}`
+        );
 
         try {
-            const result = await triggerMigrationUseCase.execute({
+            const result = await getMigrationDeps().triggerMigrationUseCase.execute({
                 userId,
                 dbType,
                 stage,
@@ -133,10 +160,10 @@ router.post(
 );
 
 /**
- * GET /db-migrate/status
+ * GET /admin/db-migrate/status
  *
  * Check if database has pending migrations
- * 
+ *
  * Query params:
  * - stage: string (optional, defaults to STAGE env var or 'production')
  *
@@ -151,15 +178,17 @@ router.post(
  * }
  */
 router.get(
-    '/db-migrate/status',
+    '/admin/db-migrate/status',
     catchAsyncError(async (req, res) => {
         const stage = req.query.stage || process.env.STAGE || 'production';
 
-        console.log(`Checking database state: stage=${stage}, worker=${workerFunctionName}`);
+        console.log(
+            `Checking database state: stage=${stage}`
+        );
 
         try {
             // Invoke worker Lambda to check database state
-            const status = await getDatabaseStateUseCase.execute(stage);
+            const status = await getDatabaseStateUseCaseInstance().execute(stage);
 
             res.status(200).json(status);
         } catch (error) {
@@ -177,7 +206,7 @@ router.get(
 );
 
 /**
- * GET /db-migrate/:migrationId
+ * GET /admin/db-migrate/:migrationId
  *
  * Get migration status by migration ID
  *
@@ -201,15 +230,17 @@ router.get(
  * }
  */
 router.get(
-    '/db-migrate/:migrationId',
+    '/admin/db-migrate/:migrationId',
     catchAsyncError(async (req, res) => {
         const { migrationId } = req.params;
         const stage = req.query.stage || process.env.STAGE || 'production';
 
-        console.log(`Migration status request: migrationId=${migrationId}, stage=${stage}`);
+        console.log(
+            `Migration status request: migrationId=${migrationId}, stage=${stage}`
+        );
 
         try {
-            const status = await getStatusUseCase.execute(migrationId, stage);
+            const status = await getMigrationDeps().getStatusUseCase.execute(migrationId, stage);
 
             res.status(200).json(status);
         } catch (error) {
@@ -236,7 +267,7 @@ router.get(
 );
 
 /**
- * POST /db-migrate/resolve
+ * POST /admin/db-migrate/resolve
  *
  * Resolve a failed migration by marking it as applied or rolled back
  *
@@ -256,24 +287,26 @@ router.get(
  * }
  */
 router.post(
-    '/db-migrate/resolve',
+    '/admin/db-migrate/resolve',
     catchAsyncError(async (req, res) => {
         const { migrationName, action = 'applied' } = req.body;
 
-        console.log(`Migration resolve request: migration=${migrationName}, action=${action}`);
+        console.log(
+            `Migration resolve request: migration=${migrationName}, action=${action}`
+        );
 
         // Validation
         if (!migrationName) {
             return res.status(400).json({
                 success: false,
-                error: 'migrationName is required'
+                error: 'migrationName is required',
             });
         }
 
         if (!['applied', 'rolled-back'].includes(action)) {
             return res.status(400).json({
                 success: false,
-                error: 'action must be either "applied" or "rolled-back"'
+                error: 'action must be either "applied" or "rolled-back"',
             });
         }
 
@@ -281,12 +314,16 @@ router.post(
             // Import prismaRunner here to avoid circular dependencies
             const prismaRunner = require('../../database/utils/prisma-runner');
 
-            const result = await prismaRunner.runPrismaMigrateResolve(migrationName, action, true);
+            const result = await prismaRunner.runPrismaMigrateResolve(
+                migrationName,
+                action,
+                true
+            );
 
             if (!result.success) {
                 return res.status(500).json({
                     success: false,
-                    error: `Failed to resolve migration: ${result.error}`
+                    error: `Failed to resolve migration: ${result.error}`,
                 });
             }
 
@@ -294,13 +331,13 @@ router.post(
                 success: true,
                 message: `Migration ${migrationName} marked as ${action}`,
                 migrationName,
-                action
+                action,
             });
         } catch (error) {
             console.error('Migration resolve failed:', error);
             return res.status(500).json({
                 success: false,
-                error: error.message
+                error: error.message,
             });
         }
     })
@@ -323,4 +360,3 @@ app.use((err, _req, res, _next) => {
 const handler = serverlessHttp(app);
 
 module.exports = { handler, router };
-

package/handlers/routers/docs.js

@@ -0,0 +1,180 @@
+/**
+ * API Documentation Router
+ *
+ * Serves dynamic OpenAPI specs and Scalar UI documentation for both v1 and v2 APIs.
+ * Specs are generated dynamically based on appDefinition and installed modules.
+ *
+ * Endpoints:
+ * - GET /api/docs - Main documentation UI with version selector
+ * - GET /api/v1/docs - v1-specific documentation
+ * - GET /api/v2/docs - v2-specific documentation
+ * - GET /api/openapi.json - v2 spec (default/current)
+ * - GET /api/openapi-v1.json - v1 spec
+ * - GET /api/openapi-v2.json - v2 spec
+ */
+
+const { Router } = require('express');
+const { createAppHandler } = require('./../app-handler-helpers');
+const {
+    generateOpenApiSpec,
+    generateOpenApiSpecV1,
+    generateOpenApiSpecV2,
+} = require('../../openapi/openapi-spec-generator');
+
+const router = Router();
+
+let cachedAppDefinition = null;
+
+/**
+ * Load the appDefinition for spec generation
+ * Lazy-loads and caches to avoid performance overhead
+ */
+function loadAppDefinitionForDocs() {
+    if (cachedAppDefinition) return cachedAppDefinition;
+
+    try {
+        const { loadAppDefinition } = require('../app-definition-loader');
+        const { integrations } = loadAppDefinition();
+        cachedAppDefinition = { integrations };
+        return cachedAppDefinition;
+    } catch (error) {
+        // App definition not available (e.g., in test environment)
+        return null;
+    }
+}
+
+/**
+ * Generate Scalar HTML with version selector
+ * @param {Object} options - Configuration options
+ * @param {string} options.specUrl - Primary spec URL
+ * @param {Array} options.sources - Array of spec sources for version selector
+ * @param {string} options.title - Page title
+ */
+function generateScalarHtml({
+    specUrl,
+    sources,
+    title = 'Frigg API Documentation',
+}) {
+    // If sources provided, use multi-spec configuration
+    const config = sources ? { sources } : { url: specUrl };
+
+    return `<!DOCTYPE html>
+<html>
+<head>
+    <title>${title}</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style>
+        body { margin: 0; padding: 0; }
+    </style>
+</head>
+<body>
+    <script id="api-reference" data-configuration='${JSON.stringify(
+        config
+    )}'></script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+</body>
+</html>`;
+}
+
+// ============================================================================
+// OpenAPI Spec Endpoints
+// ============================================================================
+
+/**
+ * GET /api/openapi.json - Default (v2) OpenAPI spec
+ */
+router.get('/api/openapi.json', (req, res) => {
+    try {
+        const serverUrl = `${req.protocol}://${req.get('host')}`;
+        const appDefinition = loadAppDefinitionForDocs();
+        const spec = generateOpenApiSpecV2(appDefinition, { serverUrl });
+        res.json(spec);
+    } catch (error) {
+        console.error('Failed to generate OpenAPI spec:', error.message);
+        res.status(500).json({ error: 'Failed to load API specification' });
+    }
+});
+
+/**
+ * GET /api/openapi-v1.json - v1 API OpenAPI spec
+ */
+router.get('/api/openapi-v1.json', (req, res) => {
+    try {
+        const serverUrl = `${req.protocol}://${req.get('host')}`;
+        const appDefinition = loadAppDefinitionForDocs();
+        const spec = generateOpenApiSpecV1(appDefinition, { serverUrl });
+        res.json(spec);
+    } catch (error) {
+        console.error('Failed to generate v1 OpenAPI spec:', error.message);
+        res.status(500).json({ error: 'Failed to load API specification' });
+    }
+});
+
+/**
+ * GET /api/openapi-v2.json - v2 API OpenAPI spec
+ */
+router.get('/api/openapi-v2.json', (req, res) => {
+    try {
+        const serverUrl = `${req.protocol}://${req.get('host')}`;
+        const appDefinition = loadAppDefinitionForDocs();
+        const spec = generateOpenApiSpecV2(appDefinition, { serverUrl });
+        res.json(spec);
+    } catch (error) {
+        console.error('Failed to generate v2 OpenAPI spec:', error.message);
+        res.status(500).json({ error: 'Failed to load API specification' });
+    }
+});
+
+// ============================================================================
+// Documentation UI Endpoints
+// ============================================================================
+
+/**
+ * GET /api/docs - Main documentation with version selector
+ * Shows both v1 and v2 APIs with a dropdown to switch between them
+ */
+router.get('/api/docs', (_req, res) => {
+    const html = generateScalarHtml({
+        sources: [
+            {
+                title: 'API v2 (Current)',
+                slug: 'v2',
+                url: '/api/openapi-v2.json',
+            },
+            {
+                title: 'API v1 (Legacy)',
+                slug: 'v1',
+                url: '/api/openapi-v1.json',
+            },
+        ],
+        title: 'Frigg API Documentation',
+    });
+    res.type('html').send(html);
+});
+
+/**
+ * GET /api/v1/docs - v1-specific documentation
+ */
+router.get('/api/v1/docs', (_req, res) => {
+    const html = generateScalarHtml({
+        specUrl: '/api/openapi-v1.json',
+        title: 'Frigg API v1 Documentation',
+    });
+    res.type('html').send(html);
+});
+
+/**
+ * GET /api/v2/docs - v2-specific documentation
+ */
+router.get('/api/v2/docs', (_req, res) => {
+    const html = generateScalarHtml({
+        specUrl: '/api/openapi-v2.json',
+        title: 'Frigg API v2 Documentation',
+    });
+    res.type('html').send(html);
+});
+
+const handler = createAppHandler('HTTP Event: Docs', router, false);
+
+module.exports = { handler, router };