# @riverbankcms/sdk

A lightweight TypeScript SDK for consuming Riverbank CMS content in React Server Components, Next.js, and client-side React applications.

## Features

- ✅ **Server-side rendering** with `loadPage()` helper
- ✅ **Unified content fetching** with `loadContent()` for pages and entries
- ✅ **Client-side data fetching** with `usePage()` and `useContent()` hooks
- ✅ **Automatic data prefetching** for blocks with loaders
- ✅ **Custom block data loaders** - Config-based (CMS endpoints) and code-based (external APIs)
- ✅ **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

```bash
npm install @riverbankcms/sdk
# or
pnpm add @riverbankcms/sdk
```

## Quick Start

> **Important:** The `baseUrl` parameter must be the complete API URL including the `/api` path. For example: `https://dashboard.example.com/api`

### Server-Side Rendering (Recommended)

Use in Next.js App Router Server Components or getServerSideProps:

```tsx
import { createRiverbankClient, loadPage, Page } from '@riverbankcms/sdk';

// Note: baseUrl must include the /api path
const client = createRiverbankClient({
  apiKey: process.env.RIVERBANK_API_KEY!,
  baseUrl: process.env.NEXT_PUBLIC_DASHBOARD_URL + '/api',
});

export default async function HomePage() {
  // Fetch all page data (site, page, block data) in parallel
  const pageData = await loadPage({
    client,
    siteId: 'your-site-id',
    path: '/',
  });

  return <Page {...pageData} />;
}
```

### Client-Side Rendering

For client-only React apps or Client Components:

```tsx
"use client";

import { createRiverbankClient } from '@riverbankcms/sdk';
import { usePage, Page } from '@riverbankcms/sdk/client';

const client = createRiverbankClient({
  apiKey: process.env.NEXT_PUBLIC_RIVERBANK_API_KEY!,
  baseUrl: process.env.NEXT_PUBLIC_DASHBOARD_URL + '/api',
});

export function DynamicPage({ path }: { path: string }) {
  const pageData = usePage({ client, siteId: 'your-site-id', path });

  if (pageData.loading) return <div>Loading...</div>;
  if (pageData.error) return <div>Error: {pageData.error.message}</div>;

  return <Page {...pageData} />;
}
```

## API Reference

### Configuration

```ts
const client = createRiverbankClient({
  apiKey: string;        // Required: Builder API key
  baseUrl: string;       // Required: Full API URL (e.g., 'https://dashboard.example.com/api')
  cache?: {
    enabled?: boolean;   // Default: true
    ttl?: number;        // Default: 300 (seconds)
    maxSize?: number;    // Default: 100
  };
});
```

### Server-Side API

```tsx
import { loadPage, Page } from '@riverbankcms/sdk';

// Fetch all page data
const pageData = await loadPage({
  client,
  siteId: string,
  path: string,
  preview?: boolean,           // Default: false - set true for draft content
  pageId?: string,             // Optional: explicit page ID
  dataLoaderOverrides?: {      // Optional: code-based data loaders for custom blocks
    'custom.block-id': {
      loaderKey: async (ctx) => fetchData(ctx.content.fieldValue),
    },
  },
});

// Render the page
<Page {...pageData} />
```

### Preview Mode (Draft Content)

The SDK supports fetching draft/unpublished content by passing `preview: true`. This requires an API key with site access.

**Server-Side Preview:**

```tsx
// app/preview/[[...slug]]/page.tsx
import { createRiverbankClient, loadPage, Page } from '@riverbankcms/sdk';

const client = createRiverbankClient({
  apiKey: process.env.RIVERBANK_API_KEY!,
  baseUrl: process.env.NEXT_PUBLIC_DASHBOARD_URL + '/api',
});

export default async function PreviewPage({ params, searchParams }) {
  const pageData = await loadPage({
    client,
    siteId: searchParams.siteId,
    path: `/${params.slug?.join('/') || ''}`,
    preview: true, // 🔑 Fetch draft content
  });

  return (
    <div>
      <div className="preview-banner">Preview Mode - Draft Content</div>
      <Page {...pageData} />
    </div>
  );
}
```

**Client-Side Preview:**

```tsx
"use client";

import { createRiverbankClient } from '@riverbankcms/sdk';
import { usePage, Page } from '@riverbankcms/sdk/client';

const client = createRiverbankClient({
  apiKey: process.env.NEXT_PUBLIC_RIVERBANK_API_KEY!,
  baseUrl: process.env.NEXT_PUBLIC_DASHBOARD_URL + '/api',
});

export function PreviewPage({ siteId, path }: { siteId: string; path: string }) {
  const pageData = usePage({
    client,
    siteId,
    path,
    preview: true, // 🔑 Fetch draft content
  });

  if (pageData.loading) return <div>Loading preview...</div>;
  if (pageData.error) return <div>Error: {pageData.error.message}</div>;

  return <Page {...pageData} />;
}
```

**How Preview Works:**

- ✅ Uses your existing API key (no separate preview tokens needed)
- ✅ Returns draft content for blocks (via `draftContent` field)
- ✅ Shows unpublished pages that are in draft state
- ✅ Published and preview content are cached separately
- ✅ Requires API key to be scoped to the site

**Use Cases:**

- Preview pages before publishing
- Share draft content with stakeholders
- Test content changes in staging environment
- Content editing workflows

### Client-Side API

```tsx
import { usePage, Page } from '@riverbankcms/sdk/client';

const pageData = usePage({
  client,
  siteId: string,
  path: string,
  preview?: boolean,  // Default: false - set true for draft content
  pageId?: string,
});

// pageData is a discriminated union:
// { loading: true, error: null, ... } |
// { loading: false, error: Error, ... } |
// { loading: false, error: null, page, theme, ... }
```

## Unified Content Loading (Pages + Entries)

When a path might resolve to either a page or a content entry (blog post, product, etc.), use `loadContent()` or `useContent()` instead of the page-specific functions.

### Server-Side: loadContent

