@easy-cms/core 0.40.0 → 0.42.0

package/dist/index.d.ts

@@ -208,6 +208,13 @@ declare class Auth {
     hasUsers(): Promise<boolean>;
     /** Ends the session for a signed token. Unknown tokens are ignored. */
     logout(signedToken: string): Promise<void>;
+    /**
+     * The user a request's headers carry: a Bearer token (session or API key) or the session
+     * cookie; `null` when there is none or it is not valid. For frameworks' pages and handlers.
+     */
+    userFromHeaders(headers: {
+        get(name: string): string | null | undefined;
+    }): Promise<AuthUser | null>;
     /**
      * Returns the user for a signed session token, or for an API key (`ecms_…`, with `apiKey` set
      * on the user), or `null` if it is invalid or expired.
@@ -1047,6 +1054,17 @@ declare class MediaFolders {
         id: ID;
         private: boolean;
     }[]>;
+    /**
+     * The privacy each folder of a subtree would have after a change to its top folder: made
+     * private or public, moved, or (as `private: false`) deleted with its contents moving up.
+     */
+    privacyAfter(id: ID, change: {
+        private?: boolean;
+        parent?: ID | null;
+    }): Promise<{
+        id: ID;
+        private: boolean;
+    }[]>;
     /**
      * The folder with this key (`folder: 'banners'` on upload fields), made at the top level when
      * there is none yet.
@@ -1103,6 +1121,28 @@ interface StorageAdapter {
      * (`<api>/media/file/<key>`), as the local adapter does.
      */
     url?(key: string): string | undefined;
+    /**
+     * Lets a browser send a file straight to the storage (large files, past a host's request
+     * limit): where to send it and how. The URL must work for `expiresIn` seconds and accept at
+     * most `size` bytes. Without it, files are uploaded through the server.
+     */
+    uploadURL?(key: string, options: {
+        contentType: string;
+        size: number;
+        expiresIn: number;
+    }): Promise<DirectUpload>;
+    /**
+     * The first `bytes` of a file and its whole size, without reading it all (to check a file
+     * uploaded straight to the storage); `null` when there is no such file. Default: `get`.
+     */
+    getStart?(key: string, bytes: number): Promise<StoredFile | null>;
+}
+/** Where and how a browser sends a file straight to the storage (`StorageAdapter.uploadURL`). */
+interface DirectUpload {
+    readonly url: string;
+    readonly method: 'PUT' | 'POST';
+    /** Headers to send with the file. */
+    readonly headers: Readonly<Record<string, string>>;
 }
 interface LocalStorageOptions {
     /** Directory, relative to the project root. Default `uploads`. */
@@ -1254,6 +1294,32 @@ declare class EasyCMS<C extends Config = Config> {
         data: Uint8Array;
         name: string;
     }, data?: Record<string, unknown>, options?: DepthOptions): Promise<MediaDocument>;
+    /**
+     * Starts an upload straight to the storage, for files too large to send through the server
+     * (`POST <api>/media/uploads`): checks who uploads what where, as `upload()` does, and returns
+     * a signed ticket and where to send the file. `upload` is `null` when the storage can't take
+     * files directly: send it to `upload()` instead. Then `completeUpload(ticket)`.
+     */
+    createUpload(file: {
+        name: string;
+        size: number;
+        type?: string;
+    }, data?: Record<string, unknown>, options?: AccessOptions): Promise<{
+        ticket: string;
+        upload: DirectUpload | null;
+    }>;
+    /**
+     * Finishes an upload made with `createUpload()` (`POST <api>/media/uploads/complete`): checks
+     * the file in the storage like any upload (its size, and its type from its contents), then
+     * makes its media document. A file that fails is deleted.
+     */
+    completeUpload(ticket: string, options?: DepthOptions): Promise<MediaDocument>;
+    /** Who may upload, and into which folder: `upload()` and direct uploads. */
+    private checkUpload;
+    /** A value with its HMAC (`secret`), for `purpose` only: `<base64url JSON>.<signature>`. */
+    private sign;
+    /** The value of a token made by `sign`, or `undefined` when it isn't genuine. */
+    private verify;
     /**
      * Downloads a file from an `http(s)` link and uploads it like `upload()`. Private network
      * addresses are refused unless `upload.fromURL.allowPrivate`. Calls on behalf of a user (the
@@ -1307,6 +1373,11 @@ declare class EasyCMS<C extends Config = Config> {
     private relocate;
     /** A folder's name, parent and permissions; private only with somewhere private to keep files. */
     private validateFolder;
