@easy-cms/core 0.48.0 → 0.60.0

package/dist/handler-CMA1LIq7.d.ts

@@ -0,0 +1,188 @@
+import { I as ID, ab as Config, au as EasyCMS, bd as LocalizationConfig, aD as Field, aH as FieldError, aS as FilterOptions, af as CreateEasyCMSOptions, bI as ResolvedConfig } from './config-jzFGsNL6.js';
+
+type BackupState = 'pending' | 'running' | 'done' | 'failed';
+/** One backup as the admin shows it (`GET <api>/admin/backups`). */
+interface AdminBackup {
+    id: ID;
+    state: BackupState;
+    trigger: 'manual' | 'scheduled';
+    /** The file's name, e.g. `my-site-2026-10-04-0300.db.gz`. */
+    filename: string | null;
+    /** Bytes, compressed. */
+    size: number | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+    error: string | null;
+    /** Who started it (manual backups). */
+    author: string | null;
+    downloadedBy: string | null;
+    downloadedAt: string | null;
+}
+/** Settings → Backups (`GET <api>/admin/backups`). */
+interface AdminBackups {
+    settings: {
+        frequency: 'daily' | 'weekly' | null;
+        at: string;
+        keep: number;
+        /** The storage adapter's name, e.g. `local` or `s3`. */
+        storage: string;
+        /** The folder, for local storage. */
+        dir: string | null;
+        database: string;
+        /** Why backups can't be made with this setup, if they can't. */
+        unavailable: string | null;
+    };
+    backups: AdminBackup[];
+}
+/**
+ * Writes a consistent copy of the database to `file` as SQLite, while the CMS keeps running:
+ * SQLite copies itself; other databases are copied into a new SQLite file (`backups.sqlite`).
+ */
+declare function writeBackupFile<C extends Config>(cms: EasyCMS<C>, file: string): Promise<void>;
+
+type Localization = Required<LocalizationConfig>;
+
+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, localization?: Localization | null): 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, localization?: Localization | null): 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;
+    /** The relationship's `filterOptions`, checked when saving. */
+    readonly filterOptions?: FilterOptions;
+    /** The upload's `mimeTypes`, checked when saving. */
+    readonly mimeTypes?: readonly string[];
+    /** The upload's `folder` with `folderOnly`: the file must be in it, checked when saving. */
+    readonly folderOnly?: string;
+}
+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;
+    /** Localized fields hold `{ [locale]: value }`; each value is validated. */
+    readonly localization?: Localization | null;
+    /**
+     * The locale being written: `required` and custom `validate` apply to its values, and its
+     * errors use the plain field path. Default: the default locale.
+     */
+    readonly locale?: string;
+}
+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>;
+
+/**
+ * The Easy CMS instance for this server, made on first use and kept across hot reloads.
+ *
+ * Configs are compared by structure, not identity: frameworks bundle the config into each server
+ * layer, so the same config can arrive as several objects. A change to fields or options (in
+ * development) closes the old instance and makes a new one; a change to a hook's code alone needs
+ * a restart. A failed start is not kept: the next call tries again.
+ */
+declare function sharedEasyCMS<const C extends Config>(config: C, options?: CreateEasyCMSOptions): Promise<EasyCMS<C>>;
+interface ApiHandlerOptions {
+    /** Where the API is mounted. Default: `routes.api` of the config. */
+    readonly basePath?: string;
+    /**
+     * The client's IP (login rate limiting, the audit log), from the framework's request object.
+     * Takes precedence over `trustProxy`.
+     */
+    readonly getClientIp?: (request: Request) => string | undefined;
+    /**
+     * Behind a proxy that adds the client's address to `X-Forwarded-For`: the last address in it
+     * (the one the proxy added; earlier ones come from the client and can say anything). Vercel
+     * and Netlify are recognized without it.
+     */
+    readonly trustProxy?: boolean;
+}
+/**
+ * The client's address from `X-Forwarded-For` as the nearest proxy wrote it: its last entry.
+ * Earlier entries were sent by the client, so they can't be trusted.
+ */
+declare function forwardedClientIp(value: string | null | undefined): string | undefined;
+/** The client's address on hosting platforms that set it themselves: Vercel, Netlify. */
+declare function platformClientIp(headers: Headers): string | undefined;
+/**
+ * The REST API as a `(Request) => Response` handler for a framework's route, on the shared
+ * instance (`sharedEasyCMS`). Mount it at `routes.api` (default `/api/cms`), for every method.
+ */
+declare function createApiHandler(config: Config, options?: ApiHandlerOptions): (request: Request) => Promise<Response>;
+
+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>;
+
+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 the config's plugins in order, without validating the result. Build tools use it to
+ * read what plugins add (e.g. `admin.modules`) when the config is not complete yet.
+ */
+declare function applyPlugins(input: Config): Promise<Config>;
+/**
+ * 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>;
+
+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;
+/**
+ * Serves the endpoints marked `root: true` (e.g. `/robots.txt`), with the same auth, CSRF and
+ * errors as the REST API. Resolves to `undefined` when no root endpoint has the request's path,
+ * so a server can go on to its other routes. Nuxt and Next.js apps own their root and don't
+ * use it; the standalone server does.
+ */
+declare function createRootEndpointHandler<C extends Config>(instance: EasyCMS<C>, options?: Pick<RestHandlerOptions, 'getClientIp'>): (request: Request) => Promise<Response | undefined>;
+declare function readCookie(request: Request, name: string): string | undefined;
+
+export { type AdminBackup as A, type BackupState as B, CONFIG_FILE_NAMES as C, DEFAULT_ADMIN_PATH as D, validateFields as E, writeBackupFile as F, type LoadConfigOptions as L, type RestHandler as R, type AdminBackups as a, type ApiHandlerOptions as b, type RestHandlerOptions as c, createApiHandler as d, createRestHandler as e, slugify as f, CSRF_COOKIE as g, CSRF_HEADER as h, DEFAULT_API_PATH as i, DEFAULT_MAX_FILE_SIZE as j, DEFAULT_TOKEN_EXPIRATION as k, loadConfig as l, applyDefaults as m, applyPlugins as n, createRootEndpointHandler as o, fillMissing as p, findConfigFile as q, resolveConfig as r, sharedEasyCMS as s, forwardedClientIp as t, generateSlugs as u, importConfig as v, mergeForUpdate as w, parseId as x, platformClientIp as y, readCookie as z };