@easy-cms/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1049 @@
+/** A document id. SQLite uses integers, Postgres may use either. */
+type ID = string | number;
+type Role = 'admin' | 'editor' | (string & {});
+/** The logged-in admin user, as seen by access functions and hooks. */
+interface AuthUser {
+    readonly id: ID;
+    readonly email: string;
+    readonly role: Role;
+    readonly [field: string]: unknown;
+}
+interface WhereOperators {
+    readonly equals?: unknown;
+    readonly not_equals?: unknown;
+    readonly in?: readonly unknown[];
+    readonly not_in?: readonly unknown[];
+    readonly gt?: number | string;
+    readonly gte?: number | string;
+    readonly lt?: number | string;
+    readonly lte?: number | string;
+    readonly like?: string;
+    readonly exists?: boolean;
+}
+type Where = {
+    readonly and?: readonly Where[];
+    readonly or?: readonly Where[];
+} & {
+    readonly [field: string]: WhereOperators | readonly Where[] | undefined;
+};
+interface AccessArgs {
+    /** `null` when the request is not logged in. */
+    readonly user: AuthUser | null;
+    readonly id?: ID;
+    readonly data?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Decides whether an operation is allowed.
+ * Return a `Where` to allow it only for the documents that match.
+ */
+type Access = (args: AccessArgs) => boolean | Where | Promise<boolean | Where>;
+interface CollectionAccess {
+    readonly read?: Access;
+    readonly create?: Access;
+    readonly update?: Access;
+    readonly delete?: Access;
+}
+interface GlobalAccess {
+    readonly read?: Access;
+    readonly update?: Access;
+}
+type FieldAccessFn = (args: AccessArgs) => boolean | Promise<boolean>;
+interface FieldAccess {
+    readonly read?: FieldAccessFn;
+    readonly update?: FieldAccessFn;
+}
+declare const anyone: Access;
+declare const isLoggedIn: Access;
+declare const isAdmin: Access;
+
+interface Logger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+declare const consoleLogger: Logger;
+declare const silentLogger: Logger;
+
+/** A document as stored: relationships and uploads are ids, never populated. */
+type RawDocument = Record<string, unknown> & {
+    id: ID;
+};
+interface PaginatedDocs<T> {
+    docs: T[];
+    totalDocs: number;
+    limit: number;
+    page: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}
+/**
+ * How the adapter treats the database schema on startup.
+ * - `push`: apply schema changes directly (development).
+ * - `verify`: fail if migrations are pending or the config changed without a migration (production).
+ * - `skip`: do nothing (used by the migration CLI).
+ */
+type SchemaMode = 'push' | 'verify' | 'skip';
+interface DatabaseInitArgs {
+    readonly config: ResolvedConfig;
+    /** Project root; relative paths (database file, migrations) resolve from here. */
+    readonly cwd: string;
+    readonly schema: SchemaMode;
+    readonly logger: Logger;
+    /** Whether the process can prompt the user (the CLI in a terminal). */
+    readonly interactive?: boolean;
+}
+interface FindArgs {
+    readonly collection: string;
+    readonly where?: Where | undefined;
+    /** Field paths; prefix with `-` for descending. */
+    readonly sort: readonly string[];
+    /** `0` returns every matching document. */
+    readonly limit: number;
+    readonly page: number;
+}
+interface MigrationInfo {
+    readonly name: string;
+    readonly applied: boolean;
+}
+interface CreateMigrationResult {
+    readonly name: string;
+    readonly file: string;
+    readonly statements: readonly string[];
+}
+/** A connected database bound to one config. Returned by `DatabaseAdapter.init`. */
+interface Database {
+    find(args: FindArgs): Promise<PaginatedDocs<RawDocument>>;
+    findById(args: {
+        collection: string;
+        id: ID;
+    }): Promise<RawDocument | null>;
+    /** Documents of one collection by id, in any order. Used to populate relationships. */
+    findByIds(args: {
+        collection: string;
+        ids: readonly ID[];
+    }): Promise<RawDocument[]>;
+    count(args: {
+        collection: string;
+        where?: Where | undefined;
+    }): Promise<number>;
+    /** `data` holds every field, `createdAt` and `updatedAt`. Runs in one transaction. */
+    create(args: {
+        collection: string;
+        data: Record<string, unknown>;
+    }): Promise<RawDocument>;
+    /** `data` holds the whole document after merging. Runs in one transaction. */
+    update(args: {
+        collection: string;
+        id: ID;
+        data: Record<string, unknown>;
+    }): Promise<RawDocument>;
+    delete(args: {
+        collection: string;
+        id: ID;
+    }): Promise<void>;
+    findGlobal(args: {
+        slug: string;
+    }): Promise<Record<string, unknown> | null>;
+    updateGlobal(args: {
+        slug: string;
+        data: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    /** Writes a migration file for the difference between the config and the latest migration. `null` when nothing changed. */
+    createMigration(args: {
+        name: string;
+    }): Promise<CreateMigrationResult | null>;
+    /** Applies pending migrations in order. Returns the names applied. */
+    migrate(): Promise<string[]>;
+    migrationStatus(): Promise<MigrationInfo[]>;
+    destroy(): Promise<void>;
+}
+/** What `sqlite()` / `postgres()` return and what `config.db` holds. */
+interface DatabaseAdapter {
+    readonly name: string;
+    init(args: DatabaseInitArgs): Promise<Database>;
+    /** Hints for bundlers (Nitro, Next.js output tracing) about files static analysis cannot find. */
+    readonly bundle?: BundleHints;
+}
+interface BundleHints {
+    /** Absolute paths of files to ship with the server build, e.g. native binaries loaded dynamically. */
+    readonly traceInclude: readonly 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>;
+interface BaseField<TType extends string, TValue> {
+    readonly type: TType;
+    readonly name: string;
+    readonly label?: Label;
+    readonly required?: boolean;
+    readonly unique?: boolean;
+    readonly index?: boolean;
+    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;
+}
+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> {
+}
+/** References a document in the built-in `media` collection. */
+interface UploadField extends BaseField<'upload', never> {
+}
+interface RelationshipField extends BaseField<'relationship', never> {
+    /** Slug of the target collection. */
+    readonly to: string;
+    readonly hasMany?: boolean;
+}
+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[];
+}
+type Field = TextField | TextareaField | NumberField | BooleanField | DateField | EmailField | JsonField | SelectField | SlugField | RichTextField | UploadField | RelationshipField | ArrayField | GroupField;
+type FieldType = Field['type'];
+declare const FIELD_TYPES: readonly ["text", "textarea", "number", "boolean", "date", "email", "json", "select", "slug", "richText", "upload", "relationship", "array", "group"];
+
+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>;
+    /**
+     * Public URL of a file, or `undefined` to serve it through the REST API
+     * (`<api>/media/file/<key>`), as the local adapter does.
+     */
+    url?(key: string): string | undefined;
+}
+interface LocalStorageOptions {
+    /** Directory, relative to the project root. Default `uploads`. */
+    readonly dir?: string;
+}
+/** Stores files on the local disk. Suitable for servers with a persistent filesystem. */
+declare function localStorage(options?: LocalStorageOptions): StorageAdapter;
+
+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;
+}
+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[];
+}
+interface GlobalHooks {
+    readonly beforeChange?: readonly BeforeChangeHook[];
+    readonly afterChange?: readonly AfterChangeHook[];
+    readonly afterRead?: readonly AfterReadHook[];
+}
+interface CollectionConfig {
+    /** URL and table name. Lowercase letters, digits, `-` and `_`. */
+    readonly slug: string;
+    readonly labels?: {
+        readonly singular?: Label;
+        readonly plural?: Label;
+    };
+    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;
+    readonly access?: CollectionAccess;
+    readonly hooks?: CollectionHooks;
+}
+interface GlobalConfig {
+    readonly slug: string;
+    readonly label?: Label;
+    readonly fields: readonly Field[];
+    readonly drafts?: boolean;
+    readonly access?: GlobalAccess;
+    readonly hooks?: GlobalHooks;
+}
+type AdminLocale = 'en' | 'th';
+interface AdminConfig {
+    /** Where the admin UI is served. Default `/admin`. */
+    readonly path?: string;
+    /** Default admin UI language. Default `en`. */
+    readonly locale?: AdminLocale;
+}
+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;
+    /**
+     * 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.
+     */
+    readonly trustedOrigins?: readonly string[];
+}
+/** 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;
+    /**
+     * 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.
+     */
+    readonly serverURL?: string;
+    readonly routes?: RoutesConfig;
+    readonly admin?: AdminConfig;
+    readonly upload?: UploadConfig;
+    readonly auth?: AuthConfig;
+    /**
+     * Collections. A collection with slug `users` adds fields, access or hooks
+     * to the built-in users collection.
+     */
+    readonly collections?: readonly CollectionConfig[];
+    readonly globals?: readonly GlobalConfig[];
+    readonly plugins?: readonly Plugin[];
+}
+/** The config after plugins ran, validation passed and defaults were applied. */
+interface ResolvedConfig extends Omit<Config, 'routes' | 'admin' | 'upload' | 'auth' | 'collections' | 'globals' | 'plugins'> {
+    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[];
+}
+/**
+ * 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;
+}
+/** 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;
+}
+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> : never;
+type Visible<Fs extends readonly Field[]> = Exclude<Fs[number], {
+    readonly hidden: true;
+}>;
+type RequiredFields<Fs extends readonly Field[]> = Extract<Visible<Fs>, {
+    readonly required: true;
+}>;
+type OptionalFields<Fs extends readonly Field[]> = Exclude<Visible<Fs>, {
+    readonly required: true;
+}>;
+/** 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> : 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;
+}>>>>;
+
+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;
+}
+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;
+}
+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 CreateEasyCMSOptions {
+    /** Project root. Default `process.cwd()`. */
+    readonly cwd?: string;
+    /** Default `verify` when `NODE_ENV=production`, otherwise `push`. */
+    readonly schema?: SchemaMode;
+    readonly logger?: Logger;
+    readonly interactive?: boolean;
+}
+/** Connects to the database and returns the Local API. */
+declare function createEasyCMS<const C extends Config>(config: C, options?: CreateEasyCMSOptions): Promise<EasyCMS<C>>;
+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;
+    constructor(config: ResolvedConfig, db: Database, logger?: Logger, storage?: StorageAdapter);
+    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;
+    } & 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>;
+    /** 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>>;
+    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>>;
+    /**
+     * What `user` may do with one document. Resolves `where`-style access
+     * against the document, so the admin UI can hide actions precisely.
+     */
+    documentPermissions(collection: Slug<C>, id: ID, user: AuthUser | null): Promise<{
+        update: boolean;
+        delete: boolean;
+    }>;
+    /** Closes the database connection. */
+    destroy(): Promise<void>;
+    /** @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;
+    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;
+}
+
+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 MIN_PASSWORD_LENGTH = 8;
+/** Hashes a password as `scrypt$N$r$p$salt$hash` (base64url). */
+declare function hashPassword(password: string): Promise<string>;
+/** Checks a password against a hash in constant time. Malformed hashes never match. */
+declare function verifyPassword(password: string, stored: string): Promise<boolean>;
+
+declare const MEDIA = "media";
+/** Collections Easy CMS uses internally. Not exposed over REST or in the admin UI. */
+declare const INTERNAL_COLLECTIONS: ReadonlySet<string>;
+
+interface ConfigIssue {
+    /** Where the problem is, e.g. `collections.posts.fields.slug.from`. */
+    readonly path: string;
+    readonly message: string;
+    /** How to fix it. */
+    readonly hint?: string;
+}
+declare class ConfigError extends Error {
+    readonly issues: readonly ConfigIssue[];
+    constructor(issues: readonly ConfigIssue[]);
+    static format(issues: readonly ConfigIssue[]): string;
+}
+/** Base class for errors that map to an HTTP status in the REST API. */
+declare class EasyCMSError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+interface FieldError {
+    /** Dotted path, e.g. `links.0.url`. */
+    readonly field: string;
+    readonly message: string;
+}
+declare class ValidationError extends EasyCMSError {
+    readonly errors: readonly FieldError[];
+    constructor(collection: string, errors: readonly FieldError[]);
+}
+declare class NotFoundError extends EasyCMSError {
+    constructor(collection: string, id: unknown);
+}
+/** A bad `where`, `sort` or unknown collection/global. */
+declare class QueryError extends EasyCMSError {
+    constructor(message: string);
+}
+/** The database schema does not match the config (pending or missing migrations). */
+declare class SchemaError extends EasyCMSError {
+    constructor(message: string);
+}
+/** Not logged in, or the session is invalid. */
+declare class UnauthorizedError extends EasyCMSError {
+    constructor(message?: string);
+}
+/** Logged in, but not allowed to do this. */
+declare class ForbiddenError extends EasyCMSError {
+    constructor(message?: string);
+}
+declare class TooManyRequestsError extends EasyCMSError {
+    constructor(message: string);
+}
+declare class PayloadTooLargeError extends EasyCMSError {
+    constructor(message: string);
+}
+
+type Data = Record<string, unknown>;
+/**
+ * Turns text into a URL slug. Keeps letters and digits of any script,
+ * so Thai titles stay readable: "สวัสดี World!" → "สวัสดี-world".
+ */
+declare function slugify(text: string): string;
+/** Fills in `defaultValue` for fields that are missing, including inside groups and array rows. */
+declare function applyDefaults(fields: readonly Field[], data: Data): Data;
+/** Gives every field a value (`null`, `[]` or a nested object) so documents always have the same shape. */
+declare function fillMissing(fields: readonly Field[], data: Data): Data;
+/** Fills empty `slug` fields from their `from` field. Does not check uniqueness. */
+declare function generateSlugs(fields: readonly Field[], data: Data): Data;
+/**
+ * Merges an update into the stored document. Top-level fields and group
+ * fields merge key by key; arrays and hasMany values are replaced.
+ */
+declare function mergeForUpdate(fields: readonly Field[], existing: Data, patch: Data): Data;
+/** Parses an id from user input. Integer ids may arrive as strings from URLs. */
+declare function parseId(value: unknown): ID | undefined;
+/** A reference to another document found while validating, checked against the database afterwards. */
+interface Reference {
+    readonly field: string;
+    readonly collection: string;
+    readonly id: ID;
+}
+interface ValidateOptions {
+    readonly operation: 'create' | 'update';
+    /** Drafts may be incomplete: skip `required`, but still check types (FR-DRF-02). */
+    readonly skipRequired?: boolean;
+    /** The whole top-level document, passed to custom `validate` functions. */
+    readonly root: Data;
+}
+interface ValidateResult {
+    /** Only known fields, with values normalized (ids parsed, dates as ISO strings, row ids filled). */
+    readonly data: Data;
+    readonly errors: FieldError[];
+    readonly references: Reference[];
+}
+/** Checks and normalizes data against fields. Unknown keys are dropped. */
+declare function validateFields(fields: readonly Field[], input: Data, options: ValidateOptions, prefix?: string): Promise<ValidateResult>;
+
+declare const CONFIG_FILE_NAMES: readonly ["easy-cms.config.ts", "easy-cms.config.mts", "easy-cms.config.js", "easy-cms.config.mjs"];
+interface LoadConfigOptions {
+    /** Directory to search. Default `process.cwd()`. */
+    readonly cwd?: string;
+    /** Explicit config file path, relative to `cwd`. */
+    readonly configFile?: string;
+}
+/** Finds the config file in `cwd`, returning its absolute path or `undefined`. */
+declare function findConfigFile(cwd?: string): string | undefined;
+/**
+ * Imports a config file without resolving or validating it.
+ * Build tools use this to read hints (e.g. `db.bundle`) when env vars may be missing.
+ */
+declare function importConfig(file: string): Promise<Config | undefined>;
+/** Loads `easy-cms.config.ts` (or `.mts`/`.js`/`.mjs`) and resolves it. */
+declare function loadConfig(options?: LoadConfigOptions): Promise<ResolvedConfig>;
+
+/** File types Easy CMS recognizes from their contents (FR-UPL-03). */
+declare const EXTENSIONS: Readonly<Record<string, string>>;
+/** Detects the MIME type from file contents, ignoring the name the client sent. */
+declare function sniffMimeType(data: Uint8Array): string | undefined;
+/** `image/*` style matching. */
+declare function mimeAllowed(type: string, allowed: readonly string[]): boolean;
+/** Width and height of PNG, GIF, JPEG and WebP images without decoding them. */
+declare function imageDimensions(data: Uint8Array, type: string): {
+    width: number;
+    height: number;
+} | undefined;
+
+declare const DEFAULT_DEPTH = 1;
+declare const MAX_DEPTH = 3;
+/** Loads the documents of one collection that the caller may see. */
+type Loader = (collection: CollectionConfig, ids: readonly ID[]) => Promise<RawDocument[]>;
+/**
+ * Replaces relationship and upload ids with documents, `depth` levels deep.
+ * Missing (or unreadable) documents become `null` (single) or are dropped (hasMany).
+ * Returns new objects; the input is not modified.
+ */
+declare function populate(load: Loader, collections: readonly CollectionConfig[], fields: readonly Field[], docs: RawDocument[], depth: number): Promise<RawDocument[]>;
+
+declare const DEFAULT_ADMIN_PATH = "/admin";
+declare const DEFAULT_API_PATH = "/api/cms";
+declare const DEFAULT_MAX_FILE_SIZE: number;
+declare const DEFAULT_TOKEN_EXPIRATION: number;
+/**
+ * Runs plugins in order, adds the built-in collections, validates the result
+ * and fills in defaults. Throws `ConfigError`. Resolving twice is a no-op.
+ */
+declare function resolveConfig(input: Config | ResolvedConfig): Promise<ResolvedConfig>;
+
+/** A field as the admin UI sees it: plain JSON, no functions. */
+interface AdminField {
+    name: string;
+    type: Field['type'];
+    label?: Label;
+    required?: boolean;
+    unique?: boolean;
+    defaultValue?: unknown;
+    minLength?: number;
+    maxLength?: number;
+    min?: number;
+    max?: number;
+    options?: {
+        label: Label;
+        value: string;
+    }[];
+    hasMany?: boolean;
+    to?: string;
+    from?: string;
+    minRows?: number;
+    maxRows?: number;
+    fields?: AdminField[];
+    /** The current user may not change this field. */
+    readOnly?: boolean;
+}
+interface AdminCollection {
+    slug: string;
+    labels?: {
+        singular?: Label;
+        plural?: Label;
+    };
+    useAsTitle?: string;
+    drafts: boolean;
+    fields: AdminField[];
+    permissions: {
+        read: boolean;
+        create: boolean;
+        update: boolean;
+        delete: boolean;
+    };
+}
+interface AdminGlobal {
+    slug: string;
+    label?: Label;
+    drafts: boolean;
+    fields: AdminField[];
+    permissions: {
+        read: boolean;
+        update: boolean;
+    };
+}
+interface AdminSchema {
+    locale: AdminLocale;
+    collections: AdminCollection[];
+    globals: AdminGlobal[];
+}
+
+declare const SESSION_COOKIE = "ecms-session";
+declare const CSRF_COOKIE = "ecms-csrf";
+declare const CSRF_HEADER = "x-csrf-token";
+interface RestHandlerOptions {
+    /** Path the handler is mounted at. Default: `routes.api` from the config (`/api/cms`). */
+    readonly basePath?: string;
+    /** Client IP, used with the email to rate-limit logins. Adapters provide it. */
+    readonly getClientIp?: (request: Request) => string | undefined;
+}
+type RestHandler = (request: Request) => Promise<Response>;
+/** Creates the REST API as a Web-standard `(Request) => Response` handler. */
+declare function createRestHandler<C extends Config>(instance: EasyCMS<C>, options?: RestHandlerOptions): RestHandler;
+declare function readCookie(request: Request, name: string): string | undefined;
+
+/** Best-effort English singular: "categories" → "category". */
+declare function singularize(word: string): string;
+/**
+ * TypeScript declarations for every collection and global, as the REST API returns them.
+ * The output has no imports, so a frontend in another repository can use it as is.
+ */
+declare function generateTypes(config: ResolvedConfig): string;
+
+declare const MIN_SECRET_LENGTH = 32;
+/** Collections that Easy CMS provides. They can be relationship targets. */
+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 { type Access, type AccessArgs, type AccessOptions, type AdminCollection, type AdminConfig, type AdminField, type AdminGlobal, 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 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 CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_TOKEN_EXPIRATION, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DateField, type DepthOptions, EXTENSIONS, EasyCMS, EasyCMSError, type EmailField, FIELD_TYPES, type Field, type FieldAccess, type FieldAccessFn, 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 LoadConfigOptions, type LocalStorageOptions, 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, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, 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 Where, type WhereOperators, anyone, applyDefaults, consoleLogger, createEasyCMS, createRestHandler, defineConfig, fillMissing, findConfigFile, generateSlugs, generateTypes, hashPassword, imageDimensions, importConfig, isAdmin, isLoggedIn, loadConfig, localStorage, mergeForUpdate, mimeAllowed, parseId, populate, readCookie, resolveConfig, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };