@easy-cms/core 0.18.0 → 0.20.0

package/dist/index.d.ts

@@ -196,6 +196,40 @@ interface BundleHints {
     readonly traceInclude: readonly string[];
 }
 
+/** An email to send. Addresses may be `name <address>`. */
+interface EmailMessage {
+    readonly to: string | readonly string[];
+    readonly cc?: string | readonly string[];
+    readonly bcc?: string | readonly string[];
+    /** Default: the adapter's `from`. */
+    readonly from?: string;
+    readonly replyTo?: string;
+    readonly subject: string;
+    readonly html?: string;
+    readonly text?: string;
+}
+/**
+ * Sends email for Easy CMS and its plugins (form notifications, and more later). Set one in
+ * the config as `email`, e.g. `smtp()` from `@easy-cms/email-smtp`, or `consoleEmail()` in
+ * development. Throw to report a failure: the message is retried later.
+ */
+interface EmailAdapter {
+    /** The sender when a message has none, e.g. `Easy CMS <no-reply@example.com>`. */
+    readonly from?: string | undefined;
+    send(message: EmailMessage & {
+        readonly from: string;
+    }): Promise<void>;
+}
+/** Prints emails to the log instead of sending them: for development and tests. */
+declare function consoleEmail(options?: {
+    from?: string;
+    log?: (text: string) => void;
+}): EmailAdapter & {
+    readonly sent: (EmailMessage & {
+        from: string;
+    })[];
+};
+
 /** A label shown in the admin UI. Either one string or one string per admin locale. */
 type Label = string | {
     readonly [locale: string]: string;
@@ -779,6 +813,7 @@ declare class EasyCMS<C extends Config = Config> {
     readonly cwd: string;
     private readonly versions;
     private readonly webhooks;
+    private readonly mailer;
     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>;
@@ -895,6 +930,16 @@ declare class EasyCMS<C extends Config = Config> {
      * returns, which may otherwise stop them.
      */
     flushWebhooks(): Promise<void>;
+    /**
+     * Sends an email with the config's `email` adapter, e.g. from a hook or plugin. Resolves once
+     * the email is queued; it is sent in the background and retried from the queue if sending
+     * fails. Without `email` in the config, the email is skipped with a warning.
+     */
+    sendEmail(message: EmailMessage): Promise<void>;
+    /** Waits for emails being sent, e.g. before a serverless function returns. */
+    flushEmails(): Promise<void>;
+    /** Emails queued until sent, stored in `email-deliveries`. */
+    private emailQueue;
     destroy(): Promise<void>;
     private schedulerTimer;
     private running;
@@ -911,6 +956,10 @@ declare class EasyCMS<C extends Config = Config> {
             sent: number;
             failed: number;
         };
+        emails: {
+            sent: number;
+            failed: number;
+        };
     }>;
     /**
      * Tries webhook deliveries that are due for another attempt. Deliveries are kept in the
@@ -1124,6 +1173,13 @@ interface ContainerAdmin {
     /** Panels in the edit page's side column, below publishing (components from admin modules). */
     readonly sidebar?: readonly AdminComponent[];
 }
+interface CollectionAdmin extends ContainerAdmin {
+    /**
+     * `settings` lists the collection under Settings in the admin menu (with Users and API keys)
+     * instead of with the content, e.g. for redirects or forms settings.
+     */
+    readonly group?: 'settings';
+}
 interface CollectionConfig {
     /** URL and table name. Lowercase letters, digits, `-` and `_`. */
     readonly slug: string;
@@ -1156,8 +1212,8 @@ interface CollectionConfig {
     readonly preview?: PreviewURL;
     readonly access?: CollectionAccess;
     readonly hooks?: CollectionHooks;
-    /** Custom admin components. */
-    readonly admin?: ContainerAdmin;
+    /** Custom admin components, and where the collection is in the menu. */
+    readonly admin?: CollectionAdmin;
 }
 interface GlobalConfig {
     readonly slug: string;
@@ -1263,6 +1319,8 @@ interface EndpointRequest {
     readonly params: Readonly<Record<string, string>>;
     /** The logged-in user (session cookie or Bearer token), or `null`. */
     readonly user: AuthUser | null;
+    /** The client's IP address, when the adapter knows it (e.g. to rate-limit a public form). */
+    readonly ip: string | undefined;
     /** 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). */
@@ -1336,6 +1394,12 @@ interface Config {
      * under Settings. A key acts as its owner, limited to the collections and operations it lists.
      */
     readonly apiKeys?: boolean;
+    /**
+     * Sends email for plugins such as the form builder, e.g. `smtp()` from
+     * `@easy-cms/email-smtp`, or `consoleEmail()` in development. Emails are queued in the
+     * database and retried until sent.
+     */
+    readonly email?: EmailAdapter;
     readonly plugins?: readonly Plugin[];
 }
 /** The config after plugins ran, validation passed and defaults were applied. */
@@ -1654,6 +1718,8 @@ interface AdminCollection {
     fields: AdminField[];
     /** Panels from admin modules in the edit page's side column. */
     sidebar?: AdminComponentRef[];
+    /** Listed under Settings in the menu (users, API keys, `admin.group: 'settings'`). */
+    group?: 'settings';
     permissions: {
         read: boolean;
         create: boolean;
@@ -1729,4 +1795,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, 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 };
+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 CollectionAdmin, 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 EmailAdapter, type EmailField, type EmailMessage, 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, consoleEmail, 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

@@ -316,12 +316,14 @@ var LOGIN_ATTEMPTS = "login-attempts";
 var VERSIONS = "document-versions";
 var SCHEDULED_JOBS = "scheduled-jobs";
 var WEBHOOK_DELIVERIES = "webhook-deliveries";
+var EMAIL_DELIVERIES = "email-deliveries";
 var INTERNAL_COLLECTIONS = /* @__PURE__ */ new Set([
   SESSIONS,
   LOGIN_ATTEMPTS,
   VERSIONS,
   SCHEDULED_JOBS,
-  WEBHOOK_DELIVERIES
+  WEBHOOK_DELIVERIES,
+  EMAIL_DELIVERIES
 ]);
 var DEFAULT_ROLES = ["admin", "editor"];
 var adminOrSelf = ({ user }) => {
@@ -536,6 +538,19 @@ var webhookDeliveriesCollection = {
     { name: "error", type: "text" }
   ]
 };
+var emailDeliveriesCollection = {
+  slug: EMAIL_DELIVERIES,
+  access: { read: nobody, create: nobody, update: nobody, delete: nobody },
+  fields: [
+    // The message as JSON.
+    { name: "message", type: "textarea", required: true },
+    { name: "attempts", type: "number", required: true },
+    { name: "nextAttemptAt", type: "text", required: true, index: true },
+    // pending | failed
+    { name: "state", type: "text", required: true, index: true },
+    { name: "error", type: "text" }
+  ]
+};
 
 // src/auth/password.ts
 import { randomBytes as randomBytes2, scrypt, timingSafeEqual as timingSafeEqual2 } from "crypto";
@@ -1290,6 +1305,140 @@ function normalizeSelect(field, raw, fail) {
   return field.hasMany ? [...new Set(values)] : values[0];
 }
 
+// src/email.ts
+function consoleEmail(options = {}) {
+  const sent = [];
+  const adapter = {
+    from: options.from ?? "Easy CMS <no-reply@localhost>",
+    sent,
+    async send(message) {
+      sent.push(message);
+      const list = (value) => value === void 0 ? void 0 : typeof value === "string" ? value : value.join(", ");
+      const lines = [
+        `Email to ${list(message.to)}${message.cc ? `, cc ${list(message.cc)}` : ""}`,
+        `From: ${message.from}${message.replyTo ? ` (reply to ${message.replyTo})` : ""}`,
+        `Subject: ${message.subject}`,
+        "",
+        message.text ?? message.html ?? ""
+      ];
+      (options.log ?? console.log)(lines.join("\n"));
+    }
+  };
+  return adapter;
+}
+var QUEUE_DELAYS = [6e4, 5 * 6e4, 30 * 6e4, 2 * 36e5, 6 * 36e5, 12 * 36e5];
+var CLAIM = 5 * 6e4;
+var later = (from, ms) => new Date(from.getTime() + ms).toISOString();
+var Mailer = class {
+  constructor(adapter, logger, queue) {
+    this.adapter = adapter;
+    this.logger = logger;
+    this.queue = queue;
+  }
+  adapter;
+  logger;
+  queue;
+  pending = /* @__PURE__ */ new Set();
+  get configured() {
+    return this.adapter !== void 0;
+  }
+  /**
+   * Queues an email and sends it without waiting. Resolves once it is saved; `flush()` waits
+   * for the sending too. Without an `email` adapter in the config, the email is skipped with a
+   * warning.
+   */
+  async send(message) {
+    if (!this.adapter) {
+      this.logger.warn(
+        `Email "${message.subject}" not sent: set \`email\` in the config (e.g. consoleEmail() in development)`
+      );
+      return;
+    }
+    const body = JSON.stringify(message);
+    let id;
+    try {
+      id = await this.queue?.add({
+        message: body,
+        attempts: 0,
+        nextAttemptAt: later(/* @__PURE__ */ new Date(), CLAIM),
+        state: "pending",
+        error: null
+      });
+    } catch (error) {
+      this.logger.error(`Could not save email: ${error.message}`);
+    }
+    this.track(this.deliver(message, body, id));
+  }
+  /** Waits for emails being sent, e.g. before a serverless function returns. */
+  async flush() {
+    while (this.pending.size > 0) await Promise.allSettled([...this.pending]);
+  }
+  /** Sends queued emails that are due for another attempt. Runs with scheduled jobs. */
+  async retry(now = /* @__PURE__ */ new Date()) {
+    if (!this.queue || !this.adapter) return { sent: 0, failed: 0 };
+    let sent = 0;
+    let failed = 0;
+    for (const { id, ...queued } of await this.queue.due(now, 50)) {
+      const attempts = queued.attempts + 1;
+      await this.queue.update(id, { ...queued, attempts, nextAttemptAt: later(now, CLAIM) });
+      const error = await this.attempt(JSON.parse(queued.message));
+      if (!error) {
+        await this.queue.remove(id);
+        sent++;
+        continue;
+      }
+      const delay = QUEUE_DELAYS[attempts - 1];
+      if (delay === void 0) {
+        failed++;
+        this.logger.error(`Email gave up after ${attempts} attempts: ${error}`);
+      }
+      await this.queue.update(id, {
+        ...queued,
+        attempts,
+        nextAttemptAt: later(now, delay ?? 0),
+        state: delay === void 0 ? "failed" : "pending",
+        error
+      });
+    }
+    return { sent, failed };
+  }
+  track(delivery) {
+    const tracked = delivery.catch((error) => this.logger.error(`Email queue failed: ${error.message}`)).finally(() => this.pending.delete(tracked));
+    this.pending.add(tracked);
+  }
+  async deliver(message, body, id) {
+    const error = await this.attempt(message);
+    if (!error) {
+      if (id !== void 0) await this.queue?.remove(id);
+      return;
+    }
+    if (id === void 0 || !this.queue) {
+      this.logger.error(`Email "${message.subject}" failed: ${error}`);
+      return;
+    }
+    this.logger.warn(`Email "${message.subject}" failed, retrying later: ${error}`);
+    await this.queue.update(id, {
+      message: body,
+      attempts: 1,
+      nextAttemptAt: later(/* @__PURE__ */ new Date(), QUEUE_DELAYS[0]),
+      state: "pending",
+      error
+    });
+  }
+  /** `undefined` when sent, else the error. */
+  async attempt(message) {
+    const adapter = this.adapter;
+    const from = message.from ?? adapter.from;
+    if (!from) return "no sender: set `from` on the message or the email adapter";
+    try {
+      await adapter.send({ ...message, from });
+      return void 0;
+    } catch (error) {
+      return error.message || String(error);
+    }
+  }
+};
+
 // src/load-config.ts
 import { existsSync } from "fs";
 import { resolve } from "path";
@@ -1306,8 +1455,8 @@ var WEBHOOK_EVENTS = [
   "draft"
 ];
 var RETRY_DELAYS = [1e3, 5e3];
-var QUEUE_DELAYS = [6e4, 5 * 6e4, 30 * 6e4, 2 * 36e5, 6 * 36e5, 12 * 36e5];
-var CLAIM = 5 * 6e4;
+var QUEUE_DELAYS2 = [6e4, 5 * 6e4, 30 * 6e4, 2 * 36e5, 6 * 36e5, 12 * 36e5];
+var CLAIM2 = 5 * 6e4;
 var TIMEOUT = 1e4;
 var Webhooks = class {
   constructor(hooks, logger, queue, fetcher = (...args) => fetch(...args), retryDelays = RETRY_DELAYS) {
@@ -1353,19 +1502,19 @@ var Webhooks = class {
         continue;
       }
       const attempts = queued.attempts + 1;
-      await this.queue.update(id, { ...queued, attempts, nextAttemptAt: later(now, CLAIM) });
+      await this.queue.update(id, { ...queued, attempts, nextAttemptAt: later2(now, CLAIM2) });
       const result = await this.attempt(hook, queued.event, queued.body, queued.delivery);
       if (result.ok) {
         await this.queue.remove(id);
         sent++;
         continue;
       }
-      const delay = QUEUE_DELAYS[Math.max(0, attempts - this.retryDelays.length - 1)];
+      const delay = QUEUE_DELAYS2[Math.max(0, attempts - this.retryDelays.length - 1)];
       if (delay === void 0) failed++;
       await this.queue.update(id, {
         ...queued,
         attempts,
-        nextAttemptAt: later(now, delay ?? 0),
+        nextAttemptAt: later2(now, delay ?? 0),
         state: delay === void 0 ? "failed" : "pending",
         error: result.error
       });
@@ -1392,7 +1541,7 @@ var Webhooks = class {
       error
     });
     const { queue } = this;
-    const saved = queue ? this.saving.then(() => queue.add(entry(0, later(/* @__PURE__ */ new Date(), CLAIM), null))) : Promise.resolve(void 0);
+    const saved = queue ? this.saving.then(() => queue.add(entry(0, later2(/* @__PURE__ */ new Date(), CLAIM2), null))) : Promise.resolve(void 0);
     this.saving = saved.catch(() => {
     });
     let queued;
@@ -1411,7 +1560,7 @@ var Webhooks = class {
       if (delay === void 0) {
         if (queued === void 0 || !this.queue)
           return this.giveUp(hook, event, result.error, attempt + 1);
-        const next = later(/* @__PURE__ */ new Date(), QUEUE_DELAYS[0]);
+        const next = later2(/* @__PURE__ */ new Date(), QUEUE_DELAYS2[0]);
         await this.queue.update(queued, entry(attempt + 1, next, result.error));
         this.logger.warn(
           `Webhook ${hook.url} failed for ${event} (${result.error}); will retry later`
@@ -1456,7 +1605,7 @@ var Webhooks = class {
     );
   }
 };
-var later = (from, ms) => new Date(from.getTime() + ms).toISOString();
+var later2 = (from, ms) => new Date(from.getTime() + ms).toISOString();
 function matches(hook, payload) {
   if (hook.events && !hook.events.includes(payload.event)) return false;
   if (payload.collection !== void 0)
@@ -1727,6 +1876,13 @@ function validateLocalization(config, add) {
   for (const [i, g] of (config.globals ?? []).entries()) walk(g?.fields, `globals[${i}].fields`);
 }
 function validateWebhooks(config, add) {
+  const email = config.email;
+  if (email !== void 0 && (typeof email !== "object" || email === null || typeof email.send !== "function"))
+    add(
+      "email",
+      "must be an email adapter with a send() function",
+      "e.g. email: consoleEmail() or smtp({ \u2026 }) from @easy-cms/email-smtp"
+    );
   const hooks = config.webhooks;
   if (hooks === void 0) return;
   if (!Array.isArray(hooks)) {
@@ -1838,6 +1994,9 @@ function validateContainer(container, path, collectionSlugs, add) {
     } else {
       const sidebar = admin.sidebar;
       if (sidebar !== void 0) validateComponents(sidebar, `${path}.admin.sidebar`, add);
+      const group = admin.group;
+      if (group !== void 0 && group !== "settings")
+        add(`${path}.admin.group`, `must be 'settings' (got ${JSON.stringify(group)})`);
     }
   }
   const reserved = new Set(SYSTEM_FIELD_NAMES);
@@ -2160,7 +2319,8 @@ async function resolveConfig(input) {
       ...usesVersions(config) ? [versionsCollection] : [],
       ...usesSchedule(config) ? [scheduledJobsCollection] : [],
       ...(config.webhooks?.length ?? 0) > 0 ? [webhookDeliveriesCollection] : [],
-      ...config.apiKeys ? [apiKeysCollection] : []
+      ...config.apiKeys ? [apiKeysCollection] : [],
+      ...config.email ? [emailDeliveriesCollection] : []
     ],
     globals: config.globals ?? [],
     endpoints: config.endpoints ?? []
@@ -2684,7 +2844,7 @@ async function createEasyCMS(config, options = {}) {
     interactive: options.interactive ?? false
   });
   const cms = new EasyCMS(resolved3, db, logger, storage, cwd);
-  const scheduling = [...resolved3.collections, ...resolved3.globals].some((c) => c.schedule) || (resolved3.webhooks?.length ?? 0) > 0;
+  const scheduling = [...resolved3.collections, ...resolved3.globals].some((c) => c.schedule) || (resolved3.webhooks?.length ?? 0) > 0 || resolved3.email !== void 0;
   if (scheduling && options.scheduler !== false) cms.startScheduler();
   return cms;
 }
@@ -2708,6 +2868,7 @@ var EasyCMS = class {
   cwd;
   versions;
   webhooks;
+  mailer;
   constructor(config, db, logger = consoleLogger, storage = localStorage({ dir: config.upload.dir }), cwd = process.cwd()) {
     this.config = config;
     this.db = db;
@@ -2720,6 +2881,11 @@ var EasyCMS = class {
       logger,
       config.collections.some((c) => c.slug === WEBHOOK_DELIVERIES) ? this.webhookQueue() : void 0
     );
+    this.mailer = new Mailer(
+      config.email,
+      logger,
+      config.collections.some((c) => c.slug === EMAIL_DELIVERIES) ? this.emailQueue() : void 0
+    );
     this.auth = new Auth(this);
   }
   async find(collection2, options = {}) {
@@ -3367,10 +3533,57 @@ var EasyCMS = class {
   flushWebhooks() {
     return this.webhooks.flush();
   }
+  /**
+   * Sends an email with the config's `email` adapter, e.g. from a hook or plugin. Resolves once
+   * the email is queued; it is sent in the background and retried from the queue if sending
+   * fails. Without `email` in the config, the email is skipped with a warning.
+   */
+  sendEmail(message) {
+    return this.mailer.send(message);
+  }
+  /** Waits for emails being sent, e.g. before a serverless function returns. */
+  flushEmails() {
+    return this.mailer.flush();
+  }
+  /** Emails queued until sent, stored in `email-deliveries`. */
+  emailQueue() {
+    const collection2 = EMAIL_DELIVERIES;
+    const toRow = (email, createdAt) => {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      return { ...email, createdAt: createdAt ?? now, updatedAt: now };
+    };
+    return {
+      add: async (email) => (await this.db.create({ collection: collection2, data: toRow(email) })).id,
+      update: async (id, email) => {
+        const current = await this.db.findById({ collection: collection2, id });
+        await this.db.update({
+          collection: collection2,
+          id,
+          data: toRow(email, current?.createdAt)
+        });
+      },
+      remove: async (id) => {
+        await this.db.delete({ collection: collection2, id });
+      },
+      due: async (now, limit) => {
+        const { docs } = await this.db.find({
+          collection: collection2,
+          where: {
+            and: [{ state: { equals: "pending" } }, { nextAttemptAt: { lte: now.toISOString() } }]
+          },
+          sort: ["nextAttemptAt"],
+          limit,
+          page: 1
+        });
+        return docs;
+      }
+    };
+  }
   async destroy() {
     if (this.schedulerTimer) clearInterval(this.schedulerTimer);
     await this.running;
     await this.webhooks.flush();
+    await this.mailer.flush();
     await this.db.destroy();
   }
   // --- Scheduled publishing --------------------------------------------------
@@ -3394,7 +3607,11 @@ var EasyCMS = class {
    */
   async runJobs(now = /* @__PURE__ */ new Date()) {
     const scheduled = await this.runScheduled(now);
-    return { ...scheduled, webhooks: await this.retryWebhooks(now) };
+    return {
+      ...scheduled,
+      webhooks: await this.retryWebhooks(now),
+      emails: await this.mailer.retry(now)
+    };
   }
   /**
    * Tries webhook deliveries that are due for another attempt. Deliveries are kept in the
@@ -4130,6 +4347,7 @@ async function readAdminModule(cms, index) {
 }
 
 // src/rest/admin-schema.ts
+var SETTINGS = /* @__PURE__ */ new Set([USERS, API_KEYS]);
 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 };
@@ -4228,6 +4446,7 @@ async function collection(config, user, localized) {
   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.admin?.group === "settings" || SETTINGS.has(config.slug)) result.group = "settings";
   if (config.editIn === "drawer" && !result.drafts && !result.versions && !result.preview)
     result.editIn = "drawer";
   return result;
@@ -4431,7 +4650,7 @@ async function respond(cms, request, url, path, root, options, production) {
     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);
+    const result = root ? await customEndpoint(cms, ctx, method, segments, true, options) : await customEndpoint(cms, ctx, method, segments, false, options) ?? 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 });
@@ -4469,7 +4688,7 @@ function withHeaders(response, extra) {
     headers
   });
 }
-async function customEndpoint(cms, ctx, method, segments, root) {
+async function customEndpoint(cms, ctx, method, segments, root, options) {
   let pathMatched = false;
   const own = cms.config.endpoints.filter((e) => !!e.root === root);
   const endpoints = [...own].sort((a, b) => fixedSegments(b) - fixedSegments(a));
@@ -4484,6 +4703,7 @@ async function customEndpoint(cms, ctx, method, segments, root) {
       url: ctx.url,
       params,
       user: ctx.user,
+      ip: options.getClientIp?.(ctx.request),
       cms,
       json: () => readJson(ctx.request)
     });
@@ -4846,7 +5066,9 @@ function readCookie(request, name) {
 function checkCsrf(cms, ctx) {
   const origin = ctx.request.headers.get("origin");
   const fetchSite = ctx.request.headers.get("sec-fetch-site");
-  const trusted = origin !== null && (origin === ctx.url.origin || cms.config.auth.trustedOrigins.includes(origin));
+  const cookie2 = ctx.via === "cookie" && ctx.token !== void 0;
+  const { cors } = cms.config;
+  const trusted = origin !== null && (origin === ctx.url.origin || cms.config.auth.trustedOrigins.includes(origin) || !cookie2 && (cors === "*" || cors.includes(origin)));
   if (origin !== null && !trusted) throw new ForbiddenError("CSRF check failed: untrusted origin");
   if (origin === null && fetchSite === "cross-site")
     throw new ForbiddenError("CSRF check failed: cross-site request");
@@ -5166,6 +5388,7 @@ export {
   applyDefaults,
   applyPlugins,
   configSignature,
+  consoleEmail,
   consoleLogger,
   copyDatabase,
   createEasyCMS,

package/package.json

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