@momentumcms/server-core 0.0.1

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@momentumcms/server-core",
+  "version": "0.0.1",
+  "description": "Framework-agnostic server handlers for Momentum CMS",
+  "license": "MIT",
+  "author": "Momentum CMS Contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/momentum-cms/momentum-cms.git",
+    "directory": "libs/server-core"
+  },
+  "homepage": "https://github.com/momentum-cms/momentum-cms#readme",
+  "bugs": {
+    "url": "https://github.com/momentum-cms/momentum-cms/issues"
+  },
+  "keywords": [
+    "cms",
+    "momentum-cms",
+    "server",
+    "api",
+    "rest",
+    "crud"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "commonjs",
+  "main": "./index.cjs",
+  "types": "./src/index.d.ts",
+  "peerDependencies": {
+    "@momentumcms/core": ">=0.0.1",
+    "@momentumcms/logger": ">=0.0.1",
+    "@momentumcms/storage": ">=0.0.1",
+    "graphql": "^16.0.0"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.983.0",
+    "@aws-sdk/s3-request-presigner": "^3.983.0"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,21 @@
+export { createMomentumHandlers, createInMemoryAdapter, type DatabaseAdapter, type MomentumConfig, type ResolvedMomentumConfig, type QueryOptions, type MomentumRequest, type MomentumResponse, type MomentumHandlers, type ValidationError, } from './lib/server-core';
+export { initializeMomentumAPI, getMomentumAPI, isMomentumAPIInitialized, resetMomentumAPI, CollectionNotFoundError, DocumentNotFoundError, AccessDeniedError, GlobalNotFoundError, ReferentialIntegrityError, ValidationError as MomentumValidationError, type MomentumAPI, type MomentumAPIContext, type CollectionOperations, type GlobalOperations, type FindOptions, type FindResult, type DeleteResult, type WhereClause, type FieldValidationError, type VersionOperations, type VersionFindOptions, } from './lib/momentum-api';
+export { VersionOperationsImpl } from './lib/version-operations';
+export { hasFieldAccessControl, filterReadableFields, filterCreatableFields, filterUpdatableFields, } from './lib/field-access';
+export { hasFieldHooks, runFieldHooks } from './lib/field-hooks';
+export { populateRelationships, type PopulateOptions } from './lib/relationship-populator';
+export { checkCollectionAdminAccess, checkSingleCollectionAdminAccess, getCollectionPermissions, type CollectionAccess, type CollectionPermissions, type AccessResponse, } from './lib/collection-access';
+export { runSeeding, shouldRunSeeding, calculateChecksum, createSeedTracker, type MomentumAuthLike, type SeedingResult, type SeedingRunOptions, type SeedTracker, type CreateSeedTrackingData, } from './lib/seeding';
+export { registerWebhookHooks } from './lib/webhooks';
+export { startPublishScheduler, type PublishSchedulerOptions, type PublishSchedulerHandle, } from './lib/publish-scheduler';
+export { buildGraphQLSchema, type GraphQLContext } from './lib/graphql-schema';
+export { executeGraphQL, type GraphQLRequestBody, type GraphQLResult } from './lib/graphql-handler';
+export { GraphQLJSON } from './lib/graphql-scalars';
+export { generateApiKey, hashApiKey, getKeyPrefix, isValidApiKeyFormat, generateApiKeyId, createAdapterApiKeyStore, createPostgresApiKeyStore, API_KEYS_TABLE_SQL_POSTGRES, API_KEYS_TABLE_SQL_SQLITE, type ApiKeyRecord, type CreateApiKeyResult, type CreateApiKeyOptions, type ApiKeyStore, } from './lib/api-keys';
+export { handleUpload, handleFileDelete, handleFileGet, getUploadConfig, type UploadRequest, type UploadResponse, type UploadConfig, } from './lib/upload-handler';
+export { generateOpenAPISpec, type OpenAPIDocument, type OpenAPIGeneratorOptions, } from './lib/openapi-generator';
+export { getSwaggerUIHTML } from './lib/swagger-ui-html';
+export { renderPreviewHTML, type PreviewRenderOptions } from './lib/preview-renderer';
+export { RateLimiter } from './lib/rate-limiter';
+export { sanitizeErrorMessage, parseWhereParam, sanitizeFilename } from './lib/shared-server-utils';
+export { exportToJson, exportToCsv, parseJsonImport, parseCsvImport, type ExportFormat, type ExportOptions, type ExportResult, type ImportOptions, type ImportResult, type ImportError, } from './lib/import-export';

package/src/lib/api-keys.d.ts

@@ -0,0 +1,105 @@
+import type { DatabaseAdapter } from '@momentumcms/core';
+/**
+ * Stored API key record.
+ */
+export interface ApiKeyRecord {
+    id: string;
+    name: string;
+    /** SHA-256 hash of the full key */
+    keyHash: string;
+    /** First 8 chars of the key for display (e.g., "mcms_abc1...") */
+    keyPrefix: string;
+    /** User ID that created this key */
+    createdBy: string;
+    /** Role assigned to this key for access control */
+    role: string;
+    expiresAt: string | null;
+    lastUsedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Result of creating a new API key.
+ * The full key is only returned once at creation time.
+ */
+export interface CreateApiKeyResult {
+    id: string;
+    name: string;
+    /** The full API key - only shown once */
+    key: string;
+    keyPrefix: string;
+    role: string;
+    expiresAt: string | null;
+    createdAt: string;
+}
+/**
+ * Options for creating an API key.
+ */
+export interface CreateApiKeyOptions {
+    name: string;
+    role?: string;
+    expiresAt?: Date;
+}
+/**
+ * Generate a cryptographically secure API key.
+ * Format: mcms_ + 40 hex chars = 45 chars total
+ */
+export declare function generateApiKey(): string;
+/**
+ * Hash an API key using SHA-256 for secure storage.
+ */
+export declare function hashApiKey(key: string): string;
+/**
+ * Extract a display-safe prefix from an API key.
+ * Returns the first 12 chars (prefix + 7 hex chars).
+ */
+export declare function getKeyPrefix(key: string): string;
+/**
+ * Validate that a string looks like a Momentum API key.
+ */
+export declare function isValidApiKeyFormat(key: string): boolean;
+/**
+ * Generate a unique ID for an API key record.
+ */
+export declare function generateApiKeyId(): string;
+/**
+ * Database operations for API keys.
+ * Uses raw SQL queries through the database adapter.
+ */
+export interface ApiKeyStore {
+    /** Create a new API key record, returns the created record ID */
+    create(record: Omit<ApiKeyRecord, 'lastUsedAt'>): Promise<string>;
+    /** Find an API key by its hash */
+    findByHash(keyHash: string): Promise<ApiKeyRecord | null>;
+    /** List all API keys (without sensitive data) */
+    listAll(): Promise<Omit<ApiKeyRecord, 'keyHash'>[]>;
+    /** List API keys created by a specific user */
+    listByUser(userId: string): Promise<Omit<ApiKeyRecord, 'keyHash'>[]>;
+    /** Find an API key by ID (without keyHash) */
+    findById(id: string): Promise<Omit<ApiKeyRecord, 'keyHash'> | null>;
+    /** Delete an API key by ID */
+    deleteById(id: string): Promise<boolean>;
+    /** Update last used timestamp */
+    updateLastUsed(id: string, timestamp: string): Promise<void>;
+}
+/**
+ * SQL for creating the API keys table (PostgreSQL).
+ */
+export declare const API_KEYS_TABLE_SQL_POSTGRES = "\n\tCREATE TABLE IF NOT EXISTS \"_api_keys\" (\n\t\t\"id\" VARCHAR(36) PRIMARY KEY NOT NULL,\n\t\t\"name\" VARCHAR(255) NOT NULL,\n\t\t\"keyHash\" VARCHAR(64) NOT NULL UNIQUE,\n\t\t\"keyPrefix\" VARCHAR(20) NOT NULL,\n\t\t\"createdBy\" VARCHAR(36) NOT NULL REFERENCES \"user\"(\"id\") ON DELETE CASCADE,\n\t\t\"role\" VARCHAR(50) NOT NULL DEFAULT 'user',\n\t\t\"expiresAt\" TIMESTAMPTZ,\n\t\t\"lastUsedAt\" TIMESTAMPTZ,\n\t\t\"createdAt\" TIMESTAMPTZ NOT NULL,\n\t\t\"updatedAt\" TIMESTAMPTZ NOT NULL\n\t);\n\n\tCREATE INDEX IF NOT EXISTS \"idx_api_keys_keyHash\" ON \"_api_keys\"(\"keyHash\");\n\tCREATE INDEX IF NOT EXISTS \"idx_api_keys_createdBy\" ON \"_api_keys\"(\"createdBy\");\n";
+/**
+ * SQL for creating the API keys table (SQLite).
+ */
+export declare const API_KEYS_TABLE_SQL_SQLITE = "\n\tCREATE TABLE IF NOT EXISTS \"_api_keys\" (\n\t\t\"id\" TEXT PRIMARY KEY NOT NULL,\n\t\t\"name\" TEXT NOT NULL,\n\t\t\"keyHash\" TEXT NOT NULL UNIQUE,\n\t\t\"keyPrefix\" TEXT NOT NULL,\n\t\t\"createdBy\" TEXT NOT NULL,\n\t\t\"role\" TEXT NOT NULL DEFAULT 'user',\n\t\t\"expiresAt\" TEXT,\n\t\t\"lastUsedAt\" TEXT,\n\t\t\"createdAt\" TEXT NOT NULL,\n\t\t\"updatedAt\" TEXT NOT NULL,\n\t\tFOREIGN KEY (\"createdBy\") REFERENCES \"user\"(\"id\") ON DELETE CASCADE\n\t);\n\n\tCREATE INDEX IF NOT EXISTS \"idx_api_keys_keyHash\" ON \"_api_keys\"(\"keyHash\");\n\tCREATE INDEX IF NOT EXISTS \"idx_api_keys_createdBy\" ON \"_api_keys\"(\"createdBy\");\n";
+/**
+ * Create an API key store backed by a generic DatabaseAdapter.
+ * Works with any adapter (SQLite, Postgres, etc.) using collection CRUD methods.
+ */
+export declare function createAdapterApiKeyStore(adapter: DatabaseAdapter): ApiKeyStore;
+/**
+ * Create an API key store backed by PostgreSQL.
+ */
+export declare function createPostgresApiKeyStore(query: {
+    query: (sql: string, params?: unknown[]) => Promise<any[]>;
+    queryOne: (sql: string, params?: unknown[]) => Promise<any | null>;
+    execute: (sql: string, params?: unknown[]) => Promise<number>;
+}): ApiKeyStore;

package/src/lib/collection-access.d.ts

@@ -0,0 +1,54 @@
+import type { MomentumConfig, CollectionConfig, UserContext } from '@momentumcms/core';
+/**
+ * Result of checking admin access for a single collection.
+ */
+export interface CollectionAccess {
+    slug: string;
+    canAccess: boolean;
+}
+/**
+ * Full access permissions for a collection.
+ */
+export interface CollectionPermissions {
+    slug: string;
+    canAccess: boolean;
+    canCreate: boolean;
+    canRead: boolean;
+    canUpdate: boolean;
+    canDelete: boolean;
+    /** True if this collection is managed (read-only via API, owned by a plugin like Better Auth). */
+    managed?: boolean;
+}
+/**
+ * Response shape for the /access endpoint.
+ */
+export interface AccessResponse {
+    collections: CollectionPermissions[];
+}
+/**
+ * Checks if a user has admin panel access to a specific collection.
+ *
+ * @param collection - The collection config to check
+ * @param user - The current user context (undefined if not authenticated)
+ * @returns true if access is allowed, false otherwise
+ */
+export declare function checkSingleCollectionAdminAccess(collection: CollectionConfig, user: UserContext | undefined): Promise<boolean>;
+/**
+ * Checks admin access for all collections in a configuration.
+ * Returns which collections the user can access in the admin panel.
+ *
+ * @param config - The Momentum CMS configuration
+ * @param user - The current user context (undefined if not authenticated)
+ * @returns Array of collection slugs with their access status
+ */
+export declare function checkCollectionAdminAccess(config: MomentumConfig, user: UserContext | undefined): Promise<CollectionAccess[]>;
+/**
+ * Gets full permissions for all collections.
+ * Used by the /access endpoint to inform the frontend about what
+ * operations the user can perform.
+ *
+ * @param config - The Momentum CMS configuration
+ * @param user - The current user context (undefined if not authenticated)
+ * @returns Full permissions for each collection
+ */
+export declare function getCollectionPermissions(config: MomentumConfig, user: UserContext | undefined): Promise<CollectionPermissions[]>;

package/src/lib/field-access.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Field-Level Access Control
+ *
+ * Enforces FieldAccessConfig (create/read/update) by filtering
+ * fields from request data or response documents based on permissions.
+ */
+import type { Field, RequestContext } from '@momentumcms/core';
+/**
+ * Check if any fields in the collection have access control defined.
+ * Recursively checks through all field nesting (groups, arrays, blocks, layout fields).
+ * Used as a fast-path to skip processing when no field access is configured.
+ */
+export declare function hasFieldAccessControl(fields: Field[]): boolean;
+/**
+ * Filter fields the user cannot read from a response document.
+ * Returns a new document with restricted fields removed.
+ */
+export declare function filterReadableFields(fields: Field[], doc: Record<string, unknown>, req: RequestContext): Promise<Record<string, unknown>>;
+/**
+ * Filter fields the user cannot create from input data.
+ * Returns a new data object with restricted fields removed.
+ */
+export declare function filterCreatableFields(fields: Field[], data: Record<string, unknown>, req: RequestContext): Promise<Record<string, unknown>>;
+/**
+ * Filter fields the user cannot update from input data.
+ * Returns a new data object with restricted fields removed.
+ */
+export declare function filterUpdatableFields(fields: Field[], data: Record<string, unknown>, req: RequestContext): Promise<Record<string, unknown>>;

package/src/lib/field-hooks.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Field-Level Hook Execution
+ *
+ * Runs FieldHooksConfig (beforeValidate/beforeChange/afterChange/afterRead)
+ * for each field that has hooks defined.
+ */
+import type { Field, RequestContext } from '@momentumcms/core';
+type FieldHookType = 'beforeValidate' | 'beforeChange' | 'afterChange' | 'afterRead';
+/**
+ * Check if any fields in the collection have hooks defined.
+ * Recursively checks through all field nesting (groups, arrays, blocks, layout fields).
+ */
+export declare function hasFieldHooks(fields: Field[]): boolean;
+/**
+ * Run field-level hooks for a specific hook type.
+ * Iterates through all fields and runs matching hooks, allowing each to transform the field value.
+ * Recurses into groups, arrays, blocks, and layout fields.
+ * Returns the data with any transformed values.
+ */
+export declare function runFieldHooks(hookType: FieldHookType, fields: Field[], data: Record<string, unknown>, req: RequestContext, operation: 'create' | 'update' | 'read'): Promise<Record<string, unknown>>;
+export {};

package/src/lib/graphql-handler.d.ts

@@ -0,0 +1,25 @@
+/**
+ * GraphQL HTTP handler for Momentum CMS.
+ *
+ * Provides a framework-agnostic handler that executes GraphQL queries
+ * against the auto-generated schema. Can be used by Express, h3, etc.
+ */
+import { type GraphQLSchema } from 'graphql';
+import type { UserContext } from '@momentumcms/core';
+/** Parsed GraphQL request body. */
+export interface GraphQLRequestBody {
+    query: string;
+    variables?: Record<string, unknown>;
+    operationName?: string;
+}
+/** Result from executeGraphQL. */
+export interface GraphQLResult {
+    status: number;
+    body: unknown;
+}
+/**
+ * Execute a GraphQL request against the provided schema.
+ */
+export declare function executeGraphQL(schema: GraphQLSchema, requestBody: GraphQLRequestBody, context: {
+    user?: UserContext;
+}): Promise<GraphQLResult>;

package/src/lib/graphql-scalars.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Custom GraphQL scalar types for Momentum CMS.
+ */
+import { GraphQLScalarType } from 'graphql';
+/** JSON scalar - accepts and returns arbitrary JSON values. */
+export declare const GraphQLJSON: GraphQLScalarType<unknown, unknown>;

package/src/lib/graphql-schema.d.ts

@@ -0,0 +1,16 @@
+/**
+ * GraphQL Schema Generator for Momentum CMS.
+ *
+ * Auto-generates a GraphQL schema from Momentum collection configs,
+ * including query/mutation types with resolvers that delegate to the MomentumAPI.
+ */
+import { GraphQLSchema } from 'graphql';
+import type { CollectionConfig, UserContext } from '@momentumcms/core';
+/** Context passed to every GraphQL resolver. */
+export interface GraphQLContext {
+    user?: UserContext;
+}
+/**
+ * Build a full GraphQL schema from a list of collection configs.
+ */
+export declare function buildGraphQLSchema(collections: CollectionConfig[]): GraphQLSchema;

package/src/lib/import-export.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Import/Export module for Momentum CMS.
+ *
+ * Provides JSON and CSV export/import for collection documents.
+ * - Export: Fetches all documents and serializes to JSON or CSV
+ * - Import: Parses JSON or CSV data and creates documents via batch operations
+ *
+ * No external dependencies - uses built-in CSV serialization.
+ */
+import type { CollectionConfig } from '@momentumcms/core';
+export type ExportFormat = 'json' | 'csv';
+export interface ExportOptions {
+    /** Export format (default: 'json') */
+    format?: ExportFormat;
+    /** Max documents to export (default: unlimited) */
+    limit?: number;
+}
+export interface ExportResult {
+    /** Format of the exported data */
+    format: ExportFormat;
+    /** Number of documents exported */
+    totalDocs: number;
+    /** For JSON format: the array of documents */
+    docs?: Record<string, unknown>[];
+    /** For CSV format: the CSV string */
+    data?: string;
+    /** Content-Type header value */
+    contentType: string;
+}
+export interface ImportOptions {
+    /** Import format (default: 'json') */
+    format?: ExportFormat;
+}
+export interface ImportResult {
+    /** Number of successfully imported documents */
+    imported: number;
+    /** Total items attempted */
+    total: number;
+    /** Error details for failed items */
+    errors: ImportError[];
+    /** Successfully created documents */
+    docs: Record<string, unknown>[];
+}
+export interface ImportError {
+    /** Index of the item in the import data */
+    index: number;
+    /** Error message */
+    message: string;
+    /** The data that failed to import */
+    data?: Record<string, unknown>;
+}
+/**
+ * Export documents from a collection as JSON.
+ */
+export declare function exportToJson(docs: Record<string, unknown>[], _collection: CollectionConfig): ExportResult;
+/**
+ * Export documents from a collection as CSV.
+ */
+export declare function exportToCsv(docs: Record<string, unknown>[], collection: CollectionConfig): ExportResult;
+/**
+ * Parse JSON import data into document records.
+ * Accepts either an array of objects or `{ docs: [...] }`.
+ */
+export declare function parseJsonImport(body: unknown): {
+    docs: Record<string, unknown>[];
+    error?: string;
+};
+/**
+ * Parse CSV import data into document records.
+ * First row is treated as header (field names).
+ */
+export declare function parseCsvImport(csvData: string, collection: CollectionConfig): {
+    docs: Record<string, unknown>[];
+    error?: string;
+};

package/src/lib/momentum-api.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Momentum API Implementation
+ *
+ * Provides direct database access for server-side operations.
+ * This is the core of the Momentum API that both SSR and Express use.
+ */
+import type { MomentumConfig } from '@momentumcms/core';
+import type { MomentumAPI } from './momentum-api.types';
+/**
+ * Initialize the Momentum API singleton.
+ * Must be called once at server startup before using getMomentumAPI().
+ *
+ * @param config - The Momentum configuration
+ * @returns The initialized API instance
+ *
+ * @example
+ * ```typescript
+ * // In server.ts
+ * import { initializeMomentumAPI } from '@momentumcms/server-core';
+ * import momentumConfig from './momentum.config';
+ *
+ * initializeMomentumAPI(momentumConfig);
+ * ```
+ */
+export declare function initializeMomentumAPI(config: MomentumConfig): MomentumAPI;
+/**
+ * Get the initialized Momentum API singleton.
+ * Throws if not initialized.
+ *
+ * @returns The API instance
+ * @throws Error if not initialized
+ *
+ * @example
+ * ```typescript
+ * const api = getMomentumAPI();
+ * const posts = await api.collection('posts').find();
+ * ```
+ */
+export declare function getMomentumAPI(): MomentumAPI;
+/**
+ * Check if the Momentum API has been initialized.
+ */
+export declare function isMomentumAPIInitialized(): boolean;
+/**
+ * Reset the Momentum API singleton.
+ * Primarily used for testing.
+ */
+export declare function resetMomentumAPI(): void;
+export type { MomentumAPI, MomentumAPIContext, CollectionOperations, GlobalOperations, FindOptions, FindResult, DeleteResult, WhereClause, FieldValidationError, VersionOperations, VersionFindOptions, } from './momentum-api.types';
+export { CollectionNotFoundError, DocumentNotFoundError, AccessDeniedError, GlobalNotFoundError, ValidationError, } from './momentum-api.types';
+export { ReferentialIntegrityError } from '@momentumcms/core';