@momentumcms/server-core 0.0.1

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

@@ -0,0 +1,368 @@
+/**
+ * Momentum API Types
+ *
+ * Type definitions for the Momentum API - a unified interface for
+ * direct database access (server-side) and HTTP calls (browser-side).
+ */
+import type { MomentumConfig, UserContext, DocumentStatus, DocumentVersionParsed, VersionQueryResult, VersionQueryOptions, RestoreVersionOptions, PublishOptions, SchedulePublishResult } from '@momentumcms/core';
+/**
+ * Context passed to API operations.
+ * Used for access control and hook execution.
+ */
+export interface MomentumAPIContext {
+    /** Current authenticated user */
+    user?: UserContext;
+    /** Depth for relationship population */
+    depth?: number;
+    /** Show hidden fields (admin only) */
+    showHiddenFields?: boolean;
+}
+/**
+ * Options for find operations.
+ */
+export interface FindOptions {
+    /** Filter conditions */
+    where?: WhereClause;
+    /** Sort field (prefix with - for descending) */
+    sort?: string;
+    /** Maximum documents to return */
+    limit?: number;
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Depth for relationship population */
+    depth?: number;
+    /** Include soft-deleted documents in results (only for collections with softDelete enabled). @default false */
+    withDeleted?: boolean;
+    /** Only return soft-deleted documents (only for collections with softDelete enabled). @default false */
+    onlyDeleted?: boolean;
+}
+/**
+ * Where clause for filtering documents.
+ * Supports field-level operators like equals, contains, etc.
+ */
+export type WhereClause = Record<string, unknown>;
+/**
+ * Result of a find operation with pagination info.
+ */
+export interface FindResult<T> {
+    /** Array of documents */
+    docs: T[];
+    /** Total number of matching documents */
+    totalDocs: number;
+    /** Total number of pages */
+    totalPages: number;
+    /** Current page number */
+    page: number;
+    /** Documents per page */
+    limit: number;
+    /** Whether there's a next page */
+    hasNextPage: boolean;
+    /** Whether there's a previous page */
+    hasPrevPage: boolean;
+    /** Next page number (if exists) */
+    nextPage?: number;
+    /** Previous page number (if exists) */
+    prevPage?: number;
+}
+/**
+ * Result of a delete operation.
+ */
+export interface DeleteResult {
+    /** ID of the deleted document */
+    id: string;
+    /** Whether deletion was successful */
+    deleted: boolean;
+}
+/**
+ * Operations available on a collection.
+ * Generic type T represents the document type.
+ */
+export interface CollectionOperations<T = Record<string, unknown>> {
+    /**
+     * Find multiple documents matching the query.
+     */
+    find(options?: FindOptions): Promise<FindResult<T>>;
+    /**
+     * Find a single document by ID.
+     */
+    findById(id: string, options?: {
+        depth?: number;
+        withDeleted?: boolean;
+    }): Promise<T | null>;
+    /**
+     * Create a new document.
+     */
+    create(data: Partial<T>): Promise<T>;
+    /**
+     * Update an existing document.
+     */
+    update(id: string, data: Partial<T>): Promise<T>;
+    /**
+     * Delete a document.
+     * For collections with softDelete enabled, this sets deletedAt instead of removing the row.
+     */
+    delete(id: string): Promise<DeleteResult>;
+    /**
+     * Permanently delete a document, bypassing soft delete.
+     * For collections without softDelete, this is identical to delete().
+     */
+    forceDelete(id: string): Promise<DeleteResult>;
+    /**
+     * Restore a soft-deleted document.
+     * Only available for collections with softDelete enabled.
+     * Throws if the document is not soft-deleted or softDelete is not enabled.
+     */
+    restore(id: string): Promise<T>;
+    /**
+     * Full-text search across collection fields.
+     * Searches text/textarea/email fields using database full-text search.
+     *
+     * @param query - The search query string
+     * @param options - Search options (fields to search, pagination)
+     * @returns Search results sorted by relevance
+     */
+    search(query: string, options?: {
+        fields?: string[];
+        limit?: number;
+        page?: number;
+    }): Promise<FindResult<T>>;
+    /**
+     * Count documents matching the query.
+     */
+    count(where?: WhereClause, options?: {
+        withDeleted?: boolean;
+    }): Promise<number>;
+    /**
+     * Create multiple documents in a single transaction.
+     * All documents are created or none (atomic).
+     *
+     * @param items - Array of document data to create
+     * @returns Array of created documents
+     */
+    batchCreate(items: Partial<T>[]): Promise<T[]>;
+    /**
+     * Update multiple documents in a single transaction.
+     * All updates succeed or none (atomic).
+     *
+     * @param items - Array of { id, data } pairs to update
+     * @returns Array of updated documents
+     */
+    batchUpdate(items: {
+        id: string;
+        data: Partial<T>;
+    }[]): Promise<T[]>;
+    /**
+     * Delete multiple documents in a single transaction.
+     * All deletions succeed or none (atomic).
+     *
+     * @param ids - Array of document IDs to delete
+     * @returns Array of deletion results
+     */
+    batchDelete(ids: string[]): Promise<DeleteResult[]>;
+    /**
+     * Get version operations for this collection.
+     * Returns null if versioning is not enabled for this collection.
+     */
+    versions(): VersionOperations<T> | null;
+}
+/**
+ * Options for finding versions.
+ */
+export interface VersionFindOptions extends VersionQueryOptions {
+    /** Depth for relationship population in version data */
+    depth?: number;
+}
+/**
+ * Operations available for managing document versions.
+ * Only available for collections with versioning enabled.
+ */
+export interface VersionOperations<T = Record<string, unknown>> {
+    /**
+     * Find all versions for a document.
+     * Returns versions in descending order (newest first) by default.
+     *
+     * @param parentId - The document ID to get versions for
+     * @param options - Query options for pagination and filtering
+     */
+    findVersions(parentId: string, options?: VersionFindOptions): Promise<VersionQueryResult<T>>;
+    /**
+     * Find a specific version by ID.
+     *
+     * @param versionId - The version ID to retrieve
+     */
+    findVersionById(versionId: string): Promise<DocumentVersionParsed<T> | null>;
+    /**
+     * Restore a document to a previous version.
+     * Creates a new version with the restored data.
+     *
+     * @param options - Restore options including version ID
+     * @returns The updated document
+     */
+    restore(options: RestoreVersionOptions): Promise<T>;
+    /**
+     * Publish a document (change status from draft to published).
+     * Creates a new published version.
+     *
+     * @param docId - The document ID to publish
+     * @param options - Publish options (e.g., scheduled publish)
+     * @returns The published document
+     */
+    publish(docId: string, options?: PublishOptions): Promise<T>;
+    /**
+     * Unpublish a document (change status from published to draft).
+     *
+     * @param docId - The document ID to unpublish
+     * @returns The unpublished document
+     */
+    unpublish(docId: string): Promise<T>;
+    /**
+     * Save a draft version without changing the main document.
+     * Used for autosave functionality.
+     *
+     * @param docId - The document ID to save draft for
+     * @param data - The draft data
+     * @returns The created draft version
+     */
+    saveDraft(docId: string, data: Partial<T>): Promise<DocumentVersionParsed<T>>;
+    /**
+     * Get the current status of a document.
+     *
+     * @param docId - The document ID
+     * @returns The document status ('draft' or 'published')
+     */
+    getStatus(docId: string): Promise<DocumentStatus>;
+    /**
+     * Compare two versions of a document.
+     * Returns the differences between the versions.
+     *
+     * @param versionId1 - First version ID
+     * @param versionId2 - Second version ID
+     * @returns Object with field-level differences
+     */
+    compare(versionId1: string, versionId2: string): Promise<{
+        field: string;
+        oldValue: unknown;
+        newValue: unknown;
+    }[]>;
+    /**
+     * Schedule a document for future publishing.
+     *
+     * @param docId - The document ID
+     * @param publishAt - ISO date string for when to publish
+     * @returns The schedule result with document ID and scheduled date
+     */
+    schedulePublish(docId: string, publishAt: string): Promise<SchedulePublishResult>;
+    /**
+     * Cancel a scheduled publish for a document.
+     *
+     * @param docId - The document ID
+     */
+    cancelScheduledPublish(docId: string): Promise<void>;
+}
+/**
+ * Operations available on a global (singleton document).
+ * Globals have exactly one document — no create/delete, no pagination.
+ */
+export interface GlobalOperations<T = Record<string, unknown>> {
+    /**
+     * Read the global document.
+     * Auto-creates with default field values if it doesn't exist yet.
+     */
+    findOne(options?: {
+        depth?: number;
+    }): Promise<T>;
+    /**
+     * Update the global document.
+     */
+    update(data: Partial<T>): Promise<T>;
+}
+/**
+ * The main Momentum API interface.
+ *
+ * Provides access to collection operations with optional context.
+ *
+ * @example
+ * ```typescript
+ * const api = getMomentumAPI();
+ *
+ * // Untyped usage
+ * const posts = await api.collection('posts').find({ limit: 10 });
+ *
+ * // Typed usage
+ * const typedPosts = await api.collection<Post>('posts').find();
+ *
+ * // With user context
+ * const adminApi = api.setContext({ user: currentUser });
+ * const result = await adminApi.collection('posts').create({ title: 'New Post' });
+ * ```
+ */
+export interface MomentumAPI {
+    /**
+     * Get operations for a specific collection.
+     *
+     * @param slug - The collection slug
+     * @returns Collection operations interface
+     */
+    collection<T = Record<string, unknown>>(slug: string): CollectionOperations<T>;
+    /**
+     * Get operations for a global (singleton document).
+     *
+     * @param slug - The global slug
+     * @returns Global operations interface
+     */
+    global<T = Record<string, unknown>>(slug: string): GlobalOperations<T>;
+    /**
+     * Get the current Momentum configuration.
+     */
+    getConfig(): MomentumConfig;
+    /**
+     * Create a new API instance with the specified context.
+     * The original instance is not modified (immutable pattern).
+     *
+     * @param ctx - Context to merge with existing context
+     * @returns New API instance with merged context
+     */
+    setContext(ctx: MomentumAPIContext): MomentumAPI;
+    /**
+     * Get the current context.
+     */
+    getContext(): MomentumAPIContext;
+}
+/**
+ * Error thrown when a collection is not found.
+ */
+export declare class CollectionNotFoundError extends Error {
+    constructor(slug: string);
+}
+/**
+ * Error thrown when a document is not found.
+ */
+export declare class DocumentNotFoundError extends Error {
+    constructor(collection: string, id: string);
+}
+/**
+ * Error thrown when access is denied.
+ */
+export declare class AccessDeniedError extends Error {
+    constructor(operation: string, collection: string);
+}
+/**
+ * Error thrown when a global is not found in the configuration.
+ */
+export declare class GlobalNotFoundError extends Error {
+    constructor(slug: string);
+}
+/**
+ * Validation error for a specific field.
+ */
+export interface FieldValidationError {
+    field: string;
+    message: string;
+}
+/**
+ * Error thrown when validation fails.
+ */
+export declare class ValidationError extends Error {
+    readonly errors: FieldValidationError[];
+    constructor(errors: FieldValidationError[]);
+}

package/src/lib/openapi-generator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * OpenAPI Spec Generator for Momentum CMS
+ *
+ * Auto-generates an OpenAPI 3.0 specification from collection configs.
+ * Covers standard CRUD routes, versioning, batch operations, search,
+ * media upload, and GraphQL endpoints.
+ */
+import type { MomentumConfig } from '@momentumcms/core';
+/** OpenAPI 3.0 document (simplified typing for generation). */
+export interface OpenAPIDocument {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    paths: Record<string, Record<string, unknown>>;
+    components: {
+        schemas: Record<string, unknown>;
+        securitySchemes?: Record<string, unknown>;
+    };
+    security?: Array<Record<string, string[]>>;
+}
+/** Options for generating the spec. */
+export interface OpenAPIGeneratorOptions {
+    /** API title (default: 'Momentum CMS API') */
+    title?: string;
+    /** API version string (default: '1.0.0') */
+    version?: string;
+    /** Description for the API */
+    description?: string;
+    /** Server URLs */
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+}
+/**
+ * Generate an OpenAPI 3.0 specification from a MomentumConfig.
+ */
+export declare function generateOpenAPISpec(config: MomentumConfig, options?: OpenAPIGeneratorOptions): OpenAPIDocument;

package/src/lib/preview-renderer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Preview Renderer for Momentum CMS
+ *
+ * Generates a styled HTML page from document data and collection config.
+ * Used by the built-in preview endpoint to render live previews in the admin iframe.
+ */
+import type { CollectionConfig } from '@momentumcms/core';
+/** Options for rendering a preview HTML page. */
+export interface PreviewRenderOptions {
+    /** Document data to render */
+    doc: Record<string, unknown>;
+    /** Collection configuration */
+    collection: CollectionConfig;
+}
+/**
+ * Render a styled HTML preview page from document data.
+ *
+ * The page includes:
+ * - Styled rendering of each visible field
+ * - Inline CSS for responsive layout
+ * - postMessage listener for live updates from the admin form
+ *
+ * Security: Rich text fields are rendered via textContent by default in the
+ * postMessage handler to prevent XSS. The initial server render of rich text
+ * is trusted server-side content from the database.
+ */
+export declare function renderPreviewHTML(options: PreviewRenderOptions): string;

package/src/lib/publish-scheduler.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Publish Scheduler
+ *
+ * Background service that polls for documents scheduled for publishing
+ * and publishes them when their scheduled time arrives.
+ */
+import type { DatabaseAdapter, CollectionConfig } from '@momentumcms/core';
+/**
+ * Options for the publish scheduler.
+ */
+export interface PublishSchedulerOptions {
+    /** Polling interval in milliseconds (default: 10000 = 10s) */
+    intervalMs?: number;
+    /** Logger function for status messages */
+    logger?: (message: string) => void;
+}
+/**
+ * Publish scheduler instance handle.
+ */
+export interface PublishSchedulerHandle {
+    /** Stop the scheduler */
+    stop(): void;
+    /** Run one poll cycle manually (for testing) */
+    poll(): Promise<number>;
+}
+/**
+ * Start a background scheduler that polls for documents with
+ * scheduledPublishAt <= now and publishes them.
+ *
+ * @param adapter - Database adapter
+ * @param collections - All collection configs (only versioned ones are checked)
+ * @param options - Scheduler options
+ * @returns Handle to stop the scheduler
+ */
+export declare function startPublishScheduler(adapter: DatabaseAdapter, collections: CollectionConfig[], options?: PublishSchedulerOptions): PublishSchedulerHandle;