```tsx
import { loadContent, isPageContent, Page } from '@riverbankcms/sdk';

export default async function DynamicRoute({ params }) {
  const path = `/${params.slug?.join('/') || ''}`;

  const content = await loadContent({
    client,
    siteId: 'your-site-id',
    path,
    preview: false, // Set true for draft content
  });

  // Pages get rendered with the Page component
  if (isPageContent(content)) {
    return <Page {...content} />;
  }

  // Entries get rendered with custom UI
  return (
    <article>
      <h1>{content.entry.title}</h1>
      <div>{JSON.stringify(content.entry.content)}</div>
    </article>
  );
}
```

### Client-Side: useContent

```tsx
"use client";

import { useContent, isPageContentResult, Page } from '@riverbankcms/sdk/client';

export function DynamicContent({ path }: { path: string }) {
  const content = useContent({
    client,
    siteId: 'your-site-id',
    path,
    preview: false,
  });

  if (content.loading) return <div>Loading...</div>;
  if (content.error) return <div>Error: {content.error.message}</div>;

  if (isPageContentResult(content)) {
    return <Page page={content.page} theme={content.theme} siteId={content.siteId} resolvedData={content.resolvedData} />;
  }

  // Render entry with custom UI
  return (
    <article>
      <h1>{content.entry.title}</h1>
      <p>Type: {content.entry.type}</p>
      <div>{JSON.stringify(content.entry.content)}</div>
    </article>
  );
}
```

### Entry-Specific Rendering

Route entries to different components based on their content type:

```tsx
import { loadContent, isPageContent, Page } from '@riverbankcms/sdk';

export default async function DynamicRoute({ params }) {
  const content = await loadContent({ client, siteId, path: `/${params.slug?.join('/') || ''}` });

  if (isPageContent(content)) {
    return <Page {...content} />;
  }

  // Route to type-specific components
  switch (content.entry.type) {
    case 'blog-post':
      return <BlogPost entry={content.entry} theme={content.theme} />;
    case 'product':
      return <ProductPage entry={content.entry} theme={content.theme} />;
    case 'event':
      return <EventPage entry={content.entry} theme={content.theme} />;
    default:
      return <GenericEntry entry={content.entry} />;
  }
}

function BlogPost({ entry, theme }) {
  const { title, content, metaDescription } = entry;
  return (
    <article>
      <h1>{title}</h1>
      <p className="lead">{metaDescription}</p>
      <div className="prose">{content.body}</div>
      <p>By {content.author} on {new Date(entry.createdAt).toLocaleDateString()}</p>
    </article>
  );
}
```

### ContentEntryData Type

When working with entries, you receive raw content data:

```ts
type ContentEntryData = {
  id: string;
  type: string | null;        // Content type key (e.g., 'blog-post', 'product')
  title: string;
  slug: string | null;
  path: string | null;
  status: string;
  publishAt: string | null;
  content: Record<string, unknown>;  // Raw content fields
  metaTitle: string | null;
  metaDescription: string | null;
  createdAt: string;
  updatedAt: string;
};
```

### When to Use Which Function

| Function | Use Case |
|----------|----------|
| `loadPage()` / `usePage()` | Pages only - throws error on entries |
| `loadContent()` / `useContent()` | Both pages and entries - discriminated union |

## Fetching Multiple Entries

Use `client.getEntries()` to fetch lists of content entries for blog listing pages, product catalogs, etc.

### Basic Usage

```tsx
import { createRiverbankClient } from '@riverbankcms/sdk';

const client = createRiverbankClient({
  apiKey: process.env.RIVERBANK_API_KEY!,
  baseUrl: process.env.NEXT_PUBLIC_DASHBOARD_URL + '/api',
});

// Fetch all published blog posts
const { entries } = await client.getEntries({
  siteId: 'your-site-id',
  contentType: 'blog-post',
});
```

### Pagination and Sorting

```tsx
// Fetch latest 10 posts (newest first)
const { entries: latestPosts } = await client.getEntries({
  siteId: 'your-site-id',
  contentType: 'blog-post',
  limit: 10,
  order: 'newest',
});

// Fetch oldest posts first (for archives)
const { entries: archivedPosts } = await client.getEntries({
  siteId: 'your-site-id',
  contentType: 'blog-post',
  order: 'oldest',
});

// Include draft entries for preview mode
const { entries: allPosts } = await client.getEntries({
  siteId: 'your-site-id',
  contentType: 'blog-post',
  preview: true, // Includes unpublished drafts
});
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `siteId` | string | Yes | Site ID |
| `contentType` | string | Yes | Content type key (e.g., 'blog-post') |
| `limit` | number | No | Maximum entries to return |
| `order` | 'newest' \| 'oldest' | No | Sort by publish date |
| `preview` | boolean | No | Include draft entries |

### Real-World Example: Blog Listing Page

```tsx
// app/blog/page.tsx
import { createRiverbankClient } from '@riverbankcms/sdk';
import Link from 'next/link';

const client = createRiverbankClient({
  apiKey: process.env.RIVERBANK_API_KEY!,
  baseUrl: process.env.NEXT_PUBLIC_DASHBOARD_URL + '/api',
});

export default async function BlogPage() {
  const site = await client.getSite({ slug: 'my-site' });

  const { entries: posts } = await client.getEntries({
    siteId: site.site.id,
    contentType: 'blog-post',
    limit: 10,
    order: 'newest',
  });

  return (
    <main>
      <h1>Blog</h1>
      <div className="grid gap-6">
        {posts.map((post) => (
          <article key={post.id}>
            <Link href={`/blog/${post.slug}`}>
              <h2>{post.title}</h2>
            </Link>
            <p>{post.metaDescription}</p>
            <time>{post.publishedAt ? new Date(post.publishedAt).toLocaleDateString() : 'Draft'}</time>
          </article>
        ))}
      </div>
    </main>
  );
}
```

## Import Patterns

⚠️ **Important:** Use the correct import path for your environment:

```tsx
// ✅ Server Components (Next.js App Router)
import { createRiverbankClient, loadPage, Page } from '@riverbankcms/sdk';

