@easy-cms/core 1.32.0 → 1.33.0

package/dist/{config-Dr_NZGm6.d.ts → config-BZ4fsHL4.d.ts}

@@ -93,6 +93,67 @@ declare const isSignedIn: Access;
  */
 declare const isAdmin: Access;
 
+/**
+ * Secrets that verify: the current one first, then `previousSecrets` while one is replaced. New
+ * values are always signed with the current one.
+ */
+type Secrets = string | readonly string[];
+/** The secrets of a config, the current one first. */
+declare function secretsOf(config: {
+    readonly secret: string;
+    readonly previousSecrets?: readonly string[] | undefined;
+}): readonly string[];
+/** What a preview token opens: one document of a collection, or one global. */
+type PreviewTarget = {
+    readonly collection: string;
+    readonly id: string;
+} | {
+    readonly global: string;
+};
+/**
+ * Why a link was sent: a forgotten password, an invitation to a new account, or (`verify`) to
+ * confirm the email of an account made by signing up.
+ */
+type PasswordPurpose = 'reset' | 'invite' | 'verify';
+
+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[]>>;
+    /**
+     * With `upload.folders`: the media folders (ids) the key may use, with their subfolders. Empty
+     * or missing: every folder.
+     */
+    readonly folders?: readonly (string | number)[];
+    /**
+     * The context the key was created in (`onRequest`, e.g. its tenant), kept for good: requests
+     * with the key get it as `user.apiKey.permissions.context`. Set by Easy CMS, not by input.
+     */
+    readonly context?: RequestContext;
+}
+/** 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;
+
 /** More about a log line: `error` for what failed (its stack goes to the log). */
 interface LogDetails {
     readonly error?: unknown;
@@ -361,66 +422,155 @@ interface BundleHints {
     readonly traceInclude: readonly string[];
 }
 
-/**
- * Secrets that verify: the current one first, then `previousSecrets` while one is replaced. New
- * values are always signed with the current one.
- */
-type Secrets = string | readonly string[];
-/** The secrets of a config, the current one first. */
-declare function secretsOf(config: {
-    readonly secret: string;
-    readonly previousSecrets?: readonly string[] | undefined;
-}): readonly string[];
-/** What a preview token opens: one document of a collection, or one global. */
-type PreviewTarget = {
-    readonly collection: string;
-    readonly id: string;
-} | {
-    readonly global: string;
-};
-/**
- * Why a link was sent: a forgotten password, an invitation to a new account, or (`verify`) to
- * confirm the email of an account made by signing up.
- */
-type PasswordPurpose = 'reset' | 'invite' | 'verify';
-
-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[]>>;
+/** Audit log settings (`audit`). */
+interface AuditConfig {
+    /** Days to keep entries; older ones are deleted. `0`: keep them all. Default 365. */
+    readonly keepDays?: number;
+    /** Keep the values before and after a change, not only which fields changed. Default `true`. */
+    readonly values?: boolean;
+    /** Failed logins within an hour that the dashboard warns about. Default 20. */
+    readonly failedLogins?: number;
     /**
-     * With `upload.folders`: the media folders (ids) the key may use, with their subfolders. Empty
-     * or missing: every folder.
+     * The part of the site an entry belongs to, from the request's context, e.g. its tenant
+     * (usually set by a plugin). Users whose role holds in a part only (`scoped`) see that part's
+     * entries; others see the chosen part's, or all.
      */
-    readonly folders?: readonly (string | number)[];
+    readonly scope?: ((args: {
+        readonly context: RequestContext;
+        readonly user: AuthUser | null;
+    }) => string | null | undefined) | false;
+}
+/** A field that changed: values before and after, unless they are not kept. */
+interface AuditChange {
+    field: string;
+    before?: unknown;
+    after?: unknown;
+}
+/** One entry (`GET <api>/admin/audit`). */
+interface AuditEntry {
+    id: ID;
+    /** When, as an ISO date. */
+    at: string;
+    /** E.g. `create`, `update`, `publish`, `delete`, `login`, `login.failed`, `role.update`. */
+    action: string;
+    /** A collection slug, `global:<slug>`, or an area such as `auth`, `roles`, `backups`. */
+    target: string | null;
+    /** The document's id. */
+    doc: string | null;
+    /** The document's title then (kept after it is deleted). */
+    title: string | null;
+    actor: {
+        id: string | null;
+        email: string | null;
+        /** `user` (admin or REST), `api-key`, `system` (code), `scheduler`. */
+        via: string;
+        ip: string | null;
+        userAgent: string | null;
+    };
+    changes: AuditChange[] | null;
+    detail: Record<string, unknown> | null;
+}
+/** `GET <api>/admin/audit`: a page of entries, newest first. */
+/** A page of the audit log: the list shape of the rest of the API. */
+type AuditPage = PaginatedDocs<AuditEntry>;
+interface AuditFilter {
+    action?: string | null;
+    target?: string | null;
+    doc?: string | null;
+    /** An email, or part of one. */
+    actor?: string | null;
+    /** ISO dates. */
+    from?: string | null;
+    to?: string | null;
+    /** Only entries of this part of the site (`scope`). */
+    scope?: string | null;
+}
+/** `POST <api>/admin/audit/verify`. */
+interface AuditVerification {
+    checked: number;
+    /** Entries whose signature does not match: changed after they were written. */
+    invalid: ID[];
     /**
-     * The context the key was created in (`onRequest`, e.g. its tenant), kept for good: requests
-     * with the key get it as `user.apiKey.permissions.context`. Set by Easy CMS, not by input.
+     * Missing ids between entries: deleted entries, or (rarely) inserts that failed. Ids are never
+     * reused, so the newest entries deleted show up here once anything is written after them (a
+     * check writes an entry itself). The server's log has each check's last id, to compare with.
      */
-    readonly context?: RequestContext;
-}
-/** Set on `AuthUser.apiKey` when a request authenticated with an API key. */
-interface ApiKeyContext {
-    readonly id: number | string;
-    readonly name: string;
-    readonly permissions: ApiKeyPermissions;
+    gaps: number;
+    at: string;
 }
 /**
- * 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.
+ * The audit log (`audit` in the config): who did what, when, from where. Entries can't be
+ * changed through Easy CMS; each is signed with the secret, so changes in the database show.
+ * Available as `cms.audit`.
  */
-declare function keyAllows(user: AuthUser | null, target: {
-    collection: string;
-} | {
-    global: string;
-}, operation: ApiKeyOperation): boolean;
+declare class AuditLog {
+    private readonly cms;
+    /** Entries that could not be written since the server started. */
+    failures: number;
+    constructor(cms: EasyCMS);
+    get enabled(): boolean;
+    private get settings();
+    /**
+     * Writes an entry. The user defaults to the request's. Never throws: a failure is logged and
+     * counted, and the dashboard says so.
+     */
+    record(entry: {
+        action: string;
+        target?: string | null;
+        doc?: ID | null;
+        title?: string | null;
+        user?: AuthUser | null;
+        /** Who it was when there is no user, e.g. the email of a failed login. */
+        email?: string | null;
+        changes?: AuditChange[] | null;
+        detail?: Record<string, unknown> | null;
+        /** The call's context, when it is not the request's. */
+        context?: RequestContext;
+    }): Promise<void>;
+    /** Entries, newest first: `page` (from 1) of `limit` (default 50, at most 100). */
+    list(options?: AuditFilter & {
+        page?: number;
+        limit?: number;
+    }): Promise<AuditPage>;
+    /** The filtered entries as CSV (the newest 10,000). */
+    csv(filter: AuditFilter): Promise<string>;
+    /** Checks every entry's signature, and that no ids are missing. */
+    verify(): Promise<AuditVerification>;
+    /** The secret an entry was signed with: the current one, a previous one, or none (changed). */
+    private signer;
+    /**
+     * After `secret` changed: signs again, with the current secret, the entries signed with one of
+     * `previousSecrets`, so they still verify once it is removed. Entries no secret verifies were
+     * changed: they are left as they are, and reported. Records `audit.resign`.
+     */
+    resign(): Promise<{
+        checked: number;
+        resigned: number;
+        invalid: ID[];
+    }>;
+    /**
+     * What the dashboard warns about: many failed logins, sign-ins of break-glass accounts in the
+     * last day, entries not written, a failed check.
+     */
+    attention(now?: Date): Promise<({
+        id: 'failed-logins';
+        count: number;
+    } | {
+        id: 'break-glass';
+        count: number;
+        emails: string[];
+    } | {
+        id: 'audit-failures';
+        count: number;
+    } | {
+        id: 'audit-tampered';
+        invalid: number;
+        at: string;
+    })[]>;
+    private sign;
+    private lastVerification;
+    private where;
+}
 
 /** The cookie that carries a sign-in through the provider and back. */
 declare const SSO_COOKIE = "ecms-sso";
@@ -717,338 +867,40 @@ interface EmailAdapter {
      * Leave it out to skip the check.
      */
     readonly apiVersion?: number;
-    /** The sender when a message has none, e.g. `Easy CMS <no-reply@example.com>`. */
-    readonly from?: string | undefined;
-    send(message: EmailMessage & {
-        readonly from: string;
-    }): Promise<void>;
-    /**
-     * The settings in use, shown to admins on Settings → Email. Never return secrets: say whether
-     * a password is set, not what it is.
-     */
-    describe?(): readonly EmailSetting[];
-    /** Checks the connection without sending (Settings → Email); throws with the reason. */
-    verify?(): Promise<void>;
-}
-/** One setting an email adapter shows to admins (`describe()`). */
-interface EmailSetting {
-    /**
-     * `host`, `port`, `secure`, `user`, `password`, `from` and `delivery` (`log`: printed, not sent)
-     * are translated in the admin; others are shown as they are.
-     */
-    readonly key: string;
-    /** `null`: not set. */
-    readonly value: string | null;
-    /** Where it comes from, e.g. `SMTP_HOST` or `smtp({ host })`. */
-    readonly source?: string;
-}
-/** Prints emails to the log instead of sending them: for development and tests. */
-declare function consoleEmail(options?: {
-    from?: string;
-    log?: (text: string) => void;
-}): EmailAdapter & {
-    readonly sent: (EmailMessage & {
-        from: string;
-    })[];
-};
-
-/** A label shown in the admin UI. Either one string or one string per admin locale. */
-type Label = string | {
-    readonly [locale: string]: string;
-};
-interface FieldValidateContext {
-    /** The whole document being validated, including sibling fields. */
-    readonly data: Readonly<Record<string, unknown>>;
-    readonly operation: 'create' | 'update';
-}
-/** Return `true` when valid, or an error message to show on the field. */
-type FieldValidate<TValue> = (value: TValue | null | undefined, ctx: FieldValidateContext) => true | string | Promise<true | string>;
-/**
- * A Web Component from an admin module (`admin.modules`), by its tag name, which must start
- * with `ecms-`. `props` (plain JSON) reach the element as its `options` property.
- */
-type AdminComponent = string | {
-    readonly tag: string;
-    readonly props?: Readonly<Record<string, unknown>>;
-};
-/** How the admin shows a field, with components from admin modules. */
-interface FieldAdmin {
-    /** Help below the field's label. */
-    readonly description?: Label;
-    /** Its share of a row (`admin.layout`'s `row`). Default: an equal share. */
-    readonly width?: '1/4' | '1/3' | '1/2' | '2/3' | '3/4' | 'full';
-    /**
-     * Shown only when its sibling fields match, e.g. `{ field: 'linkType', equals: 'external' }`.
-     * A hidden field isn't required. See `FieldCondition`.
-     */
-    readonly condition?: FieldCondition;
-    /** Shown instead of the field's input; the admin keeps the label and error messages. */
-    readonly component?: AdminComponent;
-    /** Shown below the field, e.g. a length meter or a preview. */
-    readonly after?: readonly AdminComponent[];
-    /** Shows the value in the admin's lists (e.g. a color swatch). Default: the plain value. */
-    readonly cell?: AdminComponent;
-    /**
-     * A column of the list at first (each user can change it): `true`, or per request, e.g.
-     * only when the admin shows every tenant.
-     */
-    readonly column?: boolean | ((args: AdminFieldArgs) => boolean | Promise<boolean>);
-    /** Relationships: offer to create the related document in place. Default true. */
-    readonly allowCreate?: boolean;
-    /**
-     * The value a new document's form starts with, worked out for each user, e.g. from the
-     * request's context. The server's own default (`defaultValue`, hooks) still applies.
-     */
-    readonly initialValue?: (args: AdminFieldArgs) => unknown;
-    /** `sidebar`: shown in the edit page's side panel instead of the main form (top-level fields). */
-    readonly position?: 'sidebar';
-    /** `false`: the list's filters don't offer it. Default: every field the user may read. */
-    readonly filter?: boolean;
-}
-/** What per-request admin options of a field receive. */
-interface AdminFieldArgs {
-    readonly user: AuthUser;
-    readonly context: RequestContext;
-}
-/**
- * Field types that packages add (`fieldTypes` in the config), for the types inferred from the
- * config. A package declares its own by augmenting this interface:
- *
- * ```ts
- * declare module '@easy-cms/core' {
- *   interface CustomFieldTypes {
- *     color: { value: string; options: { readonly presets?: readonly string[] } }
- *   }
- * }
- * ```
- */
-interface CustomFieldTypes {
-}
-/** A field of a type from `CustomFieldTypes`: the common options, plus the type's own. */
-type CustomField = {
-    [K in keyof CustomFieldTypes]: BaseField<K & string, CustomFieldTypes[K] extends {
-        value: infer V;
-    } ? V : unknown> & (CustomFieldTypes[K] extends {
-        options: infer O;
-    } ? O : unknown);
-}[keyof CustomFieldTypes];
-interface BaseField<TType extends string, TValue> {
-    readonly type: TType;
-    readonly name: string;
-    readonly label?: Label;
-    readonly required?: boolean;
-    readonly unique?: boolean;
-    /**
-     * With `unique` (or on a slug field): a sibling field (e.g. `parent` or `tenant`), or several,
-     * whose documents only need to differ among themselves, so `/about/team` and `/careers/team`
-     * can both be `team`. Single, unlocalized relationship, select, text or number fields.
-     */
-    readonly uniqueWithin?: string | readonly string[];
-    /**
-     * `true` for a database index (filters and sorts on this field). `'trigram'`, on text, textarea
-     * and email fields: an index for `like`, which finds any part of the text, in Thai as in other
-     * languages. Postgres only (pg_trgm); nothing on SQLite. There, `like` needs at least three
-     * characters, and the admin's searches wait for them.
-     */
-    readonly index?: boolean | 'trigram';
-    readonly defaultValue?: TValue;
-    readonly validate?: FieldValidate<TValue>;
-    readonly access?: FieldAccess;
-    /** Stored but never returned by the API nor accepted as input (e.g. a password hash). */
-    readonly hidden?: boolean;
-    /**
-     * One value per locale (needs `localization` in the config). Not for groups, arrays or
-     * hasMany fields: localize the fields inside a group or array instead.
-     */
-    readonly localized?: boolean;
-    /** How the field looks in the admin: components, position, width, conditions. */
-    readonly admin?: FieldAdmin;
-    /** Set by Easy CMS on fields of an added type (`fieldTypes`): the type's name, e.g. `color`. */
-    readonly customType?: string;
-}
-interface TextField extends BaseField<'text', string> {
-    readonly minLength?: number;
-    readonly maxLength?: number;
-}
-interface TextareaField extends BaseField<'textarea', string> {
-    readonly minLength?: number;
-    readonly maxLength?: number;
-}
-interface NumberField extends BaseField<'number', number> {
-    readonly min?: number;
-    readonly max?: number;
-}
-interface BooleanField extends BaseField<'boolean', boolean> {
-}
-/** Stored and returned as an ISO 8601 string. */
-interface DateField extends BaseField<'date', string> {
-}
-interface EmailField extends BaseField<'email', string> {
-}
-interface JsonField extends BaseField<'json', unknown> {
-}
-type SelectOption = string | {
-    readonly label: Label;
-    readonly value: string;
-};
-interface SelectField extends BaseField<'select', string | readonly string[]> {
-    readonly options: readonly SelectOption[];
-    readonly hasMany?: boolean;
-}
-interface SlugField extends BaseField<'slug', string> {
-    /** Name of a sibling `text` field to generate the slug from. */
-    readonly from?: string;
-}
-/** Tiptap / ProseMirror JSON document. */
-interface RichTextDocument {
-    readonly type: 'doc';
-    readonly content?: readonly unknown[];
-}
-interface RichTextField extends BaseField<'richText', RichTextDocument> {
-    /**
-     * Blocks editors place between paragraphs (#328): a card, a callout, a video. Each is a node
-     * `{ type: 'block', attrs: { blockType, id, fields } }` in the document.
-     */
-    readonly blocks?: readonly RichTextBlock[];
-}
-/** Arguments of a rich text block's `admin.summary` function. */
-interface BlockSummaryArgs {
-    readonly fields: Record<string, unknown>;
-    readonly user: AuthUser | null;
-    readonly cms: EasyCMS;
-}
-/** A block in rich text (`richText.blocks`): the fields of `Block`, and how its card reads. */
-interface RichTextBlock extends Block {
-    readonly admin?: {
-        /**
-         * The text of the block's card in the editor: a function, run on the server, or the tag of a
-         * custom element from an admin module, which gets `fields`. Default: the block's label and
-         * its first value.
-         */
-        readonly summary?: string | ((args: BlockSummaryArgs) => string | Promise<string>);
-    };
-}
-/** References a document in the built-in `media` collection: a file or an image. */
-interface UploadField extends BaseField<'upload', never> {
-    /** Several files, e.g. a gallery: the value is a list, in the order editors arrange. */
-    readonly hasMany?: boolean;
-    /** With `hasMany`: the fewest files. */
-    readonly minRows?: number;
-    /** With `hasMany`: the most files. */
-    readonly maxRows?: number;
-    /**
-     * The file types allowed, e.g. `['image/*']` or `['image/*', 'application/pdf']`. The admin
-     * offers only these, and saving refuses others.
-     */
-    readonly mimeTypes?: readonly string[];
-    /**
-     * With `upload.folders`: the `key` of the media folder this field's files go in, e.g.
-     * `'banners'`. Its picker opens there and its uploads land there; the folder is made when it
-     * is first needed.
-     */
-    readonly folder?: string;
-    /** With `folder`: only files in that folder (and its subfolders) may be chosen. */
-    readonly folderOnly?: boolean;
-    /** Which media documents may be chosen, as for relationships: offered and checked on save. */
-    readonly filterOptions?: FilterOptions;
-}
-interface FilterOptionsArgs {
-    /** The document being edited; `undefined` while it is being created. */
-    readonly id: ID | undefined;
-    /** The collection the choices come from: one of the field's `to`. */
-    readonly relationTo: string;
-    readonly user: AuthUser | null;
-    readonly cms: EasyCMS;
-    /** The request's context (`onRequest`), `{}` when there is none. */
-    readonly context: RequestContext;
-}
-/**
- * Which documents a relationship may point to: a `where` on the target collection, or `true`
- * for any. Runs on the server: the admin's picker offers only these, and saving checks them.
- */
-type FilterOptions = (args: FilterOptionsArgs) => Where | true | Promise<Where | true>;
-interface RelationshipField extends BaseField<'relationship', never> {
-    /**
-     * Slug of the target collection, or several: then each value is `{ relationTo, value }`, the
-     * collection and the document's id (#327).
-     */
-    readonly to: string | readonly string[];
-    readonly hasMany?: boolean;
-    /** With `hasMany`: the fewest documents. */
-    readonly minRows?: number;
-    /** With `hasMany`: the most documents. */
-    readonly maxRows?: number;
-    readonly filterOptions?: FilterOptions;
-}
-interface ArrayField extends BaseField<'array', never> {
-    readonly fields: readonly Field[];
-    readonly minRows?: number;
-    readonly maxRows?: number;
-}
-interface GroupField extends BaseField<'group', never> {
-    readonly fields: readonly Field[];
-}
-/** One kind of block in a `blocks` field. */
-interface Block {
-    /** Stored in each row as `blockType`. */
-    readonly slug: string;
-    readonly labels?: {
-        readonly singular?: Label;
-        readonly plural?: Label;
-    };
-    readonly fields: readonly Field[];
-}
-/**
- * A list of rows, each one of several block kinds (e.g. hero, text, gallery), for pages that
- * editors lay out themselves. Rows are `{ id, blockType, ...fields }`, stored as JSON.
- */
-interface BlocksField extends BaseField<'blocks', never> {
-    readonly blocks: readonly Block[];
-    readonly minRows?: number;
-    readonly maxRows?: number;
-}
-/** The fields `uniqueWithin` names, as a list. */
-declare const uniqueWithinOf: (field: Field) => readonly string[];
-/** Fields with `hasMany`: their value is a list of options, documents or files. */
-declare const isHasMany: (field: Field) => boolean;
-/**
- * Whether a MIME type is one of `patterns` (`image/*` matches every image but SVG, which can
- * carry scripts and is allowed only when listed by name: `image/svg+xml`).
- */
-declare function mimeAllowedBy(mimeType: string, patterns: readonly string[]): boolean;
-/** A relationship to several collections: its values are `{ relationTo, value }` (#327). */
-declare const isPolymorphic: (field: Field) => field is RelationshipField & {
-    readonly to: readonly string[];
-};
-/** The collections a relationship or upload field points to. */
-declare function relationTargets(field: Field): readonly string[];
-/** A `{ relationTo, value }` of a relationship to several collections, or `undefined`. */
-declare function polymorphicValue(value: unknown): {
-    relationTo: string;
-    value: unknown;
-} | undefined;
-/** Fields whose value is a list of rows: `array` and `blocks`. */
-declare const hasRows: (field: Field) => field is ArrayField | BlocksField;
-/** The fields of one row of an `array` or `blocks` field (`undefined` for an unknown block). */
-declare function rowFields(field: ArrayField | BlocksField, row: unknown): readonly Field[] | undefined;
-/**
- * Stores nothing: a component in the edit form (`admin.component`), e.g. a calculator, a preview
- * or a button. Placed like any field (layout, groups, conditions); not in the database, the API or
- * the generated types.
- */
-interface UiField extends BaseField<'ui', never> {
-    readonly admin: FieldAdmin & {
-        readonly component: AdminComponent;
-    };
+    /** The sender when a message has none, e.g. `Easy CMS <no-reply@example.com>`. */
+    readonly from?: string | undefined;
+    send(message: EmailMessage & {
+        readonly from: string;
+    }): Promise<void>;
+    /**
+     * The settings in use, shown to admins on Settings → Email. Never return secrets: say whether
+     * a password is set, not what it is.
+     */
+    describe?(): readonly EmailSetting[];
+    /** Checks the connection without sending (Settings → Email); throws with the reason. */
+    verify?(): Promise<void>;
 }
-type Field = CustomField | TextField | TextareaField | NumberField | BooleanField | DateField | EmailField | JsonField | SelectField | SlugField | RichTextField | UploadField | RelationshipField | ArrayField | GroupField | BlocksField | UiField;
-type FieldType = Field['type'];
-/**
- * The shortest `like` on a field with `index: 'trigram'`: trigrams are three characters, so a
- * shorter search can't use the index and would read every row.
- */
-declare const TRIGRAM_LIKE_MIN = 3;
-declare const FIELD_TYPES: readonly ["text", "textarea", "number", "boolean", "date", "email", "json", "select", "slug", "richText", "upload", "relationship", "array", "group", "blocks", "ui"];
+/** One setting an email adapter shows to admins (`describe()`). */
+interface EmailSetting {
+    /**
+     * `host`, `port`, `secure`, `user`, `password`, `from` and `delivery` (`log`: printed, not sent)
+     * are translated in the admin; others are shown as they are.
+     */
+    readonly key: string;
+    /** `null`: not set. */
+    readonly value: string | null;
+    /** Where it comes from, e.g. `SMTP_HOST` or `smtp({ host })`. */
+    readonly source?: string;
+}
+/** Prints emails to the log instead of sending them: for development and tests. */
+declare function consoleEmail(options?: {
+    from?: string;
+    log?: (text: string) => void;
+}): EmailAdapter & {
+    readonly sent: (EmailMessage & {
+        from: string;
+    })[];
+};
 
 type Simplify<T> = {
     [K in keyof T]: T[K];
@@ -1473,6 +1325,20 @@ type RichTextBlocks<C extends Config, S extends CollectionSlug<C>, F extends str
 } : never : never;
 
 type IntegrationCategory = 'social' | 'ai' | 'notifications' | 'automation';
+/**
+ * A provider's logo: SVG paths, e.g. from simple-icons. Without `fill`, a path takes `color` (the
+ * brand's), or the text color where that wouldn't show on the admin's background.
+ */
+interface IntegrationLogo {
+    readonly paths: readonly {
+        readonly d: string;
+        readonly fill?: string;
+    }[];
+    /** Default `0 0 24 24`. */
+    readonly viewBox?: string;
+    /** `#rrggbb`. */
+    readonly color?: string;
+}
 /** A value to fill when connecting (`kind: 'fields'`). */
 interface IntegrationField {
     readonly name: string;
@@ -1527,7 +1393,8 @@ interface IntegrationConfig {
     readonly label: Label;
     readonly category: IntegrationCategory;
     readonly description?: Label;
-    readonly icon?: string;
+    /** Its logo (#363), or the name of an admin icon (`ADMIN_ICONS`). Without one: its first letter. */
+    readonly icon?: string | IntegrationLogo;
     /** A link to its guide. */
     readonly docs?: string;
     /** The plugin it comes from, e.g. `@easy-cms/plugin-notify`. */
@@ -1551,10 +1418,19 @@ interface IntegrationConfig {
             redirectUri: string;
         }) => Promise<IntegrationOAuthResult> | IntegrationOAuthResult;
     };
-    /** Checks the values without posting anything. */
+    /** Checks the values without posting anything; `name` is the connection's. */
     readonly test?: (values: Readonly<Record<string, string>>, args: {
         cms: EasyCMS;
+        name?: string;
     }) => Promise<IntegrationTestResult> | IntegrationTestResult;
+    /**
+     * Asked before the first connection (#357), e.g. that text sent to an AI provider leaves the
+     * site: an admin accepts it, and who did is audit-logged.
+     */
+    readonly consent?: {
+        readonly text: Label;
+        readonly policy?: string;
+    };
 }
 /** A connection as plugins read it: its values, secrets decrypted. */
 interface IntegrationConnection {
@@ -1573,6 +1449,12 @@ interface AdminConnection {
     lastError: string | null;
     /** Plain values; secrets as `••••1234`. */
     values: Record<string, string>;
+    /** AI providers (#357): requests and tokens this month. */
+    usage?: {
+        requests: number;
+        input: number;
+        output: number;
+    };
 }
 /** A field as the admin gets it: without its functions. */
 type AdminIntegrationField = Omit<IntegrationField, 'lookup'> & {
@@ -1583,7 +1465,7 @@ interface AdminIntegration {
     label: Label;
     category: IntegrationCategory;
     description?: Label;
-    icon?: string;
+    icon?: string | IntegrationLogo;
     docs?: string;
     plugin?: string;
     kind: 'fields' | 'oauth';
@@ -1593,6 +1475,15 @@ interface AdminIntegration {
     envFields: string[];
     testable: boolean;
     connections: AdminConnection[];
+    /** Asked before the first connection; `consented` says who accepted it. */
+    consent?: {
+        text: Label;
+        policy?: string;
+    };
+    consented?: {
+        at: string;
+        by: string;
+    } | null;
 }
 /** What the code configures: shown, not changed, on the Integrations page. */
 interface ConfiguredService {
@@ -1673,6 +1564,18 @@ declare class Integrations {
     setEnabled(id: string, enabled: boolean, user: AuthUser): Promise<{
         enabled: boolean;
     }>;
+    /** Who accepted the integration's `consent`, and when; `null` before anyone did. */
+    private consented;
+    private checkConsent;
+    /** An admin accepts the integration's `consent`; audit-logged. */
+    consent(id: string, user: AuthUser): Promise<{
+        consented: {
+            at: string;
+            by: string;
+        };
+    }>;
+    /** The integration's own row (on or off, consent), made when first needed. */
+    private saveIntegration;
     /** Checks a connection's values with the provider; the card shows the result. */
     test(id: string, cid: ID | 'env'): Promise<IntegrationTestResult>;
     /**
@@ -1689,9 +1592,9 @@ declare class Integrations {
         })[];
     }>;
     /** The provider's sign-in page to send the admin to. */
-    authorize(id: string, user: AuthUser, redirectUri: string, name: string): {
+    authorize(id: string, user: AuthUser, redirectUri: string, name: string): Promise<{
         url: string;
-    };
+    }>;
     /**
      * Back from the provider: one account is connected at once; several wait (encrypted, 10
      * minutes) for the admin to choose. Returns where the admin goes next.
@@ -1750,6 +1653,8 @@ interface RolePermissions {
         readonly collections?: FieldRules;
         readonly globals?: FieldRules;
     };
+    /** AI requests a user of the role makes a day (with `ai`); 0: none. Unset: everyone's limit. */
+    readonly aiPerDay?: number;
 }
 /** One role as Settings → Roles shows it (`GET <api>/admin/roles`). */
 interface AdminRole {
@@ -1799,6 +1704,8 @@ interface AdminRoles {
     })[];
     globals: AdminRoleTarget[];
     views: AdminRoleView[];
+    /** Roles can be given a daily AI limit (`ai` in the config). */
+    ai: boolean;
 }
 /** One change to a role (`GET <api>/admin/roles/:id/history`). */
 interface AdminRoleChange {
@@ -1898,6 +1805,8 @@ declare class Roles {
     /** Sets one field of every matching document, keeping the rest as stored. */
     private setWhere;
     private cleanName;
+    /** The role's daily AI limit set in Settings → Roles, if any (`auth.rbac`). */
+    aiLimit(key: string): Promise<number | undefined>;
     private permissionsOf;
     private load;
     private rows;
@@ -2220,6 +2129,8 @@ declare class EasyCMS<C extends Config = Config> {
     readonly folders: MediaFolders;
     /** Accounts connected to plugins' integrations (`integrations`, Settings → Integrations). */
     readonly integrations: Integrations;
+    /** AI for the admin's features (#357): `null` without an AI plugin (`ai` in the config). */
+    readonly ai: Ai | null;
     private readonly versions;
     private readonly webhooks;
     private readonly mailer;
@@ -2770,155 +2681,472 @@ interface LivePreview<T> {
     /** From the collection's `preview` function; `null` without one. */
     readonly url: string | null;
 }
-
-/** Audit log settings (`audit`). */
-interface AuditConfig {
-    /** Days to keep entries; older ones are deleted. `0`: keep them all. Default 365. */
-    readonly keepDays?: number;
-    /** Keep the values before and after a change, not only which fields changed. Default `true`. */
-    readonly values?: boolean;
-    /** Failed logins within an hour that the dashboard warns about. Default 20. */
-    readonly failedLogins?: number;
+
+/** A label shown in the admin UI. Either one string or one string per admin locale. */
+type Label = string | {
+    readonly [locale: string]: string;
+};
+interface FieldValidateContext {
+    /** The whole document being validated, including sibling fields. */
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly operation: 'create' | 'update';
+}
+/** Return `true` when valid, or an error message to show on the field. */
+type FieldValidate<TValue> = (value: TValue | null | undefined, ctx: FieldValidateContext) => true | string | Promise<true | string>;
+/**
+ * A Web Component from an admin module (`admin.modules`), by its tag name, which must start
+ * with `ecms-`. `props` (plain JSON) reach the element as its `options` property.
+ */
+type AdminComponent = string | {
+    readonly tag: string;
+    readonly props?: Readonly<Record<string, unknown>>;
+};
+/** How the admin shows a field, with components from admin modules. */
+interface FieldAdmin {
+    /** Help below the field's label. */
+    readonly description?: Label;
+    /** Its share of a row (`admin.layout`'s `row`). Default: an equal share. */
+    readonly width?: '1/4' | '1/3' | '1/2' | '2/3' | '3/4' | 'full';
+    /**
+     * Shown only when its sibling fields match, e.g. `{ field: 'linkType', equals: 'external' }`.
+     * A hidden field isn't required. See `FieldCondition`.
+     */
+    readonly condition?: FieldCondition;
+    /** Shown instead of the field's input; the admin keeps the label and error messages. */
+    readonly component?: AdminComponent;
+    /** Shown below the field, e.g. a length meter or a preview. */
+    readonly after?: readonly AdminComponent[];
+    /** Shows the value in the admin's lists (e.g. a color swatch). Default: the plain value. */
+    readonly cell?: AdminComponent;
+    /**
+     * A column of the list at first (each user can change it): `true`, or per request, e.g.
+     * only when the admin shows every tenant.
+     */
+    readonly column?: boolean | ((args: AdminFieldArgs) => boolean | Promise<boolean>);
+    /** Relationships: offer to create the related document in place. Default true. */
+    readonly allowCreate?: boolean;
+    /**
+     * The value a new document's form starts with, worked out for each user, e.g. from the
+     * request's context. The server's own default (`defaultValue`, hooks) still applies.
+     */
+    readonly initialValue?: (args: AdminFieldArgs) => unknown;
+    /** `sidebar`: shown in the edit page's side panel instead of the main form (top-level fields). */
+    readonly position?: 'sidebar';
+    /** `false`: the list's filters don't offer it. Default: every field the user may read. */
+    readonly filter?: boolean;
+}
+/** What per-request admin options of a field receive. */
+interface AdminFieldArgs {
+    readonly user: AuthUser;
+    readonly context: RequestContext;
+}
+/**
+ * Field types that packages add (`fieldTypes` in the config), for the types inferred from the
+ * config. A package declares its own by augmenting this interface:
+ *
+ * ```ts
+ * declare module '@easy-cms/core' {
+ *   interface CustomFieldTypes {
+ *     color: { value: string; options: { readonly presets?: readonly string[] } }
+ *   }
+ * }
+ * ```
+ */
+interface CustomFieldTypes {
+}
+/** A field of a type from `CustomFieldTypes`: the common options, plus the type's own. */
+type CustomField = {
+    [K in keyof CustomFieldTypes]: BaseField<K & string, CustomFieldTypes[K] extends {
+        value: infer V;
+    } ? V : unknown> & (CustomFieldTypes[K] extends {
+        options: infer O;
+    } ? O : unknown);
+}[keyof CustomFieldTypes];
+interface BaseField<TType extends string, TValue> {
+    readonly type: TType;
+    readonly name: string;
+    readonly label?: Label;
+    readonly required?: boolean;
+    readonly unique?: boolean;
+    /**
+     * With `unique` (or on a slug field): a sibling field (e.g. `parent` or `tenant`), or several,
+     * whose documents only need to differ among themselves, so `/about/team` and `/careers/team`
+     * can both be `team`. Single, unlocalized relationship, select, text or number fields.
+     */
+    readonly uniqueWithin?: string | readonly string[];
+    /**
+     * `true` for a database index (filters and sorts on this field). `'trigram'`, on text, textarea
+     * and email fields: an index for `like`, which finds any part of the text, in Thai as in other
+     * languages. Postgres only (pg_trgm); nothing on SQLite. There, `like` needs at least three
+     * characters, and the admin's searches wait for them.
+     */
+    readonly index?: boolean | 'trigram';
+    readonly defaultValue?: TValue;
+    readonly validate?: FieldValidate<TValue>;
+    readonly access?: FieldAccess;
+    /** Stored but never returned by the API nor accepted as input (e.g. a password hash). */
+    readonly hidden?: boolean;
+    /**
+     * One value per locale (needs `localization` in the config). Not for groups, arrays or
+     * hasMany fields: localize the fields inside a group or array instead.
+     */
+    readonly localized?: boolean;
+    /** How the field looks in the admin: components, position, width, conditions. */
+    readonly admin?: FieldAdmin;
+    /** Set by Easy CMS on fields of an added type (`fieldTypes`): the type's name, e.g. `color`. */
+    readonly customType?: string;
+}
+interface TextField extends BaseField<'text', string> {
+    readonly minLength?: number;
+    readonly maxLength?: number;
+}
+interface TextareaField extends BaseField<'textarea', string> {
+    readonly minLength?: number;
+    readonly maxLength?: number;
+}
+interface NumberField extends BaseField<'number', number> {
+    readonly min?: number;
+    readonly max?: number;
+}
+interface BooleanField extends BaseField<'boolean', boolean> {
+}
+/** Stored and returned as an ISO 8601 string. */
+interface DateField extends BaseField<'date', string> {
+}
+interface EmailField extends BaseField<'email', string> {
+}
+interface JsonField extends BaseField<'json', unknown> {
+}
+type SelectOption = string | {
+    readonly label: Label;
+    readonly value: string;
+};
+interface SelectField extends BaseField<'select', string | readonly string[]> {
+    readonly options: readonly SelectOption[];
+    readonly hasMany?: boolean;
+}
+interface SlugField extends BaseField<'slug', string> {
+    /** Name of a sibling `text` field to generate the slug from. */
+    readonly from?: string;
+}
+/** Tiptap / ProseMirror JSON document. */
+interface RichTextDocument {
+    readonly type: 'doc';
+    readonly content?: readonly unknown[];
+}
+interface RichTextField extends BaseField<'richText', RichTextDocument> {
+    /**
+     * Blocks editors place between paragraphs (#328): a card, a callout, a video. Each is a node
+     * `{ type: 'block', attrs: { blockType, id, fields } }` in the document.
+     */
+    readonly blocks?: readonly RichTextBlock[];
+}
+/** Arguments of a rich text block's `admin.summary` function. */
+interface BlockSummaryArgs {
+    readonly fields: Record<string, unknown>;
+    readonly user: AuthUser | null;
+    readonly cms: EasyCMS;
+}
+/** A block in rich text (`richText.blocks`): the fields of `Block`, and how its card reads. */
+interface RichTextBlock extends Block {
+    readonly admin?: {
+        /**
+         * The text of the block's card in the editor: a function, run on the server, or the tag of a
+         * custom element from an admin module, which gets `fields`. Default: the block's label and
+         * its first value.
+         */
+        readonly summary?: string | ((args: BlockSummaryArgs) => string | Promise<string>);
+    };
+}
+/** References a document in the built-in `media` collection: a file or an image. */
+interface UploadField extends BaseField<'upload', never> {
+    /** Several files, e.g. a gallery: the value is a list, in the order editors arrange. */
+    readonly hasMany?: boolean;
+    /** With `hasMany`: the fewest files. */
+    readonly minRows?: number;
+    /** With `hasMany`: the most files. */
+    readonly maxRows?: number;
+    /**
+     * The file types allowed, e.g. `['image/*']` or `['image/*', 'application/pdf']`. The admin
+     * offers only these, and saving refuses others.
+     */
+    readonly mimeTypes?: readonly string[];
+    /**
+     * With `upload.folders`: the `key` of the media folder this field's files go in, e.g.
+     * `'banners'`. Its picker opens there and its uploads land there; the folder is made when it
+     * is first needed.
+     */
+    readonly folder?: string;
+    /** With `folder`: only files in that folder (and its subfolders) may be chosen. */
+    readonly folderOnly?: boolean;
+    /** Which media documents may be chosen, as for relationships: offered and checked on save. */
+    readonly filterOptions?: FilterOptions;
+}
+interface FilterOptionsArgs {
+    /** The document being edited; `undefined` while it is being created. */
+    readonly id: ID | undefined;
+    /** The collection the choices come from: one of the field's `to`. */
+    readonly relationTo: string;
+    readonly user: AuthUser | null;
+    readonly cms: EasyCMS;
+    /** The request's context (`onRequest`), `{}` when there is none. */
+    readonly context: RequestContext;
+}
+/**
+ * Which documents a relationship may point to: a `where` on the target collection, or `true`
+ * for any. Runs on the server: the admin's picker offers only these, and saving checks them.
+ */
+type FilterOptions = (args: FilterOptionsArgs) => Where | true | Promise<Where | true>;
+interface RelationshipField extends BaseField<'relationship', never> {
     /**
-     * The part of the site an entry belongs to, from the request's context, e.g. its tenant
-     * (usually set by a plugin). Users whose role holds in a part only (`scoped`) see that part's
-     * entries; others see the chosen part's, or all.
+     * Slug of the target collection, or several: then each value is `{ relationTo, value }`, the
+     * collection and the document's id (#327).
      */
-    readonly scope?: ((args: {
-        readonly context: RequestContext;
-        readonly user: AuthUser | null;
-    }) => string | null | undefined) | false;
+    readonly to: string | readonly string[];
+    readonly hasMany?: boolean;
+    /** With `hasMany`: the fewest documents. */
+    readonly minRows?: number;
+    /** With `hasMany`: the most documents. */
+    readonly maxRows?: number;
+    readonly filterOptions?: FilterOptions;
 }
-/** A field that changed: values before and after, unless they are not kept. */
-interface AuditChange {
-    field: string;
-    before?: unknown;
-    after?: unknown;
+interface ArrayField extends BaseField<'array', never> {
+    readonly fields: readonly Field[];
+    readonly minRows?: number;
+    readonly maxRows?: number;
 }
-/** One entry (`GET <api>/admin/audit`). */
-interface AuditEntry {
-    id: ID;
-    /** When, as an ISO date. */
-    at: string;
-    /** E.g. `create`, `update`, `publish`, `delete`, `login`, `login.failed`, `role.update`. */
-    action: string;
-    /** A collection slug, `global:<slug>`, or an area such as `auth`, `roles`, `backups`. */
-    target: string | null;
-    /** The document's id. */
-    doc: string | null;
-    /** The document's title then (kept after it is deleted). */
-    title: string | null;
-    actor: {
-        id: string | null;
-        email: string | null;
-        /** `user` (admin or REST), `api-key`, `system` (code), `scheduler`. */
-        via: string;
-        ip: string | null;
-        userAgent: string | null;
+interface GroupField extends BaseField<'group', never> {
+    readonly fields: readonly Field[];
+}
+/** One kind of block in a `blocks` field. */
+interface Block {
+    /** Stored in each row as `blockType`. */
+    readonly slug: string;
+    readonly labels?: {
+        readonly singular?: Label;
+        readonly plural?: Label;
     };
-    changes: AuditChange[] | null;
-    detail: Record<string, unknown> | null;
+    readonly fields: readonly Field[];
 }
-/** `GET <api>/admin/audit`: a page of entries, newest first. */
-/** A page of the audit log: the list shape of the rest of the API. */
-type AuditPage = PaginatedDocs<AuditEntry>;
-interface AuditFilter {
-    action?: string | null;
-    target?: string | null;
-    doc?: string | null;
-    /** An email, or part of one. */
-    actor?: string | null;
-    /** ISO dates. */
-    from?: string | null;
-    to?: string | null;
-    /** Only entries of this part of the site (`scope`). */
-    scope?: string | null;
+/**
+ * A list of rows, each one of several block kinds (e.g. hero, text, gallery), for pages that
+ * editors lay out themselves. Rows are `{ id, blockType, ...fields }`, stored as JSON.
+ */
+interface BlocksField extends BaseField<'blocks', never> {
+    readonly blocks: readonly Block[];
+    readonly minRows?: number;
+    readonly maxRows?: number;
 }
-/** `POST <api>/admin/audit/verify`. */
-interface AuditVerification {
-    checked: number;
-    /** Entries whose signature does not match: changed after they were written. */
-    invalid: ID[];
-    /**
-     * Missing ids between entries: deleted entries, or (rarely) inserts that failed. Ids are never
-     * reused, so the newest entries deleted show up here once anything is written after them (a
-     * check writes an entry itself). The server's log has each check's last id, to compare with.
-     */
-    gaps: number;
-    at: string;
+/** The fields `uniqueWithin` names, as a list. */
+declare const uniqueWithinOf: (field: Field) => readonly string[];
+/** Fields with `hasMany`: their value is a list of options, documents or files. */
+declare const isHasMany: (field: Field) => boolean;
+/**
+ * Whether a MIME type is one of `patterns` (`image/*` matches every image but SVG, which can
+ * carry scripts and is allowed only when listed by name: `image/svg+xml`).
+ */
+declare function mimeAllowedBy(mimeType: string, patterns: readonly string[]): boolean;
+/** A relationship to several collections: its values are `{ relationTo, value }` (#327). */
+declare const isPolymorphic: (field: Field) => field is RelationshipField & {
+    readonly to: readonly string[];
+};
+/** The collections a relationship or upload field points to. */
+declare function relationTargets(field: Field): readonly string[];
+/** A `{ relationTo, value }` of a relationship to several collections, or `undefined`. */
+declare function polymorphicValue(value: unknown): {
+    relationTo: string;
+    value: unknown;
+} | undefined;
+/** Fields whose value is a list of rows: `array` and `blocks`. */
+declare const hasRows: (field: Field) => field is ArrayField | BlocksField;
+/** The fields of one row of an `array` or `blocks` field (`undefined` for an unknown block). */
+declare function rowFields(field: ArrayField | BlocksField, row: unknown): readonly Field[] | undefined;
+/**
+ * Stores nothing: a component in the edit form (`admin.component`), e.g. a calculator, a preview
+ * or a button. Placed like any field (layout, groups, conditions); not in the database, the API or
+ * the generated types.
+ */
+interface UiField extends BaseField<'ui', never> {
+    readonly admin: FieldAdmin & {
+        readonly component: AdminComponent;
+    };
 }
+type Field = CustomField | TextField | TextareaField | NumberField | BooleanField | DateField | EmailField | JsonField | SelectField | SlugField | RichTextField | UploadField | RelationshipField | ArrayField | GroupField | BlocksField | UiField;
+type FieldType = Field['type'];
 /**
- * The audit log (`audit` in the config): who did what, when, from where. Entries can't be
- * changed through Easy CMS; each is signed with the secret, so changes in the database show.
- * Available as `cms.audit`.
+ * The shortest `like` on a field with `index: 'trigram'`: trigrams are three characters, so a
+ * shorter search can't use the index and would read every row.
  */
-declare class AuditLog {
+declare const TRIGRAM_LIKE_MIN = 3;
+declare const FIELD_TYPES: readonly ["text", "textarea", "number", "boolean", "date", "email", "json", "select", "slug", "richText", "upload", "relationship", "array", "group", "blocks", "ui"];
+
+/** What a provider is asked: the prompt, images as base64, and a JSON schema for the answer. */
+interface AiProviderRequest {
+    readonly system?: string;
+    readonly prompt: string;
+    readonly images: readonly {
+        readonly data: string;
+        readonly mediaType: string;
+    }[];
+    /** A JSON schema: the answer is JSON of this shape. */
+    readonly json?: Readonly<Record<string, unknown>>;
+    readonly maxTokens: number;
+    readonly signal: AbortSignal;
+}
+interface AiProviderResult {
+    readonly text: string;
+    readonly usage: {
+        readonly input: number;
+        readonly output: number;
+    };
+}
+/** A provider's refusal: `status` says whether to retry (429, 5xx) or the key is wrong (401, 403). */
+declare class AiProviderError extends Error {
+    readonly status: number | undefined;
+    constructor(message: string, status?: number);
+}
+/** A provider a plugin adds: its integration (fields, Test) and how it answers. */
+interface AiProvider {
+    /** The id of the integration whose connections it answers with, e.g. `anthropic`. */
+    readonly integration: string;
+    readonly generate: (values: Readonly<Record<string, string>>, request: AiProviderRequest) => Promise<AiProviderResult>;
+}
+/** `ai` in the config, set by the AI plugin. */
+interface AiConfig {
+    readonly providers: readonly AiProvider[];
+    readonly limits?: {
+        /** Requests a user makes a day (in `timeZone`). Admins can change it. Default 100. */
+        readonly perUserPerDay?: number;
+        /** Per role, e.g. `{ editor: 50 }`; 0 keeps a role from using AI. Settings → Roles wins. */
+        readonly roles?: Readonly<Record<string, number>>;
+    };
+}
+/** A feature that uses AI (`aiFeatures` in the config): admins turn it off or pick its connection. */
+interface AiFeatureConfig {
+    /** Lowercase letters, digits and `-`, e.g. `alt-text`. */
+    readonly id: string;
+    readonly label: Label;
+    readonly description?: Label;
+    /** On until an admin turns it off. Default true. */
+    readonly default?: boolean;
+}
+interface AiImage {
+    /** A media document: its smallest size at least 1024 pixels wide, or the file. */
+    readonly media?: ID;
+    /** Or the image itself, as base64. */
+    readonly data?: string;
+    readonly mediaType?: string;
+}
+interface AiRequest {
+    /** The feature asking (`aiFeatures`): it must be on. */
+    readonly feature: string;
+    readonly system?: string;
+    readonly prompt: string;
+    readonly images?: readonly AiImage[];
+    /** A JSON schema: the answer is parsed into `json`. */
+    readonly json?: Readonly<Record<string, unknown>>;
+    /** Default 1024. */
+    readonly maxTokens?: number;
+}
+interface AiResult {
+    readonly text: string;
+    readonly json?: unknown;
+    readonly usage: {
+        readonly input: number;
+        readonly output: number;
+    };
+    /** The connection that answered, e.g. `anthropic:Main`. */
+    readonly connection: string;
+}
+interface AdminAi {
+    main: string | null;
+    perUserPerDay: number;
+    /** The config's, for "back to the default". */
+    defaultPerUserPerDay: number;
+    connections: {
+        id: string;
+        integration: string;
+        name: string;
+        label: Label;
+    }[];
+    features: {
+        id: string;
+        label: Label;
+        description?: Label;
+        enabled: boolean;
+        connection: string | null;
+    }[];
+    /** This month, in `timeZone`. */
+    usage: {
+        byUser: {
+            user: string;
+            requests: number;
+            input: number;
+            output: number;
+        }[];
+        byFeature: {
+            feature: string;
+            requests: number;
+            input: number;
+            output: number;
+        }[];
+    };
+}
+declare class Ai {
     private readonly cms;
-    /** Entries that could not be written since the server started. */
-    failures: number;
-    constructor(cms: EasyCMS);
-    get enabled(): boolean;
-    private get settings();
-    /**
-     * Writes an entry. The user defaults to the request's. Never throws: a failure is logged and
-     * counted, and the dashboard says so.
-     */
-    record(entry: {
-        action: string;
-        target?: string | null;
-        doc?: ID | null;
-        title?: string | null;
-        user?: AuthUser | null;
-        /** Who it was when there is no user, e.g. the email of a failed login. */
-        email?: string | null;
-        changes?: AuditChange[] | null;
-        detail?: Record<string, unknown> | null;
-        /** The call's context, when it is not the request's. */
-        context?: RequestContext;
-    }): Promise<void>;
-    /** Entries, newest first: `page` (from 1) of `limit` (default 50, at most 100). */
-    list(options?: AuditFilter & {
-        page?: number;
-        limit?: number;
-    }): Promise<AuditPage>;
-    /** The filtered entries as CSV (the newest 10,000). */
-    csv(filter: AuditFilter): Promise<string>;
-    /** Checks every entry's signature, and that no ids are missing. */
-    verify(): Promise<AuditVerification>;
-    /** The secret an entry was signed with: the current one, a previous one, or none (changed). */
-    private signer;
-    /**
-     * After `secret` changed: signs again, with the current secret, the entries signed with one of
-     * `previousSecrets`, so they still verify once it is removed. Entries no secret verifies were
-     * changed: they are left as they are, and reported. Records `audit.resign`.
-     */
-    resign(): Promise<{
-        checked: number;
-        resigned: number;
-        invalid: ID[];
+    private readonly ai;
+    constructor(cms: EasyCMS, ai: AiConfig);
+    private get config();
+    private get defaultLimit();
+    /** The features of the config. */
+    get features(): readonly AiFeatureConfig[];
+    private settingsRow;
+    private settings;
+    /** Every connection of every provider, in the providers' order. */
+    private connections;
+    /** Whether a feature is on: admins' choice, else its `default`. */
+    enabled(feature: string): Promise<boolean>;
+    /** Requests a user may make today: their role's, else everyone's. */
+    limitFor(user: AuthUser): Promise<number>;
+    /** Requests the user made today (in `timeZone`) and how many are left. */
+    remaining(user: AuthUser, now?: Date): Promise<{
+        used: number;
+        limit: number;
     }>;
     /**
-     * What the dashboard warns about: many failed logins, sign-ins of break-glass accounts in the
-     * last day, entries not written, a failed check.
+     * Asks the feature's connection (or the main one). With `user`, the request counts toward their
+     * daily limit; it is refused once they reach it. Usage is recorded, never the prompt.
      */
-    attention(now?: Date): Promise<({
-        id: 'failed-logins';
-        count: number;
-    } | {
-        id: 'break-glass';
-        count: number;
-        emails: string[];
-    } | {
-        id: 'audit-failures';
-        count: number;
-    } | {
-        id: 'audit-tampered';
-        invalid: number;
-        at: string;
-    })[]>;
-    private sign;
-    private lastVerification;
-    private where;
+    generate(request: AiRequest, options?: {
+        user?: AuthUser | null;
+        about?: {
+            collection: string;
+            id: ID;
+        };
+    }): Promise<AiResult>;
+    /**
+     * The Test button of a provider's connection: a short prompt; its tokens count on the card,
+     * not toward anyone's limit.
+     */
+    test(integration: string, values: Readonly<Record<string, string>>, name?: string): Promise<IntegrationTestResult>;
+    private connectionFor;
+    private ask;
+    /** One try, and another after a second when the provider is busy or failing (429, 5xx). */
+    private call;
+    /** An image as base64: given, or read from a media document. */
+    private image;
+    /** Settings → Integrations, AI: the main connection, the features, the limit and this month. */
+    overview(now?: Date): Promise<AdminAi>;
+    /** Tokens and requests of each connection this month, for the cards. */
+    usageByConnection(now?: Date): Promise<Map<string, {
+        requests: number;
+        input: number;
+        output: number;
+    }>>;
+    /** Saves admins' choices; audit-logged. */
+    update(body: unknown, user: AuthUser): Promise<AdminAi>;
+    /** Forgets usage older than 90 days (with the scheduled jobs). */
+    upkeep(now?: Date): Promise<void>;
 }
 
 /** What the email functions in `auth.emails` receive. */
@@ -4189,9 +4417,19 @@ interface Config {
      * by plugins: a Telegram bot, an AI provider, a Facebook Page. See `IntegrationConfig`.
      */
     readonly integrations?: readonly IntegrationConfig[];
+    /**
+     * AI providers and limits (#357), set by `@easy-cms/plugin-ai`: `cms.ai` answers the admin's AI
+     * features with them. See `AiConfig`.
+     */
+    readonly ai?: AiConfig;
+    /**
+     * Features that use AI, added by plugins and by Easy CMS itself: admins turn each off or pick
+     * the connection it uses on the Integrations page. See `AiFeatureConfig`.
+     */
+    readonly aiFeatures?: readonly AiFeatureConfig[];
 }
 /** 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' | 'audit' | 'integrations'> {
+interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes' | 'admin' | 'upload' | 'auth' | 'collections' | 'globals' | 'endpoints' | 'plugins' | 'audit' | 'integrations' | 'aiFeatures'> {
     readonly cors: readonly string[] | '*';
     /** `null` without localization. */
     readonly localization: Required<LocalizationConfig> | null;
@@ -4205,6 +4443,7 @@ interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes'
     readonly globals: readonly GlobalConfig[];
     readonly endpoints: readonly Endpoint[];
     readonly integrations: readonly IntegrationConfig[];
+    readonly aiFeatures: readonly AiFeatureConfig[];
     readonly cliCommands: readonly CliCommand[];
     readonly events: readonly string[];
     readonly jobs: readonly JobConfig[];
@@ -4220,5 +4459,5 @@ interface ResolvedConfig extends Omit<Config, 'cors' | 'localization' | 'routes'
  */
 declare function defineConfig<const TConfig extends Config>(config: TConfig): TConfig;
 
-export { ADAPTER_API_VERSION as A, EasyCMS as E, AuditLog as _, Auth as a1, EasyCMSError as aK, FIELD_TYPES as aT, ConfigError as at, NotFoundError as bI, PLUGIN_API_VERSION as bO, PayloadTooLargeError as bT, QueryError as bZ, ROLE_OPERATIONS as b_, ForbiddenError as bb, definePlugin as c$, TooManyRequestsError as cD, UnauthorizedError as cG, ValidationError as cN, WEBHOOK_EVENTS as cR, anyone as cV, consoleEmail as cW, consoleLogger as cX, createEasyCMS as cY, defineConfig as cZ, defineFieldType as c_, Roles as ca, SchemaError as cd, SingleSignOn as cs, TRIGRAM_LIKE_MIN as cz, diskStorage as d0, hasRows as d1, isAdmin as d2, isHasMany as d3, isPolymorphic as d4, isSignedIn as d5, isStaff as d6, isSystemAdmin as d7, jsonLogger as d8, memorySearch as d9, mimeAllowedBy as da, polymorphicValue as db, relationTargets as dc, rowFields as dd, silentLogger as de, uniqueWithinOf as df, API_KEYS as dg, API_KEY_GLOBAL_OPERATIONS as dh, API_KEY_OPERATIONS as di, DEFAULT_MAX_VERSIONS as dj, DEFAULT_PASSWORD_EMAILS as dk, FIELD_TYPE_BASES as dl, FOLDER_LEVELS as dm, MediaFolders as dn, SSO_COOKIE as dp, codeOfStatus as dr, isJsonLogger as ds, keyAllows as dt, logFormat as du, secretsOf as dv, ADMIN_ICONS as j };
-export type { AuditPage as $, AdminRoles as B, Config as C, AdminSso as D, Field as F, GlobalSlug as G, AdminSwitcher as H, ID as I, AdminViewAccess as J, AfterChangeHook as K, LocalizationConfig as L, AfterDeleteHook as M, AfterReadHook as N, ApiKeyContext as O, PaginatedDocs as P, ApiKeyGlobalOperation as Q, ResolvedConfig as R, ApiKeyOperation as S, ApiKeyPermissions as T, UncountedDocs as U, ArrayField as V, Where as W, AuditChange as X, AuditConfig as Y, AuditEntry as Z, CollectionSlug as a, FieldTypeValidateContext as a$, AuditVerification as a0, AuthConfig as a2, AuthProvider as a3, AuthProviderProfile as a4, AuthProviderRequest as a5, AuthUser as a6, BackupsConfig as a7, BeforeChangeHook as a8, BeforeDeleteHook as a9, DashboardWidget as aA, Database as aB, DatabaseAdapter as aC, DatabaseInitArgs as aD, DatabaseTransfer as aE, DateField as aF, DepthOptions as aG, DirectUpload as aH, DiskStorageOptions as aI, DocumentOf as aJ, EmailAdapter as aL, EmailField as aM, EmailMessage as aN, Endpoint as aO, EndpointRequest as aP, ErrorCode as aQ, EventListener as aR, EventMessage as aS, FieldAccess as aU, FieldAccessFn as aV, FieldAdmin as aW, FieldRule as aX, FieldType as aY, FieldTypeBase as aZ, FieldTypeDefinition as a_, BeforeValidateHook as aa, Block as ab, BlockSummaryArgs as ac, BlocksField as ad, BooleanField as ae, BuiltinApiKeysCollection as af, BuiltinMediaCollection as ag, BuiltinMediaFoldersCollection as ah, BuiltinUsersCollection as ai, BundleHints as aj, CliCommand as ak, CollectionAccess as al, CollectionAdmin as am, CollectionCalendarAdmin as an, CollectionConfig as ao, CollectionHooks as ap, CollectionListAdmin as aq, CollectionSearch as ar, CollectionView as as, ConfigIssue as au, ContainerAdmin as av, CreateInput as aw, CreateMigrationResult as ax, CustomField as ay, CustomFieldTypes as az, CollectionDocument as b, RawDocument as b$, FieldValidate as b0, FieldValidateContext as b1, FieldValue as b2, FieldsInput as b3, FieldsValue as b4, FilterOptionsArgs as b5, FindAfterArgs as b6, FindArgs as b7, FindOptions as b8, FolderLevel as b9, LoginArgs as bA, LogsConfig as bB, MediaDocument as bC, MediaSize as bD, MembersConfig as bE, MembersSignup as bF, MigrationInfo as bG, NavGroup as bH, NumberField as bJ, OnRequest as bK, OnRequestArgs as bL, Operation as bM, OutboxRow as bN, PasswordEmail as bP, PasswordEmailArgs as bQ, PasswordEmailFn as bR, PasswordLinkOptions as bS, Plugin as bU, PluginInfo as bV, PluginTypes as bW, PreviewTarget as bX, PreviewURL as bY, FolderPermissions as ba, GlobalAccess as bc, GlobalConfig as bd, GlobalHooks as be, GlobalInput as bf, GroupField as bg, ImageSize as bh, IncrementOptions as bi, InferCollection as bj, InferGlobal as bk, IntegrationCategory as bl, IntegrationConfig as bm, IntegrationConnection as bn, IntegrationField as bo, IntegrationOAuthResult as bp, IntegrationTestResult as bq, JobConfig as br, JsonField as bs, KeysetPage as bt, Label as bu, LayoutNode as bv, LivePreview as bw, LocaleOf as bx, LogDetails as by, Logger as bz, CursorDocs as c, ReadOptions as c0, RelationshipField as c1, RequestContext as c2, RichTextBlock as c3, RichTextBlocks as c4, RichTextDocument as c5, RichTextField as c6, Role as c7, RoleOperation as c8, RolePermissions as c9, TelemetryConfig as cA, TextField as cB, TextareaField as cC, TypedPlugin as cE, UiField as cF, UpdateInput as cH, UpdateOptions as cI, UploadConfig as cJ, UploadField as cK, UploadFromURLConfig as cL, UserIdentity as cM, Version as cO, VersionSummary as cP, VersionsConfig as cQ, WebhookConfig as cS, WebhookEvent as cT, WhereOperators as cU, RoutesConfig as cb, ScheduledPublish as cc, SchemaMode as ce, SearchAdapter as cf, SearchEntry as cg, SearchHits as ch, SearchOptions as ci, SearchQuery as cj, SearchResults as ck, SearchSetting as cl, SelectField as cm, SelectOption as cn, Session as co, SidebarPanel as cp, SignupArgs as cq, SignupResult as cr, SlugField as ct, SlugOf as cu, SsoOutcome as cv, SsoProviderRef as cw, StorageAdapter as cx, StoredFile as cy, GlobalDocument as d, Secrets as dq, FieldError as e, FilterOptions as f, CreateEasyCMSOptions as g, EmailSetting as h, WebhookPayload as i, Access as k, AccessArgs as l, AccessOptions as m, AdminBrand as n, AdminCommand as o, AdminComponent as p, AdminConfig as q, AdminFieldArgs as r, AdminIcon as s, AdminLocale as t, AdminPage as u, AdminRole as v, AdminRoleChange as w, AdminRoleField as x, AdminRoleTarget as y, AdminRoleView as z };
+export { ADAPTER_API_VERSION as A, EasyCMS as E, Ai as Q, AiProviderError as Y, AuditLog as a9, ConfigError as aE, EasyCMSError as aV, Auth as ac, FIELD_TYPES as b2, NotFoundError as bU, PLUGIN_API_VERSION as b_, ForbiddenError as bm, PayloadTooLargeError as c3, QueryError as c9, SingleSignOn as cE, TRIGRAM_LIKE_MIN as cL, TooManyRequestsError as cP, UnauthorizedError as cS, ValidationError as cZ, ROLE_OPERATIONS as ca, Roles as cm, SchemaError as cp, WEBHOOK_EVENTS as d1, anyone as d5, consoleEmail as d6, consoleLogger as d7, createEasyCMS as d8, defineConfig as d9, MediaFolders as dA, SSO_COOKIE as dB, codeOfStatus as dD, isJsonLogger as dE, keyAllows as dF, logFormat as dG, secretsOf as dH, defineFieldType as da, definePlugin as db, diskStorage as dc, hasRows as dd, isAdmin as de, isHasMany as df, isPolymorphic as dg, isSignedIn as dh, isStaff as di, isSystemAdmin as dj, jsonLogger as dk, memorySearch as dl, mimeAllowedBy as dm, polymorphicValue as dn, relationTargets as dp, rowFields as dq, silentLogger as dr, uniqueWithinOf as ds, API_KEYS as dt, API_KEY_GLOBAL_OPERATIONS as du, API_KEY_OPERATIONS as dv, DEFAULT_MAX_VERSIONS as dw, DEFAULT_PASSWORD_EMAILS as dx, FIELD_TYPE_BASES as dy, FOLDER_LEVELS as dz, ADMIN_ICONS as j };
+export type { AiRequest as $, AdminRoleView as B, Config as C, AdminRoles as D, Field as F, GlobalSlug as G, AdminSso as H, ID as I, AdminSwitcher as J, AdminViewAccess as K, LocalizationConfig as L, AfterChangeHook as M, AfterDeleteHook as N, AfterReadHook as O, PaginatedDocs as P, ResolvedConfig as R, AiConfig as S, AiFeatureConfig as T, UncountedDocs as U, AiImage as V, Where as W, AiProvider as X, AiProviderRequest as Z, AiProviderResult as _, CollectionSlug as a, ErrorCode as a$, AiResult as a0, ApiKeyContext as a1, ApiKeyGlobalOperation as a2, ApiKeyOperation as a3, ApiKeyPermissions as a4, ArrayField as a5, AuditChange as a6, AuditConfig as a7, AuditEntry as a8, CollectionHooks as aA, CollectionListAdmin as aB, CollectionSearch as aC, CollectionView as aD, ConfigIssue as aF, ContainerAdmin as aG, CreateInput as aH, CreateMigrationResult as aI, CustomField as aJ, CustomFieldTypes as aK, DashboardWidget as aL, Database as aM, DatabaseAdapter as aN, DatabaseInitArgs as aO, DatabaseTransfer as aP, DateField as aQ, DepthOptions as aR, DirectUpload as aS, DiskStorageOptions as aT, DocumentOf as aU, EmailAdapter as aW, EmailField as aX, EmailMessage as aY, Endpoint as aZ, EndpointRequest as a_, AuditPage as aa, AuditVerification as ab, AuthConfig as ad, AuthProvider as ae, AuthProviderProfile as af, AuthProviderRequest as ag, AuthUser as ah, BackupsConfig as ai, BeforeChangeHook as aj, BeforeDeleteHook as ak, BeforeValidateHook as al, Block as am, BlockSummaryArgs as an, BlocksField as ao, BooleanField as ap, BuiltinApiKeysCollection as aq, BuiltinMediaCollection as ar, BuiltinMediaFoldersCollection as as, BuiltinUsersCollection as at, BundleHints as au, CliCommand as av, CollectionAccess as aw, CollectionAdmin as ax, CollectionCalendarAdmin as ay, CollectionConfig as az, CollectionDocument as b, PasswordEmail as b$, EventListener as b0, EventMessage as b1, FieldAccess as b3, FieldAccessFn as b4, FieldAdmin as b5, FieldRule as b6, FieldType as b7, FieldTypeBase as b8, FieldTypeDefinition as b9, IntegrationLogo as bA, IntegrationOAuthResult as bB, IntegrationTestResult as bC, JobConfig as bD, JsonField as bE, KeysetPage as bF, Label as bG, LayoutNode as bH, LivePreview as bI, LocaleOf as bJ, LogDetails as bK, Logger as bL, LoginArgs as bM, LogsConfig as bN, MediaDocument as bO, MediaSize as bP, MembersConfig as bQ, MembersSignup as bR, MigrationInfo as bS, NavGroup as bT, NumberField as bV, OnRequest as bW, OnRequestArgs as bX, Operation as bY, OutboxRow as bZ, FieldTypeValidateContext as ba, FieldValidate as bb, FieldValidateContext as bc, FieldValue as bd, FieldsInput as be, FieldsValue as bf, FilterOptionsArgs as bg, FindAfterArgs as bh, FindArgs as bi, FindOptions as bj, FolderLevel as bk, FolderPermissions as bl, GlobalAccess as bn, GlobalConfig as bo, GlobalHooks as bp, GlobalInput as bq, GroupField as br, ImageSize as bs, IncrementOptions as bt, InferCollection as bu, InferGlobal as bv, IntegrationCategory as bw, IntegrationConfig as bx, IntegrationConnection as by, IntegrationField as bz, CursorDocs as c, VersionSummary as c$, PasswordEmailArgs as c0, PasswordEmailFn as c1, PasswordLinkOptions as c2, Plugin as c4, PluginInfo as c5, PluginTypes as c6, PreviewTarget as c7, PreviewURL as c8, Session as cA, SidebarPanel as cB, SignupArgs as cC, SignupResult as cD, SlugField as cF, SlugOf as cG, SsoOutcome as cH, SsoProviderRef as cI, StorageAdapter as cJ, StoredFile as cK, TelemetryConfig as cM, TextField as cN, TextareaField as cO, TypedPlugin as cQ, UiField as cR, UpdateInput as cT, UpdateOptions as cU, UploadConfig as cV, UploadField as cW, UploadFromURLConfig as cX, UserIdentity as cY, Version as c_, RawDocument as cb, ReadOptions as cc, RelationshipField as cd, RequestContext as ce, RichTextBlock as cf, RichTextBlocks as cg, RichTextDocument as ch, RichTextField as ci, Role as cj, RoleOperation as ck, RolePermissions as cl, RoutesConfig as cn, ScheduledPublish as co, SchemaMode as cq, SearchAdapter as cr, SearchEntry as cs, SearchHits as ct, SearchOptions as cu, SearchQuery as cv, SearchResults as cw, SearchSetting as cx, SelectField as cy, SelectOption as cz, GlobalDocument as d, VersionsConfig as d0, WebhookConfig as d2, WebhookEvent as d3, WhereOperators as d4, Secrets as dC, FieldError as e, FilterOptions as f, CreateEasyCMSOptions as g, EmailSetting as h, WebhookPayload as i, Access as k, AccessArgs as l, AccessOptions as m, AdminAi as n, AdminBrand as o, AdminCommand as p, AdminComponent as q, AdminConfig as r, AdminFieldArgs as s, AdminIcon as t, AdminLocale as u, AdminPage as v, AdminRole as w, AdminRoleChange as x, AdminRoleField as y, AdminRoleTarget as z };