@momentumcms/core 0.1.0

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

@@ -0,0 +1,459 @@
+/**
+ * Seeding Types
+ *
+ * Type definitions for the Momentum CMS seeding system.
+ * Provides declarative data seeding with strict typing and IntelliSense support.
+ */
+/**
+ * Options for individual seed entity creation.
+ */
+export interface SeedEntityOptions {
+    /**
+     * What to do if seedId already exists.
+     * - 'skip': Don't touch existing seed (default)
+     * - 'update': Update if data changed (checksum differs)
+     * - 'error': Throw SeedConflictError
+     */
+    onConflict?: 'skip' | 'update' | 'error';
+    /**
+     * Skip lifecycle hooks during seeding.
+     * Useful for performance when seeding large amounts of data.
+     * @default false
+     */
+    skipHooks?: boolean;
+    /**
+     * Skip access control checks during seeding.
+     * Seeds typically run in a trusted context.
+     * @default true
+     */
+    skipAccessControl?: boolean;
+    /**
+     * Use Better Auth signup API to create this user with proper password hashing.
+     * When true, the seed executor will call auth.api.signUpEmail() instead of
+     * directly inserting into the database, ensuring passwords are properly hashed
+     * and account/session tables are populated.
+     *
+     * Requires `auth` to be passed to `initializeMomentum` options.
+     * Only applies to new seeds (not on 'skip' or 'update').
+     * @default false
+     */
+    useAuthSignup?: boolean;
+}
+/**
+ * Represents a single seed entity definition.
+ */
+export interface SeedEntity<TData = Record<string, unknown>> {
+    /**
+     * Unique identifier for this seed (user-provided).
+     * Used to track seeding state and prevent duplicates.
+     */
+    seedId: string;
+    /**
+     * Collection slug to seed into.
+     */
+    collection: string;
+    /**
+     * Data to create in the collection.
+     */
+    data: TData;
+    /**
+     * Options for this specific entity.
+     */
+    options?: SeedEntityOptions;
+}
+/**
+ * Result of a seeded document operation.
+ */
+export interface SeededDocument<T = Record<string, unknown>> {
+    /**
+     * The actual document ID in the database.
+     */
+    id: string;
+    /**
+     * The seed ID used to create/identify this seed.
+     */
+    seedId: string;
+    /**
+     * Collection slug where the document was seeded.
+     */
+    collection: string;
+    /**
+     * The created/updated document data.
+     */
+    data: T;
+    /**
+     * What action was taken.
+     * - 'created': New document was created
+     * - 'updated': Existing document was updated (data changed)
+     * - 'skipped': Document already exists and was not modified
+     */
+    action: 'created' | 'updated' | 'skipped';
+}
+/**
+ * Typed seed builder for a specific collection.
+ * Provides IntelliSense for collection document types.
+ */
+export interface CollectionSeedBuilder<TDoc> {
+    /**
+     * Create a seed entity for this collection.
+     *
+     * @param seedId - Unique identifier for this seed
+     * @param data - Document data to seed
+     * @param options - Optional seed options
+     * @returns Seed entity definition
+     *
+     * @example
+     * ```typescript
+     * collection<PostDoc>('posts').create('welcome-post', {
+     *   title: 'Welcome!',
+     *   status: 'published',
+     * });
+     * ```
+     */
+    create: (seedId: string, data: Partial<TDoc>, options?: SeedEntityOptions) => SeedEntity<TDoc>;
+}
+/**
+ * User seed data structure for Better Auth user table.
+ */
+export interface UserSeedData {
+    /**
+     * User's display name.
+     */
+    name: string;
+    /**
+     * User's email address (unique).
+     */
+    email: string;
+    /**
+     * User's role.
+     * @default 'user'
+     */
+    role?: string;
+    /**
+     * Whether email is verified.
+     * @default false
+     */
+    emailVerified?: boolean;
+    /**
+     * User's avatar image URL.
+     */
+    image?: string;
+}
+/**
+ * Admin seed data structure for the first admin user.
+ * Same as UserSeedData but with admin-friendly defaults.
+ */
+export interface AdminSeedData {
+    /**
+     * Admin's display name.
+     */
+    name: string;
+    /**
+     * Admin's email address (unique).
+     */
+    email: string;
+    /**
+     * Admin's role.
+     * @default 'admin'
+     */
+    role?: string;
+    /**
+     * Whether email is verified.
+     * @default true (admins are typically pre-verified)
+     */
+    emailVerified?: boolean;
+    /**
+     * Admin's avatar image URL.
+     */
+    image?: string;
+}
+/**
+ * Auth user seed data structure.
+ * Seeds directly into the Better Auth user table (auth-user collection).
+ * When used with the `authUser()` helper, the seed executor calls
+ * Better Auth's signUpEmail API to ensure proper password hashing.
+ */
+export interface AuthUserSeedData {
+    [key: string]: unknown;
+    /**
+     * User's display name.
+     */
+    name: string;
+    /**
+     * User's email address (unique).
+     */
+    email: string;
+    /**
+     * User's password (will be hashed by Better Auth).
+     * Must be at least 8 characters.
+     */
+    password: string;
+    /**
+     * User's role.
+     * @default 'user'
+     */
+    role?: string;
+    /**
+     * Whether email is verified.
+     * @default true
+     */
+    emailVerified?: boolean;
+}
+/**
+ * Default entity helpers with IntelliSense support.
+ * Used in the `defaults` function of SeedingConfig.
+ */
+export interface DefaultEntityHelpers {
+    /**
+     * Create the first admin user seed entity.
+     * Pre-configured with admin role and verified email.
+     *
+     * @param seedId - Unique identifier for this seed
+     * @param data - Admin user data
+     * @param options - Optional seed options
+     * @returns Seed entity definition
+     *
+     * @example
+     * ```typescript
+     * admin('first-admin', {
+     *   name: 'System Admin',
+     *   email: 'admin@example.com',
+     * });
+     * ```
+     */
+    admin: (seedId: string, data: AdminSeedData, options?: SeedEntityOptions) => SeedEntity<UserSeedData>;
+    /**
+     * Create a user seed entity for the Better Auth user table.
+     *
+     * @param seedId - Unique identifier for this seed
+     * @param data - User data
+     * @param options - Optional seed options
+     * @returns Seed entity definition
+     *
+     * @example
+     * ```typescript
+     * user('regular-user', {
+     *   name: 'John Doe',
+     *   email: 'john@example.com',
+     * });
+     * ```
+     */
+    user: (seedId: string, data: UserSeedData, options?: SeedEntityOptions) => SeedEntity<UserSeedData>;
+    /**
+     * Create a typed collection seed builder.
+     * Provides full IntelliSense for the document type.
+     *
+     * @param slug - Collection slug
+     * @returns Collection seed builder
+     *
+     * @example
+     * ```typescript
+     * collection<PostDoc>('posts').create('welcome', {
+     *   title: 'Welcome!',
+     *   status: 'published',
+     * });
+     * ```
+     */
+    collection: <TDoc>(slug: string) => CollectionSeedBuilder<TDoc>;
+    /**
+     * Create an auth user seed entity with password support.
+     * Seeds into the Better Auth user table using signUpEmail API
+     * to ensure proper password hashing and account creation.
+     *
+     * @param seedId - Unique identifier for this seed
+     * @param data - User data including password
+     * @param options - Optional seed options
+     * @returns Seed entity definition with useAuthSignup enabled
+     *
+     * @example
+     * ```typescript
+     * authUser('admin-user', {
+     *   name: 'Admin',
+     *   email: 'admin@example.com',
+     *   password: 'SecurePass123!',
+     *   role: 'admin',
+     * });
+     * ```
+     */
+    authUser: (seedId: string, data: AuthUserSeedData, options?: SeedEntityOptions) => SeedEntity<AuthUserSeedData>;
+}
+/**
+ * Context passed to the custom seed function.
+ * Provides utilities for seeding with dependency resolution.
+ */
+export interface SeedContext {
+    /**
+     * Get a previously seeded document by its seedId.
+     * Useful for creating relationships between seeded entities.
+     *
+     * @param seedId - The seed ID to look up
+     * @returns The seeded document or null if not found
+     *
+     * @example
+     * ```typescript
+     * const adminUser = await ctx.getSeeded('admin-user');
+     * await ctx.seed({
+     *   seedId: 'admin-post',
+     *   collection: 'posts',
+     *   data: { authorId: adminUser?.id },
+     * });
+     * ```
+     */
+    getSeeded: <T = Record<string, unknown>>(seedId: string) => Promise<SeededDocument<T> | null>;
+    /**
+     * Create a seed entity with tracking.
+     *
+     * @param entity - Seed entity definition
+     * @returns The seeded document result
+     */
+    seed: <T = Record<string, unknown>>(entity: SeedEntity<T>) => Promise<SeededDocument<T>>;
+    /**
+     * Log a message (respects quiet mode).
+     *
+     * @param message - Message to log
+     */
+    log: (message: string) => void;
+}
+/**
+ * Global seeding options.
+ */
+export interface SeedingOptions {
+    /**
+     * Default conflict handling strategy.
+     * @default 'skip'
+     */
+    onConflict?: 'skip' | 'update' | 'error';
+    /**
+     * When to run seeding on server start.
+     * - 'development': Only when NODE_ENV is 'development'
+     * - 'always': Run on every server start
+     * - true: Same as 'always'
+     * - false: Never run automatically (can be triggered via CLI)
+     * @default 'development'
+     */
+    runOnStart?: boolean | 'development' | 'always';
+    /**
+     * Suppress seeding log messages.
+     * @default false
+     */
+    quiet?: boolean;
+}
+/**
+ * Seeding configuration for Momentum CMS.
+ */
+export interface SeedingConfig {
+    /**
+     * Default entities to seed first (in order).
+     * Uses helper methods for strict typing.
+     *
+     * @param helpers - Typed entity helpers
+     * @returns Array of seed entities to create
+     *
+     * @example
+     * ```typescript
+     * defaults: ({ user, collection }) => [
+     *   user('admin', { name: 'Admin', email: 'admin@example.com', role: 'admin' }),
+     *   collection<PostDoc>('posts').create('welcome', { title: 'Welcome!' }),
+     * ]
+     * ```
+     */
+    defaults?: (helpers: DefaultEntityHelpers) => SeedEntity[];
+    /**
+     * Custom seed function for complex scenarios.
+     * Runs after defaults, has access to SeedContext for dependency resolution.
+     *
+     * @param ctx - Seeding context with utilities
+     *
+     * @example
+     * ```typescript
+     * seed: async (ctx) => {
+     *   const admin = await ctx.getSeeded('admin');
+     *   await ctx.seed({
+     *     seedId: 'admin-post',
+     *     collection: 'posts',
+     *     data: { authorId: admin?.id },
+     *   });
+     * }
+     * ```
+     */
+    seed?: (ctx: SeedContext) => Promise<void>;
+    /**
+     * Global seeding options.
+     */
+    options?: SeedingOptions;
+}
+/**
+ * Internal seed tracking document stored in _momentum_seeds table.
+ */
+export interface SeedTrackingDocument {
+    /**
+     * Primary key (auto-generated UUID).
+     */
+    id: string;
+    /**
+     * User-provided unique seed identifier.
+     */
+    seedId: string;
+    /**
+     * Collection the entity was seeded into.
+     */
+    collection: string;
+    /**
+     * Actual document ID in the target collection.
+     */
+    documentId: string;
+    /**
+     * SHA-256 hash of the seed data for change detection.
+     */
+    checksum: string;
+    /**
+     * When this seed was first created.
+     */
+    createdAt: string;
+    /**
+     * When this seed was last updated.
+     */
+    updatedAt: string;
+}
+/**
+ * Slug for the internal seed tracking collection.
+ */
+export declare const SEED_TRACKING_COLLECTION_SLUG = "_momentum_seeds";
+/**
+ * Error thrown when a seed conflict occurs with onConflict: 'error'.
+ */
+export declare class SeedConflictError extends Error {
+    readonly seedId: string;
+    readonly collection: string;
+    constructor(seedId: string, collection: string);
+}
+/**
+ * Information about a seed that was rolled back.
+ */
+export interface RolledBackSeed {
+    /** The seed ID that was rolled back */
+    seedId: string;
+    /** The collection the seed was in */
+    collection: string;
+    /** The document ID that was deleted */
+    documentId: string;
+}
+/**
+ * Error thrown when seeding fails and rollback is performed.
+ * Contains the original error and information about rolled back seeds.
+ */
+export declare class SeedRollbackError extends Error {
+    /** The original error that caused the rollback */
+    readonly originalError: Error;
+    /** Seeds that were successfully rolled back */
+    readonly rolledBackSeeds: RolledBackSeed[];
+    /** Seeds that failed to roll back */
+    readonly rollbackFailures: Array<{
+        seed: RolledBackSeed;
+        error: Error;
+    }>;
+    constructor(originalError: Error, rolledBackSeeds: RolledBackSeed[], rollbackFailures: Array<{
+        seed: RolledBackSeed;
+        error: Error;
+    }>);
+}

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