// ✅ Client Components (use "use client" directive)
"use client";
import { usePage, Page } from '@riverbankcms/sdk/client';
```

The `/client` subpath exports React hooks that require client-side React features (useState, useEffect). The main entry point only exports server-safe code.

## Layout Component

The `Layout` component renders the site header, footer, and wraps your page content. Use this when you want consistent site chrome across all pages.

### Using Layout with Pre-Fetched Site Data

When you already have site data (from `loadPage` or `client.getSite`):

```tsx
import { Layout } from '@riverbankcms/sdk';

export default async function MyPage() {
  const siteData = await client.getSite({ slug: 'my-site' });

  return (
    <Layout siteData={siteData}>
      <main>
        <h1>My Custom Page</h1>
        <p>This content is wrapped with site header and footer.</p>
      </main>
    </Layout>
  );
}
```

### Automatic Site Fetching

Layout can fetch site data automatically if you provide a client and identifier:

```tsx
import { Layout } from '@riverbankcms/sdk';

export default async function MyPage() {
  return (
    <Layout
      client={client}
      slug="my-site"  // or siteId="..." or domain="example.com"
    >
      <main>
        <h1>My Custom Page</h1>
      </main>
    </Layout>
  );
}
```

### Customizing Header and Footer

You can hide the header or footer:

```tsx
<Layout
  siteData={siteData}
  header={false}  // Hide header
  footer={false}  // Hide footer
>
  <main>Landing page without navigation</main>
</Layout>
```

### Choosing Header Variants

Override the header variant from your code:

```tsx
<Layout
  siteData={siteData}
  headerVariant="centered"  // Options: classic, centered, transparent, floating, editorial
>
  <main>Content with centered header</main>
</Layout>
```

### Fully Custom Headers

Create your own header while using CMS navigation data:

```tsx
import { Layout, type HeaderData } from '@riverbankcms/sdk';

function CustomHeader({ menu, logo, site }: HeaderData) {
  return (
    <header className="custom-header">
      <a href="/">{logo?.url && <img src={logo.url} alt={site.title} />}</a>
      <nav>
        {menu.items.map(item => (
          <a key={item.id} href={item.url.href}>{item.label}</a>
        ))}
      </nav>
    </header>
  );
}

export default async function MyPage() {
  const siteData = await client.getSite({ slug: 'my-site' });

  return (
    <Layout
      siteData={siteData}
      header={(data) => <CustomHeader {...data} />}
    >
      <main>Custom header with CMS navigation</main>
    </Layout>
  );
}
```

## Block Component

The `Block` component renders individual CMS blocks. Use this when you want to mix CMS content with custom JSX, or render blocks outside of a full page context.

### Basic Block Rendering

```tsx
import { Block } from '@riverbankcms/sdk';

export default async function CustomPage() {
  const siteData = await client.getSite({ slug: 'my-site' });

  return (
    <div>
      <h1>Custom Header</h1>

      {/* Render a CMS block inline */}
      <Block
        blockKind="block.hero"
        content={{
          headline: 'Welcome',
          subheadline: 'To our custom page',
          cta: { label: 'Get Started', href: '/signup' }
        }}
        theme={siteData.theme}
        siteId={siteData.site.id}
      />

      <p>More custom content...</p>
    </div>
  );
}
```

### Block with Data Loading

Blocks can automatically load their data (e.g., blog posts, products) if they have data loaders configured:

```tsx
<Block
  blockKind="block.blog-listing"
  blockId="block-abc123"  // Block ID enables data loading
  content={{ maxPosts: 10 }}
  theme={siteData.theme}
  siteId={siteData.site.id}
  pageId={page.id}         // Optional: for context-aware loaders
  client={client}          // Required for data loading
/>
```

### Advanced Block Options

```tsx
<Block
  blockKind="block.hero"
  blockId="block-xyz"
  content={{ heading: 'Welcome' }}
  theme={theme}
  siteId="site-123"

  // Optional data loading context
  pageId="page-456"
  previewStage="preview"  // or "published"
  client={client}

  // Show placeholder data for missing loaders
  usePlaceholders={true}
/>
```

## Metadata Generation

Generate SEO-optimized metadata for Next.js pages from Riverbank CMS data.

### Basic Usage

```tsx
import { generatePageMetadata } from '@riverbankcms/sdk/metadata';
import { loadPage } from '@riverbankcms/sdk';

export async function generateMetadata({ params }) {
  const pageData = await loadPage({ client, siteId, path: params.slug });
  const siteData = await client.getSite({ id: siteId });

  return generatePageMetadata({
    page: pageData.page,
    site: siteData.site,
    path: params.slug || '/',
    siteUrl: process.env.NEXT_PUBLIC_SITE_URL!,
  });
}
```

### With Custom Overrides

```tsx
const metadata = generatePageMetadata({
  page: pageData.page,
  site: siteData.site,
  path: '/',
  siteUrl: 'https://example.com',
  overrides: {
    title: 'Custom SEO Title',
    description: 'Custom SEO description with keywords',
    ogImage: 'https://example.com/og-image.jpg',
    canonicalUrl: 'https://example.com/canonical-path',
  },
  googleSiteVerification: 'verification-token',
});
```

### Preview Environment Metadata

```tsx
import { generatePreviewMetadata } from '@riverbankcms/sdk/metadata';

// Adds noindex/nofollow for staging environments
const metadata = generatePreviewMetadata({
  page: pageData.page,
  site: siteData.site,
  path: '/',
  siteUrl: 'https://preview.example.com',
});
```

## Route Resolution

Resolve URL paths to pages, redirects, or 404s for dynamic routing.

### Single Route Resolution

```tsx
import { resolveRoute } from '@riverbankcms/sdk/routing';
import { notFound, redirect } from 'next/navigation';

export default async function DynamicPage({ params }) {
  const path = `/${params.slug?.join('/') || ''}`;

  const resolution = await resolveRoute({
    client,
    siteId: 'your-site-id',
    path,
  });

  if (resolution.type === 'redirect') {
    redirect(resolution.destination);
  }

  if (resolution.type === 'not-found') {
    notFound();
  }

  return <Page {...resolution.pageData} />;
}
```

### Batch Route Resolution

```tsx
import { resolveRoutes } from '@riverbankcms/sdk/routing';

