@riverbankcms/sdk 0.128.0 → 0.129.1

package/dist/cli/init-docs/content/workflow-editor-workflows.md

@@ -1,130 +0,0 @@
-# Workflow: Build an Editor Workflow
-
-## Purpose
-
-Add a manual action to the Riverbank dashboard editor. Editor workflows are declared in `riverbank.config.ts` and run against either a content type or the page editor.
-
-## Configure
-
-Add a workflow to SDK config, then run `riverbankcms push-config`.
-
-```ts
-export default {
-  siteId: process.env.RIVERBANK_SITE_ID,
-  previewUrl: "https://preview.example.com",
-  workflows: [
-    {
-      id: "page.generate-seo",
-      title: "Generate SEO metadata",
-      description: "Draft page SEO fields from the current page.",
-      contentType: "page",
-      endpoint: "/api/workflows/generate-seo",
-      triggers: [{ type: "manual" }],
-    },
-  ],
-};
-```
-
-Use `contentType: "page"` for page workflows. Use a content type key, such as `blog-post`, for entry workflows. If `workflows` is missing or empty, the dashboard does not show the workflow section.
-
-## Handle the Request
-
-Riverbank saves the draft, disables the editor, creates a workflow run, and posts to your endpoint. Verify the raw body with the same HMAC helper used for webhooks:
-
-The `x-riverbank-signature` header is formatted as `sha256=<hex HMAC-SHA256 digest>`.
-
-```ts
-import { verifyWebhookSignature } from "@riverbankcms/sdk/webhooks";
-
-export async function POST(request: Request) {
-  const body = await request.text();
-  const signature = request.headers.get("x-riverbank-signature");
-  const secret = process.env.RIVERBANK_WEBHOOK_SECRET;
-
-  if (
-    !signature ||
-    !secret ||
-    !verifyWebhookSignature(body, signature, secret)
-  ) {
-    return Response.json({ error: "Invalid signature" }, { status: 401 });
-  }
-
-  const payload = JSON.parse(body);
-  // payload.entry.kind is "page" or "content-entry"
-
-  return Response.json({
-    status: "succeeded",
-    summary: "Draft updated",
-    draftContentPatch: {
-      draftMetaDescription: "A concise search description.",
-    },
-  });
-}
-```
-
-The request includes `runId`, `siteId`, `workflowId`, `contentType`, `entryId`, `trigger`, and an `entry` snapshot.
-
-## Return a Result
-
-For immediate changes, return:
-
-```json
-{
-  "status": "succeeded",
-  "summary": "Updated the draft",
-  "draftContentPatch": {}
-}
-```
-
-For longer work, return:
-
-```json
-{
-  "status": "accepted",
-  "externalJobId": "job_123",
-  "summary": "Started"
-}
-```
-
-Then call the management API when the job completes:
-
-```bash
-curl -X POST "$RIVERBANK_DASHBOARD_URL/api/sdk/$RIVERBANK_SITE_ID/workflows/runs/$RUN_ID/status" \
-  -H "Authorization: Bearer $RIVERBANK_MGMT_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"status":"succeeded","summary":"Done","draftContentPatch":{"draftMetaTitle":"Updated title"}}'
-```
-
-To report failure, return or callback with:
-
-```json
-{
-  "status": "failed",
-  "error": "Could not generate metadata"
-}
-```
-
-## Draft Patch Rules
-
-Content entry workflows patch draft content fields.
-
-Page workflows patch route metadata only:
-
-- `draftTitle`
-- `draftSlug`
-- `draftStatus`
-- `scheduledPublishAt`
-- `draftMetaTitle`
-- `draftMetaDescription`
-- `canonicalUrl`
-- `ogImageId`
-
-If the workflow returns no `draftContentPatch`, it must make changes through management API endpoints or leave the draft unchanged.
-
-## Verification
-
-1. Run `riverbankcms push-config`.
-2. Open the matching entry or page in the dashboard.
-3. Confirm the workflow section appears only when the config contains matching manual workflows.
-4. Run the workflow and confirm the editor stays disabled until the endpoint returns or the async callback completes.
-5. Confirm the draft reflects any returned patch.

package/dist/cli/init-docs/content/workflow-isr-revalidation.md

