@riverbankcms/sdk 0.78.0 → 0.79.0

package/README.md

@@ -2653,11 +2653,11 @@ import {
 
 ## Content Configuration (SDK Content Scaffolding)
 
-Define content type schema, local content scaffolding, navigation menus, and site settings in code. `push-config` syncs schema/config surfaces; mutable documents such as pages, entries, and navigation are synced with explicit `riverbankcms push` scopes.
+Define content type schema and SDK-managed configuration in code. File-based documents such as pages, entries, navigation, and settings live in `content/**` and sync with explicit `riverbankcms push` scopes; `push-config` syncs schema/config surfaces only.
 
 ### Quick Start
 
-Create a `content.config.ts` file alongside your `riverbank.config.ts`:
+Create a `content.config.ts` file alongside your `riverbank.config.ts` for schema/config surfaces:
 
 ```typescript
 // content.config.ts
@@ -2676,50 +2676,48 @@ export const contentConfig = defineContentConfig({
       ],
     },
   ],
+});
+```
 
-  // Page definitions
-  pages: [
-    {
-      identifier: 'home',
-      path: '/',
-      title: 'Home',
-      status: 'published',
-    },
-  ],
+Put mutable documents in `content/**` instead:
 
-  // Content entries
-  entries: [
-    {
-      identifier: 'testimonial-1',
-      contentType: 'testimonial',
-      status: 'published',
-      data: {
-        quote: '<p>Great product!</p>',
-        author: 'Jane Doe',
-      },
-    },
-  ],
+```jsonc
+// content/pages/home.json
+{
+  "identifier": "home",
+  "path": "/",
+  "title": "Home",
+  "status": "published"
+}
+```
 
-  // Navigation menus
-  navigationMenus: [
-    {
-      identifier: 'main',
-      name: 'Main Navigation',
-      isPrimary: true,
-      items: [
-        { label: 'Home', link: { kind: 'page', identifier: 'home' } },
-        { label: 'Get Started', link: { kind: 'url', href: '/signup' }, isCta: true },
-      ],
-    },
-  ],
+```jsonc
+// content/entries/testimonial/testimonial-1.json
+{
+  "identifier": "testimonial-1",
+  "status": "published",
+  "data": {
+    "quote": "<p>Great product!</p>",
+    "author": "Jane Doe"
+  }
+}
+```
 
-  // Site settings
-  settings: {
-    homepagePath: '/',
-    siteTitle: 'My Site',
-    siteDescription: 'Welcome to my site',
-  },
-});
+```jsonc
+// content/navigation.json
+{
+  "menus": [
+    {
+      "identifier": "main",
+      "name": "Main Navigation",
+      "isPrimary": true,
+      "items": [
+        { "label": "Home", "link": { "kind": "page", "identifier": "home" } },
+        { "label": "Get Started", "link": { "kind": "url", "href": "/signup" }, "isCta": true }
+      ]
+    }
+  ]
+}
 ```
 
 Then import it in your main config:
@@ -3155,6 +3153,7 @@ npx riverbankcms push [scope] [type] [identifier]
 | `entries` | Push all entries, a content type, or a single entry |
 | `pages` | Push all pages or a single page with blocks |
 | `navigation` | Push navigation menus |
+| `settings` | Push `content/settings.json` only |
 | `forms` | Push form definitions |
 
 **Options:**
@@ -3182,6 +3181,9 @@ npx riverbankcms push
 # Push only forms
 npx riverbankcms push forms
 
+# Push only site settings / branding
+npx riverbankcms push settings
+
 # Push to production with confirmation bypass
 npx riverbankcms push --env=remote --yes
 
@@ -3218,7 +3220,7 @@ npx riverbankcms push --dry-run --json-diff=summary
 ```
 
 - Keep branding files in `content/media/<identifier>.<ext>`
-- Run `npx riverbankcms push` to upload missing files and assign the site logo/favicon in one flow
+- Run `npx riverbankcms push settings` to upload missing branding files and assign the site logo/favicon without pushing unrelated content
 - Run `npx riverbankcms pull settings` to round-trip the current identifier-based branding state
 - If the current CMS logo/favicon asset has no media identifier yet, pull warns and omits that field instead of writing a destructive clear
 - Dashboard branding edits and CLI pushes both write the same site settings columns, so pull before pushing if someone may have changed branding in the dashboard
@@ -3257,6 +3259,86 @@ export default Page;
 export { generateMetadata };
 ```
 
+### Production ISR Setup
+
+For production SDK sites, wire the catch-all route to Next ISR and let Riverbank discover published routes at build time. Preview deployments should set `RIVERBANK_PREVIEW_MODE=true`; `getISRConfig()` then returns `revalidate: 0` so draft previews stay dynamic.
+
+```tsx
+// src/app/[[...slug]]/page.tsx
+import {
+  createCatchAllPage,
+  generateAllStaticParams,
+  getISRConfig,
+} from '@riverbankcms/sdk/next';
+
+import config from '@/riverbank.config';
+import { blockOverrides } from '@/lib/block-overrides';
+import { getRiverbankClient } from '@/lib/riverbank-client';
+
+export const revalidate = getISRConfig().revalidate;
+export const dynamicParams = true;
+export { generateAllStaticParams as generateStaticParams };
+
+const { Page, generateMetadata } = createCatchAllPage({
+  getClient: getRiverbankClient,
+  config,
+  blockOverrides,
+});
+
+export default Page;
+export { generateMetadata };
+```
+
+`generateAllStaticParams()` reads `RIVERBANK_API_KEY`, `RIVERBANK_SITE_ID`, and `NEXT_PUBLIC_DASHBOARD_URL`. By default it falls back to the homepage when route discovery fails, which keeps deploys from publishing an empty static route set silently. For strict production CI, fail the build instead:
+
+```tsx
+import { generateAllStaticParams } from '@riverbankcms/sdk/next';
+
+export function generateStaticParams() {
+  return generateAllStaticParams({ failureMode: 'throw' });
+}
+```
+
+If your site already has a configured client helper, use `createGenerateStaticParams()` so the route discovery client is explicit:
+
+```tsx
+import { createGenerateStaticParams } from '@riverbankcms/sdk/next';
+
+import config from '@/riverbank.config';
+import { getRiverbankClient } from '@/lib/riverbank-client';
+
+export const generateStaticParams = createGenerateStaticParams({
+  getClient: getRiverbankClient,
+  siteId: config.siteId,
+  failureMode: 'throw',
+});
+```
+
+Add a signed revalidation route so CMS publish events can refresh affected ISR paths immediately:
+
+```ts
+// src/app/api/revalidate/route.ts
+import { createRevalidateHandler } from '@riverbankcms/sdk/next/revalidate';
+
+export const POST = createRevalidateHandler();
+```
+
+Set `RIVERBANK_WEBHOOK_SECRET` in the deployed site and configure the matching Riverbank webhook endpoint to post to `/api/revalidate`. Revalidation requests are signed with `X-Riverbank-Signature: sha256=<hex HMAC-SHA256 digest>` over the raw JSON body. The SDK handler rejects missing prefixes, malformed digests, bad signatures, and invalid payloads; valid payloads can revalidate one or more top-level `paths` and `tags`, with malformed path entries skipped and reported in the response metadata.
+
+The CMS includes a `dispatchId` in signed payloads and sends matching `X-Riverbank-Dispatch-Id` / `X-Riverbank-Correlation-Id` headers. Use the optional callback metadata to join CMS delivery logs with consumer deployment logs without logging secrets:
+
+```ts
+export const POST = createRevalidateHandler({
+  onRevalidate: (_payload, _items, metadata) => {
+    console.info('Riverbank ISR revalidated', metadata);
+  },
+});
+```
+
+SDK-site revalidation webhook events cover publish, unpublish, delete, and public path-change events for pages and entries, plus navigation, theme, and site settings updates. Global render changes are sent as tags-only payloads, and very large explicit path sets degrade to tags-only delivery so sites do not receive unbounded path arrays. Existing webhook endpoints may need their subscribed event list updated to receive the newer unpublish, delete, and path-change events.
+
+For troubleshooting, inspect the endpoint's delivery logs in Riverbank. Each delivery stores minimized payload diagnostics with `dispatchId`, `siteId`, event, `pathCount`, `tagCount`, status, response time, and a minimized failure body. Secrets, signature headers, cookies, authorization headers, and raw sensitive fields are not written to delivery logs.
+
 ### Upstream content-load failures
 
 `createCatchAllPage()` only calls `notFound()` for confirmed content misses, such as an API 404 for an absent page. Timeout, network, 5xx, auth, and circuit-open failures from the CMS are surfaced as `RiverbankContentLoadError` by default so monitors and crawlers do not mistake a transient upstream problem for missing content. `SdkContentLoadError` remains available as a compatibility alias for the same error class.