@sprintup-cms/sdk 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to `@sprintup-cms/sdk` will be documented here.
 
+## [1.2.0] — 2026-03-05
+
+### Fixed
+- `POST` revalidate handler no longer returns `400` for `structure.update` events (which
+  carry no `slug`). It now returns 400 only when both `tag` and `slug` are absent.
+- `slug` is now derived from `data.slug` or the `tag` prefix (`content-home` → `home`)
+  so content events work even when the top-level `slug` field is not present.
+- `structure.update` events now correctly call `revalidatePath('/', 'layout')` so
+  nav and footer refresh after a site structure change.
+- `RevalidatePayload` type updated to include all CMS event names (`content.publish`,
+  `content.unpublish`, `structure.update`) in addition to the legacy names.
+
+## [1.1.0] — 2026-03-05
+
+### Added
+- `getSitemap()` — all published page URLs with priority, changefreq, lastmod for `app/sitemap.ts`
+- `getStatus()` — connectivity check returning page counts; always fresh (`cache: 'no-store'`)
+- `CMSBlocksProps.custom` — override or extend any built-in block type with a custom React component
+- `CMSSitemapResponse`, `CMSSitemapUrl`, `CMSStatusResponse` types exported
+- `rendererKey` and `variant` fields on `CMSPageType`
+- `createRevalidateHandler` `onRevalidate` callback for post-revalidation hooks
+- Root `"."` export now resolves the `src/index.ts` barrel; new `"./client"` subpath added
+
+### Changed
+- `CMSListResponse` corrected to flat `{ data, count }` shape (was `{ data, meta: { total } }`)
+- `block.data` is now canonical; `block.content` kept as legacy fallback in all renderers
+- Config resolved lazily at request time — no more build-time crashes when env vars are absent
+
+### Fixed
+- Removed `require('./page-type-renderers')` CommonJS call that broke ES module consumers
+- Removed non-existent `getPageTypes()` list method (no list endpoint exists in the v1 API)
+- Internal link anchor regex now handles multi-segment slugs and all quote styles
+
 ## [1.0.0] — 2026-03-03
 
 ### Added

package/README.md

@@ -4,155 +4,445 @@ Official SDK for **SprintUp Forge CMS** — typed API client, Next.js App Router
 
 ---
 
