@conradsix/c4m-schema 0.0.0-stage → 0.1.0-preview.1

package/dist/syncSchemas.d.ts

@@ -0,0 +1,28 @@
+import type { CmsSchemaDescriptor } from "./descriptor.js";
+type RegisteredSchema = {
+    readonly name: string;
+    readonly version: number;
+    readonly jsonSchema: string;
+};
+type SchemaRegistry = {
+    list(): Promise<readonly RegisteredSchema[]>;
+    create(schema: RegisteredSchema): Promise<void>;
+};
+type SyncResult = {
+    readonly created: Array<{
+        name: string;
+        version: number;
+    }>;
+    readonly validated: Array<{
+        name: string;
+        version: number;
+    }>;
+    readonly errors: Array<{
+        type: "mismatch" | "orphaned" | "creation";
+        details: string;
+    }>;
+};
+declare const syncSchemas: (descriptors: readonly CmsSchemaDescriptor[], registry: SchemaRegistry) => Promise<SyncResult>;
+export { syncSchemas };
+export type { RegisteredSchema, SchemaRegistry, SyncResult };
+//# sourceMappingURL=syncSchemas.d.ts.map

package/dist/syncSchemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncSchemas.d.ts","sourceRoot":"","sources":["../src/syncSchemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAM3D,KAAK,gBAAgB,GAAG;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CAAC;AAGF,KAAK,cAAc,GAAG;IACpB,IAAI,IAAI,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAAC;IAC7C,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD,CAAC;AAEF,KAAK,UAAU,GAAG;IAChB,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3D,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzF,CAAC;AAOF,QAAA,MAAM,WAAW,gBACF,SAAS,mBAAmB,EAAE,YACjC,cAAc,KACvB,OAAO,CAAC,UAAU,CAgDpB,CAAC;AAEF,OAAO,EAAE,WAAW,EAAE,CAAC;AACvB,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC"}

package/dist/syncSchemas.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { isJsonEqual } from "./isJsonEqual.js";
+const keyOf = (schema) => `${schema.name}:${schema.version}`;
+// Registers the schemas the registry lacks and checks the rest are unchanged. A registered schema never changes, so
+// a different one, or one the host no longer has, fails the sync.
+const syncSchemas = async (descriptors, registry) => {
+    if (descriptors.length === 0)
+        throw new Error("No local schemas to sync");
+    const local = new Map(descriptors.map((descriptor) => [
+        keyOf(descriptor),
+        { ...descriptor, jsonSchema: JSON.stringify(z.toJSONSchema(descriptor.schema)) },
+    ]));
+    const registered = new Map((await registry.list()).map((schema) => [keyOf(schema), schema]));
+    const result = { created: [], validated: [], errors: [] };
+    for (const [key, schema] of registered)
+        if (!local.has(key))
+            result.errors.push({
+                type: "orphaned",
+                details: `The CMS has '${schema.name}' version ${schema.version}, which doesn't exist locally`,
+            });
+    for (const [key, schema] of local) {
+        const existing = registered.get(key);
+        const entry = { name: schema.name, version: schema.version };
+        if (existing) {
+            if (isJsonEqual(schema.jsonSchema, existing.jsonSchema))
+                result.validated.push(entry);
+            else
+                result.errors.push({
+                    type: "mismatch",
+                    details: `Schema mismatch for '${schema.name}' version ${schema.version}: local and CMS schemas differ`,
+                });
+            continue;
+        }
+        try {
+            await registry.create({ ...entry, jsonSchema: schema.jsonSchema });
+            result.created.push(entry);
+        }
+        catch (error) {
+            result.errors.push({
+                type: "creation",
+                details: `Failed to create '${schema.name}' version ${schema.version}: ${String(error)}`,
+            });
+        }
+    }
+    if (result.errors.length > 0)
+        throw new Error(`Schema sync failed:\n${result.errors.map((error) => `${error.type.toUpperCase()}: ${error.details}`).join("\n")}`);
+    return result;
+};
+export { syncSchemas };
+//# sourceMappingURL=syncSchemas.js.map

