@pramen/cms 0.0.14 → 0.0.15

package/dist/index.d.ts

@@ -0,0 +1,1078 @@
+import type { HandlerContext, Policy, FileRef } from "@pramen/server";
+/** A field in a block type's (or content type's) field schema. Recursive: a `repeater`
+ * or `group` nests `fields`. Mirrors WollyCMS's FieldDefinition. */
+export interface FieldDefinition {
+    name: string;
+    label?: string;
+    type: "text" | "textarea" | "richtext" | "url" | "number" | "boolean" | "media" | "select" | "repeater" | "group";
+    required?: boolean;
+    default?: unknown;
+    /** repeater/group only — the nested fields. */
+    fields?: FieldDefinition[];
+    /** repeater only — item count bounds. */
+    min?: number;
+    max?: number;
+    /** select only. */
+    options?: string[];
+}
+/** A named region on a content type; `allowedTypes` (block-type slugs) restricts what
+ * may be placed there — `null`/omitted means any. */
+export interface RegionDefinition {
+    name: string;
+    label?: string;
+    allowedTypes?: string[] | null;
+}
+/** A block auto-created in a region when a page of this content type is created. */
+export interface DefaultBlockDefinition {
+    region: string;
+    blockTypeSlug: string;
+    fields?: Record<string, unknown>;
+}
+/** A rich-text value — a serialized editor document (or a plain string). */
+export type RichText = string | {
+    type: string;
+    content?: unknown[];
+};
+/** Map one FieldDefinition (as a const literal) to the TS type of its RENDERED value.
+ * Media resolves to `ResolvedMedia` (the assemble-time shape a component receives). */
+export type FieldTsType<D extends FieldDefinition> = D["type"] extends "text" | "textarea" | "url" | "select" ? string : D["type"] extends "richtext" ? RichText : D["type"] extends "number" ? number : D["type"] extends "boolean" ? boolean : D["type"] extends "media" ? ResolvedMedia | null : D["type"] extends "group" ? InferBlockFields<NonNullable<D["fields"]>> : D["type"] extends "repeater" ? InferBlockFields<NonNullable<D["fields"]>>[] : unknown;
+/** Infer the `fields` object type from a const `FieldDefinition[]`. Required fields are
+ * present; optional ones are `| undefined`. */
+export type InferBlockFields<T extends readonly FieldDefinition[]> = {
+    [D in T[number] as D["name"]]: D extends {
+        required: true;
+    } ? FieldTsType<D> : FieldTsType<D> | undefined;
+};
+/** A developer-authored block type: a slug + a const field schema, carrying enough type
+ * info to (a) create the DB block type and (b) type a rendering component's `fields`. */
+export interface BlockTypeDef<S extends string = string, F extends readonly FieldDefinition[] = readonly FieldDefinition[]> {
+    readonly slug: S;
+    readonly name: string;
+    readonly fieldsSchema: F;
+    readonly description?: string;
+    readonly icon?: string;
+    readonly category?: string;
+}
+/** Declare a typed block type. Pass `fields as const` to preserve the literals so
+ * `BlockFieldsOf<typeof def>` infers the field shape:
+ *
+ *   const hero = defineBlockType("hero", [
+ *     { name: "heading", type: "text", required: true },
+ *     { name: "image", type: "media" },
+ *   ] as const);
+ *   type HeroFields = BlockFieldsOf<typeof hero>; // { heading: string; image: ResolvedMedia|null|undefined }
+ *
+ * Spread `hero` (minus fieldsSchema key naming) into `createBlockType`, and use
+ * `BlockFieldsOf<typeof hero>` to type the block's React component. */
+export declare function defineBlockType<S extends string, F extends readonly FieldDefinition[]>(slug: S, fields: F, opts?: {
+    name?: string;
+    description?: string;
+    icon?: string;
+    category?: string;
+}): BlockTypeDef<S, F>;
+/** The inferred `fields` type of a `defineBlockType` result. */
+export type BlockFieldsOf<D extends BlockTypeDef> = InferBlockFields<D["fieldsSchema"]>;
+/** Emit a `.ts` module of per-slug field interfaces + a `BlockFieldsBySlug` registry from
+ * DB-stored block types (`{ slug, fieldsSchema }` rows). The runtime counterpart to the
+ * compile-time `InferBlockFields`, for webmaster-authored (data-driven) block types. */
+export declare function generateBlockTypes(blockTypes: Array<{
+    slug: string;
+    fieldsSchema?: FieldDefinition[] | null;
+}>): string;
+/** The block/page builder tables. All in the default partition (relations can't cross
+ * partitions). Prefixed `cms_` to avoid colliding with your own entities. */
+export declare const cmsSchema: {
+    cms_content_types: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        name: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        };
+        slug: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly unique: true;
+        };
+        description: {
+            readonly type: "text";
+        };
+        fieldsSchema: {
+            readonly type: "json";
+        };
+        regions: {
+            readonly type: "json";
+        };
+        defaultBlocks: {
+            readonly type: "json";
+        };
+        createdAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+    }, Record<string, never>>;
+    cms_block_types: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        name: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        };
+        slug: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly unique: true;
+        };
+        description: {
+            readonly type: "text";
+        };
+        fieldsSchema: {
+            readonly type: "json";
+        };
+        icon: {
+            readonly type: "text";
+        };
+        category: {
+            readonly type: "text";
+        };
+        createdAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+    }, Record<string, never>>;
+    cms_blocks: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        typeId: {
+            readonly type: "uuid";
+        } & {
+            readonly notNull: true;
+        };
+        title: {
+            readonly type: "text";
+        };
+        fields: {
+            readonly type: "json";
+        };
+        isReusable: {
+            readonly type: "boolean";
+        } & {
+            readonly default: false;
+        };
+        createdAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+        updatedAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+    }, {
+        type: {
+            readonly kind: "belongsTo";
+            readonly target: "cms_block_types";
+            readonly column: string;
+        };
+    }>;
+    cms_pages: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        typeId: {
+            readonly type: "uuid";
+        } & {
+            readonly notNull: true;
+        };
+        title: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        };
+        slug: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly index: true;
+        };
+        status: {
+            readonly type: "text";
+        } & {
+            readonly default: "draft";
+        };
+        locale: {
+            readonly type: "text";
+        } & {
+            readonly default: "en";
+        };
+        translationGroupId: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        };
+        fields: {
+            readonly type: "json";
+        };
+        publishedAt: {
+            readonly type: "text";
+        };
+        scheduledAt: {
+            readonly type: "text";
+        };
+        unpublishAt: {
+            readonly type: "text";
+        };
+        currentRevisionId: {
+            readonly type: "uuid";
+        };
+        metaTitle: {
+            readonly type: "text";
+        };
+        metaDescription: {
+            readonly type: "text";
+        };
+        canonicalUrl: {
+            readonly type: "text";
+        };
+        robots: {
+            readonly type: "text";
+        };
+        ogTitle: {
+            readonly type: "text";
+        };
+        ogDescription: {
+            readonly type: "text";
+        };
+        ogImage: {
+            readonly type: "uuid";
+        };
+        structuredData: {
+            readonly type: "json";
+        };
+        createdAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+        updatedAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+    }, {
+        type: {
+            readonly kind: "belongsTo";
+            readonly target: "cms_content_types";
+            readonly column: string;
+        };
+        placements: {
+            readonly kind: "hasMany";
+            readonly target: "cms_page_blocks";
+            readonly column: string;
+        };
+    }>;
+    cms_page_blocks: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        pageId: {
+            readonly type: "uuid";
+        } & {
+            readonly notNull: true;
+        };
+        blockId: {
+            readonly type: "uuid";
+        } & {
+            readonly notNull: true;
+        };
+        region: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        };
+        position: {
+            readonly type: "integer";
+        } & {
+            readonly notNull: true;
+        };
+        isShared: {
+            readonly type: "boolean";
+        } & {
+            readonly default: false;
+        };
+        overrides: {
+            readonly type: "json";
+        };
+    }, {
+        page: {
+            readonly kind: "belongsTo";
+            readonly target: "cms_pages";
+            readonly column: string;
+        };
+        block: {
+            readonly kind: "belongsTo";
+            readonly target: "cms_blocks";
+            readonly column: string;
+        };
+    }>;
+    cms_page_revisions: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        pageId: {
+            readonly type: "uuid";
+        } & {
+            readonly notNull: true;
+        };
+        title: {
+            readonly type: "text";
+        };
+        status: {
+            readonly type: "text";
+        };
+        snapshot: {
+            readonly type: "json";
+        };
+        note: {
+            readonly type: "text";
+        };
+        actor: {
+            readonly type: "text";
+        };
+        createdAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+    }, {
+        page: {
+            readonly kind: "belongsTo";
+            readonly target: "cms_pages";
+            readonly column: string;
+        };
+    }>;
+    cms_audit: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        pageId: {
+            readonly type: "uuid";
+        } & {
+            readonly index: true;
+        };
+        action: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        };
+        fromStatus: {
+            readonly type: "text";
+        };
+        toStatus: {
+            readonly type: "text";
+        };
+        actor: {
+            readonly type: "text";
+        };
+        note: {
+            readonly type: "text";
+        };
+        createdAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+    }, Record<string, never>>;
+    cms_media: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        file: {
+            readonly type: "fileRef";
+        };
+        alt: {
+            readonly type: "text";
+        };
+        createdAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+    }, Record<string, never>>;
+};
+export interface ValidateOpts {
+    /** Enforce `required` fields (reject when missing). Default true. Editor-facing draft
+     * writes (addBlock/updateBlock/createPage) pass `false` — a DRAFT block may be incomplete;
+     * required is only mandatory when publishing. Type checks always run. */
+    requireRequired?: boolean;
+}
+/** Validate a block/page's `fields` payload against a field schema, throwing a 400 on
+ * the first violation. Recursive (repeater/group). Lenient on unknown field types. */
+export declare function validateFields(schema: FieldDefinition[] | undefined | null, values: unknown, path?: string, opts?: ValidateOpts): void;
+export interface RenderedBlock {
+    /** The placement id (cms_page_blocks) — stable per position; used for reorder/remove. */
+    id: string;
+    /** The underlying block instance id (cms_blocks) — used to edit the block's content. */
+    block_id: string;
+    block_type: string;
+    title: string | null;
+    fields: Record<string, unknown>;
+    is_shared: boolean;
+}
+export interface PageTranslation {
+    locale: string;
+    slug: string;
+}
+export interface PageSeo {
+    metaTitle: string | null;
+    metaDescription: string | null;
+    canonicalUrl: string | null;
+    robots: string | null;
+    ogTitle: string | null;
+    ogDescription: string | null;
+    ogImage: ResolvedMedia | null;
+    structuredData: unknown | null;
+}
+export interface AssembledPage {
+    page: {
+        id: string;
+        title: string;
+        slug: string;
+        status: string;
+        locale: string;
+        translationGroupId: string | null;
+        /** Published sibling locales of this page (for hreflang alternates). */
+        translations: PageTranslation[];
+        fields: Record<string, unknown> | null;
+        /** Back-compat: mirrors seo.metaTitle/metaDescription. */
+        metaTitle: string | null;
+        metaDescription: string | null;
+        seo: PageSeo;
+    };
+    regions: Record<string, RenderedBlock[]>;
+}
+/** A `"media"` block field, resolved from a stored media id to a servable shape at
+ * assemble time. `url` is the raw (full-size) serving path; pass `key` to `imageUrl()`
+ * for on-the-fly transforms. `null` when the referenced media was deleted. */
+export interface ResolvedMedia {
+    id: string;
+    key: string;
+    url: string;
+    alt: string | null;
+    contentType: string | null;
+    filename: string | null;
+}
+/** The public serving path for a media blob (relative; the client resolves it against
+ * its base). Served by the Worker's public `GET /media/<key>` route. */
+export declare function mediaPath(key: string): string;
+/** Build a URL for a media blob, optionally with Cloudflare Image Resizing transforms
+ * (`/cdn-cgi/image/<opts>/…`). With no transform opts it's just `mediaPath` (optionally
+ * prefixed by `origin`). Transforms need the deploy's origin to resolve the source path. */
+export declare function imageUrl(key: string, opts?: {
+    origin?: string;
+    width?: number;
+    height?: number;
+    quality?: number;
+    format?: "auto" | "webp" | "avif";
+}): string;
+export interface CmsHandlerOpts {
+    /** Roles permitted to call the editor mutations (also enforced by the ACL). Default
+     * `["editor", "admin"]`. */
+    editorRoles?: readonly string[];
+    /** Max accepted media upload size in bytes (enforced at the Worker). Default 25 MB. */
+    mediaMaxSize?: number;
+    /** Default locale used when `getPage`/`createPage` omit one. Default `"en"`. */
+    defaultLocale?: string;
+    /** Roles permitted to approve/reject a page in review and publish (the editorial gate).
+     * Default `["reviewer", "admin"]`. */
+    reviewerRoles?: readonly string[];
+}
+/** Build the CMS handler map. Spread into your app's handlers. Editor mutations are
+ * gated both by `auth` (fast 403 before the body) and by the row ACL (cmsPolicies). */
+export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
+    listBlockTypes: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    createBlockType: import("@pramen/server").Handler<{
+        name: string;
+        slug: string;
+        fieldsSchema?: FieldDefinition[];
+        icon?: string;
+        category?: string;
+        description?: string;
+    }, Record<string, unknown>>;
+    createContentType: import("@pramen/server").Handler<{
+        name: string;
+        slug: string;
+        regions: RegionDefinition[];
+        fieldsSchema?: FieldDefinition[];
+        defaultBlocks?: DefaultBlockDefinition[];
+    }, Record<string, unknown>>;
+    /** Mint a signed upload URL for a media blob (keyed under the tenant's `media/`
+     * prefix so the public /media route can serve it). The client PUTs the bytes to
+     * `url`, then calls `createMedia` with the returned `ref`. */
+    signMediaUpload: import("@pramen/server").Handler<{
+        contentType: string;
+        filename?: string;
+    }, {
+        url: string;
+        ref: FileRef;
+    }>;
+    /** Confirm an uploaded blob is really in storage (capturing its true size) and
+     * persist a `cms_media` row. Mirrors the notes attach flow. */
+    createMedia: import("@pramen/server").Handler<{
+        ref: FileRef;
+        alt?: string;
+    }, Record<string, unknown>>;
+    listMedia: import("@pramen/server").Handler<{
+        limit?: number;
+        offset?: number;
+    }, Record<string, unknown>[]>;
+    getMedia: import("@pramen/server").Handler<{
+        id: string;
+    }, Record<string, unknown>>;
+    /** Edit a media asset's metadata (currently just `alt` text). Editor-gated. */
+    updateMedia: import("@pramen/server").Handler<{
+        id: string;
+        alt: string | null;
+    }, Record<string, unknown>>;
+    /** Delete a media row AND its R2 blob. (Automatic orphan sweeping — media no longer
+     * referenced by any block — is future work; refs live inside opaque block JSON.) */
+    deleteMedia: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: boolean;
+    }>;
+    listContentTypes: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    getContentType: import("@pramen/server").Handler<{
+        id: string;
+    }, Record<string, unknown>>;
+    listPages: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    /** Public: list published pages (slug, locale, updatedAt) for sitemap generation. The
+     * anonymous ACL scopes cms_pages reads to status=published, so this is safe to expose. */
+    listPublishedPages: import("@pramen/server").Handler<unknown, {
+        slug: string;
+        locale: string;
+        updatedAt: string;
+    }[]>;
+    /** Update a page's SEO fields (meta/canonical/robots/OpenGraph/JSON-LD). Editor-gated. */
+    updatePageSeo: import("@pramen/server").Handler<{
+        pageId: string;
+    }, {
+        ok: boolean;
+        page: Record<string, unknown>;
+    }>;
+    /** Create a page and auto-scaffold its content type's default blocks. */
+    createPage: import("@pramen/server").Handler<{
+        typeId: string;
+        title: string;
+        slug: string;
+        locale?: string;
+        fields?: Record<string, unknown>;
+    }, Record<string, unknown>>;
+    /** Create a translation of an existing page: a new page in `locale` sharing the
+     * source's translationGroupId (and content type). Content starts empty — the editor
+     * fills in the translated blocks. Slug defaults to the source's (allowed in a new locale). */
+    createTranslation: import("@pramen/server").Handler<{
+        pageId: string;
+        locale: string;
+        title?: string;
+        slug?: string;
+    }, Record<string, unknown>>;
+    /** List all locales of a page (the translation group), including the page itself. */
+    listTranslations: import("@pramen/server").Handler<{
+        pageId: string;
+    }, {
+        id: string;
+        locale: string;
+        slug: string;
+        title: string;
+        status: string;
+    }[]>;
+    /** Distinct locales present across all pages. */
+    listLocales: import("@pramen/server").Handler<unknown, string[]>;
+    /** Create a block instance and place it into a page region in one call (the common
+     * editor action). Validates the fields against the block type's schema and the region
+     * against the content type's allow-list. */
+    addBlock: import("@pramen/server").Handler<{
+        pageId: string;
+        blockTypeSlug: string;
+        region: string;
+        fields?: Record<string, unknown>;
+        title?: string;
+        position?: number;
+        isReusable?: boolean;
+    }, {
+        block: Record<string, unknown>;
+        placement: Record<string, unknown>;
+    }>;
+    /** Place an EXISTING (typically reusable) block into a page region as a SHARED
+     * placement, with optional per-placement `overrides` merged over the block's fields at
+     * read time. This is the "edit once, appear on many pages" workflow — the same block id
+     * can be placed on several pages; editing it updates them all, while `overrides` let one
+     * placement diverge. The merged (base + overrides) result is validated against the
+     * block type's field schema. */
+    placeBlock: import("@pramen/server").Handler<{
+        pageId: string;
+        blockId: string;
+        region: string;
+        position?: number;
+        overrides?: Record<string, unknown>;
+    }, Record<string, unknown>>;
+    /** Fetch a block's RAW content (media fields as ids, not resolved) — for editing. */
+    getBlock: import("@pramen/server").Handler<{
+        blockId: string;
+    }, Record<string, unknown>>;
+    /** Update a block's content (re-validated against its type's field schema). */
+    updateBlock: import("@pramen/server").Handler<{
+        blockId: string;
+        fields?: Record<string, unknown>;
+        title?: string;
+    }, Record<string, unknown> | undefined>;
+    /** Reorder a region: `order` is the page_block ids in their new order. It must cover
+     * EXACTLY the region's current placements (same set, no dups) — otherwise a partial or
+     * stale list would leave untouched placements colliding at a shared position. */
+    reorderRegion: import("@pramen/server").Handler<{
+        pageId: string;
+        region: string;
+        order: string[];
+    }, {
+        ok: boolean;
+        count: number;
+    }>;
+    /** Remove a placement. A reusable/shared block stays in the library (it may be placed
+     * elsewhere); a non-reusable block with no remaining placements is deleted too, so
+     * add/remove churn doesn't accumulate unreachable block rows. */
+    removeBlock: import("@pramen/server").Handler<{
+        pageBlockId: string;
+    }, {
+        ok: boolean;
+    }>;
+    /** Move a draft (or rejected) page into review. Editor-gated. */
+    submitForReview: import("@pramen/server").Handler<{
+        pageId: string;
+        note?: string;
+    }, {
+        ok: boolean;
+        page: Record<string, unknown> | undefined;
+    }>;
+    /** Approve a page in review → publish it (snapshot + currentRevisionId). Reviewer-gated. */
+    approve: import("@pramen/server").Handler<{
+        pageId: string;
+        note?: string;
+    }, {
+        ok: boolean;
+        page: Record<string, unknown> | undefined;
+    }>;
+    /** Reject a page in review → back to draft. Reviewer-gated. */
+    reject: import("@pramen/server").Handler<{
+        pageId: string;
+        note?: string;
+    }, {
+        ok: boolean;
+        page: Record<string, unknown> | undefined;
+    }>;
+    /** The workflow audit trail for a page (most recent first). Handler-gated to editors;
+     * reads the append-only log via `exec` (a plain admin-scoped read of a gated log). */
+    listPageAudit: import("@pramen/server").Handler<{
+        pageId: string;
+        limit?: number;
+    }, Record<string, unknown>[]>;
+    /** Publish a page directly: snapshot the assembled page into a revision and flip
+     * status to `published` (records an audit entry). The public content API serves the
+     * snapshot. `approve` is the review-gated path to the same outcome. */
+    publishPage: import("@pramen/server").Handler<{
+        pageId: string;
+        note?: string;
+    }, {
+        ok: boolean;
+        page: Record<string, unknown> | undefined;
+    }>;
+    unpublishPage: import("@pramen/server").Handler<{
+        pageId: string;
+    }, {
+        ok: boolean;
+        page: Record<string, unknown>;
+    }>;
+    /** Schedule a page to publish at `publishAt` (epoch ms), and optionally unpublish at
+     * `unpublishAt`. Enqueues delayed outbox tasks (atomic with this write).
+     *
+     * Outbox tasks can't be recalled, so cancellation/rescheduling is handled by INTENT
+     * TOKENS: the page stores the scheduled times (`scheduledAt`/`unpublishAt`, ISO), and
+     * each task carries the token it was enqueued for. At fire time the task acts ONLY if
+     * its token still equals the page's current token — so rescheduling (new token),
+     * manual publish/unpublish (token cleared), and duplicate deliveries all make a stale
+     * task a no-op. `unpublishAt` must be after `publishAt`. */
+    schedulePage: import("@pramen/server").Handler<{
+        pageId: string;
+        publishAt: number;
+        unpublishAt?: number;
+    }, {
+        ok: boolean;
+        publishInMs: number;
+    }>;
+    /** Fetch an assembled page by slug (+ locale). Anonymous callers get the published
+     * snapshot (the ACL scopes `cms_pages` reads to `status = published`). Editors may pass
+     * `preview: true` to assemble the current DRAFT live from the tables. `locale` defaults
+     * to the configured default locale; a slug is unique per locale. */
+    getPage: import("@pramen/server").Handler<{
+        slug: string;
+        locale?: string;
+        preview?: boolean;
+    }, AssembledPage>;
+};
+/** The default CMS handlers (editor roles `["editor", "admin"]`). */
+export declare const cmsHandlers: {
+    listBlockTypes: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    createBlockType: import("@pramen/server").Handler<{
+        name: string;
+        slug: string;
+        fieldsSchema?: FieldDefinition[];
+        icon?: string;
+        category?: string;
+        description?: string;
+    }, Record<string, unknown>>;
+    createContentType: import("@pramen/server").Handler<{
+        name: string;
+        slug: string;
+        regions: RegionDefinition[];
+        fieldsSchema?: FieldDefinition[];
+        defaultBlocks?: DefaultBlockDefinition[];
+    }, Record<string, unknown>>;
+    /** Mint a signed upload URL for a media blob (keyed under the tenant's `media/`
+     * prefix so the public /media route can serve it). The client PUTs the bytes to
+     * `url`, then calls `createMedia` with the returned `ref`. */
+    signMediaUpload: import("@pramen/server").Handler<{
+        contentType: string;
+        filename?: string;
+    }, {
+        url: string;
+        ref: FileRef;
+    }>;
+    /** Confirm an uploaded blob is really in storage (capturing its true size) and
+     * persist a `cms_media` row. Mirrors the notes attach flow. */
+    createMedia: import("@pramen/server").Handler<{
+        ref: FileRef;
+        alt?: string;
+    }, Record<string, unknown>>;
+    listMedia: import("@pramen/server").Handler<{
+        limit?: number;
+        offset?: number;
+    }, Record<string, unknown>[]>;
+    getMedia: import("@pramen/server").Handler<{
+        id: string;
+    }, Record<string, unknown>>;
+    /** Edit a media asset's metadata (currently just `alt` text). Editor-gated. */
+    updateMedia: import("@pramen/server").Handler<{
+        id: string;
+        alt: string | null;
+    }, Record<string, unknown>>;
+    /** Delete a media row AND its R2 blob. (Automatic orphan sweeping — media no longer
+     * referenced by any block — is future work; refs live inside opaque block JSON.) */
+    deleteMedia: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: boolean;
+    }>;
+    listContentTypes: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    getContentType: import("@pramen/server").Handler<{
+        id: string;
+    }, Record<string, unknown>>;
+    listPages: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    /** Public: list published pages (slug, locale, updatedAt) for sitemap generation. The
+     * anonymous ACL scopes cms_pages reads to status=published, so this is safe to expose. */
+    listPublishedPages: import("@pramen/server").Handler<unknown, {
+        slug: string;
+        locale: string;
+        updatedAt: string;
+    }[]>;
+    /** Update a page's SEO fields (meta/canonical/robots/OpenGraph/JSON-LD). Editor-gated. */
+    updatePageSeo: import("@pramen/server").Handler<{
+        pageId: string;
+    }, {
+        ok: boolean;
+        page: Record<string, unknown>;
+    }>;
+    /** Create a page and auto-scaffold its content type's default blocks. */
+    createPage: import("@pramen/server").Handler<{
+        typeId: string;
+        title: string;
+        slug: string;
+        locale?: string;
+        fields?: Record<string, unknown>;
+    }, Record<string, unknown>>;
+    /** Create a translation of an existing page: a new page in `locale` sharing the
+     * source's translationGroupId (and content type). Content starts empty — the editor
+     * fills in the translated blocks. Slug defaults to the source's (allowed in a new locale). */
+    createTranslation: import("@pramen/server").Handler<{
+        pageId: string;
+        locale: string;
+        title?: string;
+        slug?: string;
+    }, Record<string, unknown>>;
+    /** List all locales of a page (the translation group), including the page itself. */
+    listTranslations: import("@pramen/server").Handler<{
+        pageId: string;
+    }, {
+        id: string;
+        locale: string;
+        slug: string;
+        title: string;
+        status: string;
+    }[]>;
+    /** Distinct locales present across all pages. */
+    listLocales: import("@pramen/server").Handler<unknown, string[]>;
+    /** Create a block instance and place it into a page region in one call (the common
+     * editor action). Validates the fields against the block type's schema and the region
+     * against the content type's allow-list. */
+    addBlock: import("@pramen/server").Handler<{
+        pageId: string;
+        blockTypeSlug: string;
+        region: string;
+        fields?: Record<string, unknown>;
+        title?: string;
+        position?: number;
+        isReusable?: boolean;
+    }, {
+        block: Record<string, unknown>;
+        placement: Record<string, unknown>;
+    }>;
+    /** Place an EXISTING (typically reusable) block into a page region as a SHARED
+     * placement, with optional per-placement `overrides` merged over the block's fields at
+     * read time. This is the "edit once, appear on many pages" workflow — the same block id
+     * can be placed on several pages; editing it updates them all, while `overrides` let one
+     * placement diverge. The merged (base + overrides) result is validated against the
+     * block type's field schema. */
+    placeBlock: import("@pramen/server").Handler<{
+        pageId: string;
+        blockId: string;
+        region: string;
+        position?: number;
+        overrides?: Record<string, unknown>;
+    }, Record<string, unknown>>;
+    /** Fetch a block's RAW content (media fields as ids, not resolved) — for editing. */
+    getBlock: import("@pramen/server").Handler<{
+        blockId: string;
+    }, Record<string, unknown>>;
+    /** Update a block's content (re-validated against its type's field schema). */
+    updateBlock: import("@pramen/server").Handler<{
+        blockId: string;
+        fields?: Record<string, unknown>;
+        title?: string;
+    }, Record<string, unknown> | undefined>;
+    /** Reorder a region: `order` is the page_block ids in their new order. It must cover
+     * EXACTLY the region's current placements (same set, no dups) — otherwise a partial or
+     * stale list would leave untouched placements colliding at a shared position. */
+    reorderRegion: import("@pramen/server").Handler<{
+        pageId: string;
+        region: string;
+        order: string[];
+    }, {
+        ok: boolean;
+        count: number;
+    }>;
+    /** Remove a placement. A reusable/shared block stays in the library (it may be placed
+     * elsewhere); a non-reusable block with no remaining placements is deleted too, so
+     * add/remove churn doesn't accumulate unreachable block rows. */
+    removeBlock: import("@pramen/server").Handler<{
+        pageBlockId: string;
+    }, {
+        ok: boolean;
+    }>;
+    /** Move a draft (or rejected) page into review. Editor-gated. */
+    submitForReview: import("@pramen/server").Handler<{
+        pageId: string;
+        note?: string;
+    }, {
+        ok: boolean;
+        page: Record<string, unknown> | undefined;
+    }>;
+    /** Approve a page in review → publish it (snapshot + currentRevisionId). Reviewer-gated. */
+    approve: import("@pramen/server").Handler<{
+        pageId: string;
+        note?: string;
+    }, {
+        ok: boolean;
+        page: Record<string, unknown> | undefined;
+    }>;
+    /** Reject a page in review → back to draft. Reviewer-gated. */
+    reject: import("@pramen/server").Handler<{
+        pageId: string;
+        note?: string;
+    }, {
+        ok: boolean;
+        page: Record<string, unknown> | undefined;
+    }>;
+    /** The workflow audit trail for a page (most recent first). Handler-gated to editors;
+     * reads the append-only log via `exec` (a plain admin-scoped read of a gated log). */
+    listPageAudit: import("@pramen/server").Handler<{
+        pageId: string;
+        limit?: number;
+    }, Record<string, unknown>[]>;
+    /** Publish a page directly: snapshot the assembled page into a revision and flip
+     * status to `published` (records an audit entry). The public content API serves the
+     * snapshot. `approve` is the review-gated path to the same outcome. */
+    publishPage: import("@pramen/server").Handler<{
+        pageId: string;
+        note?: string;
+    }, {
+        ok: boolean;
+        page: Record<string, unknown> | undefined;
+    }>;
+    unpublishPage: import("@pramen/server").Handler<{
+        pageId: string;
+    }, {
+        ok: boolean;
+        page: Record<string, unknown>;
+    }>;
+    /** Schedule a page to publish at `publishAt` (epoch ms), and optionally unpublish at
+     * `unpublishAt`. Enqueues delayed outbox tasks (atomic with this write).
+     *
+     * Outbox tasks can't be recalled, so cancellation/rescheduling is handled by INTENT
+     * TOKENS: the page stores the scheduled times (`scheduledAt`/`unpublishAt`, ISO), and
+     * each task carries the token it was enqueued for. At fire time the task acts ONLY if
+     * its token still equals the page's current token — so rescheduling (new token),
+     * manual publish/unpublish (token cleared), and duplicate deliveries all make a stale
+     * task a no-op. `unpublishAt` must be after `publishAt`. */
+    schedulePage: import("@pramen/server").Handler<{
+        pageId: string;
+        publishAt: number;
+        unpublishAt?: number;
+    }, {
+        ok: boolean;
+        publishInMs: number;
+    }>;
+    /** Fetch an assembled page by slug (+ locale). Anonymous callers get the published
+     * snapshot (the ACL scopes `cms_pages` reads to `status = published`). Editors may pass
+     * `preview: true` to assemble the current DRAFT live from the tables. `locale` defaults
+     * to the configured default locale; a slug is unique per locale. */
+    getPage: import("@pramen/server").Handler<{
+        slug: string;
+        locale?: string;
+        preview?: boolean;
+    }, AssembledPage>;
+};
+export interface CmsPolicyOpts {
+    /** Prefix for policy names (unique across roles). Default `cms`. */
+    prefix?: string;
+}
+/** ACL fragments. Spread `public` into your anonymous role and `editor` into your
+ * editor/admin role:
+ *
+ *   role("anonymous", [...cmsPolicies().public])
+ *   role("editor",    [...cmsPolicies().editor])
+ *
+ * `public` grants read of PUBLISHED pages + their revision snapshots only (the public
+ * content API reads the snapshot, so unpublished block rows are never exposed).
+ * `editor` grants full CRUD across every cms_ table. */
+export declare function cmsPolicies(opts?: CmsPolicyOpts): {
+    public: Policy[];
+    editor: Policy[];
+};
+/** Task handlers backing `schedulePage`. Register via `app.tasks = { ...cmsTasks }`.
+ * They run with a privileged, system-scoped ctx off the write path (the outbox drain).
+ *
+ * Each task validates its INTENT TOKEN against the page's current `scheduledAt`/`unpublishAt`
+ * (set by `schedulePage`, cleared/overwritten by a manual publish/unpublish or a reschedule).
+ * A task whose token no longer matches is a no-op — that's how a superseded/cancelled
+ * schedule, and an at-least-once duplicate delivery, are neutralized (outbox tasks can't be
+ * recalled). NOTE on atomicity: unlike the interactive `publishPage` (one mutation
+ * transaction), the drain runs a handler WITHOUT a surrounding transaction, so a crash
+ * between the revision insert and the page update leaves the page unpublished with an orphan
+ * revision until the next at-least-once redelivery re-runs (the token still matches, so it
+ * completes). Acceptable for a scheduled job; the interactive path is atomic. */
+export declare const cmsTasks: {
+    "cms:publish": (ctx: HandlerContext, payload: unknown) => Promise<void>;
+    "cms:unpublish": (ctx: HandlerContext, payload: unknown) => Promise<void>;
+};
+export interface SitemapEntry {
+    slug: string;
+    locale: string;
+    updatedAt?: string;
+}
+export interface SitemapOpts {
+    origin: string;
+    /** Map an entry → its absolute URL. Default `${origin}/${locale}/${slug}`. */
+    pageUrl?: (e: SitemapEntry, origin: string) => string;
+}
+/** Build a sitemap.xml body from published-page entries. */
+export declare function sitemapXml(entries: SitemapEntry[], opts: SitemapOpts): string;
+/** Build a robots.txt body pointing at the sitemap. */
+export declare function robotsTxt(opts: {
+    origin: string;
+    disallow?: string[];
+}): string;
+interface RouteCtx {
+    callPrivileged: (opts: {
+        name: string;
+        input?: unknown;
+        tenant?: string;
+        roles?: string[];
+    }) => Promise<Response>;
+}
+interface CmsRoute {
+    method: string;
+    path: string;
+    handler: (request: Request, env: Readonly<Record<string, unknown>>, ctx: RouteCtx) => Promise<Response>;
+}
+/** Turnkey public routes for `GET /sitemap.xml` and `GET /robots.txt`. Spread into
+ * `app.routes`. The sitemap pulls published pages via `callPrivileged(listPublishedPages)`.
+ * `origin` defaults to the request's origin; `pageUrl` customizes the URL shape. */
+export declare function cmsRoutes(opts?: {
+    origin?: string;
+    tenant?: string;
+    pageUrl?: SitemapOpts["pageUrl"];
+    disallow?: string[];
+}): CmsRoute[];
+export {};