chaingrow-blog 0.2.2 → 0.7.0

package/README.md

@@ -2,102 +2,302 @@
 
 Drop-in Next.js SDK for rendering blogs published from [ChainGrow](https://chaingrow.de).
 
+> **0.6.0 breaking change.** The high-level `<BlogIndex>` API has been simplified
+> to a single `format` prop (`'cards' | 'list' | 'bare'`). The `components`,
+> `extra`, and `cards` props are removed — for custom design, compose
+> `listBlogs()` + your own JSX directly. `createBlogPage()` factory is also
+> removed; only the zero-config `BlogPage` default export remains. The
+> standalone sitemap route handlers (`chaingrow-blog/next/sitemap`,
+> `chaingrow-blog/next/news-sitemap`, `chaingrow-blog/next/robots`) are gone —
+> use `getBlogSitemapEntries()` with Next.js's native `app/sitemap.ts` instead.
+
 - **Zero database.** Your site stores nothing — ChainGrow is the source of truth.
-- **Instant publishing.** When you press Publish in ChainGrow, the SDK's webhook handler invalidates the relevant page via `revalidateTag`. Next request serves fresh HTML.
-- **Headless-first.** The core SDK is unstyled semantic HTML. Supply your own components for any block type you want to customize.
+- **Three layouts out of the box.** Pick `cards`, `list`, or `bare` with one prop.
+- **Headless when you want it.** For full design control, skip the high-level components and compose `listBlogs()` + `<BlogDetail>` + `<BlogJsonLd>` yourself.
+- **Webhook-driven freshness.** Publish, unpublish, and delete propagate to your site instantly via the webhook handler.
 
 ## Install
 
 ```bash
+npm install chaingrow-blog
+# or
 pnpm add chaingrow-blog
 # or
-npm install chaingrow-blog
+yarn add chaingrow-blog
 ```
 
 Requires Next.js ≥ 14 (App Router) and React ≥ 18.
 
-## Setup (3 files)
+## Quickstart
 
-### 1. Environment variable
+### 1. Environment
 
 ```env
-CHAINGROW_API_KEY=ck_live_xxx
+# .env.local
+CHAINGROW_API_KEY=cg_live_xxx
+```
+
+> That's the only required variable. Generate the key in your ChainGrow dashboard under **Integrations → API Keys**. It authenticates your API calls and verifies incoming webhooks — one secret total. The webhook delivery URL is derived automatically from the website you set on your business profile; you never paste a URL anywhere.
+### 2. List page  `app/blog/page.tsx`
+
+```tsx
+import { BlogIndex } from 'chaingrow-blog/react';
+
+export default async function Page() {
+  return <BlogIndex/>;
+}
 ```
+> Default is `format="minimalist"`: a stark monochrome grid (square image, bold title, gray date) — black on white in light mode, white on black in dark mode, no borders or shadows. Pass `format="list"` for a single-column thumbnail feed, or `format="bare"` for unstyled HTML.
+### 3. Blog page `app/blog/[slug]/page.tsx`
 
-That's the only required variable. Generate the key in your ChainGrow dashboard under **Integrations → API Keys**. It authenticates your API calls AND verifies incoming webhooks, so there's only one secret to manage. The webhook delivery URL is derived automatically from the website you set on your business profile, so you never paste a URL anywhere.
+```tsx
+import { BlogPage, generateBlogPageMetadata } from 'chaingrow-blog/next';
 
-(Optional: set `CHAINGROW_API_URL` if you're pointing at staging or a self-hosted deploy. Defaults to `https://api.chaingrow.de`.)
+export const generateMetadata = generateBlogPageMetadata();
+export default BlogPage;
+```
 
-### 2. Webhook receiver
+> That's it for rendering: fetch, metadata, JSON-LD, body, 404. Typography (h1/h2/p/ul/blockquote/img/code/etc.) is styled via self-contained CSS scoped under `.cg-blog-article` — no Tailwind, no `prose`, no CSS framework needed. Light + dark mode follow `prefers-color-scheme` by default. To override styling, target the scoped classes from your own stylesheet, or skip this component entirely (see [Custom design](#custom-design) below).
 
-Mount the SDK's handler at the convention path `/api/chaingrow/webhook` — ChainGrow always POSTs to `${your-website}/api/chaingrow/webhook`:
+### 4. Webhook `app/api/chaingrow/webhook/route.ts`
 
 ```ts
-// app/api/chaingrow/webhook/route.ts
 export { POST } from 'chaingrow-blog/next/webhook';
 ```
 
-### 3. Blog page
+Webhook allows instant publish/unpublishWhen you publish, unpublish, or delete a blog in the ChainGrow dashboard, the SDK invalidates the relevant ISR cache tags and your site updates immediately. Without this file, freshness is governed by the ISR window (default 7 days) — fine for development, not great for production. The handler verifies the `X-ChainGrow-Signature` HMAC; no manual URL configuration is needed (ChainGrow derives it from your business profile's website URL).
+
+That's the whole quickstart. Three files, one env var.
+
+> **Want a custom design?** Skip the high-level components and compose the data fetchers + the headless React components yourself. See [Custom design](#custom-design) below.
+
+## Localized routes (i18n)
+
+ChainGrow publishes language variants of a post under **one shared slug** — `getBlog(slug, language)` picks the variant. If your site prefixes routes per locale (e.g. `/blog/...` for the default locale, `/en/blog/...` for others), wire the locale through in three places:
+
+### 1. Index links — cards must link to the active locale's route
 
-**Option A — Custom rendering (bring your own JSX):**
+`<BlogIndex>` defaults to `/blog/<slug>` hrefs regardless of `language`. Derive `pathPrefix` from the active locale:
 
 ```tsx
-// app/blog/[slug]/page.tsx
-import { notFound } from 'next/navigation'; // Next.js built-in — serves a real HTTP 404 and renders app/not-found.tsx
-import { getBlog } from 'chaingrow-blog/next';
+// app/[locale]/blog/page.tsx
+export default async function Page({ params }) {
+  const { locale } = await params;
+  return (
+    <BlogIndex
+      language={locale}
+      pathPrefix={locale === 'de' ? '/blog' : `/${locale}/blog`}
+    />
+  );
+}
+```
 
-export default async function BlogPage({
-  params,
-}: {
-  params: { slug: string };
-}) {
-  const blog = await getBlog(params.slug);
-  if (!blog) notFound();
+Or take full control per card with `hrefFor` (takes precedence over `pathPrefix`):
+
+```tsx
+<BlogIndex
+  language={locale}
+  hrefFor={(b) => (b.language === 'de' ? `/blog/${b.slug}` : `/${b.language}/blog/${b.slug}`)}
+/>
+```
+
+### 2. Index metadata
+
+The index page has no post to derive metadata from — without this, `/blog` falls back to your site-default title:
+
+```ts
+import { generateBlogIndexMetadata } from 'chaingrow-blog/next';
+
+export const metadata = generateBlogIndexMetadata({
+  title: 'Blog | Acme',
+  description: 'Product updates and guides from Acme.',
+  canonical: 'https://example.com/blog',
+});
+```
+
+### 3. Detail metadata — canonical + hreflang alternates
+
+Pass `alternates` and the SDK emits `alternates.canonical` plus hreflang `alternates.languages` for every published language variant of the post (it reuses the ISR-cached list response — no extra backend hit):
+
+```ts
+export const generateMetadata = generateBlogPageMetadata({
+  alternates: {
+    siteUrl: 'https://example.com',
+    pathPrefix: (lang) => (lang === 'de' ? '/blog' : `/${lang}/blog`),
+    xDefaultLanguage: 'de',
+  },
+});
+```
+
+Sitemaps: pass the same per-locale prefix to `getBlogSitemapEntries({ language, pathPrefix })` once per locale, or build from `listBlogs({ language })` yourself.
+
+## Custom design
+
+When `format="minimalist" | "list"` aren't your style, skip `<BlogIndex>` and `BlogPage` entirely and compose your own pages. Two ChainGrow primitives do the heavy lifting:
+
+- `listBlogs()` — fetch the list (ISR-cached, webhook-invalidated)
+- `getBlog(slug, language?)` — fetch one (same caching)
+
+…and three React components compose into the detail layout:
+
+- `<BlogJsonLd blog={...} extraSchemas={...}>` — emits BlogPosting + FAQPage + your extra schemas under one `@graph`
+- `<BlogDetail blog={...} components={{ Header, Footer, blocks }}>` — full article layout with overridable header, footer, and per-block renderers
+- `<BlogRenderer blog={...}>` — body blocks only (skip the article header/footer)
+
+### Customizing the list page  `app/blog/page.tsx`
+
+```tsx
+import { listBlogs } from 'chaingrow-blog/next';
+import Link from 'next/link';
+
+export default async function Page() {
+  const blogs = await listBlogs({ status: 'PUBLISHED' });
 
   return (
-    <article>
-      <h1>{blog.title}</h1>
-      {blog.blocks.map((b, i) => (
-        /* render however you want */
-        <YourCustomBlock key={i} block={b} />
-      ))}
-    </article>
+    <main className="max-w-5xl mx-auto px-6 py-24">
+      {/* ↑ optional Tailwind: max-width container, vertical padding */}
+
+      <h1 className="text-4xl font-bold mb-8">Blog</h1>
+      {/* ↑ optional Tailwind: large headline */}
+
+      <div className="grid md:grid-cols-2 lg:grid-cols-3 gap-8">
+        {/* ↑ optional Tailwind: 1 col mobile, 2 col tablet, 3 col desktop */}
+
+        {blogs.map((b) => (
+          <Link
+            key={b.id}
+            href={`/blog/${b.slug}`}
+            className="block rounded-xl border border-gray-200 hover:shadow-lg transition p-5"
+            // ↑ optional Tailwind: rounded card with hover lift
+          >
+            {b.og_image && (
+              <img
+                src={b.og_image}
+                alt={b.title}
+                className="rounded-lg mb-4 w-full aspect-video object-cover"
+              />
+            )}
+            <h2 className="font-semibold text-lg mb-2">{b.title}</h2>
+            {b.description && (
+              <p className="text-sm text-gray-600 line-clamp-3">{b.description}</p>
+            )}
+          </Link>
+        ))}
+      </div>
+    </main>
   );
 }
 ```
 
-**Option B — Default renderer with per-block overrides:**
+Every Tailwind className is annotated. Remove all `className` props for bare HTML, or replace with your own CSS / CSS modules / styled-components. You decide what each element looks like.
+
+### Customizing the blog page `app/blog/[slug]/page.tsx` 
 
 ```tsx
+import { getBlog, generateBlogMetadata } from 'chaingrow-blog/next';
+import { BlogDetail, BlogJsonLd } from 'chaingrow-blog/react';
 import { notFound } from 'next/navigation';
-import { getBlog } from 'chaingrow-blog/next';
-import { BlogRenderer } from 'chaingrow-blog/react';
 
-export default async function BlogPage({
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  return generateBlogMetadata(slug);
+}
+
+export default async function Page({
   params,
 }: {
-  params: { slug: string };
+  params: Promise<{ slug: string }>;
 }) {
-  const blog = await getBlog(params.slug);
+  const { slug } = await params;
+  const blog = await getBlog(slug);
   if (!blog) notFound();
 
   return (
-    <article className="prose">
-      <h1>{blog.title}</h1>
-      <BlogRenderer
+    <article className="prose max-w-3xl mx-auto py-16 px-6">
+      {/* ↑ optional Tailwind Typography: prose typography wrapper */}
+
+      <BlogJsonLd blog={blog} />
+
+      <BlogDetail
         blog={blog}
         components={{
-          heading: ({ level, children }) =>
-            level === 2 ? (
-              <h2 className="text-3xl font-bold">{children}</h2>
-            ) : (
-              <h3 className="text-2xl font-semibold">{children}</h3>
-            ),
-          quote: ({ children }) => (
-            <blockquote className="border-l-4 border-blue-500 pl-4 italic">
-              {children}
-            </blockquote>
+          // Override the article header (default: og_image + h1 + time + description)
+          Header: ({ blog, formatDate }) => (
+            <header className="mb-8">
+              {blog.og_image && (
+                <img
+                  src={blog.og_image}
+                  alt={blog.title}
+                  className="rounded-xl mb-6 w-full aspect-video object-cover"
+                />
+              )}
+              <h1 className="text-4xl font-bold mb-3">{blog.title}</h1>
+              {blog.published_at && (
+                <time className="text-sm text-gray-500">
+                  {formatDate(blog.published_at)}
+                </time>
+              )}
+              {blog.description && (
+                <p className="text-lg text-gray-600 mt-4">{blog.description}</p>
+              )}
+            </header>
+          ),
+
+          // Override the article footer (default: nothing). Add share buttons,
+          // related posts, comment widgets, etc.
+          Footer: ({ blog }) => (
+            <footer className="mt-12 pt-8 border-t border-gray-200 text-sm text-gray-500">
+              Published {new Date(blog.published_at).toLocaleDateString()}
+            </footer>
           ),
+
+          // Override individual block renderers — pick any subset, the rest
+          // fall through to the bare-HTML defaults.
+          blocks: {
+            heading: ({ level, children }) => {
+              if (level === 1) return <h1 className="text-3xl font-bold mt-12 mb-4">{children}</h1>;
+              if (level === 2) return <h2 className="text-2xl font-bold mt-10 mb-3">{children}</h2>;
+              return <h3 className="text-xl font-semibold mt-8 mb-2">{children}</h3>;
+            },
+            paragraph: ({ children }) => (
+              <p className="my-4 leading-relaxed">{children}</p>
+            ),
+            blockquote: ({ children }) => (
+              <blockquote className="border-l-4 border-gray-300 pl-4 italic my-6">
+                {children}
+              </blockquote>
+            ),
+            codeBlock: ({ code, language }) => (
+              <pre className="bg-gray-100 rounded-lg p-4 overflow-x-auto my-6">
+                <code className={`language-${language ?? ''}`}>{code}</code>
+              </pre>
+            ),
+            bulletList: ({ items }) => (
+              <ul className="list-disc list-inside my-4 space-y-2">
+                {items.map((item, i) => <li key={i}>{item}</li>)}
+              </ul>
+            ),
+            orderedList: ({ items }) => (
+              <ol className="list-decimal list-inside my-4 space-y-2">
+                {items.map((item, i) => <li key={i}>{item}</li>)}
+              </ol>
+            ),
+            image: ({ src, alt, caption }) => (
+              <figure className="my-8">
+                <img src={src} alt={alt} className="rounded-xl w-full" />
+                {caption && (
+                  <figcaption className="text-sm text-gray-500 text-center mt-2">
+                    {caption}
+                  </figcaption>
+                )}
+              </figure>
+            ),
+            divider: () => <hr className="my-12 border-gray-200" />,
+          },
         }}
       />
     </article>
@@ -105,142 +305,420 @@ export default async function BlogPage({
 }
 ```
 
-## API
+Every Tailwind className is optional — drop it for bare HTML, or swap for your own CSS classes. Override any subset of `Header`, `Footer`, and `blocks.*` — anything you don't override falls back to the bare-HTML defaults.
 
-### `getBlog(slug, language?, opts?)`
+### Data shapes
 
-Fetches a blog by slug (server-side, ISR-cached under tag `chaingrow:blog:<slug>`). Returns `null` if not found.
+When you're composing your own pages (or feeding ChainGrow data into your own components), these are the types you'll work with.
+
+`listBlogs()` returns `Blog[]`. `getBlog(slug, language?)` returns `Blog | null`. The `Blog` shape:
 
-### `listBlogs(opts?, clientOpts?)`
+```ts
+type Blog = {
+  id: string;
+  slug: string;
+  language: string;            // 2-letter ISO code (e.g. 'en', 'de')
+  title: string;
+  description: string | null;
+  blocks: Block[];             // structured body (see below)
+  faq: { question: string; answer: string }[];
+  og_image: string | null;     // hero image URL
+  image_url: string | null;
+  video_url: string | null;
+  video_prompt: string | null;
+  structured_data: Record<string, unknown> | null;  // LLM-generated JSON-LD extras
+  published_at: string;        // ISO 8601 timestamp
+  social_posts: {
+    provider: string;          // 'X_TWITTER' | 'LINKEDIN' | 'FACEBOOK'
+    content: string;
+    social_title: string | null;
+  }[];
+  generatedMedia?: {
+    id: string;
+    media_url: string;
+    media_type: 'IMAGE' | 'VIDEO';
+    prompt: string;
+    created_at: string;
+  }[];
+};
+```
+
+The `Block` union covers the body content and maps one-to-one with TipTap/ProseMirror nodes:
+
+```ts
+type Block =
+  | { type: 'heading'; level: 1 | 2 | 3; content: Inline[] }
+  | { type: 'paragraph'; content: Inline[] }
+  | { type: 'bulletList'; items: ListItem[] }
+  | { type: 'orderedList'; items: ListItem[] }
+  | { type: 'blockquote'; content: Inline[] }
+  | { type: 'codeBlock'; language?: string; code: string }
+  | { type: 'image'; src: string; alt: string; caption?: string;
+      width?: number; height?: number; mediaId?: string }
+  | { type: 'divider' };
+
+type Inline = { text: string; marks?: Mark[] };
+type Mark =
+  | { type: 'bold' } | { type: 'italic' } | { type: 'strike' }
+  | { type: 'code' } | { type: 'link'; href: string };
+
+type ListItem = { content: Block[] };  // items can contain nested blocks
+```
 
-Lists blogs (optionally filtered by `status` or `language`).
+If you don't want to walk the blocks yourself, render the body with `<BlogRenderer blog={blog} />` and override per-block renderers via `components.blocks` (shown above).
 
-### `createClient({ apiUrl, apiKey })`
+### Pre-existing blog at `/blog`?
 
-Framework-agnostic client. Use from edge functions, scripts, or non-Next.js environments.
+If you already serve a blog at `/blog/[slug]` from an existing CMS (MDX, WordPress, your own backend) and want to coexist, the cleanest pattern is to mount ChainGrow at a different URL:
 
-### `<BlogRenderer blog={blog} components={...} />`
+```
+/blog/[slug]      ← legacy (untouched)
+/guides/[slug]    ← ChainGrow (new) — set pathPrefix="/guides" on getBlogSitemapEntries
+```
 
-Renders all `blog.blocks` using unstyled default components. Every block type is overridable via the `components` prop — supply only the ones you want to customize.
+If you really need both sources at the same URL space, write the dual lookup yourself in `app/blog/[slug]/page.tsx`: try `getBlog(slug)` first, render via `<BlogJsonLd>` + `<BlogDetail>` if found, fall back to your legacy renderer otherwise. The SDK doesn't provide a built-in for this — the routing logic depends on your legacy data shape and that's not something we can guess.
 
-Block types: `heading`, `paragraph`, `list`, `quote`, `code`, `image_placeholder`.
+## Sitemaps
 
-### `createWebhookHandler({ apiKey?, onEvent? })`
+Sitemaps are URL-shape decisions you should own — at root (`/sitemap.xml`), at a custom path, indexed under a master sitemap, split per-locale, etc. The SDK gives you the data; you decide the structure.
 
-Returns a `{ POST }` route handler. Verifies the `X-ChainGrow-Signature` HMAC (signed server-side with `sha256(apiKey)`) and calls `revalidateTag`. Pass `onEvent` to run custom logic after revalidation (e.g. cache warming, analytics). By default reads `CHAINGROW_API_KEY` from the environment.
+### Pattern A — Next.js native `app/sitemap.ts`
 
-### Rate-limit handling
+Drop ChainGrow blogs into your existing sitemap with one line:
 
-Calls are transparently retried once on HTTP `429 Too Many Requests`, honoring the `Retry-After` header. No configuration needed. Other errors bubble up unchanged.
-
-## How publishing works
-
-```
-ChainGrow dashboard                      Your Next.js site
-───────────────────                      ─────────────────
-Press Publish
-     │
-     ▼
-blog.status = PUBLISHED
-     │
-     ▼
-HMAC-signed webhook  ──────────────►  /api/chaingrow/webhook
-                                            │
-                                            ▼
-                                      verify signature
-                                            │
-                                            ▼
-                                      revalidateTag('chaingrow:blog:<slug>')
-                                            │
-                                            ▼
-Next user request                     /blog/<slug> cache miss
-     │                                      │
-     ▼                                      ▼
-Fresh HTML                            getBlog() → GET /api/v1/blogs/by-slug/<slug>
-                                            │
-                                            ▼
-                                      cached for next visitors
+```ts
+// app/sitemap.ts
+import type { MetadataRoute } from 'next';
+import { getBlogSitemapEntries } from 'chaingrow-blog/next';
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const blogEntries = await getBlogSitemapEntries({
+    siteUrl: 'https://example.com',
+    pathPrefix: '/blog',
+  });
+
+  return [
+    { url: 'https://example.com', lastModified: new Date() },
+    { url: 'https://example.com/pricing', lastModified: new Date() },
+    ...blogEntries,
+  ];
+}
 ```
 
-## Releasing new versions (maintainers only)
+`getBlogSitemapEntries` returns `MetadataRoute.Sitemap`-shaped entries (`{ url, lastModified }`), so you spread it in. ISR-cached and webhook-invalidated automatically — same cache tags as `<BlogPage>` and `<BlogIndex>`.
 
-> Consumers installing `chaingrow-blog` can ignore this section — it's internal notes for ChainGrow maintainers cutting a new release.
+### Pattern B — merge into an existing custom sitemap route
 
-The SDK is published to npm by a GitHub Actions workflow (`.github/workflows/publish-blog-sdk.yml`). The workflow only runs when you push a **git tag** matching `blog-sdk-v*`. Regular commits and branch pushes do **nothing** — npm is never touched unless you explicitly create and push a release tag.
+If you already serve sitemaps from a route file (e.g. `/api/sitemaps/general`), call `listBlogs()` and project to whatever shape you need:
 
-### Triggers
+```ts
+import { listBlogs } from 'chaingrow-blog/next';
+
+const blogs = await listBlogs({ status: 'PUBLISHED' });
+for (const blog of blogs) {
+  yourUrlList.push({
+    loc: `https://example.com/blog/${blog.slug}`,
+    lastmod: blog.published_at,
+    changefreq: 'monthly',
+    priority: 0.7,
+  });
+}
+```
 
-```yaml
-on:
-  push:
-    tags:
-      - 'blog-sdk-v*'   # only fires on matching tags
-  workflow_dispatch:     # manual "Run workflow" button in GitHub Actions UI
+### Pattern C — news sitemap (Google News)
+
+```ts
+import { listBlogs, type Blog } from 'chaingrow-blog/next';
+import { filterRecentForNews } from 'chaingrow-blog';
+
+const blogs = await listBlogs({ status: 'PUBLISHED' });
+const recent: Blog[] = filterRecentForNews(blogs); // last 48h, max 1000
+
+// emit Google News XML using `recent`
 ```
 
-That's it. Two ways to trigger a publish:
+`filterRecentForNews` is a pure helper that filters to the last 48 hours, sorts newest first, and caps at 1000 entries (Google's spec). You emit the XML with whatever library or hand-rolled XML builder you prefer; the SDK exports `buildNewsSitemapXml()` and `escapeXml()` from the package root if you want the SDK's defaults.
 
-1. Push a tag named `blog-sdk-v<version>` (the normal flow)
-2. Click "Run workflow" on the Actions page in GitHub (manual escape hatch)
+## JSON-LD / SEO schemas
 
-No other event publishes. You can push commits to `main` all day without releasing.
+`<BlogJsonLd blog={blog} />` emits a single `<script type="application/ld+json">` containing:
 
-### Cutting a release
+- **BlogPosting** built from `blog.title`, `blog.description`, `blog.published_at`, `blog.og_image`.
+- **FAQPage** built from `blog.faq` (only when non-empty).
+- Any LLM-generated extras passed through from `blog.structured_data.jsonLd`.
 
-```bash
-# 1. Bump the version in packages/blog-sdk/package.json
-#    "version": "0.1.0"  →  "version": "0.1.1"
+All three live under one `@graph` so Google treats them as one graph. Add your own schemas (breadcrumb, `Organization`, `WebSite`) via `extraSchemas`:
 
-# 2. Commit the version bump
-git add packages/blog-sdk/package.json
-git commit -m "chore(blog-sdk): release v0.1.1"
-git push                                   # normal push, nothing publishes yet
+```tsx
+import { BlogJsonLd } from 'chaingrow-blog/react';
+
+<BlogJsonLd
+  blog={blog}
+  url={`https://mysite.com/blog/${blog.slug}`}
+  author={{ name: 'Acme Inc.', type: 'Organization' }}
+  publisher={{ name: 'Acme Inc.', logo: 'https://mysite.com/logo.png' }}
+  extraSchemas={[
+    {
+      '@type': 'BreadcrumbList',
+      itemListElement: [
+        { '@type': 'ListItem', position: 1, name: 'Home', item: 'https://mysite.com/' },
+        { '@type': 'ListItem', position: 2, name: 'Blog', item: 'https://mysite.com/blog' },
+      ],
+    },
+  ]}
+/>
+```
 
-# 3. Create the release tag on that commit
-git tag blog-sdk-v0.1.1
+Low-level builders are exported from the package root if you want to assemble schemas yourself:
 
-# 4. Push the tag (separate command — git push alone doesn't push tags)
-git push origin blog-sdk-v0.1.1            # this is what fires the workflow
+```ts
+import {
+  buildBlogPostingSchema,
+  buildFAQPageSchema,
+  buildBlogJsonLd,
+} from 'chaingrow-blog';
+import { JsonLdGraph } from 'chaingrow-blog/react';
+
+const items = [
+  myBreadcrumbSchema,
+  ...buildBlogJsonLd(blog, { url: '…', author: { name: '…' } }),
+];
+// <JsonLdGraph items={items} />
 ```
 
-About a minute later the new version lands on [npmjs.com/package/chaingrow-blog](https://www.npmjs.com/package/chaingrow-blog).
+## Media — multiple images & videos in the body
+
+When your blog has more than one attached image or video, `<BlogRenderer>` distributes them deterministically across the body so the first one lands at the top and the rest spread evenly between blocks. No configuration needed:
+
+```
+ 1 attachment  →  [media] + all blocks
+ 2 attachments →  [media] + half the blocks + [media] + the other half
+ 3 attachments →  [media] + 1/3 blocks + [media] + 1/3 blocks + [media] + 1/3 blocks
+ N attachments →  each media lands at block index floor(i * N / K)
+```
 
-### Why tags and not branches?
+The placement is pure function of `(blocks.length, generatedMedia.length)` — same input always produces the same output, so two visitors see the same layout.
 
-Tags are immutable bookmarks pointing at a specific commit, and git treats them as a separate namespace from branches. Splitting the release trigger onto tags means:
+### Customising the media slot
 
-- Normal development pushes never accidentally publish
-- Every published version has a matching tag you can `git checkout` to see exactly what was shipped
-- Cutting a release is an explicit, deliberate action (`git tag` + `git push origin <tag>`), not a side effect of merging to main
+Override the `media` component just like any other block-level override:
 
-### Versioning rules
+```tsx
+import Image from 'next/image';
+import { BlogRenderer } from 'chaingrow-blog/react';
+
+<BlogRenderer
+  blog={blog}
+  components={{
+    media: ({ media }) =>
+      media.media_type === 'VIDEO' ? (
+        <video
+          src={media.media_url}
+          controls
+          className="rounded-xl my-8 w-full aspect-video"
+        />
+      ) : (
+        <Image
+          src={media.media_url}
+          alt={media.prompt}
+          width={1200}
+          height={675}
+          className="rounded-xl my-8"
+        />
+      ),
+  }}
+/>
+```
 
-Follow [semver](https://semver.org/):
+### Getting placement without rendering
 
-| Change | Bump |
+If you need the same distribution logic for a custom layout (e.g. wrapping each section in `<section>`), reuse the utilities directly:
+
+```ts
+import { interleaveMedia, distributeMediaPositions } from 'chaingrow-blog';
+
+// Get the insertion index for each media item:
+const positions = distributeMediaPositions(blog.blocks.length, blog.generatedMedia?.length ?? 0);
+
+// Or get a flat interleaved list you can map over:
+const slots = interleaveMedia(blog.blocks, blog.generatedMedia);
+// slots: Array<{ kind: 'block', block, index } | { kind: 'media', media, index }>
+```
+
+## API reference
+
+### `chaingrow-blog/next`
+
+#### `BlogPage`
+Default-batteries `app/blog/[slug]/page.tsx` component. Re-export from your route file. Zero configuration.
+
+#### `generateBlogPageMetadata(opts?)`
+Default-batteries `generateMetadata` factory. Zero configuration; pass `{ alternates: { siteUrl, pathPrefix?, xDefaultLanguage? } }` to also emit canonical + hreflang `alternates.languages` (see [Localized routes](#localized-routes-i18n)).
+
+#### `getBlog(slug, language?, opts?)`
+Fetches a blog by slug (server-side, ISR-cached under tag `chaingrow:blog:<slug>`). Returns `null` if not found.
+
+#### `listBlogs(listOpts?, clientOpts?)`
+Lists blogs (optionally filtered by `status` or `language` — filtering happens server-side). Automatically pages through the API until the server-reported `total` is fetched, so large accounts never truncate. Cached under tag `chaingrow:blog:list`.
+
+#### `generateBlogMetadata(slug, language?, opts?)`
+Returns a Next.js `Metadata` object (title + description + openGraph + twitter). Shares the ISR cache with `getBlog`. Pass `opts.alternates` for canonical + hreflang output.
+
+#### `generateBlogIndexMetadata({ title, description?, canonical?, ogImage? })`
+Synchronous `Metadata` for the blog *index* page — title, description, canonical, openGraph (website) + twitter. Without it, `/blog` falls back to your site-default title.
+
+#### `getBlogSitemapEntries({ siteUrl, pathPrefix?, language?, ... })`
+Returns ChainGrow blog entries already shaped for `MetadataRoute.Sitemap`. Spread into your `app/sitemap.ts`.
+
+### `chaingrow-blog/next/webhook`
+
+#### `POST` (default route handler)
+Re-export from `app/api/chaingrow/webhook/route.ts` to mount the HMAC-verified handler. Invalidates ISR tags on `blog.published`, `blog.unpublished`, `blog.deleted`, `blog.created`, `blog.updated`.
+
+#### `createWebhookHandler({ apiKey?, onEvent? })`
+Returns `{ POST }` with overrides — pass an `onEvent` callback to run custom logic after revalidation.
+
+### `chaingrow-blog/react`
+
+#### `<BlogIndex format? language? pathPrefix? hrefFor? formatDate? />`
+Default list page. Calls `listBlogs()` internally and renders one of three preset layouts: `minimalist` (default), `list`, `bare`. On locale-prefixed sites set `pathPrefix` per locale, or pass `hrefFor={(blog) => string}` for full href control (see [Localized routes](#localized-routes-i18n)). For full design control, skip this and write your own page using `listBlogs()`.
+
+#### `<BlogDetail blog={} components={} formatDate={} />`
+Article layout: `<article>` → Header → `<BlogRenderer>` → Footer. Default Header: og_image → h1 → time → description. Default Footer: nothing. Override Header, Footer, and per-block renderers via `components`.
+
+#### `<BlogRenderer blog={} components={} />`
+Renders `blog.blocks` and distributes `blog.generatedMedia` across them.
+
+#### `<BlogJsonLd blog={} url? author? publisher? extraSchemas? />`
+One-liner JSON-LD: BlogPosting + FAQPage + `structured_data.jsonLd` extras, all under one `@graph`.
+
+#### `<JsonLdGraph items={} />`
+Low-level: render any array of Schema.org objects as a single `<script type="application/ld+json">`.
+
+### `chaingrow-blog` (root)
+
+#### `createClient({ apiUrl, apiKey, fetch? })`
+Framework-agnostic client. Use from edge functions, scripts, Remix, SvelteKit, etc.
+
+#### `buildBlogPostingSchema(blog, opts?)` / `buildFAQPageSchema(faq)` / `buildBlogJsonLd(blog, opts?)`
+Pure JSON-LD builders.
+
+#### `buildSitemapXml(blogs, { baseUrl, pathPrefix? })` / `buildNewsSitemapXml(blogs, { baseUrl, publicationName, ... })`
+Pure XML builders for hand-rolled sitemap routes (alternative to `app/sitemap.ts`).
+
+#### `filterRecentForNews(blogs, now?)`
+Returns blogs published in the last 48 hours, sorted newest first, capped at 1000 — input shape for `buildNewsSitemapXml`.
+
+#### `escapeXml(s)`
+Escapes the five XML special characters.
+
+#### `distributeMediaPositions(blockCount, mediaCount)` / `interleaveMedia(blocks, media)`
+Pure media-placement utilities matching `<BlogRenderer>`'s deterministic distribution.
+
+### Rate-limit handling
+Calls are transparently retried once on HTTP `429 Too Many Requests`, honoring the `Retry-After` header. No configuration needed.
+
+## Caching & revalidation
+
+`getBlog()` and `listBlogs()` run on the server and plug into Next's ISR cache. Every response is tagged (`chaingrow:blog`, `chaingrow:blog:<slug>`, `chaingrow:blog:list`) so the webhook can invalidate by slug.
+
+**Default:** `revalidate: 604800` (7 days). Blog posts are effectively immutable once published, and the webhook (if mounted) invalidates the cache the moment ChainGrow publishes — so the window is a safety net, not a freshness promise.
+
+Override per call when you need different behaviour:
+
+```ts
+// Staging / debugging — hit ChainGrow every request
+await getBlog(slug, lang, { revalidate: 0 });
+
+// Pair with the webhook route for cache-forever + instant invalidation
+await getBlog(slug, lang, { revalidate: false });
+
+// Custom window
+await getBlog(slug, lang, { revalidate: 3600 }); // 1 hour
+```
+
+| `revalidate` | Background fetches / day / slug | When this makes sense |
+|---|---|---|
+| `0` | one per request | staging, debugging |
+| `3600` (1 h) | 24 | content updates hourly, no webhook |
+| `86400` (1 day) | 1 | content updates daily, no webhook |
+| **`604800` (1 week, default)** | **0.14** | blog posts, with or without webhook |
+| `false` (forever) | 0 | paired with the webhook — invalidation only on publish |
+
+## Webhook details
+
+The webhook handler at `chaingrow-blog/next/webhook` exports a `POST` route that:
+
+1. Reads the raw request body
+2. Verifies the `X-ChainGrow-Signature` HMAC against `sha256(CHAINGROW_API_KEY)`
+3. Parses the `WebhookPayload` (type-narrowed by event)
+4. Calls `revalidateTag('chaingrow:blog')`, `revalidateTag('chaingrow:blog:list')`, and `revalidateTag('chaingrow:blog:<slug>')` for the affected blog
+5. Optionally invokes your `onEvent` callback for side effects (cache warming, analytics, etc.)
+6. Returns `200 { ok: true, revalidated: <slug> }`
+
+Events emitted by ChainGrow:
+
+| Event | When |
 |---|---|
-| Adding a new field to `Blog` (backwards-compatible) | patch (`0.1.0` → `0.1.1`) |
-| Adding a new exported function or component | minor (`0.1.0` → `0.2.0`) |
-| **Changing the `Block` type union** | **major (`0.1.0` → `1.0.0`)** — customer override maps will break |
-| Removing or renaming any exported symbol | major |
+| `blog.created` | A new blog row is created (typically before publishing) |
+| `blog.updated` | Title/body/metadata changes on an existing blog |
+| `blog.published` | Status flips to `PUBLISHED` |
+| `blog.unpublished` | Status flips back to `DRAFT` |
+| `blog.deleted` | Blog is deleted |
 
-### Fixing a mistake
+The handler invalidates cache tags on every event; that's why publish, unpublish, and delete all become visible to your visitors on the next request rather than waiting out the ISR window.
 
-If you tagged the wrong commit and it hasn't published yet:
+To run custom logic after revalidation, use the factory:
 
-```bash
-git tag -d blog-sdk-v0.1.1                      # delete local tag
-git push origin :refs/tags/blog-sdk-v0.1.1      # delete remote tag
-# then re-tag correctly
+```ts
+// app/api/chaingrow/webhook/route.ts
+import { createWebhookHandler } from 'chaingrow-blog/next/webhook';
+
+export const { POST } = createWebhookHandler({
+  onEvent: async ({ event, blog }) => {
+    console.log('chaingrow:', event, blog.slug);
+    // push to analytics, warm caches, etc.
+  },
+});
 ```
 
-If it already published: npm blocks unpublishing after 72 hours. The recipe is to deprecate the bad version and bump:
+## Releasing new versions (maintainers only)
+
+> Consumers installing `chaingrow-blog` can ignore this section — it's internal notes for ChainGrow maintainers cutting a new release.
+
+The SDK is published to npm by a GitHub Actions workflow (`.github/workflows/publish-blog-sdk.yml`). The workflow only runs when you push a **git tag** matching `blog-sdk-v*`.
+
+### Triggers
+
+```yaml
+on:
+  push:
+    tags:
+      - 'blog-sdk-v*'   # only fires on matching tags
+  workflow_dispatch:     # manual "Run workflow" button in GitHub Actions UI
+```
+
+### Cutting a release
 
 ```bash
-npm deprecate chaingrow-blog@0.1.1 "published in error — use 0.1.2"
-# then cut a fresh release with the fix
+# 1. Bump the version in packages/blog-sdk/package.json
+# 2. Commit the version bump and push
+# 3. Create + push the release tag:
+git tag blog-sdk-v0.6.0
+git push origin blog-sdk-v0.6.0
 ```
 
+About a minute later the new version lands on [npmjs.com/package/chaingrow-blog](https://www.npmjs.com/package/chaingrow-blog).
+
+### Versioning rules
+
+| Change | Bump |
+|---|---|
+| Adding a new field to `Blog` (backwards-compatible) | patch |
+| Adding a new exported function or component | minor |
+| Removing or renaming any exported symbol | minor (pre-1.0) / major (post-1.0) |
+| Changing the `Block` type union | major |
+
 ## License
 
 MIT