@easy-cms/core 0.28.0 → 0.29.0

package/dist/index.d.ts

@@ -238,6 +238,8 @@ interface EmailMessage {
  * development. Throw to report a failure: the message is retried later.
  */
 interface EmailAdapter {
+    /** What sends the email, e.g. `smtp`; shown to admins on the dashboard (System). */
+    readonly name?: string;
     /** The sender when a message has none, e.g. `Easy CMS <no-reply@example.com>`. */
     readonly from?: string | undefined;
     send(message: EmailMessage & {
@@ -1726,8 +1728,17 @@ interface Endpoint {
      */
     readonly handler: (request: EndpointRequest) => MaybePromise<unknown>;
 }
+/** A plugin's package and version, listed for admins on the dashboard (System). */
+interface PluginInfo {
+    /** Usually the package name, e.g. `@acme/easy-cms-plugin-stats`. */
+    readonly name: string;
+    readonly version?: string;
+}
 /** Receives the config and returns a modified copy. Runs before validation. */
-type Plugin = (config: Config) => MaybePromise<Config>;
+type Plugin = ((config: Config) => MaybePromise<Config>) & {
+    /** Set by `definePlugin(plugin, info)`. */
+    readonly info?: PluginInfo;
+};
 /** Holds a plugin's `PluginTypes` at the type level only: nothing is stored at runtime. */
 declare const PLUGIN_TYPES: unique symbol;
 /**
@@ -1749,17 +1760,18 @@ type TypedPlugin<T extends PluginTypes> = Plugin & {
     readonly [PLUGIN_TYPES]?: T;
 };
 /**
- * Returns the plugin unchanged, with what it adds as types, so `cms.find()` and
- * `CollectionDocument` know the plugin's fields:
+ * Returns the plugin with what it adds as types, so `cms.find()` and `CollectionDocument` know
+ * the plugin's fields; `info` (its name and version) is listed for admins on the dashboard:
  *
  * ```ts
  * export const colorPlugin = (options: { collections: readonly string[] }) =>
  *   definePlugin<{ fields: { posts: readonly [{ readonly name: 'color'; readonly type: 'text' }] } }>(
  *     (config) => ({ ...config, collections: … }),
+ *     { name: '@acme/easy-cms-plugin-color', version: '1.2.0' },
  *   )
  * ```
  */
-declare function definePlugin<const T extends PluginTypes = Record<never, never>>(plugin: Plugin): TypedPlugin<T>;
+declare function definePlugin<const T extends PluginTypes = Record<never, never>>(plugin: Plugin, info?: PluginInfo): TypedPlugin<T>;
 interface Config {
     /** Signs sessions. At least 32 characters; read it from `process.env.EASY_CMS_SECRET`. */
     readonly secret: string;
@@ -1831,6 +1843,8 @@ interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes'
     readonly endpoints: readonly Endpoint[];
     readonly commands: readonly CliCommand[];
     readonly fieldTypes: readonly FieldTypeDefinition[];
+    /** The config's plugins in order, with their `info` where they give one. */
+    readonly installedPlugins: readonly Partial<PluginInfo>[];
 }
 /**
  * Declares the Easy CMS config. Returns it unchanged, keeping literal types
@@ -2162,6 +2176,54 @@ interface AdminSchema {
     dashboard: AdminWidgetRef[];
 }
 
+/** Something an admin should look at, shown on the dashboard with a link to how to fix it. */
+type AdminAttention = 
+/** Webhook deliveries that failed for good in the last 7 days; `url`: the one failing most. */
+{
+    id: 'webhooks';
+    count: number;
+    url: string;
+}
+/** Emails waiting over an hour, or that failed for good in the last 7 days. */
+ | {
+    id: 'emails';
+    count: number;
+}
+/** Scheduled publishing more than 10 minutes late: nothing runs `jobs/run`. */
+ | {
+    id: 'scheduled';
+    count: number;
+}
+/** No `email` in the config: no forgotten-password links, invitations or form emails. */
+ | {
+    id: 'no-email';
+}
+/** In production without `serverURL`: links in emails can't be made. */
+ | {
+    id: 'no-server-url';
+};
+/** What the dashboard shows admins (`GET <api>/admin/status`). */
+interface AdminStatus {
+    system: {
+        /** `@easy-cms/core`'s version. */
+        version: string;
+        /** The database adapter, e.g. `sqlite` or `postgres`. */
+        database: string;
+        /** Where uploads are stored, e.g. `local` or `s3`. */
+        storage: string;
+        /** The email adapter's name, `custom` when it has none, or `null` without email. */
+        email: string | null;
+        /** The config's plugins, with their name and version when they give them. */
+        plugins: {
+            name?: string;
+            version?: string;
+        }[];
+        /** Field types from packages (`fieldTypes`). */
+        fieldTypes: string[];
+    };
+    attention: AdminAttention[];
+}
+
 declare const SESSION_COOKIE = "ecms-session";
 declare const CSRF_COOKIE = "ecms-csrf";
 declare const CSRF_HEADER = "x-csrf-token";
@@ -2197,4 +2259,7 @@ 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 AdminPage, type AdminPageRef, type AdminSchema, type AdminViewAccess, type AdminWidgetRef, 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 CliCommand, type CollectionAccess, type CollectionAdmin, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionListAdmin, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, type CustomField, type CustomFieldTypes, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_PASSWORD_EMAILS, DEFAULT_TOKEN_EXPIRATION, type DashboardWidget, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DepthOptions, type DocumentOf, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailField, type EmailMessage, type Endpoint, type EndpointRequest, FIELD_TYPES, FIELD_TYPE_BASES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldType, type FieldTypeBase, type FieldTypeDefinition, type FieldTypeValidateContext, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FilterOptions, type FilterOptionsArgs, 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, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, PayloadTooLargeError, type Plugin, type PluginTypes, 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 SlugOf, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, type UploadFromURLConfig, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, configSignature, consoleEmail, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, defineFieldType, definePlugin, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };
+/** The version of `@easy-cms/core`, set when the package is built. */
+declare const VERSION: string;
+
+export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, type Access, type AccessArgs, type AccessOptions, type AdminAttention, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminPage, type AdminPageRef, type AdminSchema, type AdminStatus, type AdminViewAccess, type AdminWidgetRef, 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 CliCommand, type CollectionAccess, type CollectionAdmin, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionListAdmin, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, type CustomField, type CustomFieldTypes, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_PASSWORD_EMAILS, DEFAULT_TOKEN_EXPIRATION, type DashboardWidget, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DepthOptions, type DocumentOf, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailField, type EmailMessage, type Endpoint, type EndpointRequest, FIELD_TYPES, FIELD_TYPE_BASES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldType, type FieldTypeBase, type FieldTypeDefinition, type FieldTypeValidateContext, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FilterOptions, type FilterOptionsArgs, 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, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, PayloadTooLargeError, type Plugin, type PluginInfo, type PluginTypes, 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 SlugOf, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, type UploadFromURLConfig, VERSION, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, configSignature, consoleEmail, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, defineFieldType, definePlugin, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };

package/dist/index.js

@@ -1142,7 +1142,8 @@ var ADMIN_ICONS = [
   "chart-column",
   "chart-line"
 ];
-function definePlugin(plugin) {
+function definePlugin(plugin, info) {
+  if (info) Object.defineProperty(plugin, "info", { value: info, configurable: true });
   return plugin;
 }
 function defineConfig(config) {
@@ -1304,13 +1305,13 @@ function generateSlugs(fields, data, localization = null) {
 function mergeForUpdate(fields, existing, patch) {
   const result = {};
   for (const field of fields) {
-    const has = Object.hasOwn(patch, field.name);
+    const has2 = Object.hasOwn(patch, field.name);
     const next = patch[field.name];
     const prev = existing[field.name];
-    if (field.type === "group" && has && isPlainObject(next)) {
+    if (field.type === "group" && has2 && isPlainObject(next)) {
       result[field.name] = mergeForUpdate(field.fields, isPlainObject(prev) ? prev : {}, next);
     } else {
-      result[field.name] = has ? next : prev;
+      result[field.name] = has2 ? next : prev;
     }
   }
   return result;
@@ -1541,6 +1542,7 @@ function normalizeSelect(field, raw, fail) {
 function consoleEmail(options = {}) {
   const sent = [];
   const adapter = {
+    name: "console",
     from: options.from ?? "Easy CMS <no-reply@localhost>",
     sent,
     async send(message) {
@@ -2840,7 +2842,7 @@ async function resolveConfig(input) {
   config = applied.config;
   const issues = [...applied.issues, ...validateConfig(config)];
   if (issues.length > 0) throw new ConfigError(issues);
-  const { plugins: _plugins, ...rest } = config;
+  const { plugins, ...rest } = config;
   const result = {
     ...rest,
     cors: config.cors ?? [],
@@ -2890,6 +2892,9 @@ async function resolveConfig(input) {
     globals: config.globals ?? [],
     endpoints: config.endpoints ?? [],
     commands: config.commands ?? [],
+    installedPlugins: (plugins ?? []).map(
+      (plugin) => typeof plugin === "function" && plugin.info ? { ...plugin.info } : {}
+    ),
     fieldTypes: config.fieldTypes ?? []
   };
   resolved.add(result);
@@ -5385,6 +5390,80 @@ async function widgets(cms, user) {
   return out;
 }
 
+// src/version.ts
+var VERSION = true ? "0.29.0" : "0.0.0-dev";
+
+// src/rest/admin-status.ts
+var DAY = 864e5;
+var has = (cms, slug) => cms.config.collections.some((c) => c.slug === slug);
+async function adminStatus(cms) {
+  const config = cms.config;
+  const attention = [];
+  const now = Date.now();
+  const weekAgo = new Date(now - 7 * DAY).toISOString();
+  if (has(cms, WEBHOOK_DELIVERIES)) {
+    const failed = await cms.db.find({
+      collection: WEBHOOK_DELIVERIES,
+      where: { and: [{ state: { equals: "failed" } }, { updatedAt: { gte: weekAgo } }] },
+      sort: ["-updatedAt"],
+      limit: 200,
+      page: 1
+    });
+    if (failed.totalDocs > 0) {
+      const byUrl = /* @__PURE__ */ new Map();
+      for (const row of failed.docs) {
+        const url2 = String(row.url ?? "");
+        byUrl.set(url2, (byUrl.get(url2) ?? 0) + 1);
+      }
+      const [url] = [...byUrl.entries()].sort((a, b) => b[1] - a[1])[0] ?? [""];
+      attention.push({ id: "webhooks", count: failed.totalDocs, url });
+    }
+  }
+  if (has(cms, EMAIL_DELIVERIES)) {
+    const count = await cms.db.count({
+      collection: EMAIL_DELIVERIES,
+      where: {
+        or: [
+          { and: [{ state: { equals: "failed" } }, { updatedAt: { gte: weekAgo } }] },
+          {
+            and: [
+              { state: { equals: "pending" } },
+              { createdAt: { lte: new Date(now - 60 * 6e4).toISOString() } }
+            ]
+          }
+        ]
+      }
+    });
+    if (count > 0) attention.push({ id: "emails", count });
+  }
+  if (has(cms, SCHEDULED_JOBS)) {
+    const count = await cms.db.count({
+      collection: SCHEDULED_JOBS,
+      where: {
+        and: [
+          { state: { equals: "pending" } },
+          { runAt: { lte: new Date(now - 10 * 6e4).toISOString() } }
+        ]
+      }
+    });
+    if (count > 0) attention.push({ id: "scheduled", count });
+  }
+  if (!config.email) attention.push({ id: "no-email" });
+  if (!config.serverURL && process.env.NODE_ENV === "production")
+    attention.push({ id: "no-server-url" });
+  return {
+    system: {
+      version: VERSION,
+      database: config.db.name,
+      storage: config.upload.storage?.name ?? "local",
+      email: config.email ? config.email.name ?? "custom" : null,
+      plugins: config.installedPlugins.map((p) => ({ ...p })),
+      fieldTypes: config.fieldTypes.map((t) => t.name)
+    },
+    attention
+  };
+}
+
 // src/rest/filter-options.ts
 function fieldAt(fields, path) {
   let current = fields;
@@ -5771,6 +5850,10 @@ async function route(cms, ctx, method, segments, options) {
         return { body: new Response(null, { status: 304, headers }) };
       return { body: new Response(file.body, { headers }) };
     }
+    if (second === "status" && third === void 0) {
+      if (ctx.user.role !== "admin" || ctx.user.apiKey) throw new ForbiddenError();
+      return { body: await adminStatus(cms) };
+    }
     if (second === "scheduled" && third === void 0)
       return { body: await cms.upcomingJobs({ user: ctx.user, overrideAccess: false }) };
     const [, , collection3, id2, extra] = segments;
@@ -6382,6 +6465,7 @@ export {
   SchemaError,
   TooManyRequestsError,
   UnauthorizedError,
+  VERSION,
   ValidationError,
   WEBHOOK_EVENTS,
   anyone,

package/package.json

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