@riverbankcms/sdk 0.6.1 → 0.7.2

package/dist/server/next.d.ts

@@ -0,0 +1,432 @@
+import { ReactNode, ComponentType } from 'react';
+import { R as RiverbankClient } from './types-DnkRh0UL.js';
+import { R as RiverbankSiteConfig } from './types-DLBhEPSt.js';
+import { B as BlockOverrides } from './loadPage-i2r-X5b9.js';
+import './schema-Z6-afHJG.js';
+import { M as Metadata } from './index-CJk9iQQW.js';
+import { b as LoadContentResult } from './loadContent-CXUWMuzY.js';
+import './types-CVykEqXN.js';
+import '@riverbankcms/ai';
+import 'zod';
+import './link-DjxLyC82.js';
+import '@riverbankcms/media-storage-supabase';
+import '@riverbankcms/db';
+import './blockKinds-B6MWzNWp.js';
+import 'react/jsx-runtime';
+import './core-DsNWrl3o.js';
+import './types-DuQCNVV0.js';
+
+/**
+ * Type definitions for Next.js integration helpers.
+ *
+ * These types define the options and props for the `createCatchAllPage()` factory,
+ * which simplifies catch-all routing for Riverbank CMS sites.
+ */
+
+/**
+ * Context passed to escape hatch callbacks.
+ */
+interface CatchAllContext {
+    /** Loaded content (page or entry) */
+    content: LoadContentResult;
+    /** Resolved URL path (e.g., '/about', '/blog/my-post') */
+    path: string;
+    /** Whether preview mode is enabled */
+    preview: boolean;
+    /** Search parameters from the URL (for filtering, pagination, etc.) */
+    searchParams: Record<string, string | string[] | undefined>;
+}
+/**
+ * Options for the `createCatchAllPage()` factory.
+ *
+ * @example Basic usage
+ * ```tsx
+ * const { Page, generateMetadata } = createCatchAllPage({
+ *   getClient: getRiverbankClient,
+ *   config,
+ *   blockOverrides: { hero: MyCustomHero },
+ * });
+ * ```
+ *
+ * @example With maintenance mode
+ * ```tsx
+ * const { Page, generateMetadata } = createCatchAllPage({
+ *   getClient,
+ *   config,
+ *   beforeRender: async () => {
+ *     if (process.env.MAINTENANCE_MODE === 'true') {
+ *       return <MaintenancePage />;
+ *     }
+ *     return null; // Continue with normal rendering
+ *   },
+ * });
+ * ```
+ */
+interface CreateCatchAllPageOptions {
+    /**
+     * Function that returns the Riverbank client.
+     * Called fresh on each request to support different caching strategies.
+     */
+    getClient: () => RiverbankClient;
+    /**
+     * Site configuration from `defineConfig()`.
+     * Provides siteId and content type routing information.
+     */
+    config: RiverbankSiteConfig;
+    /**
+     * Custom block component overrides for rendering.
+     * Keys can be full block kind ("block.hero") or short form ("hero").
+     */
+    blockOverrides?: BlockOverrides;
+    /**
+     * Override site URL for metadata generation.
+     * Defaults to `config.liveUrl` or `config.previewUrl` based on preview mode.
+     */
+    siteUrl?: string;
+    /**
+     * Intercept before rendering to implement maintenance mode, access control, etc.
+     *
+     * Return a React node to short-circuit rendering, or `null` to continue
+     * with normal page/entry rendering.
+     *
+     * @example Maintenance mode
+     * ```tsx
+     * beforeRender: async () => {
+     *   if (process.env.MAINTENANCE_MODE === 'true') {
+     *     return <MaintenancePage />;
+     *   }
+     *   return null;
+     * }
+     * ```
+     *
+     * @example Access control
+     * ```tsx
+     * beforeRender: async ({ path }) => {
+     *   if (path.startsWith('/members')) {
+     *     const session = await getSession();
+     *     if (!session) return <LoginPage redirect={path} />;
+     *   }
+     *   return null;
+     * }
+     * ```
+     */
+    beforeRender?: (context: CatchAllContext) => ReactNode | null | Promise<ReactNode | null>;
+    /**
+     * Custom metadata generator. If provided, replaces default metadata generation.
+     *
+     * Use this when you need full control over SEO metadata, such as adding
+     * product-specific Open Graph tags for e-commerce sites.
+     *
+     * @example Custom product metadata
+     * ```tsx
+     * customMetadata: async ({ content }) => {
+     *   if (isEntryContent(content) && content.entry.type === 'product') {
+     *     return {
+     *       title: `${content.entry.title} | Shop`,
+     *       openGraph: { type: 'product' },
+     *     };
+     *   }
+     *   // Use default for other content types
+     *   return generatePageMetadata({ page, site, path, siteUrl });
+     * }
+     * ```
+     */
+    customMetadata?: (context: CatchAllContext) => Metadata | Promise<Metadata>;
+    /**
+     * Wrapper component around rendered content.
+     *
+     * Useful for adding analytics scripts, error boundaries, or layout wrappers
+     * that should wrap all page content.
+     *
+     * @example Analytics wrapper
+     * ```tsx
+     * wrapper: ({ children }) => (
+     *   <>
+     *     {children}
+     *     <AnalyticsScript siteId={config.siteId} />
+     *   </>
+     * )
+     * ```
+     */
+    wrapper?: ComponentType<{
+        children: ReactNode;
+    }>;
+}
+/**
+ * Next.js page props for catch-all routes.
+ *
+ * This matches the signature expected by Next.js 15+ App Router pages
+ * with the `[[...slug]]` pattern.
+ */
+interface CatchAllPageProps {
+    /** Route parameters containing the slug segments */
+    params: Promise<{
+        slug?: string[];
+    }>;
+    /** Optional search parameters from the URL */
+    searchParams?: Promise<Record<string, string | string[] | undefined>>;
+}
+/**
+ * Result of the `createCatchAllPage()` factory.
+ */
+interface CreateCatchAllPageResult {
+    /**
+     * React component to use as the default export of your catch-all page.
+     *
+     * @example
+     * ```tsx
+     * const { Page, generateMetadata } = createCatchAllPage({ ... });
+     * export default Page;
+     * ```
+     */
+    Page: (props: CatchAllPageProps) => Promise<ReactNode>;
+    /**
+     * Metadata generation function for Next.js `generateMetadata`.
+     *
+     * @example
+     * ```tsx
+     * const { Page, generateMetadata } = createCatchAllPage({ ... });
+     * export { generateMetadata };
+     * ```
+     */
+    generateMetadata: (props: CatchAllPageProps) => Promise<Metadata>;
+}
+
+/**
+ * Next.js catch-all page factory for Riverbank CMS.
+ *
+ * Provides a simple, opinionated way to render CMS content in Next.js catch-all routes.
+ * Reduces typical page.tsx boilerplate from ~160 lines to ~10 lines.
+ *
+ * @example
+ * ```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: { hero: MyCustomHero },
+ * });
+ *
+ * export default Page;
+ * export { generateMetadata };
+ * ```
+ */
+
+/**
+ * Factory function to create a Next.js catch-all page component and metadata generator.
+ *
+ * This provides a simple, opinionated setup for rendering Riverbank CMS content
+ * in external SDK sites. It handles:
+ *
+ * - Page and content entry routing
+ * - Preview mode detection (via `RIVERBANK_PREVIEW_MODE` env var)
+ * - SEO metadata generation
+ * - Block overrides for custom components
+ * - 404 handling for missing content
+ *
+ * ## Escape Hatches
+ *
+ * For customization beyond the defaults, use these options:
+ *
+ * - `beforeRender`: Intercept before rendering (maintenance mode, access control)
+ * - `customMetadata`: Full control over SEO metadata
+ * - `wrapper`: Wrap all content (analytics, error boundaries)
+ *
+ * For maximum control, use the lower-level helpers directly:
+ * - `loadContent()` from `@riverbankcms/sdk/rendering`
+ * - `Page` component from `@riverbankcms/sdk/rendering`
+ * - `generatePageMetadata()` from `@riverbankcms/sdk/metadata`
+ *
+ * @param options - Configuration options
+ * @returns Object with `Page` component and `generateMetadata` function
+ *
+ * @example Basic usage
+ * ```tsx
+ * const { Page, generateMetadata } = createCatchAllPage({
+ *   getClient: getRiverbankClient,
+ *   config,
+ * });
+ *
+ * export default Page;
+ * export { generateMetadata };
+ * ```
+ *
+ * @example With maintenance mode
+ * ```tsx
+ * const { Page, generateMetadata } = createCatchAllPage({
+ *   getClient,
+ *   config,
+ *   beforeRender: async () => {
+ *     if (process.env.MAINTENANCE_MODE === 'true') {
+ *       return <MaintenancePage />;
+ *     }
+ *     return null;
+ *   },
+ * });
+ * ```
+ */
+declare function createCatchAllPage(options: CreateCatchAllPageOptions): CreateCatchAllPageResult;
+
+/**
+ * Static params generation for Next.js SSG
+ *
+ * Provides helpers for generating static params from published CMS routes.
+ *
+ * @example
+ * ```tsx
+ * // app/[[...slug]]/page.tsx
+ * import { generateAllStaticParams } from '@riverbankcms/sdk/next';
+ *
+ * export { generateAllStaticParams as generateStaticParams };
+ * ```
+ */
+/**
+ * Environment variable validation result
+ */
+type StaticParamsEnvResult = {
+    valid: true;
+    config: {
+        apiKey: string;
+        siteId: string;
+        baseUrl: string;
+    };
+} | {
+    valid: false;
+    missingVars: string[];
+};
+/**
+ * Validate that all required environment variables are set.
+ *
+ * Required env vars:
+ * - RIVERBANK_API_KEY: API key for published content
+ * - RIVERBANK_SITE_ID: Site ID
+ * - NEXT_PUBLIC_DASHBOARD_URL: Dashboard API URL
+ *
+ * @returns Validation result with config or missing vars
+ */
+declare function validateStaticParamsEnv(): StaticParamsEnvResult;
+/**
+ * Convert a route path to a Next.js slug array.
+ *
+ * @param path - The route path (e.g., '/about', '/blog/post')
+ * @returns The slug array for Next.js catch-all route
+ *
+ * @example
+ * ```ts
+ * pathToSlugArray('/')           // []
+ * pathToSlugArray('/about')      // ['about']
+ * pathToSlugArray('/blog/post')  // ['blog', 'post']
+ * ```
+ */
+declare function pathToSlugArray(path: string): string[];
+/**
+ * Generate static params for all published routes.
+ *
+ * This function fetches all published routes from the CMS and converts them
+ * to the static params format expected by Next.js catch-all routes.
+ *
+ * Requires environment variables:
+ * - RIVERBANK_API_KEY: API key for published content
+ * - RIVERBANK_SITE_ID: Site ID
+ * - NEXT_PUBLIC_DASHBOARD_URL: Dashboard API URL
+ *
+ * @throws Error if required env vars are missing (prevents silent empty SSG in CI)
+ * @returns Array of static params objects for Next.js
+ *
+ * @example
+ * ```tsx
+ * // app/[[...slug]]/page.tsx
+ * import { generateAllStaticParams } from '@riverbankcms/sdk/next';
+ *
+ * export { generateAllStaticParams as generateStaticParams };
+ *
+ * // Or with custom logic:
+ * export async function generateStaticParams() {
+ *   const params = await generateAllStaticParams();
+ *   // Filter or modify params as needed
+ *   return params.filter(p => !p.slug.includes('private'));
+ * }
+ * ```
+ */
+declare function generateAllStaticParams(): Promise<{
+    slug: string[];
+}[]>;
+
+/**
+ * Next.js integration helpers for Riverbank CMS SDK.
+ *
+ * Provides opinionated factories for common Next.js patterns, reducing
+ * boilerplate while maintaining full customizability through escape hatches.
+ *
+ * @example Basic catch-all page
+ * ```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,
+ * });
+ *
+ * export default Page;
+ * export { generateMetadata };
+ * ```
+ *
+ * @example With customization
+ * ```tsx
+ * const { Page, generateMetadata } = createCatchAllPage({
+ *   getClient,
+ *   config,
+ *   blockOverrides: { hero: MyCustomHero },
+ *   beforeRender: async () => {
+ *     if (process.env.MAINTENANCE_MODE === 'true') {
+ *       return <MaintenancePage />;
+ *     }
+ *     return null;
+ *   },
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * ISR revalidation duration in seconds for production mode.
+ * 5 minutes provides a good balance between freshness and performance.
+ */
+declare const ISR_REVALIDATE_SECONDS = 300;
+interface ISRConfig {
+    /**
+     * Revalidation interval in seconds.
+     * - 0: Dynamic rendering (no caching) - used in preview mode
+     * - 300: 5 minute ISR - used in production mode
+     */
+    revalidate: number | false;
+    /**
+     * Whether the current environment is in preview mode.
+     * Useful for conditional rendering or data fetching behavior.
+     */
+    isPreview: boolean;
+}
+/**
+ * Get ISR configuration based on the current environment.
+ *
+ * @example
+ * ```tsx
+ * // app/[[...slug]]/page.tsx
+ * import { getISRConfig } from '@riverbankcms/sdk/next';
+ *
+ * export const revalidate = getISRConfig().revalidate;
+ * ```
+ *
+ * @returns ISR configuration with revalidate interval and preview flag
+ */
+declare function getISRConfig(): ISRConfig;
+
+export { type CatchAllContext, type CatchAllPageProps, type CreateCatchAllPageOptions, type CreateCatchAllPageResult, type ISRConfig, ISR_REVALIDATE_SECONDS, type StaticParamsEnvResult, createCatchAllPage, generateAllStaticParams, getISRConfig, pathToSlugArray, validateStaticParamsEnv };

package/dist/server/next.js

@@ -0,0 +1,217 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
+
+
+var _chunkBNQV3PXPjs = require('./chunk-BNQV3PXP.js');
+
+
+var _chunkWYNEYDXOjs = require('./chunk-WYNEYDXO.js');
+
+
+var _chunkHMENX4Y7js = require('./chunk-HMENX4Y7.js');
+
+
+
+
+var _chunkJWRNMNWIjs = require('./chunk-JWRNMNWI.js');
+
+
+var _chunkT26N3P26js = require('./chunk-T26N3P26.js');
+require('./chunk-7UPVCT3K.js');
+require('./chunk-RVDS7VSP.js');
+require('./chunk-YYO3RIFO.js');
+
+// src/next/catch-all.tsx
+var _navigation = require('next/navigation');
+var _jsxruntime = require('react/jsx-runtime');
+function isPreviewMode2() {
+  return process.env.RIVERBANK_PREVIEW_MODE === "true";
+}
+function slugToPath(slug) {
+  if (!slug || slug.length === 0) return "/";
+  return "/" + slug.join("/");
+}
+function createCatchAllPage(options) {
+  const {
+    getClient,
+    config,
+    blockOverrides,
+    siteUrl,
+    beforeRender,
+    customMetadata,
+    wrapper: Wrapper
+  } = options;
+  async function Page2({ params, searchParams: searchParamsPromise }) {
+    const [{ slug }, searchParams] = await Promise.all([
+      params,
+      _nullishCoalesce(searchParamsPromise, () => ( Promise.resolve({})))
+    ]);
+    const path = slugToPath(slug);
+    const preview = isPreviewMode2();
+    const client = getClient();
+    let content;
+    try {
+      content = await _chunkJWRNMNWIjs.loadContent.call(void 0, {
+        client,
+        siteId: config.siteId,
+        path,
+        preview
+      });
+    } catch (error) {
+      console.debug("[createCatchAllPage] Failed to load content for path:", path, error);
+      return _navigation.notFound.call(void 0, );
+    }
+    if (beforeRender) {
+      const intercepted = await beforeRender({ content, path, preview, searchParams });
+      if (intercepted !== null) {
+        return Wrapper ? /* @__PURE__ */ _jsxruntime.jsx.call(void 0, Wrapper, { children: intercepted }) : intercepted;
+      }
+    }
+    let rendered;
+    if (_chunkJWRNMNWIjs.isPageContent.call(void 0, content)) {
+      rendered = /* @__PURE__ */ _jsxruntime.jsx.call(void 0, 
+        _chunkT26N3P26js.Page,
+        {
+          page: content.page,
+          theme: content.theme,
+          siteId: content.siteId,
+          resolvedData: content.resolvedData,
+          blockOverrides
+        }
+      );
+    } else if (_chunkJWRNMNWIjs.isEntryContent.call(void 0, content)) {
+      if (!content.templatePage) {
+        return _navigation.notFound.call(void 0, );
+      }
+      rendered = /* @__PURE__ */ _jsxruntime.jsx.call(void 0, 
+        _chunkT26N3P26js.Page,
+        {
+          page: content.templatePage,
+          theme: content.theme,
+          siteId: content.siteId,
+          resolvedData: content.resolvedData,
+          blockOverrides,
+          dataContext: {
+            contentEntry: content.dataContext.contentEntry
+          }
+        }
+      );
+    } else {
+      return _navigation.notFound.call(void 0, );
+    }
+    return Wrapper ? /* @__PURE__ */ _jsxruntime.jsx.call(void 0, Wrapper, { children: rendered }) : rendered;
+  }
+  async function generateMetadataFn({ params, searchParams: searchParamsPromise }) {
+    const [{ slug }, searchParams] = await Promise.all([
+      params,
+      _nullishCoalesce(searchParamsPromise, () => ( Promise.resolve({})))
+    ]);
+    const path = slugToPath(slug);
+    const preview = isPreviewMode2();
+    try {
+      const content = await _chunkJWRNMNWIjs.loadContent.call(void 0, {
+        client: getClient(),
+        siteId: config.siteId,
+        path,
+        preview
+      });
+      if (customMetadata) {
+        return customMetadata({ content, path, preview, searchParams });
+      }
+      const resolvedUrl = _nullishCoalesce(_nullishCoalesce(siteUrl, () => ( (preview ? config.previewUrl : config.liveUrl))), () => ( ""));
+      if (!resolvedUrl) {
+        console.warn(
+          "[createCatchAllPage] No siteUrl configured. OpenGraph and Twitter tags will have relative URLs which may cause social sharing previews to fail. Set siteUrl option, or config.liveUrl/config.previewUrl in your riverbank.config."
+        );
+      }
+      const page = _chunkJWRNMNWIjs.isPageContent.call(void 0, content) ? content.page : _chunkJWRNMNWIjs.isEntryContent.call(void 0, content) ? {
+        name: _nullishCoalesce(content.entry.metaTitle, () => ( content.entry.title)),
+        purpose: _nullishCoalesce(content.entry.metaDescription, () => ( void 0))
+      } : { name: "Page" };
+      const metadataGenerator = preview ? _chunkBNQV3PXPjs.generatePreviewMetadata : _chunkBNQV3PXPjs.generatePageMetadata;
+      return metadataGenerator({
+        page,
+        site: content.site,
+        path,
+        siteUrl: resolvedUrl
+      });
+    } catch (error) {
+      console.debug("[createCatchAllPage] Failed to generate metadata for path:", path, error);
+      return {
+        title: "Page Not Found",
+        robots: { index: false, follow: false }
+      };
+    }
+  }
+  return {
+    Page: Page2,
+    generateMetadata: generateMetadataFn
+  };
+}
+
+// src/rendering/hooks/usePage.ts
+var _react = require('react');
+
+// src/rendering/hooks/useContent.ts
+
+
+// src/next/static-params.ts
+function validateStaticParamsEnv() {
+  const apiKey = process.env.RIVERBANK_API_KEY;
+  const siteId = process.env.RIVERBANK_SITE_ID;
+  const baseUrl = process.env.NEXT_PUBLIC_DASHBOARD_URL;
+  const missingVars = [];
+  if (!apiKey) missingVars.push("RIVERBANK_API_KEY");
+  if (!siteId) missingVars.push("RIVERBANK_SITE_ID");
+  if (!baseUrl) missingVars.push("NEXT_PUBLIC_DASHBOARD_URL");
+  if (missingVars.length > 0) {
+    return { valid: false, missingVars };
+  }
+  return {
+    valid: true,
+    config: { apiKey, siteId, baseUrl }
+  };
+}
+function pathToSlugArray(path) {
+  if (path === "/") return [];
+  return path.slice(1).split("/");
+}
+async function generateAllStaticParams() {
+  const envResult = validateStaticParamsEnv();
+  if (!envResult.valid) {
+    throw new Error(
+      `[Riverbank] generateAllStaticParams requires env vars: ${envResult.missingVars.join(", ")}. This error prevents accidentally deploying with zero static pages.`
+    );
+  }
+  const { apiKey, siteId: _siteId, baseUrl } = envResult.config;
+  const _client = _chunkHMENX4Y7js.createRiverbankClient.call(void 0, {
+    apiKey,
+    baseUrl,
+    // Disable caching for build-time fetches
+    cache: { enabled: false },
+    // Disable resilience for build-time fetches (want fast failure)
+    resilience: { enabled: false }
+  });
+  console.warn(
+    "[Riverbank] generateAllStaticParams: getAllPublishedRoutes API not yet implemented. Pages will be generated on-demand with ISR."
+  );
+  return [{ slug: [] }];
+}
+
+// src/next/index.ts
+var ISR_REVALIDATE_SECONDS = 300;
+function getISRConfig() {
+  const preview = _chunkWYNEYDXOjs.isPreviewMode.call(void 0, );
+  return {
+    revalidate: preview ? 0 : ISR_REVALIDATE_SECONDS,
+    isPreview: preview
+  };
+}
+
+
+
+
+
+
+
+exports.ISR_REVALIDATE_SECONDS = ISR_REVALIDATE_SECONDS; exports.createCatchAllPage = createCatchAllPage; exports.generateAllStaticParams = generateAllStaticParams; exports.getISRConfig = getISRConfig; exports.pathToSlugArray = pathToSlugArray; exports.validateStaticParamsEnv = validateStaticParamsEnv;
+//# sourceMappingURL=next.js.map