@momentumcms/core 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "@momentumcms/core",
+	"version": "0.1.0",
+	"description": "Core collection config, fields, hooks, and access control for Momentum CMS",
+	"license": "MIT",
+	"author": "Momentum CMS Contributors",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/momentum-cms/momentum-cms.git",
+		"directory": "libs/core"
+	},
+	"homepage": "https://github.com/momentum-cms/momentum-cms#readme",
+	"bugs": {
+		"url": "https://github.com/momentum-cms/momentum-cms/issues"
+	},
+	"keywords": [
+		"cms",
+		"headless-cms",
+		"angular",
+		"momentum-cms",
+		"collections",
+		"fields",
+		"content-management"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"type": "commonjs",
+	"main": "./index.cjs",
+	"types": "./src/index.d.ts",
+	"dependencies": {}
+}

package/src/generators/types/generator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Momentum CMS Type Generator
+ *
+ * Generates TypeScript interfaces from collection definitions.
+ * Run via: nx run <app>:generate-types
+ */
+interface GeneratorSchema {
+    configPath: string;
+    outputPath: string;
+    watch?: boolean;
+}
+interface ExecutorContext {
+    root: string;
+    projectName?: string;
+    projectsConfigurations?: {
+        projects: Record<string, {
+            root: string;
+        }>;
+    };
+}
+/**
+ * Main executor function.
+ */
+export default function runExecutor(options: GeneratorSchema, context: ExecutorContext): Promise<{
+    success: boolean;
+}>;
+export {};

package/src/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @momentumcms/core
+ *
+ * Core package for Momentum CMS
+ * Contains collection types, field builders, and utility functions
+ */
+export * from './lib/collections';
+export * from './lib/fields';
+export * from './lib/access';
+export * from './lib/config';
+export * from './lib/plugins';
+export * from './lib/storage';
+export * from './lib/seeding';
+export * from './lib/versions';

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

