@riverbankcms/sdk 0.78.2 → 0.80.0

package/README.md

@@ -3259,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.