// Useful for sitemap generation or validation
const resolutions = await resolveRoutes({
  client,
  siteId: 'your-site-id',
  paths: ['/', '/about', '/services', '/contact'],
});

resolutions.forEach(({ path, resolution }) => {
  if (resolution.type === 'page') {
    console.log(`${path} → Page: ${resolution.pageData.page.name}`);
  } else if (resolution.type === 'redirect') {
    console.log(`${path} → Redirect to ${resolution.destination}`);
  } else {
    console.log(`${path} → Not found`);
  }
});
```

## Analytics

Track page views, CTA clicks, form submissions, and custom events.

### Add Analytics to Layout

```tsx
import { AnalyticsBootstrap } from '@riverbankcms/sdk/analytics';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}

        {/* Auto-tracks page views on navigation */}
        <AnalyticsBootstrap
          siteId="your-site-id"
          siteSlug="your-site-slug"
          endpoint="/api/analytics/collect"
        />
      </body>
    </html>
  );
}
```

### Track Events in Components

```tsx
'use client';

import { useAnalytics } from '@riverbankcms/sdk/analytics';

export function MyComponent() {
  const analytics = useAnalytics({
    siteId: 'your-site-id',
    siteSlug: 'your-site-slug',
  });

  const handleClick = () => {
    analytics.trackCtaClick({ buttonLabel: 'Sign Up' });
  };

  const handleSubmit = () => {
    analytics.trackFormSubmit({ formName: 'contact-form' });
  };

  const handleCustomEvent = () => {
    analytics.trackEvent({
      eventType: 'video_play',
      metadata: { videoId: '123', duration: 120 },
    });
  };

  return (
    <>
      <button onClick={handleClick}>Sign Up</button>
      <form onSubmit={handleSubmit}>...</form>
    </>
  );
}
```

## Theming

Style Builder blocks to match your brand using the Theme Bridge. This provides CSS variables and optional component styles without requiring the full CMS theme system.

### Quick Start

Wrap your app with `ThemeBridgeProvider` and define your color tokens:

```tsx
import { ThemeBridgeProvider } from '@riverbankcms/sdk/theme-bridge';

export default function RootLayout({ children }) {
  return (
    <ThemeBridgeProvider
      config={{
        tokens: {
          primary: '#6d28d9',
          secondary: '#4c1d95',
          background: '#ffffff',
          text: '#1e293b',
        },
      }}
    >
      {children}
    </ThemeBridgeProvider>
  );
}
```

### Token System

Define color tokens as key-value pairs. Keys become CSS variables (`--color-{key}`):

```tsx
<ThemeBridgeProvider
  config={{
    tokens: {
      // Brand colors
      primary: '#6d28d9',
      secondary: '#4c1d95',

      // Backgrounds
      background: '#ffffff',
      surface: '#f8fafc',

      // Text
      text: '#1e293b',
      mutedText: '#64748b',

      // UI
      border: '#e2e8f0',
      white: '#ffffff',

      // Status
      success: '#22c55e',
      warning: '#f59e0b',
      danger: '#ef4444',
    },
  }}
>
```

Token values can be:
- **Hex colors**: `'#6d28d9'` (converted to RGB for Tailwind alpha support)
- **CSS variable refs**: `'var(--brand-purple)'` (passed through)
- **RGB values**: `'109 40 217'` (used directly)

### Design Presets

Control typography, spacing, corners, and shadows:

```tsx
<ThemeBridgeProvider
  config={{
    tokens: { /* ... */ },

    // Typography
    typography: {
      headingFamily: '"Inter", sans-serif',
      bodyFamily: '"Inter", sans-serif',
      headingWeight: 700,
      bodyWeight: 400,
    },

    // Spacing density
    spacing: 'standard',  // 'comfortable' | 'standard' | 'dense'

    // Corner radius
    corners: 'rounded',   // 'square' | 'soft' | 'rounded' | 'pill'

    // Shadow intensity
    shadows: 'medium',    // 'none' | 'low' | 'medium' | 'high'
  }}
>
```

### Component CSS (Opt-in)

By default, only CSS variables are generated. Enable component CSS for buttons, cards, and inputs:

```tsx
<ThemeBridgeProvider
  config={{
    tokens: {
      primary: '#6d28d9',
      secondary: '#4c1d95',
      white: '#ffffff',
      surface: '#f8fafc',
      text: '#1e293b',
      border: '#e2e8f0',
    },
    corners: 'rounded',
    shadows: 'medium',
    components: {
      buttons: true,  // Generates .button-primary, .button-secondary, etc.
      cards: true,    // Generates .card-default, .card-elevated, etc.
      inputs: true,   // Generates .form-input, .form-label, etc.
    },
  }}
>
```

### Custom Component Variants

Specify which variants to generate:

```tsx
components: {
  buttons: {
    variants: ['primary', 'secondary'],  // Only these variants
  },
  cards: {
    variants: ['default', 'elevated'],
  },
}
```

### CSS Overrides

Add custom CSS rules scoped to theme components:

```tsx
<ThemeBridgeProvider
  config={{
    tokens: { /* ... */ },
    components: { buttons: true },
    overrides: {
      '.button-primary': 'border-radius: 9999px; font-weight: 700;',
      '.button-primary:hover': 'transform: translateY(-2px);',
    },
  }}
>
```

### Pass-Through to Design Systems

Reference existing CSS variables from your design system:

```tsx
<ThemeBridgeProvider
  config={{
    tokens: {
      primary: 'var(--brand-purple)',
      secondary: 'var(--brand-navy)',
      background: 'var(--ds-bg)',
      text: 'var(--ds-text)',
    },
    components: { buttons: true },
  }}
>
```

### Using Generated CSS Directly

For advanced use cases, generate CSS without the provider:

```tsx
import { generateThemeBridgeCss } from '@riverbankcms/sdk/theme-bridge';

