@riverbankcms/sdk 0.7.2 → 0.7.4

package/dist/server/env.d.mts

@@ -1,15 +1,56 @@
 /**
  * Environment detection utilities for SDK
  *
- * Provides helpers for detecting preview mode and other environment states.
+ * Provides helpers for detecting preview mode and auto-selecting the correct API key.
+ *
+ * @example
+ * ```ts
+ * import { getRiverbankEnv } from '@riverbankcms/sdk/env';
+ * import { createRiverbankClient } from '@riverbankcms/sdk';
+ *
+ * const env = getRiverbankEnv();
+ * const client = createRiverbankClient({
+ *   apiKey: env.apiKey,
+ *   baseUrl: env.baseUrl,
+ * });
+ * ```
+ */
+/**
+ * Environment target: 'local' for development, 'remote' for production
+ */
+type RiverbankEnvTarget = 'local' | 'remote';
+/**
+ * Runtime environment configuration
  */
+interface RiverbankEnvConfig {
+    /** The detected environment target */
+    target: RiverbankEnvTarget;
+    /** Whether preview mode is enabled */
+    previewMode: boolean;
+    /** Site ID */
+    siteId: string;
+    /** Dashboard/API base URL */
+    baseUrl: string;
+    /** The auto-selected API key (preview or content key based on mode) */
+    apiKey: string;
+    /** The type of key being used */
+    keyType: 'preview' | 'content';
+}
+/**
+ * Error thrown when required environment variables are missing
+ */
+declare class RiverbankEnvError extends Error {
+    readonly missingVars: string[];
+    constructor(message: string, missingVars: string[]);
+}
 /**
  * Detects if the current environment is in preview mode.
  *
  * Precedence:
- * 1. RIVERBANK_PREVIEW env var (explicit override) - 'true' or 'false'
- * 2. VERCEL_ENV === 'preview' (Vercel preview deployments)
- * 3. Default: false (production behavior)
+ * 1. RIVERBANK_PREVIEW_MODE env var (explicit override) - 'true' or 'false'
+ * 2. RIVERBANK_PREVIEW env var (legacy) - 'true' or 'false'
+ * 3. VERCEL_ENV === 'preview' (Vercel preview deployments)
+ * 4. Default: false (production behavior)
  *
  * In preview mode:
  * - Draft content is visible
@@ -19,5 +60,50 @@
  * @returns true if in preview mode, false otherwise
  */
 declare function isPreviewMode(): boolean;
+/**
+ * Get the current environment target.
+ *
+ * This is a convenience function for checking `RIVERBANK_ENV`.
+ *
+ * @returns 'local' or 'remote'
+ */
+declare function getRiverbankTarget(): RiverbankEnvTarget;
+/**
+ * Get runtime environment configuration with automatic API key selection.
+ *
+ * This helper reads environment variables and automatically selects the correct
+ * API key based on the current environment and preview mode:
+ *
+ * - When `RIVERBANK_PREVIEW_MODE=true`: Uses preview API key (bld_preview_sk_...)
+ * - When `RIVERBANK_PREVIEW_MODE=false` (default): Uses content API key (bld_live_sk_...)
+ *
+ * Environment variable patterns:
+ * - `RIVERBANK_ENV`: 'local' (default) or 'remote'
+ * - `RIVERBANK_PREVIEW_MODE`: 'true' or 'false' (default)
+ * - `RIVERBANK_{LOCAL|REMOTE}_SITE_ID`: Site ID
+ * - `RIVERBANK_{LOCAL|REMOTE}_DASHBOARD_URL`: Dashboard URL
+ * - `RIVERBANK_{LOCAL|REMOTE}_API_KEY`: Content/live API key
+ * - `RIVERBANK_{LOCAL|REMOTE}_PREVIEW_API_KEY`: Preview API key
+ *
+ * @returns Environment configuration with auto-selected API key
+ * @throws {RiverbankEnvError} If required environment variables are missing
+ *
+ * @example
+ * ```ts
+ * // lib/builder-client.ts
+ * import { getRiverbankEnv } from '@riverbankcms/sdk/env';
+ * import { createRiverbankClient } from '@riverbankcms/sdk';
+ *
+ * const env = getRiverbankEnv();
+ *
+ * export const client = createRiverbankClient({
+ *   apiKey: env.apiKey,
+ *   baseUrl: env.baseUrl,
+ * });
+ *
+ * export const siteId = env.siteId;
+ * ```
+ */
+declare function getRiverbankEnv(): RiverbankEnvConfig;
 