+## Table of contents
+
+1. [Install](#install)
+2. [Environment variables](#environment-variables)
+3. [Initial setup](#initial-setup)
+   - [Connect to the CMS](#connect-to-the-cms)
+   - [Catch-all page route](#catch-all-page-route)
+   - [On-demand revalidation webhook](#on-demand-revalidation-webhook)
+   - [Preview mode exit](#preview-mode-exit)
+   - [Sitemap](#sitemap)
+4. [Verify your connection](#verify-your-connection)
+5. [Adding new pages](#adding-new-pages)
+6. [Custom page layouts](#custom-page-layouts)
+7. [Navigation and footer](#navigation-and-footer)
+8. [Extending with custom blocks](#extending-with-custom-blocks)
+9. [ISR and caching strategy](#isr-and-caching-strategy)
+10. [API reference](#api-reference)
+11. [Block types reference](#block-types-reference)
+12. [Troubleshooting](#troubleshooting)
+
+---
+
 ## Install
 
 ```bash
 npm install @sprintup-cms/sdk
+# or
+pnpm add @sprintup-cms/sdk
+# or
+yarn add @sprintup-cms/sdk
 ```
 
 ---
 
-## Quick start
-
-### 1. Environment variables
+## Environment variables
 
-Add to your school website's `.env.local`:
+Add the following to your website's `.env.local`. **Never commit these to git.**
 
 ```env
+# ── Required ──────────────────────────────────────────────────────────────────
+# Base URL of your SprintUp Forge CMS deployment
 NEXT_PUBLIC_CMS_URL=https://your-cms.vercel.app
+
+# API key from CMS Admin → Settings → API Keys → Create key
 CMS_API_KEY=cmsk_xxxxxxxxxxxxxxxxxxxx
+
+# App ID from CMS Admin → Settings → Apps
+# (shown in the URL when you select a site: /admin/dashboard?app=school-website)
 CMS_APP_ID=school-website
+
+# ── Required for webhooks ──────────────────────────────────────────────────────
+# Secret that the CMS will send with every webhook request — validate on your end
 CMS_WEBHOOK_SECRET=your-random-secret
+
+# ── Optional ──────────────────────────────────────────────────────────────────
+# Public URL of this website — used by sitemap generation
+NEXT_PUBLIC_SITE_URL=https://www.yourschool.edu
 ```
 
-Generate a webhook secret with:
+Generate a secure webhook secret:
 
 ```bash
 openssl rand -hex 32
 ```
 
+**Where to find your values in the CMS:**
+
+| Variable | Location in CMS Admin |
+|---|---|
+| `NEXT_PUBLIC_CMS_URL` | The domain your CMS is deployed to |
+| `CMS_API_KEY` | Settings → API Keys → Create new key |
+| `CMS_APP_ID` | Settings → Apps → click your site → copy App ID |
+| `CMS_WEBHOOK_SECRET` | Settings → Webhooks → add secret when registering the URL |
+
+---
+
+## Initial setup
+
+### Connect to the CMS
+
+The SDK reads your environment variables automatically. No extra configuration is required for the default singleton client.
+
+```ts
+// lib/cms.ts
+import { cmsClient } from '@sprintup-cms/sdk'
+export default cmsClient
+```
+
+For multiple sites or custom configuration:
+
+```ts
+import { createCMSClient } from '@sprintup-cms/sdk'
+
+export const schoolCms = createCMSClient({
+  baseUrl: process.env.NEXT_PUBLIC_CMS_URL,
+  apiKey:  process.env.CMS_API_KEY,
+  appId:   process.env.CMS_APP_ID,
+})
+```
+
 ---
 
-### 2. Catch-all CMS page
+### Catch-all page route
 
-Create `app/[...slug]/page.tsx`:
+This single file automatically renders **every page** published in your CMS — no manual routing needed.
 
 ```ts
+// app/[...slug]/page.tsx
 export { CMSCatchAllPage as default, generateMetadata } from '@sprintup-cms/sdk/next'
 ```
 
-That's it. Every page published in the CMS will be automatically rendered.
+How it works:
+- Fetches the page by `slug` from the CMS on each request (ISR, 60s revalidation).
+- Falls through to `notFound()` when the slug does not exist in the CMS.
+- Activates draft/preview mode automatically when `draftMode()` is enabled.
+- Renders `<CMSBlocks>` for standard pages and structured content for page-type pages.
 
 ---
 
-### 3. On-demand revalidation webhook
+### On-demand revalidation webhook
 
-Create `app/api/cms-revalidate/route.ts`:
+When an editor publishes or updates a page in the CMS, this webhook fires to instantly clear the ISR cache for that page.
 
 ```ts
+// app/api/cms-revalidate/route.ts
 export { POST } from '@sprintup-cms/sdk/next'
 ```
 
-Then set the webhook URL in your CMS App Settings to:
+Then register the webhook in your **CMS Admin → Settings → Webhooks**:
 
 ```
-https://your-school-site.vercel.app/api/cms-revalidate
+URL:    https://www.yourschool.edu/api/cms-revalidate
+Secret: (same value as CMS_WEBHOOK_SECRET)
+Events: published, deleted, archived
 ```
 
----
+Custom hook with extra logic:
 
-### 4. Preview exit
+```ts
+// app/api/cms-revalidate/route.ts
+import { createRevalidateHandler } from '@sprintup-cms/sdk/next'
+
+export const POST = createRevalidateHandler({
+  secret: process.env.CMS_WEBHOOK_SECRET,
+  onRevalidate: async ({ slug, event }) => {
+    console.log(`CMS revalidated /${slug} — event: ${event}`)
+    // e.g. update a search index, notify Slack, etc.
+  },
+})
+```
 
-Create `app/api/cms-preview/exit/route.ts`:
+---
+
+### Preview  mode exit
 
 ```ts
+// app/api/cms-preview/exit/route.ts
 export { previewExitGET as GET } from '@sprintup-cms/sdk/next'
 ```
 
----
+The CMS editor links to `/api/cms-preview/exit?redirect=/your-slug` to leave draft mode. This handler disables `draftMode()` and redirects the editor back to the live page.
 
-## Manual usage
+---
 
-### Core client
+### Sitemap
 
 ```ts
+// app/sitemap.ts
+import type { MetadataRoute } from 'next'
 import { cmsClient } from '@sprintup-cms/sdk'
 
-// Get a single page by slug
-const page = await cmsClient.getPage('about')
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const data = await cmsClient.getSitemap()
+  if (!data?.enabled) return []
 
-// Get all blog posts
-const posts = await cmsClient.getBlogPosts()
-
-// Get site structure (nav, footer)
-const structure = await cmsClient.getSiteStructure()
+  return data.urls.map(url => ({
+    url:             `${process.env.NEXT_PUBLIC_SITE_URL}${url.loc}`,
+    lastModified:    url.lastmod,
+    changeFrequency: url.changefreq as MetadataRoute.Sitemap[0]['changeFrequency'],
+    priority:        url.priority,
+  }))
+}
 ```
 
-### Custom client instance
+---
+
+## Verify your connection
+
+Add a temporary status check page to confirm your API key and App ID are working:
 
 ```ts
-import { createCMSClient } from '@sprintup-cms/sdk'
+// app/cms-status/page.tsx  (remove before going to production)
+import { cmsClient } from '@sprintup-cms/sdk'
 
-const cms = createCMSClient({
-  baseUrl: 'https://your-cms.vercel.app',
-  apiKey:  'cmsk_xxxx',
-  appId:   'school-website',
-})
+export default async function CmsStatusPage() {
+  const status = await cmsClient.getStatus()
+  if (!status) return <p>CMS connection failed — check your environment variables.</p>
+
+  return (
+    <div style={{ padding: 32, fontFamily: 'monospace' }}>
+      <h1>CMS Status</h1>
+      <p>App ID: {status.appId}</p>
+      <p>Total pages: {status.totalPages}</p>
+      <p>Published: {status.publishedPages}</p>
+      <pre>{JSON.stringify(status.pages.slice(0, 5), null, 2)}</pre>
+    </div>
+  )
+}
+```
+
+---
+
+## Adding new pages
+
+You **never write code** to add a new page. All content management happens in the CMS:
+
+1. Go to **CMS Admin → Content** (scoped to your site).
+2. Click **New Page**.
+3. Choose a page type (e.g. Standard Page, Blog Post, Event).
+4. Fill in the title, slug, and content blocks.
+5. Click **Publish**.
+6. The webhook fires, your Next.js site revalidates within seconds, and the page is live at `https://yoursite.com/<slug>`.
+
+To add a **custom page type** (e.g. Programme, Staff Profile):
+
+1. Go to **CMS Admin → Page Types**.
+2. Click **New Page Type**.
+3. Define sections and fields.
+4. Create content using that type.
+5. In your website, customize the rendering — see [Custom page layouts](#custom-page-layouts).
+
+---
+
+## Custom page layouts
+
+Override the default rendering for a specific page type by wrapping `CMSCatchAllPage`:
+
+```tsx
+// app/[...slug]/page.tsx
+import { notFound } from 'next/navigation'
+import { cmsClient } from '@sprintup-cms/sdk'
+import { CMSBlocks } from '@sprintup-cms/sdk/react'
+import type { Metadata } from 'next'
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string[] }> }): Promise<Metadata> {
+  const { slug } = await params
+  const page = await cmsClient.getPage(slug.join('/'))
+  if (!page) return { title: 'Not Found' }
+  return {
+    title:       page.seo?.title       || page.title,
+    description: page.seo?.description || '',
+  }
+}
+
+export default async function Page({ params }: { params: Promise<{ slug: string[] }> }) {
+  const { slug } = await params
+  const page = await cmsClient.getPage(slug.join('/'))
+  if (!page) notFound()
+
+  // Render a blog post with a custom layout
+  if (page.pageType === 'blog-post') {
+    return (
+      <article className="max-w-2xl mx-auto py-16 px-6">
+        <h1 className="text-4xl font-bold">{page.title}</h1>
+        <time className="text-sm text-gray-500">{page.publishedAt}</time>
+        <CMSBlocks blocks={page.blocks} />
+      </article>
+    )
+  }
+
+  // Fall back to default layout for all other page types
+  return (
+    <main className="max-w-5xl mx-auto py-12 px-6">
+      <h1 className="text-4xl font-bold mb-8">{page.title}</h1>
+      <CMSBlocks blocks={page.blocks} />
+    </main>
+  )
+}
 ```
 
-### React block renderer
+---
+
+## Navigation and footer
+
+Pull live nav and footer data from the CMS site structure:
 
 ```tsx
-import { CMSBlocks, CMSPreviewBanner } from '@sprintup-cms/sdk/react'
+// components/layout/header.tsx
+import { cmsClient } from '@sprintup-cms/sdk'
+import type { CMSMenuItem } from '@sprintup-cms/sdk'
+import Link from 'next/link'
+
+export async function Header() {
+  const structure = await cmsClient.getSiteStructure()
+  const navItems: CMSMenuItem[] = structure?.menus.header ?? []
 
-export default function Page({ page, pageType, isPreview }) {
   return (
-    <>
-      <CMSPreviewBanner isPreview={isPreview} status={page.status} slug={page.slug} />
-      <CMSBlocks
-        blocks={page.blocks}
-        pageType={pageType}
-        // Override any block type with your own component:
-        custom={{
-          'my-hero': (block) => <MyHeroComponent {...block.data} />,
-        }}
-      />
-    </>
+    <header className="border-b">
+      <nav className="max-w-5xl mx-auto px-6 py-4 flex gap-6">
+        {navItems.map(item => (
+          <Link key={item.id} href={item.href} target={item.openInNewTab ? '_blank' : undefined}>
+            {item.label}
+          </Link>
+        ))}
+      </nav>
+    </header>
+  )
+}
+```
+
+```tsx
+// app/layout.tsx
+import { Header } from '@/components/layout/header'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Header />
+        {children}
+      </body>
+    </html>
   )
 }
 ```
 
 ---
 
-## Supported block types
+## Extending with custom blocks
 
-| Type | Description |
+Override any built-in block or add a completely new block type using the `custom` prop:
+
+```tsx
+import { CMSBlocks } from '@sprintup-cms/sdk/react'
+import { MyVideoPlayer } from '@/components/video-player'
+import { ProgrammeCard } from '@/components/programme-card'
+
+<CMSBlocks
+  blocks={page.blocks}
+  custom={{
+    // Override built-in video block with your own player
+    'video': (block) => <MyVideoPlayer src={block.data?.url} />,
+
+    // Add a completely custom block type created in the CMS
+    'programme-card': (block) => (
+      <ProgrammeCard
+        title={block.data?.title}
+        duration={block.data?.duration}
+        applyUrl={block.data?.applyUrl}
+      />
+    ),
+  }}
+/>
+```
+
+The `custom` prop is a `Record<blockType, (block: CMSBlock) => React.ReactNode>`. It takes priority over all built-in renderers.
+
+---
+
+## ISR and caching strategy
+
+| Data | Revalidation | Cache tag |
+|---|---|---|
+| Individual page | 60 seconds | `cms-page-{slug}` |
+| All pages list | 60 seconds | `cms-pages-{appId}` |
+| Page type schema | 3600 seconds | `cms-page-type-{id}` |
+| Site structure (nav/footer) | 300 seconds | `site-structure-{appId}` |
+| Sitemap | 3600 seconds | — |
+| Status check | No cache | — |
+
+The revalidation webhook calls `revalidateTag('cms-page-{slug}')` and `revalidatePath('/{slug}')` when the CMS publishes a page, giving you **instant updates** without a full rebuild.
+
+---
+
+## API reference
+
+### `cmsClient`
+
+| Method | Description |
 |---|---|
-| `heading` | H1–H4 heading |
-| `text` | Plain paragraph |
-| `richtext` | HTML rich text (rendered with `prose`) |
-| `image` | Image with optional caption |
-| `hero` / `hero-section` | Hero with title, subtitle, CTA buttons |
-| `cta` | Call-to-action section |
-| `faq` | Accordion FAQ list |
-| `stats` | Stats grid |
-| `testimonial` | Quote card with author |
-| `quote` | Blockquote |
-| `alert` | Info / success / warning / error banner |
-| `divider` | Horizontal rule |
-| `spacer` | Vertical spacing (sm/md/lg/xl) |
-| `video` | YouTube / Vimeo embed |
-| *(any page type section)* | Rendered as labelled fields from schema |
-
----
-
-## Entry points
-
-| Import | Contents |
+| `getPage(slug)` | Fetch a single published page by slug |
+| `getPages(options?)` | Fetch multiple pages — filterable by `type`, `group`, `page`, `perPage` |
+| `getBlogPosts()` | Shorthand for `getPages({ type: 'blog-post' })` |
+| `getEvents()` | Shorthand for `getPages({ type: 'event-page' })` |
+| `getAnnouncements()` | Shorthand for `getPages({ type: 'announcement-page' })` |
+| `getPageType(id)` | Fetch a page type schema by ID |
+| `getSiteStructure()` | Fetch nav, footer, and page tree |
+| `getPreviewPage(token)` | Fetch a draft page for preview mode |
+| `getPageWithPreview(slug, token?)` | Fetch page — preview if token present, live otherwise |
+| `getSitemap()` | Fetch all published slugs with sitemap metadata |
+| `getStatus()` | Connectivity check — returns counts and page list |
+
+---
+
+## Block types reference
+
+| Block type | Key fields in `block.data` |
 |---|---|
-| `@sprintup-cms/sdk` | Typed client, all interfaces |
-| `@sprintup-cms/sdk/next` | `CMSCatchAllPage`, `POST` revalidate, `previewExitGET` |
-| `@sprintup-cms/sdk/react` | `CMSBlocks`, `CMSPreviewBanner` |
+| `heading` | `text`, `level` (1–4) |
+| `text` | `text` |
+| `richtext` | `content` (HTML string) |
+| `image` | `src`, `alt`, `caption` |
+| `hero` | `title`, `subtitle`, `primaryButton`, `primaryUrl`, `secondaryButton`, `secondaryUrl`, `badge` |
+| `cta` | `title`, `subtitle`, `primaryButton`, `primaryUrl`, `secondaryButton`, `secondaryUrl` |
+| `faq` | `title`, `items[]` — each `{ question, answer }` |
+| `stats` | `items[]` — each `{ value, label, description }` |
+| `testimonial` | `quote`, `author`, `role`, `avatar` |
+| `quote` | `quote`, `author`, `source` |
+| `alert` | `message`, `type` (info/success/warning/error) |
+| `divider` | — |
+| `spacer` | `size` (sm/md/lg/xl) |
+| `video` | `url` (YouTube or Vimeo), `title`, `autoplay` |
+
+---
+
+## Troubleshooting
+
+**Pages return empty (`getPage` returns `null`)**
+
+- Check `CMS_APP_ID` matches exactly what is shown in CMS Admin → Apps.
+- Verify the page status is **Published** (not Draft).
+- Confirm the API key has `read` permission for the app.
+
+**`getStatus()` returns `null`**
+
+- All three env vars (`NEXT_PUBLIC_CMS_URL`, `CMS_API_KEY`, `CMS_APP_ID`) must be set.
+- The CMS URL must not have a trailing slash.
+- Test the API key directly: `curl -H "X-CMS-API-Key: cmsk_xxx" https://your-cms.vercel.app/api/v1/school-website/status`
+
+**Webhook not firing / pages stale**
+
+- Confirm the webhook URL is registered in CMS Admin → Settings → Webhooks.
+- `CMS_WEBHOOK_SECRET` on both sides must match exactly.
+- Check your deployment logs for `[sprintup-cms] revalidate error:` messages.
+
+**Preview mode not working**
+
+- The `/api/cms-preview/exit` route must exist.
+- `draftMode()` requires a Next.js App Router project (not Pages Router).
 
 ---
 

package/dist/client.cjs

@@ -110,31 +110,31 @@ function createCMSClient(options) {
       return null;
     }
   }
-  async function getPageTypes() {
+  async function getSiteStructure() {
     const { baseUrl, apiKey, appId } = cfg();
-    if (!baseUrl || !apiKey || !appId) return [];
+    if (!baseUrl || !apiKey || !appId) return null;
     try {
-      const res = await fetch(`${baseUrl}/api/v1/${appId}/page-types`, {
+      const res = await fetch(`${baseUrl}/api/v1/${appId}/site-structure`, {
         headers: headers(),
-        next: { revalidate: 3600, tags: [`cms-page-types-${appId}`] }
+        next: {
+          revalidate: 300,
+          tags: [`site-structure-${appId}`]
+        }
       });
-      if (!res.ok) return [];
+      if (!res.ok) return null;
       const json = await res.json();
-      return json.data ?? [];
+      return json.data ?? null;
     } catch {
-      return [];
+      return null;
     }
   }
-  async function getSiteStructure() {
+  async function getSitemap() {
     const { baseUrl, apiKey, appId } = cfg();
     if (!baseUrl || !apiKey || !appId) return null;
     try {
-      const res = await fetch(`${baseUrl}/api/v1/${appId}/site-structure`, {
+      const res = await fetch(`${baseUrl}/api/v1/${appId}/sitemap`, {
         headers: headers(),
-        next: {
-          revalidate: 300,
-          tags: [`site-structure-${appId}`]
-        }
+        next: { revalidate: 3600 }
       });
       if (!res.ok) return null;
       const json = await res.json();
@@ -143,6 +143,20 @@ function createCMSClient(options) {
       return null;
     }
   }
+  async function getStatus() {
+    const { baseUrl, apiKey, appId } = cfg();
+    if (!baseUrl || !apiKey || !appId) return null;
+    try {
+      const res = await fetch(`${baseUrl}/api/v1/${appId}/status`, {
+        headers: headers(),
+        cache: "no-store"
+      });
+      if (!res.ok) return null;
+      return await res.json();
+    } catch {
+      return null;
+    }
+  }
   return {
     getPages,
     getPage,
@@ -152,8 +166,9 @@ function createCMSClient(options) {
     getPreviewPage,
     getPageWithPreview,
     getPageType,
-    getPageTypes,
-    getSiteStructure
+    getSiteStructure,
+    getSitemap,
+    getStatus
   };
 }
 var cmsClient = createCMSClient();