@easy-cms/core 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -1275,10 +1275,17 @@ interface EndpointRequest {
 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`.
+     * not be a collection slug or one of `users`, `globals`, `admin`, `jobs`. With `root`, the
+     * path from the site's root, outside the API and the admin.
      */
     readonly path: string;
     readonly method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    /**
+     * Serve the path from the site's root instead of under `routes.api`, e.g. `/robots.txt`.
+     * Only the standalone server (`easy-cms serve`) serves these; a Nuxt or Next.js app owns its
+     * root, so plugins also offer a helper to use in the app's own route. Default false.
+     */
+    readonly root?: boolean;
     /**
      * Returns a `Response`, or a value that is sent as JSON. Throw an Easy CMS error
      * (`UnauthorizedError`, `ForbiddenError`, `ValidationError`, `NotFoundError`) for error responses.
@@ -1388,6 +1395,16 @@ declare const MEDIA = "media";
 /** Collections Easy CMS uses internally. Not exposed over REST or in the admin UI. */
 declare const INTERNAL_COLLECTIONS: ReadonlySet<string>;
 
+/**
+ * A string that is the same for configs with the same structure: collections, fields, options
+ * and every other plain value. Functions count only by where they are, not by their code, since
+ * bundlers rename variables differently each time they compile the same source.
+ *
+ * Frameworks may load the config module more than once (Next.js bundles it into each server
+ * layer), which gives different objects for the same config; this tells those apart from edits.
+ */
+declare function configSignature(config: Config): string;
+
 interface CopyProgress {
     readonly table: string;
     readonly rows: number;
@@ -1689,6 +1706,13 @@ interface RestHandlerOptions {
 type RestHandler = (request: Request) => Promise<Response>;
 /** Creates the REST API as a Web-standard `(Request) => Response` handler. */
 declare function createRestHandler<C extends Config>(instance: EasyCMS<C>, options?: RestHandlerOptions): RestHandler;
+/**
+ * Serves the endpoints marked `root: true` (e.g. `/robots.txt`), with the same auth, CSRF and
+ * errors as the REST API. Resolves to `undefined` when no root endpoint has the request's path,
+ * so a server can go on to its other routes. Nuxt and Next.js apps own their root and don't
+ * use it; the standalone server does.
+ */
+declare function createRootEndpointHandler<C extends Config>(instance: EasyCMS<C>, options?: Pick<RestHandlerOptions, 'getClientIp'>): (request: Request) => Promise<Response | undefined>;
 declare function readCookie(request: Request, name: string): string | undefined;
 
 /** Best-effort English singular: "categories" → "category". */
@@ -1705,4 +1729,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, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, 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 ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, 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 CopyProgress, type CopyResult, 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 DatabaseTransfer, 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, copyDatabase, createEasyCMS, createRestHandler, defineConfig, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };
+export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, 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 ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, 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 CopyProgress, type CopyResult, 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 DatabaseTransfer, 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, configSignature, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };

package/dist/index.js

@@ -915,6 +915,31 @@ function defineConfig(config) {
   return config;
 }
 
+// src/config-signature.ts
+function configSignature(config) {
+  const known = signatures.get(config);
+  if (known !== void 0) return known;
+  const seen = /* @__PURE__ */ new WeakSet();
+  const signature = JSON.stringify(config, (_key, value) => {
+    if (typeof value === "function") return "fn";
+    if (typeof value === "object" && value !== null) {
+      if (seen.has(value)) return "[circular]";
+      seen.add(value);
+      if (!Array.isArray(value)) {
+        const sorted = {};
+        for (const key2 of Object.keys(value).sort())
+          sorted[key2] = value[key2];
+        seen.add(sorted);
+        return sorted;
+      }
+    }
+    return value;
+  });
+  signatures.set(config, signature);
+  return signature;
+}
+var signatures = /* @__PURE__ */ new WeakMap();
+
 // src/copy.ts
 var BATCH = 200;
 async function copyDatabase(source, target, options = {}) {
@@ -1991,18 +2016,31 @@ function validateEndpoints(config, collectionSlugs, add) {
       add(path, "must be an object { path, method, handler }");
       return;
     }
-    const { path: route2, method, handler } = endpoint;
+    const { path: route2, method, handler, root } = endpoint;
+    if (root !== void 0 && typeof root !== "boolean")
+      add(`${path}.root`, "must be true or false");
     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(":")) {
+      const first = segments[0];
+      if (first.startsWith(":")) {
         add(`${path}.path`, "must start with a fixed segment, not a parameter");
-      } else if (RESERVED_ENDPOINT_ROOTS.has(root) || collectionSlugs.has(root)) {
+      } else if (root === true) {
+        const taken = [
+          config.routes?.api ?? "/api/cms",
+          `/${(config.admin?.path ?? "/admin").replace(/^\/+|\/+$/g, "")}`,
+          "/healthz"
+        ].map((p) => p.replace(/\/+$/, "")).find((p) => route2 === p || route2.startsWith(`${p}/`) || p.startsWith(`${route2}/`));
+        if (taken)
+          add(
+            `${path}.path`,
+            `"${route2}" is served by ${taken === "/healthz" ? "the standalone server" : `"${taken}"`}`
+          );
+      } else if (RESERVED_ENDPOINT_ROOTS.has(first) || collectionSlugs.has(first)) {
         add(
           `${path}.path`,
-          `"/${root}" is used by the built-in API`,
+          `"/${first}" is used by the built-in API`,
           'start the path with your plugin or feature name, e.g. "/seo/generate"'
         );
       }
@@ -2016,7 +2054,7 @@ function validateEndpoints(config, collectionSlugs, add) {
     }
     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, ":")}`;
+      const key2 = `${root === true ? "root " : ""}${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);
     }
@@ -4333,6 +4371,42 @@ function createRestHandler(instance, options = {}) {
   const cms = instance;
   const basePath = (options.basePath ?? cms.config.routes.api).replace(/\/+$/, "");
   const production = process.env.NODE_ENV === "production";
+  return withCors(cms, (request) => {
+    const url = new URL(request.url);
+    const inside = url.pathname === basePath || url.pathname.startsWith(`${basePath}/`);
+    return respond(
+      cms,
+      request,
+      url,
+      inside ? url.pathname.slice(basePath.length) : null,
+      false,
+      options,
+      production
+    );
+  });
+}
+function createRootEndpointHandler(instance, options = {}) {
+  const cms = instance;
+  const production = process.env.NODE_ENV === "production";
+  const handler = withCors(cms, (request) => {
+    const url = new URL(request.url);
+    return respond(cms, request, url, url.pathname, true, options, production);
+  });
+  return async (request) => {
+    let segments;
+    try {
+      segments = pathSegments(new URL(request.url).pathname);
+    } catch {
+      return void 0;
+    }
+    const matched = cms.config.endpoints.some((e) => e.root && matchPath(e.path, segments));
+    return matched ? handler(request) : void 0;
+  };
+}
+function pathSegments(path) {
+  return path.split("/").filter(Boolean).map((s) => decodeURIComponent(s));
+}
+function withCors(cms, handle) {
   return async (request) => {
     const cors = corsHeaders(cms, request);
     if (request.method.toUpperCase() === "OPTIONS") {
@@ -4340,31 +4414,29 @@ function createRestHandler(instance, options = {}) {
     }
     return withHeaders(await handle(request), cors);
   };
-  async function handle(request) {
-    const headers = new Headers({
-      "content-type": "application/json; charset=utf-8",
-      "cache-control": "no-store",
-      "x-content-type-options": "nosniff"
-    });
-    try {
-      const url = new URL(request.url);
-      if (url.pathname !== basePath && !url.pathname.startsWith(`${basePath}/`)) {
-        throw new HttpError("Not found", 404);
-      }
-      const segments = url.pathname.slice(basePath.length).split("/").filter(Boolean).map((s) => decodeURIComponent(s));
-      const { token, via } = readToken(request);
-      const user = token ? await cms.auth.verify(token) : null;
-      if (!user && via === "bearer" && token?.startsWith("ecms_"))
-        throw new UnauthorizedError("Invalid or expired API key");
-      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 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) {
-      return errorResponse(cms, error, headers, production);
-    }
+}
+async function respond(cms, request, url, path, root, options, production) {
+  const headers = new Headers({
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+    "x-content-type-options": "nosniff"
+  });
+  try {
+    if (path === null) throw new HttpError("Not found", 404);
+    const segments = pathSegments(path);
+    const { token, via } = readToken(request);
+    const user = token ? await cms.auth.verify(token) : null;
+    if (!user && via === "bearer" && token?.startsWith("ecms_"))
+      throw new UnauthorizedError("Invalid or expired API key");
+    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 = root ? await customEndpoint(cms, ctx, method, segments, true) : await customEndpoint(cms, ctx, method, segments, false) ?? await route(cms, ctx, method, segments, options);
+    if (!result) throw new HttpError("Not found", 404);
+    if (result.body instanceof Response) return result.body;
+    return new Response(JSON.stringify(result.body), { status: result.status ?? 200, headers });
+  } catch (error) {
+    return errorResponse(cms, error, headers, production);
   }
 }
 var CORS_METHODS = "GET, HEAD, POST, PATCH, PUT, DELETE";
@@ -4397,9 +4469,10 @@ function withHeaders(response, extra) {
     headers
   });
 }
-async function customEndpoint(cms, ctx, method, segments) {
+async function customEndpoint(cms, ctx, method, segments, root) {
   let pathMatched = false;
-  const endpoints = [...cms.config.endpoints].sort((a, b) => fixedSegments(b) - fixedSegments(a));
+  const own = cms.config.endpoints.filter((e) => !!e.root === root);
+  const endpoints = [...own].sort((a, b) => fixedSegments(b) - fixedSegments(a));
   for (const endpoint of endpoints) {
     const params = matchPath(endpoint.path, segments);
     if (!params) continue;
@@ -4417,7 +4490,7 @@ async function customEndpoint(cms, ctx, method, segments) {
     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());
+    const allow = own.filter((e) => matchPath(e.path, segments)).map((e) => e.method.toUpperCase());
     throw methodNotAllowed(ctx, [...new Set(allow)].join(", "));
   }
   return void 0;
@@ -5092,10 +5165,12 @@ export {
   anyone,
   applyDefaults,
   applyPlugins,
+  configSignature,
   consoleLogger,
   copyDatabase,
   createEasyCMS,
   createRestHandler,
+  createRootEndpointHandler,
   defineConfig,
   fillMissing,
   findConfigFile,

package/package.json

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