package/src/lib/rate-limiter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Simple in-memory rate limiter with automatic cleanup of expired entries.
+ *
+ * Tracks request counts per key (typically IP address) within a sliding window.
+ * Periodically evicts expired entries to prevent unbounded memory growth.
+ */
+export declare class RateLimiter {
+    private readonly limits;
+    private readonly maxPerMinute;
+    private readonly windowMs;
+    private lastCleanup;
+    private static readonly CLEANUP_INTERVAL;
+    constructor(maxPerMinute: number, windowMs?: number);
+    /** Number of tracked entries (for monitoring/testing). */
+    get size(): number;
+    /** Check if a request from the given key is allowed. */
+    isAllowed(key: string): boolean;
+    /** Evict expired entries if enough time has passed since last cleanup. */
+    private maybeCleanup;
+}

package/src/lib/relationship-populator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Relationship Population
+ *
+ * Populates relationship fields by replacing document IDs with actual
+ * related documents, up to a configurable depth level.
+ * Respects collection-level and field-level access control.
+ */
+import type { CollectionConfig, DatabaseAdapter, Field, RequestContext } from '@momentumcms/core';
+export interface PopulateOptions {
+    /** Maximum depth of population (0 = no population, 1 = populate immediate, etc.) */
+    depth: number;
+    /** All collection configs (needed to resolve relationship targets) */
+    collections: CollectionConfig[];
+    /** Database adapter for fetching related documents */
+    adapter: DatabaseAdapter;
+    /** Request context for access control checks */
+    req?: RequestContext;
+}
+/**
+ * Populate relationship fields in a document up to the specified depth.
+ * Returns a new document with relationship IDs replaced by full documents.
+ *
+ * @param doc The document to populate
+ * @param fields The collection's field definitions
+ * @param options Population options including depth, collections, and adapter
+ */
+export declare function populateRelationships(doc: Record<string, unknown>, fields: Field[], options: PopulateOptions): Promise<Record<string, unknown>>;

package/src/lib/seeding/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Seeding Module (Server-Core)
+ *
+ * Server-side implementation of the seeding system.
+ */
+export * from './seed-tracker';
+export * from './seed-executor';