@@ -1,158 +0,0 @@
-# Workflow: Production ISR and Revalidation
-
-## Purpose
-
-Configure a Riverbank SDK Next.js App Router site to prerender published routes, serve production pages through ISR, and refresh affected paths when the CMS sends signed publish webhooks.
-
-## Prerequisites
-
-- A Riverbank SDK site using `createCatchAllPage()` in `src/app/[[...slug]]/page.tsx`.
-- A production content API key in `RIVERBANK_API_KEY`.
-- `RIVERBANK_SITE_ID` set to this site's Riverbank site ID.
-- `NEXT_PUBLIC_DASHBOARD_URL` set to the dashboard origin, for example `https://cms.example.com`.
-- `RIVERBANK_WEBHOOK_SECRET` set from the CMS-generated Riverbank webhook secret.
-
-Preview deployments should also set `RIVERBANK_PREVIEW_MODE=true` so draft previews stay dynamic instead of serving stale ISR HTML.
-
-## Configure the Catch-All Route
-
-In `src/app/[[...slug]]/page.tsx`:
-
-```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()` discovers published pages and routable entries at build time. It reads:
-
-- `RIVERBANK_API_KEY`
-- `RIVERBANK_SITE_ID`
-- `NEXT_PUBLIC_DASHBOARD_URL`
-
-By default, route discovery falls back to the homepage if the CMS is temporarily unavailable. Use strict mode when you want production CI to fail instead:
-
-```tsx
-import { generateAllStaticParams } from '@riverbankcms/sdk/next'
-
-export function generateStaticParams() {
-  return generateAllStaticParams({ failureMode: 'throw' })
-}
-```
-
-If your site already centralizes the SDK client, use the explicit factory:
-
-```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 the Revalidation Route
-
-Create `src/app/api/revalidate/route.ts`:
-
-```ts
-import { createRevalidateHandler } from '@riverbankcms/sdk/next/revalidate'
-import { getRiverbankClient } from '@/lib/riverbank-client'
-
-export const POST = createRevalidateHandler({
-  getClient: getRiverbankClient,
-})
-```
-
-The deployed site must have the CMS-generated webhook secret:
-
-```bash
-RIVERBANK_WEBHOOK_SECRET=...
-```
-
-Riverbank signs each request with:
-
-```http
-X-Riverbank-Signature: sha256=<hex HMAC-SHA256 digest>
-```
-
-The digest is computed over the raw JSON body. The SDK handler rejects unsigned requests, plain hex signatures without the `sha256=` prefix, malformed digests, bad signatures, and invalid payloads. Malformed path entries are skipped and reported in the response metadata while valid tags and paths still revalidate.
-
-Passing `getClient: getRiverbankClient` also clears the current process's SDK client response cache after valid webhooks. This is useful in single-process deployments, `next dev`, `next start`, and runtimes where the revalidation route and render path share the same module instance. On serverless platforms such as Vercel, `/api/revalidate` and page rendering can run in separate functions and many warm containers, so this process-local cache clear is best-effort only. Use Next tag/path revalidation as the cross-instance freshness layer, and disable or shorten SDK response caching for force-dynamic deployments that need immediate freshness across serverless instances.
-
-Riverbank includes a `dispatchId` in signed payloads and sends matching `X-Riverbank-Dispatch-Id` / `X-Riverbank-Correlation-Id` headers. To join CMS delivery logs with this site's deployment logs, use the optional callback metadata:
-
-```ts
-export const POST = createRevalidateHandler({
-  getClient: getRiverbankClient,
-  onRevalidate: (_payload, _items, metadata) => {
-    console.info('Riverbank ISR revalidated', metadata)
-  },
-})
-```
-
-## Configure the CMS Webhook Endpoint
-
-Use the SDK CLI to configure or reuse an enabled CMS webhook endpoint whose URL points at the deployed route:
-
-```bash
-riverbankcms webhooks setup \
-  --env=remote \
-  --url=https://www.example.com/api/revalidate \
-  --yes \
-  --vercel
-```
-
-The command keeps the CMS as the source of truth for the webhook secret. It creates or updates the endpoint, ensures the full SDK revalidation event list is subscribed, writes a newly generated one-time secret to `.env.local` when one is returned, and prints hosted-environment and deploy/test steps. Existing endpoint secrets are not returned or changed unless you pass `--rotate-secret`.
-
-The deployed SDK site uses the returned one-time `RIVERBANK_WEBHOOK_SECRET`. The dashboard/CMS uses a separate `WEBHOOK_SIGNING_SECRET_KEYRING_JSON` environment variable to encrypt stored endpoint secrets; keep that keyring only in the dashboard environment.
-
-The same destination URL can also be configured from the Riverbank dashboard:
-
-```text
-https://www.example.com/api/revalidate
-```
-
-SDK-site revalidation events include page and entry publish, unpublish, delete, and public path changes, along with navigation, theme, site settings, and public event updates. Event updates are tag-authoritative: they always invalidate the site-wide public event and event-filter tags, and include the linked event path when one is known. Events send top-level `paths` and `tags`; the SDK handler normalizes and dedupes them before calling `revalidatePath()` and `revalidateTag()`.
-
-Some valid events are tags-only. Global render changes do not include explicit paths, and very large path sets degrade to tags-only delivery so webhook payloads stay bounded. 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.
-
-## Verify
-
-1. Build the site with production environment variables present.
-2. Confirm a published route is included in the static params output or appears as prerendered in the Next build summary.
-3. Visit a published page.
-4. Publish a change in the CMS.
-5. Confirm the webhook delivery succeeds.
-6. Reload the page and confirm the changed content appears without waiting for the normal ISR interval.
-
-For local SDK development inside the Riverbank monorepo, the smoke check is:
-
-```bash
-pnpm --filter @riverbankcms/sdk test:isr-catch-all-revalidate-smoke
-```

package/dist/cli/init-docs/content/workflow-preview-mode.md

@@ -1,239 +0,0 @@
-# Workflow: SDK Preview Mode
-
-## Purpose
-
-Enable dashboard preview editing for an SDK-hosted Next.js site. Preview mode lets the dashboard open the external site with a short-lived editor session, render draft content, and show the Riverbank preview shell.
-
-## Prerequisites
-
-- A Riverbank SDK site using the Next.js App Router.
-- A preview/staging URL for the site.
-- A Riverbank preview API key (`bld_preview_sk_...`) for draft content.
-- Dashboard access to run `riverbankcms push-config`.
-
-## Configure `riverbank.config.ts`
-
-Set the preview URL and enable token-based preview editing:
-
-```ts
-import { defineConfig } from '@riverbankcms/sdk/config'
-
-export default defineConfig({
-  siteId: process.env.RIVERBANK_SITE_ID!,
-  previewUrl: process.env.NEXT_PUBLIC_SITE_URL!,
-  dashboard: {
-    previewEditingEnabled: true,
-  },
-})
-```
-
-Then sync the config:
-
-```bash
-riverbankcms push-config --env=remote
-```
-
-Use `--dashboard <url>` and `--api-key <key>` when you want explicit values to override environment variables.
-
-## Add Preview Token Proxy
-
-Create `src/proxy.ts`:
-
-```ts
-import { handlePreviewTokens } from '@riverbankcms/sdk/preview-next/middleware'
-import { NextResponse, type NextRequest } from 'next/server'
-
-import { getCmsConfig } from './lib/env'
-
-export async function proxy(request: NextRequest) {
-  if (process.env.RIVERBANK_PREVIEW_MODE === 'true') {
-    const { dashboardUrl } = getCmsConfig()
-    const response = await handlePreviewTokens(request, {
-      dashboardUrl: dashboardUrl ?? null,
-      onExchangeFailure: (failure) => {
-        console.warn('[riverbank] preview token exchange failed', failure)
-      },
-    })
-    if (response) return response
-  }
-
-  return NextResponse.next()
-}
-
-export const config = {
-  matcher: ['/((?!_next/static|_next/image|api|favicon.ico|robots.txt|sitemap.xml).*)'],
-}
-```
-
-The example logs preview exchange failures with `console.warn`; replace it with your app logger if you already centralize server-side logging.
-
-If you are upgrading an existing generated site, make sure your proxy imports `getCmsConfig`, is declared `async`, and passes `dashboardUrl` into `handlePreviewTokens`. Without the dashboard URL, visits with `preview_code` cannot exchange the short-lived code for preview cookies.
-
-## Public Runtime Adapter Contracts
-
-Use `resolveRouteDecision` for middleware or redirect-only checks. It returns only `contentExists`, `redirect`, `notFound`, or `loadFailed`; use `resolveRouteOutcome` only when the caller needs the full content payload for rendering.
-
-Event registration endpoints use the `public-event-ticket-selection.v2` transport shape: pass `ticketSelections: [{ ticketTypeId, quantity }]`. Legacy top-level `ticketsCount` or `ticketTypeId` fields are rejected so stale clients fail visibly instead of silently selecting the wrong tickets.
-
-## Add Preview Keep-Alive Route
-
-Create `src/app/api/preview/keep-alive/route.ts`:
-
-```ts
-import type { NextRequest } from 'next/server'
-
-import { createPreviewKeepAliveRouteHandler } from '@riverbankcms/sdk/preview-next/keep-alive'
-
-const handler = createPreviewKeepAliveRouteHandler()
-
-export function GET(request: NextRequest) {
-  return handler(request)
-}
-
-export function POST(request: NextRequest) {
-  return handler(request)
-}
-```
-
-## Add The Client Preview Wrapper
-
-Create `src/components/preview/SdkPreviewModeClient.tsx`:
-
-```tsx
-'use client'
-
-import { PreviewQueryProvider, SdkPreviewMode, type SdkPreviewModeProps } from '@riverbankcms/sdk/preview-next/client'
-
-import { blockOverrides } from '@/lib/block-overrides'
-
-type SdkPreviewModeClientProps = Omit<SdkPreviewModeProps, 'blockOverrides'>
-
-export function SdkPreviewModeClient(props: SdkPreviewModeClientProps) {
-  return (
-    <PreviewQueryProvider>
-      <SdkPreviewMode {...props} blockOverrides={blockOverrides} />
-    </PreviewQueryProvider>
-  )
-}
-```
-
-## Wire The Catch-All Page
-
-Use `createPreviewModeBeforeRender` in the catch-all page:
-
-```tsx
-import { createCatchAllPage } from '@riverbankcms/sdk/next'
-import { createPreviewModeBeforeRender } from '@riverbankcms/sdk/preview-next/before-render'
-
-import config from '../../../riverbank.config'
-import { blockOverrides } from '@/lib/block-overrides'
-import { getRiverbankClient } from '@/lib/riverbank-client'
-import { SdkPreviewModeClient } from '@/components/preview/SdkPreviewModeClient'
-
-const { Page, generateMetadata } = createCatchAllPage({
-  getClient: getRiverbankClient,
-  config,
-  blockOverrides,
-  beforeRender: createPreviewModeBeforeRender({
-    getClient: getRiverbankClient,
-    siteId: config.siteId,
-    PreviewModeClient: SdkPreviewModeClient,
-  }),
-})
-
-export default Page
-export { generateMetadata }
-```
-
-## Custom Header/Footer Chrome
-
-If your site replaces the SDK header or footer, pass that chrome into `PreviewLayoutProvider` only when there is an editable preview session. `RIVERBANK_PREVIEW_MODE=true` makes the route preview-capable, but `getPreviewSession()` tells you whether the current request actually has preview cookies. Regular visitors without preview cookies should keep the normal SDK `Layout`.
-
-In `src/app/layout.tsx`:
-
-```tsx
-import type { ReactNode } from 'react'
-
-import { Layout } from '@riverbankcms/sdk/rendering/server'
-import { PreviewLayoutProvider } from '@riverbankcms/sdk/preview-next/client'
-import { getPreviewSession } from '@riverbankcms/sdk/preview-next/session'
-
-import { getRiverbankClient, getSiteId } from '@/lib/riverbank-client'
-
-function SiteHeader() {
-  return <header>{/* your site header */}</header>
-}
-
-function SiteFooter() {
-  return <footer>{/* your site footer */}</footer>
-}
-
-export default async function RootLayout({ children }: { children: ReactNode }) {
-  const session = await getPreviewSession()
-  const hasEditablePreviewSession = Boolean(session?.canEdit && session?.token)
-  const headerNode = <SiteHeader />
-  const footerNode = <SiteFooter />
-
-  return (
-    <html lang="en">
-      <body>
-        {hasEditablePreviewSession ? (
-          <PreviewLayoutProvider headerNode={headerNode} footerNode={footerNode}>
-            {children}
-          </PreviewLayoutProvider>
-        ) : (
-          <Layout
-            client={getRiverbankClient()}
-            siteId={getSiteId()}
-            header={() => headerNode}
-            footer={() => footerNode}
-          >
-            {children}
-          </Layout>
-        )}
-      </body>
-    </html>
-  )
-}
-```
-
-If your custom chrome needs CMS navigation data, build the `headerNode` and `footerNode` from the same data used by your normal layout before branching. Calling `getPreviewSession()` in the root layout reads cookies, so the layout becomes dynamic.
-
-## Import Preview CSS
-
-For Tailwind sites, add this to `src/app/globals.css`:
-
-```css
-@import "tailwindcss";
-@import "@riverbankcms/sdk/preview-next/tailwind-sources.css";
-@import "@riverbankcms/sdk/preview-next/chrome.css";
-```
-
-For non-Tailwind sites, use the legacy single import:
-
-```css
-@import "@riverbankcms/sdk/preview-next/styles.css";
-```
-
-## Environment Variables
-
-For Vercel preview or any external preview host:
-
-```bash
-RIVERBANK_PREVIEW_MODE=true
-RIVERBANK_ENV=remote
-RIVERBANK_REMOTE_SITE_ID=...
-RIVERBANK_REMOTE_DASHBOARD_URL=https://...
-RIVERBANK_REMOTE_PREVIEW_API_KEY=bld_preview_sk_...
-```
-
-Use a preview API key when `RIVERBANK_PREVIEW_MODE=true`; content/live keys cannot read draft content. Keep the management API key (`RIVERBANK_REMOTE_MGMT_API_KEY`) for CLI sync commands such as `push-config`, not for public rendering.
-
-## Verification
-
-1. Run `riverbankcms push-config --env=remote`.
-2. Build the site with `RIVERBANK_PREVIEW_MODE=true`.
-3. Open the dashboard preview button.
-4. Confirm the URL starts at `previewUrl`.
-5. Confirm the preview shell loads and editable content appears.
-6. Confirm `/api/preview/keep-alive` returns without authentication errors during the session.