@@ -0,0 +1,212 @@
+/**
+ * Access Control Helpers
+ *
+ * Provides type-safe helper functions for defining access control rules.
+ * These helpers improve DX by providing:
+ * - Full IntelliSense for user properties
+ * - Type-safe role checking
+ * - Common access patterns as simple functions
+ *
+ * @example
+ * ```typescript
+ * import { access, hasRole, hasAnyRole, isAuthenticated, allowAll } from '@momentumcms/core';
+ *
+ * // Using pre-built helpers
+ * access: {
+ *   read: allowAll(),
+ *   create: isAuthenticated(),
+ *   update: hasAnyRole(['admin', 'editor']),
+ *   delete: hasRole('admin'),
+ * }
+ *
+ * // Using typed custom access
+ * interface MyUser {
+ *   id: string;
+ *   role: 'admin' | 'editor' | 'viewer';
+ *   permissions: string[];
+ * }
+ *
+ * access: {
+ *   read: access<MyUser>(({ user }) => user?.permissions.includes('read') ?? false),
+ *   create: access<MyUser>(({ user }) => user?.role !== 'viewer'),
+ * }
+ * ```
+ */
+import type { AccessFunction, UserContext } from '../collections/collection.types';
+/**
+ * Arguments passed to access callback functions.
+ * Generic over user type for full type safety.
+ */
+export interface AccessCallbackArgs<TUser extends UserContext = UserContext> {
+    /** The authenticated user, or undefined if not authenticated */
+    user: TUser | undefined;
+    /** Document ID (for update/delete operations) */
+    id?: string | number;
+    /** Document data (for create/update operations) */
+    data?: Record<string, unknown>;
+}
+/**
+ * Typed access callback function.
+ * Receives user-friendly arguments with full type inference.
+ */
+export type AccessCallback<TUser extends UserContext = UserContext> = (args: AccessCallbackArgs<TUser>) => boolean | Promise<boolean>;
+/**
+ * Creates a typed access function with full IntelliSense support.
+ *
+ * Use this when you need custom access logic with type-safe user properties.
+ * The generic type parameter lets you define your user shape for autocomplete.
+ *
+ * @example
+ * ```typescript
+ * // With default UserContext type
+ * access: {
+ *   read: access(({ user }) => user?.role === 'admin'),
+ * }
+ *
+ * // With custom user type for full IntelliSense
+ * interface MyUser {
+ *   id: string;
+ *   email: string;
+ *   role: 'admin' | 'editor' | 'viewer';
+ *   teamId: string;
+ * }
+ *
+ * access: {
+ *   read: access<MyUser>(({ user }) => user?.teamId === 'team-1'),
+ *   create: access<MyUser>(({ user, data }) => {
+ *     // user has full MyUser type with autocomplete
+ *     return user?.role === 'admin' || user?.role === 'editor';
+ *   }),
+ * }
+ * ```
+ */
+export declare function access<TUser extends UserContext = UserContext>(callback: AccessCallback<TUser>): AccessFunction;
+/**
+ * Allow all access (public).
+ *
+ * @example
+ * ```typescript
+ * access: {
+ *   read: allowAll(), // Anyone can read
+ * }
+ * ```
+ */
+export declare function allowAll(): AccessFunction;
+/**
+ * Deny all access.
+ *
+ * @example
+ * ```typescript
+ * access: {
+ *   delete: denyAll(), // No one can delete
+ * }
+ * ```
+ */
+export declare function denyAll(): AccessFunction;
+/**
+ * Require authentication (any logged-in user).
+ *
+ * @example
+ * ```typescript
+ * access: {
+ *   create: isAuthenticated(), // Any logged-in user can create
+ * }
+ * ```
+ */
+export declare function isAuthenticated(): AccessFunction;
+/**
+ * Require a specific role.
+ *
+ * @param role - The role required for access
+ *
+ * @example
+ * ```typescript
+ * access: {
+ *   delete: hasRole('admin'), // Only admins can delete
+ * }
+ * ```
+ */
+export declare function hasRole(role: string): AccessFunction;
+/**
+ * Require any of the specified roles.
+ *
+ * @param roles - Array of roles, any of which grants access
+ *
+ * @example
+ * ```typescript
+ * access: {
+ *   update: hasAnyRole(['admin', 'editor']), // Admins or editors can update
+ * }
+ * ```
+ */
+export declare function hasAnyRole(roles: readonly string[]): AccessFunction;
+/**
+ * Require all of the specified roles (for multi-role systems).
+ *
+ * @param roles - Array of roles, all of which are required
+ *
+ * @example
+ * ```typescript
+ * // If user has multiple roles stored as an array
+ * access: {
+ *   admin: hasAllRoles(['verified', 'admin']),
+ * }
+ * ```
+ */
+export declare function hasAllRoles(roles: readonly string[]): AccessFunction;
+/**
+ * Combine multiple access functions with AND logic.
+ * All conditions must pass for access to be granted.
+ *
+ * @param fns - Access functions to combine
+ *
+ * @example
+ * ```typescript
+ * access: {
+ *   update: and(isAuthenticated(), hasAnyRole(['admin', 'editor'])),
+ * }
+ * ```
+ */
+export declare function and(...fns: AccessFunction[]): AccessFunction;
+/**
+ * Combine multiple access functions with OR logic.
+ * Any condition passing grants access.
+ *
+ * @param fns - Access functions to combine
+ *
+ * @example
+ * ```typescript
+ * access: {
+ *   read: or(allowAll(), hasRole('admin')), // Public read, but admin always allowed
+ * }
+ * ```
+ */
+export declare function or(...fns: AccessFunction[]): AccessFunction;
+/**
+ * Negate an access function.
+ *
+ * @param fn - Access function to negate
+ *
+ * @example
+ * ```typescript
+ * access: {
+ *   read: not(hasRole('banned')), // Anyone except banned users
+ * }
+ * ```
+ */
+export declare function not(fn: AccessFunction): AccessFunction;
+/**
+ * Check if the authenticated user owns the document.
+ * Compares user.id with the document's author/owner field.
+ *
+ * @param ownerField - The field name containing the owner's user ID (default: 'createdBy')
+ *
+ * @example
+ * ```typescript
+ * access: {
+ *   update: or(hasRole('admin'), isOwner()), // Admin or document owner
+ *   delete: or(hasRole('admin'), isOwner('authorId')),
+ * }
+ * ```
+ */
+export declare function isOwner(ownerField?: string): AccessFunction;

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

@@ -0,0 +1,6 @@
+/**
+ * Access Control Module
+ *
+ * Provides type-safe helper functions for defining access control rules.
+ */
+export { access, type AccessCallback, type AccessCallbackArgs, allowAll, denyAll, isAuthenticated, hasRole, hasAnyRole, hasAllRoles, and, or, not, isOwner, } from './access-helpers';