-export { isPreviewMode };
+export { type RiverbankEnvConfig, RiverbankEnvError, type RiverbankEnvTarget, getRiverbankEnv, getRiverbankTarget, isPreviewMode };

package/dist/server/env.d.ts

@@ -1,15 +1,56 @@
 /**
  * Environment detection utilities for SDK
  *
- * Provides helpers for detecting preview mode and other environment states.
+ * Provides helpers for detecting preview mode and auto-selecting the correct API key.
+ *
+ * @example
+ * ```ts
+ * import { getRiverbankEnv } from '@riverbankcms/sdk/env';
+ * import { createRiverbankClient } from '@riverbankcms/sdk';
+ *
+ * const env = getRiverbankEnv();
+ * const client = createRiverbankClient({
+ *   apiKey: env.apiKey,
+ *   baseUrl: env.baseUrl,
+ * });
+ * ```
+ */
+/**
+ * Environment target: 'local' for development, 'remote' for production
+ */
+type RiverbankEnvTarget = 'local' | 'remote';
+/**
+ * Runtime environment configuration
  */
+interface RiverbankEnvConfig {
+    /** The detected environment target */
+    target: RiverbankEnvTarget;
+    /** Whether preview mode is enabled */
+    previewMode: boolean;
+    /** Site ID */
+    siteId: string;
+    /** Dashboard/API base URL */
+    baseUrl: string;
+    /** The auto-selected API key (preview or content key based on mode) */
+    apiKey: string;
+    /** The type of key being used */
+    keyType: 'preview' | 'content';
+}
+/**
+ * Error thrown when required environment variables are missing
+ */
+declare class RiverbankEnvError extends Error {
+    readonly missingVars: string[];
+    constructor(message: string, missingVars: string[]);
+}
 /**
  * Detects if the current environment is in preview mode.
  *
  * Precedence:
- * 1. RIVERBANK_PREVIEW env var (explicit override) - 'true' or 'false'
- * 2. VERCEL_ENV === 'preview' (Vercel preview deployments)
- * 3. Default: false (production behavior)
+ * 1. RIVERBANK_PREVIEW_MODE env var (explicit override) - 'true' or 'false'
+ * 2. RIVERBANK_PREVIEW env var (legacy) - 'true' or 'false'
+ * 3. VERCEL_ENV === 'preview' (Vercel preview deployments)
+ * 4. Default: false (production behavior)
  *
  * In preview mode:
  * - Draft content is visible
@@ -19,5 +60,50 @@
  * @returns true if in preview mode, false otherwise
  */
 declare function isPreviewMode(): boolean;
+/**
+ * Get the current environment target.
+ *
+ * This is a convenience function for checking `RIVERBANK_ENV`.
+ *
+ * @returns 'local' or 'remote'
+ */
+declare function getRiverbankTarget(): RiverbankEnvTarget;
+/**
+ * Get runtime environment configuration with automatic API key selection.
+ *
+ * This helper reads environment variables and automatically selects the correct
+ * API key based on the current environment and preview mode:
+ *
+ * - When `RIVERBANK_PREVIEW_MODE=true`: Uses preview API key (bld_preview_sk_...)
+ * - When `RIVERBANK_PREVIEW_MODE=false` (default): Uses content API key (bld_live_sk_...)
+ *
+ * Environment variable patterns:
+ * - `RIVERBANK_ENV`: 'local' (default) or 'remote'
+ * - `RIVERBANK_PREVIEW_MODE`: 'true' or 'false' (default)
+ * - `RIVERBANK_{LOCAL|REMOTE}_SITE_ID`: Site ID
+ * - `RIVERBANK_{LOCAL|REMOTE}_DASHBOARD_URL`: Dashboard URL
+ * - `RIVERBANK_{LOCAL|REMOTE}_API_KEY`: Content/live API key
+ * - `RIVERBANK_{LOCAL|REMOTE}_PREVIEW_API_KEY`: Preview API key
+ *
+ * @returns Environment configuration with auto-selected API key
+ * @throws {RiverbankEnvError} If required environment variables are missing
+ *
+ * @example
+ * ```ts
+ * // lib/builder-client.ts
+ * import { getRiverbankEnv } from '@riverbankcms/sdk/env';
+ * import { createRiverbankClient } from '@riverbankcms/sdk';
+ *
+ * const env = getRiverbankEnv();
+ *
+ * export const client = createRiverbankClient({
+ *   apiKey: env.apiKey,
+ *   baseUrl: env.baseUrl,
+ * });
+ *
+ * export const siteId = env.siteId;
+ * ```
+ */
+declare function getRiverbankEnv(): RiverbankEnvConfig;
 
