@easy-cms/core 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -263,9 +263,32 @@ interface ArrayField extends BaseField<'array', never> {
 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;
+/** 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;
+}
+/** 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;
+type Field = TextField | TextareaField | NumberField | BooleanField | DateField | EmailField | JsonField | SelectField | SlugField | RichTextField | UploadField | RelationshipField | ArrayField | GroupField | BlocksField;
 type FieldType = Field['type'];
-declare const FIELD_TYPES: readonly ["text", "textarea", "number", "boolean", "date", "email", "json", "select", "slug", "richText", "upload", "relationship", "array", "group"];
+declare const FIELD_TYPES: readonly ["text", "textarea", "number", "boolean", "date", "email", "json", "select", "slug", "richText", "upload", "relationship", "array", "group", "blocks"];
 
 interface StoredFile {
     readonly body: Uint8Array;
@@ -296,6 +319,39 @@ interface LocalStorageOptions {
 /** Stores files on the local disk. Suitable for servers with a persistent filesystem. */
 declare function localStorage(options?: LocalStorageOptions): StorageAdapter;
 
+declare const WEBHOOK_EVENTS: readonly ["create", "update", "delete", "publish", "unpublish", "draft"];
+/**
+ * `create`, `update`, `delete`: the stored document changed. `publish` / `unpublish`: its status
+ * changed (sent with `create` or `update`). `draft`: only a draft was saved; what is live did not
+ * change (collections with versions and drafts).
+ */
+type WebhookEvent = (typeof WEBHOOK_EVENTS)[number];
+interface WebhookConfig {
+    /** Where to POST events. */
+    readonly url: string;
+    /** Events to send. Default: all. */
+    readonly events?: readonly WebhookEvent[];
+    /** Collections to send events for. Default: all; `[]` for none. */
+    readonly collections?: readonly string[];
+    /** Globals to send events for. Default: all; `[]` for none. */
+    readonly globals?: readonly string[];
+    /** Signs each body: `x-easy-cms-signature: sha256=<hex HMAC-SHA256 of the body>`. */
+    readonly secret?: string;
+    /** Extra request headers, e.g. a token the receiver checks. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** What a webhook receives as JSON. */
+interface WebhookPayload {
+    readonly event: WebhookEvent;
+    readonly collection?: string;
+    readonly global?: string;
+    readonly id?: ID;
+    /** The stored document (every locale, no hidden fields); for `delete`, as it was. */
+    readonly doc: Record<string, unknown>;
+    /** ISO time of the change. */
+    readonly timestamp: string;
+}
+
 type Data$2 = Record<string, unknown>;
 type MaybePromise<T> = T | Promise<T>;
 type Operation = 'create' | 'update';
@@ -384,6 +440,8 @@ interface CollectionConfig {
      * it is published again.
      */
     readonly versions?: boolean | VersionsConfig;
+    /** Allow scheduling publish/unpublish for a later time (needs `drafts`). */
+    readonly schedule?: boolean;
     /** Live preview: the page that shows a document, e.g. `({ doc }) => \`/posts/${doc.slug}\``. */
     readonly preview?: PreviewURL;
     readonly access?: CollectionAccess;
@@ -396,6 +454,8 @@ interface GlobalConfig {
     readonly drafts?: boolean;
     /** Keep a snapshot of every save. See `CollectionConfig.versions`. */
     readonly versions?: boolean | VersionsConfig;
+    /** Allow scheduling publish/unpublish for a later time (needs `drafts`). */
+    readonly schedule?: boolean;
     /** Live preview: the page that shows the global. See `CollectionConfig.preview`. */
     readonly preview?: PreviewURL;
     readonly access?: GlobalAccess;
@@ -464,6 +524,14 @@ interface Config {
      * `auth.trustedOrigins` are always allowed, with cookies. Default: none.
      */
     readonly cors?: readonly string[] | '*';
+    /**
+     * Lets a cron service run due scheduled jobs: `GET <api>/jobs/run` with
+     * `Authorization: Bearer <cronSecret>`. Default: the `CRON_SECRET` environment variable (the
+     * convention of Vercel Cron). Logged-in admins can always run jobs.
+     */
+    readonly cronSecret?: string;
+    /** Endpoints notified when content changes, e.g. to rebuild a static site. */
+    readonly webhooks?: readonly WebhookConfig[];
     /** Content in several languages: fields with `localized: true` hold one value per locale. */
     readonly localization?: LocalizationConfig | null;
     readonly routes?: RoutesConfig;
@@ -596,16 +664,38 @@ type FieldValue<F extends Field, C extends Config = Config> = F extends {
 }>[] : F extends {
     readonly type: 'group';
     readonly fields: infer Sub extends readonly Field[];
-} ? FieldsValue<Sub, C> : never;
+} ? FieldsValue<Sub, C> : F extends {
+    readonly type: 'blocks';
+    readonly blocks: infer B extends readonly Block[];
+} ? BlockValue<B[number], C>[] : never;
+/** One row of a `blocks` field: the block's fields plus `id` and `blockType` (distributes over kinds). */
+type BlockValue<B, C extends Config> = B extends {
+    readonly slug: infer S;
+    readonly fields: infer Sub extends readonly Field[];
+} ? Simplify<FieldsValue<Sub, C> & {
+    id: string;
+    blockType: S;
+}> : never;
+type BlockInput<B> = B extends {
+    readonly slug: infer S;
+    readonly fields: infer Sub extends readonly Field[];
+} ? Simplify<FieldsInput<Sub> & {
+    id?: string;
+    blockType: S;
+}> : never;
 type Visible<Fs extends readonly Field[]> = Exclude<Fs[number], {
     readonly hidden: true;
 }>;
-type RequiredFields<Fs extends readonly Field[]> = Extract<Visible<Fs>, {
+/** Always set when read: required fields, and lists and groups (empty `[]` / `{}` otherwise). */
+type Present = {
     readonly required: true;
-}>;
-type OptionalFields<Fs extends readonly Field[]> = Exclude<Visible<Fs>, {
-    readonly required: true;
-}>;
+} | {
+    readonly type: 'array' | 'blocks' | 'group';
+} | {
+    readonly hasMany: true;
+};
+type RequiredFields<Fs extends readonly Field[]> = Extract<Visible<Fs>, Present>;
+type OptionalFields<Fs extends readonly Field[]> = Exclude<Visible<Fs>, Present>;
 /** 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>;
@@ -660,7 +750,10 @@ type InputValue<F extends Field> = F extends {
 }>[] : F extends {
     readonly type: 'group';
     readonly fields: infer Sub extends readonly Field[];
-} ? FieldsInput<Sub> : FieldValue<F>;
+} ? FieldsInput<Sub> : F extends {
+    readonly type: 'blocks';
+    readonly blocks: infer B extends readonly Block[];
+} ? readonly BlockInput<B[number]>[] : 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;
@@ -761,6 +854,12 @@ interface FindOptions extends ReadOptions {
 interface CreateEasyCMSOptions {
     /** Project root. Default `process.cwd()`. */
     readonly cwd?: string;
+    /**
+     * Run due scheduled jobs and webhook retries every minute in this process. Default: on when
+     * a collection or global has `schedule`, or `webhooks` is set. Turn it off where a cron calls
+     * `runJobs` (or `GET <api>/jobs/run`) instead.
+     */
+    readonly scheduler?: boolean;
     /** Default `verify` when `NODE_ENV=production`, otherwise `push`. */
     readonly schema?: SchemaMode;
     readonly logger?: Logger;
@@ -768,6 +867,16 @@ interface CreateEasyCMSOptions {
 }
 /** Connects to the database and returns the Local API. */
 declare function createEasyCMS<const C extends Config>(config: C, options?: CreateEasyCMSOptions): Promise<EasyCMS<C>>;
+/** A scheduled publish or unpublish. */
+interface ScheduledJob {
+    readonly id: ID;
+    readonly action: 'publish' | 'unpublish';
+    /** ISO time the job runs at (or after). */
+    readonly runAt: string;
+    readonly state: 'pending' | 'done' | 'failed';
+    readonly error: string | null;
+    readonly author: ID | null;
+}
 declare class EasyCMS<C extends Config = Config> {
     readonly config: ResolvedConfig;
     readonly db: Database;
@@ -777,6 +886,7 @@ declare class EasyCMS<C extends Config = Config> {
     /** Where uploaded files are stored. */
     readonly storage: StorageAdapter;
     private readonly versions;
+    private readonly webhooks;
     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>;
@@ -875,7 +985,65 @@ declare class EasyCMS<C extends Config = Config> {
         delete: boolean;
     }>;
     /** Closes the database connection. */
+    /**
+     * Waits until webhook deliveries in progress are done. Call it before a serverless function
+     * returns, which may otherwise stop them.
+     */
+    flushWebhooks(): Promise<void>;
     destroy(): Promise<void>;
+    private schedulerTimer;
+    private running;
+    /** Runs `runJobs` every `interval` ms in this process (`createEasyCMS` does this by default). */
+    startScheduler(interval?: number): void;
+    /**
+     * Runs due scheduled publishes and unpublishes, and retries failed webhook deliveries. What the
+     * scheduler and the cron endpoint (`GET <api>/jobs/run`) call.
+     */
+    runJobs(now?: Date): Promise<{
+        ran: number;
+        failed: number;
+        webhooks: {
+            sent: number;
+            failed: number;
+        };
+    }>;
+    /**
+     * Tries webhook deliveries that failed earlier and are due for another attempt. Failed
+     * deliveries are kept in the database, so they survive restarts.
+     */
+    retryWebhooks(now?: Date): Promise<{
+        sent: number;
+        failed: number;
+    }>;
+    /** Failed webhook deliveries, stored in `webhook-deliveries`. */
+    private webhookQueue;
+    /**
+     * Publishes or unpublishes documents whose scheduled time has come. Safe to call often, e.g.
+     * from a cron job (`GET <api>/jobs/run`) where no process keeps running.
+     */
+    runScheduled(now?: Date): Promise<{
+        ran: number;
+        failed: number;
+    }>;
+    /** Schedules a publish or unpublish, replacing a pending job with the same action. */
+    schedule<S extends Slug<C>>(collection: S, id: ID, job: {
+        action: 'publish' | 'unpublish';
+        at: Date | string;
+    }, options?: AccessOptions): Promise<ScheduledJob>;
+    /** Pending jobs of a document, soonest first. */
+    scheduled<S extends Slug<C>>(collection: S, id: ID, options?: AccessOptions): Promise<ScheduledJob[]>;
+    cancelSchedule<S extends Slug<C>>(collection: S, id: ID, jobId: ID, options?: AccessOptions): Promise<void>;
+    scheduleGlobal<S extends GSlug<C>>(slug: S, job: {
+        action: 'publish' | 'unpublish';
+        at: Date | string;
+    }, options?: AccessOptions): Promise<ScheduledJob>;
+    scheduledGlobal<S extends GSlug<C>>(slug: S, options?: AccessOptions): Promise<ScheduledJob[]>;
+    cancelGlobalSchedule<S extends GSlug<C>>(slug: S, jobId: ID, options?: AccessOptions): Promise<void>;
+    private scheduleTarget;
+    private globalScheduleTarget;
+    private addJob;
+    private pendingJobs;
+    private removeJob;
     /** @internal */
     collection(slug: string): CollectionConfig;
     private global;
@@ -900,6 +1068,8 @@ declare class EasyCMS<C extends Config = Config> {
     private separateDrafts;
     /** Replaces published documents that have a newer draft with that draft. */
     private withDrafts;
+    /** Sends webhook events for a change; `before` is the stored status before it, if any. */
+    private emit;
     /** Records a version after a save, when the collection or global keeps versions. */
     private saveVersion;
     private hookArgs;
@@ -1161,6 +1331,15 @@ interface AdminField {
     minRows?: number;
     maxRows?: number;
     fields?: AdminField[];
+    /** Block kinds of a `blocks` field. */
+    blocks?: {
+        slug: string;
+        labels?: {
+            singular?: Label;
+            plural?: Label;
+        };
+        fields: AdminField[];
+    }[];
     /** The current user may not change this field. */
     readOnly?: boolean;
     /** One value per content locale. */
@@ -1177,6 +1356,8 @@ interface AdminCollection {
     versions: boolean;
     /** Has live preview (`preview` in the config). */
     preview: boolean;
+    /** Publishing can be scheduled. */
+    schedule: boolean;
     fields: AdminField[];
     permissions: {
         read: boolean;
@@ -1192,6 +1373,8 @@ interface AdminGlobal {
     versions: boolean;
     /** Has live preview (`preview` in the config). */
     preview: boolean;
+    /** Publishing can be scheduled. */
+    schedule: boolean;
     fields: AdminField[];
     permissions: {
         read: boolean;
@@ -1237,4 +1420,4 @@ 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_MAX_VERSIONS, 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 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, PayloadTooLargeError, type Plugin, 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, 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 Version, type VersionSummary, type VersionsConfig, 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 };
+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 Block, type BlocksField, 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_MAX_VERSIONS, 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 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, PayloadTooLargeError, type Plugin, 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 StorageAdapter, type StoredFile, type TextField, type TextareaField, TooManyRequestsError, UnauthorizedError, type UpdateInput, type UploadConfig, type UploadField, ValidationError, type Version, type VersionSummary, type VersionsConfig, WEBHOOK_EVENTS, type WebhookConfig, type WebhookEvent, type WebhookPayload, type Where, type WhereOperators, anyone, applyDefaults, consoleLogger, createEasyCMS, createRestHandler, defineConfig, fillMissing, findConfigFile, generateSlugs, generateTypes, hasRows, hashPassword, imageDimensions, importConfig, isAdmin, isLoggedIn, loadConfig, localStorage, mergeForUpdate, mimeAllowed, parseId, populate, readCookie, resolveConfig, rowFields, silentLogger, singularize, slugify, sniffMimeType, validateConfig, validateFields, verifyPassword };