const { css, cssVars } = generateThemeBridgeCss({
  tokens: {
    primary: '#6d28d9',
    background: '#ffffff',
  },
  components: { buttons: true },
});

// css: Full CSS string for injection
// cssVars: Object of CSS variable name-value pairs
```

### Available Exports

```tsx
import {
  // Provider component
  ThemeBridgeProvider,
  useThemeBridgeCss,

  // CSS generator
  generateThemeBridgeCss,

  // Types
  type ThemeBridgeConfig,
  type ThemeBridgeTypography,
  type ThemeBridgeSpacing,
  type ThemeBridgeCorners,
  type ThemeBridgeShadows,
  type ThemeBridgeComponents,
  type ThemeBridgeOutput,
} from '@riverbankcms/sdk/theme-bridge';
```

## Block Field Options

Customize field options for specific blocks directly in your SDK configuration. This allows SDK sites to define site-specific choices for select fields in system blocks.

### Basic Configuration

Add `blockFieldOptions` to your `riverbank.config.ts`:

```typescript
import { defineConfig } from '@riverbankcms/sdk/config';

export default defineConfig({
  siteId: 'your-site-id',
  blockFieldOptions: {
    'block.embed': {
      layout: {
        options: [
          { value: 'showcase', label: 'Showcase Grid' },
          { value: 'list', label: 'Simple List' },
          { value: 'featured', label: 'Featured Hero' },
        ]
      }
    }
  }
});
```

### How It Works

1. **Block ID format**: Use `block.*` for system blocks or `custom.*` for custom blocks
2. **Field ID**: The field within the block whose options you want to override
3. **Options**: Array of `{ value, label }` objects that replace the default options

When a block field uses the `sdkSelect` widget (like the embed block's `layout` field), it will:
- Use SDK-provided options when available in `blockFieldOptions`
- Fall back to the field's default options if no SDK options are configured

### Types

```typescript
import type {
  FieldSelectOption,
  BlockFieldConfig,
  BlockFieldOptionsMap,
} from '@riverbankcms/sdk/config';

// A single select option
type FieldSelectOption = {
  value: string;  // Value stored when selected
  label: string;  // Display text in dropdown
};

// Configuration for a field
type BlockFieldConfig = {
  options?: FieldSelectOption[];  // Override select options
};

// Map of block IDs to field configurations
type BlockFieldOptionsMap = Record<string, Record<string, BlockFieldConfig>>;
```

### Current Use Cases

**Embed Block Layout**: The `block.embed` block uses `sdkSelect` for its `layout` field, allowing SDK sites to define custom layout options that match their site-specific renderers:

```typescript
export default defineConfig({
  siteId: 'your-site-id',
  blockFieldOptions: {
    'block.embed': {
      layout: {
        options: [
          { value: 'blog-grid', label: 'Blog Grid' },
          { value: 'team-cards', label: 'Team Cards' },
          { value: 'portfolio', label: 'Portfolio Gallery' },
        ]
      }
    }
  }
});
```

Then in your block override, handle each layout:

```tsx
function EmbedRenderer({ content, data }) {
  switch (content.layout) {
    case 'blog-grid':
      return <BlogGrid entries={data.entries} />;
    case 'team-cards':
      return <TeamCards entries={data.entries} />;
    case 'portfolio':
      return <PortfolioGallery entries={data.entries} />;
    default:
      return <DefaultList entries={data.entries} />;
  }
}
```

### Validation Rules

- Block IDs must match pattern: `block.*` or `custom.*` (lowercase letters, numbers, hyphens)
- Field IDs must be non-empty strings
- Each option must have both `value` and `label` (non-empty strings)
- At least one option is required when `options` is specified

## Block Field Extensions

Add custom fields to built-in block types without modifying the core CMS. This is different from `blockFieldOptions` (which overrides options for existing fields) – `blockFieldExtensions` lets you add entirely new fields.

### Basic Configuration

Add `blockFieldExtensions` to your `riverbank.config.ts`:

```typescript
import { defineConfig } from '@riverbankcms/sdk/config';

export default defineConfig({
  siteId: 'your-site-id',
  blockFieldExtensions: {
    'block.body-text': {
      fields: [
        {
          id: 'layout',
          type: 'select',
          label: 'Layout',
          defaultValue: 'default',
          required: false,
          multiple: false,
          options: [
            { value: 'default', label: 'Default' },
            { value: 'wide', label: 'Wide' },
            { value: 'narrow', label: 'Narrow' },
            { value: 'pullquote', label: 'Pull Quote' },
          ],
        },
      ],
    },
    'block.hero': {
      fields: [
        {
          id: 'videoBackground',
          type: 'media',
          label: 'Video Background',
          description: 'Optional video to play behind the hero',
          mediaKinds: ['video'],
          required: false,
        },
        {
          id: 'overlayOpacity',
          type: 'number',
          label: 'Overlay Opacity',
          description: 'Darkness of the overlay (0-100)',
          defaultValue: 50,
          required: false,
        },
      ],
    },
  },
});
```

### How It Works

1. **Extended fields appear at the end** of the block's editing form in the CMS
2. **Field values are stored** alongside normal block content
3. **Values are accessible** in your `blockOverrides` via the `content` prop
4. **All field types supported**: text, select, media, repeater, group, etc.

### Accessing Extended Fields in blockOverrides

```tsx
import { loadPage, Page } from '@riverbankcms/sdk';

