@riverbankcms/sdk 0.77.0 → 0.78.0

package/README.md

@@ -3257,6 +3257,34 @@ export default Page;
 export { generateMetadata };
 ```
 
+### 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.
+
+If you want to render a custom temporary-unavailable view, use `onContentLoadFailure`. Be aware that rendering a fallback from a Next.js page component may produce a normal page response; if you need a specific HTTP status such as 503, verify it in your host app and error-boundary setup.
+
+```tsx
+import { createCatchAllPage } from '@riverbankcms/sdk/next';
+
+const { Page, generateMetadata } = createCatchAllPage({
+  getClient: getRiverbankClient,
+  config,
+  getRequestContext: () => ({
+    host: process.env.NEXT_PUBLIC_SITE_HOST,
+  }),
+  onContentLoadFailure: ({ failure }) => (
+    <main>
+      <h1>Temporarily unavailable</h1>
+      <p>Please try again shortly.</p>
+      <small>{failure.kind}</small>
+    </main>
+  ),
+});
+
+export default Page;
+export { generateMetadata };
+```
+
 ### Lazy Block Overrides
 
 Eager `blockOverrides` remain supported and are a good fit for small server-safe components. For client-heavy or rarely used custom blocks, register a lazy override so `createCatchAllPage()` resolves only the override modules needed by the page or entry template being rendered:
@@ -3322,6 +3350,47 @@ Invalid subroute segments (e.g., `/events/yoga-class/invalid-date`) return a 404
 
 See [`docs/guides/entry-subroutes.md`](../../docs/guides/entry-subroutes.md) for the full data flow and instructions for adding a new subroute kind.
 
+#### Lower-Level `resolvePageContent` Contract
+
+If you use `resolvePageContent` directly from `@riverbankcms/sdk/routing`, the `loadContent` callback must return the explicit routing result helpers rather than `content | null`:
+
+```ts
+import { RiverbankApiError } from '@riverbankcms/sdk'
+import {
+  contentFound,
+  contentLoadFailed,
+  contentNotFound,
+  resolvePageContent,
+} from '@riverbankcms/sdk/routing'
+
+await resolvePageContent({
+  path,
+  contentTypes,
+  loadContent: async (contentPath) => {
+    try {
+      const content = await client.getPage({ siteId, path: contentPath })
+      return contentFound(content)
+    } catch (error) {
+      if (error instanceof RiverbankApiError && error.status === 404) {
+        return contentNotFound()
+      }
+
+      return contentLoadFailed({
+        kind: 'unknown',
+        stage: 'content_lookup',
+        message: error instanceof Error ? error.message : String(error),
+      })
+    }
+  },
+  resolveEntrySubroute,
+  isEntry,
+  getEntryId,
+  getEntryTypeKey,
+})
+```
+
+This distinction is intentional: true absence remains a 404 candidate, while transient CMS/API failures can surface through the host application's error boundary instead of being cached or reported as missing content.
+
 ### Escape Hatches
 
 For customization beyond the defaults, use these options: