@momentumcms/server-express 0.1.0

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@momentumcms/server-express",
+	"version": "0.1.0",
+	"description": "Express adapter for Momentum CMS with Angular SSR support",
+	"license": "MIT",
+	"author": "Momentum CMS Contributors",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/momentum-cms/momentum-cms.git",
+		"directory": "libs/server-express"
+	},
+	"homepage": "https://github.com/momentum-cms/momentum-cms#readme",
+	"bugs": {
+		"url": "https://github.com/momentum-cms/momentum-cms/issues"
+	},
+	"keywords": [
+		"cms",
+		"momentum-cms",
+		"express",
+		"ssr",
+		"angular",
+		"server"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"type": "commonjs",
+	"main": "./index.cjs",
+	"types": "./index.d.ts",
+	"peerDependencies": {
+		"@angular/core": "^19.0.0 || ^20.0.0 || ^21.0.0",
+		"@momentumcms/auth": ">=0.0.1",
+		"@momentumcms/core": ">=0.0.1",
+		"@momentumcms/logger": ">=0.0.1",
+		"@momentumcms/plugins-core": ">=0.0.1",
+		"@momentumcms/server-core": ">=0.0.1",
+		"better-auth": "^1.0.0",
+		"better-sqlite3": "^12.0.0",
+		"express": "^4.18.0 || ^5.0.0",
+		"multer": "^2.0.0",
+		"pg": "^8.0.0"
+	},
+	"dependencies": {
+		"@aws-sdk/client-s3": "^3.983.0",
+		"@aws-sdk/s3-request-presigner": "^3.983.0",
+		"graphql": "^16.12.0",
+		"nodemailer": "^8.0.0"
+	}
+}

package/src/index.d.ts

@@ -0,0 +1,7 @@
+export * from './lib/server-express';
+export { createAuthMiddleware, createProtectMiddleware, createSessionResolverMiddleware, createDeferredSessionResolver, type AuthenticatedRequest, type AuthMiddlewareOptions, } from './lib/auth-middleware';
+export { createSetupMiddleware, type SetupStatus, type SetupMiddlewareConfig, } from './lib/setup-middleware';
+export { createApiKeyResolverMiddleware, createApiKeyRoutes, type ApiKeyMiddlewareConfig, } from './lib/api-key-middleware';
+export { initializeMomentum, createHealthMiddleware, type MomentumInitResult, type SeedingStatus, type InitializeMomentumOptions, type HealthMiddlewareOptions, type HealthResponse, } from './lib/init-helpers';
+export { getPluginProviders } from './lib/plugin-middleware-registry';
+export { createMomentumServer, type CreateMomentumServerOptions, type MomentumServer, } from './lib/create-momentum-server';

package/src/lib/api-key-middleware.d.ts

@@ -0,0 +1,43 @@
+import type { Router, Response, NextFunction } from 'express';
+import type { ApiKeyStore } from '@momentumcms/server-core';
+import type { AuthenticatedRequest } from './auth-middleware';
+/**
+ * Configuration for API key middleware.
+ */
+export interface ApiKeyMiddlewareConfig {
+    /** The API key store for database operations */
+    store: ApiKeyStore;
+}
+/**
+ * Creates middleware that resolves API key from X-API-Key header.
+ *
+ * If a valid API key is found, sets req.user with the key's role.
+ * If no API key header is present, passes through (session auth may handle it).
+ * If an invalid/expired key is provided, returns 401.
+ *
+ * Should be placed BEFORE session resolver middleware so both auth methods work.
+ *
+ * @example
+ * ```typescript
+ * app.use(createApiKeyResolverMiddleware({ store: apiKeyStore }));
+ * app.use(createSessionResolverMiddleware(auth));
+ * app.use('/api', momentumApiMiddleware(config));
+ * ```
+ */
+export declare function createApiKeyResolverMiddleware(config: ApiKeyMiddlewareConfig): (req: AuthenticatedRequest, res: Response, next: NextFunction) => Promise<void>;
+/**
+ * Creates Express router for API key management endpoints.
+ *
+ * All endpoints require authentication. Admin sees all keys, non-admin sees own.
+ *
+ * Endpoints:
+ * - GET    /api-keys       - List API keys (admin: all, others: own)
+ * - POST   /api-keys       - Create a new API key
+ * - DELETE  /api-keys/:id   - Delete an API key (admin: any, others: own)
+ *
+ * @example
+ * ```typescript
+ * app.use('/api', createApiKeyRoutes({ store: apiKeyStore }));
+ * ```
+ */
+export declare function createApiKeyRoutes(config: ApiKeyMiddlewareConfig): Router;

package/src/lib/auth-middleware.d.ts

@@ -0,0 +1,83 @@
+import type { Router, Request, Response, NextFunction, RequestHandler } from 'express';
+import type { MomentumAuth, MomentumAuthPlugin, OAuthProvidersConfig } from '@momentumcms/auth';
+/**
+ * Extended Request type with auth session data.
+ */
+export interface AuthenticatedRequest extends Request {
+    user?: unknown;
+    authSession?: unknown;
+}
+/**
+ * Creates Express middleware to handle Better Auth routes.
+ *
+ * Mounts Better Auth at /auth/* path. All auth endpoints like
+ * /auth/sign-in/email, /auth/sign-up/email, /auth/sign-out, /auth/get-session
+ * are automatically handled.
+ *
+ * @example
+ * ```typescript
+ * import { createAuthMiddleware } from '@momentumcms/server-express';
+ * import { createMomentumAuth } from '@momentumcms/auth';
+ *
+ * const auth = createMomentumAuth({ database });
+ * app.use('/api', createAuthMiddleware(auth));
+ * // Auth endpoints available at /api/auth/*
+ * ```
+ */
+/**
+ * Options for the auth middleware.
+ */
+export interface AuthMiddlewareOptions {
+    /** OAuth providers config (used to expose enabled providers to the client) */
+    socialProviders?: OAuthProvidersConfig;
+}
+export declare function createAuthMiddleware(auth: MomentumAuth, options?: AuthMiddlewareOptions): Router;
+/**
+ * Middleware to protect routes that require authentication.
+ *
+ * Validates the session and attaches the user to the request.
+ * Returns 401 if no valid session is found.
+ *
+ * @example
+ * ```typescript
+ * import { createProtectMiddleware } from '@momentumcms/server-express';
+ *
+ * // Protect all collection routes
+ * app.use('/api/collections', createProtectMiddleware(auth), collectionsRouter);
+ * ```
+ */
+export declare function createProtectMiddleware(auth: MomentumAuth): (req: AuthenticatedRequest, res: Response, next: NextFunction) => Promise<void>;
+/**
+ * Middleware to resolve session for all requests (including SSR).
+ *
+ * Unlike createProtectMiddleware, this does NOT block unauthenticated requests.
+ * It simply validates the session if cookies are present and attaches the user
+ * to the request for use by Angular SSR.
+ *
+ * Role is read directly from the Better Auth user table (single source of truth).
+ *
+ * @example
+ * ```typescript
+ * import { createSessionResolverMiddleware } from '@momentumcms/server-express';
+ *
+ * app.use(createSessionResolverMiddleware(auth));
+ * ```
+ */
+export declare function createSessionResolverMiddleware(auth: MomentumAuth): (req: AuthenticatedRequest, res: Response, next: NextFunction) => Promise<void>;
+/**
+ * Creates a deferred session resolver middleware for an auth plugin.
+ *
+ * This can be called at module scope before the auth plugin is initialized.
+ * The middleware passes through (calls next()) until the auth instance is ready,
+ * then resolves sessions normally.
+ *
+ * @example
+ * ```typescript
+ * import { createDeferredSessionResolver } from '@momentumcms/server-express';
+ * import { momentumAuth } from '@momentumcms/auth';
+ *
+ * const authPlugin = momentumAuth({ ... });
+ * app.use(createDeferredSessionResolver(authPlugin));
+ * ```
+ */
+export declare function createDeferredSessionResolver(plugin: MomentumAuthPlugin): RequestHandler;

