@riverbankcms/sdk 0.7.0 → 0.7.3

package/README.md

@@ -2530,6 +2530,232 @@ npx riverbankcms push-config \
   --dashboard https://www.riverbankcms.com
 ```
 
+## Next.js Catch-All Page Factory
+
+The SDK provides a `createCatchAllPage()` factory that dramatically reduces boilerplate for Next.js catch-all routes. It handles page/entry routing, preview mode, metadata generation, and error handling in ~10 lines.
+
+### Basic Usage
+
+```tsx
+// src/app/[[...slug]]/page.tsx
+import { createCatchAllPage } from '@riverbankcms/sdk/next';
+import { getRiverbankClient } from '@/lib/builder-client';
+import config from '@/riverbank.config';
+
+const { Page, generateMetadata } = createCatchAllPage({
+  getClient: getRiverbankClient,
+  config,
+  blockOverrides: { /* custom block components */ },
+});
+
+export default Page;
+export { generateMetadata };
+```
+
+This single call replaces ~160 lines of typical boilerplate that handles:
+- Path resolution from URL slugs
+- Content loading (pages and entries)
+- Preview mode detection
+- Template rendering for entries
+- SEO metadata generation
+- 404 handling
+
+### Preview Mode
+
+Preview mode is detected via the `RIVERBANK_PREVIEW_MODE` environment variable:
+
+```bash
+# In your preview/staging environment
+RIVERBANK_PREVIEW_MODE=true
+```
+
+When enabled, `loadContent()` fetches draft/unpublished content instead of published content.
+
+### Escape Hatches
+
+For customization beyond the defaults, use these options:
+
+#### `beforeRender` - Maintenance Mode, Access Control
+
+Intercept before rendering to implement maintenance mode, authentication, etc. Return a React node to short-circuit rendering, or `null` to continue.
+
+```tsx
+const { Page, generateMetadata } = createCatchAllPage({
+  getClient,
+  config,
+  beforeRender: async ({ content, path, preview, searchParams }) => {
+    // Maintenance mode
+    if (process.env.MAINTENANCE_MODE === 'true') {
+      return <MaintenancePage />;
+    }
+
+    // Access control for protected paths
+    if (path.startsWith('/members')) {
+      const session = await getSession();
+      if (!session) {
+        return <LoginPage redirect={path} />;
+      }
+    }
+
+    // Continue with normal rendering
+    return null;
+  },
+});
+```
+
+#### `customMetadata` - Custom SEO Logic
+
+Replace default metadata generation with custom logic:
+
+```tsx
+createCatchAllPage({
+  getClient,
+  config,
+  customMetadata: async ({ content, path, preview, searchParams }) => {
+    if (isEntryContent(content) && content.entry.type === 'product') {
+      return {
+        title: `${content.entry.title} | Shop`,
+        openGraph: {
+          type: 'product',
+          // ... product-specific OG tags
+        },
+      };
+    }
+
+    // Fall back to default for other content
+    return generatePageMetadata({
+      page: content.page,
+      site: content.site,
+      path,
+      siteUrl: 'https://example.com',
+    });
+  },
+});
+```
+
+#### `wrapper` - Analytics, Error Boundaries
+
+Wrap all rendered content with a component:
+
+```tsx
+createCatchAllPage({
+  getClient,
+  config,
+  wrapper: ({ children }) => (
+    <>
+      {children}
+      <AnalyticsScript siteId={config.siteId} />
+    </>
+  ),
+});
+```
+
+### Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `getClient` | `() => RiverbankClient` | Yes | Factory function returning a configured client |
+| `config` | `RiverbankSiteConfig` | Yes | Site config from `defineConfig()` |
+| `blockOverrides` | `BlockOverrides` | No | Custom block component overrides |
+| `siteUrl` | `string` | No | Override site URL for metadata (uses `config.liveUrl`/`previewUrl` as fallback) |
+| `beforeRender` | `function` | No | Intercept before rendering |
+| `customMetadata` | `function` | No | Custom metadata generation |
+| `wrapper` | `ComponentType` | No | Wrapper component for rendered content |
+
+### Context Available in Escape Hatches
+
+Both `beforeRender` and `customMetadata` receive a context object:
+
+```typescript
+type CatchAllContext = {
+  content: LoadContentResult;  // Page or entry data (includes site data)
+  path: string;                // Resolved path (e.g., '/blog/my-post')
+  preview: boolean;            // Whether preview mode is enabled
+  searchParams: Record<string, string | string[] | undefined>;  // URL search params
+};
+```
+
+### Full Control - Use Lower-Level Helpers
+
+For maximum customization, skip `createCatchAllPage` and use the underlying helpers:
+
+```tsx
+import { loadContent, isPageContent, Page } from '@riverbankcms/sdk/rendering';
+import { generatePageMetadata } from '@riverbankcms/sdk/metadata';
+
+export default async function CustomPage({ params }) {
+  const { slug } = await params;
+  const path = `/${slug?.join('/') || ''}`;
+
+  const content = await loadContent({
+    client: getClient(),
+    siteId: config.siteId,
+    path,
+    preview: process.env.RIVERBANK_PREVIEW_MODE === 'true',
+  });
+
+  if (isPageContent(content)) {
+    return <Page {...content} />;
+  }
+
+  // Custom entry rendering
+  return <CustomEntryRenderer entry={content.entry} theme={content.theme} />;
+}
+```
+
+## Spam Protection
+
+Add ALTCHA proof-of-work spam protection to forms. The widget runs entirely client-side and requires no API keys.
+
+### Setup
+
+```tsx
+'use client'
+
+import { useSpamProtection, getChallengeUrl } from '@riverbankcms/sdk/spam-protection'
+
+function ContactForm() {
+  const { solution, isReady, reset, Widget } = useSpamProtection(getChallengeUrl())
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    if (!isReady) return
+
+    await fetch('/api/contact', {
+      method: 'POST',
+      body: JSON.stringify({
+        ...formData,
+        altchaSolution: solution,  // Include with submission
+      }),
+    })
+    reset()  // Reset for another submission
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* form fields */}
+      <Widget />
+      <button disabled={!isReady}>Submit</button>
+    </form>
+  )
+}
+```
+
+### Environment
+
+Set `NEXT_PUBLIC_DASHBOARD_URL` so `getChallengeUrl()` resolves correctly.
+
+### Exports
+
+```tsx
+import {
+  useSpamProtection,    // Hook for solution state management
+  getChallengeUrl,      // Returns challenge endpoint URL
+  hasSpamProtection,    // Check if spam protection is enabled (server-only)
+  AltchaWidget,         // Low-level widget component
+} from '@riverbankcms/sdk/spam-protection'
+```
+
 ## Additional Exports
 
 - `@riverbankcms/sdk/rendering` - Low-level rendering components
@@ -2539,5 +2765,8 @@ npx riverbankcms push-config \
 - `@riverbankcms/sdk/data` - Data prefetching utilities
 - `@riverbankcms/sdk/metadata` - Metadata generation helpers
 - `@riverbankcms/sdk/routing` - Route resolution helpers
+- `@riverbankcms/sdk/navigation` - Navigation helpers and types
 - `@riverbankcms/sdk/analytics` - Analytics tracking helpers
 - `@riverbankcms/sdk/config` - Site configuration utilities (includes `defineConfig`, `defineContentConfig`, `RiverbankSiteConfig`, `ContentConfig`, etc.)
+- `@riverbankcms/sdk/next` - Next.js integration utilities (`createCatchAllPage`)
+- `@riverbankcms/sdk/spam-protection` - ALTCHA spam protection (`useSpamProtection`, `getChallengeUrl`, `AltchaWidget`)

package/dist/cli/index.js

@@ -8495,25 +8495,56 @@ function renderOptionsList(options, depth) {
 // src/cli/init-docs/index.ts
 var AGENTS_START = "<!-- RIVERBANK-CONTEXT-START -->";
 var AGENTS_END = "<!-- RIVERBANK-CONTEXT-END -->";
+function getContentDir() {
+  const isBundled = __dirname.includes("/dist/cli") || __dirname.endsWith("/dist/cli");
+  if (isBundled) {
+    return path9__namespace.join(__dirname, "init-docs", "content");
+  }
+  return path9__namespace.join(__dirname, "content");
+}
+function loadTemplate(name) {
+  const contentDir = getContentDir();
+  const filePath = path9__namespace.join(contentDir, `${name}.md`);
+  return fs.readFileSync(filePath, "utf-8");
+}
 async function initDocs(options) {
-  const { rootDir, configPath, agentsPath, output } = options;
+  const { rootDir, configPath, agentsPath } = options;
   const docsDir = path9__namespace.join(rootDir, "docs");
   const contextDir = path9__namespace.join(rootDir, "context");
   const workflowsDir = path9__namespace.join(docsDir, "workflows");
+  const siteWorkflowsDir = path9__namespace.join(docsDir, "site-workflows");
   const knowledgeDir = path9__namespace.join(contextDir, "knowledge");
   const brandDir = path9__namespace.join(contextDir, "brand");
   await ensureDir2(workflowsDir);
+  await ensureDir2(siteWorkflowsDir);
   await ensureDir2(knowledgeDir);
   await ensureDir2(brandDir);
-  await writeFileIfMissing(path9__namespace.join(docsDir, "cli-reference.md"), cliReferenceTemplate());
-  await writeFileIfMissing(path9__namespace.join(docsDir, "content-management.md"), contentManagementTemplate());
-  await writeFileIfMissing(path9__namespace.join(workflowsDir, "create-page.md"), workflowCreatePageTemplate());
-  await writeFileIfMissing(path9__namespace.join(workflowsDir, "add-block.md"), workflowAddBlockTemplate());
-  await writeFileIfMissing(path9__namespace.join(workflowsDir, "publish-workflow.md"), workflowPublishTemplate());
-  await writeFileIfMissing(path9__namespace.join(contextDir, "brief.md"), briefTemplate());
-  await writeFileIfMissing(path9__namespace.join(knowledgeDir, "README.md"), knowledgeTemplate());
-  await writeFileIfMissing(path9__namespace.join(brandDir, "README.md"), brandTemplate());
-  const { config: config3, errorMessage } = await loadConfig(configPath, output);
+  await writeFileIfMissing(path9__namespace.join(docsDir, "getting-started.md"), loadTemplate("getting-started"));
+  await writeFileIfMissing(path9__namespace.join(docsDir, "cli-reference.md"), loadTemplate("cli-reference"));
+  await writeFileIfMissing(
+    path9__namespace.join(docsDir, "content-management.md"),
+    loadTemplate("content-management")
+  );
+  await writeFileIfMissing(
+    path9__namespace.join(workflowsDir, "create-page.md"),
+    loadTemplate("workflow-create-page")
+  );
+  await writeFileIfMissing(
+    path9__namespace.join(workflowsDir, "add-block.md"),
+    loadTemplate("workflow-add-block")
+  );
+  await writeFileIfMissing(
+    path9__namespace.join(workflowsDir, "publish-workflow.md"),
+    loadTemplate("workflow-publish")
+  );
+  await writeFileIfMissing(
+    path9__namespace.join(siteWorkflowsDir, "README.md"),
+    loadTemplate("site-workflows-readme")
+  );
+  await writeFileIfMissing(path9__namespace.join(contextDir, "brief.md"), loadTemplate("context-brief"));
+  await writeFileIfMissing(path9__namespace.join(knowledgeDir, "README.md"), loadTemplate("context-knowledge"));
+  await writeFileIfMissing(path9__namespace.join(brandDir, "README.md"), loadTemplate("context-brand"));
+  const { config: config3, errorMessage } = await loadConfig(configPath, options.output);
   await upsertGeneratedDoc(
     path9__namespace.join(docsDir, "schema.md"),
     buildSchemaTemplate({ config: config3, errorMessage }),
@@ -8587,94 +8618,10 @@ ${after}`;
 }
 async function upsertAgentsSection(filePath) {
   const content = await readFileOrTemplate(filePath, "# AGENTS.md\n");
-  const section2 = agentsSectionTemplate();
+  const section2 = loadTemplate("agents-section");
   const updated = replaceMarkedSection(content, AGENTS_START, AGENTS_END, section2);
   await fs3__namespace.writeFile(filePath, updated, "utf-8");
 }
