@riverbankcms/sdk 0.3.0 → 0.4.0

package/README.md

@@ -12,6 +12,7 @@ A lightweight TypeScript SDK for consuming Riverbank CMS content in React Server
 - ✅ **Type-safe API client** with caching
 - ✅ **React Server Components** compatible
 - ✅ **Custom blocks** - Define site-specific blocks with full CMS editing support
+- ✅ **Content scaffolding** - Define content types, pages, entries, and navigation in code
 
 ## Installation
 
@@ -1879,6 +1880,259 @@ import {
 } from '@riverbankcms/sdk/data';
 ```
 
+## Content Configuration (SDK Content Scaffolding)
+
+Define content types, pages, entries, navigation menus, and site settings in code. When you push your SDK config, this content is automatically synced to the CMS database.
+
+### Quick Start
+
+Create a `content.config.ts` file alongside your `riverbank.config.ts`:
+
+```typescript
+// content.config.ts
+import { defineContentConfig } from '@riverbankcms/sdk/config';
+
+export const contentConfig = defineContentConfig({
+  // Content type definitions
+  contentTypes: [
+    {
+      key: 'testimonial',
+      name: 'Testimonial',
+      hasPages: false,
+      fields: [
+        { id: 'quote', type: 'richText', label: 'Quote', required: true },
+        { id: 'author', type: 'text', label: 'Author Name', required: true, multiline: false },
+      ],
+    },
+  ],
+
+  // Page definitions
+  pages: [
+    {
+      identifier: 'home',
+      path: '/',
+      title: 'Home',
+      status: 'published',
+    },
+  ],
+
+  // Content entries
+  entries: [
+    {
+      identifier: 'testimonial-1',
+      contentType: 'testimonial',
+      title: 'First Testimonial',
+      status: 'published',
+      data: {
+        quote: '<p>Great product!</p>',
+        author: 'Jane Doe',
+      },
+    },
+  ],
+
+  // Navigation menus
+  navigationMenus: [
+    {
+      identifier: 'main',
+      name: 'Main Navigation',
+      isPrimary: true,
+      items: [
+        { label: 'Home', link: { kind: 'page', identifier: 'home' } },
+      ],
+    },
+  ],
+
+  // Site settings
+  settings: {
+    homepagePath: '/',
+    siteTitle: 'My Site',
+    siteDescription: 'Welcome to my site',
+  },
+});
+```
+
+Then import it in your main config:
+
+```typescript
+// riverbank.config.ts
+import { defineConfig } from '@riverbankcms/sdk/config';
+import { contentConfig } from './content.config';
+
+export default defineConfig({
+  siteId: 'your-site-id',
+  theme: { /* ... */ },
+  content: contentConfig,
+});
+```
+
+### Content Types
+
+Define reusable content structures:
+
+```typescript
+contentTypes: [
+  {
+    key: 'blog-post',           // Unique identifier
+    name: 'Blog Post',          // Display name
+    description: 'Blog articles',
+    hasPages: true,             // Whether entries are routable
+    routePattern: '/blog/{slug}', // URL pattern (required if hasPages)
+    fields: [
+      { id: 'body', type: 'richText', label: 'Content', required: true },
+      { id: 'author', type: 'text', label: 'Author', required: false, multiline: false },
+      { id: 'featuredImage', type: 'media', label: 'Featured Image', mediaKinds: ['image'] },
+    ],
+    titleField: 'title',        // Field to use as entry title
+  },
+]
+```
+
+### Pages
+
+Define pages with optional initial blocks:
+
+```typescript
+pages: [
+  {
+    identifier: 'about',        // Required, unique per site
+    path: '/about',             // URL path
+    title: 'About Us',
+    purpose: 'content',         // 'content' | 'landing' | etc.
+    status: 'draft',            // 'draft' | 'published'
+    metaTitle: 'About Us | My Site',
+    metaDescription: 'Learn more about our company',
+    blocks: [
+      {
+        kind: 'block.hero',
+        content: { headline: 'About Us', subheadline: 'Our Story' },
+        orderIndex: 0,
+      },
+    ],
+  },
+]
+```
+
+### Content Entries
+
+Create content entries for your content types:
+
+```typescript
+entries: [
+  {
+    identifier: 'john-smith',   // Required, unique per site
+    contentType: 'team-member', // Content type key
+    title: 'John Smith',
+    slug: 'john-smith',         // For routable entries (defaults to identifier)
+    status: 'published',
+    data: {
+      bio: '<p>Our founder...</p>',
+      role: 'CEO',
+    },
+    metaTitle: 'John Smith | Team',
+    metaDescription: 'Meet John Smith, our CEO',
+  },
+]
+```
+
+### Navigation Menus
+
+Define navigation structure with page/entry references:
+
+```typescript
+navigationMenus: [
+  {
+    identifier: 'main',
+    name: 'Main Navigation',
+    isPrimary: true,
+    items: [
+      // Link to a page by identifier
+      { label: 'Home', link: { kind: 'page', identifier: 'home' } },
+
+      // Link to a routable content entry
+      { label: 'About John', link: { kind: 'entry', identifier: 'john-smith' } },
+
+      // External link
+      { label: 'GitHub', link: { kind: 'external', href: 'https://github.com' } },
+
+      // Dropdown with children
+      {
+        label: 'Resources',
+        link: { kind: 'dropdown' },
+        children: [
+          { label: 'Blog', link: { kind: 'page', identifier: 'blog' } },
+          { label: 'Docs', link: { kind: 'external', href: 'https://docs.example.com' } },
+        ],
+      },
+    ],
+  },
+]
+```
+
+### Site Settings
+
+Configure site-wide settings:
+
+```typescript
+settings: {
+  homepagePath: '/',           // Path to homepage
+  siteTitle: 'My Site',        // Site title for metadata
+  siteDescription: 'Welcome',  // Site description for metadata
+}
+```
+
+### Sync Behavior
+
+When you run `riverbank push`:
+
+1. **Creates** new content if the identifier doesn't exist
+2. **Updates** existing content if it hasn't been modified in the dashboard
+3. **Skips** content that was edited in the dashboard (preserves manual changes)
+4. **Never deletes** - removing from config doesn't delete from CMS
+
+This "overwrite if unchanged" behavior ensures:
+- SDK-defined content can be version controlled
+- Dashboard edits are never lost
+- Teams can safely iterate on config
+
+### Sync Order
+
+Content syncs in dependency order:
+
+1. Content Types (no dependencies)
+2. Site Settings (no dependencies)
+3. Pages (needed for navigation references)
+4. Content Entries (depend on content types)
+5. Navigation Menus (reference pages and entries)
+
+### Validation
+
+The SDK validates your content config on push:
+
+- Unique identifiers per entity type
+- Valid content type references
+- Valid field definitions
+- Navigation references resolve to existing pages/entries
+- Path uniqueness for pages
+
+### Types
+
+```typescript
+import {
+  // Helper function
+  defineContentConfig,
+
+  // Types
+  type ContentConfig,
+  type ContentTypeConfig,
+  type PageConfig,
+  type EntryConfig,
+  type BlockConfig,
+  type NavigationMenuConfig,
+  type NavigationItemConfig,
+  type SiteSettingsConfig,
+} from '@riverbankcms/sdk/config';
+```
+
 ## Additional Exports
 
 - `@riverbankcms/sdk/rendering` - Low-level rendering components
@@ -1889,4 +2143,4 @@ import {
 - `@riverbankcms/sdk/metadata` - Metadata generation helpers
 - `@riverbankcms/sdk/routing` - Route resolution helpers
 - `@riverbankcms/sdk/analytics` - Analytics tracking helpers
-- `@riverbankcms/sdk/config` - Site configuration utilities (includes `defineConfig`, `RiverbankSiteConfig`, `BlockFieldOptionsMap`, `FieldSelectOption`, etc.)
+- `@riverbankcms/sdk/config` - Site configuration utilities (includes `defineConfig`, `defineContentConfig`, `RiverbankSiteConfig`, `ContentConfig`, etc.)

package/dist/cli/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
+var dotenv = require('dotenv');
 var commander = require('commander');
 var zod = require('zod');
 var jiti = require('jiti');
@@ -685,7 +686,7 @@ function sectionContainer(children, opts) {
 var DEFAULT_SECTION_SPACING = "medium";
 
 // ../blocks/src/system/node/fragments/styledSection.ts
-function styledSection(config) {
+function styledSection(config2) {
   const {
     children,
     baseClass = "px-6",
@@ -693,7 +694,7 @@ function styledSection(config) {
     background = "background/base",
     bindFrom = "_sectionStyles",
     imageClassName = "absolute -z-10"
-  } = config;
+  } = config2;
   const backgroundNodes = backgroundLayer(`${bindFrom}.background`, {
     imageClassName
   });
@@ -834,8 +835,8 @@ var FragmentConfigError = class extends Error {
     this.name = "FragmentConfigError";
   }
 };
-function defineFragment(config) {
-  const parsed = fragmentConfigSchema.parse(config);
+function defineFragment(config2) {
+  const parsed = fragmentConfigSchema.parse(config2);
   validateFieldDefinitions(parsed.fields, parsed.id);
   return {
     ...parsed,
@@ -1042,26 +1043,26 @@ var FragmentCompositionError = class extends Error {
   }
 };
 var DOT_SCOPE_REGEX = /^[A-Za-z0-9_.-]*$/;
-function materializeFragment(config) {
-  const scope = normalizeScope(config.scope);
-  const fields4 = scopeFragmentFields(config.fragment, scope);
-  const layout = scopeFragmentLayout(config.fragment, scope);
-  const fieldPriority = config.fieldPriority ?? 0;
+function materializeFragment(config2) {
+  const scope = normalizeScope(config2.scope);
+  const fields4 = scopeFragmentFields(config2.fragment, scope);
+  const layout = scopeFragmentLayout(config2.fragment, scope);
+  const fieldPriority = config2.fieldPriority ?? 0;
   let data;
-  if (config.fragment.data) {
-    const key = config.dataKey ?? config.fragment.data.key;
+  if (config2.fragment.data) {
+    const key = config2.dataKey ?? config2.fragment.data.key;
     if (!key || typeof key !== "string") {
       throw new FragmentCompositionError(
-        `Fragment "${config.fragment.id}" requires a data key to compose.`
+        `Fragment "${config2.fragment.id}" requires a data key to compose.`
       );
     }
     data = {
       key,
-      loader: config.fragment.data.loader ? { ...config.fragment.data.loader } : void 0
+      loader: config2.fragment.data.loader ? { ...config2.fragment.data.loader } : void 0
     };
   }
   return {
-    fragment: config.fragment,
+    fragment: config2.fragment,
     scope,
     fields: fields4,
     layout,
@@ -2845,13 +2846,13 @@ function sectionStylesField(options = {}) {
 }
 
 // ../blocks/src/system/defineBlock.ts
-function createBlockManifest(config) {
-  const composition2 = config.fragments ? composeFragments(config.fragments) : { fields: []};
+function createBlockManifest(config2) {
+  const composition2 = config2.fragments ? composeFragments(config2.fragments) : { fields: []};
   const allFields = [
     ...composition2.fields,
-    ...config.additionalFields ?? []
+    ...config2.additionalFields ?? []
   ];
-  if (!config.skipSectionStyles) {
+  if (!config2.skipSectionStyles) {
     allFields.push(
       sectionStylesField({
         id: "_sectionStyles",
@@ -2860,36 +2861,36 @@ function createBlockManifest(config) {
     );
   }
   const fields4 = fieldSchema.array().parse(allFields);
-  const layout = config.layout;
-  const variants = config.variants;
-  let behaviours = config.behaviours;
-  if (!behaviours && config.paletteHidden !== void 0) {
+  const layout = config2.layout;
+  const variants = config2.variants;
+  let behaviours = config2.behaviours;
+  if (!behaviours && config2.paletteHidden !== void 0) {
     behaviours = {
       supportsThemeSwitching: true,
       inlineEditing: true,
       animation: true,
-      paletteHidden: config.paletteHidden
+      paletteHidden: config2.paletteHidden
     };
   }
   const manifest = {
-    name: config.id,
+    name: config2.id,
     version: "0.1.0",
-    title: config.title,
-    titleSource: config.titleSource,
-    description: config.description ?? "",
-    component: config.component ?? deriveComponentName(config.id),
+    title: config2.title,
+    titleSource: config2.titleSource,
+    description: config2.description ?? "",
+    component: config2.component ?? deriveComponentName(config2.id),
     fields: fields4,
     slots: [],
     // Always empty
-    styleTokens: config.styleTokens,
+    styleTokens: config2.styleTokens,
     behaviours,
-    category: config.category,
-    contentTypes: config.contentTypes,
-    tags: config.tags ?? [],
-    icon: config.icon ?? "Box",
+    category: config2.category,
+    contentTypes: config2.contentTypes,
+    tags: config2.tags ?? [],
+    icon: config2.icon ?? "Box",
     layout,
     variants,
-    defaultVariant: config.defaultVariant
+    defaultVariant: config2.defaultVariant
   };
   return augmentManifest(manifest);
 }
@@ -4840,6 +4841,211 @@ function getBlockDefinition(name) {
   return blockStore.get(name);
 }
 
+// ../blocks/src/system/constants/blockKinds.ts
+var SYSTEM_BLOCK_KINDS = [
+  // Layout blocks
+  "block.hero",
+  "block.columns",
+  "block.ctaFull",
+  "block.singleButton",
+  // Content blocks
+  "block.bodyText",
+  "block.faq",
+  "block.testimonials",
+  "block.embed",
+  // Blog blocks
+  "block.blogPost",
+  "block.blogPlaceholder",
+  "block.blogListing",
+  // Site structure blocks
+  "block.siteHeader",
+  "block.siteFooter",
+  // Form/booking blocks
+  "block.form",
+  "block.appointment-booking",
+  "block.event-registration",
+  // Event display blocks
+  "block.event-spotlight",
+  "block.event-listing",
+  "block.event-calendar"
+];
+
+// src/config/content-validation.ts
+var jsonDataSchema = zod.z.record(zod.z.string(), zod.z.any());
+var contentTypeKeySchema = zod.z.string().min(1).regex(
+  /^[a-z][a-z0-9-]*$/,
+  "Key must be lowercase, start with a letter, and contain only letters, numbers, and hyphens"
+);
+var contentTypeConfigSchema = zod.z.object({
+  key: contentTypeKeySchema,
+  name: zod.z.string().min(1),
+  description: zod.z.string().optional(),
+  hasPages: zod.z.boolean(),
+  routePattern: zod.z.string().optional(),
+  // Fields are validated as any[] here - deep field validation happens in @riverbankcms/blocks
+  fields: zod.z.array(zod.z.any()).min(1, "At least one field is required"),
+  titleField: zod.z.string().optional()
+}).refine(
+  (data) => {
+    if (data.hasPages) {
+      return data.routePattern && data.routePattern.includes("{slug}");
+    }
+    return true;
+  },
+  { message: "routePattern with {slug} is required when hasPages is true" }
+).refine(
+  (data) => {
+    if (!data.hasPages && data.routePattern) {
+      return false;
+    }
+    return true;
+  },
+  { message: "routePattern must not be defined when hasPages is false" }
+);
+var blockKindSchema = zod.z.string().refine(
+  (kind) => {
+    if (SYSTEM_BLOCK_KINDS.includes(kind)) {
+      return true;
+    }
+    if (kind.startsWith("custom.") && kind.length > 7) {
+      return true;
+    }
+    return false;
+  },
+  {
+    message: 'Block kind must be a system block (e.g., "block.hero") or a custom block (e.g., "custom.myBlock")'
+  }
+);
+var blockConfigSchema = zod.z.object({
+  kind: blockKindSchema,
+  content: jsonDataSchema,
+  orderIndex: zod.z.number().optional()
+});
+var pageConfigSchema = zod.z.object({
+  identifier: zod.z.string().min(1, "Identifier is required"),
+  title: zod.z.string().min(1, "Title is required"),
+  path: zod.z.string().regex(/^\//, "Path must start with /"),
+  purpose: zod.z.string().default("content"),
+  blocks: zod.z.array(blockConfigSchema).optional(),
+  status: zod.z.enum(["draft", "published"]).default("draft"),
+  metaTitle: zod.z.string().optional(),
+  metaDescription: zod.z.string().optional()
+});
+var entryConfigSchema = zod.z.object({
+  identifier: zod.z.string().min(1, "Identifier is required"),
+  contentType: zod.z.string().min(1, "Content type is required"),
+  data: jsonDataSchema,
+  status: zod.z.enum(["draft", "published"]).default("draft"),
+  slug: zod.z.string().optional(),
+  title: zod.z.string().optional(),
+  summary: zod.z.string().optional(),
+  metaTitle: zod.z.string().optional(),
+  metaDescription: zod.z.string().optional()
+});
+var pageLinkSchema = zod.z.object({
+  kind: zod.z.literal("page"),
+  identifier: zod.z.string().min(1)
+});
+var entryLinkSchema = zod.z.object({
+  kind: zod.z.literal("entry"),
+  identifier: zod.z.string().min(1)
+});
+var externalLinkSchema = zod.z.object({
+  kind: zod.z.literal("external"),
+  href: zod.z.string().url("Invalid URL")
+});
+var dropdownLinkSchema = zod.z.object({
+  kind: zod.z.literal("dropdown")
+});
+var navigationLinkSchema = zod.z.discriminatedUnion("kind", [
+  pageLinkSchema,
+  entryLinkSchema,
+  externalLinkSchema,
+  dropdownLinkSchema
+]);
+var baseNavigationItemSchema = zod.z.object({
+  label: zod.z.string().min(1, "Label is required"),
+  link: navigationLinkSchema,
+  isCta: zod.z.boolean().optional()
+});
+var navigationItemConfigSchema = baseNavigationItemSchema.extend({
+  children: zod.z.lazy(() => zod.z.array(navigationItemConfigSchema)).optional()
+});
+var navigationMenuConfigSchema = zod.z.object({
+  identifier: zod.z.string().min(1, "Identifier is required"),
+  name: zod.z.string().min(1, "Name is required"),
+  isPrimary: zod.z.boolean().optional(),
+  items: zod.z.array(navigationItemConfigSchema)
+});
+var siteSettingsConfigSchema = zod.z.object({
+  homepagePath: zod.z.string().optional(),
+  siteTitle: zod.z.string().optional(),
+  siteDescription: zod.z.string().optional(),
+  defaultTemplates: zod.z.record(zod.z.string(), zod.z.string()).optional()
+});
+var contentConfigBaseSchema = zod.z.object({
+  contentTypes: zod.z.array(contentTypeConfigSchema).optional(),
+  entries: zod.z.array(entryConfigSchema).optional(),
+  pages: zod.z.array(pageConfigSchema).optional(),
+  navigationMenus: zod.z.array(navigationMenuConfigSchema).optional(),
+  settings: siteSettingsConfigSchema.optional()
+});
+var contentConfigSchema = contentConfigBaseSchema.superRefine((data, ctx) => {
+  if (data.contentTypes && data.contentTypes.length > 1) {
+    const keys = data.contentTypes.map((ct) => ct.key);
+    const duplicateKeys = keys.filter((key, i) => keys.indexOf(key) !== i);
+    if (duplicateKeys.length > 0) {
+      ctx.addIssue({
+        code: zod.z.ZodIssueCode.custom,
+        message: `Content type keys must be unique. Duplicates: ${duplicateKeys.join(", ")}`,
+        path: ["contentTypes"]
+      });
+    }
+  }
+  if (data.pages && data.pages.length > 1) {
+    const identifiers = data.pages.map((p) => p.identifier);
+    const duplicateIds = identifiers.filter((id, i) => identifiers.indexOf(id) !== i);
+    if (duplicateIds.length > 0) {
+      ctx.addIssue({
+        code: zod.z.ZodIssueCode.custom,
+        message: `Page identifiers must be unique. Duplicates: ${duplicateIds.join(", ")}`,
+        path: ["pages"]
+      });
+    }
+    const paths = data.pages.map((p) => p.path);
+    const duplicatePaths = paths.filter((path, i) => paths.indexOf(path) !== i);
+    if (duplicatePaths.length > 0) {
+      ctx.addIssue({
+        code: zod.z.ZodIssueCode.custom,
+        message: `Page paths must be unique. Duplicates: ${duplicatePaths.join(", ")}`,
+        path: ["pages"]
+      });
+    }
+  }
+  if (data.entries && data.entries.length > 1) {
+    const identifiers = data.entries.map((e) => e.identifier);
+    const duplicateIds = identifiers.filter((id, i) => identifiers.indexOf(id) !== i);
+    if (duplicateIds.length > 0) {
+      ctx.addIssue({
+        code: zod.z.ZodIssueCode.custom,
+        message: `Entry identifiers must be unique. Duplicates: ${duplicateIds.join(", ")}`,
+        path: ["entries"]
+      });
+    }
+  }
+  if (data.navigationMenus && data.navigationMenus.length > 1) {
+    const identifiers = data.navigationMenus.map((m) => m.identifier);
+    const duplicateIds = identifiers.filter((id, i) => identifiers.indexOf(id) !== i);
+    if (duplicateIds.length > 0) {
+      ctx.addIssue({
+        code: zod.z.ZodIssueCode.custom,
+        message: `Navigation menu identifiers must be unique. Duplicates: ${duplicateIds.join(", ")}`,
+        path: ["navigationMenus"]
+      });
+    }
+  }
+});
+
 // src/data/prefetchBlockData.ts
 var SUPPORTED_LOADER_ENDPOINTS = [
   "listPublishedEntries",
@@ -5026,7 +5232,8 @@ var riverbankSiteConfigSchema = zod.z.object({
     { message: "Block IDs must be unique" }
   ).optional(),
   blockFieldOptions: blockFieldOptionsSchema,
-  blockFieldExtensions: blockFieldExtensionsSchema
+  blockFieldExtensions: blockFieldExtensionsSchema,
+  content: contentConfigSchema.optional()
 }).strict();
 var DEFAULT_CONFIG_FILENAME = "riverbank.config.ts";
 async function loadConfigFile(configPath) {
@@ -5045,11 +5252,11 @@ Create a riverbank.config.ts file or specify a path with --config`
   });
   try {
     const configModule = await jiti$1.import(resolvedPath);
-    const config = configModule.default ?? configModule.config ?? configModule;
-    if (!config || typeof config !== "object") {
+    const config2 = configModule.default ?? configModule.config ?? configModule;
+    if (!config2 || typeof config2 !== "object") {
       throw new Error("Config file must export a configuration object");
     }
-    return config;
+    return config2;
   } catch (error) {
     if (error instanceof Error) {
       throw new Error(`Failed to load config: ${error.message}`);
@@ -5069,7 +5276,7 @@ function resolveConfigPath(configPath) {
 }
 
 // src/cli/push-config.ts
-async function pushToDashboard(dashboardUrl, siteId, apiKey, config) {
+async function pushToDashboard(dashboardUrl, siteId, apiKey, config2) {
   const pushUrl = `${dashboardUrl}/api/sites/${siteId}/sdk-config`;
   console.log(`Pushing config to ${pushUrl}...`);
   let response;
@@ -5080,7 +5287,7 @@ async function pushToDashboard(dashboardUrl, siteId, apiKey, config) {
         "Content-Type": "application/json",
         "X-API-Key": apiKey
       },
-      body: JSON.stringify({ config }),
+      body: JSON.stringify({ config: config2 }),
       signal: AbortSignal.timeout(3e4)
     });
   } catch (error) {
@@ -5150,6 +5357,8 @@ var pushConfigCommand = new commander.Command("push-config").description("Push S
 });
 
 // src/cli/index.ts
+dotenv.config({ path: ".env.local" });
+dotenv.config({ path: ".env" });
 var program = new commander.Command();
 program.name("riverbankcms").description("Builder SDK CLI tools").version("0.1.0");
 program.addCommand(pushConfigCommand);