export default async function CMSPage({ params }) {
  const pageData = await loadPage({ client, siteId, path: '/' });

  return (
    <Page
      {...pageData}
      blockOverrides={{
        bodyText: ({ content }) => {
          // Extended field values are available on content
          const layout = content.layout ?? 'default';

          const layoutClass = {
            default: 'max-w-prose mx-auto',
            wide: 'max-w-4xl mx-auto',
            narrow: 'max-w-md mx-auto',
            pullquote: 'max-w-lg mx-auto text-xl italic border-l-4 pl-6',
          }[layout];

          return (
            <div className={layoutClass}>
              <RichText content={content.body} />
            </div>
          );
        },
        hero: ({ content }) => {
          const { videoBackground, overlayOpacity = 50 } = content;

          return (
            <div className="relative">
              {videoBackground && (
                <video
                  src={videoBackground.url}
                  className="absolute inset-0 w-full h-full object-cover"
                  autoPlay
                  muted
                  loop
                />
              )}
              <div
                className="absolute inset-0 bg-black"
                style={{ opacity: overlayOpacity / 100 }}
              />
              <div className="relative z-10">
                <h1>{content.headline}</h1>
              </div>
            </div>
          );
        },
      }}
    />
  );
}
```

### Types

```typescript
import type {
  BlockFieldExtension,
  BlockFieldExtensionsMap,
  FieldDefinition,
} from '@riverbankcms/sdk/config';

// Configuration for extending a single block
type BlockFieldExtension = {
  fields: FieldDefinition[];  // Same field format as block manifests
};

// Map of block IDs to their extensions
type BlockFieldExtensionsMap = Record<string, BlockFieldExtension>;
```

### Validation Rules

- **Block IDs must be system blocks**: Only `block.*` format (e.g., `block.body-text`, `block.hero`). Custom blocks (`custom.*`) should define their fields directly in `customBlocks`.
- **Field IDs must be unique**: Extended field IDs cannot conflict with existing fields in the block. The CLI will error if you try to add a field with an ID that already exists.
- **Required fields need defaultValue**: If `required: true`, you must provide a `defaultValue`. This ensures existing blocks (created before the extension) can still be edited.
- **At least one field required**: Each block extension must have at least one field.

### Use Cases

**Layout variations for text blocks:**
```typescript
'block.body-text': {
  fields: [
    {
      id: 'layout',
      type: 'select',
      label: 'Layout',
      defaultValue: 'default',
      required: false,
      multiple: false,
      options: [
        { value: 'default', label: 'Default' },
        { value: 'wide', label: 'Wide' },
        { value: 'sidebar', label: 'With Sidebar' },
      ],
    },
  ],
}
```

**Custom styling options:**
```typescript
'block.hero': {
  fields: [
    {
      id: 'textAlignment',
      type: 'select',
      label: 'Text Alignment',
      defaultValue: 'center',
      required: false,
      multiple: false,
      options: [
        { value: 'left', label: 'Left' },
        { value: 'center', label: 'Center' },
        { value: 'right', label: 'Right' },
      ],
    },
    {
      id: 'showBreadcrumbs',
      type: 'boolean',
      label: 'Show Breadcrumbs',
      defaultValue: false,
      required: false,
    },
  ],
}
```

**Adding metadata fields:**
```typescript
'block.blog-listing': {
  fields: [
    {
      id: 'analyticsId',
      type: 'text',
      label: 'Analytics ID',
      description: 'Track this specific listing in analytics',
      required: false,
      multiline: false,
    },
  ],
}
```

### Comparison: blockFieldOptions vs blockFieldExtensions

| Feature | `blockFieldOptions` | `blockFieldExtensions` |
|---------|---------------------|------------------------|
| Purpose | Override options for existing select fields | Add new fields to blocks |
| Supports | Select field options only | All field types |
| Use case | Customize dropdown choices | Add new data fields |
| Block types | System and custom blocks | System blocks only |

Use **both together** for maximum customization:

```typescript
export default defineConfig({
  siteId: 'your-site-id',

  // Override options for existing fields
  blockFieldOptions: {
    'block.embed': {
      layout: {
        options: [
          { value: 'blog-grid', label: 'Blog Grid' },
          { value: 'team-cards', label: 'Team Cards' },
        ],
      },
    },
  },

  // Add new fields to blocks
  blockFieldExtensions: {
    'block.body-text': {
      fields: [
        {
          id: 'layout',
          type: 'select',
          label: 'Layout',
          defaultValue: 'default',
          required: false,
          multiple: false,
          options: [
            { value: 'default', label: 'Default' },
            { value: 'wide', label: 'Wide' },
          ],
        },
      ],
    },
  },
});
```

## Custom Blocks

Define site-specific blocks directly in your SDK configuration. Custom blocks appear in the CMS block picker alongside system blocks, are edited using CMS-generated forms, and are rendered by your own React components.

### Quick Start

1. **Define the block schema** in your `riverbank.config.ts`:

```typescript
import { defineConfig } from '@riverbankcms/sdk/config';

export default defineConfig({
  siteId: 'your-site-id',
  customBlocks: [
    {
      id: 'custom.team-member',
      title: 'Team Member',
      titleSource: 'name',
      description: 'Display a team member with photo and bio',
      category: 'content',
      icon: 'User',
      tags: ['team', 'about'],
      fields: [
        { id: 'name', type: 'text', label: 'Name', required: true, multiline: false },
        { id: 'role', type: 'text', label: 'Role', required: false, multiline: false },
        { id: 'photo', type: 'media', label: 'Photo', required: false, mediaKinds: ['image'] },
        { id: 'bio', type: 'richText', label: 'Bio', required: false },
      ],
    },
  ],
});
```

2. **Create your component** to render the block:

```tsx
// components/blocks/TeamMember.tsx
import type { SystemBlockComponentProps } from '@riverbankcms/blocks';

type TeamMemberContent = {
  name: string;
  role?: string;
  photo?: { url: string; alt?: string };
  bio?: string;
};

export function TeamMember({ content }: SystemBlockComponentProps<TeamMemberContent>) {
  return (
    <div className="flex items-start gap-6 p-6">
      {content.photo && (
        <img
          src={content.photo.url}
          alt={content.photo.alt || content.name}
          className="h-24 w-24 rounded-full object-cover"
        />
      )}
      <div>
        <h3 className="text-xl font-bold">{content.name}</h3>
        {content.role && <p className="text-gray-600">{content.role}</p>}
        {content.bio && (
          <div className="mt-2 prose" dangerouslySetInnerHTML={{ __html: content.bio }} />
        )}
      </div>
    </div>
  );
}
```

3. **Register the component** with `blockOverrides`:

```tsx
// app/[...slug]/page.tsx
import { loadPage, Page } from '@riverbankcms/sdk';
import { TeamMember } from '@/components/blocks/TeamMember';