-function cliReferenceTemplate() {
-  return [
-    "# CLI Reference",
-    "",
-    "Describe the SDK CLI commands available to agents.",
-    "",
-    "Include usage patterns, required flags, and common examples.",
-    ""
-  ].join("\n");
-}
-function contentManagementTemplate() {
-  return [
-    "# Content Management",
-    "",
-    "Describe how content is structured, edited, and published for this site.",
-    ""
-  ].join("\n");
-}
-function workflowCreatePageTemplate() {
-  return [
-    "# Workflow: Create a Page",
-    "",
-    "Describe the steps to create a page for this site.",
-    "",
-    "Include any required content types or blocks.",
-    ""
-  ].join("\n");
-}
-function workflowAddBlockTemplate() {
-  return [
-    "# Workflow: Add a Block",
-    "",
-    "Describe how to add blocks to an existing page.",
-    ""
-  ].join("\n");
-}
-function workflowPublishTemplate() {
-  return [
-    "# Workflow: Publish Content",
-    "",
-    "Describe how to publish content safely for this site.",
-    ""
-  ].join("\n");
-}
-function briefTemplate() {
-  return [
-    "# Site Brief",
-    "",
-    "Summarize the brand, tone, and goals for this site.",
-    ""
-  ].join("\n");
-}
-function knowledgeTemplate() {
-  return [
-    "# Knowledge Base",
-    "",
-    "Add domain knowledge, FAQs, and reference links for the site.",
-    ""
-  ].join("\n");
-}
-function brandTemplate() {
-  return [
-    "# Brand Assets",
-    "",
-    "List or link the brand assets available for this site.",
-    ""
-  ].join("\n");
-}
-function agentsSectionTemplate() {
-  return [
-    "## Riverbank SDK Context",
-    "",
-    "- This repo contains both the CMS and the SDK used by this site.",
-    "- Agents can suggest or implement CMS changes when needed, not just local workarounds.",
-    "- Use riverbank.config.ts as the source of truth for site schema and custom blocks.",
-    "",
-    "## Code Quality Guidelines (SDK + CMS)",
-    "",
-    "- Prefer functional, composable helpers over large classes.",
-    "- Keep changes small and DRY; remove old code instead of shimming.",
-    "- Keep route handlers thin and use helpers/services.",
-    "- Use typed API clients; avoid hardcoded URLs."
-  ].join("\n");
-}
 
 // src/cli/commands/init-docs.ts
 async function runInitDocs(options, command) {