@easy-cms/core 0.45.0 → 0.47.0

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { FieldCondition } from './conditions.js';
+export { conditionIssues, matchesCondition } from './conditions.js';
+
 /** A document id. SQLite uses integers, Postgres may use either. */
 type ID = string | number;
 type Role = 'admin' | 'editor' | (string & {});
@@ -12,6 +15,11 @@ interface AuthUser {
      * backups, roles, other users' API keys).
      */
     readonly scoped?: boolean;
+    /**
+     * A member of the site, e.g. a customer (`auth.members.roles`): signs in on the site, never to
+     * the admin, and `isLoggedIn` doesn't count them.
+     */
+    readonly member?: boolean;
     readonly [field: string]: unknown;
 }
 /**
@@ -71,7 +79,13 @@ interface FieldAccess {
     readonly update?: FieldAccessFn;
 }
 declare const anyone: Access;
+/**
+ * A signed-in user of the admin: not a site member (`auth.members`). What collections allow by
+ * default.
+ */
 declare const isLoggedIn: Access;
+/** Anyone signed in, site members (e.g. customers) included. */
+declare const isSignedIn: Access;
 declare const isAdmin: Access;
 
 /** What a preview token opens: one document of a collection, or one global. */
@@ -81,8 +95,11 @@ type PreviewTarget = {
 } | {
     readonly global: string;
 };
-/** Why a password link was sent: a forgotten password, or an invitation to a new account. */
-type PasswordPurpose = 'reset' | 'invite';
+/**
+ * Why a link was sent: a forgotten password, an invitation to a new account, or (`verify`) to
+ * confirm the email of an account made by signing up.
+ */
+type PasswordPurpose = 'reset' | 'invite' | 'verify';
 
 /** The cookie that carries a sign-in through the provider and back. */
 declare const SSO_COOKIE = "ecms-sso";
@@ -195,6 +212,29 @@ interface Session {
     readonly csrfToken: string;
     readonly expiresAt: string;
 }
+interface SignupArgs {
+    readonly email: string;
+    readonly password: string;
+    readonly name?: string | undefined;
+    /** From `GET <api>/users/signup`: the form was loaded a moment ago. */
+    readonly token?: unknown;
+    /** The hidden field; bots fill it in. */
+    readonly honeypot?: unknown;
+    /** The Cloudflare Turnstile response, with `signup.turnstile`. */
+    readonly turnstile?: unknown;
+    readonly ip?: string | undefined;
+    /** The request's origin: used for the link only in development, without a site URL. */
+    readonly origin?: string | undefined;
+    readonly locale?: string | undefined;
+    /** The request's context (`onRequest`), e.g. the tenant: given to the users' hooks. */
+    readonly context?: RequestContext;
+}
+/** What signing up did: a link was emailed to confirm, or (without `verifyEmail`) a session. */
+type SignupResult = {
+    readonly verify: true;
+} | (Session & {
+    readonly verify: false;
+});
 /** Where a password link is opened from, and the language of its email. */
 interface PasswordLinkOptions {
     /** The request's origin: used for the link only in development, when `serverURL` is not set. */
@@ -223,6 +263,29 @@ declare class Auth {
         setupCode?: string;
         ip?: string | undefined;
     }): Promise<Session>;
+    /** What a sign-up form needs: a token proving when it was loaded, and Turnstile's site key. */
+    signupForm(): {
+        token: string;
+        turnstile: string | null;
+        verifyEmail: boolean;
+    };
+    /**
+     * Creates a member's account (`auth.members.signup`). With `verifyEmail` (the default), emails
+     * a link to confirm the address and answers the same whether or not the email has an account;
+     * otherwise starts a session. Throws `ValidationError` for spam checks and bad input.
+     */
+    signup(args: SignupArgs): Promise<SignupResult>;
+    /** Confirms a member's email from the link, and signs them in. */
+    verifyEmail(args: {
+        token: string;
+        ip?: string | undefined;
+    }): Promise<Session>;
+    private mailVerifyLink;
+    /**
+     * A link to one of the site's pages for members (`auth.members.pages`), else to the admin's
+     * page of the same purpose.
+     */
+    private memberLink;
     hasUsers(): Promise<boolean>;
     /** Ends the session for a signed token. Unknown tokens are ignored. */
     logout(signedToken: string): Promise<void>;
@@ -374,12 +437,35 @@ interface Database {
         collection: string;
         data: Record<string, unknown>;
     }): Promise<RawDocument>;
-    /** `data` holds the whole document after merging. Runs in one transaction. */
+    /**
+     * `data` holds the whole document after merging. Runs in one transaction. With `where`, only
+     * when the stored document matches it at the moment of writing (compare and set): `null` when
+     * it doesn't, and nothing is written.
+     */
     update(args: {
         collection: string;
         id: ID;
         data: Record<string, unknown>;
     }): Promise<RawDocument>;