package/dist/syncSchemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncSchemas.js","sourceRoot":"","sources":["../src/syncSchemas.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@conradsix/c4m-schema",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-preview.1",
+  "description": "Versioned block and menu action schemas for C4M, defined with zod, and their sync with the engine.",
+  "keywords": [
+    "c4m",
+    "cms",
+    "zod",
+    "json-schema"
+  ],
+  "license": "MIT",
+  "author": "Brian Tyler",
+  "homepage": "https://github.com/conradsix/c4m#readme",
+  "bugs": "https://github.com/conradsix/c4m/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/conradsix/c4m.git",
+    "directory": "typescript/packages/c4m-schema"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "check:types": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.5",
+    "typescript": "7.0.2",
+    "vite": "8.3.5",
+    "vitest": "5.0.5",
+    "zod": "4.6.7"
+  }
 }

package/src/defineBlock.ts

@@ -0,0 +1,153 @@
+import { z } from "zod";
+
+// A block version's schema. Its __typename and __version are literals, so stored data names the schema it was saved
+// with.
+type VersionedSchema = z.ZodObject;
+
+// Data at one version, as the next.
+type Upgrade<TFrom extends VersionedSchema, TTo extends VersionedSchema> = (
+  block: z.output<TFrom>,
+) => z.input<TTo>;
+
+type BlockDefinition<
+  TName extends string,
+  TSchemas extends readonly VersionedSchema[],
+  TLatest extends VersionedSchema,
+> = {
+  readonly name: TName;
+  // Every version, oldest first.
+  readonly schemas: TSchemas;
+  readonly latest: TLatest;
+  // Data stored at any version, as the latest: through the legacy upgrade, then each later version's step. Returns new
+  // data and leaves its input alone, even when the input is already the latest version.
+  upgrade(block: z.output<TSchemas[number]>): z.output<TLatest>;
+  // Adds the next version; its from takes the step that brings the current latest to it.
+  version<TNext extends VersionedSchema>(
+    schema: TNext,
+  ): NextVersion<TName, TSchemas, TLatest, TNext>;
+};
+
+type NextVersion<
+  TName extends string,
+  TSchemas extends readonly VersionedSchema[],
+  TLatest extends VersionedSchema,
+  TNext extends VersionedSchema,
+> = {
+  from(
+    upgrade: Upgrade<TLatest, TNext>,
+  ): BlockDefinition<TName, readonly [...TSchemas, TNext], TNext>;
+};
+
+type Legacy<TVersions extends readonly VersionedSchema[]> = {
+  // The versions from before the baseline, oldest first.
+  readonly versions: TVersions;
+  // Data stored at any of them, as the baseline. The catalogue sets the baseline's version but doesn't check the result
+  // against its schema: it is taken as it is.
+  readonly upgrade: (block: z.output<TVersions[number]>) => object;
+};
+
+type AnyUpgrade = (block: never) => unknown;
+
+type Chain = {
+  readonly name: string;
+  readonly schemas: readonly VersionedSchema[];
+  readonly baseline: number;
+  readonly legacy: ((block: never) => object) | undefined;
+  // steps[i] takes version baseline + i to the next.
+  readonly steps: readonly AnyUpgrade[];
+};
+
+const literalOf = (schema: VersionedSchema, key: "__typename" | "__version"): unknown => {
+  const field = (schema.shape as Readonly<Record<string, unknown>>)[key];
+  return field instanceof z.ZodLiteral && field.values.size === 1
+    ? [...field.values][0]
+    : undefined;
+};
+
+const versionOf = (name: string, schema: VersionedSchema): number => {
+  const version = literalOf(schema, "__version");
+  if (literalOf(schema, "__typename") !== name || typeof version !== "number")
+    throw new Error(
+      `Every ${name} schema needs the literals __typename "${name}" and a __version number`,
+    );
+  return version;
+};
+
+const itemAt = <T>(items: readonly T[], index: number, name: string): T => {
+  const item = items[index];
+  if (item === undefined) throw new Error(`${name} has no version ${index + 1}`);
+  return item;
+};
+
+const upgradeChain = (chain: Chain, block: { readonly __version: number }): unknown => {
+  const latest = chain.schemas.length;
+  let version = block.__version;
+  if (!Number.isInteger(version) || version < 1 || version > latest)
+    throw new Error(`${chain.name} has no version ${String(version)}`);
+  let data: unknown = block;
+  if (version < chain.baseline) {
+    if (!chain.legacy) throw new Error(`${chain.name} has no legacy upgrade`);
+    data = { ...chain.legacy(data as never), __version: chain.baseline };
+    version = chain.baseline;
+  }
+  for (; version < latest; version++) {
+    const step = itemAt(chain.steps, version - chain.baseline, chain.name);
+    data = itemAt(chain.schemas, version, chain.name).parse(step(data as never));
+  }
+  return data;
+};
+
+const build = (
+  chain: Chain,
+): BlockDefinition<string, readonly VersionedSchema[], VersionedSchema> => ({
+  name: chain.name,
+  schemas: chain.schemas,
+  latest: itemAt(chain.schemas, chain.schemas.length - 1, chain.name),
+  upgrade: (block) =>
+    upgradeChain(
+      chain,
+      structuredClone(block) as { readonly __version: number },
+    ) as z.output<VersionedSchema>,
+  version: <TNext extends VersionedSchema>(
+    schema: TNext,
+  ): NextVersion<string, readonly VersionedSchema[], VersionedSchema, TNext> => {
+    if (versionOf(chain.name, schema) !== chain.schemas.length + 1)
+      throw new Error(`The next ${chain.name} version is ${chain.schemas.length + 1}`);
+    return {
+      from: (upgrade) =>
+        build({
+          ...chain,
+          schemas: [...chain.schemas, schema],
+          steps: [...chain.steps, upgrade],
+        }) as BlockDefinition<string, readonly [...VersionedSchema[], TNext], TNext>,
+    };
+  },
+});
+
+// A block type and every version it has had. Versions from before the baseline upgrade to it through the legacy
+// upgrade; each version added after it brings its own step.
+const defineBlock = <
+  TName extends string,
+  TBaseline extends VersionedSchema,
+  const TLegacy extends readonly VersionedSchema[] = readonly [],
+>(
+  name: TName,
+  definition: { readonly baseline: TBaseline; readonly legacy?: Legacy<TLegacy> },
+): BlockDefinition<TName, readonly [...TLegacy, TBaseline], TBaseline> => {
+  const schemas = [...(definition.legacy?.versions ?? []), definition.baseline];
+  for (const [index, schema] of schemas.entries())
+    if (versionOf(name, schema) !== index + 1)
+      throw new Error(
+        `${name} versions must run from 1 without gaps; version ${index + 1} is missing`,
+      );
+  return build({
+    name,
+    schemas,
+    baseline: schemas.length,
+    legacy: definition.legacy?.upgrade,
+    steps: [],
+  }) as BlockDefinition<TName, readonly [...TLegacy, TBaseline], TBaseline>;
+};
+
+export { defineBlock, versionOf };
+export type { BlockDefinition, Upgrade, VersionedSchema };