export default async function CMSPage({ params }) {
  const pageData = await loadPage({
    client,
    siteId: process.env.SITE_ID!,
    path: `/${params.slug?.join('/') || ''}`,
  });

  return (
    <Page
      {...pageData}
      blockOverrides={{
        'custom.team-member': TeamMember,
      }}
    />
  );
}
```

### Block Definition Schema

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | `custom.${string}` | Yes | Unique block ID, must start with `custom.` |
| `title` | `string` | Yes | Display name in block picker |
| `titleSource` | `string` | No | Field ID to use as block title in lists |
| `description` | `string` | No | Description shown in block picker |
| `category` | `BlockCategory` | Yes | One of: `marketing`, `content`, `blog`, `media`, `layout`, `interactive` |
| `icon` | `string` | No | Lucide icon name (e.g., `User`, `CreditCard`) |
| `tags` | `string[]` | No | Search tags for discoverability |
| `fields` | `FieldDefinition[]` | Yes | Field definitions for the block |

### Supported Field Types

All field types from the CMS are supported:

**Basic Types:**
- `text` - Single or multiline text
- `richText` - Rich text editor with formatting
- `number` - Numeric input
- `boolean` - Toggle/checkbox

**Media & Links:**
- `media` - Image, video, or file upload
- `url` - URL input with validation
- `link` - Internal or external link picker

**Selection:**
- `select` - Dropdown selection
- `reference` - Reference to other content entries

**Date/Time:**
- `date` - Date picker
- `time` - Time picker
- `datetime` - Combined date and time

**Complex Types:**
- `group` - Group related fields together
- `repeater` - Repeatable list of items
- `modal` - Fields in a modal dialog
- `tabGroup` - Tabbed field groups

### Examples

**Pricing Card:**

```typescript
{
  id: 'custom.pricing-card',
  title: 'Pricing Card',
  titleSource: 'planName',
  category: 'marketing',
  icon: 'CreditCard',
  fields: [
    { id: 'planName', type: 'text', label: 'Plan Name', required: true, multiline: false },
    { id: 'price', type: 'text', label: 'Price', required: false, multiline: false, description: 'e.g., "$29/mo"' },
    { id: 'featured', type: 'boolean', label: 'Featured Plan', required: false },
    {
      id: 'features',
      type: 'repeater',
      label: 'Features',
      required: false,
      itemLabel: 'Feature',
      maxItems: 10,
      fields: [
        { id: 'text', type: 'text', label: 'Feature', required: true, multiline: false },
        { id: 'included', type: 'boolean', label: 'Included', required: false },
      ],
    },
    { id: 'ctaLabel', type: 'text', label: 'Button Label', required: false, multiline: false },
    { id: 'ctaLink', type: 'link', label: 'Button Link', required: false },
  ],
}
```

**Testimonial:**

```typescript
{
  id: 'custom.testimonial',
  title: 'Testimonial',
  titleSource: 'authorName',
  category: 'content',
  icon: 'Quote',
  fields: [
    { id: 'quote', type: 'richText', label: 'Quote', required: true },
    { id: 'authorName', type: 'text', label: 'Author Name', required: true, multiline: false },
    { id: 'authorTitle', type: 'text', label: 'Author Title', required: false, multiline: false },
    { id: 'authorPhoto', type: 'media', label: 'Author Photo', required: false, mediaKinds: ['image'] },
    { id: 'companyLogo', type: 'media', label: 'Company Logo', required: false, mediaKinds: ['image'] },
    { id: 'rating', type: 'number', label: 'Rating (1-5)', required: false },
  ],
}
```

### Validation Rules

- Maximum 20 custom blocks per site
- Block IDs must be unique within the site
- Block IDs must start with `custom.` followed by lowercase letters, numbers, or hyphens
- `titleSource` must reference a valid field ID if provided
- At least one field is required per block
- Maximum 5 data loaders per block

### Best Practices

1. **Use descriptive IDs**: `custom.team-member` is better than `custom.tm`
2. **Set `titleSource`**: Helps editors identify blocks in the page structure
3. **Add descriptions**: Help editors understand when to use each block
4. **Group related fields**: Use `group` for related fields that should appear together
5. **Validate required fields**: Mark essential fields as `required: true`
6. **Provide defaults**: Use `defaultValue` for optional fields with sensible defaults

## Custom Block Data Loaders

Custom blocks can fetch data automatically using data loaders. There are two approaches:

1. **Config-based loaders** - Declarative loaders defined in `riverbank.config.ts` for whitelisted CMS endpoints
2. **Code-based loaders** - Functions passed to `loadPage()` for external APIs

Both loader types run server-side during `loadPage()`. Data is passed to your component via the `data` prop.

### Config-Based Loaders (CMS Endpoints)

Define loaders declaratively in your block definition. These are restricted to whitelisted CMS endpoints for security.

**Supported Endpoints:**

| Endpoint | Description |
|----------|-------------|
| `listPublishedEntries` | Fetch published content entries |
| `getPublishedEntryPreview` | Fetch a single entry by slug |
| `listPublicEvents` | Fetch events |
| `getPublicFormById` | Fetch form configuration |
| `getPublicBookingServices` | Fetch booking services |

**Parameter Bindings:**

Loader params can be static values or dynamic bindings:

- `{ $bind: { from: 'content.fieldName' } }` - Bind to a block field value
- `{ $bind: { from: 'content.fieldName', fallback: '10' } }` - With fallback
- `{ $bind: { from: '$root.siteId' } }` - Bind to site ID from page context
- `{ $bind: { from: '$root.pageId' } }` - Bind to page ID
- `{ $bind: { from: '$root.previewStage' } }` - 'published' or 'preview'

**Example: Blog Listing Block**

```typescript
// riverbank.config.ts
import { defineConfig } from '@riverbankcms/sdk/config';

