@easy-cms/core 0.30.0 → 0.32.0

package/dist/index.d.ts

@@ -187,6 +187,8 @@ interface Database {
     readonly backup?: ((file: string) => Promise<void>) | undefined;
     /** Raw table access for copying a whole database to another (`easy-cms copy`). */
     readonly transfer?: DatabaseTransfer | undefined;
+    /** The prefix of its tables (`tablePrefix`), so a copy (a backup) can use the same. */
+    readonly tablePrefix?: string | undefined;
     destroy(): Promise<void>;
 }
 /**
@@ -245,6 +247,25 @@ interface EmailAdapter {
     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?: {
@@ -1784,6 +1805,27 @@ type TypedPlugin<T extends PluginTypes> = Plugin & {
  * ```
  */
 declare function definePlugin<const T extends PluginTypes = Record<never, never>>(plugin: Plugin, info?: PluginInfo): TypedPlugin<T>;
+/** Database backups (Settings → Backups): one compressed SQLite file each. */
+interface BackupsConfig {
+    /** Back up automatically every day or week. Default: only by hand. */
+    readonly every?: 'day' | 'week';
+    /** When, as `HH:MM` in the server's time zone. Default `03:00`. */
+    readonly at?: string;
+    /** How many finished backups to keep; older ones are deleted. Default 7. */
+    readonly keep?: number;
+    /** Folder for the default local storage, from the project root. Default `backups`. Never served publicly. */
+    readonly dir?: string;
+    /** Where backups are stored instead, e.g. `s3Storage()` with a private bucket. */
+    readonly storage?: StorageAdapter;
+    /**
+     * For Postgres: the SQLite adapter that writes the backup file, `sqlite` from
+     * `@easy-cms/db-sqlite`. SQLite databases back themselves up and don't need it.
+     */
+    readonly sqlite?: (options: {
+        url: string;
+        tablePrefix?: string;
+    }) => DatabaseAdapter;
+}
 interface Config {
     /** Signs sessions. At least 32 characters; read it from `process.env.EASY_CMS_SECRET`. */
     readonly secret: string;
@@ -1839,6 +1881,11 @@ interface Config {
      * database and retried until sent.
      */
     readonly email?: EmailAdapter;
+    /**
+     * Database backups, made on a schedule and from the admin (Settings → Backups). Without
+     * `every`, admins can still back up by hand.
+     */
+    readonly backups?: BackupsConfig;
     readonly plugins?: readonly Plugin[];
 }
 /** The config after plugins ran, validation passed and defaults were applied. */
@@ -1898,6 +1945,46 @@ 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>;
 
+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: {
+        every: 'day' | 'week' | 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>;
+
 declare const MEDIA = "media";
 /** Collections Easy CMS uses internally. Not exposed over REST or in the admin UI. */
 declare const INTERNAL_COLLECTIONS: ReadonlySet<string>;
@@ -2080,6 +2167,26 @@ interface AdminDeliveries {
     counts: Record<DeliveryState, number>;
 }
 
+/** Settings → Email in the admin (`GET <api>/admin/email`). */
+interface AdminEmail {
+    /** An `email` adapter is set in the config. */
+    configured: boolean;
+    /** The adapter's name, e.g. `smtp`; `custom` when it has none. */
+    name: string | null;
+    /** The default sender. */
+    from: string | null;
+    /** What the adapter tells about itself (`describe()`), never secrets. */
+    settings: EmailSetting[];
+    /** The adapter can check its connection without sending (`verify()`). */
+    canVerify: boolean;
+}
+type EmailCheck = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+
 /**
  * Finds the file of an admin module (`admin.modules`): a package export or a path relative to
  * the project root. Looks from the project root first, then from the server's entry file
@@ -2259,6 +2366,12 @@ type AdminAttention =
 /** In production without `serverURL`: links in emails can't be made. */
  | {
     id: 'no-server-url';
+}
+/** The last scheduled backup failed, or none finished in two periods (`backups.every`). */
+ | {
+    id: 'backups';
+    failed: boolean;
+    lastDone: string | null;
 };
 /** What the dashboard shows admins (`GET <api>/admin/status`). */
 interface AdminStatus {
@@ -2320,4 +2433,4 @@ declare function validateConfig(config: Config): ConfigIssue[];
 /** The version of `@easy-cms/core`, set when the package is built. */
 declare const VERSION: string;
 
-export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, type Access, type AccessArgs, type AccessOptions, type AdminAttention, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminDeliveries, type AdminDelivery, type AdminEmailDelivery, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminPage, type AdminPageRef, type AdminSchema, type AdminStatus, type AdminViewAccess, type AdminWebhookDelivery, type AdminWidgetRef, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CliCommand, type CollectionAccess, type CollectionAdmin, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionListAdmin, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, type CustomField, type CustomFieldTypes, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_PASSWORD_EMAILS, DEFAULT_TOKEN_EXPIRATION, type DashboardWidget, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DeliveryKind, type DeliveryState, type DepthOptions, type DocumentOf, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailField, type EmailMessage, type Endpoint, type EndpointRequest, FIELD_TYPES, FIELD_TYPE_BASES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldType, type FieldTypeBase, type FieldTypeDefinition, type FieldTypeValidateContext, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FilterOptions, type FilterOptionsArgs, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, PayloadTooLargeError, type Plugin, type PluginInfo, type PluginTypes, type PreviewTarget, type PreviewURL, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type SlugOf, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, type UploadFromURLConfig, VERSION, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, configSignature, consoleEmail, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, defineFieldType, definePlugin, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };
+export { ADMIN_ICONS, API_KEYS, API_KEY_GLOBAL_OPERATIONS, API_KEY_OPERATIONS, type Access, type AccessArgs, type AccessOptions, type AdminAttention, type AdminBackup, type AdminBackups, type AdminBrand, type AdminCollection, type AdminComponent, type AdminComponentRef, type AdminConfig, type AdminDeliveries, type AdminDelivery, type AdminEmail, type AdminEmailDelivery, type AdminField, type AdminGlobal, type AdminIcon, type AdminLocale, type AdminPage, type AdminPageRef, type AdminSchema, type AdminStatus, type AdminViewAccess, type AdminWebhookDelivery, type AdminWidgetRef, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, Auth, type AuthConfig, type AuthUser, BUILTIN_COLLECTIONS, type BackupState, type BackupsConfig, type BeforeChangeHook, type BeforeDeleteHook, type BeforeValidateHook, type Block, type BlocksField, type BooleanField, type BuiltinApiKeysCollection, type BuiltinMediaCollection, type BuiltinUsersCollection, type BundleHints, CONFIG_FILE_NAMES, CSRF_COOKIE, CSRF_HEADER, type CliCommand, type CollectionAccess, type CollectionAdmin, type CollectionConfig, type CollectionDocument, type CollectionHooks, type CollectionListAdmin, type CollectionSlug, type Config, ConfigError, type ConfigIssue, type ContainerAdmin, type CopyProgress, type CopyResult, type CreateEasyCMSOptions, type CreateInput, type CreateMigrationResult, type CustomField, type CustomFieldTypes, DEFAULT_ADMIN_PATH, DEFAULT_API_PATH, DEFAULT_DEPTH, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_VERSIONS, DEFAULT_PASSWORD_EMAILS, DEFAULT_TOKEN_EXPIRATION, type DashboardWidget, type Database, type DatabaseAdapter, type DatabaseInitArgs, type DatabaseTransfer, type DateField, type DeliveryKind, type DeliveryState, type DepthOptions, type DocumentOf, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailCheck, type EmailField, type EmailMessage, type EmailSetting, type Endpoint, type EndpointRequest, FIELD_TYPES, FIELD_TYPE_BASES, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldType, type FieldTypeBase, type FieldTypeDefinition, type FieldTypeValidateContext, type FieldValidate, type FieldValidateContext, type FieldValue, type FieldsInput, type FieldsValue, type FilterOptions, type FilterOptionsArgs, type FindArgs, type FindOptions, ForbiddenError, type GlobalAccess, type GlobalConfig, type GlobalDocument, type GlobalHooks, type GlobalInput, type GlobalSlug, type GroupField, type ID, INTERNAL_COLLECTIONS, type ImageSize, type InferCollection, type InferGlobal, type JsonField, type Label, type LivePreview, type LoadConfigOptions, type LocalStorageOptions, type LocalizationConfig, type Logger, type LoginArgs, MAX_DEPTH, MEDIA, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, type MediaSize, type MigrationInfo, NotFoundError, type NumberField, type Operation, type PaginatedDocs, type PasswordEmail, type PasswordEmailArgs, type PasswordEmailFn, type PasswordLinkOptions, PayloadTooLargeError, type Plugin, type PluginInfo, type PluginTypes, type PreviewTarget, type PreviewURL, QueryError, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoutesConfig, SESSION_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type SlugOf, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, type UploadFromURLConfig, VERSION, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, applyPlugins, configSignature, consoleEmail, consoleLogger, copyDatabase, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, defineFieldType, definePlugin, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword, writeBackupFile };