package/src/lib/collections/collection.types.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Collection Types for Momentum CMS
+ * Defines the structure of collections (similar to Payload CMS)
+ */
+import type { Field } from '../fields/field.types';
+export interface AccessArgs {
+    req: RequestContext;
+    id?: string | number;
+    data?: Record<string, unknown>;
+}
+export interface RequestContext {
+    user?: UserContext;
+    headers?: Record<string, string>;
+}
+export interface UserContext {
+    id: string | number;
+    email?: string;
+    role?: string;
+    [key: string]: unknown;
+}
+export type AccessFunction = (args: AccessArgs) => boolean | Promise<boolean>;
+export interface AccessConfig {
+    create?: AccessFunction;
+    read?: AccessFunction;
+    update?: AccessFunction;
+    delete?: AccessFunction;
+    admin?: AccessFunction;
+    unlock?: AccessFunction;
+    /** Control who can restore soft-deleted documents (falls back to update access) */
+    restore?: AccessFunction;
+    /** Control who can permanently delete soft-deleted documents (falls back to delete access) */
+    forceDelete?: AccessFunction;
+    /** Control who can read version history */
+    readVersions?: AccessFunction;
+    /** Control who can publish/unpublish documents */
+    publishVersions?: AccessFunction;
+    /** Control who can restore previous versions */
+    restoreVersions?: AccessFunction;
+}
+export interface HookArgs {
+    req: RequestContext;
+    data?: Record<string, unknown>;
+    doc?: Record<string, unknown>;
+    operation?: 'create' | 'update' | 'delete' | 'softDelete' | 'restore';
+    originalDoc?: Record<string, unknown>;
+}
+export type HookFunction = (args: HookArgs) => Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
+export interface HooksConfig {
+    beforeValidate?: HookFunction[];
+    beforeChange?: HookFunction[];
+    afterChange?: HookFunction[];
+    beforeRead?: HookFunction[];
+    afterRead?: HookFunction[];
+    beforeDelete?: HookFunction[];
+    afterDelete?: HookFunction[];
+    beforeRestore?: HookFunction[];
+    afterRestore?: HookFunction[];
+}
+export interface AdminConfig {
+    /** Field to use as the document title in the admin UI */
+    useAsTitle?: string;
+    /** Default columns to show in list view */
+    defaultColumns?: string[];
+    /** Admin sidebar group */
+    group?: string;
+    /** Fields searchable in admin list */
+    listSearchableFields?: string[];
+    /** Pagination settings */
+    pagination?: {
+        defaultLimit?: number;
+        limits?: number[];
+    };
+    /** Custom description for admin UI */
+    description?: string;
+    /** Hide from admin navigation */
+    hidden?: boolean;
+    /** Enable preview mode */
+    preview?: boolean | ((doc: Record<string, unknown>) => string);
+    /** Custom action buttons displayed in the collection list header (alongside Create button) */
+    headerActions?: Array<{
+        id: string;
+        label: string;
+        /** HTTP endpoint path for the action (e.g., '/api/auth/api-keys') */
+        endpoint?: string;
+    }>;
+}
+export interface VersionsConfig {
+    /** Enable draft versions */
+    drafts?: boolean | DraftsConfig;
+    /** Maximum versions to keep per document */
+    maxPerDoc?: number;
+}
+export interface DraftsConfig {
+    /** Auto-save drafts */
+    autosave?: boolean | AutosaveConfig;
+}
+export interface AutosaveConfig {
+    /** Interval in milliseconds */
+    interval?: number;
+}
+export interface AuthConfig {
+    /** Enable token-based auth */
+    tokenExpiration?: number;
+    /** Verify email before login */
+    verify?: boolean;
+    /** Max login attempts before lockout */
+    maxLoginAttempts?: number;
+    /** Lockout interval in milliseconds */
+    lockTime?: number;
+    /** Cookies configuration */
+    cookies?: {
+        secure?: boolean;
+        sameSite?: 'strict' | 'lax' | 'none';
+        domain?: string;
+    };
+}
+export interface SoftDeleteConfig {
+    /** Column name for the deletion timestamp. @default 'deletedAt' */
+    field?: string;
+    /** Auto-purge soft-deleted records after this many days. Undefined means never purge. */
+    retentionDays?: number;
+}
+export interface TimestampsConfig {
+    /** Add createdAt field */
+    createdAt?: boolean;
+    /** Add updatedAt field */
+    updatedAt?: boolean;
+}
+export interface IndexDefinition {
+    /** Column names to include in the index */
+    columns: string[];
+    /** Whether this index enforces uniqueness */
+    unique?: boolean;
+    /** Custom index name (auto-generated from columns if omitted) */
+    name?: string;
+}
+export interface CollectionConfig {
+    /** Unique identifier for the collection (used in URLs and database) */
+    slug: string;
+    /** Custom labels */
+    labels?: {
+        singular?: string;
+        plural?: string;
+    };
+    /** Field definitions */
+    fields: Field[];
+    /** Admin panel configuration */
+    admin?: AdminConfig;
+    /** Access control functions */
+    access?: AccessConfig;
+    /** Lifecycle hooks */
+    hooks?: HooksConfig;
+    /** Enable authentication for this collection (makes it a user collection) */
+    auth?: boolean | AuthConfig;
+    /** Enable versioning */
+    versions?: boolean | VersionsConfig;
+    /** Timestamps configuration */
+    timestamps?: boolean | TimestampsConfig;
+    /** Enable soft deletes (sets deletedAt instead of removing row) */
+    softDelete?: boolean | SoftDeleteConfig;
+    /**
+     * Mark this collection as managed — schema is created but no CRUD routes are generated.
+     * Useful for tables owned by external systems (e.g., Better Auth) that should participate
+     * in schema generation and optionally appear in the admin UI.
+     */
+    managed?: boolean;
+    /** Custom database table/collection name */
+    dbName?: string;
+    /** Explicit database indexes for this collection */
+    indexes?: IndexDefinition[];
+    /** Default sort field */
+    defaultSort?: string;
+    /** GraphQL configuration */
+    graphQL?: {
+        singularName?: string;
+        pluralName?: string;
+        disableQueries?: boolean;
+        disableMutations?: boolean;
+    };
+    /**
+     * Default query constraints applied to all CRUD operations (find, findById, update, delete).
+     * For reads, constraints are injected into the query. For mutations, the document is checked
+     * post-fetch and rejected with DocumentNotFoundError if it falls outside the user's scope.
+     * Returns WHERE conditions to enforce, or undefined for no filtering.
+     */
+    defaultWhere?: (req: RequestContext) => Record<string, unknown> | undefined;
+    /** Custom endpoints */
+    endpoints?: EndpointConfig[];
+    /** Webhook subscriptions for this collection */
+    webhooks?: WebhookConfig[];
+}
+/** Events that trigger webhooks. */
+export type WebhookEvent = 'afterChange' | 'afterDelete' | 'afterCreate' | 'afterUpdate';
+/** Configuration for a single webhook subscription. */
+export interface WebhookConfig {
+    /** URL to send the webhook POST request to. */
+    url: string;
+    /** Events that trigger this webhook. Defaults to all events. */
+    events?: WebhookEvent[];
+    /** Secret for HMAC-SHA256 signature verification. */
+    secret?: string;
+    /** Maximum retries on failure. @default 0 */
+    retries?: number;
+    /** Custom headers to include in the request. */
+    headers?: Record<string, string>;
+}
+/** Payload sent in webhook POST requests. */
+export interface WebhookPayload {
+    /** The event that triggered the webhook. */
+    event: WebhookEvent;
+    /** The collection slug. */
+    collection: string;
+    /** The operation type. */
+    operation: 'create' | 'update' | 'delete' | 'softDelete' | 'restore';
+    /** Timestamp of the event. */
+    timestamp: string;
+    /** The document data (after the operation). */
+    doc: Record<string, unknown>;
+    /** The previous document data (for updates). */
+    previousDoc?: Record<string, unknown>;
+}
+/** Response from a custom endpoint handler. */
+export interface EndpointResponse {
+    status: number;
+    body: unknown;
+}
+/** Arguments passed to custom endpoint handlers. */
+export interface EndpointArgs {
+    /** Request context (user, headers) */
+    req: RequestContext;
+    /** This collection's config */
+    collection: CollectionConfig;
+    /** Request body (for POST/PUT/PATCH endpoints) */
+    body?: Record<string, unknown>;
+    /**
+     * Async helper to query any collection.
+     * Returns the raw API result (find returns { docs, totalDocs }, findById returns doc, etc.).
+     * Abstracts away server-core imports so collections remain isomorphic.
+     */
+    query: EndpointQueryHelper;
+}
+/** Query helper for custom endpoints - provides access to collection data without server-core imports. */
+export interface EndpointQueryHelper {
+    find: (slug: string, options?: {
+        limit?: number;
+        page?: number;
+    }) => Promise<{
+        docs: Record<string, unknown>[];
+        totalDocs: number;
+    }>;
+    findById: (slug: string, id: string) => Promise<Record<string, unknown> | null>;
+    count: (slug: string) => Promise<number>;
+    create: (slug: string, data: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    update: (slug: string, id: string, data: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    delete: (slug: string, id: string) => Promise<{
+        id: string;
+        deleted: boolean;
+    }>;
+    /**
+     * Execute multiple operations within a database transaction.
+     * All operations succeed or all are rolled back.
+     * Falls back to non-transactional execution if adapter doesn't support transactions.
+     */
+    transaction: <T>(callback: (query: EndpointQueryHelper) => Promise<T>) => Promise<T>;
+}
+export interface EndpointConfig {
+    path: string;
+    method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    handler: (args: EndpointArgs) => Promise<EndpointResponse>;
+}
+export interface GlobalConfig {
+    slug: string;
+    label?: string;
+    fields: Field[];
+    admin?: Omit<AdminConfig, 'useAsTitle' | 'defaultColumns' | 'pagination'>;
+    access?: Pick<AccessConfig, 'read' | 'update'>;
+    hooks?: Pick<HooksConfig, 'beforeValidate' | 'beforeChange' | 'afterChange' | 'beforeRead' | 'afterRead'>;
+    versions?: boolean | VersionsConfig;
+}

package/src/lib/collections/define-collection.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Define Collection Function
+ *
+ * Creates a collection configuration with proper typing.
+ * This is the main entry point for defining collections in Momentum CMS.
+ *
+ * Example:
+ * ```typescript
+ * export const Posts = defineCollection({
+ *   slug: 'posts',
+ *   fields: [
+ *     text('title', { required: true }),
+ *     richText('content'),
+ *   ],
+ *   access: {
+ *     read: () => true,
+ *     create: ({ req }) => !!req.user,
+ *   },
+ * });
+ * ```
+ */
+import type { CollectionConfig, GlobalConfig } from './collection.types';
+/**
+ * Define a collection configuration
+ * @param config Collection configuration object
+ * @returns The same configuration with proper typing
+ */
+export declare function defineCollection(config: CollectionConfig): CollectionConfig;
+/**
+ * Define a global configuration (single document, like site settings)
+ * @param config Global configuration object
+ * @returns The same configuration with proper typing
+ */
+export declare function defineGlobal(config: GlobalConfig): GlobalConfig;
+/**
+ * Get the soft delete field name for a collection.
+ * Returns the field name (default 'deletedAt') if soft delete is enabled, or null if not.
+ *
+ * @param config - The collection configuration
+ * @returns The deletedAt field name, or null if soft delete is not enabled
+ */
+export declare function getSoftDeleteField(config: CollectionConfig): string | null;
+/**
+ * Helper type to extract the document type from a collection
+ * Useful for typing API responses and database queries
+ */
+export type InferDocumentType<T extends CollectionConfig> = {
+    id: string | number;
+    createdAt?: Date;
+    updatedAt?: Date;
+} & {
+    [K in T['fields'][number]['name']]?: unknown;
+};

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

@@ -0,0 +1,5 @@
+export * from './collection.types';
+export { defineCollection, defineGlobal, getSoftDeleteField } from './define-collection';
+export type { InferDocumentType } from './define-collection';
+export { MediaCollection } from './media.collection';
+export type { MediaDocument } from './media.collection';

package/src/lib/collections/media.collection.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Built-in Media Collection for Momentum CMS
+ * Stores metadata for uploaded files
+ */
+/**
+ * Built-in Media collection for storing file upload metadata.
+ * Users can override this by defining their own 'media' collection.
+ */
+export declare const MediaCollection: import("./collection.types").CollectionConfig;
+/**
+ * Type for a media document.
+ */
+export interface MediaDocument {
+    id: string;
+    filename: string;
+    mimeType: string;
+    filesize?: number;
+    path: string;
+    url?: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    focalPoint?: {
+        x: number;
+        y: number;
+    };
+    createdAt: string;
+    updatedAt: string;
+}