@@ -0,0 +1,86 @@
+/**
+ * Storage module for Momentum CMS
+ * Defines interfaces for file storage adapters
+ */
+/**
+ * Represents an uploaded file before storage.
+ */
+export interface UploadedFile {
+    /** Original filename */
+    originalName: string;
+    /** MIME type of the file */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+    /** File content as Buffer */
+    buffer: Buffer;
+}
+/**
+ * Represents a file after it has been stored.
+ */
+export interface StoredFile {
+    /** Storage path/key */
+    path: string;
+    /** Public URL to access the file */
+    url: string;
+    /** Stored filename */
+    filename: string;
+    /** MIME type */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+}
+/**
+ * Options for upload operations.
+ */
+export interface UploadOptions {
+    /** Custom filename (without extension) */
+    filename?: string;
+    /** Subdirectory within the upload directory */
+    directory?: string;
+}
+/**
+ * Storage adapter interface.
+ * Implement this interface to create custom storage backends.
+ */
+export interface StorageAdapter {
+    /**
+     * Upload a file to storage.
+     * @param file - The file to upload
+     * @param options - Upload options
+     * @returns The stored file metadata
+     */
+    upload(file: UploadedFile, options?: UploadOptions): Promise<StoredFile>;
+    /**
+     * Delete a file from storage.
+     * @param path - The storage path/key of the file
+     * @returns True if deleted, false if not found
+     */
+    delete(path: string): Promise<boolean>;
+    /**
+     * Get the public URL for a stored file.
+     * @param path - The storage path/key
+     * @returns The public URL
+     */
+    getUrl(path: string): string;
+    /**
+     * Check if a file exists in storage.
+     * @param path - The storage path/key
+     * @returns True if exists
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Get a signed URL for temporary access (optional).
+     * Useful for private S3 buckets.
+     * @param path - The storage path/key
+     * @param expiresIn - Expiration time in seconds
+     * @returns The signed URL
+     */
+    getSignedUrl?(path: string, expiresIn?: number): Promise<string>;
+    /**
+     * Read a file from storage.
+     * @param path - The storage path/key
+     * @returns The file as a Buffer, or null if not found
+     */
+    read?(path: string): Promise<Buffer | null>;
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Versions module
+ * Types and utilities for document versioning and drafts
+ */
+export * from './version.types';

package/src/lib/versions/version.types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Version Types for Momentum CMS
+ * Defines the structure of document versions and drafts
+ */
+/**
+ * Status of a document in a versioned collection.
+ * - 'draft': Document is not publicly visible
+ * - 'published': Document is publicly visible
+ */
+export type DocumentStatus = 'draft' | 'published';
+/**
+ * Represents a single version of a document.
+ * Each version stores a full snapshot of the document at a point in time.
+ */
+export interface DocumentVersion {
+    /** Unique identifier for this version */
+    id: string;
+    /** ID of the parent document this version belongs to */
+    parent: string;
+    /** Full document snapshot stored as JSON string */
+    version: string;
+    /** Status of this version */
+    _status: DocumentStatus;
+    /** Whether this version was created by autosave */
+    autosave: boolean;
+    /** When this version was published (if published) */
+    publishedAt?: string;
+    /** When this version was created */
+    createdAt: string;
+    /** When this version was last updated */
+    updatedAt: string;
+}
+/**
+ * Document version with parsed version data.
+ * Used when returning versions to the API layer.
+ */
+export interface DocumentVersionParsed<T = Record<string, unknown>> {
+    /** Unique identifier for this version */
+    id: string;
+    /** ID of the parent document this version belongs to */
+    parent: string;
+    /** Parsed document snapshot */
+    version: T;
+    /** Status of this version */
+    _status: DocumentStatus;
+    /** Whether this version was created by autosave */
+    autosave: boolean;
+    /** When this version was published (if published) */
+    publishedAt?: string;
+    /** When this version was created */
+    createdAt: string;
+    /** When this version was last updated */
+    updatedAt: string;
+}
+/**
+ * Options for counting versions (filter options only, no pagination).
+ */
+export interface VersionCountOptions {
+    /** Include autosave versions in count (default: false) */
+    includeAutosave?: boolean;
+    /** Filter by status */
+    status?: DocumentStatus;
+}
+/**
+ * Options for querying versions of a document.
+ */
+export interface VersionQueryOptions extends VersionCountOptions {
+    /** Maximum number of versions to return */
+    limit?: number;
+    /** Page number for pagination (1-based) */
+    page?: number;
+    /** Sort order (default: 'desc' = newest first) */
+    sort?: 'asc' | 'desc';
+}
+/**
+ * Result of a version query with pagination info.
+ */
+export interface VersionQueryResult<T = Record<string, unknown>> {
+    /** Array of versions */
+    docs: DocumentVersionParsed<T>[];
+    /** Total number of versions */
+    totalDocs: number;
+    /** Total number of pages */
+    totalPages: number;
+    /** Current page number */
+    page: number;
+    /** Items per page */
+    limit: number;
+    /** Whether there is a next page */
+    hasNextPage: boolean;
+    /** Whether there is a previous page */
+    hasPrevPage: boolean;
+}
+/**
+ * Options for restoring a version.
+ */
+export interface RestoreVersionOptions {
+    /** The version ID to restore */
+    versionId: string;
+    /** The document ID that the version must belong to (validated when provided) */
+    docId?: string;
+    /** Whether to publish the restored version immediately (default: false) */
+    publish?: boolean;
+}
+/**
+ * Options for creating a version.
+ */
+export interface CreateVersionOptions {
+    /** Status of the new version */
+    status?: DocumentStatus;
+    /** Whether this is an autosave version */
+    autosave?: boolean;
+}
+/**
+ * Options for publishing a document.
+ */
+export interface PublishOptions {
+    /** Scheduled publish date (ISO string). If provided, document will be scheduled for future publishing. */
+    scheduledPublishAt?: string;
+}
+/**
+ * Options for scheduling a document publish.
+ */
+export interface SchedulePublishOptions {
+    /** ISO date string for when the document should be published. */
+    publishAt: string;
+}
+/**
+ * Result of a schedule publish operation.
+ */
+export interface SchedulePublishResult {
+    /** Document ID */
+    id: string;
+    /** Scheduled publish date (ISO string) */
+    scheduledPublishAt: string;
+}
+/**
+ * Event data passed to version-related hooks.
+ */
+export interface VersionHookArgs {
+    /** The version being operated on */
+    version: DocumentVersion;
+    /** The parent document ID */
+    parentId: string;
+    /** The collection slug */
+    collection: string;
+    /** The operation being performed */
+    operation: 'create' | 'restore' | 'publish' | 'unpublish' | 'delete';
+}