package/src/lib/create-momentum-server.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Consolidated Momentum CMS server factory for Express.
+ *
+ * Replaces the manual orchestration of 12+ separate functions
+ * with a single `createMomentumServer()` call that handles:
+ * - Express app creation with JSON parsing
+ * - Plugin initialization (auth, analytics, event bus, etc.)
+ * - Database schema + API initialization
+ * - Seeding
+ * - Webhook hooks registration
+ * - Health endpoint
+ * - Session resolver middleware
+ * - OpenAPI docs endpoint
+ * - CMS API endpoints
+ * - Publish scheduler
+ * - SSR provider helpers
+ */
+import { type Express, type RequestHandler } from 'express';
+import type { MomentumConfig, ResolvedMomentumConfig } from '@momentumcms/core';
+import type { Provider } from '@angular/core';
+import { type MomentumInitResult } from './init-helpers';
+import type { MomentumAuthPlugin } from '@momentumcms/auth';
+/**
+ * Options for creating a consolidated Momentum CMS Express server.
+ */
+export interface CreateMomentumServerOptions {
+    /** Fully resolved Momentum configuration */
+    config: MomentumConfig | ResolvedMomentumConfig;
+    /**
+     * Custom Express app instance.
+     * If not provided, a new Express app is created with `express.json()` body parser.
+     */
+    app?: Express;
+    /**
+     * Mount health endpoint at /api/health.
+     * @default true
+     */
+    health?: boolean;
+    /**
+     * Mount OpenAPI/Swagger docs at /api/docs.
+     * @default false
+     */
+    openapi?: boolean;
+    /**
+     * Start publish scheduler for scheduled content.
+     * Pass `true` for default interval (10s) or an object with custom intervalMs.
+     * @default false
+     */
+    publishScheduler?: boolean | {
+        intervalMs: number;
+    };
+    /**
+     * Register webhook hooks on collections.
+     * @default true (if any collection has webhook config)
+     */
+    webhooks?: boolean;
+    /**
+     * Auth plugin instance for session resolution.
+     * If not provided, auto-detected from config.plugins.
+     */
+    authPlugin?: MomentumAuthPlugin;
+    /**
+     * Factory to create SSR providers for the Momentum API.
+     * Receives the API singleton and user context; should return Angular Providers.
+     *
+     * Typically: `(api, ctx) => provideMomentumAPI(api, ctx)` from `@momentumcms/admin`.
+     * If not provided, `getSsrProviders()` returns only plugin providers.
+     */
+    providerFactory?: (api: unknown, context: {
+        user?: {
+            id: string;
+            email: string;
+            role: string;
+        };
+    }) => Provider[];
+}
+/**
+ * Result of creating a Momentum CMS server.
+ */
+export interface MomentumServer {
+    /**
+     * Express app with all CMS middleware mounted.
+     * Mount additional routes (static files, SSR handler) on this app.
+     */
+    app: Express;
+    /**
+     * Initialization result with ready promise and seeding status.
+     */
+    init: MomentumInitResult;
+    /**
+     * Session resolver middleware.
+     * Mount this before your Angular/framework SSR handler so that
+     * `req.user` is populated for access-controlled SSR rendering.
+     */
+    sessionResolver: RequestHandler;
+    /**
+     * Get Angular SSR providers for the current request.
+     * Includes the Momentum API singleton and all plugin providers.
+     *
+     * @param user - The authenticated user from `req.user` (set by sessionResolver)
+     */
+    getSsrProviders(user?: {
+        id: string;
+        email: string;
+        role: string;
+    }): Provider[];
+    /**
+     * Graceful shutdown: stops publish scheduler and plugin runners.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Create a fully configured Momentum CMS Express server with a single function call.
+ *
+ * Consolidates initialization, middleware mounting, and plugin wiring that previously
+ * required 12+ separate function calls orchestrated in a specific order.
+ *
+ * @example
+ * ```typescript
+ * import { createMomentumServer } from '@momentumcms/server-express';
+ * import config from './momentum.config';
+ *
+ * const server = await createMomentumServer({
+ *   config,
+ *   health: true,
+ *   openapi: true,
+ *   publishScheduler: { intervalMs: 2000 },
+ * });
+ *
+ * // Add app-specific routes (static files, SSR)
+ * server.app.use(express.static(browserDistFolder, { maxAge: '1y' }));
+ * server.app.use(server.sessionResolver);
+ * server.app.use('/**', (req, res, next) => {
+ *   angularApp.handle(req, { providers: server.getSsrProviders(req.user) })...
+ * });
+ *
+ * server.app.listen(4000);
+ * ```
+ */
+export declare function createMomentumServer(options: CreateMomentumServerOptions): Promise<MomentumServer>;

package/src/lib/init-helpers.d.ts

@@ -0,0 +1,138 @@
+import type { Router } from 'express';
+import { type SeedingResult, type MomentumAuthLike } from '@momentumcms/server-core';
+import type { MomentumConfig, ResolvedMomentumConfig } from '@momentumcms/core';
+/**
+ * Result of initializing Momentum CMS.
+ */
+export interface MomentumInitResult {
+    /**
+     * Promise that resolves when initialization (including seeding) completes.
+     * Use this to wait for full initialization before accepting requests.
+     */
+    ready: Promise<void>;
+    /**
+     * Seeding result if seeding was run, null otherwise.
+     */
+    seedingResult: SeedingResult | null;
+    /**
+     * Whether initialization has completed.
+     */
+    isReady: () => boolean;
+    /**
+     * Get current seeding status for health checks.
+     */
+    getSeedingStatus: () => SeedingStatus;
+    /**
+     * Gracefully shut down all plugins.
+     * Call this when the server is stopping.
+     */
+    shutdown: () => Promise<void>;
+}
+/**
+ * Seeding status for health endpoint.
+ */
+export interface SeedingStatus {
+    /** Number of seeds that were processed */
+    completed: number;
+    /** Total number of seeds expected */
+    expected: number;
+    /** Whether seeding has completed */
+    ready: boolean;
+}
+/**
+ * Options for initializeMomentum.
+ */
+export interface InitializeMomentumOptions {
+    /**
+     * Whether to log initialization progress.
+     * @default true
+     */
+    logging?: boolean;
+    /**
+     * Custom logger function.
+     * @default console.log
+     */
+    logger?: (message: string) => void;
+    /**
+     * Auth instance for auth-aware user seeding.
+     * When provided, seeds created with `authUser()` will automatically
+     * create Better Auth users with hashed passwords.
+     */
+    auth?: MomentumAuthLike;
+}
+/**
+ * Initialize Momentum CMS with a single function call.
+ *
+ * Handles:
+ * - Database schema initialization (if adapter supports it)
+ * - Momentum API singleton initialization
+ * - Seeding (if configured in the config)
+ *
+ * @example
+ * ```typescript
+ * import { initializeMomentum } from '@momentumcms/server-express';
+ * import momentumConfig from './momentum.config';
+ *
+ * const { ready, getSeedingStatus } = initializeMomentum(momentumConfig);
+ *
+ * // Wait for initialization before accepting requests
+ * await ready;
+ *
+ * // Or use non-blocking initialization for faster dev startup
+ * ready.catch(console.error);
+ * ```
+ */
+export declare function initializeMomentum(config: MomentumConfig | ResolvedMomentumConfig, options?: InitializeMomentumOptions): MomentumInitResult;
+/**
+ * Options for createHealthMiddleware.
+ */
+export interface HealthMiddlewareOptions {
+    /**
+     * Function to check if the server is ready.
+     */
+    isReady?: () => boolean;
+    /**
+     * Function to get seeding status.
+     */
+    getSeedingStatus?: () => SeedingStatus;
+    /**
+     * Promise to wait for when ?checkSeeds=true is requested.
+     */
+    waitForReady?: Promise<void>;
+    /**
+     * Additional health data to include in response.
+     */
+    additionalData?: () => Record<string, unknown>;
+}
+/**
+ * Health response structure.
+ */
+export interface HealthResponse {
+    status: 'ok' | 'initializing' | 'error';
+    ready: boolean;
+    seeds?: SeedingStatus;
+    [key: string]: unknown;
+}
+/**
+ * Creates Express middleware for a health endpoint.
+ *
+ * Features:
+ * - Reports server ready status
+ * - Reports seeding status (if provided)
+ * - Can wait for initialization when ?checkSeeds=true
+ *
+ * @example
+ * ```typescript
+ * import { initializeMomentum, createHealthMiddleware } from '@momentumcms/server-express';
+ *
+ * const init = initializeMomentum(config);
+ *
+ * // Mount at /api/health
+ * app.use('/api/health', createHealthMiddleware({
+ *   isReady: init.isReady,
+ *   getSeedingStatus: init.getSeedingStatus,
+ *   waitForReady: init.ready,
+ * }));
+ * ```
+ */
+export declare function createHealthMiddleware(options?: HealthMiddlewareOptions): Router;

package/src/lib/plugin-middleware-registry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Plugin Middleware Registry
+ *
+ * Module-level singleton that bridges plugin initialization and middleware mounting.
+ * Same pattern as getMomentumAPI()/initializeMomentumAPI() in server-core.
+ *
+ * Flow:
+ * 1. initializeMomentum() runs pluginRunner.runInit() — plugins register middleware/providers
+ * 2. initializeMomentum() calls setPluginMiddleware/setPluginProviders to store them
+ * 3. momentumApiMiddleware() calls getPluginMiddleware() to auto-mount them
+ * 4. server.ts calls getPluginProviders() to spread into Angular SSR
+ */
+import type { PluginMiddlewareDescriptor, PluginProviderDescriptor } from '@momentumcms/plugins/core';
+/**
+ * Store plugin middleware descriptors collected during onInit.
+ * Called by initializeMomentum() after pluginRunner.runInit().
+ */
+export declare function setPluginMiddleware(middleware: PluginMiddlewareDescriptor[]): void;
+/**
+ * Get plugin middleware descriptors for auto-mounting.
+ * Called by momentumApiMiddleware() to mount plugin routes/middleware.
+ */
+export declare function getPluginMiddleware(): PluginMiddlewareDescriptor[];
+/**
+ * Store plugin provider descriptors collected during onInit.
+ * Called by initializeMomentum() after pluginRunner.runInit().
+ */
+export declare function setPluginProviders(providers: PluginProviderDescriptor[]): void;
+/**
+ * Get plugin provider descriptors for Angular SSR injection.
+ * Called by server.ts to spread into angularApp.handle() providers.
+ *
+ * @example
+ * ```typescript
+ * import { getPluginProviders } from '@momentumcms/server-express';
+ *
+ * angularApp.handle(req, {
+ *   providers: [
+ *     ...provideMomentumAPI(api, { user }),
+ *     ...getPluginProviders().map(p => ({ provide: p.token, useValue: p.value })),
+ *   ],
+ * });
+ * ```
+ */
+export declare function getPluginProviders(): PluginProviderDescriptor[];

package/src/lib/server-express.d.ts

@@ -0,0 +1,45 @@
+import { Router } from 'express';
+import { type OpenAPIGeneratorOptions } from '@momentumcms/server-core';
+import type { MomentumConfig, ResolvedMomentumConfig } from '@momentumcms/core';
+/**
+ * Creates Express middleware for Momentum CMS API.
+ *
+ * Usage:
+ * ```typescript
+ * import express from 'express';
+ * import { momentumApiMiddleware } from '@momentumcms/server-express';
+ * import momentumConfig from './momentum.config';
+ *
+ * const app = express();
+ * app.use('/api', momentumApiMiddleware(momentumConfig));
+ * ```
+ */
+export declare function momentumApiMiddleware(config: MomentumConfig | ResolvedMomentumConfig): Router;
+/**
+ * OpenAPI docs middleware configuration.
+ */
+export interface OpenAPIDocsConfig {
+    /** Momentum config (used to generate the spec from collections) */
+    config: MomentumConfig | ResolvedMomentumConfig;
+    /** OpenAPI generator options (title, version, description, servers) */
+    openapi?: OpenAPIGeneratorOptions;
+}
+/**
+ * Creates Express middleware that serves OpenAPI docs.
+ *
+ * Provides two endpoints:
+ * - GET /openapi.json - the generated OpenAPI 3.0 spec
+ * - GET / - Swagger UI HTML page
+ *
+ * Mount this BEFORE the momentum API middleware to avoid route conflicts.
+ *
+ * @example
+ * ```typescript
+ * app.use('/api/docs', createOpenAPIMiddleware({
+ *   config: momentumConfig,
+ *   openapi: { title: 'My API', version: '2.0.0' },
+ * }));
+ * app.use('/api', momentumApiMiddleware(momentumConfig));
+ * ```
+ */
+export declare function createOpenAPIMiddleware(docsConfig: OpenAPIDocsConfig): Router;

package/src/lib/setup-middleware.d.ts

@@ -0,0 +1,63 @@
+import type { Router } from 'express';
+import type { Pool } from 'pg';
+import type { Database } from 'better-sqlite3';
+import type { MomentumAuth } from '@momentumcms/auth';
+/**
+ * Response type for the setup status endpoint.
+ */
+export interface SetupStatus {
+    /** True if no users exist and setup is required */
+    needsSetup: boolean;
+    /** True if at least one user exists */
+    hasUsers: boolean;
+}
+/**
+ * Database configuration - supports both SQLite and PostgreSQL.
+ */
+export type DatabaseConfig = {
+    type: 'sqlite';
+    database: Database;
+} | {
+    type: 'postgres';
+    pool: Pool;
+};
+/**
+ * Configuration for the setup middleware.
+ */
+export interface SetupMiddlewareConfig {
+    /** Database configuration - supports SQLite or PostgreSQL */
+    db: DatabaseConfig;
+    /** The Better Auth instance for user creation */
+    auth: MomentumAuth;
+}
+/**
+ * Legacy configuration for backwards compatibility.
+ */
+export interface SetupMiddlewareConfigLegacy {
+    /** The SQLite database instance (deprecated, use db instead) */
+    database: Database;
+    /** The Better Auth instance for user creation */
+    auth: MomentumAuth;
+}
+/**
+ * Creates Express middleware for setup-related endpoints.
+ *
+ * Provides endpoints to:
+ * - Check if the application needs initial setup (no users exist)
+ * - Create the first admin user during setup
+ *
+ * @example
+ * ```typescript
+ * import { createSetupMiddleware } from '@momentumcms/server-express';
+ * import { createMomentumAuth } from '@momentumcms/auth';
+ *
+ * // With PostgreSQL
+ * const auth = createMomentumAuth({ db: { type: 'postgres', pool } });
+ * app.use('/api', createSetupMiddleware({ db: { type: 'postgres', pool }, auth }));
+ *
+ * // With SQLite (legacy)
+ * const auth = createMomentumAuth({ database: sqliteDb });
+ * app.use('/api', createSetupMiddleware({ database: sqliteDb, auth }));
+ * ```
+ */
+export declare function createSetupMiddleware(config: SetupMiddlewareConfig | SetupMiddlewareConfigLegacy): Router;