@riverbankcms/sdk 0.77.1 → 0.78.2

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,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 +3352,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: