@riverbankcms/sdk 0.104.3 → 0.107.0

package/README.md

@@ -191,19 +191,26 @@ SDK sites that need bespoke event registration UI can use the headless event reg
 
 ```tsx
 import { loadPage, Page } from '@riverbankcms/sdk';
+import type { DataLoaderOverrides } from '@riverbankcms/sdk/data';
+
+const dataLoaderOverrides = {
+  'custom.block-id': {
+    loaderKey: async ({ content }) => {
+      const fieldValue = typeof content.fieldValue === 'string'
+        ? content.fieldValue
+        : '';
+      return fetchAndParseHostData(fieldValue);
+    },
+  },
+} satisfies DataLoaderOverrides;
 
 // 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),
-    },
-  },
+  siteId,
+  path,
+  preview: false,
+  dataLoaderOverrides,
 });
 
 // Render the page
@@ -2325,9 +2332,9 @@ All field types from the CMS are supported:
 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
+2. **Code-based loaders** - Server-only functions passed to `createCatchAllPage()`, `loadContent()`, or `loadPage()` for host databases and APIs
 
-Both loader types run server-side during `loadPage()`. Data is passed to your component via the `data` prop.
+Both loader types run server-side during normal page rendering. Data is passed to your component via the `data` prop.
 
 ### Config-Based Loaders (CMS Endpoints)
 
@@ -2547,49 +2554,61 @@ export function FeaturedPosts({
 
 ### Code-Based Loaders (External APIs)
 
-For data from external APIs, pass loader functions to `loadPage()`. This gives you full control over the fetch logic.
+For host database or API data, declare a server-only registry and pass it to the canonical catch-all. The recursive `DataLoaderValue` return type excludes functions, `undefined`, dates, class instances, and other values that cannot safely cross the RSC boundary. Riverbank also validates values defensively at runtime for JavaScript, `any`, and hostile object boundaries.
 
 **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}` } }
-          );
+// src/lib/data-loader-overrides.server.ts
+import 'server-only';
 
-          return res.json();
-        },
-      },
-    },
-  });
+import type { DataLoaderOverrides, DataLoaderValue } from '@riverbankcms/sdk/next';
+import { parseProductPayload } from '@/lib/product-api-schema';
 
-  return (
-    <Page
-      {...pageData}
-      blockOverrides={{
-        'custom.featured-products': FeaturedProducts,
-      }}
-    />
+async function fetchProducts(categoryId: string, limit: number): Promise<DataLoaderValue> {
+  const response = await fetch(
+    `https://api.shop.com/products?category=${encodeURIComponent(categoryId)}&limit=${limit}`,
+    { headers: { Authorization: `Bearer ${process.env.SHOP_API_KEY}` } },
   );
+  if (!response.ok) throw new Error(`Product API returned ${response.status}`);
+
+  const payload: unknown = await response.json();
+  // Parse and validate payload here with your application's boundary schema.
+  return parseProductPayload(payload);
 }
+
+export const dataLoaderOverrides = {
+  'custom.featured-products': {
+    products: async ({ content, searchParams }) => {
+      const categoryId = typeof content.categoryId === 'string' ? content.categoryId : '';
+      const configuredLimit = typeof content.limit === 'number' ? content.limit : 10;
+      const queryLimit = typeof searchParams.limit === 'string'
+        ? Number.parseInt(searchParams.limit, 10)
+        : configuredLimit;
+      return fetchProducts(categoryId, Number.isFinite(queryLimit) ? queryLimit : configuredLimit);
+    },
+  },
+} satisfies DataLoaderOverrides;
 ```
 
+```typescript
+// src/app/[[...slug]]/page.tsx
+import { createCatchAllPage } from '@riverbankcms/sdk/next';
+import { dataLoaderOverrides } from '@/lib/data-loader-overrides.server';
+
+const { Page, generateMetadata } = createCatchAllPage({
+  getClient,
+  config,
+  dataLoaderOverrides,
+  blockOverrides: { 'custom.featured-products': FeaturedProducts },
+});
+
+export default Page;
+export { generateMetadata };
+```
+
+Keep the `server-only` marker at the top of the registry so Next.js turns an accidental Client Component import into a build error. `generateMetadata()` never receives or runs host loaders—even with `customMetadata`—so a normal request does not repeat host queries for metadata and rendering.
+
 ```tsx
 // components/blocks/FeaturedProducts.tsx
 import type { BlockOverrideProps } from '@riverbankcms/sdk/rendering';
@@ -2646,6 +2665,12 @@ interface DataLoaderContext {
 
   /** Whether fetching preview/draft content */
   previewStage: 'published' | 'preview';
+
+  /** Immutable URL query parameters */
+  searchParams: Readonly<Record<string, string | readonly string[] | undefined>>;
+
+  /** Exact page, entry-template, or page-surface-template owner */
+  renderTarget: DataLoaderRenderTarget;
 }
 ```
 
@@ -2669,14 +2694,18 @@ customBlocks: [{
   },
 }]
 
-// page.tsx - Code loader for external API
-const pageData = await loadPage({
-  client,
-  siteId,
-  path: '/',
+// src/app/[[...slug]]/page.tsx - host loader for an external API
+const { Page, generateMetadata } = createCatchAllPage({
+  getClient,
+  config,
   dataLoaderOverrides: {
     'custom.product-showcase': {
-      products: async (ctx) => fetchProductsFromShopify(ctx.content.collectionId),
+      products: async ({ content }) => {
+        const collectionId = typeof content.collectionId === 'string'
+          ? content.collectionId
+          : '';
+        return fetchProductsFromShopify(collectionId);
+      },
     },
   },
 });
@@ -2688,7 +2717,7 @@ const pageData = await loadPage({
 
 Data loaders are best-effort. If a loader fails:
 
-- The error is logged to console
+- A structured warning identifies the site, page/template, block, loader key, stage, and failure kind without including thrown errors, block content, secrets, or loader results
 - The loader key is undefined in the `data` prop
 - Other loaders continue executing
 - Your component should handle missing data gracefully
@@ -2724,6 +2753,10 @@ import {
   type DataLoaderFn,
   type BlockLoaderMap,
   type DataLoaderOverrides,
+  type DataLoaderPreviewStage,
+  type DataLoaderRenderTarget,
+  type DataLoaderSearchParams,
+  type DataLoaderValue,
   type PrefetchContext,
   type ResolvedBlockData,
   type SdkPrefetchOptions,