export default defineConfig({
  siteId: 'your-site-id',
  customBlocks: [
    {
      id: 'custom.featured-posts',
      title: 'Featured Posts',
      category: 'blog',
      icon: 'FileText',
      fields: [
        { id: 'limit', type: 'number', label: 'Number of posts', required: false },
        { id: 'category', type: 'text', label: 'Category filter', required: false, multiline: false },
      ],
      dataLoaders: {
        posts: {
          endpoint: 'listPublishedEntries',
          params: {
            siteId: { $bind: { from: '$root.siteId' } },
            type: 'blog-post',
            limit: { $bind: { from: 'content.limit', fallback: '10' } },
          },
        },
      },
    },
  ],
});
```

```tsx
// components/blocks/FeaturedPosts.tsx
import type { SystemBlockComponentProps } from '@riverbankcms/blocks';

type FeaturedPostsContent = {
  limit?: number;
  category?: string;
};

type FeaturedPostsData = {
  posts: { entries: Array<{ id: string; title: string; slug: string }> };
};

export function FeaturedPosts({
  content,
  data,
}: SystemBlockComponentProps<FeaturedPostsContent, FeaturedPostsData>) {
  const posts = data?.posts?.entries ?? [];

  return (
    <div className="grid gap-4">
      {posts.map((post) => (
        <article key={post.id}>
          <a href={`/blog/${post.slug}`}>
            <h3>{post.title}</h3>
          </a>
        </article>
      ))}
    </div>
  );
}
```

### Code-Based Loaders (External APIs)

For data from external APIs, pass loader functions to `loadPage()`. This gives you full control over the fetch logic.

**Example: E-commerce Product Block**

```typescript
// app/[...slug]/page.tsx
import { loadPage, Page } from '@riverbankcms/sdk';
import { FeaturedProducts } from '@/components/blocks/FeaturedProducts';

export default async function CMSPage({ params }) {
  const pageData = await loadPage({
    client,
    siteId: process.env.SITE_ID!,
    path: `/${params.slug?.join('/') || ''}`,
    dataLoaderOverrides: {
      'custom.featured-products': {
        products: async (ctx) => {
          // Access block content for parameters
          const categoryId = ctx.content.categoryId as string;
          const limit = (ctx.content.limit as number) ?? 10;

          const res = await fetch(
            `https://api.shop.com/products?category=${categoryId}&limit=${limit}`,
            { headers: { 'Authorization': `Bearer ${process.env.SHOP_API_KEY}` } }
          );

          return res.json();
        },
      },
    },
  });

  return (
    <Page
      {...pageData}
      blockOverrides={{
        'custom.featured-products': FeaturedProducts,
      }}
    />
  );
}
```

```tsx
// components/blocks/FeaturedProducts.tsx
import type { SystemBlockComponentProps } from '@riverbankcms/blocks';

type ProductsContent = {
  categoryId: string;
  limit?: number;
};

type ProductsData = {
  products: Array<{ id: string; name: string; price: number; image: string }>;
};

export function FeaturedProducts({
  content,
  data,
}: SystemBlockComponentProps<ProductsContent, ProductsData>) {
  const products = data?.products ?? [];

  return (
    <div className="grid grid-cols-3 gap-6">
      {products.map((product) => (
        <div key={product.id} className="border rounded p-4">
          <img src={product.image} alt={product.name} />
          <h3>{product.name}</h3>
          <p>${product.price}</p>
        </div>
      ))}
    </div>
  );
}
```

### DataLoaderContext

Code-based loaders receive context about the block and page:

```typescript
interface DataLoaderContext {
  /** Site ID from page context */
  siteId: string;

  /** Page ID from page context */
  pageId: string;

  /** Unique block instance ID */
  blockId: string;

  /** Block kind (e.g., 'custom.featured-products') */
  blockKind: string;

  /** The block's CMS content (field values) */
  content: Record<string, unknown>;

  /** Whether fetching preview/draft content */
  previewStage: 'published' | 'preview';
}
```

### Combining Config and Code Loaders

You can use both loader types together. Config loaders run first, then code loaders. On key conflicts, code loaders take precedence.

```typescript
// riverbank.config.ts - Config loader for CMS data
customBlocks: [{
  id: 'custom.product-showcase',
  dataLoaders: {
    relatedPosts: {
      endpoint: 'listPublishedEntries',
      params: {
        siteId: { $bind: { from: '$root.siteId' } },
        type: 'blog-post',
        limit: '3',
      },
    },
  },
}]

// page.tsx - Code loader for external API
const pageData = await loadPage({
  client,
  siteId,
  path: '/',
  dataLoaderOverrides: {
    'custom.product-showcase': {
      products: async (ctx) => fetchProductsFromShopify(ctx.content.collectionId),
    },
  },
});

// Component receives both: data.relatedPosts (CMS) and data.products (Shopify)
```

### Error Handling

Data loaders are best-effort. If a loader fails:

- The error is logged to console
- The loader key is undefined in the `data` prop
- Other loaders continue executing
- Your component should handle missing data gracefully

```tsx
function MyBlock({ data }: SystemBlockComponentProps<Content, Data>) {
  // Handle missing data
  const products = data?.products ?? [];

  if (products.length === 0) {
    return <p>No products available</p>;
  }

  return <ProductGrid products={products} />;
}
```

### Data Exports

Import data utilities from `@riverbankcms/sdk/data`:

```typescript
import {
  // Core prefetch function
  prefetchBlockData,

  // Code loader execution
  executeCodeLoaders,
  mergeLoaderResults,

  // Types
  type DataLoaderContext,
  type DataLoaderFn,
  type BlockLoaderMap,
  type DataLoaderOverrides,
  type PrefetchContext,
  type ResolvedBlockData,
  type SdkPrefetchOptions,
} 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
- `@riverbankcms/sdk/theme` - Theme utilities
- `@riverbankcms/sdk/theme-bridge` - Simplified theming for SDK sites
- `@riverbankcms/sdk/hooks` - (Deprecated: use `/client` instead)
- `@riverbankcms/sdk/data` - Data prefetching utilities
- `@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`, `defineContentConfig`, `RiverbankSiteConfig`, `ContentConfig`, etc.)