+    /**
+     * Refuses a change that would move more than 200 files between storages in one request: they
+     * are copied one by one, which could outlast a serverless function.
+     */
+    private checkMoveLimit;
     /** After a folder became private or public (or moved): its files follow, in every subfolder. */
     private settlePrivacy;
     /** Files at the top level are public. */
@@ -2806,6 +2877,32 @@ interface ValidateResult {
 /** 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;
+    /** Use the first `X-Forwarded-For` address. Only behind a proxy you trust (Vercel, Netlify…). */
+    readonly trustProxy?: boolean;
+}
+/**
+ * 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()`. */
@@ -3193,7 +3290,9 @@ interface AdminStatus {
     attention: AdminAttention[];
 }
 
+/** The session cookie the REST API sets at login. */
 declare const SESSION_COOKIE = "ecms-session";
+
 declare const CSRF_COOKIE = "ecms-csrf";
 declare const CSRF_HEADER = "x-csrf-token";
 interface RestHandlerOptions {
@@ -3231,4 +3330,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 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 AdminRole, type AdminRoleChange, type AdminRoleField, type AdminRoleTarget, type AdminRoleView, type AdminRoles, type AdminSchema, type AdminSso, type AdminStatus, type AdminViewAccess, type AdminWebhookDelivery, type AdminWidgetRef, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, type AuditChange, type AuditConfig, type AuditEntry, AuditLog, type AuditPage, type AuditVerification, Auth, type AuthConfig, type AuthProvider, type AuthProviderProfile, type AuthProviderRequest, 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 BuiltinMediaFoldersCollection, 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, FOLDER_LEVELS, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldRule, 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, type FolderLevel, type FolderPermissions, 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, MEDIA_FOLDERS, MIME_GROUPS, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, MediaFolders, 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, ROLE_OPERATIONS, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoleOperation, type RolePermissions, Roles, type RoutesConfig, SESSION_COOKIE, SSO_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type SlugOf, type SsoOutcome, type SsoProviderRef, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, type UploadFromURLConfig, type UserIdentity, 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, expandMimeTypes, 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 };
+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 AdminRole, type AdminRoleChange, type AdminRoleField, type AdminRoleTarget, type AdminRoleView, type AdminRoles, type AdminSchema, type AdminSso, type AdminStatus, type AdminViewAccess, type AdminWebhookDelivery, type AdminWidgetRef, type AfterChangeHook, type AfterDeleteHook, type AfterReadHook, type ApiHandlerOptions, type ApiKeyContext, type ApiKeyGlobalOperation, type ApiKeyOperation, type ApiKeyPermissions, type ArrayField, type AuditChange, type AuditConfig, type AuditEntry, AuditLog, type AuditPage, type AuditVerification, Auth, type AuthConfig, type AuthProvider, type AuthProviderProfile, type AuthProviderRequest, 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 BuiltinMediaFoldersCollection, 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 DirectUpload, type DocumentOf, EXTENSIONS, EasyCMS, EasyCMSError, type EmailAdapter, type EmailCheck, type EmailField, type EmailMessage, type EmailSetting, type Endpoint, type EndpointRequest, FIELD_TYPES, FIELD_TYPE_BASES, FOLDER_LEVELS, type Field, type FieldAccess, type FieldAccessFn, type FieldAdmin, type FieldError, type FieldRule, 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, type FolderLevel, type FolderPermissions, 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, MEDIA_FOLDERS, MIME_GROUPS, MIN_PASSWORD_LENGTH, MIN_SECRET_LENGTH, type MediaDocument, MediaFolders, 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, ROLE_OPERATIONS, type RawDocument, type ReadOptions, type RelationshipField, type ResolvedConfig, type RestHandler, type RestHandlerOptions, type RichTextDocument, type RichTextField, type Role, type RoleOperation, type RolePermissions, Roles, type RoutesConfig, SESSION_COOKIE, SSO_COOKIE, type ScheduledJob, SchemaError, type SchemaMode, type SelectField, type SelectOption, type Session, type SlugField, type SlugOf, type SsoOutcome, type SsoProviderRef, type StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, type TypedPlugin, UnauthorizedError, type UpdateInput, type UpdateOptions, type UploadConfig, type UploadField, type UploadFromURLConfig, type UserIdentity, 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, createApiHandler, createEasyCMS, createRestHandler, createRootEndpointHandler, defineConfig, defineFieldType, definePlugin, expandMimeTypes, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isHasMany, isLoggedIn, keyAllows, loadConfig, localStorage, mergeForUpdate, mimeAllowed, mimeAllowedBy, parseId, populate, readCookie, resolveAdminModule, resolveConfig, rowFields, sharedEasyCMS, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword, writeBackupFile };