package/src/defineCatalogue.ts

@@ -0,0 +1,118 @@
+import type { BlockDefinition, VersionedSchema } from "./defineBlock.js";
+import type { CmsSchemaDescriptor } from "./descriptor.js";
+
+import { z } from "zod";
+
+import { versionOf } from "./defineBlock.js";
+
+type AnyBlock = BlockDefinition<string, readonly VersionedSchema[], VersionedSchema>;
+
+type VersionOf<TSchema> = TSchema extends VersionedSchema
+  ? z.output<TSchema> extends { readonly __version: infer TVersion }
+    ? TVersion
+    : number
+  : never;
+
+type StoredSchemaOf<TBlocks extends readonly AnyBlock[]> = TBlocks[number]["schemas"][number];
+
+type LatestSchemas<TBlocks extends readonly AnyBlock[]> = {
+  -readonly [K in keyof TBlocks]: TBlocks[K]["latest"];
+};
+
+type DescriptorsOf<TBlock extends AnyBlock> = {
+  [K in keyof TBlock["schemas"]]: {
+    readonly name: TBlock["name"];
+    readonly version: VersionOf<TBlock["schemas"][K]>;
+    readonly schema: TBlock["schemas"][K];
+  };
+}[number];
+
+type CurrentDescriptors<TBlocks extends readonly AnyBlock[]> = {
+  readonly [K in keyof TBlocks]: {
+    readonly name: TBlocks[K]["name"];
+    readonly version: VersionOf<TBlocks[K]["latest"]>;
+    readonly schema: TBlocks[K]["latest"];
+  };
+};
+
+type StoredUnion<TBlocks extends readonly AnyBlock[]> = z.ZodUnion<StoredSchemaOf<TBlocks>[]>;
+
+type CurrentUnion<TBlocks extends readonly AnyBlock[]> = z.ZodUnion<LatestSchemas<TBlocks>>;
+
+type BlockCatalogue<TBlocks extends readonly AnyBlock[]> = {
+  readonly blocks: TBlocks;
+  // Every version of every block: what the CMS registers.
+  readonly descriptors: readonly DescriptorsOf<TBlocks[number]>[];
+  // Each block's latest version, in catalogue order.
+  readonly current: CurrentDescriptors<TBlocks>;
+  // Data stored at any version of any block.
+  readonly Stored: StoredUnion<TBlocks>;
+  // Any block at its latest version.
+  readonly Current: CurrentUnion<TBlocks>;
+  // Stored data, upgraded to its block's latest version.
+  readonly Block: z.ZodPipe<
+    StoredUnion<TBlocks>,
+    z.ZodTransform<z.output<CurrentUnion<TBlocks>>, z.output<StoredUnion<TBlocks>>>
+  >;
+  // Upgrades data that names its block and version. Throws for a block or version the catalogue doesn't have.
+  readonly upgrade: (block: {
+    readonly __typename: string;
+    readonly __version: number;
+  }) => z.output<CurrentUnion<TBlocks>>;
+};
+
+// The blocks a host stores. Each block's name may appear once.
+const defineCatalogue = <const TBlocks extends readonly AnyBlock[]>(
+  blocks: TBlocks,
+): BlockCatalogue<TBlocks> => {
+  const byName = new Map<string, AnyBlock>();
+  for (const block of blocks) {
+    if (byName.has(block.name)) throw new Error(`The catalogue has ${block.name} twice`);
+    byName.set(block.name, block);
+  }
+
+  const descriptors: CmsSchemaDescriptor[] = blocks.flatMap((block) =>
+    block.schemas.map((schema) => ({
+      name: block.name,
+      version: versionOf(block.name, schema),
+      schema,
+    })),
+  );
+  const current = blocks.map((block) => ({
+    name: block.name,
+    version: versionOf(block.name, block.latest),
+    schema: block.latest,
+  }));
+  const Stored = z.union(descriptors.map((descriptor) => descriptor.schema));
+  const Current = z.union(blocks.map((block) => block.latest));
+
+  const upgrade = (block: { readonly __typename: string; readonly __version: number }): unknown => {
+    const definition = byName.get(block.__typename);
+    if (!definition) throw new Error(`Unknown block ${block.__typename}`);
+    return definition.upgrade(block);
+  };
+
+  const Block = Stored.transform((block, ctx) => {
+    try {
+      return upgrade(block as { readonly __typename: string; readonly __version: number });
+    } catch (error) {
+      if (!(error instanceof z.ZodError)) throw error;
+      for (const issue of error.issues)
+        ctx.issues.push({ code: "custom", message: issue.message, path: issue.path, input: block });
+      return z.NEVER;
+    }
+  });
+
+  return {
+    blocks,
+    descriptors,
+    current,
+    Stored,
+    Current,
+    Block,
+    upgrade,
+  } as unknown as BlockCatalogue<TBlocks>;
+};
+
+export { defineCatalogue };
+export type { BlockCatalogue };

package/src/descriptor.ts

@@ -0,0 +1,10 @@
+import type { z } from "zod";
+
+// One version of a CMS type, as the CMS registers it and checks stored data against it.
+type CmsSchemaDescriptor = {
+  readonly name: string;
+  readonly version: number;
+  readonly schema: z.ZodObject;
+};
+
+export type { CmsSchemaDescriptor };

package/src/index.ts

@@ -0,0 +1,24 @@
+export { defineBlock } from "./defineBlock.js";
+export { defineCatalogue } from "./defineCatalogue.js";
+export {
+  extractMarkdownPageRefIds,
+  fromMarkdownPageRefHref,
+  toMarkdownPageRefHref,
+} from "./markdownPageRef.js";
+export {
+  defineMenuAction,
+  EmptyActionV1Schema,
+  ExternalLinkActionV1Schema,
+  PageLinkActionV1Schema,
+  standardMenuActions,
+} from "./menuActions.js";
+export { PageSeoInputSchema, PublishablePageSeoSchema } from "./pageSeo.js";
+export { ImageRefSchema, PageRefSchema, ResourceRefSchema } from "./references.js";
+export { syncSchemas } from "./syncSchemas.js";
+export type { BlockDefinition, Upgrade, VersionedSchema } from "./defineBlock.js";
+export type { BlockCatalogue } from "./defineCatalogue.js";
+export type { CmsSchemaDescriptor } from "./descriptor.js";
+export type { EmptyActionV1, ExternalLinkActionV1, PageLinkActionV1 } from "./menuActions.js";
+export type { PageSeoInput } from "./pageSeo.js";
+export type { ImageRef, PageRef, ResourceRef } from "./references.js";
+export type { RegisteredSchema, SchemaRegistry, SyncResult } from "./syncSchemas.js";

package/src/isJsonEqual.ts

@@ -0,0 +1,26 @@
+const sortKeys = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(sortKeys);
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.keys(value)
+      .sort()
+      .reduce<Record<string, unknown>>((acc, key) => {
+        acc[key] = sortKeys((value as Record<string, unknown>)[key]);
+        return acc;
+      }, {});
+  }
+  return value;
+};
+
+const isJsonEqual = (a: string, b: string): boolean => {
+  try {
+    const objA = sortKeys(JSON.parse(a));
+    const objB = sortKeys(JSON.parse(b));
+    return JSON.stringify(objA) === JSON.stringify(objB);
+  } catch {
+    return false;
+  }
+};
+
+export { isJsonEqual };

package/src/markdownPageRef.ts

@@ -0,0 +1,30 @@
+import { PageRefSchema } from "./references.js";
+
+const MARKDOWN_PAGE_REF_PREFIX = "page-ref:";
+
+const toMarkdownPageRefHref = (pageId: string): string => {
+  const result = PageRefSchema.shape.id.safeParse(pageId);
+  if (!result.success) throw new Error(`Invalid CMS page ID: ${pageId}`);
+  return `${MARKDOWN_PAGE_REF_PREFIX}${result.data}`;
+};
+
+const fromMarkdownPageRefHref = (href: string): string | undefined => {
+  if (!href.startsWith(MARKDOWN_PAGE_REF_PREFIX)) return undefined;
+  const result = PageRefSchema.shape.id.safeParse(href.slice(MARKDOWN_PAGE_REF_PREFIX.length));
+  return result.success ? result.data : undefined;
+};
+
+const extractMarkdownPageRefIds = (markdown: string): string[] => {
+  const ids = new Set<string>();
+
+  for (const match of markdown.matchAll(/page-ref:([0-9a-f-]{36})/giu)) {
+    const id = match[1];
+    if (!id) continue;
+    const result = PageRefSchema.shape.id.safeParse(id);
+    if (result.success) ids.add(result.data);
+  }
+
+  return [...ids];
+};
+
+export { extractMarkdownPageRefIds, fromMarkdownPageRefHref, toMarkdownPageRefHref };