package/src/lib/seeding/seed-executor.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Seed Executor
+ *
+ * Main execution logic for the Momentum CMS seeding system.
+ * Handles processing seed entities, idempotency, and change detection.
+ */
+import type { DatabaseAdapter, SeedingConfig, SeededDocument } from '@momentumcms/core';
+/**
+ * Minimal auth interface for seed executor.
+ * Avoids depending on the full auth package.
+ */
+export interface MomentumAuthLike {
+    api: {
+        signUpEmail: (options: {
+            body: {
+                name: string;
+                email: string;
+                password: string;
+            };
+        }) => Promise<{
+            user?: {
+                id: string;
+            } | null;
+        } | null>;
+    };
+}
+/**
+ * Result of a seeding run.
+ */
+export interface SeedingResult {
+    /**
+     * Total number of seed entities processed.
+     */
+    total: number;
+    /**
+     * Number of new documents created.
+     */
+    created: number;
+    /**
+     * Number of documents updated (data changed).
+     */
+    updated: number;
+    /**
+     * Number of seeds skipped (already exist, no changes).
+     */
+    skipped: number;
+    /**
+     * All seeded documents (for reference).
+     */
+    seeds: SeededDocument[];
+}
+/**
+ * Options for running the seeding process.
+ */
+export interface SeedingRunOptions {
+    /**
+     * Optional auth instance for auth-aware user seeding.
+     * When provided, seeds with `syncAuth: true` will create Better Auth users
+     * with hashed passwords before creating the Momentum collection document.
+     */
+    auth?: MomentumAuthLike;
+}
+/**
+ * Calculate SHA-256 checksum of seed data for change detection.
+ * Normalizes the JSON to ensure consistent checksums.
+ *
+ * @param data - The data to hash
+ * @returns SHA-256 hex string
+ */
+export declare function calculateChecksum(data: Record<string, unknown>): string;
+/**
+ * Check if seeding should run based on configuration.
+ *
+ * @param runOnStart - The runOnStart option value
+ * @returns True if seeding should run
+ */
+export declare function shouldRunSeeding(runOnStart: boolean | 'development' | 'always'): boolean;
+/**
+ * Run the seeding process.
+ *
+ * @param config - The seeding configuration
+ * @param adapter - The database adapter
+ * @param runOptions - Optional run options (e.g., auth instance for user sync)
+ * @returns Seeding result summary
+ *
+ * @example
+ * ```typescript
+ * const result = await runSeeding(config.seeding, config.db.adapter, { auth });
+ * console.log(`Seeded ${result.created} new documents`);
+ * ```
+ */
+export declare function runSeeding(config: SeedingConfig, adapter: DatabaseAdapter, runOptions?: SeedingRunOptions): Promise<SeedingResult>;

package/src/lib/seeding/seed-tracker.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Seed Tracker
+ *
+ * Manages the internal seed tracking collection (_momentum_seeds).
+ * Tracks seeded entities to ensure idempotency across server restarts.
+ */
+import type { DatabaseAdapter } from '@momentumcms/core';
+import type { SeedTrackingDocument } from '@momentumcms/core';
+/**
+ * Data required to create a new seed tracking record.
+ */
+export interface CreateSeedTrackingData {
+    seedId: string;
+    collection: string;
+    documentId: string;
+    checksum: string;
+}
+/**
+ * Seed tracker interface for managing seed tracking records.
+ */
+export interface SeedTracker {
+    /**
+     * Find a seed tracking record by its seedId.
+     *
+     * @param seedId - The unique seed identifier
+     * @returns The tracking record or null if not found
+     */
+    findBySeedId(seedId: string): Promise<SeedTrackingDocument | null>;
+    /**
+     * Create a new seed tracking record.
+     *
+     * @param data - The tracking data
+     * @returns The created tracking record
+     */
+    create(data: CreateSeedTrackingData): Promise<SeedTrackingDocument>;
+    /**
+     * Update the checksum of an existing seed tracking record.
+     *
+     * @param seedId - The unique seed identifier
+     * @param checksum - The new checksum
+     * @returns The updated tracking record
+     */
+    updateChecksum(seedId: string, checksum: string): Promise<SeedTrackingDocument>;
+    /**
+     * Delete a seed tracking record by its seedId.
+     *
+     * @param seedId - The unique seed identifier
+     * @returns True if deleted, false if not found
+     */
+    delete(seedId: string): Promise<boolean>;
+}
+/**
+ * Creates a seed tracker instance for managing seed tracking records.
+ *
+ * @param adapter - The database adapter to use
+ * @returns Seed tracker instance
+ *
+ * @example
+ * ```typescript
+ * const tracker = createSeedTracker(adapter);
+ * const existing = await tracker.findBySeedId('admin-user');
+ * if (!existing) {
+ *   await tracker.create({
+ *     seedId: 'admin-user',
+ *     collection: 'user',
+ *     documentId: 'uuid-here',
+ *     checksum: 'sha256-hash',
+ *   });
+ * }
+ * ```
+ */
+export declare function createSeedTracker(adapter: DatabaseAdapter): SeedTracker;