@easy-cms/core 0.44.0 → 0.46.0

package/dist/index.d.ts

@@ -12,6 +12,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 +76,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 +92,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 +209,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 +260,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 +434,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 +706,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 +854,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>;
@@ -1087,9 +1175,15 @@ declare class MediaFolders {
      * The folder with this key (`folder: 'banners'` on upload fields), made at the top level when
      * there is none yet.
      */
-    keyed(key: string): Promise<ID>;
+    /**
+     * The folder with this key, made when first needed. `scope`: the values the key is unique
+     * within (`uniqueWithin` of the `key` field, e.g. the tenant), given to a new folder too.
+     * `null` when there is none and `create` is false.
+     */
+    keyed(key: string, scope?: Readonly<Record<string, unknown>>): Promise<ID>;
+    keyed(key: string, scope: Readonly<Record<string, unknown>>, create: boolean): Promise<ID | null>;
     /** Whether a file in `folder` is in the folder with this key, or below it. */
-    inKeyed(key: string, folder: ID | null): Promise<boolean>;
+    inKeyed(key: string, folder: ID | null, scope?: Readonly<Record<string, unknown>>): Promise<boolean>;
     /** The user's level in a folder (`null`: the top level). */
     level(user: AuthUser | null, id: ID | null): Promise<FolderLevel | 'none'>;
     /**
@@ -1231,6 +1325,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 {
     /**
@@ -1255,8 +1361,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`. */
@@ -1420,7 +1526,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;
@@ -1550,7 +1667,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.
@@ -1648,7 +1779,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.
@@ -1673,6 +1804,23 @@ declare class EasyCMS<C extends Config = Config> {
     private makeSlugsUnique;
     private checkUnique;
     private isTaken;
+    /**
+     * What folder keys are unique within for a call (`uniqueWithin` of the `key` field of media
+     * folders, e.g. the tenant): the value a folder made by this call would get from its hooks.
+     */
+    private folderScope;
+    /**
+     * Where a unique field's values must differ for a call (`uniqueWithin`, e.g. the tenant): the
+     * value a document created by this call would get there from its hooks, as `{ [field]: value }`;
+     * `{}` when the field is unique everywhere. For finding documents by such a field, e.g. a page
+     * by its path in the current tenant.
+     */
+    uniqueScope(collection: string, field: string, options?: Pick<AccessOptions, 'user' | 'context'>): Promise<Record<string, unknown>>;
+    /**
+     * @internal The id of the media folder with this key (`folder` of upload fields), made when
+     * needed; `null` when the call has no scope to make it in (e.g. all tenants) and none exists.
+     */
+    keyedFolder(key: string, options?: AccessOptions): Promise<ID | null>;
     /** Each reference is one its relationship's `filterOptions` allow. */
     private checkFilterOptions;
     private checkReferences;
@@ -1711,6 +1859,23 @@ interface FieldAdmin {
     readonly after?: readonly AdminComponent[];
     /** Shows the value in the admin's lists (e.g. a color swatch). Default: the plain value. */
     readonly cell?: AdminComponent;
+    /**
+     * A column of the list at first (each user can change it): `true`, or per request, e.g.
+     * only when the admin shows every tenant.
+     */
+    readonly column?: boolean | ((args: AdminFieldArgs) => boolean | Promise<boolean>);
+    /** Relationships: offer to create the related document in place. Default true. */
+    readonly allowCreate?: boolean;
+    /**
+     * The value a new document's form starts with, worked out for each user, e.g. from the
+     * request's context. The server's own default (`defaultValue`, hooks) still applies.
+     */
+    readonly defaultValue?: (args: AdminFieldArgs) => unknown;
+}
+/** What per-request admin options of a field receive. */
+interface AdminFieldArgs {
+    readonly user: AuthUser;
+    readonly context: RequestContext;
 }
 /**
  * Field types that packages add (`fieldTypes` in the config), for the types inferred from the
@@ -1741,11 +1906,11 @@ interface BaseField<TType extends string, TValue> {
     readonly required?: boolean;
     readonly unique?: boolean;
     /**
-     * With `unique` (or on a slug field): the name of a sibling field (e.g. `parent` or `tenant`)
+     * With `unique` (or on a slug field): a sibling field (e.g. `parent` or `tenant`), or several,
      * whose documents only need to differ among themselves, so `/about/team` and `/careers/team`
-     * can both be `team`. A single, unlocalized relationship, select, text or number field.
+     * can both be `team`. Single, unlocalized relationship, select, text or number fields.
      */
-    readonly uniqueWithin?: string;
+    readonly uniqueWithin?: string | readonly string[];
     readonly index?: boolean;
     readonly defaultValue?: TValue;
     readonly validate?: FieldValidate<TValue>;
@@ -1825,6 +1990,8 @@ interface UploadField extends BaseField<'upload', never> {
     readonly folder?: string;
     /** With `folder`: only files in that folder (and its subfolders) may be chosen. */
     readonly folderOnly?: boolean;
+    /** Which media documents may be chosen, as for relationships: offered and checked on save. */
+    readonly filterOptions?: FilterOptions;
 }
 interface FilterOptionsArgs {
     /** The document being edited; `undefined` while it is being created. */
@@ -1876,6 +2043,8 @@ interface BlocksField extends BaseField<'blocks', never> {
     readonly minRows?: number;
     readonly maxRows?: number;
 }
+/** The fields `uniqueWithin` names, as a list. */
+declare const uniqueWithinOf: (field: Field) => readonly string[];
 /** Fields with `hasMany`: their value is a list of options, documents or files. */
 declare const isHasMany: (field: Field) => boolean;
 /** Whether a MIME type is one of `patterns` (`image/*` matches every image). */
@@ -1896,6 +2065,12 @@ interface AuditConfig {
     readonly values?: boolean;
     /** Failed logins within an hour that the dashboard warns about. Default 20. */
     readonly failedLogins?: number;
+    /**
+     * The part of the site an entry belongs to, from the request's context, e.g. its tenant
+     * (usually set by a plugin). Users whose role holds in a part only (`scoped`) see that part's
+     * entries; others see the chosen part's, or all.
+     */
+    readonly scope?: ((context: RequestContext) => string | null | undefined) | null;
 }
 /** A field that changed: values before and after, unless they are not kept. */
 interface AuditChange {
@@ -1943,6 +2118,8 @@ interface AuditFilter {
     /** ISO dates. */
     from?: string | null;
     to?: string | null;
+    /** Only entries of this part of the site (`scope`). */
+    scope?: string | null;
 }
 /** `POST <api>/admin/audit/verify`. */
 interface AuditVerification {
@@ -1979,12 +2156,14 @@ declare class AuditLog {
         email?: string | null;
         changes?: AuditChange[] | null;
         detail?: Record<string, unknown> | null;
+        /** The call's context, when it is not the request's. */
+        context?: RequestContext;
     }): Promise<void>;
     /**
      * A change to a document or global: what changed between `before` and `after`. Internal
      * collections (sessions, versions…) are not logged.
      */
-    content(config: CollectionConfig | GlobalConfig, global: boolean, action: string, after: Record<string, unknown> | undefined, before: Record<string, unknown> | undefined, user: AuthUser | null): Promise<void>;
+    content(config: CollectionConfig | GlobalConfig, global: boolean, action: string, after: Record<string, unknown> | undefined, before: Record<string, unknown> | undefined, user: AuthUser | null, context?: RequestContext): Promise<void>;
     /** Fields whose stored value changed. Hidden ones never (the password only as "changed"). */
     diff(fields: readonly Field[], before: Record<string, unknown>, after: Record<string, unknown>): AuditChange[];
     list(filter: AuditFilter, page?: number): Promise<AuditPage>;
@@ -2009,6 +2188,8 @@ declare class AuditLog {
         invalid: number;
         at: string;
     })[]>;
+    /** The part of the site a context is in (`scope`), or `null`. */
+    scopeOf(context: RequestContext | undefined): string | null;
     private sign;
     private lastVerification;
     private where;
@@ -2041,6 +2222,7 @@ declare const DEFAULT_PASSWORD_EMAILS: {
     resetPassword: PasswordEmailFn;
     invite: PasswordEmailFn;
     passwordChanged: PasswordEmailFn;
+    verifyEmail: PasswordEmailFn;
 };
 
 /**
@@ -2187,8 +2369,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. */
@@ -2200,11 +2385,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;
@@ -2290,15 +2479,26 @@ interface ContainerAdmin {
 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.
+     * instead of with the content, e.g. for redirects or forms settings. A label (e.g.
+     * `{ en: 'Shop', th: 'ร้านค้า' }`) lists it under a heading of that name, after the content.
      */
-    readonly group?: 'settings';
+    readonly group?: 'settings' | Label;
     readonly list?: CollectionListAdmin;
     /**
      * With `auth.rbac`: the relationship field to `users` that names a document's owner, e.g.
      * `author`, for roles given "own documents only". Default: who created it (`createdBy`).
      */
     readonly ownerField?: string;
+    /**
+     * Deleting asks more than "Are you sure?", for documents that take much with them (e.g. a
+     * tenant): `typeTitle` has the user type the document's title; `impact` is a path under the
+     * API, called with `?id=`, that returns `{ message }` (a label) saying what will be lost.
+     * Documents are then deleted one at a time, not from a selection.
+     */
+    readonly confirmDelete?: {
+        readonly typeTitle?: boolean;
+        readonly impact?: string;
+    };
 }
 interface CollectionListAdmin {
     /**
@@ -2515,6 +2715,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
@@ -2568,6 +2806,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;
@@ -2611,9 +2854,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`. */
@@ -2630,6 +2886,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
@@ -2738,6 +2998,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;
@@ -2799,6 +3066,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>[];
@@ -3199,6 +3468,10 @@ interface AdminField {
         after?: AdminComponentRef[];
         cell?: AdminComponentRef;
     };
+    /** A column of the list at first (`admin.column`). */
+    column?: boolean;
+    /** A relationship that offers no "Create" in place (`admin.allowCreate: false`). */
+    noCreate?: boolean;
     /** A field of an added type (`fieldTypes`), e.g. `color`; `type` is the base it's stored as. */
     customType?: string;
 }
@@ -3223,6 +3496,8 @@ interface AdminCollection {
     sidebar?: AdminComponentRef[];
     /** Listed under Settings in the menu (users, API keys, `admin.group: 'settings'`). */
     group?: 'settings';
+    /** Listed under a heading of its own in the menu (`admin.group` with a label). */
+    section?: Label;
     /** The list is a tree along this relationship field (`admin.list.tree`). */
     tree?: string;
     /** The list's default order (`admin.list.sort`). */
@@ -3236,6 +3511,11 @@ interface AdminCollection {
     };
     /** With `auth.rbac`: the field naming a document's owner (`createdBy` or `admin.ownerField`). */
     owner?: string;
+    /** Deleting asks to type the title, and says what goes too (`admin.confirmDelete`). */
+    confirmDelete?: {
+        typeTitle?: boolean;
+        impact?: string;
+    };
 }
 interface AdminGlobal {
     slug: string;
@@ -3420,6 +3700,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;
 /**
@@ -3437,4 +3738,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 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, 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 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 IncrementOptions, type InferCollection, type InferGlobal, type JobConfig, 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 MembersConfig, type MembersSignup, 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 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 };