@easy-cms/core 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -194,6 +194,21 @@ interface FieldValidateContext {
 }
 /** Return `true` when valid, or an error message to show on the field. */
 type FieldValidate<TValue> = (value: TValue | null | undefined, ctx: FieldValidateContext) => true | string | Promise<true | string>;
+/**
+ * A Web Component from an admin module (`admin.modules`), by its tag name, which must start
+ * with `ecms-`. `props` (plain JSON) reach the element as its `options` property.
+ */
+type AdminComponent = string | {
+    readonly tag: string;
+    readonly props?: Readonly<Record<string, unknown>>;
+};
+/** How the admin shows a field, with components from admin modules. */
+interface FieldAdmin {
+    /** Shown instead of the field's input; the admin keeps the label and error messages. */
+    readonly component?: AdminComponent;
+    /** Shown below the field, e.g. a length meter or a preview. */
+    readonly after?: readonly AdminComponent[];
+}
 interface BaseField<TType extends string, TValue> {
     readonly type: TType;
     readonly name: string;
@@ -211,6 +226,10 @@ interface BaseField<TType extends string, TValue> {
      * hasMany fields: localize the fields inside a group or array instead.
      */
     readonly localized?: boolean;
+    /** `sidebar`: shown in the edit page's side panel instead of the main form (top-level fields). */
+    readonly position?: 'sidebar';
+    /** Custom admin components for this field. */
+    readonly admin?: FieldAdmin;
 }
 interface TextField extends BaseField<'text', string> {
     readonly minLength?: number;
@@ -427,6 +446,11 @@ interface VersionsConfig {
     /** Versions kept per document; older ones are deleted. Default 50. */
     readonly max?: number;
 }
+/** Custom admin components for a collection's or global's edit page. */
+interface ContainerAdmin {
+    /** Panels in the edit page's side column, below publishing (components from admin modules). */
+    readonly sidebar?: readonly AdminComponent[];
+}
 interface CollectionConfig {
     /** URL and table name. Lowercase letters, digits, `-` and `_`. */
     readonly slug: string;
@@ -436,6 +460,12 @@ interface CollectionConfig {
     };
     /** Icon in the admin menu. Default `file-text`. */
     readonly icon?: AdminIcon;
+    /**
+     * How the admin opens documents from the list: `drawer` slides a panel over the list, handy
+     * for small collections (categories, tags). Default `page`. Collections with drafts, versions
+     * or live preview always use the page.
+     */
+    readonly editIn?: 'page' | 'drawer';
     readonly fields: readonly Field[];
     /** Top-level field shown as the document title in the admin UI. */
     readonly useAsTitle?: string;
@@ -453,6 +483,8 @@ interface CollectionConfig {
     readonly preview?: PreviewURL;
     readonly access?: CollectionAccess;
     readonly hooks?: CollectionHooks;
+    /** Custom admin components. */
+    readonly admin?: ContainerAdmin;
 }
 interface GlobalConfig {
     readonly slug: string;
@@ -469,6 +501,8 @@ interface GlobalConfig {
     readonly preview?: PreviewURL;
     readonly access?: GlobalAccess;
     readonly hooks?: GlobalHooks;
+    /** Custom admin components. */
+    readonly admin?: ContainerAdmin;
 }
 type AdminLocale = 'en' | 'th';
 /** Icons a collection or global can show in the admin menu ([Lucide](https://lucide.dev) names). */
@@ -490,6 +524,24 @@ interface AdminConfig {
     readonly locale?: AdminLocale;
     /** Name, logo and color of the admin UI. */
     readonly brand?: AdminBrand;
+    /**
+     * The public site, for the admin's "View site" link: a path (`/`) or an `https://` URL.
+     * Default `/` with Nuxt and Next.js; none with the standalone server.
+     */
+    readonly siteUrl?: string;
+    /**
+     * Order of collections in the admin menu, by slug, e.g. `['posts', 'categories', 'media']`.
+     * Collections not listed follow in config order, with the media library last.
+     */
+    readonly menu?: readonly string[];
+    /**
+     * JavaScript modules the admin loads after login, which define Web Components used by
+     * fields (`admin.component`, `admin.after`) and edit pages (`admin.sidebar`). Each entry is a
+     * package export (`'@easy-cms/plugin-seo/admin'`) or a file path relative to the project root
+     * (`'./admin/color-picker.js'`), resolved on the server. A module must be one self-contained ES
+     * module file. Remote URLs are not allowed.
+     */
+    readonly modules?: readonly string[];
 }
 interface ImageSize {
     /** Key in `media.sizes`, e.g. `thumbnail`. */
@@ -530,6 +582,36 @@ interface AuthConfig {
      */
     readonly trustedOrigins?: readonly string[];
 }
+/** What an endpoint's handler receives. */
+interface EndpointRequest {
+    readonly request: Request;
+    readonly url: URL;
+    /** Values of `:name` segments in the endpoint's path. */
+    readonly params: Readonly<Record<string, string>>;
+    /** The logged-in user (session cookie or Bearer token), or `null`. */
+    readonly user: AuthUser | null;
+    /** The Local API. Pass `{ user, overrideAccess: false }` to apply the user's access rules. */
+    readonly cms: EasyCMS;
+    /** The request's JSON body, which must be an object (at most 1 MB). */
+    json(): Promise<Record<string, unknown>>;
+}
+/**
+ * A custom REST endpoint, served under `routes.api`. Writes from the browser pass the same
+ * CSRF check as the built-in endpoints.
+ */
+interface Endpoint {
+    /**
+     * Path under the API, e.g. `/seo/generate` or `/stats/:collection`. The first segment must
+     * not be a collection slug or one of `users`, `globals`, `admin`, `jobs`.
+     */
+    readonly path: string;
+    readonly method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    /**
+     * Returns a `Response`, or a value that is sent as JSON. Throw an Easy CMS error
+     * (`UnauthorizedError`, `ForbiddenError`, `ValidationError`, `NotFoundError`) for error responses.
+     */
+    readonly handler: (request: EndpointRequest) => MaybePromise<unknown>;
+}
 /** Receives the config and returns a modified copy. Runs before validation. */
 type Plugin = (config: Config) => MaybePromise<Config>;
 interface Config {
@@ -567,10 +649,12 @@ interface Config {
      */
     readonly collections?: readonly CollectionConfig[];
     readonly globals?: readonly GlobalConfig[];
+    /** Custom REST endpoints, e.g. from plugins. */
+    readonly endpoints?: readonly Endpoint[];
     readonly plugins?: readonly Plugin[];
 }
 /** The config after plugins ran, validation passed and defaults were applied. */
-interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes' | 'admin' | 'upload' | 'auth' | 'collections' | 'globals' | 'plugins'> {
+interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes' | 'admin' | 'upload' | 'auth' | 'collections' | 'globals' | 'endpoints' | 'plugins'> {
     readonly cors: readonly string[] | '*';
     /** `null` without localization. */
     readonly localization: Required<LocalizationConfig> | null;
@@ -580,6 +664,7 @@ interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes'
     readonly auth: Required<AuthConfig>;
     readonly collections: readonly CollectionConfig[];
     readonly globals: readonly GlobalConfig[];
+    readonly endpoints: readonly Endpoint[];
 }
 /**
  * Declares the Easy CMS config. Returns it unchanged, keeping literal types
@@ -908,9 +993,11 @@ declare class EasyCMS<C extends Config = Config> {
     readonly auth: Auth;
     /** Where uploaded files are stored. */
     readonly storage: StorageAdapter;
+    /** Project root: relative paths in the config (e.g. `admin.modules`) start here. */
+    readonly cwd: string;
     private readonly versions;
     private readonly webhooks;
-    constructor(config: ResolvedConfig, db: Database, logger?: Logger, storage?: StorageAdapter);
+    constructor(config: ResolvedConfig, db: Database, logger?: Logger, storage?: StorageAdapter, cwd?: string);
     find<S extends Slug<C>>(collection: S, options?: FindOptions): Promise<PaginatedDocs<Doc<C, S>>>;
     findById<S extends Slug<C>>(collection: S, id: ID, options?: ReadOptions): Promise<Doc<C, S> | null>;
     count<S extends Slug<C>>(collection: S, options?: {
@@ -1337,12 +1424,29 @@ declare const DEFAULT_ADMIN_PATH = "/admin";
 declare const DEFAULT_API_PATH = "/api/cms";
 declare const DEFAULT_MAX_FILE_SIZE: number;
 declare const DEFAULT_TOKEN_EXPIRATION: number;
+/**
+ * Runs the config's plugins in order, without validating the result. Build tools use it to
+ * read what plugins add (e.g. `admin.modules`) when the config is not complete yet.
+ */
+declare function applyPlugins(input: Config): Promise<Config>;
 /**
  * Runs plugins in order, adds the built-in collections, validates the result
  * and fills in defaults. Throws `ConfigError`. Resolving twice is a no-op.
  */
 declare function resolveConfig(input: Config | ResolvedConfig): Promise<ResolvedConfig>;
 
+/**
+ * Finds the file of an admin module (`admin.modules`): a package export or a path relative to
+ * the project root. Looks from the project root first, then from the server's entry file
+ * (a Nuxt `.output/server` build keeps traced packages next to it). `undefined` when not found.
+ */
+declare function resolveAdminModule(specifier: string, cwd?: string): string | undefined;
+
+/** A Web Component from an admin module, with its `props` (plain JSON). */
+interface AdminComponentRef {
+    tag: string;
+    props?: Record<string, unknown>;
+}
 /** A field as the admin UI sees it: plain JSON, no functions. */
 interface AdminField {
     name: string;
@@ -1378,6 +1482,13 @@ interface AdminField {
     readOnly?: boolean;
     /** One value per content locale. */
     localized?: boolean;
+    /** Shown in the edit page's side panel. */
+    position?: 'sidebar';
+    /** Components from admin modules: instead of the input, and below the field. */
+    admin?: {
+        component?: AdminComponentRef;
+        after?: AdminComponentRef[];
+    };
 }
 interface AdminCollection {
     slug: string;
@@ -1387,6 +1498,8 @@ interface AdminCollection {
     };
     icon?: string;
     useAsTitle?: string;
+    /** Documents open in a panel over the list. */
+    editIn?: 'drawer';
     drafts: boolean;
     versions: boolean;
     /** Has live preview (`preview` in the config). */
@@ -1394,6 +1507,8 @@ interface AdminCollection {
     /** Publishing can be scheduled. */
     schedule: boolean;
     fields: AdminField[];
+    /** Panels from admin modules in the edit page's side column. */
+    sidebar?: AdminComponentRef[];
     permissions: {
         read: boolean;
         create: boolean;
@@ -1412,6 +1527,8 @@ interface AdminGlobal {
     /** Publishing can be scheduled. */
     schedule: boolean;
     fields: AdminField[];
+    /** Panels from admin modules in the edit page's side column. */
+    sidebar?: AdminComponentRef[];
     permissions: {
         read: boolean;
         update: boolean;
@@ -1419,6 +1536,8 @@ interface AdminGlobal {
 }
 interface AdminSchema {
     locale: AdminLocale;
+    /** Menu order of collections (`admin.menu`); unlisted ones follow. */
+    menu: string[];
     /** Content locales, when the config has `localization`. */
     localization: {
         locales: string[];
@@ -1426,6 +1545,8 @@ interface AdminSchema {
     } | null;
     collections: AdminCollection[];
     globals: AdminGlobal[];
+    /** URLs under the API of the admin modules to load (`admin.modules`). */
+    modules: string[];
 }
 
 declare const SESSION_COOKIE = "ecms-session";
@@ -1456,4 +1577,4 @@ declare const BUILTIN_COLLECTIONS: readonly ["users", "media"];
 /** Checks a config and returns every problem found. An empty array means it is valid. */
 declare function validateConfig(config: Config): ConfigIssue[];
 
-export { ADMIN_ICONS, type Access, type AccessArgs, type AccessOptions, type AdminBrand, type AdminCollection, type AdminConfig, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminSchema, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CollectionAccess, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_TOKEN_EXPIRATION, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DateField, type DepthOptions, EXTENSIONS, EasyCMS, EasyCMSError, type EmailField, FIELD_TYPES, type Field, type FieldAccess, type FieldAccessFn, type FieldError, type FieldType, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, PayloadTooLargeError, type Plugin, type PreviewTarget, type PreviewURL, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, UnauthorizedError, type UpdateInput, type UploadConfig, type UploadField, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, consoleLogger, createEasyCMS, createRestHandler, defineConfig, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isLoggedIn, loadConfig, localStorage, mergeForUpdate, mimeAllowed, parseId, populate, readCookie, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };
+export { ADMIN_ICONS, type Access, type AccessArgs, type AccessOptions, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminSchema, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CollectionAccess, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_TOKEN_EXPIRATION, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DateField, type DepthOptions, EXTENSIONS, EasyCMS, EasyCMSError, type EmailField, type Endpoint, type EndpointRequest, FIELD_TYPES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldType, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, PayloadTooLargeError, type Plugin, type PreviewTarget, type PreviewURL, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, UnauthorizedError, type UpdateInput, type UploadConfig, type UploadField, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, consoleLogger, createEasyCMS, createRestHandler, defineConfig, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isLoggedIn, loadConfig, localStorage, mergeForUpdate, mimeAllowed, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };

package/dist/index.js

@@ -1279,15 +1279,30 @@ function validateConfig(config) {
     const slug = checkSlug(collection2, `collections[${i}]`, seenCollections, add);
     if (slug) collectionSlugs.add(slug);
   });
+  const menu = config.admin?.menu;
+  if (menu !== void 0) {
+    if (!Array.isArray(menu)) {
+      add("admin.menu", "must be an array of collection slugs", "e.g. menu: ['posts', 'media']");
+    } else {
+      for (const [i, slug] of menu.entries()) {
+        if (typeof slug !== "string" || !collectionSlugs.has(slug))
+          add(`admin.menu[${i}]`, `unknown collection ${JSON.stringify(slug)}`);
+      }
+    }
+  }
   const seenGlobals = /* @__PURE__ */ new Set();
   globals.forEach((global2, i) => {
     checkSlug(global2, `globals[${i}]`, seenGlobals, add);
   });
+  validateEndpoints(config, collectionSlugs, add);
   collections.forEach((collection2, i) => {
     const path = `collections.${collection2.slug ?? `[${i}]`}`;
     validateContainer(collection2, path, collectionSlugs, add);
     validateUseAsTitle(collection2, path, add);
     validateIcon(collection2, path, add);
+    const editIn = collection2.editIn;
+    if (editIn !== void 0 && editIn !== "page" && editIn !== "drawer")
+      add(`${path}.editIn`, `must be "page" or "drawer" (got ${JSON.stringify(editIn)})`);
   });
   globals.forEach((global2, i) => {
     const path = `globals.${global2.slug ?? `[${i}]`}`;
@@ -1321,6 +1336,32 @@ function validateAdmin(config, add) {
   if (admin.locale !== void 0 && admin.locale !== "en" && admin.locale !== "th") {
     add("admin.locale", `must be "en" or "th" (got ${JSON.stringify(admin.locale)})`);
   }
+  const siteUrl = admin.siteUrl;
+  if (siteUrl !== void 0 && (typeof siteUrl !== "string" || !/^(\/|https?:\/\/)/.test(siteUrl))) {
+    add(
+      "admin.siteUrl",
+      'must be a path starting with "/" or an http(s) URL',
+      "e.g. siteUrl: 'https://example.com'"
+    );
+  }
+  const modules = admin.modules;
+  if (modules !== void 0) {
+    if (!Array.isArray(modules)) {
+      add("admin.modules", "must be an array", "e.g. modules: ['@easy-cms/plugin-seo/admin']");
+    } else {
+      for (const [i, module] of modules.entries()) {
+        if (typeof module !== "string" || module.trim() === "") {
+          add(`admin.modules[${i}]`, "must be a package export or a file path");
+        } else if (/^[a-z][a-z0-9+.-]*:/i.test(module) || module.startsWith("//")) {
+          add(
+            `admin.modules[${i}]`,
+            "must be a package export or a file path, not a URL",
+            "admin modules are served from your server, e.g. '@easy-cms/plugin-seo/admin'"
+          );
+        }
+      }
+    }
+  }
   const brand = admin.brand;
   if (brand === void 0) return;
   if (typeof brand !== "object" || brand === null) {
@@ -1559,6 +1600,15 @@ function validateContainer(container, path, collectionSlugs, add) {
       "preview: ({ doc }) => `/posts/${doc.slug}`"
     );
   }
+  const admin = container.admin;
+  if (admin !== void 0) {
+    if (typeof admin !== "object" || admin === null) {
+      add(`${path}.admin`, "must be an object", "e.g. admin: { sidebar: ['ecms-my-panel'] }");
+    } else {
+      const sidebar = admin.sidebar;
+      if (sidebar !== void 0) validateComponents(sidebar, `${path}.admin.sidebar`, add);
+    }
+  }
   const reserved = new Set(SYSTEM_FIELD_NAMES);
   if (container.drafts) reserved.add("status");
   validateFields2(container.fields, `${path}.fields`, reserved, collectionSlugs, add);
@@ -1595,6 +1645,20 @@ function validateFields2(fields, path, reserved, collectionSlugs, add) {
   }
 }
 function validateField(field, path, siblings, collectionSlugs, add) {
+  const position = field.position;
+  if (position !== void 0 && position !== "sidebar") {
+    add(`${path}.position`, `must be "sidebar" (got ${JSON.stringify(position)})`);
+  }
+  const admin = field.admin;
+  if (admin !== void 0) {
+    if (typeof admin !== "object" || admin === null) {
+      add(`${path}.admin`, "must be an object", "e.g. admin: { component: 'ecms-color-picker' }");
+    } else {
+      const { component, after } = admin;
+      if (component !== void 0) validateComponent(component, `${path}.admin.component`, add);
+      if (after !== void 0) validateComponents(after, `${path}.admin.after`, add);
+    }
+  }
   switch (field.type) {
     case "text":
     case "textarea":
@@ -1674,6 +1738,84 @@ function validateField(field, path, siblings, collectionSlugs, add) {
     }
   }
 }
+var ADMIN_COMPONENT_TAG = /^ecms-[a-z0-9]+(-[a-z0-9]+)*$/;
+function validateComponent(component, path, add) {
+  const tag = typeof component === "object" && component !== null ? component.tag : component;
+  if (typeof tag !== "string" || !ADMIN_COMPONENT_TAG.test(tag)) {
+    add(
+      path,
+      `must be a custom element name starting with "ecms-" (got ${JSON.stringify(tag)})`,
+      "e.g. 'ecms-color-picker' or { tag: 'ecms-color-picker', props: { palette: 'brand' } }"
+    );
+    return;
+  }
+  if (typeof component === "object" && component !== null) {
+    const props = component.props;
+    if (props !== void 0 && (typeof props !== "object" || props === null || Array.isArray(props)))
+      add(`${path}.props`, "must be an object of plain JSON values");
+  }
+}
+function validateComponents(components, path, add) {
+  if (!Array.isArray(components)) {
+    add(path, "must be an array of components", "e.g. ['ecms-seo-preview']");
+    return;
+  }
+  for (const [i, component] of components.entries()) {
+    validateComponent(component, `${path}[${i}]`, add);
+  }
+}
+var ENDPOINT_METHODS = ["get", "post", "put", "patch", "delete"];
+var ENDPOINT_SEGMENT = /^(:[A-Za-z_][A-Za-z0-9_]*|[A-Za-z0-9._~-]+)$/;
+var RESERVED_ENDPOINT_ROOTS = /* @__PURE__ */ new Set(["users", "globals", "admin", "jobs", "media"]);
+function validateEndpoints(config, collectionSlugs, add) {
+  const endpoints = config.endpoints;
+  if (endpoints === void 0) return;
+  if (!Array.isArray(endpoints)) {
+    add(
+      "endpoints",
+      "must be an array",
+      "e.g. endpoints: [{ path: '/hello', method: 'get', handler }]"
+    );
+    return;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  endpoints.forEach((endpoint, i) => {
+    const path = `endpoints[${i}]`;
+    if (typeof endpoint !== "object" || endpoint === null) {
+      add(path, "must be an object { path, method, handler }");
+      return;
+    }
+    const { path: route2, method, handler } = endpoint;
+    const segments = typeof route2 === "string" ? route2.split("/").slice(1) : [];
+    if (typeof route2 !== "string" || !route2.startsWith("/") || segments.length === 0 || !segments.every((s) => ENDPOINT_SEGMENT.test(s))) {
+      add(`${path}.path`, `must be a path like "/seo/generate" (got ${JSON.stringify(route2)})`);
+    } else {
+      const root = segments[0];
+      if (root.startsWith(":")) {
+        add(`${path}.path`, "must start with a fixed segment, not a parameter");
+      } else if (RESERVED_ENDPOINT_ROOTS.has(root) || collectionSlugs.has(root)) {
+        add(
+          `${path}.path`,
+          `"/${root}" is used by the built-in API`,
+          'start the path with your plugin or feature name, e.g. "/seo/generate"'
+        );
+      }
+    }
+    const verb = typeof method === "string" ? method.toLowerCase() : method;
+    if (typeof verb !== "string" || !ENDPOINT_METHODS.includes(verb)) {
+      add(
+        `${path}.method`,
+        `must be one of ${ENDPOINT_METHODS.join(", ")} (got ${JSON.stringify(method)})`
+      );
+    }
+    if (typeof handler !== "function") add(`${path}.handler`, "must be a function");
+    if (typeof route2 === "string" && typeof verb === "string") {
+      const key2 = `${verb} ${route2.replace(/:[A-Za-z_][A-Za-z0-9_]*/g, ":")}`;
+      if (seen.has(key2)) add(`${path}.path`, `duplicate endpoint ${verb.toUpperCase()} ${route2}`);
+      seen.add(key2);
+    }
+  });
+}
 function checkRange(min, max, minName, maxName, path, add) {
   if (min !== void 0 && max !== void 0 && min > max) {
     add(path, `${minName} (${min}) is greater than ${maxName} (${max})`);
@@ -1719,14 +1861,18 @@ var DEFAULT_API_PATH = "/api/cms";
 var DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
 var DEFAULT_TOKEN_EXPIRATION = 7 * 24 * 60 * 60;
 var resolved = /* @__PURE__ */ new WeakSet();
-async function resolveConfig(input) {
-  if (resolved.has(input)) return input;
+async function applyPlugins(input) {
   let config = input;
   const plugins = Array.isArray(config?.plugins) ? config.plugins : [];
   for (const plugin of plugins) {
     if (typeof plugin !== "function") break;
     config = await plugin(config);
   }
+  return config;
+}
+async function resolveConfig(input) {
+  if (resolved.has(input)) return input;
+  let config = await applyPlugins(input);
   if (typeof config === "object" && config !== null && Array.isArray(config.collections ?? [])) {
     config = withMedia(withUsers(config));
   }
@@ -1745,7 +1891,10 @@ async function resolveConfig(input) {
     admin: {
       path: config.admin?.path ?? DEFAULT_ADMIN_PATH,
       locale: config.admin?.locale ?? "en",
-      brand: config.admin?.brand ?? {}
+      brand: config.admin?.brand ?? {},
+      siteUrl: config.admin?.siteUrl ?? "",
+      menu: config.admin?.menu ?? [],
+      modules: config.admin?.modules ?? []
     },
     upload: {
       dir: config.upload?.dir ?? "uploads",
@@ -1768,7 +1917,8 @@ async function resolveConfig(input) {
       ...usesSchedule(config) ? [scheduledJobsCollection] : [],
       ...(config.webhooks?.length ?? 0) > 0 ? [webhookDeliveriesCollection] : []
     ],
-    globals: config.globals ?? []
+    globals: config.globals ?? [],
+    endpoints: config.endpoints ?? []
   };
   resolved.add(result);
   return result;
@@ -2276,20 +2426,20 @@ var VersionStore = class {
 
 // src/local-api.ts
 async function createEasyCMS(config, options = {}) {
-  const resolved2 = await resolveConfig(config);
+  const resolved3 = await resolveConfig(config);
   const logger = options.logger ?? consoleLogger;
   const cwd = options.cwd ?? process.cwd();
-  const storage = resolved2.upload.storage ?? localStorage({ dir: resolved2.upload.dir });
+  const storage = resolved3.upload.storage ?? localStorage({ dir: resolved3.upload.dir });
   await storage.init?.({ cwd });
-  const db = await resolved2.db.init({
-    config: resolved2,
+  const db = await resolved3.db.init({
+    config: resolved3,
     cwd,
     schema: options.schema ?? (process.env.NODE_ENV === "production" ? "verify" : "push"),
     logger,
     interactive: options.interactive ?? false
   });
-  const cms = new EasyCMS(resolved2, db, logger, storage);
-  const scheduling = [...resolved2.collections, ...resolved2.globals].some((c) => c.schedule) || (resolved2.webhooks?.length ?? 0) > 0;
+  const cms = new EasyCMS(resolved3, db, logger, storage, cwd);
+  const scheduling = [...resolved3.collections, ...resolved3.globals].some((c) => c.schedule) || (resolved3.webhooks?.length ?? 0) > 0;
   if (scheduling && options.scheduler !== false) cms.startScheduler();
   return cms;
 }
@@ -2309,13 +2459,16 @@ var EasyCMS = class {
   auth;
   /** Where uploaded files are stored. */
   storage;
+  /** Project root: relative paths in the config (e.g. `admin.modules`) start here. */
+  cwd;
   versions;
   webhooks;
-  constructor(config, db, logger = consoleLogger, storage = localStorage({ dir: config.upload.dir })) {
+  constructor(config, db, logger = consoleLogger, storage = localStorage({ dir: config.upload.dir }), cwd = process.cwd()) {
     this.config = config;
     this.db = db;
     this.logger = logger;
     this.storage = storage;
+    this.cwd = cwd;
     this.versions = new VersionStore(db);
     this.webhooks = new Webhooks(
       config.webhooks ?? [],
@@ -3631,7 +3784,56 @@ function asObject(data, name) {
   return data;
 }
 
+// src/rest/admin-modules.ts
+import { createHash as createHash2 } from "crypto";
+import { readFile as readFile2 } from "fs/promises";
+import { createRequire } from "module";
+import { join as join2 } from "path";
+function resolveAdminModule(specifier, cwd = process.cwd()) {
+  const bases = [join2(cwd, "package.json")];
+  const entry = process.argv[1];
+  if (entry && !specifier.startsWith(".")) bases.push(entry);
+  for (const base of bases) {
+    try {
+      return createRequire(base).resolve(specifier);
+    } catch {
+    }
+  }
+  return void 0;
+}
+var resolved2 = /* @__PURE__ */ new WeakMap();
+function files(cms) {
+  let result = resolved2.get(cms);
+  if (!result) {
+    result = cms.config.admin.modules.map((specifier) => {
+      const file = resolveAdminModule(specifier, cms.cwd);
+      if (!file) {
+        cms.logger.error(
+          `Admin module "${specifier}" not found: install the package, or check the path (relative to ${cms.cwd}). The admin loads without it.`
+        );
+      }
+      return file;
+    });
+    resolved2.set(cms, result);
+  }
+  return result;
+}
+function adminModuleUrls(cms) {
+  return files(cms).flatMap((file, i) => file ? [`/admin/modules/${i}.js`] : []);
+}
+async function readAdminModule(cms, index) {
+  const file = files(cms)[index];
+  if (!file) return void 0;
+  const body = await readFile2(file, "utf8").catch(() => void 0);
+  if (body === void 0) return void 0;
+  return { body, etag: `"${createHash2("sha1").update(body).digest("base64url")}"` };
+}
+
 // src/rest/admin-schema.ts
+function componentRef(component) {
+  if (typeof component === "string") return { tag: component };
+  return component.props ? { tag: component.tag, props: JSON.parse(JSON.stringify(component.props)) } : { tag: component.tag };
+}
 async function allowed(access, user) {
   return await evaluateAccess(access, { user }) !== false;
 }
@@ -3646,6 +3848,13 @@ async function serializeFields(fields, update, localized) {
     if (field.defaultValue !== void 0) f.defaultValue = field.defaultValue;
     if (!await update.allows(field)) f.readOnly = true;
     if (field.localized && localized) f.localized = true;
+    if (field.position === "sidebar") f.position = "sidebar";
+    if (field.admin?.component || field.admin?.after?.length) {
+      f.admin = {
+        ...field.admin.component ? { component: componentRef(field.admin.component) } : {},
+        ...field.admin.after?.length ? { after: field.admin.after.map(componentRef) } : {}
+      };
+    }
     switch (field.type) {
       case "text":
       case "textarea":
@@ -3718,6 +3927,9 @@ async function collection(config, user, localized) {
   if (config.labels) result.labels = config.labels;
   if (config.useAsTitle) result.useAsTitle = config.useAsTitle;
   if (config.icon) result.icon = config.icon;
+  if (config.admin?.sidebar?.length) result.sidebar = config.admin.sidebar.map(componentRef);
+  if (config.editIn === "drawer" && !result.drafts && !result.versions && !result.preview)
+    result.editIn = "drawer";
   return result;
 }
 async function global(config, user, localized) {
@@ -3739,6 +3951,7 @@ async function global(config, user, localized) {
   };
   if (config.label !== void 0) result.label = config.label;
   if (config.icon) result.icon = config.icon;
+  if (config.admin?.sidebar?.length) result.sidebar = config.admin.sidebar.map(componentRef);
   return result;
 }
 async function adminSchema(cms, user) {
@@ -3747,9 +3960,11 @@ async function adminSchema(cms, user) {
   const localized = localization !== null;
   return {
     locale: cms.config.admin.locale,
+    menu: [...cms.config.admin.menu],
     localization: localization ? { locales: [...localization.locales], defaultLocale: localization.defaultLocale } : null,
     collections: await Promise.all(collections.map((c) => collection(c, user, localized))),
-    globals: await Promise.all(cms.config.globals.map((g) => global(g, user, localized)))
+    globals: await Promise.all(cms.config.globals.map((g) => global(g, user, localized))),
+    modules: adminModuleUrls(cms)
   };
 }
 
@@ -3880,7 +4095,7 @@ function createRestHandler(instance, options = {}) {
       const ctx = { request, url, user, via: user ? via : null, token, headers };
       const method = request.method.toUpperCase();
       if (method !== "GET" && method !== "HEAD") checkCsrf(cms, ctx);
-      const result = await route(cms, ctx, method, segments, options);
+      const result = await customEndpoint(cms, ctx, method, segments) ?? await route(cms, ctx, method, segments, options);
       if (result.body instanceof Response) return result.body;
       return new Response(JSON.stringify(result.body), { status: result.status ?? 200, headers });
     } catch (error) {
@@ -3918,6 +4133,43 @@ function withHeaders(response, extra) {
     headers
   });
 }
+async function customEndpoint(cms, ctx, method, segments) {
+  let pathMatched = false;
+  const endpoints = [...cms.config.endpoints].sort((a, b) => fixedSegments(b) - fixedSegments(a));
+  for (const endpoint of endpoints) {
+    const params = matchPath(endpoint.path, segments);
+    if (!params) continue;
+    pathMatched = true;
+    const verb = endpoint.method.toUpperCase();
+    if (verb !== method && !(verb === "GET" && method === "HEAD")) continue;
+    const body = await endpoint.handler({
+      request: ctx.request,
+      url: ctx.url,
+      params,
+      user: ctx.user,
+      cms,
+      json: () => readJson(ctx.request)
+    });
+    return { body: body === void 0 ? null : body };
+  }
+  if (pathMatched) {
+    const allow = cms.config.endpoints.filter((e) => matchPath(e.path, segments)).map((e) => e.method.toUpperCase());
+    throw methodNotAllowed(ctx, [...new Set(allow)].join(", "));
+  }
+  return void 0;
+}
+var fixedSegments = (endpoint) => endpoint.path.split("/").filter((s) => s && !s.startsWith(":")).length;
+function matchPath(path, segments) {
+  const parts = path.split("/").filter(Boolean);
+  if (parts.length !== segments.length) return void 0;
+  const params = {};
+  for (const [i, part] of parts.entries()) {
+    const segment = segments[i];
+    if (part.startsWith(":")) params[part.slice(1)] = segment;
+    else if (part !== segment) return void 0;
+  }
+  return params;
+}
 async function route(cms, ctx, method, segments, options) {
   const [first, second, third] = segments;
   const access = { overrideAccess: false, user: ctx.user, ...parseLocale(ctx.url) };
@@ -3981,6 +4233,20 @@ async function route(cms, ctx, method, segments, options) {
     if (!ctx.user) throw new UnauthorizedError();
     if (second === "schema" && third === void 0)
       return { body: await adminSchema(cms, ctx.user) };
+    if (second === "modules" && third !== void 0 && segments.length === 3) {
+      const index = /^(\d+)\.js$/.exec(third)?.[1];
+      const file = index === void 0 ? void 0 : await readAdminModule(cms, Number(index));
+      if (!file) throw new HttpError("Not found", 404);
+      const headers = {
+        "content-type": "text/javascript; charset=utf-8",
+        "cache-control": "private, no-cache",
+        etag: file.etag,
+        "x-content-type-options": "nosniff"
+      };
+      if (ctx.request.headers.get("if-none-match") === file.etag)
+        return { body: new Response(null, { status: 304, headers }) };
+      return { body: new Response(file.body, { headers }) };
+    }
     if (second === "scheduled" && third === void 0)
       return { body: await cms.upcomingJobs({ user: ctx.user, overrideAccess: false }) };
     const [, , collection3, id2, extra] = segments;
@@ -4546,6 +4812,7 @@ export {
   WEBHOOK_EVENTS,
   anyone,
   applyDefaults,
+  applyPlugins,
   consoleLogger,
   createEasyCMS,
   createRestHandler,
@@ -4567,6 +4834,7 @@ export {
   parseId,
   populate,
   readCookie,
+  resolveAdminModule,
   resolveConfig,
   rowFields,
   silentLogger,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easy-cms/core",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Embedded, code-first headless CMS for Nuxt and Next.js",
   "license": "MIT",
   "type": "module",