+    update(args: {
+        collection: string;
+        id: ID;
+        data: Record<string, unknown>;
+        where: Where;
+    }): Promise<RawDocument | null>;
+    /**
+     * Adds `by` to a top-level number field in one statement, safe against concurrent calls; an
+     * empty value counts as 0. With `min` / `max`, only when the result stays within them. Returns
+     * the new value, or `null` when it would leave the bounds or the document is gone.
+     */
+    increment(args: {
+        collection: string;
+        id: ID;
+        field: string;
+        by: number;
+        min?: number | undefined;
+        max?: number | undefined;
+    }): Promise<number | null>;
     delete(args: {
         collection: string;
         id: ID;
@@ -623,8 +709,13 @@ type WithPluginFields<C extends Config, T extends {
 }, Key extends 'fields' | 'globalFields'> = [PluginFields<C, T['slug'], Key>] extends [never] ? T : Omit<T, 'fields'> & {
     readonly fields: readonly (T['fields'][number] | PluginFields<C, T['slug'], Key>)[];
 };
+/**
+ * The config's own collections. A literal config without `collections` has none (only plugins
+ * add some); a loosely typed `Config` has any.
+ */
+type OwnCollections<C extends Config> = 'collections' extends keyof C ? NonNullable<C['collections']>[number] : never;
 /** Every collection of a config, including the built-in ones and those plugins add. */
-type AllCollections<C extends Config> = NonNullable<C['collections']>[number] | BuiltinUsersCollection | BuiltinMediaCollection | ApiKeysOf<C> | FoldersOf<C> | PluginCollections<C>;
+type AllCollections<C extends Config> = OwnCollections<C> | BuiltinUsersCollection | BuiltinMediaCollection | ApiKeysOf<C> | FoldersOf<C> | PluginCollections<C>;
 /** The built-in media collection; its documents are typed as `MediaDocument`. */
 interface BuiltinMediaCollection {
     readonly slug: 'media';
@@ -766,7 +857,7 @@ type InferGlobal<T extends FieldsOwner, C extends Config = Config> = Simplify<
 } ? {
     status: 'draft' | 'published';
 } : unknown) & FieldsValue<T['fields'], C>>;
-type CollectionSlug<C extends Config> = NonNullable<C['collections']>[number]['slug'] | 'users' | 'media' | ApiKeysOf<C>['slug'] | FoldersOf<C>['slug'] | PluginCollections<C>['slug'];
+type CollectionSlug<C extends Config> = OwnCollections<C>['slug'] | 'users' | 'media' | ApiKeysOf<C>['slug'] | FoldersOf<C>['slug'] | PluginCollections<C>['slug'];
 type GlobalSlug<C extends Config> = NonNullable<C['globals']>[number]['slug'];
 /** Document type of a collection, e.g. `CollectionDocument<typeof config, 'posts'>`. */
 type CollectionDocument<C extends Config, S extends CollectionSlug<C>> = S extends 'media' ? MediaDocument : InferCollection<CollectionBySlug<C, S>, C>;
@@ -797,7 +888,10 @@ type InputValue<F extends Field> = F extends {
     readonly type: 'blocks';
     readonly blocks: infer B extends readonly Block[];
 } ? readonly BlockInput<B[number]>[] : FieldValue<F>;
-/** Required fields must be given, unless Easy CMS can fill them (default value, slug from another field). */
+/**
+ * Required fields must be given, unless Easy CMS can fill them (default value, slug from another
+ * field) or a condition may hide them (`admin.condition`).
+ */
 type NeedsInput<F extends Field> = F extends {
     readonly required: true;
 } ? F extends {
@@ -805,6 +899,10 @@ type NeedsInput<F extends Field> = F extends {
 } ? never : F extends {
     readonly type: 'slug';
     readonly from: string;
+} ? never : F extends {
+    readonly admin: {
+        readonly condition: object;
+    };
 } ? never : F : never;
 type FieldsInput<Fs extends readonly Field[]> = Simplify<{
     -readonly [F in NeedsInput<Visible<Fs>> as F['name']]: InputValue<F>;
@@ -1237,6 +1335,18 @@ interface UpdateOptions extends DepthOptions {
      * stays, and no version is added to the history.
      */
     readonly live?: boolean;
+    /**
+     * Saves only when the stored document still matches this at the moment of writing (compare and
+     * set), e.g. `{ status: { equals: 'pending' } }` so that one of two concurrent calls wins.
+     * `update()` then returns `null` when it doesn't match, after its `before*` hooks ran.
+     */
+    readonly where?: Where;
+}
+interface IncrementOptions {
+    /** Only when the result stays at or above this, e.g. `0` for stock. */
+    readonly min?: number;
+    /** Only when the result stays at or below this. */
+    readonly max?: number;
 }
 interface ReadOptions extends DepthOptions {
     /**
@@ -1261,8 +1371,8 @@ interface CreateEasyCMSOptions {
     readonly cwd?: string;
     /**
      * Run due scheduled jobs and webhook retries every minute in this process. Default: on when
-     * a collection or global has `schedule`, or `webhooks` is set. Turn it off where a cron calls
-     * `runJobs` (or `GET <api>/jobs/run`) instead.
+     * a collection or global has `schedule`, or `webhooks`, `email` or `jobs` is set. Turn it off
+     * where a cron calls `runJobs` (or `GET <api>/jobs/run`) instead.
      */
     readonly scheduler?: boolean;
     /** Default `verify` when `NODE_ENV=production`, otherwise `push`. */
@@ -1426,7 +1536,18 @@ declare class EasyCMS<C extends Config = Config> {
     /** Files at the top level are public. */
     private settleTopLevel;
     private settleFiles;
-    update<S extends Slug<C>>(collection: S, id: ID, data: Update<C, S>, options?: UpdateOptions): Promise<Doc<C, S>>;
+    update<S extends Slug<C>>(collection: S, id: ID, data: Update<C, S>, options: UpdateOptions & {
+        where: Where;
+    }): Promise<Doc<C, S> | null>;
+    update<S extends Slug<C>>(collection: S, id: ID, data: Update<C, S>, options?: UpdateOptions & {
+        where?: undefined;
+    }): Promise<Doc<C, S>>;
+    /**
+     * Adds `by` (negative to take away) to a top-level number field in one database statement, so
+     * concurrent calls never lose a change, e.g. stock or a counter. Skips hooks, validation, access
+     * and versions. Returns the new value, or `null` when `min` / `max` would be passed.
+     */
+    increment<S extends Slug<C>>(collection: S, id: ID, field: string, by: number, options?: IncrementOptions): Promise<number | null>;
     /**
      * Takes a document off the site: its status becomes `draft`. With versions and drafts, a plain
      * `update` with `status: 'draft'` only saves a draft and leaves the published document live;
@@ -1556,7 +1677,21 @@ declare class EasyCMS<C extends Config = Config> {
             sent: number;
             failed: number;
         };
+        jobs: {
+            ran: number;
+            failed: number;
+        };
     }>;
+    /** `jobs` of the config that are due; when each last ran is kept in the database. */
+    private runConfigJobs;
+    /**
+     * Sends an event of the app or a plugin (`events` in the config, e.g. `order.paid`) to the
+     * webhooks that list it. Returns at once; deliveries are queued and retried like content changes.
+     */
+    emit(event: string, data: Record<string, unknown>, about?: {
+        collection: string;
+        id: ID;
+    }): void;
     /**
      * Tries webhook deliveries that are due for another attempt. Deliveries are kept in the
      * database until they succeed, so they survive restarts.
@@ -1654,7 +1789,7 @@ declare class EasyCMS<C extends Config = Config> {
     /** Replaces published documents that have a newer draft with that draft. */
     private withDrafts;
     /** Sends webhook events for a change; `before` is the stored status before it, if any. */
-    private emit;
+    private emitChange;
     /**
      * Writes the audit log entry for a change (`audit`): publishing, unpublishing and restoring
      * are told apart from other saves.
@@ -1728,6 +1863,15 @@ type AdminComponent = string | {
 };
 /** How the admin shows a field, with components from admin modules. */
 interface FieldAdmin {
+    /** Help below the field's label. */
+    readonly description?: Label;
+    /** Its share of a row (`admin.layout`'s `row`). Default: an equal share. */
+    readonly width?: '1/4' | '1/3' | '1/2' | '2/3' | '3/4' | 'full';
+    /**
+     * Shown only when its sibling fields match, e.g. `{ field: 'linkType', equals: 'external' }`.
+     * A hidden field isn't required. See `FieldCondition`.
+     */
+    readonly condition?: FieldCondition;
     /** 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. */
@@ -2097,6 +2241,7 @@ declare const DEFAULT_PASSWORD_EMAILS: {
     resetPassword: PasswordEmailFn;
     invite: PasswordEmailFn;
     passwordChanged: PasswordEmailFn;
+    verifyEmail: PasswordEmailFn;
 };
 
 /**
@@ -2243,8 +2388,11 @@ type WebhookEvent = (typeof WEBHOOK_EVENTS)[number];
 interface WebhookConfig {
     /** Where to POST events. */
     readonly url: string;
-    /** Events to send. Default: all. */
-    readonly events?: readonly WebhookEvent[];
+    /**
+     * Events to send. Default: every content change. Events of the app or its plugins (`events`
+     * in the config, e.g. `order.paid`) are sent only when listed here.
+     */
+    readonly events?: readonly (WebhookEvent | (string & {}))[];
     /** Collections to send events for. Default: all; `[]` for none. */
     readonly collections?: readonly string[];
     /** Globals to send events for. Default: all; `[]` for none. */
@@ -2256,11 +2404,15 @@ interface WebhookConfig {
 }
 /** What a webhook receives as JSON. */
 interface WebhookPayload {
-    readonly event: WebhookEvent;
+    /** A content change (`WebhookEvent`), or an event of the app or a plugin, e.g. `order.paid`. */
+    readonly event: string;
     readonly collection?: string;
     readonly global?: string;
     readonly id?: ID;
-    /** The stored document (every locale, no hidden fields); for `delete`, as it was. */
+    /**
+     * The stored document (every locale, no hidden fields); for `delete`, as it was. For an event of
+     * the app or a plugin: what `cms.emit()` was given.
+     */
     readonly doc: Record<string, unknown>;
     /** ISO time of the change. */
     readonly timestamp: string;
@@ -2338,17 +2490,72 @@ interface VersionsConfig {
     /** Versions kept per document; older ones are deleted. Default 50. */
     readonly max?: number;
 }
+/** A panel of an edit page's side column: a component, at the top or (default) below the rest. */
+type SidebarPanel = AdminComponent | {
+    readonly tag: string;
+    readonly props?: Readonly<Record<string, unknown>>;
+    /** `top`: right below publishing, above the side fields. Default: below them. */
+    readonly position?: 'top';
+};
+/**
+ * Where the edit page puts its fields: tabs, collapsible sections and rows, by field name. Only
+ * how they look: the data stays as the fields say. Fields not placed follow at the end (in the
+ * first tab). Top-level fields; sidebar fields stay in the side column.
+ *
+ * ```ts
+ * layout: [
+ *   { tab: 'Content', fields: ['title', { row: ['author', 'category'] }, 'body'] },
+ *   { tab: 'SEO', fields: ['meta'] },
+ * ]
+ * ```
+ */
+type LayoutNode = string | {
+    readonly row: readonly string[];
+} | {
+    readonly collapsible: Label;
+    /** Starts folded. */
+    readonly collapsed?: boolean;
+    readonly description?: Label;
+    readonly fields: readonly LayoutNode[];
+} | {
+    readonly tab: Label;
+    readonly description?: Label;
+    readonly fields: readonly LayoutNode[];
+};
 /** 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[];
+    /** Panels in the edit page's side column (components from admin modules). */
+    readonly sidebar?: readonly SidebarPanel[];
+    /** Tabs, collapsible sections and rows of the edit page. See `LayoutNode`. */
+    readonly layout?: readonly LayoutNode[];
+    /**
+     * Its menu group: a group's id (`admin.nav`), e.g. `shop` or `shop.catalog`; `settings` for
+     * Settings; or a label, which makes a group of that name. Default: Content for collections,
+     * Settings › Site for globals.
+     */
+    readonly group?: 'settings' | Label;
 }
 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.
+     * A number that needs attention, next to its menu item: the documents matching `where` (that
+     * the user may read), e.g. orders to send. `tone`: `accent` (default), `warning` or `danger`.
      */
-    readonly group?: 'settings';
+    readonly badge?: {
+        readonly where: Where;
+        readonly tone?: 'accent' | 'warning' | 'danger';
+        /** What the number counts, for screen readers, e.g. `{ en: 'to send', th: 'รอจัดส่ง' }`. */
+        readonly label?: Label;
+    };
+    /** The number of documents beside its menu item. Default `true`. */
+    readonly count?: boolean;
+    /** The list with no documents yet: what to say, and a link, e.g. to a guide. */
+    readonly empty?: {
+        readonly description?: Label;
+        readonly link?: {
+            readonly label: Label;
+            readonly href: string;
+        };
+    };
     readonly list?: CollectionListAdmin;
     /**
      * With `auth.rbac`: the relationship field to `users` that names a document's owner, e.g.
@@ -2450,6 +2657,26 @@ interface AdminBrand {
     /** Main color as `#rrggbb`; lighter and darker shades are derived from it. */
     readonly color?: string;
 }
+/** A group of the admin menu (`admin.nav`). */
+interface NavGroup {
+    /** Lowercase letters, digits and `-`; children are named `<parent>.<child>`, e.g. `shop.catalog`. */
+    readonly id: string;
+    readonly label: Label;
+    readonly icon?: AdminIcon;
+    /** Its place among the groups: lower first. Content is 0, the media library 10, Settings 1000. */
+    readonly order?: number;
+    /** Groups inside it, one level. */
+    readonly children?: readonly Omit<NavGroup, 'children'>[];
+}
+/** An entry of the command palette (⌘K) that opens a page of the admin. */
+interface AdminCommand {
+    readonly label: Label;
+    /** A path in the admin, e.g. `/collections/orders?f_status=paid`. */
+    readonly to: string;
+    readonly icon?: AdminIcon;
+    /** Words that find it besides its label. */
+    readonly keywords?: readonly string[];
+}
 /** Who may see an admin page or dashboard widget. Default: every logged-in user. */
 type AdminViewAccess = (args: {
     readonly user: AuthUser;
@@ -2464,8 +2691,11 @@ interface AdminPage {
     readonly label: Label;
     /** Icon in the admin menu. Default `file-text`. */
     readonly icon?: AdminIcon;
-    /** Listed under Content (default) or Settings in the menu, or not listed (`false`): reached by links. */
-    readonly group?: 'content' | 'settings' | false;
+    /**
+     * Its menu group: `content` (default), `settings`, a group's id (`admin.nav`) or a label; `false`:
+     * not listed, reached by links.
+     */
+    readonly group?: 'content' | 'settings' | false | Label;
     /** Who may open it. Pages a user may not open are left out of their admin. */
     readonly access?: AdminViewAccess;
 }
@@ -2497,6 +2727,15 @@ interface AdminConfig {
      * Collections not listed follow in config order, with the media library last.
      */
     readonly menu?: readonly string[];
+    /**
+     * The admin menu's groups, which collections, globals and pages name in `admin.group`, e.g.
+     * `{ id: 'shop', label: 'Shop', icon: 'store', children: [{ id: 'catalog', label: 'Catalog' }] }`.
+     * Built in: `content` and `settings` (with `site`, `people` and `system`); declaring one of
+     * their ids changes its label, icon or order. Plugins declare their own.
+     */
+    readonly nav?: readonly NavGroup[];
+    /** More entries of the command palette (⌘K), e.g. a plugin's page with a filter. */
+    readonly commands?: readonly AdminCommand[];
     /**
      * 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
@@ -2581,6 +2820,44 @@ interface RoutesConfig {
     /** Where the REST API is served. Default `/api/cms`. */
     readonly api?: string;
 }
+/**
+ * People who sign in on the site rather than to the admin, e.g. customers of a shop.
+ */
+interface MembersConfig {
+    /**
+     * Their roles, also listed in `roles`. Members never get into the admin, and access that
+     * defaults to logged-in users (`isLoggedIn`) doesn't count them: give them access in the
+     * collections they use, e.g. with `isSignedIn`.
+     */
+    readonly roles: readonly string[];
+    /** Visitors create their own account: `POST <api>/users/signup`. */
+    readonly signup?: MembersSignup;
+    /**
+     * The site's pages that open the links of members' emails, given `?token=`: paths on
+     * `admin.siteUrl` (else `serverURL`), or full URLs. Without them, links go to the admin's pages.
+     */
+    readonly pages?: {
+        /** Confirms the email of a new account: `POST <api>/users/verify-email` with the token. */
+        readonly verifyEmail?: string;
+        /** Sets a forgotten password: `POST <api>/users/reset-password` with the token. */
+        readonly resetPassword?: string;
+    };
+    /** Your own text for the email that confirms an address. Default: English or Thai. */
+    readonly emails?: {
+        readonly verifyEmail?: PasswordEmailFn;
+    };
+}
+interface MembersSignup {
+    /** The role new accounts get: one of `members.roles`. */
+    readonly role: string;
+    /** New accounts confirm their email with a link before signing in. Default `true`. */
+    readonly verifyEmail?: boolean;
+    /** Cloudflare Turnstile, checked on every sign-up when set. */
+    readonly turnstile?: {
+        readonly siteKey: string;
+        readonly secretKey: string;
+    };
+}
 interface AuthConfig {
     /**
      * Roles a user can have. Must include `admin`. Default `['admin', 'editor']`. With `rbac`, these
@@ -2634,6 +2911,11 @@ interface AuthConfig {
      * no code is asked.
      */
     readonly setupCode?: string;
+    /**
+     * People who sign in on the site, not to the admin, e.g. customers: their roles, signing up,
+     * and the pages their email links open.
+     */
+    readonly members?: MembersConfig;
     /** Your own text for the password emails, e.g. in your brand's voice. Default: English or Thai. */
     readonly emails?: {
         readonly resetPassword?: PasswordEmailFn;
@@ -2677,9 +2959,22 @@ interface EndpointRequest {
     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.
+ * Work that runs with the scheduled jobs: every minute in a server, or each time a cron calls
+ * `GET <api>/jobs/run`. E.g. a plugin's clean-up.
  */
+interface JobConfig {
+    /** Unique, e.g. `ecommerce:carts`. */
+    readonly name: string;
+    /**
+     * At most this often, in seconds. Default: every run. The last run is kept in the database, so
+     * it holds across processes and serverless invocations.
+     */
+    readonly every?: number;
+    readonly run: (args: {
+        readonly cms: EasyCMS;
+        readonly now: Date;
+    }) => MaybePromise<unknown>;
+}
 /** An `easy-cms <name> [args…]` command. Built-in commands keep their names. */
 interface CliCommand {
     /** Lowercase, e.g. `nested:rebuild`. */
@@ -2696,6 +2991,10 @@ interface CliCommand {
         readonly log: (line: string) => void;
     }) => MaybePromise<number | undefined>;
 }
+/**
+ * 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
@@ -2804,6 +3103,13 @@ interface Config {
     readonly cronSecret?: string;
     /** Endpoints notified when content changes, e.g. to rebuild a static site. */
     readonly webhooks?: readonly WebhookConfig[];
+    /**
+     * Events of the app or its plugins besides content changes, e.g. `order.paid`: sent with
+     * `cms.emit()` to the webhooks that list them in `events`. Named `<area>.<what>`.
+     */
+    readonly events?: readonly string[];
+    /** Work run with the scheduled jobs, e.g. a plugin's clean-up. */
+    readonly jobs?: readonly JobConfig[];
     /** Content in several languages: fields with `localized: true` hold one value per locale. */
     readonly localization?: LocalizationConfig | null;
     readonly routes?: RoutesConfig;
@@ -2865,6 +3171,8 @@ interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes'
     readonly globals: readonly GlobalConfig[];
     readonly endpoints: readonly Endpoint[];
     readonly commands: readonly CliCommand[];
+    readonly events: readonly string[];
+    readonly jobs: readonly JobConfig[];
     readonly fieldTypes: readonly FieldTypeDefinition[];
     /** The config's plugins in order, with their `info` where they give one. */
     readonly installedPlugins: readonly Partial<PluginInfo>[];
@@ -3114,6 +3422,9 @@ declare function imageDimensions(data: Uint8Array, type: string): {
     height: number;
 } | undefined;
 
+/** The menu's groups that are always there. Declaring their ids changes labels, icons, order. */
+declare const BUILTIN_NAV: readonly NavGroup[];
+
 declare const DEFAULT_DEPTH = 1;
 declare const MAX_DEPTH = 3;
 /** Loads the documents of one collection that the caller may see. */
@@ -3212,7 +3523,51 @@ declare function resolveAdminModule(specifier: string, cwd?: string): string | u
 interface AdminComponentRef {
     tag: string;
     props?: Record<string, unknown>;
+    /** A side panel at the top of the side column (`position: 'top'`). */
+    position?: 'top';
+}
+/** Where the edit page puts its fields (`admin.layout`), with unplaced fields filled in. */
+type AdminLayoutNode = {
+    type: 'field';
+    name: string;
+} | {
+    type: 'row';
+    fields: string[];
+} | {
+    type: 'collapsible';
+    label: Label;
+    collapsed?: boolean;
+    description?: Label;
+    nodes: AdminLayoutNode[];
+} | {
+    type: 'tab';
+    label: Label;
+    description?: Label;
+    nodes: AdminLayoutNode[];
+};
+/** An entry of the admin menu. */
+type AdminNavItem = {
+    kind: 'collection';
+    slug: string;
+} | {
+    kind: 'global';
+    slug: string;
+} | {
+    kind: 'page';
+    path: string;
+} | {
+    kind: 'view';
+    view: 'roles' | 'sso' | 'backups' | 'email' | 'deliveries' | 'audit';
+};
+/** A group of the admin menu (`admin.nav`), with what this user may open in it. */
+interface AdminNavGroup {
+    kind: 'group';
+    id: string;
+    label: Label;
+    icon?: string;
+    items: AdminNavNode[];
 }
+type AdminNavNode = AdminNavItem | AdminNavGroup;
 /** A field as the admin UI sees it: plain JSON, no functions. */
 interface AdminField {
     name: string;
@@ -3271,6 +3626,12 @@ interface AdminField {
     noCreate?: boolean;
     /** A field of an added type (`fieldTypes`), e.g. `color`; `type` is the base it's stored as. */
     customType?: string;
+    /** Help below its label (`admin.description`). */
+    description?: Label;
+    /** Its share of a row (`admin.width`). */
+    width?: string;
+    /** Shown only when its siblings match (`admin.condition`). */
+    condition?: FieldCondition;
 }
 interface AdminCollection {
     slug: string;
@@ -3291,8 +3652,23 @@ 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';
+    /** Tabs, sections and rows of the edit page (`admin.layout`). */
+    layout?: AdminLayoutNode[];
+    /** A number in the menu (`admin.badge`); the menu's counts come from `GET <api>/admin/counts`. */
+    badge?: {
+        tone: 'accent' | 'warning' | 'danger';
+        label?: Label;
+    };
+    /** No document count beside it in the menu (`admin.count: false`). */
+    noCount?: boolean;
+    /** What the list says while it has no documents (`admin.empty`). */
+    empty?: {
+        description?: Label;
+        link?: {
+            label: Label;
+            href: string;
+        };
+    };
     /** The list is a tree along this relationship field (`admin.list.tree`). */
     tree?: string;
     /** The list's default order (`admin.list.sort`). */
@@ -3325,6 +3701,8 @@ interface AdminGlobal {
     fields: AdminField[];
     /** Panels from admin modules in the edit page's side column. */
     sidebar?: AdminComponentRef[];
+    /** Tabs, sections and rows of the edit page (`admin.layout`). */
+    layout?: AdminLayoutNode[];
     permissions: {
         read: boolean;
         update: boolean;
@@ -3336,8 +3714,6 @@ interface AdminPageRef {
     path: string;
     label: Label;
     icon?: string;
-    /** Where it is listed in the menu; `false`: not listed. */
-    group: 'content' | 'settings' | false;
     component: AdminComponentRef;
 }
 /** A dashboard panel (`admin.dashboard`) this user may see. */
@@ -3353,6 +3729,15 @@ interface AdminSchema {
     passwordLinks: boolean;
     /** Menu order of collections (`admin.menu`); unlisted ones follow. */
     menu: string[];
+    /** The menu: groups and what this user may open in them, in order. */
+    nav: AdminNavNode[];
+    /** More entries of the command palette (`admin.commands`). */
+    commands: {
+        label: Label;
+        to: string;
+        icon?: string;
+        keywords?: string[];
+    }[];
     /** Content locales, when the config has `localization`. */
     localization: {
         locales: string[];
@@ -3402,6 +3787,13 @@ interface AdminSchema {
     dashboard: AdminWidgetRef[];
 }
 
+interface SearchHit {
+    readonly collection: string;
+    readonly id: ID;
+    readonly title: string;
+    readonly status?: string;
+}
+
 /** 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. */
@@ -3495,6 +3887,27 @@ declare function createRestHandler<C extends Config>(instance: EasyCMS<C>, optio
 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;
 
+/** A token that proves the form `purpose` names was loaded at `now`: `<time>.<signature>`. */
+declare function formToken(secret: string, purpose: string, now?: number): string;
+/**
+ * Checks a token: `ok` when the form was loaded at least `minTime` ms ago (people take a few
+ * seconds; bots don't) and less than a day ago.
+ */
+declare function checkFormToken(secret: string, purpose: string, token: unknown, minTime: number, now?: number): 'ok' | 'invalid' | 'too-fast' | 'expired';
+/**
+ * Rate-limit keys for `subject` (e.g. an IP and a form) in the current and previous window of
+ * `window` seconds. A hash with the window in it: no IP is kept, and keys from different
+ * windows can't be linked.
+ */
+declare function rateKeys(secret: string, subject: string, window: number, now?: number): {
+    current: string;
+    previous: string;
+};
+/** The hidden field bots fill in: a common name the form doesn't use. */
+declare function honeypotName(names: readonly string[]): string;
+/** Checks a Cloudflare Turnstile response with Cloudflare. */
+declare function verifyTurnstile(secretKey: string, response: unknown, ip: string | undefined, fetcher?: typeof fetch): Promise<boolean>;
+
 /** Best-effort English singular: "categories" → "category". */
 declare function singularize(word: string): string;
 /**
@@ -3512,4 +3925,4 @@ declare function validateConfig(config: Config): ConfigIssue[];
 /** 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 AdminBackup, type AdminBackups, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminDeliveries, type AdminDelivery, type AdminEmail, type AdminEmailDelivery, type AdminField, type AdminFieldArgs, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminPage, type AdminPageRef, type AdminRole, type AdminRoleChange, type AdminRoleField, type AdminRoleTarget, type AdminRoleView, type AdminRoles, type AdminSchema, type AdminSso, type AdminStatus, type AdminSwitcher, type AdminViewAccess, type AdminWebhookDelivery, type AdminWidgetRef, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiHandlerOptions, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, type AuditChange, type AuditConfig, type AuditEntry, AuditLog, type AuditPage, type AuditVerification, Auth, type AuthConfig, type AuthProvider, type AuthProviderProfile, type AuthProviderRequest, type AuthUser, BUILTIN_COLLECTIONS, type BackupState, type BackupsConfig, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, type BuiltinMediaCollection, type BuiltinMediaFoldersCollection, 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 DeliveryKind, type DeliveryState, type DepthOptions, type DirectUpload, type DocumentOf, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailCheck, type EmailField, type EmailMessage, type EmailSetting, type Endpoint, type EndpointRequest, FIELD_TYPES, FIELD_TYPE_BASES, FOLDER_LEVELS, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldRule, 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, type FolderLevel, type FolderPermissions, 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, MEDIA_FOLDERS, MIME_GROUPS, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, MediaFolders, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type OnRequest, type OnRequestArgs, type Operation, type PaginatedDocs, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, PayloadTooLargeError, type Plugin, type PluginInfo, type PluginTypes, type PreviewTarget, type PreviewURL, QueryError, ROLE_OPERATIONS, type RawDocument, type ReadOptions, type RelationshipField, type RequestContext, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoleOperation, type RolePermissions, Roles, type RoutesConfig, SESSION_COOKIE, SSO_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type SlugOf, type SsoOutcome, type SsoProviderRef, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, type UploadFromURLConfig, type UserIdentity, 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, createApiHandler, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, defineFieldType, definePlugin, expandMimeTypes, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, isSystemAdmin, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, sharedEasyCMS, silentLogger, singularize, slugify, sniffMimeType, uniqueWithinOf, validateConfig, validateFields, verifyPassword, writeBackupFile };
+export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, type Access, type AccessArgs, type AccessOptions, type AdminAttention, type AdminBackup, type AdminBackups, type AdminBrand, type AdminCollection, type AdminCommand, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminDeliveries, type AdminDelivery, type AdminEmail, type AdminEmailDelivery, type AdminField, type AdminFieldArgs, type AdminGlobal, type AdminIcon, type AdminLayoutNode, type AdminLocale, type AdminNavGroup, type AdminNavItem, type AdminNavNode, type AdminPage, type AdminPageRef, type AdminRole, type AdminRoleChange, type AdminRoleField, type AdminRoleTarget, type AdminRoleView, type AdminRoles, type AdminSchema, type AdminSso, type AdminStatus, type AdminSwitcher, type AdminViewAccess, type AdminWebhookDelivery, type AdminWidgetRef, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiHandlerOptions, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, type AuditChange, type AuditConfig, type AuditEntry, AuditLog, type AuditPage, type AuditVerification, Auth, type AuthConfig, type AuthProvider, type AuthProviderProfile, type AuthProviderRequest, type AuthUser, BUILTIN_COLLECTIONS, BUILTIN_NAV, type BackupState, type BackupsConfig, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, type BuiltinMediaCollection, type BuiltinMediaFoldersCollection, 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 DeliveryKind, type DeliveryState, type DepthOptions, type DirectUpload, type DocumentOf, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailCheck, type EmailField, type EmailMessage, type EmailSetting, type Endpoint, type EndpointRequest, FIELD_TYPES, FIELD_TYPE_BASES, FOLDER_LEVELS, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, FieldCondition, type FieldError, type FieldRule, 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, type FolderLevel, type FolderPermissions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type IncrementOptions, type InferCollection, type InferGlobal, type JobConfig, type JsonField, type Label, type LayoutNode, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MEDIA_FOLDERS, MIME_GROUPS, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, MediaFolders, type MediaSize, type MembersConfig, type MembersSignup, type MigrationInfo, type NavGroup, NotFoundError, type NumberField, type OnRequest, type OnRequestArgs, type Operation, type PaginatedDocs, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, PayloadTooLargeError, type Plugin, type PluginInfo, type PluginTypes, type PreviewTarget, type PreviewURL, QueryError, ROLE_OPERATIONS, type RawDocument, type ReadOptions, type RelationshipField, type RequestContext, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoleOperation, type RolePermissions, Roles, type RoutesConfig, SESSION_COOKIE, SSO_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SearchHit, type SelectField, type SelectOption, type Session, type SidebarPanel, type SignupArgs, type SignupResult, type SlugField, type SlugOf, type SsoOutcome, type SsoProviderRef, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, type UploadFromURLConfig, type UserIdentity, VERSION, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, checkFormToken, configSignature, consoleEmail, consoleLogger, copyDatabase, createApiHandler, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, defineFieldType, definePlugin, expandMimeTypes, fillMissing, findConfigFile, formToken, generateSlugs, generateTypes, hasRows, hashPassword, honeypotName, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, isSignedIn, isSystemAdmin, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, rateKeys, readCookie, resolveAdminModule, resolveConfig, rowFields, sharedEasyCMS, silentLogger, singularize, slugify, sniffMimeType, uniqueWithinOf, validateConfig, validateFields, verifyPassword, verifyTurnstile, writeBackupFile };