@easy-cms/core 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -56,14 +56,6 @@ declare const anyone: Access;
 declare const isLoggedIn: Access;
 declare const isAdmin: Access;
 
-/** What a preview token opens: one document of a collection, or one global. */
-type PreviewTarget = {
-    readonly collection: string;
-    readonly id: string;
-} | {
-    readonly global: string;
-};
-
 interface Logger {
     info(message: string): void;
     warn(message: string): void;
@@ -335,959 +327,1056 @@ type Field = TextField | TextareaField | NumberField | BooleanField | DateField
 type FieldType = Field['type'];
 declare const FIELD_TYPES: readonly ["text", "textarea", "number", "boolean", "date", "email", "json", "select", "slug", "richText", "upload", "relationship", "array", "group", "blocks"];
 
-interface StoredFile {
-    readonly body: Uint8Array;
-    readonly size: number;
+/** What a preview token opens: one document of a collection, or one global. */
+type PreviewTarget = {
+    readonly collection: string;
+    readonly id: string;
+} | {
+    readonly global: string;
+};
+
+interface LoginArgs {
+    readonly email: string;
+    readonly password: string;
+    /** Client IP, used together with the email for rate limiting. */
+    readonly ip?: string | undefined;
 }
-/** Where uploaded files live. Keys are generated by Easy CMS: `<name>-<random>.<ext>`. */
-interface StorageAdapter {
-    readonly name: string;
-    /** Called once with the project root, before any other method. */
-    init?(args: {
-        cwd: string;
-    }): void | Promise<void>;
-    put(key: string, data: Uint8Array, options: {
-        contentType: string;
-    }): Promise<void>;
-    get(key: string): Promise<StoredFile | null>;
-    delete(key: string): Promise<void>;
+interface Session {
+    readonly user: AuthUser;
+    /** Signed session token, the value of the session cookie. */
+    readonly token: string;
+    /** Send back in the `X-CSRF-Token` header on cookie-authenticated writes. */
+    readonly csrfToken: string;
+    readonly expiresAt: string;
+}
+/** Login, logout and session verification. Available as `cms.auth`. */
+declare class Auth {
+    private readonly cms;
+    constructor(cms: EasyCMS);
+    private get db();
+    private get config();
+    /** Checks credentials and starts a session. Throws `UnauthorizedError` or `TooManyRequestsError`. */
+    login(args: LoginArgs): Promise<Session>;
+    /** Creates the first admin. Only works while there are no users. */
+    registerFirstUser(args: {
+        email: string;
+        password: string;
+        name?: string;
+    }): Promise<Session>;
+    hasUsers(): Promise<boolean>;
+    /** Ends the session for a signed token. Unknown tokens are ignored. */
+    logout(signedToken: string): Promise<void>;
     /**
-     * Public URL of a file, or `undefined` to serve it through the REST API
-     * (`<api>/media/file/<key>`), as the local adapter does.
+     * Returns the user for a signed session token, or for an API key (`ecms_…`, with `apiKey` set
+     * on the user), or `null` if it is invalid or expired.
      */
-    url?(key: string): string | undefined;
-}
-interface LocalStorageOptions {
-    /** Directory, relative to the project root. Default `uploads`. */
-    readonly dir?: string;
+    verify(signedToken: string | undefined | null): Promise<AuthUser | null>;
+    /** The CSRF token clients must echo for a signed session token. */
+    csrfFor(signedToken: string): string | undefined;
+    /** Starts a new session for a user, e.g. after they changed their own password. */
+    createSession(userId: ID): Promise<Session>;
+    /** Signs a user out everywhere. */
+    revokeSessions(userId: ID): Promise<void>;
+    /** The owner of an API key, limited by the key; `null` when unknown, expired or disabled. */
+    private verifyApiKey;
+    private startSession;
+    private findSession;
+    private toAuthUser;
+    private deleteExpiredSessions;
+    private windowStart;
+    private checkRateLimit;
+    private recordFailure;
+    private clearFailures;
 }
-/** Stores files on the local disk. Suitable for servers with a persistent filesystem. */
-declare function localStorage(options?: LocalStorageOptions): StorageAdapter;
 
-declare const WEBHOOK_EVENTS: readonly ["create", "update", "delete", "publish", "unpublish", "draft"];
-/**
- * `create`, `update`, `delete`: the stored document changed. `publish` / `unpublish`: its status
- * changed (sent with `create` or `update`). `draft`: only a draft was saved; what is live did not
- * change (collections with versions and drafts).
- */
-type WebhookEvent = (typeof WEBHOOK_EVENTS)[number];
-interface WebhookConfig {
-    /** Where to POST events. */
-    readonly url: string;
-    /** Events to send. Default: all. */
-    readonly events?: readonly WebhookEvent[];
-    /** Collections to send events for. Default: all; `[]` for none. */
-    readonly collections?: readonly string[];
-    /** Globals to send events for. Default: all; `[]` for none. */
-    readonly globals?: readonly string[];
-    /** Signs each body: `x-easy-cms-signature: sha256=<hex HMAC-SHA256 of the body>`. */
-    readonly secret?: string;
-    /** Extra request headers, e.g. a token the receiver checks. */
-    readonly headers?: Readonly<Record<string, string>>;
-}
-/** What a webhook receives as JSON. */
-interface WebhookPayload {
-    readonly event: WebhookEvent;
-    readonly collection?: string;
-    readonly global?: string;
-    readonly id?: ID;
-    /** The stored document (every locale, no hidden fields); for `delete`, as it was. */
-    readonly doc: Record<string, unknown>;
-    /** ISO time of the change. */
-    readonly timestamp: string;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type OptionValue<O> = O extends string ? O : O extends {
+    readonly value: infer V;
+} ? V : never;
+type SelectValue<F> = F extends {
+    readonly options: readonly (infer O extends SelectOption)[];
+} ? F extends {
+    readonly hasMany: true;
+} ? OptionValue<O>[] : OptionValue<O> : never;
+/** The built-in users collection as seen by the type system (hidden fields left out). */
+interface BuiltinUsersCollection {
+    readonly slug: 'users';
+    readonly fields: readonly [
+        {
+            readonly name: 'email';
+            readonly type: 'email';
+            readonly required: true;
+        },
+        {
+            readonly name: 'name';
+            readonly type: 'text';
+        },
+        {
+            readonly name: 'role';
+            readonly type: 'select';
+            readonly options: readonly string[];
+            readonly required: true;
+        },
+        {
+            readonly name: 'active';
+            readonly type: 'boolean';
+        }
+    ];
 }
-
-type Data$2 = Record<string, unknown>;
-type MaybePromise<T> = T | Promise<T>;
-type Operation = 'create' | 'update';
-interface HookBase {
-    /** The user the operation runs for; `null` for anonymous or trusted Local API calls. */
-    readonly user: AuthUser | null;
-    /** The Local API, e.g. to query other collections or trigger a revalidation. */
-    readonly cms: EasyCMS;
-    /** Slug of the collection or global. */
-    readonly slug: string;
+/** The built-in API keys collection (`apiKeys: true`); the key's hash is left out. */
+interface BuiltinApiKeysCollection {
+    readonly slug: 'api-keys';
+    readonly fields: readonly [
+        {
+            readonly name: 'name';
+            readonly type: 'text';
+            readonly required: true;
+        },
+        {
+            readonly name: 'permissions';
+            readonly type: 'json';
+        },
+        {
+            readonly name: 'expiresAt';
+            readonly type: 'date';
+        },
+        {
+            readonly name: 'prefix';
+            readonly type: 'text';
+        },
+        {
+            readonly name: 'user';
+            readonly type: 'relationship';
+            readonly to: 'users';
+        },
+        {
+            readonly name: 'lastUsedAt';
+            readonly type: 'date';
+        }
+    ];
 }
-type BeforeValidateHook = (args: HookBase & {
-    data: Data$2;
-    operation: Operation;
-    originalDoc?: Data$2;
-}) => MaybePromise<Data$2 | undefined>;
-type BeforeChangeHook = (args: HookBase & {
-    data: Data$2;
-    operation: Operation;
-    originalDoc?: Data$2;
-}) => MaybePromise<Data$2 | undefined>;
-type AfterChangeHook = (args: HookBase & {
-    doc: Data$2;
-    operation: Operation;
-    previousDoc?: Data$2;
-}) => MaybePromise<void>;
-type BeforeDeleteHook = (args: HookBase & {
-    id: ID;
-}) => MaybePromise<void>;
-type AfterDeleteHook = (args: HookBase & {
-    id: ID;
-    doc: Data$2;
-}) => MaybePromise<void>;
-type AfterReadHook = (args: HookBase & {
-    doc: Data$2;
-}) => MaybePromise<Data$2 | undefined>;
-interface CollectionHooks {
-    readonly beforeValidate?: readonly BeforeValidateHook[];
-    readonly beforeChange?: readonly BeforeChangeHook[];
-    readonly afterChange?: readonly AfterChangeHook[];
-    readonly beforeDelete?: readonly BeforeDeleteHook[];
-    readonly afterDelete?: readonly AfterDeleteHook[];
-    readonly afterRead?: readonly AfterReadHook[];
+/** `api-keys` when the config turns API keys on. */
+type ApiKeysOf<C extends Config> = C extends {
+    readonly apiKeys: true;
+} ? BuiltinApiKeysCollection : never;
+/** Every collection of a config, including the built-in ones. */
+type AllCollections<C extends Config> = NonNullable<C['collections']>[number] | BuiltinUsersCollection | BuiltinMediaCollection | ApiKeysOf<C>;
+/** The built-in media collection; its documents are typed as `MediaDocument`. */
+interface BuiltinMediaCollection {
+    readonly slug: 'media';
+    readonly fields: readonly [];
 }
-interface GlobalHooks {
-    readonly beforeChange?: readonly BeforeChangeHook[];
-    readonly afterChange?: readonly AfterChangeHook[];
-    readonly afterRead?: readonly AfterReadHook[];
+type CollectionBySlug<C extends Config, S> = Extract<AllCollections<C>, {
+    readonly slug: S;
+}>;
+/** Relationships are ids at depth 0 and documents when populated. */
+type RelationValue<C extends Config, S> = [CollectionBySlug<C, S>] extends [never] ? ID | Record<string, unknown> : ID | CollectionDocument<C, S & string>;
+interface MediaSize {
+    filename: string;
+    width: number;
+    height: number;
+    filesize: number;
+    url: string;
 }
-interface LocalizationConfig {
-    /** Content locales, e.g. `['th', 'en']`. */
-    readonly locales: readonly string[];
-    /** The locale used when none is given; its values also fill empty ones. Default: the first. */
-    readonly defaultLocale?: string;
-    /** Reads return the default locale's value when a locale's value is empty. Default true. */
-    readonly fallback?: boolean;
+/** A document of the built-in `media` collection, as returned by the API. */
+interface MediaDocument {
+    id: ID;
+    filename: string;
+    originalName?: string | null;
+    mimeType: string;
+    filesize: number;
+    width?: number | null;
+    height?: number | null;
+    alt?: string | null;
+    /** Public URL of the file. */
+    url: string;
+    /** Resized copies, when `upload.imageSizes` is set and sharp is installed. */
+    sizes: Record<string, MediaSize>;
+    createdAt: string;
+    updatedAt: string;
+    [field: string]: unknown;
 }
-/**
- * Where a document is shown on the site, for live preview in the admin: an absolute URL or a
- * path on the site's origin. Return `null` when the document has no page.
- */
-type PreviewURL = (args: {
-    readonly doc: Record<string, unknown>;
-    /** The content locale being edited (with `localization`), otherwise the admin locale. */
-    readonly locale: string;
-}) => string | null | undefined;
-interface VersionsConfig {
-    /** Versions kept per document; older ones are deleted. Default 50. */
-    readonly max?: number;
-}
-/** 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[];
-}
-interface CollectionConfig {
-    /** URL and table name. Lowercase letters, digits, `-` and `_`. */
-    readonly slug: string;
-    readonly labels?: {
-        readonly singular?: Label;
-        readonly plural?: Label;
-    };
-    /** Icon in the admin menu. Default `file-text`. */
-    readonly icon?: AdminIcon;
-    /**
-     * How the admin opens documents from the list: `drawer` slides a panel over the list, handy
-     * for small collections (categories, tags). Default `page`. Collections with drafts, versions
-     * or live preview always use the page.
-     */
-    readonly editIn?: 'page' | 'drawer';
-    readonly fields: readonly Field[];
-    /** Top-level field shown as the document title in the admin UI. */
-    readonly useAsTitle?: string;
-    /** Adds a `status` field (`draft` | `published`). */
+type FieldValue<F extends Field, C extends Config = Config> = F extends {
+    readonly type: 'text' | 'textarea' | 'email' | 'slug' | 'date';
+} ? string : F extends {
+    readonly type: 'number';
+} ? number : F extends {
+    readonly type: 'boolean';
+} ? boolean : F extends {
+    readonly type: 'json';
+} ? unknown : F extends {
+    readonly type: 'select';
+} ? SelectValue<F> : F extends {
+    readonly type: 'richText';
+} ? RichTextDocument : F extends {
+    readonly type: 'upload';
+} ? ID | MediaDocument : F extends {
+    readonly type: 'relationship';
+    readonly to: infer S;
+} ? F extends {
+    readonly hasMany: true;
+} ? RelationValue<C, S>[] : RelationValue<C, S> : F extends {
+    readonly type: 'array';
+    readonly fields: infer Sub extends readonly Field[];
+} ? Simplify<FieldsValue<Sub, C> & {
+    id: string;
+}>[] : F extends {
+    readonly type: 'group';
+    readonly fields: infer Sub extends readonly Field[];
+} ? FieldsValue<Sub, C> : F extends {
+    readonly type: 'blocks';
+    readonly blocks: infer B extends readonly Block[];
+} ? BlockValue<B[number], C>[] : never;
+/** One row of a `blocks` field: the block's fields plus `id` and `blockType` (distributes over kinds). */
+type BlockValue<B, C extends Config> = B extends {
+    readonly slug: infer S;
+    readonly fields: infer Sub extends readonly Field[];
+} ? Simplify<FieldsValue<Sub, C> & {
+    id: string;
+    blockType: S;
+}> : never;
+type BlockInput<B> = B extends {
+    readonly slug: infer S;
+    readonly fields: infer Sub extends readonly Field[];
+} ? Simplify<FieldsInput<Sub> & {
+    id?: string;
+    blockType: S;
+}> : never;
+type Visible<Fs extends readonly Field[]> = Exclude<Fs[number], {
+    readonly hidden: true;
+}>;
+/** Always set when read: required fields, and lists and groups (empty `[]` / `{}` otherwise). */
+type Present = {
+    readonly required: true;
+} | {
+    readonly type: 'array' | 'blocks' | 'group';
+} | {
+    readonly hasMany: true;
+};
+type RequiredFields<Fs extends readonly Field[]> = Extract<Visible<Fs>, Present>;
+type OptionalFields<Fs extends readonly Field[]> = Exclude<Visible<Fs>, Present>;
+/** The shape of the data described by a list of fields. */
+type FieldsValue<Fs extends readonly Field[], C extends Config = Config> = Simplify<{
+    -readonly [F in RequiredFields<Fs> as F['name']]: FieldValue<F, C>;
+} & {
+    -readonly [F in OptionalFields<Fs> as F['name']]?: FieldValue<F, C> | null;
+}>;
+type SystemFields<T extends {
     readonly drafts?: boolean;
+}> = {
+    id: ID;
+    createdAt: string;
+    updatedAt: string;
+} & (T extends {
+    readonly drafts: true;
+} ? {
+    status: 'draft' | 'published';
+} : unknown);
+type InferCollection<T extends CollectionConfig, C extends Config = Config> = Simplify<SystemFields<T> & FieldsValue<T['fields'], C>>;
+type InferGlobal<T extends GlobalConfig, C extends Config = Config> = Simplify<
+/** `null` until the global is saved for the first time. */
+{
+    updatedAt: string | null;
+} & (T extends {
+    readonly drafts: true;
+} ? {
+    status: 'draft' | 'published';
+} : unknown) & FieldsValue<T['fields'], C>>;
+type CollectionSlug<C extends Config> = NonNullable<C['collections']>[number]['slug'] | 'users' | 'media' | ApiKeysOf<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>;
+/** Data type of a global, e.g. `GlobalDocument<typeof config, 'site'>`. */
+type GlobalDocument<C extends Config, S extends GlobalSlug<C>> = InferGlobal<Extract<NonNullable<C['globals']>[number], {
+    readonly slug: S;
+}>, C>;
+type InputValue<F extends Field> = F extends {
+    readonly type: 'relationship';
+} ? F extends {
+    readonly hasMany: true;
+} ? readonly ID[] : ID : F extends {
+    readonly type: 'select';
+    readonly hasMany: true;
+} ? Readonly<SelectValue<F>> : F extends {
+    readonly type: 'upload';
+} ? ID : F extends {
+    readonly type: 'date';
+} ? string | Date : F extends {
+    readonly type: 'array';
+    readonly fields: infer Sub extends readonly Field[];
+} ? readonly Simplify<FieldsInput<Sub> & {
+    id?: string;
+}>[] : F extends {
+    readonly type: 'group';
+    readonly fields: infer Sub extends readonly Field[];
+} ? FieldsInput<Sub> : 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). */
+type NeedsInput<F extends Field> = F extends {
+    readonly required: true;
+} ? F extends {
+    readonly defaultValue: unknown;
+} ? never : F extends {
+    readonly type: 'slug';
+    readonly from: string;
+} ? never : F : never;
+type FieldsInput<Fs extends readonly Field[]> = Simplify<{
+    -readonly [F in NeedsInput<Visible<Fs>> as F['name']]: InputValue<F>;
+} & {
+    -readonly [F in Exclude<Visible<Fs>, NeedsInput<Visible<Fs>>> as F['name']]?: InputValue<F> | null;
+}>;
+type StatusInput<T> = T extends {
+    readonly drafts: true;
+} ? {
+    status?: 'draft' | 'published';
+} : unknown;
+/** Users are created with a password, which is hashed and never returned. */
+type PasswordInput<S, Required extends boolean> = S extends 'users' ? Required extends true ? {
+    password: string;
+} : {
+    password?: string;
+} : unknown;
+/** Data accepted by `create`, e.g. `CreateInput<typeof config, 'posts'>`. */
+type CreateInput<C extends Config, S extends CollectionSlug<C>> = Simplify<FieldsInput<CollectionBySlug<C, S>['fields']> & StatusInput<CollectionBySlug<C, S>> & PasswordInput<S, true>>;
+/** Data accepted by `update`: any subset of `CreateInput`. */
+type UpdateInput<C extends Config, S extends CollectionSlug<C>> = Partial<CreateInput<C, S>>;
+/** Data accepted by `updateGlobal`. */
+type GlobalInput<C extends Config, S extends GlobalSlug<C>> = Partial<Simplify<FieldsInput<Extract<NonNullable<C['globals']>[number], {
+    readonly slug: S;
+}>['fields']> & StatusInput<Extract<NonNullable<C['globals']>[number], {
+    readonly slug: S;
+}>>>>;
+
+interface StoredFile {
+    readonly body: Uint8Array;
+    readonly size: number;
+}
+/** Where uploaded files live. Keys are generated by Easy CMS: `<name>-<random>.<ext>`. */
+interface StorageAdapter {
+    readonly name: string;
+    /** Called once with the project root, before any other method. */
+    init?(args: {
+        cwd: string;
+    }): void | Promise<void>;
+    put(key: string, data: Uint8Array, options: {
+        contentType: string;
+    }): Promise<void>;
+    get(key: string): Promise<StoredFile | null>;
+    delete(key: string): Promise<void>;
     /**
-     * Keep a snapshot of every save, to view history and restore. With `drafts`, a draft saved
-     * on a published document is kept as a version and the published document stays live until
-     * it is published again.
+     * Public URL of a file, or `undefined` to serve it through the REST API
+     * (`<api>/media/file/<key>`), as the local adapter does.
      */
-    readonly versions?: boolean | VersionsConfig;
-    /** Allow scheduling publish/unpublish for a later time (needs `drafts`). */
-    readonly schedule?: boolean;
-    /** Live preview: the page that shows a document, e.g. `({ doc }) => \`/posts/${doc.slug}\``. */
-    readonly preview?: PreviewURL;
-    readonly access?: CollectionAccess;
-    readonly hooks?: CollectionHooks;
-    /** Custom admin components. */
-    readonly admin?: ContainerAdmin;
+    url?(key: string): string | undefined;
 }
-interface GlobalConfig {
-    readonly slug: string;
-    readonly label?: Label;
-    /** Icon in the admin menu. Default `settings`. */
-    readonly icon?: AdminIcon;
-    readonly fields: readonly Field[];
-    readonly drafts?: boolean;
-    /** Keep a snapshot of every save. See `CollectionConfig.versions`. */
-    readonly versions?: boolean | VersionsConfig;
-    /** Allow scheduling publish/unpublish for a later time (needs `drafts`). */
-    readonly schedule?: boolean;
-    /** Live preview: the page that shows the global. See `CollectionConfig.preview`. */
-    readonly preview?: PreviewURL;
-    readonly access?: GlobalAccess;
-    readonly hooks?: GlobalHooks;
-    /** Custom admin components. */
-    readonly admin?: ContainerAdmin;
+interface LocalStorageOptions {
+    /** Directory, relative to the project root. Default `uploads`. */
+    readonly dir?: string;
 }
-type AdminLocale = 'en' | 'th';
-/** Icons a collection or global can show in the admin menu ([Lucide](https://lucide.dev) names). */
-declare const ADMIN_ICONS: readonly ["file-text", "newspaper", "book-open", "notebook", "folder", "tag", "tags", "image", "images", "video", "music", "file", "users", "user", "building", "store", "shopping-bag", "shopping-cart", "package", "box", "calendar", "calendar-days", "map-pin", "globe", "house", "layout-grid", "layers", "star", "heart", "message-square", "mail", "phone", "briefcase", "graduation-cap", "utensils", "car", "settings", "sliders-horizontal", "palette", "megaphone", "bell", "link", "quote", "circle-help", "award", "ticket", "camera"];
-type AdminIcon = (typeof ADMIN_ICONS)[number];
-/** Your or your client's brand in the admin UI. */
-interface AdminBrand {
-    /** Shown in the menu, on the login page and in the browser tab. Default "Easy CMS". */
-    readonly name?: string;
-    /** Logo URL: a path on your site (`/logo.svg`) or an `https://` address. */
-    readonly logo?: string;
-    /** Main color as `#rrggbb`; lighter and darker shades are derived from it. */
-    readonly color?: string;
+/** Stores files on the local disk. Suitable for servers with a persistent filesystem. */
+declare function localStorage(options?: LocalStorageOptions): StorageAdapter;
+
+declare const DEFAULT_MAX_VERSIONS = 50;
+/** One saved state of a document or global. */
+interface VersionSummary {
+    readonly id: ID;
+    /** `draft` or `published` with drafts enabled, otherwise `null`. */
+    readonly status: 'draft' | 'published' | null;
+    /** The newest version: the document's current editable state. */
+    readonly latest: boolean;
+    /** Who saved it (user id), or `null` for saves without a user (scripts, seeds). */
+    readonly author: ID | null;
+    readonly createdAt: string;
 }
-interface AdminConfig {
-    /** Where the admin UI is served. Default `/admin`. */
-    readonly path?: string;
-    /** Default admin UI language. Default `en`. */
-    readonly locale?: AdminLocale;
-    /** Name, logo and color of the admin UI. */
-    readonly brand?: AdminBrand;
+interface Version<T = Record<string, unknown>> extends VersionSummary {
+    /** The document as it was saved (hidden fields such as password hashes are never kept). */
+    readonly data: T;
+}
+
+type Data$2 = Record<string, unknown>;
+type Slug<C extends Config> = string extends CollectionSlug<C> ? string : CollectionSlug<C>;
+type GSlug<C extends Config> = string extends GlobalSlug<C> ? string : GlobalSlug<C>;
+type Doc<C extends Config, S> = string extends CollectionSlug<C> ? RawDocument : CollectionDocument<C, S & CollectionSlug<C>>;
+type Create<C extends Config, S> = string extends CollectionSlug<C> ? Data$2 : CreateInput<C, S & CollectionSlug<C>>;
+type Update<C extends Config, S> = string extends CollectionSlug<C> ? Data$2 : UpdateInput<C, S & CollectionSlug<C>>;
+type GDoc<C extends Config, S> = string extends GlobalSlug<C> ? Data$2 : GlobalDocument<C, S & GlobalSlug<C>>;
+type GInput<C extends Config, S> = string extends GlobalSlug<C> ? Data$2 : GlobalInput<C, S & GlobalSlug<C>>;
+interface AccessOptions {
     /**
-     * The public site, for the admin's "View site" link: a path (`/`) or an `https://` URL.
-     * Default `/` with Nuxt and Next.js; none with the standalone server.
+     * The Local API trusts its caller and skips access rules by default.
+     * Pass `false` (with `user`) to apply them, as the REST API does.
      */
-    readonly siteUrl?: string;
+    readonly overrideAccess?: boolean;
+    /** The user to check access for. `null` = not logged in. */
+    readonly user?: AuthUser | null;
+}
+interface DepthOptions extends AccessOptions {
+    /** How many levels of relationships to populate. Default 1, maximum 3. */
+    readonly depth?: number;
     /**
-     * Order of collections in the admin menu, by slug, e.g. `['posts', 'categories', 'media']`.
-     * Collections not listed follow in config order, with the media library last.
+     * With `localization`: the locale to read, and for writes the locale the data is in. Default:
+     * the default locale. `'all'` reads (and writes) localized fields as `{ [locale]: value }`.
      */
-    readonly menu?: readonly string[];
+    readonly locale?: string;
+}
+interface ReadOptions extends DepthOptions {
     /**
-     * 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
-     * package export (`'@easy-cms/plugin-seo/admin'`) or a file path relative to the project root
-     * (`'./admin/color-picker.js'`), resolved on the server. A module must be one self-contained ES
-     * module file. Remote URLs are not allowed.
+     * Include drafts. By default only published documents of collections with
+     * `drafts: true` are returned, including when populating relationships (FR-DRF-04).
      */
-    readonly modules?: readonly string[];
-}
-interface ImageSize {
-    /** Key in `media.sizes`, e.g. `thumbnail`. */
-    readonly name: string;
-    readonly width: number;
-    readonly height?: number;
-    /** How to fit when both width and height are set. Default `cover`. */
-    readonly fit?: 'cover' | 'contain' | 'inside';
-}
-interface UploadConfig {
-    /** Directory for uploaded files with the default local storage, relative to the project root. Default `uploads`. */
-    readonly dir?: string;
-    /** Maximum file size in bytes. Default 10 MB. */
-    readonly maxFileSize?: number;
-    /** Allowed MIME types, detected from file contents. `image/*` style wildcards are allowed. */
-    readonly mimeTypes?: readonly string[];
-    /** Where files are stored. Default: local disk in `dir`. */
-    readonly storage?: StorageAdapter;
-    /** Resized copies generated for images when `sharp` is installed. */
-    readonly imageSizes?: readonly ImageSize[];
+    readonly draft?: boolean;
+    /** Use the default locale's value when a localized value is empty. Default: `localization.fallback`. */
+    readonly fallbackLocale?: boolean;
 }
-interface RoutesConfig {
-    /** Where the REST API is served. Default `/api/cms`. */
-    readonly api?: string;
+interface FindOptions extends ReadOptions {
+    readonly where?: Where;
+    /** Field path, `-` prefix for descending. Default `-createdAt`. */
+    readonly sort?: string | readonly string[];
+    /** Default 10. `0` returns every document. */
+    readonly limit?: number;
+    /** 1-based. Default 1. */
+    readonly page?: number;
 }
-interface AuthConfig {
-    /** Roles a user can have. Must include `admin`. Default `['admin', 'editor']`. */
-    readonly roles?: readonly string[];
-    /** Session lifetime in seconds. Default 7 days. */
-    readonly tokenExpiration?: number;
-    /** Failed logins allowed per email (and IP) within `lockWindow`. Default 5. */
-    readonly maxLoginAttempts?: number;
-    /** Window for `maxLoginAttempts`, in seconds. Default 15 minutes. */
-    readonly lockWindow?: number;
+interface CreateEasyCMSOptions {
+    /** Project root. Default `process.cwd()`. */
+    readonly cwd?: string;
     /**
-     * Origins allowed to send cookie-authenticated requests, besides the API's own origin.
-     * Needed when the admin or frontend is served from another origin, or behind a proxy that rewrites the host.
+     * 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.
      */
-    readonly trustedOrigins?: readonly string[];
+    readonly scheduler?: boolean;
+    /** Default `verify` when `NODE_ENV=production`, otherwise `push`. */
+    readonly schema?: SchemaMode;
+    readonly logger?: Logger;
+    readonly interactive?: boolean;
 }
-/** What an endpoint's handler receives. */
-interface EndpointRequest {
-    readonly request: Request;
-    readonly url: URL;
-    /** Values of `:name` segments in the endpoint's path. */
-    readonly params: Readonly<Record<string, string>>;
-    /** The logged-in user (session cookie or Bearer token), or `null`. */
-    readonly user: AuthUser | null;
-    /** 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). */
-    json(): Promise<Record<string, unknown>>;
+/** Connects to the database and returns the Local API. */
+declare function createEasyCMS<const C extends Config>(config: C, options?: CreateEasyCMSOptions): Promise<EasyCMS<C>>;
+/** A scheduled publish or unpublish. */
+interface ScheduledJob {
+    readonly id: ID;
+    readonly action: 'publish' | 'unpublish';
+    /** ISO time the job runs at (or after). */
+    readonly runAt: string;
+    readonly state: 'pending' | 'done' | 'failed';
+    readonly error: string | null;
+    readonly author: ID | null;
 }
-/**
- * A custom REST endpoint, served under `routes.api`. Writes from the browser pass the same
- * CSRF check as the built-in endpoints.
- */
-interface Endpoint {
+declare class EasyCMS<C extends Config = Config> {
+    readonly config: ResolvedConfig;
+    readonly db: Database;
+    readonly logger: Logger;
+    /** Login, logout and session checks. */
+    readonly auth: Auth;
+    /** Where uploaded files are stored. */
+    readonly storage: StorageAdapter;
+    /** Project root: relative paths in the config (e.g. `admin.modules`) start here. */
+    readonly cwd: string;
+    private readonly versions;
+    private readonly webhooks;
+    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>;
+    count<S extends Slug<C>>(collection: S, options?: {
+        where?: Where;
+        draft?: boolean;
+        locale?: string;
+    } & AccessOptions): Promise<number>;
+    create<S extends Slug<C>>(collection: S, data: Create<C, S>, options?: DepthOptions): Promise<Doc<C, S>>;
+    /**
+     * Stores a file and creates its `media` document (FR-UPL). The type is detected from
+     * the contents; images get width/height, and resized copies when `sharp` is installed.
+     */
+    upload(file: {
+        data: Uint8Array;
+        name: string;
+    }, data?: Record<string, unknown>, options?: DepthOptions): Promise<MediaDocument>;
+    /**
+     * Creates an API key (needs `apiKeys: true`) and returns it once: only a hash is stored.
+     * With access enforced the key belongs to `user`; trusted calls name the owner in `data.user`.
+     */
+    createApiKey(data: {
+        name: string;
+        permissions?: ApiKeyPermissions;
+        expiresAt?: string | Date | null;
+        user?: ID;
+    }, options?: AccessOptions): Promise<{
+        key: string;
+        doc: Record<string, unknown>;
+    }>;
+    /** Public URL of a stored file. */
+    mediaURL(key: string): string;
+    update<S extends Slug<C>>(collection: S, id: ID, data: Update<C, S>, options?: DepthOptions): Promise<Doc<C, S>>;
+    /**
+     * 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;
+     * this is how to unpublish it.
+     */
+    unpublish<S extends Slug<C>>(collection: S, id: ID, options?: DepthOptions): Promise<Doc<C, S>>;
+    /** Throws away the unpublished draft of a published document, going back to what is live. */
+    discardDraft<S extends Slug<C>>(collection: S, id: ID, options?: DepthOptions): Promise<Doc<C, S>>;
+    /** Saved versions of a document, newest first. Needs update access to the document. */
+    findVersions<S extends Slug<C>>(collection: S, id: ID, options?: AccessOptions & {
+        limit?: number;
+        page?: number;
+    }): Promise<PaginatedDocs<VersionSummary>>;
+    /** One saved version with the document as it was then. */
+    findVersion<S extends Slug<C>>(collection: S, id: ID, versionId: ID, options?: DepthOptions): Promise<Version<Doc<C, S>> | null>;
+    /**
+     * Makes an old version the current content, as a new version. With drafts it is restored as
+     * a draft (publish it to put it live); access, hooks and validation run as for `update`.
+     */
+    restoreVersion<S extends Slug<C>>(collection: S, id: ID, versionId: ID, options?: DepthOptions): Promise<Doc<C, S>>;
+    /**
+     * Live preview: the document as it would be read if `data` were saved on top of its current
+     * state (or as a new document when `id` is `null`), with relationships populated and
+     * `afterRead` hooks applied. Nothing is written. Also returns the page URL from `preview`.
+     */
+    preview<S extends Slug<C>>(collection: S, id: ID | null, data: Record<string, unknown>, options?: DepthOptions): Promise<LivePreview<Doc<C, S>>>;
+    /**
+     * A token that lets a page read one document's current draft for a while (default one hour),
+     * without a login: `GET /api/cms/:collection/:id?preview=<token>`. The admin adds one to the
+     * preview URL as `easy-cms-preview`, for sites on another origin.
+     */
+    createPreviewToken(target: {
+        collection: string;
+        id: ID;
+    } | {
+        global: string;
+    }, options?: {
+        expiresIn?: number;
+    }): string;
+    /** What a preview token opens, or `null` when it is invalid or expired. */
+    verifyPreviewToken(token: string | null | undefined): (PreviewTarget & {
+        expiresAt: number;
+    }) | null;
+    /** Live preview of a global. See `preview`. */
+    previewGlobal<S extends GSlug<C>>(slug: S, data: Record<string, unknown>, options?: DepthOptions): Promise<LivePreview<GDoc<C, S>>>;
+    /** Coerces preview input like a save would, keeping values that would fail validation. */
+    private previewDoc;
+    private previewURL;
+    private versionTarget;
+    private updateDocument;
+    delete<S extends Slug<C>>(collection: S, id: ID, options?: AccessOptions): Promise<Doc<C, S>>;
+    findGlobal<S extends GSlug<C>>(slug: S, options?: ReadOptions): Promise<GDoc<C, S>>;
+    updateGlobal<S extends GSlug<C>>(slug: S, data: GInput<C, S>, options?: DepthOptions): Promise<GDoc<C, S>>;
+    /** Takes a global off the site (`status: 'draft'`). See `unpublish`. */
+    unpublishGlobal<S extends GSlug<C>>(slug: S, options?: DepthOptions): Promise<GDoc<C, S>>;
+    /** Throws away the unpublished draft of a published global. */
+    discardGlobalDraft<S extends GSlug<C>>(slug: S, options?: DepthOptions): Promise<GDoc<C, S>>;
+    /** Saved versions of a global, newest first. Needs update access. */
+    findGlobalVersions<S extends GSlug<C>>(slug: S, options?: AccessOptions & {
+        limit?: number;
+        page?: number;
+    }): Promise<PaginatedDocs<VersionSummary>>;
+    findGlobalVersion<S extends GSlug<C>>(slug: S, versionId: ID, options?: DepthOptions): Promise<Version<GDoc<C, S>> | null>;
+    /** Makes an old version of a global current (as a draft when the global has drafts). */
+    restoreGlobalVersion<S extends GSlug<C>>(slug: S, versionId: ID, options?: DepthOptions): Promise<GDoc<C, S>>;
+    private globalVersionTarget;
+    /** The global's pending draft when it has one (see `withDrafts`), otherwise `saved`. */
+    private globalDraft;
+    private saveGlobal;
     /**
-     * Path under the API, e.g. `/seo/generate` or `/stats/:collection`. The first segment must
-     * not be a collection slug or one of `users`, `globals`, `admin`, `jobs`.
+     * What `user` may do with one document. Resolves `where`-style access
+     * against the document, so the admin UI can hide actions precisely.
      */
-    readonly path: string;
-    readonly method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    documentPermissions(collection: Slug<C>, id: ID, user: AuthUser | null): Promise<{
+        update: boolean;
+        delete: boolean;
+    }>;
+    /** Closes the database connection. */
     /**
-     * Returns a `Response`, or a value that is sent as JSON. Throw an Easy CMS error
-     * (`UnauthorizedError`, `ForbiddenError`, `ValidationError`, `NotFoundError`) for error responses.
+     * Waits until webhook deliveries in progress are done. Call it before a serverless function
+     * returns, which may otherwise stop them.
      */
-    readonly handler: (request: EndpointRequest) => MaybePromise<unknown>;
-}
-/** Receives the config and returns a modified copy. Runs before validation. */
-type Plugin = (config: Config) => MaybePromise<Config>;
-interface Config {
-    /** Signs sessions. At least 32 characters; read it from `process.env.EASY_CMS_SECRET`. */
-    readonly secret: string;
-    readonly db: DatabaseAdapter;
+    flushWebhooks(): Promise<void>;
+    destroy(): Promise<void>;
+    private schedulerTimer;
+    private running;
+    /** Runs `runJobs` every `interval` ms in this process (`createEasyCMS` does this by default). */
+    startScheduler(interval?: number): void;
     /**
-     * Public origin of the app, e.g. `https://example.com`. When set, media URLs are absolute
-     * so frontends on other origins can use them. Default: relative URLs.
+     * Runs due scheduled publishes and unpublishes, and retries failed webhook deliveries. What the
+     * scheduler and the cron endpoint (`GET <api>/jobs/run`) call.
      */
-    readonly serverURL?: string;
+    runJobs(now?: Date): Promise<{
+        ran: number;
+        failed: number;
+        webhooks: {
+            sent: number;
+            failed: number;
+        };
+    }>;
     /**
-     * Origins whose browser code may call the REST API (CORS), e.g. a Vite or React app on
-     * another origin. `'*'` allows any origin for anonymous requests. Origins in
-     * `auth.trustedOrigins` are always allowed, with cookies. Default: none.
+     * Tries webhook deliveries that are due for another attempt. Deliveries are kept in the
+     * database until they succeed, so they survive restarts.
      */
-    readonly cors?: readonly string[] | '*';
+    retryWebhooks(now?: Date): Promise<{
+        sent: number;
+        failed: number;
+    }>;
+    /** Webhook deliveries until they succeed, stored in `webhook-deliveries`. */
+    private webhookQueue;
     /**
-     * Lets a cron service run due scheduled jobs: `GET <api>/jobs/run` with
-     * `Authorization: Bearer <cronSecret>`. Default: the `CRON_SECRET` environment variable (the
-     * convention of Vercel Cron). Logged-in admins can always run jobs.
+     * Publishes or unpublishes documents whose scheduled time has come. Safe to call often, e.g.
+     * from a cron job (`GET <api>/jobs/run`) where no process keeps running.
      */
-    readonly cronSecret?: string;
-    /** Endpoints notified when content changes, e.g. to rebuild a static site. */
-    readonly webhooks?: readonly WebhookConfig[];
-    /** Content in several languages: fields with `localized: true` hold one value per locale. */
-    readonly localization?: LocalizationConfig | null;
-    readonly routes?: RoutesConfig;
-    readonly admin?: AdminConfig;
-    readonly upload?: UploadConfig;
-    readonly auth?: AuthConfig;
+    runScheduled(now?: Date): Promise<{
+        ran: number;
+        failed: number;
+    }>;
+    /** Schedules a publish or unpublish, replacing a pending job with the same action. */
+    schedule<S extends Slug<C>>(collection: S, id: ID, job: {
+        action: 'publish' | 'unpublish';
+        at: Date | string;
+    }, options?: AccessOptions): Promise<ScheduledJob>;
+    /** Pending jobs of a document, soonest first. */
+    scheduled<S extends Slug<C>>(collection: S, id: ID, options?: AccessOptions): Promise<ScheduledJob[]>;
+    cancelSchedule<S extends Slug<C>>(collection: S, id: ID, jobId: ID, options?: AccessOptions): Promise<void>;
+    scheduleGlobal<S extends GSlug<C>>(slug: S, job: {
+        action: 'publish' | 'unpublish';
+        at: Date | string;
+    }, options?: AccessOptions): Promise<ScheduledJob>;
+    scheduledGlobal<S extends GSlug<C>>(slug: S, options?: AccessOptions): Promise<ScheduledJob[]>;
+    cancelGlobalSchedule<S extends GSlug<C>>(slug: S, jobId: ID, options?: AccessOptions): Promise<void>;
+    private scheduleTarget;
+    private globalScheduleTarget;
+    private addJob;
     /**
-     * Collections. A collection with slug `users` adds fields, access or hooks
-     * to the built-in users collection.
+     * The next pending jobs across all collections and globals, soonest first; with access
+     * enforced, only those the user may update.
      */
-    readonly collections?: readonly CollectionConfig[];
-    readonly globals?: readonly GlobalConfig[];
-    /** Custom REST endpoints, e.g. from plugins. */
-    readonly endpoints?: readonly Endpoint[];
-    readonly plugins?: readonly Plugin[];
-}
-/** The config after plugins ran, validation passed and defaults were applied. */
-interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes' | 'admin' | 'upload' | 'auth' | 'collections' | 'globals' | 'endpoints' | 'plugins'> {
-    readonly cors: readonly string[] | '*';
-    /** `null` without localization. */
-    readonly localization: Required<LocalizationConfig> | null;
-    readonly routes: Required<RoutesConfig>;
-    readonly admin: Required<AdminConfig>;
-    readonly upload: Required<Omit<UploadConfig, 'storage'>> & Pick<UploadConfig, 'storage'>;
-    readonly auth: Required<AuthConfig>;
-    readonly collections: readonly CollectionConfig[];
-    readonly globals: readonly GlobalConfig[];
-    readonly endpoints: readonly Endpoint[];
-}
-/**
- * Declares the Easy CMS config. Returns it unchanged, keeping literal types
- * so document types can be inferred from it.
- */
-declare function defineConfig<const TConfig extends Config>(config: TConfig): TConfig;
-
-type Simplify<T> = {
-    [K in keyof T]: T[K];
-} & {};
-type OptionValue<O> = O extends string ? O : O extends {
-    readonly value: infer V;
-} ? V : never;
-type SelectValue<F> = F extends {
-    readonly options: readonly (infer O extends SelectOption)[];
-} ? F extends {
-    readonly hasMany: true;
-} ? OptionValue<O>[] : OptionValue<O> : never;
-/** The built-in users collection as seen by the type system (hidden fields left out). */
-interface BuiltinUsersCollection {
-    readonly slug: 'users';
-    readonly fields: readonly [
-        {
-            readonly name: 'email';
-            readonly type: 'email';
-            readonly required: true;
-        },
-        {
-            readonly name: 'name';
-            readonly type: 'text';
-        },
-        {
-            readonly name: 'role';
-            readonly type: 'select';
-            readonly options: readonly string[];
-            readonly required: true;
-        },
-        {
-            readonly name: 'active';
-            readonly type: 'boolean';
-        }
-    ];
-}
-/** Every collection of a config, including the built-in users collection. */
-type AllCollections<C extends Config> = NonNullable<C['collections']>[number] | BuiltinUsersCollection | BuiltinMediaCollection;
-/** The built-in media collection; its documents are typed as `MediaDocument`. */
-interface BuiltinMediaCollection {
-    readonly slug: 'media';
-    readonly fields: readonly [];
-}
-type CollectionBySlug<C extends Config, S> = Extract<AllCollections<C>, {
-    readonly slug: S;
-}>;
-/** Relationships are ids at depth 0 and documents when populated. */
-type RelationValue<C extends Config, S> = [CollectionBySlug<C, S>] extends [never] ? ID | Record<string, unknown> : ID | CollectionDocument<C, S & string>;
-interface MediaSize {
-    filename: string;
-    width: number;
-    height: number;
-    filesize: number;
-    url: string;
+    upcomingJobs(options?: AccessOptions & {
+        limit?: number;
+    }): Promise<(ScheduledJob & {
+        collection?: string;
+        global?: string;
+        doc: ID;
+    })[]>;
+    private pendingJobs;
+    private removeJob;
+    /** @internal */
+    collection(slug: string): CollectionConfig;
+    private global;
+    /** Refuses what a request's API key does not allow (see `ApiKeyPermissions`). */
+    private checkKey;
+    /** The query constraint read access adds, or `undefined` when there is none. Throws when denied. */
+    private readWhere;
+    private checkDocumentAccess;
+    private checkGlobalAccess;
+    private fieldChecker;
+    /** Runs afterRead hooks, populates relationships and removes what the caller may not see. */
+    private output;
+    /** Creates a document: access, input filtering, hooks, validation, then afterChange. */
+    private createDocument;
+    /** The locale for an operation; `undefined` without localization. Throws on unknown locales. */
+    private localeOf;
+    /** Stored localized maps → the values of the requested locale. */
+    private pick;
+    /** Input for one locale → stored localized maps, keeping the other locales from `current`. */
+    private toMaps;
+    /** Makes `where` match localized fields in the operation's locale. */
+    private whereFor;
+    /** Drafts are kept as versions (instead of unpublishing) when both are enabled. */
+    private separateDrafts;
+    /** 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;
+    /** Records a version after a save, when the collection or global keeps versions. */
+    private saveVersion;
+    private hookArgs;
+    /**
+     * Runs hooks that may replace a value, passed as `data` (before hooks) or `doc` (afterRead).
+     * Returning `undefined` keeps the value; a throw cancels the operation.
+     */
+    private transform;
+    /** Runs hooks after the change is saved: failures are logged, never undo the save (NFR-REL-03). */
+    private notify;
+    /** Writes resized copies with sharp, when installed and configured. */
+    private resizeImage;
+    /** Validates, checks uniqueness and references. Returns clean data or throws `ValidationError`. */
+    private prepare;
+    /** Refuses changes that would leave no active admin (and lock everyone out). */
+    private guardLastAdmin;
+    private makeSlugsUnique;
+    private checkUnique;
+    private isTaken;
+    private checkReferences;
 }
-/** A document of the built-in `media` collection, as returned by the API. */
-interface MediaDocument {
-    id: ID;
-    filename: string;
-    originalName?: string | null;
-    mimeType: string;
-    filesize: number;
-    width?: number | null;
-    height?: number | null;
-    alt?: string | null;
-    /** Public URL of the file. */
-    url: string;
-    /** Resized copies, when `upload.imageSizes` is set and sharp is installed. */
-    sizes: Record<string, MediaSize>;
-    createdAt: string;
-    updatedAt: string;
-    [field: string]: unknown;
+/** A document as live preview shows it, and the page to show it on. */
+interface LivePreview<T> {
+    readonly doc: T;
+    /** From the collection's `preview` function; `null` without one. */
+    readonly url: string | null;
 }
-type FieldValue<F extends Field, C extends Config = Config> = F extends {
-    readonly type: 'text' | 'textarea' | 'email' | 'slug' | 'date';
-} ? string : F extends {
-    readonly type: 'number';
-} ? number : F extends {
-    readonly type: 'boolean';
-} ? boolean : F extends {
-    readonly type: 'json';
-} ? unknown : F extends {
-    readonly type: 'select';
-} ? SelectValue<F> : F extends {
-    readonly type: 'richText';
-} ? RichTextDocument : F extends {
-    readonly type: 'upload';
-} ? ID | MediaDocument : F extends {
-    readonly type: 'relationship';
-    readonly to: infer S;
-} ? F extends {
-    readonly hasMany: true;
-} ? RelationValue<C, S>[] : RelationValue<C, S> : F extends {
-    readonly type: 'array';
-    readonly fields: infer Sub extends readonly Field[];
-} ? Simplify<FieldsValue<Sub, C> & {
-    id: string;
-}>[] : F extends {
-    readonly type: 'group';
-    readonly fields: infer Sub extends readonly Field[];
-} ? FieldsValue<Sub, C> : F extends {
-    readonly type: 'blocks';
-    readonly blocks: infer B extends readonly Block[];
-} ? BlockValue<B[number], C>[] : never;
-/** One row of a `blocks` field: the block's fields plus `id` and `blockType` (distributes over kinds). */
-type BlockValue<B, C extends Config> = B extends {
-    readonly slug: infer S;
-    readonly fields: infer Sub extends readonly Field[];
-} ? Simplify<FieldsValue<Sub, C> & {
-    id: string;
-    blockType: S;
-}> : never;
-type BlockInput<B> = B extends {
-    readonly slug: infer S;
-    readonly fields: infer Sub extends readonly Field[];
-} ? Simplify<FieldsInput<Sub> & {
-    id?: string;
-    blockType: S;
-}> : never;
-type Visible<Fs extends readonly Field[]> = Exclude<Fs[number], {
-    readonly hidden: true;
-}>;
-/** Always set when read: required fields, and lists and groups (empty `[]` / `{}` otherwise). */
-type Present = {
-    readonly required: true;
-} | {
-    readonly type: 'array' | 'blocks' | 'group';
-} | {
-    readonly hasMany: true;
-};
-type RequiredFields<Fs extends readonly Field[]> = Extract<Visible<Fs>, Present>;
-type OptionalFields<Fs extends readonly Field[]> = Exclude<Visible<Fs>, Present>;
-/** The shape of the data described by a list of fields. */
-type FieldsValue<Fs extends readonly Field[], C extends Config = Config> = Simplify<{
-    -readonly [F in RequiredFields<Fs> as F['name']]: FieldValue<F, C>;
-} & {
-    -readonly [F in OptionalFields<Fs> as F['name']]?: FieldValue<F, C> | null;
-}>;
-type SystemFields<T extends {
-    readonly drafts?: boolean;
-}> = {
-    id: ID;
-    createdAt: string;
-    updatedAt: string;
-} & (T extends {
-    readonly drafts: true;
-} ? {
-    status: 'draft' | 'published';
-} : unknown);
-type InferCollection<T extends CollectionConfig, C extends Config = Config> = Simplify<SystemFields<T> & FieldsValue<T['fields'], C>>;
-type InferGlobal<T extends GlobalConfig, C extends Config = Config> = Simplify<
-/** `null` until the global is saved for the first time. */
-{
-    updatedAt: string | null;
-} & (T extends {
-    readonly drafts: true;
-} ? {
-    status: 'draft' | 'published';
-} : unknown) & FieldsValue<T['fields'], C>>;
-type CollectionSlug<C extends Config> = NonNullable<C['collections']>[number]['slug'] | 'users' | 'media';
-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>;
-/** Data type of a global, e.g. `GlobalDocument<typeof config, 'site'>`. */
-type GlobalDocument<C extends Config, S extends GlobalSlug<C>> = InferGlobal<Extract<NonNullable<C['globals']>[number], {
-    readonly slug: S;
-}>, C>;
-type InputValue<F extends Field> = F extends {
-    readonly type: 'relationship';
-} ? F extends {
-    readonly hasMany: true;
-} ? readonly ID[] : ID : F extends {
-    readonly type: 'select';
-    readonly hasMany: true;
-} ? Readonly<SelectValue<F>> : F extends {
-    readonly type: 'upload';
-} ? ID : F extends {
-    readonly type: 'date';
-} ? string | Date : F extends {
-    readonly type: 'array';
-    readonly fields: infer Sub extends readonly Field[];
-} ? readonly Simplify<FieldsInput<Sub> & {
-    id?: string;
-}>[] : F extends {
-    readonly type: 'group';
-    readonly fields: infer Sub extends readonly Field[];
-} ? FieldsInput<Sub> : 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). */
-type NeedsInput<F extends Field> = F extends {
-    readonly required: true;
-} ? F extends {
-    readonly defaultValue: unknown;
-} ? never : F extends {
-    readonly type: 'slug';
-    readonly from: string;
-} ? never : F : never;
-type FieldsInput<Fs extends readonly Field[]> = Simplify<{
-    -readonly [F in NeedsInput<Visible<Fs>> as F['name']]: InputValue<F>;
-} & {
-    -readonly [F in Exclude<Visible<Fs>, NeedsInput<Visible<Fs>>> as F['name']]?: InputValue<F> | null;
-}>;
-type StatusInput<T> = T extends {
-    readonly drafts: true;
-} ? {
-    status?: 'draft' | 'published';
-} : unknown;
-/** Users are created with a password, which is hashed and never returned. */
-type PasswordInput<S, Required extends boolean> = S extends 'users' ? Required extends true ? {
-    password: string;
-} : {
-    password?: string;
-} : unknown;
-/** Data accepted by `create`, e.g. `CreateInput<typeof config, 'posts'>`. */
-type CreateInput<C extends Config, S extends CollectionSlug<C>> = Simplify<FieldsInput<CollectionBySlug<C, S>['fields']> & StatusInput<CollectionBySlug<C, S>> & PasswordInput<S, true>>;
-/** Data accepted by `update`: any subset of `CreateInput`. */
-type UpdateInput<C extends Config, S extends CollectionSlug<C>> = Partial<CreateInput<C, S>>;
-/** Data accepted by `updateGlobal`. */
-type GlobalInput<C extends Config, S extends GlobalSlug<C>> = Partial<Simplify<FieldsInput<Extract<NonNullable<C['globals']>[number], {
-    readonly slug: S;
-}>['fields']> & StatusInput<Extract<NonNullable<C['globals']>[number], {
-    readonly slug: S;
-}>>>>;
 
-declare const DEFAULT_MAX_VERSIONS = 50;
-/** One saved state of a document or global. */
-interface VersionSummary {
-    readonly id: ID;
-    /** `draft` or `published` with drafts enabled, otherwise `null`. */
-    readonly status: 'draft' | 'published' | null;
-    /** The newest version: the document's current editable state. */
-    readonly latest: boolean;
-    /** Who saved it (user id), or `null` for saves without a user (scripts, seeds). */
-    readonly author: ID | null;
-    readonly createdAt: string;
+declare const WEBHOOK_EVENTS: readonly ["create", "update", "delete", "publish", "unpublish", "draft"];
+/**
+ * `create`, `update`, `delete`: the stored document changed. `publish` / `unpublish`: its status
+ * changed (sent with `create` or `update`). `draft`: only a draft was saved; what is live did not
+ * change (collections with versions and drafts).
+ */
+type WebhookEvent = (typeof WEBHOOK_EVENTS)[number];
+interface WebhookConfig {
+    /** Where to POST events. */
+    readonly url: string;
+    /** Events to send. Default: all. */
+    readonly events?: readonly WebhookEvent[];
+    /** Collections to send events for. Default: all; `[]` for none. */
+    readonly collections?: readonly string[];
+    /** Globals to send events for. Default: all; `[]` for none. */
+    readonly globals?: readonly string[];
+    /** Signs each body: `x-easy-cms-signature: sha256=<hex HMAC-SHA256 of the body>`. */
+    readonly secret?: string;
+    /** Extra request headers, e.g. a token the receiver checks. */
+    readonly headers?: Readonly<Record<string, string>>;
 }
-interface Version<T = Record<string, unknown>> extends VersionSummary {
-    /** The document as it was saved (hidden fields such as password hashes are never kept). */
-    readonly data: T;
+/** What a webhook receives as JSON. */
+interface WebhookPayload {
+    readonly event: WebhookEvent;
+    readonly collection?: string;
+    readonly global?: string;
+    readonly id?: ID;
+    /** The stored document (every locale, no hidden fields); for `delete`, as it was. */
+    readonly doc: Record<string, unknown>;
+    /** ISO time of the change. */
+    readonly timestamp: string;
 }
 
 type Data$1 = Record<string, unknown>;
-type Slug<C extends Config> = string extends CollectionSlug<C> ? string : CollectionSlug<C>;
-type GSlug<C extends Config> = string extends GlobalSlug<C> ? string : GlobalSlug<C>;
-type Doc<C extends Config, S> = string extends CollectionSlug<C> ? RawDocument : CollectionDocument<C, S & CollectionSlug<C>>;
-type Create<C extends Config, S> = string extends CollectionSlug<C> ? Data$1 : CreateInput<C, S & CollectionSlug<C>>;
-type Update<C extends Config, S> = string extends CollectionSlug<C> ? Data$1 : UpdateInput<C, S & CollectionSlug<C>>;
-type GDoc<C extends Config, S> = string extends GlobalSlug<C> ? Data$1 : GlobalDocument<C, S & GlobalSlug<C>>;
-type GInput<C extends Config, S> = string extends GlobalSlug<C> ? Data$1 : GlobalInput<C, S & GlobalSlug<C>>;
-interface AccessOptions {
-    /**
-     * The Local API trusts its caller and skips access rules by default.
-     * Pass `false` (with `user`) to apply them, as the REST API does.
-     */
-    readonly overrideAccess?: boolean;
-    /** The user to check access for. `null` = not logged in. */
-    readonly user?: AuthUser | null;
-}
-interface DepthOptions extends AccessOptions {
-    /** How many levels of relationships to populate. Default 1, maximum 3. */
-    readonly depth?: number;
-    /**
-     * With `localization`: the locale to read, and for writes the locale the data is in. Default:
-     * the default locale. `'all'` reads (and writes) localized fields as `{ [locale]: value }`.
-     */
-    readonly locale?: string;
+type MaybePromise<T> = T | Promise<T>;
+type Operation = 'create' | 'update';
+interface HookBase {
+    /** The user the operation runs for; `null` for anonymous or trusted Local API calls. */
+    readonly user: AuthUser | null;
+    /** The Local API, e.g. to query other collections or trigger a revalidation. */
+    readonly cms: EasyCMS;
+    /** Slug of the collection or global. */
+    readonly slug: string;
 }
-interface ReadOptions extends DepthOptions {
-    /**
-     * Include drafts. By default only published documents of collections with
-     * `drafts: true` are returned, including when populating relationships (FR-DRF-04).
-     */
-    readonly draft?: boolean;
-    /** Use the default locale's value when a localized value is empty. Default: `localization.fallback`. */
-    readonly fallbackLocale?: boolean;
+type BeforeValidateHook = (args: HookBase & {
+    data: Data$1;
+    operation: Operation;
+    originalDoc?: Data$1;
+}) => MaybePromise<Data$1 | undefined>;
+type BeforeChangeHook = (args: HookBase & {
+    data: Data$1;
+    operation: Operation;
+    originalDoc?: Data$1;
+}) => MaybePromise<Data$1 | undefined>;
+type AfterChangeHook = (args: HookBase & {
+    doc: Data$1;
+    operation: Operation;
+    previousDoc?: Data$1;
+}) => MaybePromise<void>;
+type BeforeDeleteHook = (args: HookBase & {
+    id: ID;
+}) => MaybePromise<void>;
+type AfterDeleteHook = (args: HookBase & {
+    id: ID;
+    doc: Data$1;
+}) => MaybePromise<void>;
+type AfterReadHook = (args: HookBase & {
+    doc: Data$1;
+}) => MaybePromise<Data$1 | undefined>;
+interface CollectionHooks {
+    readonly beforeValidate?: readonly BeforeValidateHook[];
+    readonly beforeChange?: readonly BeforeChangeHook[];
+    readonly afterChange?: readonly AfterChangeHook[];
+    readonly beforeDelete?: readonly BeforeDeleteHook[];
+    readonly afterDelete?: readonly AfterDeleteHook[];
+    readonly afterRead?: readonly AfterReadHook[];
 }
-interface FindOptions extends ReadOptions {
-    readonly where?: Where;
-    /** Field path, `-` prefix for descending. Default `-createdAt`. */
-    readonly sort?: string | readonly string[];
-    /** Default 10. `0` returns every document. */
-    readonly limit?: number;
-    /** 1-based. Default 1. */
-    readonly page?: number;
+interface GlobalHooks {
+    readonly beforeChange?: readonly BeforeChangeHook[];
+    readonly afterChange?: readonly AfterChangeHook[];
+    readonly afterRead?: readonly AfterReadHook[];
 }
-interface CreateEasyCMSOptions {
-    /** Project root. Default `process.cwd()`. */
-    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.
-     */
-    readonly scheduler?: boolean;
-    /** Default `verify` when `NODE_ENV=production`, otherwise `push`. */
-    readonly schema?: SchemaMode;
-    readonly logger?: Logger;
-    readonly interactive?: boolean;
+interface LocalizationConfig {
+    /** Content locales, e.g. `['th', 'en']`. */
+    readonly locales: readonly string[];
+    /** The locale used when none is given; its values also fill empty ones. Default: the first. */
+    readonly defaultLocale?: string;
+    /** Reads return the default locale's value when a locale's value is empty. Default true. */
+    readonly fallback?: boolean;
 }
-/** Connects to the database and returns the Local API. */
-declare function createEasyCMS<const C extends Config>(config: C, options?: CreateEasyCMSOptions): Promise<EasyCMS<C>>;
-/** A scheduled publish or unpublish. */
-interface ScheduledJob {
-    readonly id: ID;
-    readonly action: 'publish' | 'unpublish';
-    /** ISO time the job runs at (or after). */
-    readonly runAt: string;
-    readonly state: 'pending' | 'done' | 'failed';
-    readonly error: string | null;
-    readonly author: ID | null;
+/**
+ * Where a document is shown on the site, for live preview in the admin: an absolute URL or a
+ * path on the site's origin. Return `null` when the document has no page.
+ */
+type PreviewURL = (args: {
+    readonly doc: Record<string, unknown>;
+    /** The content locale being edited (with `localization`), otherwise the admin locale. */
+    readonly locale: string;
+}) => string | null | undefined;
+interface VersionsConfig {
+    /** Versions kept per document; older ones are deleted. Default 50. */
+    readonly max?: number;
 }
-declare class EasyCMS<C extends Config = Config> {
-    readonly config: ResolvedConfig;
-    readonly db: Database;
-    readonly logger: Logger;
-    /** Login, logout and session checks. */
-    readonly auth: Auth;
-    /** Where uploaded files are stored. */
-    readonly storage: StorageAdapter;
-    /** Project root: relative paths in the config (e.g. `admin.modules`) start here. */
-    readonly cwd: string;
-    private readonly versions;
-    private readonly webhooks;
-    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>;
-    count<S extends Slug<C>>(collection: S, options?: {
-        where?: Where;
-        draft?: boolean;
-        locale?: string;
-    } & AccessOptions): Promise<number>;
-    create<S extends Slug<C>>(collection: S, data: Create<C, S>, options?: DepthOptions): Promise<Doc<C, S>>;
+/** 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[];
+}
+interface CollectionConfig {
+    /** URL and table name. Lowercase letters, digits, `-` and `_`. */
+    readonly slug: string;
+    readonly labels?: {
+        readonly singular?: Label;
+        readonly plural?: Label;
+    };
+    /** Icon in the admin menu. Default `file-text`. */
+    readonly icon?: AdminIcon;
     /**
-     * Stores a file and creates its `media` document (FR-UPL). The type is detected from
-     * the contents; images get width/height, and resized copies when `sharp` is installed.
+     * How the admin opens documents from the list: `drawer` slides a panel over the list, handy
+     * for small collections (categories, tags). Default `page`. Collections with drafts, versions
+     * or live preview always use the page.
      */
-    upload(file: {
-        data: Uint8Array;
-        name: string;
-    }, data?: Record<string, unknown>, options?: DepthOptions): Promise<MediaDocument>;
-    /** Public URL of a stored file. */
-    mediaURL(key: string): string;
-    update<S extends Slug<C>>(collection: S, id: ID, data: Update<C, S>, options?: DepthOptions): Promise<Doc<C, S>>;
+    readonly editIn?: 'page' | 'drawer';
+    readonly fields: readonly Field[];
+    /** Top-level field shown as the document title in the admin UI. */
+    readonly useAsTitle?: string;
+    /** Adds a `status` field (`draft` | `published`). */
+    readonly drafts?: boolean;
     /**
-     * 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;
-     * this is how to unpublish it.
+     * Keep a snapshot of every save, to view history and restore. With `drafts`, a draft saved
+     * on a published document is kept as a version and the published document stays live until
+     * it is published again.
      */
-    unpublish<S extends Slug<C>>(collection: S, id: ID, options?: DepthOptions): Promise<Doc<C, S>>;
-    /** Throws away the unpublished draft of a published document, going back to what is live. */
-    discardDraft<S extends Slug<C>>(collection: S, id: ID, options?: DepthOptions): Promise<Doc<C, S>>;
-    /** Saved versions of a document, newest first. Needs update access to the document. */
-    findVersions<S extends Slug<C>>(collection: S, id: ID, options?: AccessOptions & {
-        limit?: number;
-        page?: number;
-    }): Promise<PaginatedDocs<VersionSummary>>;
-    /** One saved version with the document as it was then. */
-    findVersion<S extends Slug<C>>(collection: S, id: ID, versionId: ID, options?: DepthOptions): Promise<Version<Doc<C, S>> | null>;
+    readonly versions?: boolean | VersionsConfig;
+    /** Allow scheduling publish/unpublish for a later time (needs `drafts`). */
+    readonly schedule?: boolean;
+    /** Live preview: the page that shows a document, e.g. `({ doc }) => \`/posts/${doc.slug}\``. */
+    readonly preview?: PreviewURL;
+    readonly access?: CollectionAccess;
+    readonly hooks?: CollectionHooks;
+    /** Custom admin components. */
+    readonly admin?: ContainerAdmin;
+}
+interface GlobalConfig {
+    readonly slug: string;
+    readonly label?: Label;
+    /** Icon in the admin menu. Default `settings`. */
+    readonly icon?: AdminIcon;
+    readonly fields: readonly Field[];
+    readonly drafts?: boolean;
+    /** Keep a snapshot of every save. See `CollectionConfig.versions`. */
+    readonly versions?: boolean | VersionsConfig;
+    /** Allow scheduling publish/unpublish for a later time (needs `drafts`). */
+    readonly schedule?: boolean;
+    /** Live preview: the page that shows the global. See `CollectionConfig.preview`. */
+    readonly preview?: PreviewURL;
+    readonly access?: GlobalAccess;
+    readonly hooks?: GlobalHooks;
+    /** Custom admin components. */
+    readonly admin?: ContainerAdmin;
+}
+type AdminLocale = 'en' | 'th';
+/** Icons a collection or global can show in the admin menu ([Lucide](https://lucide.dev) names). */
+declare const ADMIN_ICONS: readonly ["file-text", "newspaper", "book-open", "notebook", "folder", "tag", "tags", "image", "images", "video", "music", "file", "users", "user", "building", "store", "shopping-bag", "shopping-cart", "package", "box", "calendar", "calendar-days", "map-pin", "globe", "house", "layout-grid", "layers", "star", "heart", "message-square", "mail", "phone", "briefcase", "graduation-cap", "utensils", "car", "settings", "sliders-horizontal", "palette", "megaphone", "bell", "link", "quote", "circle-help", "award", "ticket", "camera", "key"];
+type AdminIcon = (typeof ADMIN_ICONS)[number];
+/** Your or your client's brand in the admin UI. */
+interface AdminBrand {
+    /** Shown in the menu, on the login page and in the browser tab. Default "Easy CMS". */
+    readonly name?: string;
+    /** Logo URL: a path on your site (`/logo.svg`) or an `https://` address. */
+    readonly logo?: string;
+    /** Main color as `#rrggbb`; lighter and darker shades are derived from it. */
+    readonly color?: string;
+}
+interface AdminConfig {
+    /** Where the admin UI is served. Default `/admin`. */
+    readonly path?: string;
+    /** Default admin UI language. Default `en`. */
+    readonly locale?: AdminLocale;
+    /** Name, logo and color of the admin UI. */
+    readonly brand?: AdminBrand;
     /**
-     * Makes an old version the current content, as a new version. With drafts it is restored as
-     * a draft (publish it to put it live); access, hooks and validation run as for `update`.
+     * The public site, for the admin's "View site" link: a path (`/`) or an `https://` URL.
+     * Default `/` with Nuxt and Next.js; none with the standalone server.
      */
-    restoreVersion<S extends Slug<C>>(collection: S, id: ID, versionId: ID, options?: DepthOptions): Promise<Doc<C, S>>;
+    readonly siteUrl?: string;
     /**
-     * Live preview: the document as it would be read if `data` were saved on top of its current
-     * state (or as a new document when `id` is `null`), with relationships populated and
-     * `afterRead` hooks applied. Nothing is written. Also returns the page URL from `preview`.
+     * Order of collections in the admin menu, by slug, e.g. `['posts', 'categories', 'media']`.
+     * Collections not listed follow in config order, with the media library last.
      */
-    preview<S extends Slug<C>>(collection: S, id: ID | null, data: Record<string, unknown>, options?: DepthOptions): Promise<LivePreview<Doc<C, S>>>;
+    readonly menu?: readonly string[];
     /**
-     * A token that lets a page read one document's current draft for a while (default one hour),
-     * without a login: `GET /api/cms/:collection/:id?preview=<token>`. The admin adds one to the
-     * preview URL as `easy-cms-preview`, for sites on another origin.
+     * 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
+     * package export (`'@easy-cms/plugin-seo/admin'`) or a file path relative to the project root
+     * (`'./admin/color-picker.js'`), resolved on the server. A module must be one self-contained ES
+     * module file. Remote URLs are not allowed.
      */
-    createPreviewToken(target: {
-        collection: string;
-        id: ID;
-    } | {
-        global: string;
-    }, options?: {
-        expiresIn?: number;
-    }): string;
-    /** What a preview token opens, or `null` when it is invalid or expired. */
-    verifyPreviewToken(token: string | null | undefined): (PreviewTarget & {
-        expiresAt: number;
-    }) | null;
-    /** Live preview of a global. See `preview`. */
-    previewGlobal<S extends GSlug<C>>(slug: S, data: Record<string, unknown>, options?: DepthOptions): Promise<LivePreview<GDoc<C, S>>>;
-    /** Coerces preview input like a save would, keeping values that would fail validation. */
-    private previewDoc;
-    private previewURL;
-    private versionTarget;
-    private updateDocument;
-    delete<S extends Slug<C>>(collection: S, id: ID, options?: AccessOptions): Promise<Doc<C, S>>;
-    findGlobal<S extends GSlug<C>>(slug: S, options?: ReadOptions): Promise<GDoc<C, S>>;
-    updateGlobal<S extends GSlug<C>>(slug: S, data: GInput<C, S>, options?: DepthOptions): Promise<GDoc<C, S>>;
-    /** Takes a global off the site (`status: 'draft'`). See `unpublish`. */
-    unpublishGlobal<S extends GSlug<C>>(slug: S, options?: DepthOptions): Promise<GDoc<C, S>>;
-    /** Throws away the unpublished draft of a published global. */
-    discardGlobalDraft<S extends GSlug<C>>(slug: S, options?: DepthOptions): Promise<GDoc<C, S>>;
-    /** Saved versions of a global, newest first. Needs update access. */
-    findGlobalVersions<S extends GSlug<C>>(slug: S, options?: AccessOptions & {
-        limit?: number;
-        page?: number;
-    }): Promise<PaginatedDocs<VersionSummary>>;
-    findGlobalVersion<S extends GSlug<C>>(slug: S, versionId: ID, options?: DepthOptions): Promise<Version<GDoc<C, S>> | null>;
-    /** Makes an old version of a global current (as a draft when the global has drafts). */
-    restoreGlobalVersion<S extends GSlug<C>>(slug: S, versionId: ID, options?: DepthOptions): Promise<GDoc<C, S>>;
-    private globalVersionTarget;
-    /** The global's pending draft when it has one (see `withDrafts`), otherwise `saved`. */
-    private globalDraft;
-    private saveGlobal;
+    readonly modules?: readonly string[];
+}
+interface ImageSize {
+    /** Key in `media.sizes`, e.g. `thumbnail`. */
+    readonly name: string;
+    readonly width: number;
+    readonly height?: number;
+    /** How to fit when both width and height are set. Default `cover`. */
+    readonly fit?: 'cover' | 'contain' | 'inside';
+}
+interface UploadConfig {
+    /** Directory for uploaded files with the default local storage, relative to the project root. Default `uploads`. */
+    readonly dir?: string;
+    /** Maximum file size in bytes. Default 10 MB. */
+    readonly maxFileSize?: number;
+    /** Allowed MIME types, detected from file contents. `image/*` style wildcards are allowed. */
+    readonly mimeTypes?: readonly string[];
+    /** Where files are stored. Default: local disk in `dir`. */
+    readonly storage?: StorageAdapter;
+    /** Resized copies generated for images when `sharp` is installed. */
+    readonly imageSizes?: readonly ImageSize[];
+}
+interface RoutesConfig {
+    /** Where the REST API is served. Default `/api/cms`. */
+    readonly api?: string;
+}
+interface AuthConfig {
+    /** Roles a user can have. Must include `admin`. Default `['admin', 'editor']`. */
+    readonly roles?: readonly string[];
+    /** Session lifetime in seconds. Default 7 days. */
+    readonly tokenExpiration?: number;
+    /** Failed logins allowed per email (and IP) within `lockWindow`. Default 5. */
+    readonly maxLoginAttempts?: number;
+    /** Window for `maxLoginAttempts`, in seconds. Default 15 minutes. */
+    readonly lockWindow?: number;
     /**
-     * What `user` may do with one document. Resolves `where`-style access
-     * against the document, so the admin UI can hide actions precisely.
+     * Origins allowed to send cookie-authenticated requests, besides the API's own origin.
+     * Needed when the admin or frontend is served from another origin, or behind a proxy that rewrites the host.
      */
-    documentPermissions(collection: Slug<C>, id: ID, user: AuthUser | null): Promise<{
-        update: boolean;
-        delete: boolean;
-    }>;
-    /** Closes the database connection. */
+    readonly trustedOrigins?: readonly string[];
+}
+/** What an endpoint's handler receives. */
+interface EndpointRequest {
+    readonly request: Request;
+    readonly url: URL;
+    /** Values of `:name` segments in the endpoint's path. */
+    readonly params: Readonly<Record<string, string>>;
+    /** The logged-in user (session cookie or Bearer token), or `null`. */
+    readonly user: AuthUser | null;
+    /** 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). */
+    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.
+ */
+interface Endpoint {
     /**
-     * Waits until webhook deliveries in progress are done. Call it before a serverless function
-     * returns, which may otherwise stop them.
+     * Path under the API, e.g. `/seo/generate` or `/stats/:collection`. The first segment must
+     * not be a collection slug or one of `users`, `globals`, `admin`, `jobs`.
      */
-    flushWebhooks(): Promise<void>;
-    destroy(): Promise<void>;
-    private schedulerTimer;
-    private running;
-    /** Runs `runJobs` every `interval` ms in this process (`createEasyCMS` does this by default). */
-    startScheduler(interval?: number): void;
+    readonly path: string;
+    readonly method: 'get' | 'post' | 'put' | 'patch' | 'delete';
     /**
-     * Runs due scheduled publishes and unpublishes, and retries failed webhook deliveries. What the
-     * scheduler and the cron endpoint (`GET <api>/jobs/run`) call.
+     * Returns a `Response`, or a value that is sent as JSON. Throw an Easy CMS error
+     * (`UnauthorizedError`, `ForbiddenError`, `ValidationError`, `NotFoundError`) for error responses.
      */
-    runJobs(now?: Date): Promise<{
-        ran: number;
-        failed: number;
-        webhooks: {
-            sent: number;
-            failed: number;
-        };
-    }>;
+    readonly handler: (request: EndpointRequest) => MaybePromise<unknown>;
+}
+/** Receives the config and returns a modified copy. Runs before validation. */
+type Plugin = (config: Config) => MaybePromise<Config>;
+interface Config {
+    /** Signs sessions. At least 32 characters; read it from `process.env.EASY_CMS_SECRET`. */
+    readonly secret: string;
+    readonly db: DatabaseAdapter;
     /**
-     * Tries webhook deliveries that are due for another attempt. Deliveries are kept in the
-     * database until they succeed, so they survive restarts.
+     * Public origin of the app, e.g. `https://example.com`. When set, media URLs are absolute
+     * so frontends on other origins can use them. Default: relative URLs.
      */
-    retryWebhooks(now?: Date): Promise<{
-        sent: number;
-        failed: number;
-    }>;
-    /** Webhook deliveries until they succeed, stored in `webhook-deliveries`. */
-    private webhookQueue;
+    readonly serverURL?: string;
     /**
-     * Publishes or unpublishes documents whose scheduled time has come. Safe to call often, e.g.
-     * from a cron job (`GET <api>/jobs/run`) where no process keeps running.
+     * Origins whose browser code may call the REST API (CORS), e.g. a Vite or React app on
+     * another origin. `'*'` allows any origin for anonymous requests. Origins in
+     * `auth.trustedOrigins` are always allowed, with cookies. Default: none.
      */
-    runScheduled(now?: Date): Promise<{
-        ran: number;
-        failed: number;
-    }>;
-    /** Schedules a publish or unpublish, replacing a pending job with the same action. */
-    schedule<S extends Slug<C>>(collection: S, id: ID, job: {
-        action: 'publish' | 'unpublish';
-        at: Date | string;
-    }, options?: AccessOptions): Promise<ScheduledJob>;
-    /** Pending jobs of a document, soonest first. */
-    scheduled<S extends Slug<C>>(collection: S, id: ID, options?: AccessOptions): Promise<ScheduledJob[]>;
-    cancelSchedule<S extends Slug<C>>(collection: S, id: ID, jobId: ID, options?: AccessOptions): Promise<void>;
-    scheduleGlobal<S extends GSlug<C>>(slug: S, job: {
-        action: 'publish' | 'unpublish';
-        at: Date | string;
-    }, options?: AccessOptions): Promise<ScheduledJob>;
-    scheduledGlobal<S extends GSlug<C>>(slug: S, options?: AccessOptions): Promise<ScheduledJob[]>;
-    cancelGlobalSchedule<S extends GSlug<C>>(slug: S, jobId: ID, options?: AccessOptions): Promise<void>;
-    private scheduleTarget;
-    private globalScheduleTarget;
-    private addJob;
+    readonly cors?: readonly string[] | '*';
     /**
-     * The next pending jobs across all collections and globals, soonest first; with access
-     * enforced, only those the user may update.
+     * Lets a cron service run due scheduled jobs: `GET <api>/jobs/run` with
+     * `Authorization: Bearer <cronSecret>`. Default: the `CRON_SECRET` environment variable (the
+     * convention of Vercel Cron). Logged-in admins can always run jobs.
      */
-    upcomingJobs(options?: AccessOptions & {
-        limit?: number;
-    }): Promise<(ScheduledJob & {
-        collection?: string;
-        global?: string;
-        doc: ID;
-    })[]>;
-    private pendingJobs;
-    private removeJob;
-    /** @internal */
-    collection(slug: string): CollectionConfig;
-    private global;
-    /** The query constraint read access adds, or `undefined` when there is none. Throws when denied. */
-    private readWhere;
-    private checkDocumentAccess;
-    private checkGlobalAccess;
-    private fieldChecker;
-    /** Runs afterRead hooks, populates relationships and removes what the caller may not see. */
-    private output;
-    /** Creates a document: access, input filtering, hooks, validation, then afterChange. */
-    private createDocument;
-    /** The locale for an operation; `undefined` without localization. Throws on unknown locales. */
-    private localeOf;
-    /** Stored localized maps → the values of the requested locale. */
-    private pick;
-    /** Input for one locale → stored localized maps, keeping the other locales from `current`. */
-    private toMaps;
-    /** Makes `where` match localized fields in the operation's locale. */
-    private whereFor;
-    /** Drafts are kept as versions (instead of unpublishing) when both are enabled. */
-    private separateDrafts;
-    /** 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;
-    /** Records a version after a save, when the collection or global keeps versions. */
-    private saveVersion;
-    private hookArgs;
+    readonly cronSecret?: string;
+    /** Endpoints notified when content changes, e.g. to rebuild a static site. */
+    readonly webhooks?: readonly WebhookConfig[];
+    /** Content in several languages: fields with `localized: true` hold one value per locale. */
+    readonly localization?: LocalizationConfig | null;
+    readonly routes?: RoutesConfig;
+    readonly admin?: AdminConfig;
+    readonly upload?: UploadConfig;
+    readonly auth?: AuthConfig;
     /**
-     * Runs hooks that may replace a value, passed as `data` (before hooks) or `doc` (afterRead).
-     * Returning `undefined` keeps the value; a throw cancels the operation.
+     * Collections. A collection with slug `users` adds fields, access or hooks
+     * to the built-in users collection.
      */
-    private transform;
-    /** Runs hooks after the change is saved: failures are logged, never undo the save (NFR-REL-03). */
-    private notify;
-    /** Writes resized copies with sharp, when installed and configured. */
-    private resizeImage;
-    /** Validates, checks uniqueness and references. Returns clean data or throws `ValidationError`. */
-    private prepare;
-    /** Refuses changes that would leave no active admin (and lock everyone out). */
-    private guardLastAdmin;
-    private makeSlugsUnique;
-    private checkUnique;
-    private isTaken;
-    private checkReferences;
+    readonly collections?: readonly CollectionConfig[];
+    readonly globals?: readonly GlobalConfig[];
+    /** Custom REST endpoints, e.g. from plugins. */
+    readonly endpoints?: readonly Endpoint[];
+    /**
+     * API keys for scripts and other apps (`Authorization: Bearer ecms_…`), managed in the admin
+     * under Settings. A key acts as its owner, limited to the collections and operations it lists.
+     */
+    readonly apiKeys?: boolean;
+    readonly plugins?: readonly Plugin[];
 }
-/** A document as live preview shows it, and the page to show it on. */
-interface LivePreview<T> {
-    readonly doc: T;
-    /** From the collection's `preview` function; `null` without one. */
-    readonly url: string | null;
+/** The config after plugins ran, validation passed and defaults were applied. */
+interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes' | 'admin' | 'upload' | 'auth' | 'collections' | 'globals' | 'endpoints' | 'plugins'> {
+    readonly cors: readonly string[] | '*';
+    /** `null` without localization. */
+    readonly localization: Required<LocalizationConfig> | null;
+    readonly routes: Required<RoutesConfig>;
+    readonly admin: Required<AdminConfig>;
+    readonly upload: Required<Omit<UploadConfig, 'storage'>> & Pick<UploadConfig, 'storage'>;
+    readonly auth: Required<AuthConfig>;
+    readonly collections: readonly CollectionConfig[];
+    readonly globals: readonly GlobalConfig[];
+    readonly endpoints: readonly Endpoint[];
 }
+/**
+ * Declares the Easy CMS config. Returns it unchanged, keeping literal types
+ * so document types can be inferred from it.
+ */
+declare function defineConfig<const TConfig extends Config>(config: TConfig): TConfig;
 
-interface LoginArgs {
-    readonly email: string;
-    readonly password: string;
-    /** Client IP, used together with the email for rate limiting. */
-    readonly ip?: string | undefined;
-}
-interface Session {
-    readonly user: AuthUser;
-    /** Signed session token, the value of the session cookie. */
-    readonly token: string;
-    /** Send back in the `X-CSRF-Token` header on cookie-authenticated writes. */
-    readonly csrfToken: string;
-    readonly expiresAt: string;
-}
-/** Login, logout and session verification. Available as `cms.auth`. */
-declare class Auth {
-    private readonly cms;
-    constructor(cms: EasyCMS);
-    private get db();
-    private get config();
-    /** Checks credentials and starts a session. Throws `UnauthorizedError` or `TooManyRequestsError`. */
-    login(args: LoginArgs): Promise<Session>;
-    /** Creates the first admin. Only works while there are no users. */
-    registerFirstUser(args: {
-        email: string;
-        password: string;
-        name?: string;
-    }): Promise<Session>;
-    hasUsers(): Promise<boolean>;
-    /** Ends the session for a signed token. Unknown tokens are ignored. */
-    logout(signedToken: string): Promise<void>;
-    /** Returns the user for a signed session token, or `null` if it is invalid or expired. */
-    verify(signedToken: string | undefined | null): Promise<AuthUser | null>;
-    /** The CSRF token clients must echo for a signed session token. */
-    csrfFor(signedToken: string): string | undefined;
-    /** Starts a new session for a user, e.g. after they changed their own password. */
-    createSession(userId: ID): Promise<Session>;
-    /** Signs a user out everywhere. */
-    revokeSessions(userId: ID): Promise<void>;
-    private startSession;
-    private findSession;
-    private toAuthUser;
-    private deleteExpiredSessions;
-    private windowStart;
-    private checkRateLimit;
-    private recordFailure;
-    private clearFailures;
+declare const API_KEYS = "api-keys";
+/** What a key may do with a collection. `create` on `media` means uploading. */
+declare const API_KEY_OPERATIONS: readonly ["read", "create", "update", "delete", "publish"];
+type ApiKeyOperation = (typeof API_KEY_OPERATIONS)[number];
+/** What a key may do with a global. */
+declare const API_KEY_GLOBAL_OPERATIONS: readonly ["read", "update", "publish"];
+type ApiKeyGlobalOperation = (typeof API_KEY_GLOBAL_OPERATIONS)[number];
+/** Stored in the key's `permissions` field. Anything not listed is not allowed. */
+interface ApiKeyPermissions {
+    readonly collections?: Readonly<Record<string, readonly ApiKeyOperation[]>>;
+    readonly globals?: Readonly<Record<string, readonly ApiKeyGlobalOperation[]>>;
+}
+/** Set on `AuthUser.apiKey` when a request authenticated with an API key. */
+interface ApiKeyContext {
+    readonly id: number | string;
+    readonly name: string;
+    readonly permissions: ApiKeyPermissions;
 }
+/**
+ * Whether a request's API key allows an operation. Always true without a key (sessions are
+ * governed by access rules alone); a key only narrows what its user may do.
+ */
+declare function keyAllows(user: AuthUser | null, target: {
+    collection: string;
+} | {
+    global: string;
+}, operation: ApiKeyOperation): boolean;
 
 declare const MIN_PASSWORD_LENGTH = 8;
 /** Hashes a password as `scrypt$N$r$p$salt$hash` (base64url). */
@@ -1616,4 +1705,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, 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 ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CollectionAccess, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_TOKEN_EXPIRATION, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DepthOptions, EXTENSIONS, EasyCMS, EasyCMSError, type EmailField, type Endpoint, type EndpointRequest, FIELD_TYPES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldType, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, PayloadTooLargeError, type Plugin, type PreviewTarget, type PreviewURL, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, UnauthorizedError, type UpdateInput, type UploadConfig, type UploadField, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, defineConfig, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isLoggedIn, loadConfig, localStorage, mergeForUpdate, mimeAllowed, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };
+export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, type Access, type AccessArgs, type AccessOptions, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminSchema, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CollectionAccess, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_TOKEN_EXPIRATION, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DepthOptions, EXTENSIONS, EasyCMS, EasyCMSError, type EmailField, type Endpoint, type EndpointRequest, FIELD_TYPES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldType, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, PayloadTooLargeError, type Plugin, type PreviewTarget, type PreviewURL, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, UnauthorizedError, type UpdateInput, type UploadConfig, type UploadField, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, defineConfig, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };