@betttercms/codegen 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @betttercms/codegen
+
+Generate TypeScript types from your BetterCMS content schema.
+
+Your models are defined once — in the dashboard schema builder **or** by your AI through
+the MCP tools. Both write the same underlying field schema, so the types this generates can
+never drift from what your editors and agents actually create. This is the **deterministic
+floor** under the AI integration: even if an agent mis-wires something, you still have exact,
+committed types to fall back on.
+
+## Use it
+
+```bash
+# In your site repo (key from the dashboard → Settings → API Keys, content:manage scope)
+BETTERCMS_API_KEY=bcms_xxx npx @betttercms/codegen --out src/bettercms.generated.ts
+```
+
+```
+✓ Generated 2 model types → src/bettercms.generated.ts
+```
+
+Commit the generated file and re-run codegen after any schema change (a CI step or the
+BetterCMS GitHub Action does this for you on every build).
+
+### Options
+
+| Flag | Env | Default |
+|------|-----|---------|
+| `--out, -o` | — | `bettercms.generated.ts` |
+| `--api-url` | `BETTERCMS_API_URL` | `https://api.bettercms.ai/api/v1` |
+| `--key` | `BETTERCMS_API_KEY` | — |
+
+## What it emits
+
+For a `blog` model with `title` (text, required), `body` (richtext), `hero` (group):
+
+```ts
+export interface BlogFields {
+  readonly title: string;
+  readonly body?: RichText;
+  readonly hero?: {
+    readonly heading: string;
+  };
+}
+
+export interface BetterCMSSchema {
+  readonly "blog": BlogFields;
+}
+export type BetterCMSModelSlug = keyof BetterCMSSchema;
+```
+
+The `BetterCMSSchema` registry lets the Next.js adapter type `getEntry("blog", …)` by slug.
+
+## Field type → TypeScript
+
+| Field | TS |
+|-------|-----|
+| text · date · datetime | `string` |
+| richtext | `RichText` |
+| image | `BetterCMSImage` |
+| boolean / number | `boolean` / `number` |
+| select | `"a" \| "b"` (or `string`) |
+| reference / multi-reference | `string` / `string[]` (entry ids) |
+| array | `string[]` / `number[]` |
+| group | `{ …nested }` |
+| repeater | `Array<{ …nested }>` |
+
+## Library API
+
+```ts
+import { generateTypes, fetchModels } from "@betttercms/codegen";
+
+const models = await fetchModels({ apiUrl, apiKey });
+const source = generateTypes(models); // pure, deterministic
+```
+
+`generateTypes` is pure and deterministic — same models in, byte-identical output out.

package/dist/cli.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { writeFile, mkdir } from "fs/promises";
+import { dirname, resolve } from "path";
+
+// src/fetch-models.ts
+async function fetchModels(opts) {
+  const doFetch = opts.fetchImpl ?? globalThis.fetch;
+  const base = opts.apiUrl.replace(/\/+$/, "");
+  const url = `${base}/management/content/models`;
+  let res;
+  try {
+    res = await doFetch(url, {
+      // No Content-Type: this is a bodyless GET; the header is incorrect here and
+      // strict edge runtimes/proxies may reject it.
+      headers: { Authorization: `Bearer ${opts.apiKey}`, Accept: "application/json" }
+    });
+  } catch (err) {
+    throw new Error(
+      `Could not reach the BetterCMS Management API at ${url}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (!res.ok) {
+    const hint = res.status === 401 || res.status === 403 ? " \u2014 check your management API key (it must have the content:manage scope)." : "";
+    throw new Error(`Management API returned ${res.status} ${res.statusText}${hint}`);
+  }
+  const body = await res.json();
+  const rows = body.data ?? [];
+  return rows.map((r) => ({
+    slug: r.slug,
+    name: r.name,
+    description: r.description ?? null,
+    fields: r.fields ?? []
+  }));
+}
+
+// src/generate.ts
+var PREAMBLE = `/**
+ * Rich-text field value \u2014 the serialized portable rich-text payload returned by the
+ * Delivery API. Treated as opaque; render it with your editor's serializer.
+ */
+export type RichText = { readonly format: string; readonly value: unknown };
+
+/** Image / media field value as resolved by the Delivery API. */
+export interface BetterCMSImage {
+  readonly url: string;
+  readonly alt?: string;
+  readonly width?: number;
+  readonly height?: number;
+}
+
+/**
+ * Delivery envelope around a model's typed \`data\`. \`getEntry\`/\`listEntries\` in the
+ * Next adapter return this shape, with \`fields\` typed by the model.
+ */
+export interface BetterCMSEntry<TFields> {
+  readonly slug: string;
+  readonly status: "draft" | "published";
+  readonly fields: TFields;
+  readonly updatedAt: string;
+}
+`;
+function pascalCase(slug) {
+  const parts = slug.split(/[-_\s]+/).filter(Boolean);
+  const pascal = parts.map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+  return /^[0-9]/.test(pascal) ? `Model${pascal}` : pascal || "Model";
+}
+function escapeJsDoc(text) {
+  return text.replace(/\*\//g, "* /").replace(/[\r\n]+/g, " ").trim();
+}
+var VALID_IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function propName(key) {
+  return VALID_IDENT.test(key) ? key : JSON.stringify(key);
+}
+function scalarType(field) {
+  const t = field.type;
+  switch (t) {
+    case "text":
+      return "string";
+    case "richtext":
+      return "RichText";
+    case "image":
+      return "BetterCMSImage";
+    case "boolean":
+      return "boolean";
+    case "number":
+      return "number";
+    case "date":
+    case "datetime":
+      return "string";
+    // ISO 8601
+    case "select": {
+      const opts = field.options?.filter((o) => typeof o === "string") ?? [];
+      return opts.length > 0 ? opts.map((o) => JSON.stringify(o)).join(" | ") : "string";
+    }
+    case "reference":
+      return "string";
+    // referenced entry id
+    case "multi-reference":
+      return "string[]";
+    // referenced entry ids
+    case "array": {
+      const itemType = field.config?.itemType ?? "text";
+      const inner = itemType === "number" ? "number" : "string";
+      return `${inner}[]`;
+    }
+    case "group":
+    case "repeater":
+      return "unknown";
+    default: {
+      const _exhaustive = t;
+      return "unknown";
+    }
+  }
+}
+function fieldsToBody(fields, indent) {
+  const lines = [];
+  for (const field of fields) {
+    const optional = field.required ? "" : "?";
+    let typeExpr;
+    if (field.type === "group") {
+      const nested = fieldsToBody(field.fields ?? [], indent + "  ");
+      typeExpr = `{
+${nested}
+${indent}}`;
+    } else if (field.type === "repeater") {
+      const nested = fieldsToBody(field.fields ?? [], indent + "  ");
+      typeExpr = `Array<{
+${nested}
+${indent}}>`;
+    } else {
+      typeExpr = scalarType(field);
+    }
+    const safeLabel = field.label ? escapeJsDoc(field.label) : "";
+    if (safeLabel && safeLabel !== field.key) {
+      lines.push(`${indent}/** ${safeLabel} */`);
+    }
+    lines.push(`${indent}readonly ${propName(field.key)}${optional}: ${typeExpr};`);
+  }
+  return lines.join("\n");
+}
+function generateTypes(models, opts = {}) {
+  const version = opts.version ?? "0.1.0";
+  const sorted = [...models].sort(
+    (a, b) => a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0
+  );
+  const header = `// \u26A0\uFE0F  AUTO-GENERATED by @betttercms/codegen v${version} \u2014 DO NOT EDIT.
+// Regenerate with: npx @betttercms/codegen
+// Source of truth: your BetterCMS content models (the same schema the dashboard
+// builder and the MCP tools write). Re-run codegen after any schema change.
+${opts.bannerComment ? `// ${opts.bannerComment}
+` : ""}`;
+  const interfaces = [];
+  const mapEntries = [];
+  const usedNames = /* @__PURE__ */ new Set();
+  for (const model of sorted) {
+    const base = `${pascalCase(model.slug)}Fields`;
+    let typeName = base;
+    for (let n = 2; usedNames.has(typeName); n++) typeName = `${base}_${n}`;
+    usedNames.add(typeName);
+    const name = model.name ? escapeJsDoc(model.name) : "";
+    const desc = model.description ? escapeJsDoc(model.description) : "";
+    const doc = name ? `/**
+ * ${name}${desc ? ` \u2014 ${desc}` : ""}
+ * Model slug: \`${model.slug}\`
+ */
+` : "";
+    const body = model.fields.length ? fieldsToBody(model.fields, "  ") : "  // (no fields defined yet)";
+    interfaces.push(`${doc}export interface ${typeName} {
+${body}
+}`);
+    mapEntries.push(`  readonly ${JSON.stringify(model.slug)}: ${typeName};`);
+  }
+  const schemaMap = `/**
+ * Registry mapping each model slug to its typed fields. The Next adapter uses this to
+ * type \`getEntry("blog", ...)\` by slug \u2014 autocomplete and exhaustiveness for free.
+ */
+export interface BetterCMSSchema {
+${mapEntries.join("\n") || "  // (no models defined yet)"}
+}
+
+/** Union of all model slugs. */
+export type BetterCMSModelSlug = keyof BetterCMSSchema;`;
+  return [header, PREAMBLE, interfaces.join("\n\n"), schemaMap, ""].join("\n");
+}
+
+// src/cli.ts
+var VERSION = "0.1.0";
+var DEFAULT_API_URL = "https://api.bettercms.ai/api/v1";
+var DEFAULT_OUT = "bettercms.generated.ts";
+function parseArgs(argv) {
+  const args = {
+    apiUrl: process.env.BETTERCMS_API_URL ?? DEFAULT_API_URL,
+    apiKey: process.env.BETTERCMS_API_KEY,
+    out: DEFAULT_OUT,
+    help: false
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = () => argv[++i];
+    switch (arg) {
+      case "--api-url":
+        args.apiUrl = next() ?? args.apiUrl;
+        break;
+      case "--key":
+      case "--api-key":
+        args.apiKey = next();
+        break;
+      case "--out":
+      case "-o":
+        args.out = next() ?? args.out;
+        break;
+      case "--help":
+      case "-h":
+        args.help = true;
+        break;
+    }
+  }
+  return args;
+}
+var HELP = `bettercms-codegen v${VERSION} \u2014 generate TypeScript types from your BetterCMS schema
+
+Usage:
+  npx @betttercms/codegen [options]
+
+Options:
+  -o, --out <path>      Output file (default: ${DEFAULT_OUT})
+      --api-url <url>   Management API base (default: ${DEFAULT_API_URL})
+      --key <key>       Management API key (or set BETTERCMS_API_KEY)
+  -h, --help            Show this help
+
+Env:
+  BETTERCMS_API_KEY     Management-scoped key (content:manage)
+  BETTERCMS_API_URL     Override the API base
+`;
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (!args.apiKey) {
+    process.stderr.write(
+      "error: no API key. Pass --key <key> or set BETTERCMS_API_KEY.\n"
+    );
+    process.exit(1);
+  }
+  const models = await fetchModels({ apiUrl: args.apiUrl, apiKey: args.apiKey });
+  const source = generateTypes(models, { version: VERSION });
+  const outPath = resolve(process.cwd(), args.out);
+  await mkdir(dirname(outPath), { recursive: true });
+  await writeFile(outPath, source, "utf8");
+  process.stdout.write(
+    `\u2713 Generated ${models.length} model type${models.length === 1 ? "" : "s"} \u2192 ${args.out}
+`
+  );
+}
+main().catch((err) => {
+  process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts","../src/fetch-models.ts","../src/generate.ts"],"sourcesContent":["/**\n * `bettercms-codegen` — fetch a project's content models and write a typed `.ts` file.\n *\n * Designed for two call sites:\n *   1. A developer in their repo:  npx @betttercms/codegen --out src/bettercms.generated.ts\n *   2. The build-time GitHub Action: same command, key from a repo secret.\n *\n * Auth + endpoint come from flags or env (BETTERCMS_API_KEY, BETTERCMS_API_URL).\n */\n\nimport { writeFile, mkdir } from \"node:fs/promises\";\nimport { dirname, resolve } from \"node:path\";\nimport { fetchModels } from \"./fetch-models.js\";\nimport { generateTypes } from \"./generate.js\";\n\nconst VERSION = \"0.1.0\";\nconst DEFAULT_API_URL = \"https://api.bettercms.ai/api/v1\";\nconst DEFAULT_OUT = \"bettercms.generated.ts\";\n\ninterface CliArgs {\n  apiUrl: string;\n  apiKey: string | undefined;\n  out: string;\n  help: boolean;\n}\n\nfunction parseArgs(argv: string[]): CliArgs {\n  const args: CliArgs = {\n    apiUrl: process.env.BETTERCMS_API_URL ?? DEFAULT_API_URL,\n    apiKey: process.env.BETTERCMS_API_KEY,\n    out: DEFAULT_OUT,\n    help: false,\n  };\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i];\n    const next = () => argv[++i];\n    switch (arg) {\n      case \"--api-url\":\n        args.apiUrl = next() ?? args.apiUrl;\n        break;\n      case \"--key\":\n      case \"--api-key\":\n        args.apiKey = next();\n        break;\n      case \"--out\":\n      case \"-o\":\n        args.out = next() ?? args.out;\n        break;\n      case \"--help\":\n      case \"-h\":\n        args.help = true;\n        break;\n    }\n  }\n  return args;\n}\n\nconst HELP = `bettercms-codegen v${VERSION} — generate TypeScript types from your BetterCMS schema\n\nUsage:\n  npx @betttercms/codegen [options]\n\nOptions:\n  -o, --out <path>      Output file (default: ${DEFAULT_OUT})\n      --api-url <url>   Management API base (default: ${DEFAULT_API_URL})\n      --key <key>       Management API key (or set BETTERCMS_API_KEY)\n  -h, --help            Show this help\n\nEnv:\n  BETTERCMS_API_KEY     Management-scoped key (content:manage)\n  BETTERCMS_API_URL     Override the API base\n`;\n\nasync function main(): Promise<void> {\n  const args = parseArgs(process.argv.slice(2));\n\n  if (args.help) {\n    process.stdout.write(HELP);\n    return;\n  }\n  if (!args.apiKey) {\n    process.stderr.write(\n      \"error: no API key. Pass --key <key> or set BETTERCMS_API_KEY.\\n\",\n    );\n    process.exit(1);\n  }\n\n  const models = await fetchModels({ apiUrl: args.apiUrl, apiKey: args.apiKey });\n  const source = generateTypes(models, { version: VERSION });\n\n  const outPath = resolve(process.cwd(), args.out);\n  await mkdir(dirname(outPath), { recursive: true });\n  await writeFile(outPath, source, \"utf8\");\n\n  process.stdout.write(\n    `✓ Generated ${models.length} model type${models.length === 1 ? \"\" : \"s\"} → ${args.out}\\n`,\n  );\n}\n\nmain().catch((err: unknown) => {\n  process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\\n`);\n  process.exit(1);\n});\n","/**\n * Fetches content models from the BetterCMS Management API so the CLI can generate\n * types against a live project. Kept dependency-free (plain fetch) so the generated\n * artifact and this fetcher can run anywhere — a GitHub Action, a postinstall, a script.\n */\n\nimport type { GeneratableModel } from \"./generate.js\";\n\nexport interface FetchModelsOptions {\n  /** Management API base, e.g. \"https://api.bettercms.ai/api/v1\". */\n  apiUrl: string;\n  /** A management-scoped key (content:manage) or device-minted token. */\n  apiKey: string;\n  /** Optional fetch override (testing / custom runtime). */\n  fetchImpl?: typeof fetch;\n}\n\ninterface ManagedModelRow {\n  slug: string;\n  name?: string;\n  description?: string | null;\n  fields: GeneratableModel[\"fields\"];\n}\n\n/**\n * GET /management/content/models — returns the project's models (the key is\n * project-scoped server-side, so this is exactly the schema for this site).\n */\nexport async function fetchModels(\n  opts: FetchModelsOptions,\n): Promise<GeneratableModel[]> {\n  const doFetch = opts.fetchImpl ?? globalThis.fetch;\n  const base = opts.apiUrl.replace(/\\/+$/, \"\");\n  const url = `${base}/management/content/models`;\n\n  let res: Response;\n  try {\n    res = await doFetch(url, {\n      // No Content-Type: this is a bodyless GET; the header is incorrect here and\n      // strict edge runtimes/proxies may reject it.\n      headers: { Authorization: `Bearer ${opts.apiKey}`, Accept: \"application/json\" },\n    });\n  } catch (err) {\n    throw new Error(\n      `Could not reach the BetterCMS Management API at ${url}: ${\n        err instanceof Error ? err.message : String(err)\n      }`,\n    );\n  }\n\n  if (!res.ok) {\n    const hint =\n      res.status === 401 || res.status === 403\n        ? \" — check your management API key (it must have the content:manage scope).\"\n        : \"\";\n    throw new Error(`Management API returned ${res.status} ${res.statusText}${hint}`);\n  }\n\n  const body = (await res.json()) as { data?: ManagedModelRow[] };\n  const rows = body.data ?? [];\n  return rows.map((r) => ({\n    slug: r.slug,\n    name: r.name,\n    description: r.description ?? null,\n    fields: r.fields ?? [],\n  }));\n}\n","/**\n * @betttercms/codegen — schema → TypeScript generator (the single source of truth).\n *\n * Both the dashboard schema builder and the MCP `create_model`/`add_field` tools write\n * the SAME `content_models.fields` (an array of `ContentModelField`). This generator maps\n * that one array into TypeScript. Because there is exactly one schema representation, the\n * generated types can never drift from the editor or the agent — they are the same source.\n *\n * Pure + deterministic: same models in → identical string out (stable ordering, no clock,\n * no I/O). That makes it trivially testable and safe to commit + diff in a customer repo.\n */\n\nimport type { ContentModelField, ContentModelFieldType } from \"@betttercms/types\";\n\n/** Minimal model shape the generator needs — a subset of the Management API model row. */\nexport interface GeneratableModel {\n  /** Machine-safe slug, e.g. \"blog\" or \"case-study\". Used for the schema-map key. */\n  slug: string;\n  /** Human name, used only for the JSDoc header. */\n  name?: string;\n  description?: string | null;\n  fields: ContentModelField[];\n}\n\nexport interface GenerateOptions {\n  /** Generator version stamped into the header (defaults to the package version). */\n  version?: string;\n  /** Override the banner timestamp source — omitted by default so output is deterministic. */\n  bannerComment?: string;\n}\n\n/** Helper types emitted once at the top of every generated file (self-contained, zero-dep). */\nconst PREAMBLE = `/**\n * Rich-text field value — the serialized portable rich-text payload returned by the\n * Delivery API. Treated as opaque; render it with your editor's serializer.\n */\nexport type RichText = { readonly format: string; readonly value: unknown };\n\n/** Image / media field value as resolved by the Delivery API. */\nexport interface BetterCMSImage {\n  readonly url: string;\n  readonly alt?: string;\n  readonly width?: number;\n  readonly height?: number;\n}\n\n/**\n * Delivery envelope around a model's typed \\`data\\`. \\`getEntry\\`/\\`listEntries\\` in the\n * Next adapter return this shape, with \\`fields\\` typed by the model.\n */\nexport interface BetterCMSEntry<TFields> {\n  readonly slug: string;\n  readonly status: \"draft\" | \"published\";\n  readonly fields: TFields;\n  readonly updatedAt: string;\n}\n`;\n\n/** PascalCase an identifier from a slug: \"case-study\" → \"CaseStudy\". */\nfunction pascalCase(slug: string): string {\n  const parts = slug.split(/[-_\\s]+/).filter(Boolean);\n  const pascal = parts\n    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))\n    .join(\"\");\n  // Guard against an identifier that starts with a digit (invalid TS type name).\n  return /^[0-9]/.test(pascal) ? `Model${pascal}` : pascal || \"Model\";\n}\n\n/**\n * Make a string safe to embed inside a `/** ... *​/` JSDoc comment. A field label\n * (free-text, author/agent-controlled) could contain `*​/` — which closes the comment\n * early and injects the remainder as code — or a newline, which breaks the single-line\n * comment. Both are neutralized here. Without this, hostile content produces non-\n * compiling (or worse, code-injected) output.\n */\nfunction escapeJsDoc(text: string): string {\n  return text.replace(/\\*\\//g, \"* /\").replace(/[\\r\\n]+/g, \" \").trim();\n}\n\nconst VALID_IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;\n\n/**\n * Render a field key as a TS property name. Field keys are author/agent-controlled and\n * not guaranteed to be valid identifiers (e.g. \"my-field\", \"1title\", \"\"), so anything\n * that isn't a bare identifier is emitted as a quoted property name — always valid TS.\n */\nfunction propName(key: string): string {\n  return VALID_IDENT.test(key) ? key : JSON.stringify(key);\n}\n\n/** A scalar/primitive field maps to a TS type expression (no nesting). */\nfunction scalarType(field: ContentModelField): string {\n  const t: ContentModelFieldType = field.type;\n  switch (t) {\n    case \"text\":\n      return \"string\";\n    case \"richtext\":\n      return \"RichText\";\n    case \"image\":\n      return \"BetterCMSImage\";\n    case \"boolean\":\n      return \"boolean\";\n    case \"number\":\n      return \"number\";\n    case \"date\":\n    case \"datetime\":\n      return \"string\"; // ISO 8601\n    case \"select\": {\n      const opts = field.options?.filter((o) => typeof o === \"string\") ?? [];\n      return opts.length > 0\n        ? opts.map((o) => JSON.stringify(o)).join(\" | \")\n        : \"string\";\n    }\n    case \"reference\":\n      return \"string\"; // referenced entry id\n    case \"multi-reference\":\n      return \"string[]\"; // referenced entry ids\n    case \"array\": {\n      const itemType = (field.config?.itemType as string) ?? \"text\";\n      const inner =\n        itemType === \"number\" ? \"number\" : \"string\"; // text | date → string\n      return `${inner}[]`;\n    }\n    case \"group\":\n    case \"repeater\":\n      // Handled by the caller (needs nested-field expansion); never reached.\n      return \"unknown\";\n    default: {\n      // Exhaustiveness guard: if a new field type is added to the union and not\n      // mapped here, this line becomes a compile error in the codegen build.\n      const _exhaustive: never = t;\n      return \"unknown\";\n    }\n  }\n}\n\n/** Render the body of an object type from a field list, recursing into zones. */\nfunction fieldsToBody(fields: ContentModelField[], indent: string): string {\n  const lines: string[] = [];\n  for (const field of fields) {\n    const optional = field.required ? \"\" : \"?\";\n    let typeExpr: string;\n\n    if (field.type === \"group\") {\n      const nested = fieldsToBody(field.fields ?? [], indent + \"  \");\n      typeExpr = `{\\n${nested}\\n${indent}}`;\n    } else if (field.type === \"repeater\") {\n      const nested = fieldsToBody(field.fields ?? [], indent + \"  \");\n      typeExpr = `Array<{\\n${nested}\\n${indent}}>`;\n    } else {\n      typeExpr = scalarType(field);\n    }\n\n    const safeLabel = field.label ? escapeJsDoc(field.label) : \"\";\n    if (safeLabel && safeLabel !== field.key) {\n      lines.push(`${indent}/** ${safeLabel} */`);\n    }\n    lines.push(`${indent}readonly ${propName(field.key)}${optional}: ${typeExpr};`);\n  }\n  return lines.join(\"\\n\");\n}\n\n/**\n * Generate a complete `.ts` module from a set of content models.\n * Deterministic: models are sorted by slug; field order is preserved as authored.\n */\nexport function generateTypes(\n  models: GeneratableModel[],\n  opts: GenerateOptions = {},\n): string {\n  const version = opts.version ?? \"0.1.0\";\n  // Code-unit sort (NOT localeCompare): locale/ICU-independent so the generated\n  // file is byte-identical on every machine — committed output diffs cleanly.\n  const sorted = [...models].sort((a, b) =>\n    a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0,\n  );\n\n  const header = `// ⚠️  AUTO-GENERATED by @betttercms/codegen v${version} — DO NOT EDIT.\n// Regenerate with: npx @betttercms/codegen\n// Source of truth: your BetterCMS content models (the same schema the dashboard\n// builder and the MCP tools write). Re-run codegen after any schema change.\n${opts.bannerComment ? `// ${opts.bannerComment}\\n` : \"\"}`;\n\n  const interfaces: string[] = [];\n  const mapEntries: string[] = [];\n  // Different slugs can PascalCase to the same base name (e.g. \"case-study\" and\n  // \"case_study\" → \"CaseStudy\"). Emitting two identical interfaces would silently\n  // declaration-merge into one wrong type, so disambiguate with a numeric suffix.\n  const usedNames = new Set<string>();\n\n  for (const model of sorted) {\n    const base = `${pascalCase(model.slug)}Fields`;\n    let typeName = base;\n    for (let n = 2; usedNames.has(typeName); n++) typeName = `${base}_${n}`;\n    usedNames.add(typeName);\n\n    const name = model.name ? escapeJsDoc(model.name) : \"\";\n    const desc = model.description ? escapeJsDoc(model.description) : \"\";\n    const doc = name\n      ? `/**\\n * ${name}${desc ? ` — ${desc}` : \"\"}\\n * Model slug: \\`${model.slug}\\`\\n */\\n`\n      : \"\";\n    const body = model.fields.length\n      ? fieldsToBody(model.fields, \"  \")\n      : \"  // (no fields defined yet)\";\n    interfaces.push(`${doc}export interface ${typeName} {\\n${body}\\n}`);\n    mapEntries.push(`  readonly ${JSON.stringify(model.slug)}: ${typeName};`);\n  }\n\n  const schemaMap = `/**\n * Registry mapping each model slug to its typed fields. The Next adapter uses this to\n * type \\`getEntry(\"blog\", ...)\\` by slug — autocomplete and exhaustiveness for free.\n */\nexport interface BetterCMSSchema {\n${mapEntries.join(\"\\n\") || \"  // (no models defined yet)\"}\n}\n\n/** Union of all model slugs. */\nexport type BetterCMSModelSlug = keyof BetterCMSSchema;`;\n\n  return [header, PREAMBLE, interfaces.join(\"\\n\\n\"), schemaMap, \"\"].join(\"\\n\");\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { ContentModelField } from '@betttercms/types';
+
+/**
+ * @betttercms/codegen — schema → TypeScript generator (the single source of truth).
+ *
+ * Both the dashboard schema builder and the MCP `create_model`/`add_field` tools write
+ * the SAME `content_models.fields` (an array of `ContentModelField`). This generator maps
+ * that one array into TypeScript. Because there is exactly one schema representation, the
+ * generated types can never drift from the editor or the agent — they are the same source.
+ *
+ * Pure + deterministic: same models in → identical string out (stable ordering, no clock,
+ * no I/O). That makes it trivially testable and safe to commit + diff in a customer repo.
+ */
+
+/** Minimal model shape the generator needs — a subset of the Management API model row. */
+interface GeneratableModel {
+    /** Machine-safe slug, e.g. "blog" or "case-study". Used for the schema-map key. */
+    slug: string;
+    /** Human name, used only for the JSDoc header. */
+    name?: string;
+    description?: string | null;
+    fields: ContentModelField[];
+}
+interface GenerateOptions {
+    /** Generator version stamped into the header (defaults to the package version). */
+    version?: string;
+    /** Override the banner timestamp source — omitted by default so output is deterministic. */
+    bannerComment?: string;
+}
+/**
+ * Generate a complete `.ts` module from a set of content models.
+ * Deterministic: models are sorted by slug; field order is preserved as authored.
+ */
+declare function generateTypes(models: GeneratableModel[], opts?: GenerateOptions): string;
+
+/**
+ * Fetches content models from the BetterCMS Management API so the CLI can generate
+ * types against a live project. Kept dependency-free (plain fetch) so the generated
+ * artifact and this fetcher can run anywhere — a GitHub Action, a postinstall, a script.
+ */
+
+interface FetchModelsOptions {
+    /** Management API base, e.g. "https://api.bettercms.ai/api/v1". */
+    apiUrl: string;
+    /** A management-scoped key (content:manage) or device-minted token. */
+    apiKey: string;
+    /** Optional fetch override (testing / custom runtime). */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * GET /management/content/models — returns the project's models (the key is
+ * project-scoped server-side, so this is exactly the schema for this site).
+ */
+declare function fetchModels(opts: FetchModelsOptions): Promise<GeneratableModel[]>;
+
+export { type FetchModelsOptions, type GeneratableModel, type GenerateOptions, fetchModels, generateTypes };

package/dist/index.js

@@ -0,0 +1,185 @@
+// src/generate.ts
+var PREAMBLE = `/**
+ * Rich-text field value \u2014 the serialized portable rich-text payload returned by the
+ * Delivery API. Treated as opaque; render it with your editor's serializer.
+ */
+export type RichText = { readonly format: string; readonly value: unknown };
+
+/** Image / media field value as resolved by the Delivery API. */
+export interface BetterCMSImage {
+  readonly url: string;
+  readonly alt?: string;
+  readonly width?: number;
+  readonly height?: number;
+}
+
+/**
+ * Delivery envelope around a model's typed \`data\`. \`getEntry\`/\`listEntries\` in the
+ * Next adapter return this shape, with \`fields\` typed by the model.
+ */
+export interface BetterCMSEntry<TFields> {
+  readonly slug: string;
+  readonly status: "draft" | "published";
+  readonly fields: TFields;
+  readonly updatedAt: string;
+}
+`;
+function pascalCase(slug) {
+  const parts = slug.split(/[-_\s]+/).filter(Boolean);
+  const pascal = parts.map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+  return /^[0-9]/.test(pascal) ? `Model${pascal}` : pascal || "Model";
+}
+function escapeJsDoc(text) {
+  return text.replace(/\*\//g, "* /").replace(/[\r\n]+/g, " ").trim();
+}
+var VALID_IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function propName(key) {
+  return VALID_IDENT.test(key) ? key : JSON.stringify(key);
+}
+function scalarType(field) {
+  const t = field.type;
+  switch (t) {
+    case "text":
+      return "string";
+    case "richtext":
+      return "RichText";
+    case "image":
+      return "BetterCMSImage";
+    case "boolean":
+      return "boolean";
+    case "number":
+      return "number";
+    case "date":
+    case "datetime":
+      return "string";
+    // ISO 8601
+    case "select": {
+      const opts = field.options?.filter((o) => typeof o === "string") ?? [];
+      return opts.length > 0 ? opts.map((o) => JSON.stringify(o)).join(" | ") : "string";
+    }
+    case "reference":
+      return "string";
+    // referenced entry id
+    case "multi-reference":
+      return "string[]";
+    // referenced entry ids
+    case "array": {
+      const itemType = field.config?.itemType ?? "text";
+      const inner = itemType === "number" ? "number" : "string";
+      return `${inner}[]`;
+    }
+    case "group":
+    case "repeater":
+      return "unknown";
+    default: {
+      const _exhaustive = t;
+      return "unknown";
+    }
+  }
+}
+function fieldsToBody(fields, indent) {
+  const lines = [];
+  for (const field of fields) {
+    const optional = field.required ? "" : "?";
+    let typeExpr;
+    if (field.type === "group") {
+      const nested = fieldsToBody(field.fields ?? [], indent + "  ");
+      typeExpr = `{
+${nested}
+${indent}}`;
+    } else if (field.type === "repeater") {
+      const nested = fieldsToBody(field.fields ?? [], indent + "  ");
+      typeExpr = `Array<{
+${nested}
+${indent}}>`;
+    } else {
+      typeExpr = scalarType(field);
+    }
+    const safeLabel = field.label ? escapeJsDoc(field.label) : "";
+    if (safeLabel && safeLabel !== field.key) {
+      lines.push(`${indent}/** ${safeLabel} */`);
+    }
+    lines.push(`${indent}readonly ${propName(field.key)}${optional}: ${typeExpr};`);
+  }
+  return lines.join("\n");
+}
+function generateTypes(models, opts = {}) {
+  const version = opts.version ?? "0.1.0";
+  const sorted = [...models].sort(
+    (a, b) => a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0
+  );
+  const header = `// \u26A0\uFE0F  AUTO-GENERATED by @betttercms/codegen v${version} \u2014 DO NOT EDIT.
+// Regenerate with: npx @betttercms/codegen
+// Source of truth: your BetterCMS content models (the same schema the dashboard
+// builder and the MCP tools write). Re-run codegen after any schema change.
+${opts.bannerComment ? `// ${opts.bannerComment}
+` : ""}`;
+  const interfaces = [];
+  const mapEntries = [];
+  const usedNames = /* @__PURE__ */ new Set();
+  for (const model of sorted) {
+    const base = `${pascalCase(model.slug)}Fields`;
+    let typeName = base;
+    for (let n = 2; usedNames.has(typeName); n++) typeName = `${base}_${n}`;
+    usedNames.add(typeName);
+    const name = model.name ? escapeJsDoc(model.name) : "";
+    const desc = model.description ? escapeJsDoc(model.description) : "";
+    const doc = name ? `/**
+ * ${name}${desc ? ` \u2014 ${desc}` : ""}
+ * Model slug: \`${model.slug}\`
+ */
+` : "";
+    const body = model.fields.length ? fieldsToBody(model.fields, "  ") : "  // (no fields defined yet)";
+    interfaces.push(`${doc}export interface ${typeName} {
+${body}
+}`);
+    mapEntries.push(`  readonly ${JSON.stringify(model.slug)}: ${typeName};`);
+  }
+  const schemaMap = `/**
+ * Registry mapping each model slug to its typed fields. The Next adapter uses this to
+ * type \`getEntry("blog", ...)\` by slug \u2014 autocomplete and exhaustiveness for free.
+ */
+export interface BetterCMSSchema {
+${mapEntries.join("\n") || "  // (no models defined yet)"}
+}
+
+/** Union of all model slugs. */
+export type BetterCMSModelSlug = keyof BetterCMSSchema;`;
+  return [header, PREAMBLE, interfaces.join("\n\n"), schemaMap, ""].join("\n");
+}
+
+// src/fetch-models.ts
+async function fetchModels(opts) {
+  const doFetch = opts.fetchImpl ?? globalThis.fetch;
+  const base = opts.apiUrl.replace(/\/+$/, "");
+  const url = `${base}/management/content/models`;
+  let res;
+  try {
+    res = await doFetch(url, {
+      // No Content-Type: this is a bodyless GET; the header is incorrect here and
+      // strict edge runtimes/proxies may reject it.
+      headers: { Authorization: `Bearer ${opts.apiKey}`, Accept: "application/json" }
+    });
+  } catch (err) {
+    throw new Error(
+      `Could not reach the BetterCMS Management API at ${url}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (!res.ok) {
+    const hint = res.status === 401 || res.status === 403 ? " \u2014 check your management API key (it must have the content:manage scope)." : "";
+    throw new Error(`Management API returned ${res.status} ${res.statusText}${hint}`);
+  }
+  const body = await res.json();
+  const rows = body.data ?? [];
+  return rows.map((r) => ({
+    slug: r.slug,
+    name: r.name,
+    description: r.description ?? null,
+    fields: r.fields ?? []
+  }));
+}
+export {
+  fetchModels,
+  generateTypes
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/generate.ts","../src/fetch-models.ts"],"sourcesContent":["/**\n * @betttercms/codegen — schema → TypeScript generator (the single source of truth).\n *\n * Both the dashboard schema builder and the MCP `create_model`/`add_field` tools write\n * the SAME `content_models.fields` (an array of `ContentModelField`). This generator maps\n * that one array into TypeScript. Because there is exactly one schema representation, the\n * generated types can never drift from the editor or the agent — they are the same source.\n *\n * Pure + deterministic: same models in → identical string out (stable ordering, no clock,\n * no I/O). That makes it trivially testable and safe to commit + diff in a customer repo.\n */\n\nimport type { ContentModelField, ContentModelFieldType } from \"@betttercms/types\";\n\n/** Minimal model shape the generator needs — a subset of the Management API model row. */\nexport interface GeneratableModel {\n  /** Machine-safe slug, e.g. \"blog\" or \"case-study\". Used for the schema-map key. */\n  slug: string;\n  /** Human name, used only for the JSDoc header. */\n  name?: string;\n  description?: string | null;\n  fields: ContentModelField[];\n}\n\nexport interface GenerateOptions {\n  /** Generator version stamped into the header (defaults to the package version). */\n  version?: string;\n  /** Override the banner timestamp source — omitted by default so output is deterministic. */\n  bannerComment?: string;\n}\n\n/** Helper types emitted once at the top of every generated file (self-contained, zero-dep). */\nconst PREAMBLE = `/**\n * Rich-text field value — the serialized portable rich-text payload returned by the\n * Delivery API. Treated as opaque; render it with your editor's serializer.\n */\nexport type RichText = { readonly format: string; readonly value: unknown };\n\n/** Image / media field value as resolved by the Delivery API. */\nexport interface BetterCMSImage {\n  readonly url: string;\n  readonly alt?: string;\n  readonly width?: number;\n  readonly height?: number;\n}\n\n/**\n * Delivery envelope around a model's typed \\`data\\`. \\`getEntry\\`/\\`listEntries\\` in the\n * Next adapter return this shape, with \\`fields\\` typed by the model.\n */\nexport interface BetterCMSEntry<TFields> {\n  readonly slug: string;\n  readonly status: \"draft\" | \"published\";\n  readonly fields: TFields;\n  readonly updatedAt: string;\n}\n`;\n\n/** PascalCase an identifier from a slug: \"case-study\" → \"CaseStudy\". */\nfunction pascalCase(slug: string): string {\n  const parts = slug.split(/[-_\\s]+/).filter(Boolean);\n  const pascal = parts\n    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))\n    .join(\"\");\n  // Guard against an identifier that starts with a digit (invalid TS type name).\n  return /^[0-9]/.test(pascal) ? `Model${pascal}` : pascal || \"Model\";\n}\n\n/**\n * Make a string safe to embed inside a `/** ... *​/` JSDoc comment. A field label\n * (free-text, author/agent-controlled) could contain `*​/` — which closes the comment\n * early and injects the remainder as code — or a newline, which breaks the single-line\n * comment. Both are neutralized here. Without this, hostile content produces non-\n * compiling (or worse, code-injected) output.\n */\nfunction escapeJsDoc(text: string): string {\n  return text.replace(/\\*\\//g, \"* /\").replace(/[\\r\\n]+/g, \" \").trim();\n}\n\nconst VALID_IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;\n\n/**\n * Render a field key as a TS property name. Field keys are author/agent-controlled and\n * not guaranteed to be valid identifiers (e.g. \"my-field\", \"1title\", \"\"), so anything\n * that isn't a bare identifier is emitted as a quoted property name — always valid TS.\n */\nfunction propName(key: string): string {\n  return VALID_IDENT.test(key) ? key : JSON.stringify(key);\n}\n\n/** A scalar/primitive field maps to a TS type expression (no nesting). */\nfunction scalarType(field: ContentModelField): string {\n  const t: ContentModelFieldType = field.type;\n  switch (t) {\n    case \"text\":\n      return \"string\";\n    case \"richtext\":\n      return \"RichText\";\n    case \"image\":\n      return \"BetterCMSImage\";\n    case \"boolean\":\n      return \"boolean\";\n    case \"number\":\n      return \"number\";\n    case \"date\":\n    case \"datetime\":\n      return \"string\"; // ISO 8601\n    case \"select\": {\n      const opts = field.options?.filter((o) => typeof o === \"string\") ?? [];\n      return opts.length > 0\n        ? opts.map((o) => JSON.stringify(o)).join(\" | \")\n        : \"string\";\n    }\n    case \"reference\":\n      return \"string\"; // referenced entry id\n    case \"multi-reference\":\n      return \"string[]\"; // referenced entry ids\n    case \"array\": {\n      const itemType = (field.config?.itemType as string) ?? \"text\";\n      const inner =\n        itemType === \"number\" ? \"number\" : \"string\"; // text | date → string\n      return `${inner}[]`;\n    }\n    case \"group\":\n    case \"repeater\":\n      // Handled by the caller (needs nested-field expansion); never reached.\n      return \"unknown\";\n    default: {\n      // Exhaustiveness guard: if a new field type is added to the union and not\n      // mapped here, this line becomes a compile error in the codegen build.\n      const _exhaustive: never = t;\n      return \"unknown\";\n    }\n  }\n}\n\n/** Render the body of an object type from a field list, recursing into zones. */\nfunction fieldsToBody(fields: ContentModelField[], indent: string): string {\n  const lines: string[] = [];\n  for (const field of fields) {\n    const optional = field.required ? \"\" : \"?\";\n    let typeExpr: string;\n\n    if (field.type === \"group\") {\n      const nested = fieldsToBody(field.fields ?? [], indent + \"  \");\n      typeExpr = `{\\n${nested}\\n${indent}}`;\n    } else if (field.type === \"repeater\") {\n      const nested = fieldsToBody(field.fields ?? [], indent + \"  \");\n      typeExpr = `Array<{\\n${nested}\\n${indent}}>`;\n    } else {\n      typeExpr = scalarType(field);\n    }\n\n    const safeLabel = field.label ? escapeJsDoc(field.label) : \"\";\n    if (safeLabel && safeLabel !== field.key) {\n      lines.push(`${indent}/** ${safeLabel} */`);\n    }\n    lines.push(`${indent}readonly ${propName(field.key)}${optional}: ${typeExpr};`);\n  }\n  return lines.join(\"\\n\");\n}\n\n/**\n * Generate a complete `.ts` module from a set of content models.\n * Deterministic: models are sorted by slug; field order is preserved as authored.\n */\nexport function generateTypes(\n  models: GeneratableModel[],\n  opts: GenerateOptions = {},\n): string {\n  const version = opts.version ?? \"0.1.0\";\n  // Code-unit sort (NOT localeCompare): locale/ICU-independent so the generated\n  // file is byte-identical on every machine — committed output diffs cleanly.\n  const sorted = [...models].sort((a, b) =>\n    a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0,\n  );\n\n  const header = `// ⚠️  AUTO-GENERATED by @betttercms/codegen v${version} — DO NOT EDIT.\n// Regenerate with: npx @betttercms/codegen\n// Source of truth: your BetterCMS content models (the same schema the dashboard\n// builder and the MCP tools write). Re-run codegen after any schema change.\n${opts.bannerComment ? `// ${opts.bannerComment}\\n` : \"\"}`;\n\n  const interfaces: string[] = [];\n  const mapEntries: string[] = [];\n  // Different slugs can PascalCase to the same base name (e.g. \"case-study\" and\n  // \"case_study\" → \"CaseStudy\"). Emitting two identical interfaces would silently\n  // declaration-merge into one wrong type, so disambiguate with a numeric suffix.\n  const usedNames = new Set<string>();\n\n  for (const model of sorted) {\n    const base = `${pascalCase(model.slug)}Fields`;\n    let typeName = base;\n    for (let n = 2; usedNames.has(typeName); n++) typeName = `${base}_${n}`;\n    usedNames.add(typeName);\n\n    const name = model.name ? escapeJsDoc(model.name) : \"\";\n    const desc = model.description ? escapeJsDoc(model.description) : \"\";\n    const doc = name\n      ? `/**\\n * ${name}${desc ? ` — ${desc}` : \"\"}\\n * Model slug: \\`${model.slug}\\`\\n */\\n`\n      : \"\";\n    const body = model.fields.length\n      ? fieldsToBody(model.fields, \"  \")\n      : \"  // (no fields defined yet)\";\n    interfaces.push(`${doc}export interface ${typeName} {\\n${body}\\n}`);\n    mapEntries.push(`  readonly ${JSON.stringify(model.slug)}: ${typeName};`);\n  }\n\n  const schemaMap = `/**\n * Registry mapping each model slug to its typed fields. The Next adapter uses this to\n * type \\`getEntry(\"blog\", ...)\\` by slug — autocomplete and exhaustiveness for free.\n */\nexport interface BetterCMSSchema {\n${mapEntries.join(\"\\n\") || \"  // (no models defined yet)\"}\n}\n\n/** Union of all model slugs. */\nexport type BetterCMSModelSlug = keyof BetterCMSSchema;`;\n\n  return [header, PREAMBLE, interfaces.join(\"\\n\\n\"), schemaMap, \"\"].join(\"\\n\");\n}\n","/**\n * Fetches content models from the BetterCMS Management API so the CLI can generate\n * types against a live project. Kept dependency-free (plain fetch) so the generated\n * artifact and this fetcher can run anywhere — a GitHub Action, a postinstall, a script.\n */\n\nimport type { GeneratableModel } from \"./generate.js\";\n\nexport interface FetchModelsOptions {\n  /** Management API base, e.g. \"https://api.bettercms.ai/api/v1\". */\n  apiUrl: string;\n  /** A management-scoped key (content:manage) or device-minted token. */\n  apiKey: string;\n  /** Optional fetch override (testing / custom runtime). */\n  fetchImpl?: typeof fetch;\n}\n\ninterface ManagedModelRow {\n  slug: string;\n  name?: string;\n  description?: string | null;\n  fields: GeneratableModel[\"fields\"];\n}\n\n/**\n * GET /management/content/models — returns the project's models (the key is\n * project-scoped server-side, so this is exactly the schema for this site).\n */\nexport async function fetchModels(\n  opts: FetchModelsOptions,\n): Promise<GeneratableModel[]> {\n  const doFetch = opts.fetchImpl ?? globalThis.fetch;\n  const base = opts.apiUrl.replace(/\\/+$/, \"\");\n  const url = `${base}/management/content/models`;\n\n  let res: Response;\n  try {\n    res = await doFetch(url, {\n      // No Content-Type: this is a bodyless GET; the header is incorrect here and\n      // strict edge runtimes/proxies may reject it.\n      headers: { Authorization: `Bearer ${opts.apiKey}`, Accept: \"application/json\" },\n    });\n  } catch (err) {\n    throw new Error(\n      `Could not reach the BetterCMS Management API at ${url}: ${\n        err instanceof Error ? err.message : String(err)\n      }`,\n    );\n  }\n\n  if (!res.ok) {\n    const hint =\n      res.status === 401 || res.status === 403\n        ? \" — check your management API key (it must have the content:manage scope).\"\n        : \"\";\n    throw new Error(`Management API returned ${res.status} ${res.statusText}${hint}`);\n  }\n\n  const body = (await res.json()) as { data?: ManagedModelRow[] };\n  const rows = body.data ?? [];\n  return rows.map((r) => ({\n    slug: r.slug,\n    name: r.name,\n    description: r.description ?? null,\n    fields: r.fields ?? [],\n  }));\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@betttercms/codegen",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Generate TypeScript types from your BetterCMS content schema — the single source of truth shared by the dashboard builder and the MCP tools.",
+  "bin": {
+    "bettercms-codegen": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@betttercms/types": "^1.0.17"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsup": "^8.5.1",
+    "vitest": "^4.1.4"
+  }
+}