@momentumcms/core 0.5.0 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@momentumcms/core",
-	"version": "0.5.0",
+	"version": "0.5.2",
 	"description": "Core collection config, fields, hooks, and access control for Momentum CMS",
 	"license": "MIT",
 	"author": "Momentum CMS Contributors",

package/src/generators/generator.cjs

@@ -711,7 +711,9 @@ function generateAdminConfig(config, typesRelPath) {
   }
   lines.push(`import type { ${typeImports.join(", ")} } from '${typesRelPath}';`);
   for (const plugin of pluginsWithAdminRoutes) {
-    const imp = plugin.browserImports.adminRoutes;
+    const imp = plugin.browserImports?.adminRoutes;
+    if (!imp)
+      continue;
     lines.push(`import { ${imp.exportName} } from '${imp.path}';`);
   }
   lines.push("");
@@ -744,9 +746,11 @@ ${globalItems},
     }
   }
   if (pluginsWithAdminRoutes.length > 0) {
-    const pluginItems = pluginsWithAdminRoutes.map((p) => {
-      const imp = p.browserImports.adminRoutes;
-      return `		{ name: ${JSON.stringify(p.name)}, adminRoutes: ${imp.exportName} }`;
+    const pluginItems = pluginsWithAdminRoutes.flatMap((p) => {
+      const imp = p.browserImports?.adminRoutes;
+      if (!imp)
+        return [];
+      return [`		{ name: ${JSON.stringify(p.name)}, adminRoutes: ${imp.exportName} }`];
     }).join(",\n");
     lines.push(`	plugins: [
 ${pluginItems},

package/src/generators/generator.js

@@ -680,7 +680,9 @@ function generateAdminConfig(config, typesRelPath) {
   }
   lines.push(`import type { ${typeImports.join(", ")} } from '${typesRelPath}';`);
   for (const plugin of pluginsWithAdminRoutes) {
-    const imp = plugin.browserImports.adminRoutes;
+    const imp = plugin.browserImports?.adminRoutes;
+    if (!imp)
+      continue;
     lines.push(`import { ${imp.exportName} } from '${imp.path}';`);
   }
   lines.push("");
@@ -713,9 +715,11 @@ ${globalItems},
     }
   }
   if (pluginsWithAdminRoutes.length > 0) {
-    const pluginItems = pluginsWithAdminRoutes.map((p) => {
-      const imp = p.browserImports.adminRoutes;
-      return `		{ name: ${JSON.stringify(p.name)}, adminRoutes: ${imp.exportName} }`;
+    const pluginItems = pluginsWithAdminRoutes.flatMap((p) => {
+      const imp = p.browserImports?.adminRoutes;
+      if (!imp)
+        return [];
+      return [`		{ name: ${JSON.stringify(p.name)}, adminRoutes: ${imp.exportName} }`];
     }).join(",\n");
     lines.push(`	plugins: [
 ${pluginItems},

package/src/index.cjs

@@ -128,6 +128,8 @@ function getUploadFieldMapping(config) {
   if (!isUploadCollection(config))
     return null;
   const u = config.upload;
+  if (!u)
+    return null;
   return {
     filename: u.filenameField ?? "filename",
     mimeType: u.mimeTypeField ?? "mimeType",
@@ -443,6 +445,31 @@ function validateRowCount(name, label, count, minRows, maxRows, errors) {
 }
 
 // libs/core/src/lib/collections/media.collection.ts
+var validateFocalPoint = (value) => {
+  if (value === null || value === void 0)
+    return true;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    return "Focal point must be an object with x and y coordinates";
+  }
+  const fp = Object.fromEntries(Object.entries(value));
+  if (!("x" in fp) || !("y" in fp)) {
+    return "Focal point must have both x and y properties";
+  }
+  const { x, y } = fp;
+  if (typeof x !== "number" || !Number.isFinite(x)) {
+    return "Focal point x must be a finite number";
+  }
+  if (typeof y !== "number" || !Number.isFinite(y)) {
+    return "Focal point y must be a finite number";
+  }
+  if (x < 0 || x > 1) {
+    return `Focal point x must be between 0 and 1 (received ${x})`;
+  }
+  if (y < 0 || y > 1) {
+    return `Focal point y must be between 0 and 1 (received ${y})`;
+  }
+  return true;
+};
 var MediaCollection = defineCollection({
   slug: "media",
   labels: {
@@ -497,6 +524,14 @@ var MediaCollection = defineCollection({
     json("focalPoint", {
       label: "Focal Point",
       description: "Focal point coordinates for image cropping",
+      validate: validateFocalPoint,
+      admin: {
+        hidden: true
+      }
+    }),
+    json("sizes", {
+      label: "Image Sizes",
+      description: "Generated image size variants",
       admin: {
         hidden: true
       }
@@ -586,7 +621,7 @@ function isOwner(ownerField = "createdBy") {
 function resolveMigrationMode(mode) {
   if (mode === "push" || mode === "migrate")
     return mode;
-  const env = process.env["NODE_ENV"];
+  const env = globalThis["process"]?.env?.["NODE_ENV"];
   if (env === "production")
     return "migrate";
   return "push";

package/src/index.d.ts

@@ -13,3 +13,5 @@ export * from './lib/storage';
 export * from './lib/seeding';
 export * from './lib/versions';
 export * from './lib/migrations';
+export * from './lib/queue';
+export * from './lib/cron';

package/src/index.js

@@ -47,6 +47,8 @@ function getUploadFieldMapping(config) {
   if (!isUploadCollection(config))
     return null;
   const u = config.upload;
+  if (!u)
+    return null;
   return {
     filename: u.filenameField ?? "filename",
     mimeType: u.mimeTypeField ?? "mimeType",
@@ -362,6 +364,31 @@ function validateRowCount(name, label, count, minRows, maxRows, errors) {
 }
 
 // libs/core/src/lib/collections/media.collection.ts
+var validateFocalPoint = (value) => {
+  if (value === null || value === void 0)
+    return true;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    return "Focal point must be an object with x and y coordinates";
+  }
+  const fp = Object.fromEntries(Object.entries(value));
+  if (!("x" in fp) || !("y" in fp)) {
+    return "Focal point must have both x and y properties";
+  }
+  const { x, y } = fp;
+  if (typeof x !== "number" || !Number.isFinite(x)) {
+    return "Focal point x must be a finite number";
+  }
+  if (typeof y !== "number" || !Number.isFinite(y)) {
+    return "Focal point y must be a finite number";
+  }
+  if (x < 0 || x > 1) {
+    return `Focal point x must be between 0 and 1 (received ${x})`;
+  }
+  if (y < 0 || y > 1) {
+    return `Focal point y must be between 0 and 1 (received ${y})`;
+  }
+  return true;
+};
 var MediaCollection = defineCollection({
   slug: "media",
   labels: {
@@ -416,6 +443,14 @@ var MediaCollection = defineCollection({
     json("focalPoint", {
       label: "Focal Point",
       description: "Focal point coordinates for image cropping",
+      validate: validateFocalPoint,
+      admin: {
+        hidden: true
+      }
+    }),
+    json("sizes", {
+      label: "Image Sizes",
+      description: "Generated image size variants",
       admin: {
         hidden: true
       }
@@ -505,7 +540,7 @@ function isOwner(ownerField = "createdBy") {
 function resolveMigrationMode(mode) {
   if (mode === "push" || mode === "migrate")
     return mode;
-  const env = process.env["NODE_ENV"];
+  const env = globalThis["process"]?.env?.["NODE_ENV"];
   if (env === "production")
     return "migrate";
   return "push";

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

@@ -3,6 +3,7 @@
  * Defines the structure of collections (similar to Payload CMS)
  */
 import type { Field } from '../fields/field.types';
+import type { ImageSizeConfig } from '../storage';
 export interface AccessArgs {
     req: RequestContext;
     id?: string | number;
@@ -137,6 +138,10 @@ export interface UploadCollectionConfig {
     pathField?: string;
     /** Field name for the public URL. @default 'url' */
     urlField?: string;
+    /** Image sizes to generate on upload (images only) */
+    imageSizes?: ImageSizeConfig[];
+    /** Default output format for generated sizes. @default 'original' */
+    formatPreference?: 'jpeg' | 'webp' | 'avif' | 'original';
 }
 export interface TimestampsConfig {
     /** Add createdAt field */

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

@@ -2,6 +2,13 @@
  * Built-in Media Collection for Momentum CMS
  * Stores metadata for uploaded files
  */
+import type { ValidateFunction } from '../fields/field.types';
+/**
+ * Validates a focalPoint value: null/undefined is allowed (optional field).
+ * When present, must be a plain object with exactly `x` and `y` properties,
+ * both finite numbers in the [0, 1] range.
+ */
+export declare const validateFocalPoint: ValidateFunction;
 /**
  * Built-in Media collection for storing file upload metadata.
  * Users can override this by defining their own 'media' collection.
@@ -24,6 +31,14 @@ export interface MediaDocument {
         x: number;
         y: number;
     };
+    sizes?: Record<string, {
+        url: string;
+        path: string;
+        width: number;
+        height: number;
+        mimeType: string;
+        filesize: number;
+    }>;
     createdAt: string;
     updatedAt: string;
 }

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

@@ -0,0 +1,29 @@
+/**
+ * Cron module for Momentum CMS
+ * Defines types for recurring job schedules
+ */
+import type { JobPriority } from '../queue';
+/**
+ * A recurring job schedule definition.
+ * Used by the cron plugin to periodically enqueue jobs into the queue.
+ */
+export interface RecurringJobDefinition {
+    /** Unique name for this recurring schedule */
+    name: string;
+    /** Job type to enqueue (must match a registered handler in the queue plugin) */
+    type: string;
+    /** Cron expression (5-field: minute hour day-of-month month day-of-week) */
+    cron: string;
+    /** Job payload */
+    payload?: unknown;
+    /** Queue name. @default 'default' */
+    queue?: string;
+    /** Priority (0=highest, 9=lowest). @default 5 */
+    priority?: JobPriority;
+    /** Maximum retry attempts. @default 3 */
+    maxRetries?: number;
+    /** Timeout in ms. @default 30000 */
+    timeout?: number;
+    /** Whether the schedule is enabled. @default true */
+    enabled?: boolean;
+}

package/src/lib/fields/field.types.d.ts

@@ -20,8 +20,8 @@ export interface FieldAdminConfig {
     readOnly?: boolean;
     hidden?: boolean;
     placeholder?: string;
-    /** For blocks fields: editor rendering mode. 'visual' enables the WYSIWYG block editor. */
-    editor?: 'visual' | 'form';
+    /** Editor rendering mode. 'visual' enables WYSIWYG block editor; 'email-builder' enables email template builder; 'form-builder' enables form schema builder for json fields. */
+    editor?: 'visual' | 'form' | 'email-builder' | 'form-builder';
     /** Render this group field as a collapsible accordion section */
     collapsible?: boolean;
     /** Whether the collapsible section starts expanded (default: false) */

package/src/lib/plugins.d.ts

@@ -5,7 +5,7 @@
  * These live in @momentumcms/core to avoid circular dependencies.
  * Runtime implementations (PluginRunner, etc.) live in @momentumcms/plugins/core.
  */
-import type { CollectionConfig } from './collections';
+import type { CollectionConfig, UserContext } from './collections';
 import type { MomentumConfig } from './config';
 /**
  * Descriptor for Express middleware/routes that a plugin wants auto-mounted.
@@ -127,6 +127,12 @@ export interface MomentumAPI {
     collection(slug: string): unknown;
     /** Get the current config */
     getConfig(): MomentumConfig;
+    /** Return a new API instance with merged context (immutable). */
+    setContext(ctx: {
+        user?: UserContext;
+        depth?: number;
+        showHiddenFields?: boolean;
+    }): MomentumAPI;
 }
 /**
  * A Momentum CMS plugin.

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

@@ -0,0 +1,208 @@
+/**
+ * Queue module for Momentum CMS
+ * Defines interfaces for job queue adapters
+ */
+/**
+ * Job status lifecycle:
+ * pending -> active -> completed
+ *                   -> failed (retries remain) -> pending (retry)
+ *                   -> dead (max retries exceeded)
+ */
+export type JobStatus = 'pending' | 'active' | 'completed' | 'failed' | 'dead';
+/**
+ * Job priority levels. Lower number = higher priority.
+ * 0 is the highest priority, 9 is the lowest.
+ */
+export type JobPriority = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+/**
+ * Backoff strategy for job retries.
+ */
+export interface BackoffStrategy {
+    /** Backoff type */
+    type: 'exponential' | 'linear' | 'fixed';
+    /** Base delay in milliseconds */
+    delay: number;
+    /** Maximum delay in milliseconds (cap for exponential). @default 300000 (5 minutes) */
+    maxDelay?: number;
+}
+/**
+ * Options when enqueuing a job.
+ */
+export interface EnqueueOptions {
+    /** Queue name. @default 'default' */
+    queue?: string;
+    /** Priority (0=highest, 9=lowest). @default 5 */
+    priority?: JobPriority;
+    /** Delay execution until this Date (ISO string or Date). */
+    runAt?: string | Date;
+    /** Maximum retry attempts. @default 3 */
+    maxRetries?: number;
+    /** Backoff strategy for retries. @default { type: 'exponential', delay: 1000 } */
+    backoff?: BackoffStrategy;
+    /** Maximum time in ms a job can run before being considered stalled. @default 30000 */
+    timeout?: number;
+    /** Unique key for deduplication. If a pending/active job with this key exists, the new job is skipped. */
+    uniqueKey?: string;
+    /** Arbitrary metadata attached to the job (not part of the handler payload). */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A job record as stored/returned by the adapter.
+ */
+export interface Job<T = unknown> {
+    /** Unique job ID */
+    id: string;
+    /** Job type name (matches a registered handler) */
+    type: string;
+    /** Job payload (serialized as JSON) */
+    payload: T;
+    /** Current job status */
+    status: JobStatus;
+    /** Queue name */
+    queue: string;
+    /** Priority (0-9) */
+    priority: JobPriority;
+    /** Number of attempts made */
+    attempts: number;
+    /** Maximum retry attempts */
+    maxRetries: number;
+    /** Backoff configuration */
+    backoff: BackoffStrategy;
+    /** Timeout in milliseconds */
+    timeout: number;
+    /** Unique deduplication key */
+    uniqueKey?: string;
+    /** When the job should run (null = immediately) */
+    runAt: string | null;
+    /** When the job was last started */
+    startedAt?: string;
+    /** When the job completed or failed permanently */
+    finishedAt?: string;
+    /** Last error message (if failed/dead) */
+    lastError?: string;
+    /** Arbitrary metadata */
+    metadata?: Record<string, unknown>;
+    /** ISO timestamp of creation */
+    createdAt: string;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+}
+/**
+ * Options for fetching the next batch of jobs to process.
+ */
+export interface FetchJobsOptions {
+    /** Queue name to fetch from. @default 'default' */
+    queue?: string;
+    /** Maximum number of jobs to fetch. @default 1 */
+    limit?: number;
+}
+/**
+ * Options for querying jobs (admin dashboard, monitoring).
+ */
+export interface JobQueryOptions {
+    /** Filter by status */
+    status?: JobStatus;
+    /** Filter by queue name */
+    queue?: string;
+    /** Filter by job type */
+    type?: string;
+    /** Pagination limit. @default 50 */
+    limit?: number;
+    /** Pagination page (1-based). @default 1 */
+    page?: number;
+}
+/**
+ * Result of a job query.
+ */
+export interface JobQueryResult {
+    jobs: Job[];
+    total: number;
+    page: number;
+    limit: number;
+}
+/**
+ * Queue statistics for monitoring.
+ */
+export interface QueueStats {
+    /** Queue name */
+    queue: string;
+    /** Count of jobs by status */
+    counts: Record<JobStatus, number>;
+    /** Oldest pending job age in milliseconds */
+    oldestPendingAge?: number;
+}
+/**
+ * Queue adapter interface.
+ * Implement this interface to create custom queue backends (PostgreSQL, Redis, etc.).
+ */
+export interface QueueAdapter {
+    /**
+     * Initialize the queue backend (create indexes, etc.).
+     * Called once during server startup after collection tables are created.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Enqueue a new job.
+     * @param type - Job type name (matches a registered handler)
+     * @param payload - Job payload data
+     * @param options - Enqueue options
+     * @returns The created job record
+     */
+    enqueue(type: string, payload: unknown, options?: EnqueueOptions): Promise<Job>;
+    /**
+     * Fetch the next batch of jobs ready for processing.
+     * Must use atomic locking (e.g., SKIP LOCKED) to prevent double-processing.
+     * Jobs are returned in priority order (lowest number first), then by runAt/createdAt.
+     */
+    fetchJobs(options?: FetchJobsOptions): Promise<Job[]>;
+    /**
+     * Mark a job as completed.
+     */
+    completeJob(jobId: string): Promise<void>;
+    /**
+     * Mark a job as failed. If retries remain, schedules the next attempt.
+     * If max retries exceeded, moves to 'dead' status.
+     */
+    failJob(jobId: string, error: string): Promise<void>;
+    /**
+     * Query jobs for monitoring/admin UI.
+     */
+    queryJobs(options?: JobQueryOptions): Promise<JobQueryResult>;
+    /**
+     * Get statistics for one or all queues.
+     * @param queue - Optional queue name (all queues if omitted)
+     */
+    getStats(queue?: string): Promise<QueueStats[]>;
+    /**
+     * Get a single job by ID.
+     * @returns The job record, or null if not found
+     */
+    getJob(jobId: string): Promise<Job | null>;
+    /**
+     * Delete a specific job by ID.
+     * @returns True if deleted
+     */
+    deleteJob(jobId: string): Promise<boolean>;
+    /**
+     * Purge completed/dead jobs older than the given age.
+     * @param olderThanMs - Age threshold in milliseconds
+     * @param status - Status to purge. @default 'completed'
+     * @returns Number of jobs purged
+     */
+    purgeJobs(olderThanMs: number, status?: 'completed' | 'dead'): Promise<number>;
+    /**
+     * Retry a dead job (move it back to pending with reset attempts).
+     * @returns The updated job
+     */
+    retryJob(jobId: string): Promise<Job>;
+    /**
+     * Detect and recover stalled jobs (active jobs that exceeded their timeout).
+     * Moves them back to pending for retry, or to dead if maxRetries exceeded.
+     * @returns Number of jobs recovered
+     */
+    recoverStalledJobs(): Promise<number>;
+    /**
+     * Graceful shutdown. Releases any held resources.
+     */
+    shutdown(): Promise<void>;
+}

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

@@ -1,7 +1,57 @@
 /**
  * Storage module for Momentum CMS
- * Defines interfaces for file storage adapters
+ * Defines interfaces for file storage adapters and image processing
  */
+/**
+ * Describes one output size for image processing.
+ */
+export interface ImageSizeConfig {
+    /** Named key for this size (e.g. 'thumbnail', 'medium') */
+    name: string;
+    /** Target width in pixels. Undefined = proportional from height. */
+    width?: number;
+    /** Target height in pixels. Undefined = proportional from width. */
+    height?: number;
+    /**
+     * Resizing strategy.
+     * - 'contain': shrink to fit, no cropping
+     * - 'cover': resize + crop to fill exact dimensions (uses focalPoint)
+     * - 'fill': stretch to exact dimensions
+     * - 'width': resize to width, height proportional
+     * - 'height': resize to height, width proportional
+     * @default 'cover'
+     */
+    fit?: 'contain' | 'cover' | 'fill' | 'width' | 'height';
+    /** Output format. When undefined, uses source format or global formatPreference. */
+    format?: 'jpeg' | 'webp' | 'avif' | 'png';
+    /** JPEG/WebP/AVIF quality (1-100). @default 80 */
+    quality?: number;
+}
+/**
+ * Image dimensions in pixels.
+ */
+export interface ImageDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * Pluggable image processor interface.
+ * Implement this to provide custom image processing backends.
+ */
+export interface ImageProcessor {
+    /** Detect image dimensions without full decode when possible. */
+    getDimensions(buffer: Uint8Array, mimeType: string): Promise<ImageDimensions>;
+    /** Process one size variant. Returns the processed buffer and its dimensions. */
+    processVariant(buffer: Uint8Array, mimeType: string, size: ImageSizeConfig, focalPoint?: {
+        x: number;
+        y: number;
+    }): Promise<{
+        buffer: Uint8Array;
+        width: number;
+        height: number;
+        mimeType: string;
+    }>;
+}
 /**
  * Represents an uploaded file before storage.
  */
@@ -12,8 +62,8 @@ export interface UploadedFile {
     mimeType: string;
     /** File size in bytes */
     size: number;
-    /** File content as Buffer */
-    buffer: Buffer;
+    /** File content (Uint8Array for universal compat; Node Buffer extends Uint8Array) */
+    buffer: Uint8Array;
 }
 /**
  * Represents a file after it has been stored.
@@ -82,5 +132,5 @@ export interface StorageAdapter {
      * @param path - The storage path/key
      * @returns The file as a Buffer, or null if not found
      */
-    read?(path: string): Promise<Buffer | null>;
+    read?(path: string): Promise<Uint8Array | null>;
 }