-export { isPreviewMode };
+export { type RiverbankEnvConfig, RiverbankEnvError, type RiverbankEnvTarget, getRiverbankEnv, getRiverbankTarget, isPreviewMode };

package/dist/server/env.js

@@ -1,7 +1,14 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunkWYNEYDXOjs = require('./chunk-WYNEYDXO.js');
 
 
-exports.isPreviewMode = _chunkWYNEYDXOjs.isPreviewMode;
+
+var _chunk2IZ6S225js = require('./chunk-2IZ6S225.js');
+require('./chunk-4CV4JOE5.js');
+
+
+
+
+
+exports.RiverbankEnvError = _chunk2IZ6S225js.RiverbankEnvError; exports.getRiverbankEnv = _chunk2IZ6S225js.getRiverbankEnv; exports.getRiverbankTarget = _chunk2IZ6S225js.getRiverbankTarget; exports.isPreviewMode = _chunk2IZ6S225js.isPreviewMode;
 //# sourceMappingURL=env.js.map

package/dist/server/env.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/will/Projects/Business/cms/builder/packages/sdk/dist/server/env.js"],"names":[],"mappings":"AAAA;AACE;AACF,sDAA4B;AAC5B;AACE;AACF,uDAAC","file":"/Users/will/Projects/Business/cms/builder/packages/sdk/dist/server/env.js"}
+{"version":3,"sources":["/Users/will/Projects/Business/cms/builder/packages/sdk/dist/server/env.js"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACF,sDAA4B;AAC5B,+BAA4B;AAC5B;AACE;AACA;AACA;AACA;AACF,qPAAC","file":"/Users/will/Projects/Business/cms/builder/packages/sdk/dist/server/env.js"}

package/dist/server/env.mjs

@@ -1,7 +1,14 @@
 import {
+  RiverbankEnvError,
+  getRiverbankEnv,
+  getRiverbankTarget,
   isPreviewMode
-} from "./chunk-LQUKXIW7.mjs";
+} from "./chunk-PPHZV6YD.mjs";
+import "./chunk-NFEGQTCC.mjs";
 export {
+  RiverbankEnvError,
+  getRiverbankEnv,
+  getRiverbankTarget,
   isPreviewMode
 };
 //# sourceMappingURL=env.mjs.map

package/dist/server/{index-BL66CU6d.d.mts → index--Oyunk_B.d.mts}

@@ -1,5 +1,5 @@
-import { a as LoadPageResult } from './loadPage-CxlYLe5K.mjs';
-import { S as SiteResponse } from './types-MF2AWoKv.mjs';
+import { a as LoadPageResult } from './loadPage-BucnLHmE.mjs';
+import { S as SiteResponse } from './types-C-LShyIg.mjs';
 
 /**
  * Metadata generation helper for Next.js pages

package/dist/server/{index-CJk9iQQW.d.ts → index-C9Ra8dza.d.ts}

@@ -1,5 +1,5 @@
-import { a as LoadPageResult } from './loadPage-i2r-X5b9.js';
-import { S as SiteResponse } from './types-DnkRh0UL.js';
+import { a as LoadPageResult } from './loadPage-BmYJCe_V.js';
+import { S as SiteResponse } from './types-BRQyLrQU.js';
 
 /**
  * Metadata generation helper for Next.js pages

package/dist/server/{index-Bkva0WAj.d.mts → index-Clm3skz_.d.mts}

@@ -1,4 +1,4 @@
-import { a as RiverbankClientConfig, R as RiverbankClient } from './types-MF2AWoKv.mjs';
+import { a as RiverbankClientConfig, R as RiverbankClient } from './types-C-LShyIg.mjs';
 import './schema-Z6-afHJG.mjs';
 
 /**

package/dist/server/{index-CSBWKA3r.d.ts → index-DLvNddi-.d.ts}

@@ -1,4 +1,4 @@
-import { a as RiverbankClientConfig, R as RiverbankClient } from './types-DnkRh0UL.js';
+import { a as RiverbankClientConfig, R as RiverbankClient } from './types-BRQyLrQU.js';
 import './schema-Z6-afHJG.js';
 
 /**

package/dist/server/index.d.mts

@@ -1,6 +1,7 @@
-export { c as createRiverbankClient } from './index-Bkva0WAj.mjs';
-export { E as EntriesResponse, c as EntriesResponseWithMeta, b as EntryResponse, P as PageResponse, d as PaginationMeta, R as RiverbankClient, a as RiverbankClientConfig, S as SiteResponse } from './types-MF2AWoKv.mjs';
-import { A as APIEndpoints, b as APICallParams } from './types-Dsu9wsUh.mjs';
+export { c as createRiverbankClient } from './index-Clm3skz_.mjs';
+import { R as RiverbankClient, S as SiteResponse, P as PageResponse, G as GetEntriesBaseParams, E as EntriesResponse, d as EntriesResponseWithMeta } from './types-C-LShyIg.mjs';
+export { j as CircuitBreakerConfig, C as CircuitState, b as EntryResponse, e as PaginationMeta, f as ResilienceConfig, h as ResilienceSource, g as ResilienceStatus, i as RetryConfig, a as RiverbankClientConfig } from './types-C-LShyIg.mjs';
+import { A as APIEndpoints, b as APICallParams, a as NavigationItemRecord } from './types-BSV6Vc-P.mjs';
 import './schema-Z6-afHJG.mjs';
 export { g as ContainerAlignment, f as ContainerMaxWidth, d as ContainerOptionsConfig, R as RiverbankSiteConfig, b as SectionBackground, c as SectionOptionsConfig, e as SectionSpacing, S as SiteStyleConfig } from './types-BjgZt8xJ.mjs';
 export { B as BlockKind, C as CustomBlockKind, S as SYSTEM_BLOCK_KINDS, a as SystemBlockKind } from './blockKinds-B6MWzNWp.mjs';
@@ -1644,4 +1645,214 @@ declare const API_ENDPOINTS: {
 };
 declare function buildEndpointURL(baseURL: string, endpoint: keyof APIEndpoints): string;
 
-export { API_ENDPOINTS, type ApiClient, buildEndpointURL };
+/**
+ * Types for prebuild cache functionality
+ *
+ * The prebuild cache generates static JSON files at build time that serve
+ * as a last-resort fallback when the CMS is unavailable.
+ */
+
+/**
+ * Content types that can be included in the prebuild cache.
+ */
+type PrebuildContentType = 'site' | 'pages' | 'entries' | 'navigation';
+/**
+ * Progress callback data for prebuild operations.
+ */
+interface PrebuildProgress {
+    /** Current item number (1-indexed) */
+    current: number;
+    /** Total items to process */
+    total: number;
+    /** Description of current item being processed */
+    item: string;
+    /** Content type being processed */
+    contentType: PrebuildContentType;
+}
+/**
+ * Options for the prebuildCache function.
+ */
+interface PrebuildOptions {
+    /** Configured Riverbank client */
+    client: RiverbankClient;
+    /** Site ID to prebuild */
+    siteId: string;
+    /** Output directory for prebuild cache (e.g., '.riverbank-cache') */
+    outputDir: string;
+    /** Content types to include (default: all) */
+    include?: PrebuildContentType[];
+    /** Filter entries to specific content types (default: all configured) */
+    contentTypes?: string[];
+    /** Gzip compress output files (default: false) */
+    compress?: boolean;
+    /** Progress callback fired during generation */
+    onProgress?: (progress: PrebuildProgress) => void;
+}
+/**
+ * Result from prebuildCache function.
+ */
+interface PrebuildResult {
+    /** Whether prebuild completed successfully */
+    success: boolean;
+    /** Output directory path */
+    outputDir: string;
+    /** List of generated files (relative to outputDir) */
+    files: string[];
+    /** Total size of all files in bytes */
+    totalSize: number;
+    /** ISO timestamp when prebuild was generated */
+    generatedAt: string;
+    /** SHA256 checksum of manifest for validation */
+    checksum: string;
+    /** Any errors encountered (partial success possible) */
+    errors?: string[];
+}
+/**
+ * Manifest file structure for prebuild cache.
+ */
+interface PrebuildManifest {
+    /** Manifest version for compatibility checking */
+    version: string;
+    /** ISO timestamp when prebuild was generated */
+    generatedAt: string;
+    /** SHA256 checksum of manifest contents (excluding checksum field) */
+    checksum: string;
+    /** Site ID this prebuild is for */
+    siteId: string;
+    /** SDK version used to generate prebuild */
+    sdkVersion: string;
+    /** Mapping of cache keys to file paths */
+    keyToFile: Record<string, string>;
+    /** Content types included in this prebuild */
+    includedTypes: PrebuildContentType[];
+    /** Total number of files generated */
+    fileCount: number;
+    /** Total size in bytes */
+    totalSize: number;
+}
+/**
+ * Navigation cache file structure.
+ */
+interface NavigationCacheFile {
+    /** Navigation menu data */
+    menus: Array<{
+        /** Menu identifier (used as lookup key) */
+        identifier: string | null;
+        /** Menu ID (fallback if no identifier) */
+        id: string;
+        /** Menu display name */
+        name: string;
+        /** Navigation items in this menu */
+        items: NavigationItemRecord[];
+    }>;
+    /** When this was generated */
+    generatedAt: string;
+}
+
+/**
+ * Prebuild cache generation
+ *
+ * Exports static content at build time for use as a last-resort fallback
+ * when the CMS is unavailable.
+ */
+
+/**
+ * Generate a prebuild cache for the specified site.
+ *
+ * The prebuild cache contains static JSON files that can serve as a
+ * last-resort fallback when the CMS is unavailable.
+ *
+ * @param options - Prebuild configuration
+ * @returns Result with generated files and metadata
+ *
+ * @example
+ * ```typescript
+ * import { createRiverbankClient, prebuildCache } from '@riverbankcms/sdk';
+ *
+ * const client = createRiverbankClient({ apiKey, baseUrl });
+ *
+ * const result = await prebuildCache({
+ *   client,
+ *   siteId: 'your-site-id',
+ *   outputDir: '.riverbank-cache',
+ *   onProgress: (p) => console.log(`${p.current}/${p.total}: ${p.item}`),
+ * });
+ *
+ * console.log(`Generated ${result.files.length} files (${result.totalSize} bytes)`);
+ * ```
+ */
+declare function prebuildCache(options: PrebuildOptions): Promise<PrebuildResult>;
+
+/**
+ * Prebuild cache loader
+ *
+ * Loads content from the prebuild cache at runtime as a last-resort fallback.
+ */
+
+interface PrebuildLoaderConfig {
+    /** Path to prebuild cache directory */
+    prebuildDir: string;
+    /** Maximum age in seconds for prebuild cache */
+    maxPrebuildAgeSec?: number;
+}
+interface LoadResult<T> {
+    /** Loaded data */
+    data: T;
+    /** Age of prebuild in seconds */
+    prebuildAgeSec: number;
+}
+/**
+ * Check if we're running in a Node.js environment with filesystem access.
+ * Edge runtimes (Vercel Edge, Cloudflare Workers) don't have fs access.
+ */
+declare function canUsePrebuild(): boolean;
+/**
+ * Loader for reading data from the prebuild cache.
+ *
+ * Used as a last-resort fallback when the CMS is unavailable and
+ * there's no cached data.
+ */
+declare class PrebuildLoader {
+    private readonly prebuildDir;
+    private readonly maxPrebuildAgeSec;
+    constructor(config: PrebuildLoaderConfig);
+    /**
+     * Check if prebuild is available and not expired.
+     */
+    isAvailable(): boolean;
+    /**
+     * Load site data from prebuild cache.
+     */
+    loadSite(siteId: string): LoadResult<SiteResponse> | null;
+    /**
+     * Load page data from prebuild cache.
+     */
+    loadPage(siteId: string, pagePath: string): LoadResult<PageResponse> | null;
+    /**
+     * Load entries from prebuild cache with runtime filtering.
+     *
+     * The prebuild stores ALL entries for each content type.
+     * Filtering, ordering, and pagination are applied at runtime.
+     */
+    loadEntries(siteId: string, params: GetEntriesBaseParams & {
+        includeMeta?: boolean;
+    }): LoadResult<EntriesResponse | EntriesResponseWithMeta> | null;
+    /**
+     * Load navigation data from prebuild cache.
+     */
+    loadNavigation(): LoadResult<NavigationCacheFile['menus']> | null;
+    /**
+     * Get the manifest for inspection.
+     */
+    getManifest(): PrebuildManifest | null;
+    /**
+     * Clear the cached manifest (for testing).
+     */
+    clearCache(): void;
+}
+/**
+ * Create a prebuild loader instance.
+ */
+declare function createPrebuildLoader(config: PrebuildLoaderConfig): PrebuildLoader;
+
+export { API_ENDPOINTS, type ApiClient, EntriesResponse, EntriesResponseWithMeta, type LoadResult, PageResponse, type PrebuildContentType, PrebuildLoader, type PrebuildLoaderConfig, type PrebuildManifest, type PrebuildOptions, type PrebuildProgress, type PrebuildResult, RiverbankClient, SiteResponse, buildEndpointURL, canUsePrebuild, createPrebuildLoader, prebuildCache };