@velora-cms/api-schemas 0.9.0

package/dist/public-api.schema.d.ts

@@ -0,0 +1,211 @@
+import { z } from "zod";
+export declare const PublicContentExtensionsSchema: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+export declare const PublicContentItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    documentTypeId: z.ZodString;
+    locale: z.ZodString;
+    publishedAt: z.ZodNullable<z.ZodString>;
+    version: z.ZodNumber;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
+export type PublicContentItem = z.infer<typeof PublicContentItemSchema>;
+export declare const PublicContentItemQuerySchema: z.ZodObject<{
+    locale: z.ZodOptional<z.ZodString>;
+    fallback: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    previewToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PublicContentItemQuery = z.infer<typeof PublicContentItemQuerySchema>;
+export declare const PublicContentFormatResponseSchema: z.ZodObject<{
+    format: z.ZodString;
+    content: z.ZodUnknown;
+}, z.core.$strip>;
+export type PublicContentFormatResponse = z.infer<typeof PublicContentFormatResponseSchema>;
+export declare const PublicContentByPathQuerySchema: z.ZodObject<{
+    locale: z.ZodOptional<z.ZodString>;
+    fallback: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    previewToken: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+}, z.core.$strip>;
+export type PublicContentByPathQuery = z.infer<typeof PublicContentByPathQuerySchema>;
+export declare const PublicContentListQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type PublicContentListQuery = z.infer<typeof PublicContentListQuerySchema>;
+export declare const PublicContentNodeSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    parentId: z.ZodNullable<z.ZodString>;
+    path: z.ZodString;
+    depth: z.ZodNumber;
+    sortOrder: z.ZodNumber;
+    documentTypeId: z.ZodString;
+    locale: z.ZodString;
+    publishedAt: z.ZodString;
+}, z.core.$strip>;
+export type PublicContentNodeSummary = z.infer<typeof PublicContentNodeSummarySchema>;
+export declare const PublicContentListResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        parentId: z.ZodNullable<z.ZodString>;
+        path: z.ZodString;
+        depth: z.ZodNumber;
+        sortOrder: z.ZodNumber;
+        documentTypeId: z.ZodString;
+        locale: z.ZodString;
+        publishedAt: z.ZodString;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type PublicContentListResponse = z.infer<typeof PublicContentListResponseSchema>;
+export declare const PublicContentSearchQuerySchema: z.ZodObject<{
+    documentTypeId: z.ZodOptional<z.ZodString>;
+    under: z.ZodOptional<z.ZodString>;
+    q: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type PublicContentSearchQuery = z.infer<typeof PublicContentSearchQuerySchema>;
+export declare const PublicMediaFileSchema: z.ZodObject<{
+    id: z.ZodString;
+    filename: z.ZodString;
+    mimeType: z.ZodString;
+    size: z.ZodNumber;
+    downloadUrl: z.ZodString;
+    uploadedAt: z.ZodString;
+}, z.core.$strip>;
+export type PublicMediaFile = z.infer<typeof PublicMediaFileSchema>;
+export declare const PublicMediaListQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    search: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PublicMediaListQuery = z.infer<typeof PublicMediaListQuerySchema>;
+export declare const PublicMediaListResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        filename: z.ZodString;
+        mimeType: z.ZodString;
+        size: z.ZodNumber;
+        downloadUrl: z.ZodString;
+        uploadedAt: z.ZodString;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type PublicMediaListResponse = z.infer<typeof PublicMediaListResponseSchema>;
+export declare const PublicFieldDefinitionSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    datatypeId: z.ZodString;
+    validation: z.ZodOptional<z.ZodObject<{
+        required: z.ZodOptional<z.ZodBoolean>;
+        minLength: z.ZodOptional<z.ZodNumber>;
+        maxLength: z.ZodOptional<z.ZodNumber>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        pattern: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PublicFieldDefinition = z.infer<typeof PublicFieldDefinitionSchema>;
+export declare const PublicDocumentTypeSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    icon: z.ZodString;
+    kind: z.ZodEnum<{
+        page: "page";
+        element: "element";
+    }>;
+    fields: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        datatypeId: z.ZodString;
+        validation: z.ZodOptional<z.ZodObject<{
+            required: z.ZodOptional<z.ZodBoolean>;
+            minLength: z.ZodOptional<z.ZodNumber>;
+            maxLength: z.ZodOptional<z.ZodNumber>;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            pattern: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PublicDocumentType = z.infer<typeof PublicDocumentTypeSchema>;
+export declare const PublicDocumentTypeListQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type PublicDocumentTypeListQuery = z.infer<typeof PublicDocumentTypeListQuerySchema>;
+export declare const PublicDocumentTypeListResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        icon: z.ZodString;
+        kind: z.ZodEnum<{
+            page: "page";
+            element: "element";
+        }>;
+        fields: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            datatypeId: z.ZodString;
+            validation: z.ZodOptional<z.ZodObject<{
+                required: z.ZodOptional<z.ZodBoolean>;
+                minLength: z.ZodOptional<z.ZodNumber>;
+                maxLength: z.ZodOptional<z.ZodNumber>;
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+                pattern: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type PublicDocumentTypeListResponse = z.infer<typeof PublicDocumentTypeListResponseSchema>;
+export declare const PublicTemplateSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    documentTypeId: z.ZodString;
+}, z.core.$strip>;
+export type PublicTemplate = z.infer<typeof PublicTemplateSchema>;
+export declare const PublicTemplateListQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    documentTypeId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PublicTemplateListQuery = z.infer<typeof PublicTemplateListQuerySchema>;
+export declare const PublicTemplateListResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        documentTypeId: z.ZodString;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type PublicTemplateListResponse = z.infer<typeof PublicTemplateListResponseSchema>;
+export declare const PublicContentWriteResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    documentTypeId: z.ZodString;
+    parentId: z.ZodNullable<z.ZodString>;
+    path: z.ZodString;
+    locale: z.ZodString;
+    version: z.ZodNumber;
+    publishedAt: z.ZodNullable<z.ZodString>;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type PublicContentWriteResponse = z.infer<typeof PublicContentWriteResponseSchema>;
+export declare const PublicCreateContentRequestSchema: z.ZodObject<{
+    documentTypeId: z.ZodString;
+    parentId: z.ZodNullable<z.ZodString>;
+    slug: z.ZodString;
+    locale: z.ZodDefault<z.ZodString>;
+    isDefaultLocale: z.ZodDefault<z.ZodBoolean>;
+    translationGroupId: z.ZodOptional<z.ZodString>;
+    data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type PublicCreateContentRequest = z.infer<typeof PublicCreateContentRequestSchema>;
+export declare const PublicUpdateContentRequestSchema: z.ZodObject<{
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type PublicUpdateContentRequest = z.infer<typeof PublicUpdateContentRequestSchema>;

package/dist/public-api.schema.js

@@ -0,0 +1,185 @@
+import { z } from "zod";
+// Session 112: serializer-contribution output. Keyed by pluginId —
+// structurally separate from core fields and `data`, so a contribution
+// can never remove or overwrite either. Present only when at least one
+// active plugin's extendContentResponse produced a value.
+export const PublicContentExtensionsSchema = z.record(z.string(), z.record(z.string(), z.unknown()));
+// The public Content API's own wire contract (Month 9). Deliberately NOT
+// a re-export of the backoffice ContentNode/ContentVersion shapes — the
+// public surface exposes only what an external consumer needs, and can
+// stay stable while internal shapes evolve. Session 103 widens this file.
+// Session 116: `publishedAt` is nullable ONLY here — a verified preview
+// token can serve a genuinely-draft node's latest version, which has no
+// publishedAt. Every other public schema (summaries/lists) stays on the
+// published-only surface and keeps its non-null publishedAt unchanged.
+export const PublicContentItemSchema = z.object({
+    id: z.string().uuid(),
+    documentTypeId: z.string().uuid(),
+    locale: z.string().min(2),
+    publishedAt: z.string().datetime().nullable(),
+    version: z.number().int().positive(),
+    data: z.record(z.string(), z.unknown()),
+    extensions: PublicContentExtensionsSchema.optional(),
+});
+// Locale params mirror the backoffice contract exactly (content-api.schema):
+// `fallback` is a fallback LOCALE (string), not a boolean — ?locale=ar&fallback=en.
+// `previewToken` (Session 116) is a stateless signed token minted by
+// POST /api/content/:id/preview-token; verified once per request against
+// the FINAL resolved (post-locale) node id — see published-item.ts.
+export const PublicContentItemQuerySchema = z.object({
+    locale: z.string().min(2).optional(),
+    fallback: z.string().min(2).optional(),
+    format: z.string().regex(/^[a-z0-9.-]+:[a-z0-9-]+$/).optional(),
+    previewToken: z.string().optional(),
+});
+// A custom-format read (?format=<pluginId>:<name>) — the plugin's whole
+// projection rides in `content`; the caller asked for the plugin's shape,
+// so the server imposes nothing beyond JSON-serializability.
+export const PublicContentFormatResponseSchema = z.object({
+    format: z.string(),
+    content: z.unknown(),
+});
+export const PublicContentByPathQuerySchema = PublicContentItemQuerySchema.extend({
+    path: z.string().min(1).startsWith("/"),
+});
+export const PublicContentListQuerySchema = z.object({
+    cursor: z.string().uuid().optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+});
+// The tree-walk row: everything a consumer needs to render navigation and
+// fetch the full item — no version data (fetch by id for that), and
+// publishedAt is non-nullable by construction (published-only surface).
+export const PublicContentNodeSummarySchema = z.object({
+    id: z.string().uuid(),
+    parentId: z.string().uuid().nullable(),
+    path: z.string().min(1),
+    depth: z.number().int().nonnegative(),
+    sortOrder: z.number().int(),
+    documentTypeId: z.string().uuid(),
+    locale: z.string().min(2),
+    publishedAt: z.string().datetime(),
+});
+export const PublicContentListResponseSchema = z.object({
+    items: z.array(PublicContentNodeSummarySchema),
+    nextCursor: z.string().uuid().nullable(),
+});
+// GET /api/v1/content — combinable filters over the published surface.
+// `under` is a published node's id; the server resolves it to a subtree
+// path filter (strict descendants). q is a case-insensitive substring
+// (ASCII-pinned), min 2 chars so a single char can't trigger full scans.
+export const PublicContentSearchQuerySchema = z.object({
+    documentTypeId: z.string().uuid().optional(),
+    under: z.string().uuid().optional(),
+    q: z.string().min(2).optional(),
+    cursor: z.string().uuid().optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+});
+// Public media (Month 9, Session 105). downloadUrl is generated per
+// response — a fresh presigned GET, same convention as the backoffice
+// MediaFileResponseSchema — never the persisted canonical url, never
+// stored. filename/mimeType/size/uploadedAt are safe to expose as-is;
+// uploadedBy (an internal user id) is deliberately omitted.
+export const PublicMediaFileSchema = z.object({
+    id: z.string().uuid(),
+    filename: z.string().min(1),
+    mimeType: z.string().min(1),
+    size: z.number().int().nonnegative(),
+    downloadUrl: z.string().url(),
+    uploadedAt: z.string().datetime(),
+});
+export const PublicMediaListQuerySchema = z.object({
+    cursor: z.string().uuid().optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(24),
+    search: z.string().min(1).optional(),
+});
+export const PublicMediaListResponseSchema = z.object({
+    items: z.array(PublicMediaFileSchema),
+    nextCursor: z.string().uuid().nullable(),
+});
+// Public document type introspection. Deliberately narrower than the
+// backoffice DocumentTypeDefinitionSchema: tabs (admin-UI organization),
+// treeRules (an admin content-placement rule), and defaultTemplateId (an
+// editor pointer — the separate templates resource covers discovery) are
+// all excluded. Just enough to interpret a fetched ContentVersion.data:
+// each field's data key (id), display name, datatypeId, and its
+// client-facing validation rules.
+export const PublicFieldDefinitionSchema = z.object({
+    id: z.string(),
+    name: z.string().min(1),
+    datatypeId: z.string().min(1),
+    validation: z
+        .object({
+        required: z.boolean().optional(),
+        minLength: z.number().int().nonnegative().optional(),
+        maxLength: z.number().int().nonnegative().optional(),
+        min: z.number().optional(),
+        max: z.number().optional(),
+        pattern: z.string().min(1).optional(),
+    })
+        .optional(),
+});
+export const PublicDocumentTypeSchema = z.object({
+    id: z.string().uuid(),
+    name: z.string().min(1),
+    icon: z.string().min(1),
+    kind: z.enum(["page", "element"]),
+    fields: z.array(PublicFieldDefinitionSchema),
+});
+export const PublicDocumentTypeListQuerySchema = z.object({
+    cursor: z.string().uuid().optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+});
+export const PublicDocumentTypeListResponseSchema = z.object({
+    items: z.array(PublicDocumentTypeSchema),
+    nextCursor: z.string().uuid().nullable(),
+});
+// Templates are inert data (headless-first decision) — the public shape
+// is the same three fields the backoffice already exposes, defined fresh
+// as its own contract rather than re-exporting TemplateDefinitionSchema.
+export const PublicTemplateSchema = z.object({
+    id: z.string().uuid(),
+    name: z.string().min(1),
+    documentTypeId: z.string().uuid(),
+});
+export const PublicTemplateListQuerySchema = z.object({
+    cursor: z.string().uuid().optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+    documentTypeId: z.string().uuid().optional(),
+});
+export const PublicTemplateListResponseSchema = z.object({
+    items: z.array(PublicTemplateSchema),
+    nextCursor: z.string().uuid().nullable(),
+});
+// Public content write shapes (Month 9, Session 107). The write surface is
+// key-gated and NOT published-only — a writer operates on a node by id in
+// any publish state, so `publishedAt` here is nullable (a fresh draft),
+// unlike the read PublicContentItemSchema's non-null publishedAt.
+export const PublicContentWriteResponseSchema = z.object({
+    id: z.string().uuid(),
+    documentTypeId: z.string().uuid(),
+    parentId: z.string().uuid().nullable(),
+    path: z.string().min(1),
+    locale: z.string().min(2),
+    version: z.number().int().positive(),
+    publishedAt: z.string().datetime().nullable(),
+    data: z.record(z.string(), z.unknown()),
+});
+// Create derives path/depth/sortOrder server-side from parentId + slug, so
+// an external consumer never computes tree internals. `slug` is an
+// already-slugified path segment; `data` defaults to {} (the stub-then-
+// PATCH pattern). Non-empty data is field-validated at the route.
+export const PublicCreateContentRequestSchema = z.object({
+    documentTypeId: z.string().uuid(),
+    parentId: z.string().uuid().nullable(),
+    slug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+    locale: z.string().min(2).default("en"),
+    isDefaultLocale: z.boolean().default(true),
+    translationGroupId: z.string().uuid().optional(),
+    data: z.record(z.string(), z.unknown()).default({}),
+});
+// Body for both PUT (full-replace) and PATCH (partial merge) — the verb,
+// not the body shape, decides the merge semantics. See the route
+// descriptions.
+export const PublicUpdateContentRequestSchema = z.object({
+    data: z.record(z.string(), z.unknown()),
+});

package/dist/setup-api.schema.d.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+export declare const BundledTemplateSchema: z.ZodObject<{
+    pluginId: z.ZodString;
+    version: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    sampleContent: z.ZodBoolean;
+}, z.core.$strip>;
+export type BundledTemplate = z.infer<typeof BundledTemplateSchema>;
+export declare const SetupStatusResponseSchema: z.ZodObject<{
+    setupRequired: z.ZodBoolean;
+    bundledTemplates: z.ZodArray<z.ZodObject<{
+        pluginId: z.ZodString;
+        version: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        sampleContent: z.ZodBoolean;
+    }, z.core.$strip>>;
+    databaseConfigured: z.ZodBoolean;
+}, z.core.$strip>;
+export type SetupStatusResponse = z.infer<typeof SetupStatusResponseSchema>;
+export declare const SetupStarterSelectionSchema: z.ZodObject<{
+    pluginId: z.ZodString;
+    includeSampleContent: z.ZodBoolean;
+}, z.core.$strip>;
+export type SetupStarterSelection = z.infer<typeof SetupStarterSelectionSchema>;
+export declare const SetupCompleteRequestSchema: z.ZodObject<{
+    admin: z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodString;
+        password: z.ZodString;
+    }, z.core.$strip>;
+    database: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        dialect: z.ZodLiteral<"sqlite">;
+        filePath: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodCoercedNumber<unknown>;
+        database: z.ZodString;
+        username: z.ZodString;
+        password: z.ZodString;
+        dialect: z.ZodLiteral<"postgresql">;
+    }, z.core.$strip>, z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodCoercedNumber<unknown>;
+        database: z.ZodString;
+        username: z.ZodString;
+        password: z.ZodString;
+        dialect: z.ZodLiteral<"mysql">;
+    }, z.core.$strip>], "dialect">>;
+    starter: z.ZodOptional<z.ZodObject<{
+        pluginId: z.ZodString;
+        includeSampleContent: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SetupCompleteRequest = z.infer<typeof SetupCompleteRequestSchema>;
+export declare const SetupStarterResultSchema: z.ZodObject<{
+    pluginId: z.ZodString;
+    outcome: z.ZodEnum<{
+        installed: "installed";
+        failed: "failed";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SetupStarterResult = z.infer<typeof SetupStarterResultSchema>;
+export declare const SetupCompleteResponseSchema: z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    starter: z.ZodOptional<z.ZodObject<{
+        pluginId: z.ZodString;
+        outcome: z.ZodEnum<{
+            installed: "installed";
+            failed: "failed";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    configWarning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SetupCompleteResponse = z.infer<typeof SetupCompleteResponseSchema>;

package/dist/setup-api.schema.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+// One bundled first-party starter template (currently only the blog
+// template — apps/server/src/setup/bundled-templates.ts) offered from the
+// setup wizard's optional "starter template" step. `pluginId` matches the
+// template plugin's manifest id (e.g. "com.velora.blog") — the same id the
+// marketplace install flow uses elsewhere, so a template picked here and a
+// template found later in the marketplace are addressed identically.
+// `sampleContent` reports whether the packed artifact carries a
+// sample-content.json seed tree, not the content itself.
+export const BundledTemplateSchema = z.object({
+    pluginId: z.string().min(1),
+    version: z.string().min(1),
+    name: z.string().min(1),
+    description: z.string().min(1).optional(),
+    sampleContent: z.boolean(),
+});
+export const SetupStatusResponseSchema = z.object({
+    setupRequired: z.boolean(),
+    // Always present — [] outside setup mode (a fully-configured instance has
+    // nothing left to offer here) and whenever nothing bundled is resolvable,
+    // never omitted or null.
+    bundledTemplates: z.array(BundledTemplateSchema),
+    // True when DATABASE_URL was already set at boot, so the wizard is
+    // running in its admin-only mode and must not render a database step.
+    // See the BootMode type and resolveBootMode function in
+    // apps/server/src/boot/resolve-boot-mode.ts for the three states.
+    databaseConfigured: z.boolean(),
+});
+const SqliteSelectionSchema = z.object({
+    dialect: z.literal("sqlite"),
+    filePath: z.string().min(1),
+});
+const ServerDialectSelectionSchema = z.object({
+    dialect: z.enum(["postgresql", "mysql"]),
+    host: z.string().min(1),
+    port: z.coerce.number().int().positive(),
+    database: z.string().min(1),
+    username: z.string().min(1),
+    password: z.string(),
+});
+// The wizard's optional starter step (Session 151): which bundled template
+// to install during setup completion, and whether its sample-content.json
+// tree should be seeded. Absent entirely = skip — never null.
+export const SetupStarterSelectionSchema = z.object({
+    pluginId: z.string().min(1),
+    includeSampleContent: z.boolean(),
+});
+export const SetupCompleteRequestSchema = z.object({
+    admin: z.object({
+        email: z.string().email(),
+        name: z.string().min(1),
+        password: z.string().min(8),
+    }),
+    // Optional because the wizard has two shapes. On a fresh instance it
+    // collects a database selection; when DATABASE_URL was already injected
+    // the database is configured and read-only, and the request carries the
+    // admin only. The ROUTE enforces the pairing in both directions —
+    // routes/setup.ts — because "optional" alone would let a caller silently
+    // send a selection that is ignored.
+    database: z
+        .discriminatedUnion("dialect", [
+        SqliteSelectionSchema,
+        ServerDialectSelectionSchema.extend({ dialect: z.literal("postgresql") }),
+        ServerDialectSelectionSchema.extend({ dialect: z.literal("mysql") }),
+    ])
+        .optional(),
+    starter: SetupStarterSelectionSchema.optional(),
+});
+// What happened to the requested starter. "failed" never fails setup
+// itself — the admin account and database config always stand — so this
+// rides alongside success: true rather than replacing it. `reason` is only
+// present on failure.
+export const SetupStarterResultSchema = z.object({
+    pluginId: z.string().min(1),
+    outcome: z.enum(["installed", "failed"]),
+    reason: z.string().min(1).optional(),
+});
+export const SetupCompleteResponseSchema = z.object({
+    success: z.literal(true),
+    // ABSENT (not null) when no starter was requested — the skip-path
+    // response stays byte-identical to the pre-starter shape.
+    starter: SetupStarterResultSchema.optional(),
+    // ABSENT unless setup completed but could not write its configuration
+    // to disk. Setup itself still succeeded — the admin account and the
+    // provisioned database stand — so this rides alongside success: true
+    // rather than replacing it, exactly as `starter` does.
+    configWarning: z.string().min(1).optional(),
+});

package/dist/snapshot-api.schema.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+export declare const CreateSnapshotRequestSchema: z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CreateSnapshotRequest = z.infer<typeof CreateSnapshotRequestSchema>;
+export declare const SnapshotResponseSchema: z.ZodObject<{
+    snapshot: z.ZodObject<{
+        id: z.ZodString;
+        createdAt: z.ZodString;
+        createdBy: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type SnapshotResponse = z.infer<typeof SnapshotResponseSchema>;
+export declare const SnapshotListQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type SnapshotListQuery = z.infer<typeof SnapshotListQuerySchema>;
+export declare const SnapshotListResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        createdAt: z.ZodString;
+        createdBy: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type SnapshotListResponse = z.infer<typeof SnapshotListResponseSchema>;
+export declare const RestoreSnapshotResponseSchema: z.ZodObject<{
+    snapshot: z.ZodObject<{
+        id: z.ZodString;
+        createdAt: z.ZodString;
+        createdBy: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    restoredItems: z.ZodNumber;
+}, z.core.$strip>;
+export type RestoreSnapshotResponse = z.infer<typeof RestoreSnapshotResponseSchema>;

package/dist/snapshot-api.schema.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { SnapshotMetaSchema } from "./snapshot.schema.js";
+// createdBy comes from the JWT, never the body (same rule as content).
+export const CreateSnapshotRequestSchema = z.object({
+    label: z.string().min(1),
+    description: z.string().min(1).optional(),
+});
+export const SnapshotResponseSchema = z.object({
+    snapshot: SnapshotMetaSchema,
+});
+// Newest-first; cursor = id of the previous page's last snapshot.
+export const SnapshotListQuerySchema = z.object({
+    cursor: z.string().uuid().optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+export const SnapshotListResponseSchema = z.object({
+    items: z.array(SnapshotMetaSchema),
+    // null = no more pages.
+    nextCursor: z.string().uuid().nullable(),
+});
+export const RestoreSnapshotResponseSchema = z.object({
+    snapshot: SnapshotMetaSchema,
+    // How many content nodes had their pointers repointed.
+    restoredItems: z.number().int().nonnegative(),
+});

package/dist/snapshot.schema.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export declare const SnapshotItemSchema: z.ZodObject<{
+    contentId: z.ZodString;
+    version: z.ZodNumber;
+    publishedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const SnapshotSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    createdBy: z.ZodString;
+    items: z.ZodArray<z.ZodObject<{
+        contentId: z.ZodString;
+        version: z.ZodNumber;
+        publishedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SnapshotItem = z.infer<typeof SnapshotItemSchema>;
+export type Snapshot = z.infer<typeof SnapshotSchema>;
+export declare const SnapshotMetaSchema: z.ZodObject<{
+    id: z.ZodString;
+    createdAt: z.ZodString;
+    createdBy: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type SnapshotMeta = z.infer<typeof SnapshotMetaSchema>;

package/dist/snapshot.schema.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+export const SnapshotItemSchema = z.object({
+    contentId: z.string().uuid(),
+    version: z.number().int().positive(),
+    publishedAt: z.string().datetime().nullable(),
+});
+export const SnapshotSchema = z.object({
+    id: z.string().uuid(),
+    label: z.string().min(1),
+    description: z.string().nullable(),
+    createdAt: z.string().datetime(),
+    createdBy: z.string().uuid(),
+    items: z.array(SnapshotItemSchema),
+});
+// Timeline listings — items excluded on purpose: a snapshot's items array
+// scales with tree size and the timeline only needs the row facts.
+export const SnapshotMetaSchema = SnapshotSchema.omit({ items: true });