package/src/menuActions.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+
+import { defineBlock } from "./defineBlock.js";
+
+// Menu action types version and upgrade as blocks do.
+const defineMenuAction = defineBlock;
+
+// A menu item that only opens its children. The engine requires it to have some.
+const EmptyActionV1Schema = z.object({
+  __typename: z.literal("empty"),
+  __version: z.literal(1),
+});
+
+const PageLinkActionV1Schema = z.object({
+  __typename: z.literal("page-link"),
+  __version: z.literal(1),
+  pageRef: z.object({
+    __typename: z.literal("page-ref"),
+    id: z.uuid(),
+  }),
+  openInNewTab: z.boolean().optional().default(false),
+});
+
+const ExternalLinkActionV1Schema = z.object({
+  __typename: z.literal("external-link"),
+  __version: z.literal(1),
+  url: z.url("Must be a valid URL"),
+  openInNewTab: z.boolean().optional().default(true),
+});
+
+// The menu actions every host has: a heading for children, a link to a page, and a link elsewhere.
+const standardMenuActions = [
+  defineMenuAction("empty", { baseline: EmptyActionV1Schema }),
+  defineMenuAction("page-link", { baseline: PageLinkActionV1Schema }),
+  defineMenuAction("external-link", { baseline: ExternalLinkActionV1Schema }),
+] as const;
+
+type EmptyActionV1 = z.infer<typeof EmptyActionV1Schema>;
+type PageLinkActionV1 = z.infer<typeof PageLinkActionV1Schema>;
+type ExternalLinkActionV1 = z.infer<typeof ExternalLinkActionV1Schema>;
+
+export {
+  defineMenuAction,
+  EmptyActionV1Schema,
+  ExternalLinkActionV1Schema,
+  PageLinkActionV1Schema,
+  standardMenuActions,
+};
+
+export type { EmptyActionV1, ExternalLinkActionV1, PageLinkActionV1 };

package/src/pageSeo.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+const PageSeoInputSchema = z.object({
+  title: z.string().trim().max(60, "Use 60 characters or fewer"),
+  description: z.string().trim().max(160, "Use 160 characters or fewer"),
+  socialImageId: z.uuid().nullable(),
+  index: z.boolean(),
+  follow: z.boolean(),
+});
+
+const PublishablePageSeoSchema = PageSeoInputSchema.extend({
+  title: z.string().trim().min(1, "Enter an SEO title").max(60, "Use 60 characters or fewer"),
+  description: z
+    .string()
+    .trim()
+    .min(1, "Enter an SEO description")
+    .max(160, "Use 160 characters or fewer"),
+});
+
+type PageSeoInput = z.infer<typeof PageSeoInputSchema>;
+
+export { PageSeoInputSchema, PublishablePageSeoSchema };
+export type { PageSeoInput };

package/src/references.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+const ImageRefSchema = z.object({
+  __typename: z.literal("image-ref"),
+  id: z.uuid(),
+});
+
+const PageRefSchema = z.object({
+  __typename: z.literal("page-ref"),
+  id: z.uuid(),
+});
+
+const ResourceRefSchema = z.union([ImageRefSchema, PageRefSchema]);
+
+type ImageRef = z.infer<typeof ImageRefSchema>;
+type PageRef = z.infer<typeof PageRefSchema>;
+type ResourceRef = z.infer<typeof ResourceRefSchema>;
+
+export { ImageRefSchema, PageRefSchema, ResourceRefSchema };
+
+export type { ImageRef, PageRef, ResourceRef };