@riverbankcms/sdk 0.3.0 → 0.4.1

package/dist/server/{types-_nDnPHpv.d.mts → types-CbagRQ_7.d.mts}

@@ -1,3 +1,5 @@
+import { B as BlockKind } from './blockKinds-B6MWzNWp.mjs';
+
 /**
  * Data loading types for block prefetching.
  * Shared between frontend and SDK implementations.
@@ -30,6 +32,7 @@ type ResolvedBlockData = Record<string, Record<string, unknown>>;
  * These types enable SDK sites to define loader functions that fetch
  * data from external APIs (not just CMS endpoints).
  */
+
 /**
  * Context provided to code-based data loaders.
  *
@@ -44,7 +47,7 @@ interface DataLoaderContext {
     /** Unique block instance ID */
     blockId: string;
     /** Block kind (e.g., 'custom.featured-products') */
-    blockKind: string;
+    blockKind: BlockKind;
     /**
      * The block's CMS content.
      * Use this to access field values for parameterizing API calls.
@@ -52,6 +55,21 @@ interface DataLoaderContext {
     content: Record<string, unknown>;
     /** Whether fetching preview/draft content */
     previewStage: 'published' | 'preview';
+    /**
+     * URL search parameters from the page request.
+     * Use for pagination, filtering, or sorting based on URL params.
+     *
+     * Always defined (defaults to empty object if not provided to loadPage).
+     * This allows loaders to safely access properties without null checks.
+     *
+     * @example
+     * ```typescript
+     * const page = parseInt(searchParams?.page as string || '1', 10);
+     * const limit = parseInt(content.postsPerPage as string || '12', 10);
+     * const offset = (page - 1) * limit;
+     * ```
+     */
+    searchParams: Record<string, string | string[] | undefined>;
 }
 /**
  * A code-based data loader function.

package/dist/server/{types-_nDnPHpv.d.ts → types-DuQCNVV0.d.ts}

@@ -1,3 +1,5 @@
+import { B as BlockKind } from './blockKinds-B6MWzNWp.js';
+
 /**
  * Data loading types for block prefetching.
  * Shared between frontend and SDK implementations.
@@ -30,6 +32,7 @@ type ResolvedBlockData = Record<string, Record<string, unknown>>;
  * These types enable SDK sites to define loader functions that fetch
  * data from external APIs (not just CMS endpoints).
  */
+
 /**
  * Context provided to code-based data loaders.
  *
@@ -44,7 +47,7 @@ interface DataLoaderContext {
     /** Unique block instance ID */
     blockId: string;
     /** Block kind (e.g., 'custom.featured-products') */
-    blockKind: string;
+    blockKind: BlockKind;
     /**
      * The block's CMS content.
      * Use this to access field values for parameterizing API calls.
@@ -52,6 +55,21 @@ interface DataLoaderContext {
     content: Record<string, unknown>;
     /** Whether fetching preview/draft content */
     previewStage: 'published' | 'preview';
+    /**
+     * URL search parameters from the page request.
+     * Use for pagination, filtering, or sorting based on URL params.
+     *
+     * Always defined (defaults to empty object if not provided to loadPage).
+     * This allows loaders to safely access properties without null checks.
+     *
+     * @example
+     * ```typescript
+     * const page = parseInt(searchParams?.page as string || '1', 10);
+     * const limit = parseInt(content.postsPerPage as string || '12', 10);
+     * const offset = (page - 1) * limit;
+     * ```
+     */
+    searchParams: Record<string, string | string[] | undefined>;
 }
 /**
  * A code-based data loader function.

package/dist/server/validation-C7W2Fe0i.d.ts

@@ -0,0 +1,459 @@
+import { z } from 'zod';
+import { S as SdkCustomBlock } from './schema-Bpy9N5ZI.js';
+import { C as ContentConfig, l as ContentTypeConfig, R as RiverbankSiteConfig, i as BlockFieldOptionsMap, j as BlockFieldExtension, k as BlockFieldExtensionsMap } from './types-CMqVHYLG.js';
+
+/**
+ * SDK Content Config Validation
+ *
+ * Zod schemas for validating SDK content configuration.
+ */
+
+/**
+ * Content type config schema.
+ */
+declare const contentTypeConfigSchema: z.ZodType<ContentTypeConfig>;
+declare const blockConfigSchema: z.ZodObject<{
+    kind: z.ZodString;
+    content: z.ZodRecord<z.ZodString, z.ZodAny>;
+    orderIndex: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const pageConfigSchema: z.ZodObject<{
+    identifier: z.ZodString;
+    title: z.ZodString;
+    path: z.ZodString;
+    purpose: z.ZodDefault<z.ZodString>;
+    blocks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        content: z.ZodRecord<z.ZodString, z.ZodAny>;
+        orderIndex: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    status: z.ZodDefault<z.ZodEnum<{
+        published: "published";
+        draft: "draft";
+    }>>;
+    metaTitle: z.ZodOptional<z.ZodString>;
+    metaDescription: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const entryConfigSchema: z.ZodObject<{
+    identifier: z.ZodString;
+    contentType: z.ZodString;
+    data: z.ZodRecord<z.ZodString, z.ZodAny>;
+    status: z.ZodDefault<z.ZodEnum<{
+        published: "published";
+        draft: "draft";
+    }>>;
+    slug: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    metaTitle: z.ZodOptional<z.ZodString>;
+    metaDescription: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const navigationItemConfigSchema: z.ZodType<{
+    label: string;
+    link: {
+        kind: 'page';
+        identifier: string;
+    } | {
+        kind: 'entry';
+        identifier: string;
+    } | {
+        kind: 'external';
+        href: string;
+    } | {
+        kind: 'dropdown';
+    };
+    isCta?: boolean;
+    children?: Array<{
+        label: string;
+        link: {
+            kind: 'page';
+            identifier: string;
+        } | {
+            kind: 'entry';
+            identifier: string;
+        } | {
+            kind: 'external';
+            href: string;
+        } | {
+            kind: 'dropdown';
+        };
+        isCta?: boolean;
+        children?: unknown[];
+    }>;
+}>;
+declare const navigationMenuConfigSchema: z.ZodObject<{
+    identifier: z.ZodString;
+    name: z.ZodString;
+    isPrimary: z.ZodOptional<z.ZodBoolean>;
+    items: z.ZodArray<z.ZodType<{
+        label: string;
+        link: {
+            kind: "page";
+            identifier: string;
+        } | {
+            kind: "entry";
+            identifier: string;
+        } | {
+            kind: "external";
+            href: string;
+        } | {
+            kind: "dropdown";
+        };
+        isCta?: boolean;
+        children?: Array<{
+            label: string;
+            link: {
+                kind: "page";
+                identifier: string;
+            } | {
+                kind: "entry";
+                identifier: string;
+            } | {
+                kind: "external";
+                href: string;
+            } | {
+                kind: "dropdown";
+            };
+            isCta?: boolean;
+            children?: unknown[];
+        }>;
+    }, unknown, z.core.$ZodTypeInternals<{
+        label: string;
+        link: {
+            kind: "page";
+            identifier: string;
+        } | {
+            kind: "entry";
+            identifier: string;
+        } | {
+            kind: "external";
+            href: string;
+        } | {
+            kind: "dropdown";
+        };
+        isCta?: boolean;
+        children?: Array<{
+            label: string;
+            link: {
+                kind: "page";
+                identifier: string;
+            } | {
+                kind: "entry";
+                identifier: string;
+            } | {
+                kind: "external";
+                href: string;
+            } | {
+                kind: "dropdown";
+            };
+            isCta?: boolean;
+            children?: unknown[];
+        }>;
+    }, unknown>>>;
+}, z.core.$strip>;
+declare const siteSettingsConfigSchema: z.ZodObject<{
+    homepagePath: z.ZodOptional<z.ZodString>;
+    siteTitle: z.ZodOptional<z.ZodString>;
+    siteDescription: z.ZodOptional<z.ZodString>;
+    defaultTemplates: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+declare const contentConfigSchema: z.ZodType<ContentConfig>;
+type ContentConfigInput = z.input<typeof contentConfigSchema>;
+type ContentConfigOutput = z.output<typeof contentConfigSchema>;
+
+/**
+ * Zod validation schemas for SDK site configuration.
+ *
+ * These schemas are used to validate configuration fetched from
+ * SDK sites before storing in the database.
+ */
+
+/**
+ * Schema for SDK theme palette.
+ * Maps token names to CSS color values.
+ */
+declare const sdkThemePaletteSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+/**
+ * Schema for SDK theme configuration.
+ */
+declare const sdkThemeConfigSchema: z.ZodObject<{
+    palette: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Schema for section background color options.
+ */
+declare const sectionBackgroundSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    token: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Schema for section spacing values.
+ */
+declare const sectionSpacingSchema: z.ZodEnum<{
+    default: "default";
+    compact: "compact";
+    spacious: "spacious";
+}>;
+/**
+ * Schema for container max-width values.
+ */
+declare const containerMaxWidthSchema: z.ZodEnum<{
+    default: "default";
+    full: "full";
+    narrow: "narrow";
+    wide: "wide";
+}>;
+/**
+ * Schema for container alignment values.
+ */
+declare const containerAlignmentSchema: z.ZodEnum<{
+    center: "center";
+    left: "left";
+    right: "right";
+}>;
+/**
+ * Schema for section options configuration.
+ */
+declare const sectionOptionsSchema: z.ZodOptional<z.ZodObject<{
+    backgroundColor: z.ZodOptional<z.ZodBoolean>;
+    backgroundImage: z.ZodOptional<z.ZodBoolean>;
+    backgroundGradient: z.ZodOptional<z.ZodBoolean>;
+    spacing: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodEnum<{
+        default: "default";
+        compact: "compact";
+        spacious: "spacious";
+    }>>, z.ZodBoolean]>>;
+    textColor: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>>;
+/**
+ * Schema for container options configuration.
+ */
+declare const containerOptionsSchema: z.ZodOptional<z.ZodObject<{
+    maxWidth: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodEnum<{
+        default: "default";
+        full: "full";
+        narrow: "narrow";
+        wide: "wide";
+    }>>, z.ZodBoolean]>>;
+    alignment: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodEnum<{
+        center: "center";
+        left: "left";
+        right: "right";
+    }>>, z.ZodBoolean]>>;
+}, z.core.$strip>>;
+/**
+ * Schema for site style configuration.
+ */
+declare const siteStyleConfigSchema: z.ZodOptional<z.ZodObject<{
+    sectionBackgrounds: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$strip>>>;
+    sectionOptions: z.ZodOptional<z.ZodObject<{
+        backgroundColor: z.ZodOptional<z.ZodBoolean>;
+        backgroundImage: z.ZodOptional<z.ZodBoolean>;
+        backgroundGradient: z.ZodOptional<z.ZodBoolean>;
+        spacing: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodEnum<{
+            default: "default";
+            compact: "compact";
+            spacious: "spacious";
+        }>>, z.ZodBoolean]>>;
+        textColor: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    containerOptions: z.ZodOptional<z.ZodObject<{
+        maxWidth: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodEnum<{
+            default: "default";
+            full: "full";
+            narrow: "narrow";
+            wide: "wide";
+        }>>, z.ZodBoolean]>>;
+        alignment: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodEnum<{
+            center: "center";
+            left: "left";
+            right: "right";
+        }>>, z.ZodBoolean]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+/**
+ * Whitelisted endpoints for SDK data loaders.
+ *
+ * These are the only CMS endpoints that can be called from config-based loaders.
+ * This ensures SDK sites can only access safe, read-only public endpoints.
+ *
+ * Derived from SUPPORTED_LOADER_ENDPOINTS - the single source of truth.
+ */
+declare const sdkLoaderEndpointSchema: z.ZodEnum<{
+    listPublishedEntries: "listPublishedEntries";
+    getPublishedEntryPreview: "getPublishedEntryPreview";
+    listPublicEvents: "listPublicEvents";
+    getPublicFormById: "getPublicFormById";
+    getPublicBookingServices: "getPublicBookingServices";
+}>;
+/**
+ * A binding expression for dynamic loader params.
+ *
+ * @example
+ * ```typescript
+ * { $bind: { from: 'content.categoryId' } }
+ * { $bind: { from: '$root.siteId' } }
+ * { $bind: { from: 'content.limit', fallback: '10' } }
+ * ```
+ */
+declare const loaderParamBindingSchema: z.ZodObject<{
+    $bind: z.ZodObject<{
+        from: z.ZodString;
+        fallback: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * A loader param value can be static or a binding expression.
+ */
+declare const loaderParamValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodObject<{
+    $bind: z.ZodObject<{
+        from: z.ZodString;
+        fallback: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>]>;
+/**
+ * Schema for config-based data loader.
+ *
+ * Config loaders execute server-side during loadPage() and are
+ * restricted to whitelisted CMS endpoints.
+ */
+declare const sdkConfigLoaderSchema: z.ZodObject<{
+    endpoint: z.ZodEnum<{
+        listPublishedEntries: "listPublishedEntries";
+        getPublishedEntryPreview: "getPublishedEntryPreview";
+        listPublicEvents: "listPublicEvents";
+        getPublicFormById: "getPublicFormById";
+        getPublicBookingServices: "getPublicBookingServices";
+    }>;
+    params: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodObject<{
+        $bind: z.ZodObject<{
+            from: z.ZodString;
+            fallback: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>]>>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        server: "server";
+        client: "client";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Schema for the dataLoaders field on custom blocks.
+ * Validates the loader configuration and limits the number of loaders.
+ */
+declare const sdkDataLoadersSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+    endpoint: z.ZodEnum<{
+        listPublishedEntries: "listPublishedEntries";
+        getPublishedEntryPreview: "getPublishedEntryPreview";
+        listPublicEvents: "listPublicEvents";
+        getPublicFormById: "getPublicFormById";
+        getPublicBookingServices: "getPublicBookingServices";
+    }>;
+    params: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodObject<{
+        $bind: z.ZodObject<{
+            from: z.ZodString;
+            fallback: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>]>>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        server: "server";
+        client: "client";
+    }>>;
+}, z.core.$strip>>>;
+/**
+ * Schema for field select option.
+ */
+declare const fieldSelectOptionSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Schema for per-field configuration within a block.
+ */
+declare const blockFieldConfigSchema: z.ZodObject<{
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * Schema for per-block field options.
+ *
+ * Block IDs must be either 'block.*' (system blocks) or 'custom.*' (custom blocks).
+ * Field IDs can be any valid identifier string.
+ */
+declare const blockFieldOptionsSchema: z.ZodType<BlockFieldOptionsMap>;
+/**
+ * Schema for block field extension configuration.
+ *
+ * Validates additional fields to be appended to a built-in block.
+ * Includes refinement to ensure required fields have defaultValue.
+ *
+ * Note: Explicit type annotation required due to recursive fieldSchema complexity.
+ */
+declare const blockFieldExtensionSchema: z.ZodType<BlockFieldExtension>;
+/**
+ * Schema for block field extensions map.
+ *
+ * Block IDs must be system blocks (e.g., 'block.bodyText', 'block.hero').
+ * Custom blocks ('custom.*') should define their fields directly, not via extensions.
+ */
+declare const blockFieldExtensionsSchema: z.ZodType<BlockFieldExtensionsMap | undefined>;
+/**
+ * Validates that extended field IDs don't conflict with existing block fields.
+ *
+ * This validation should be called during config push to provide clear error messages.
+ * Returns an array of conflict errors, or empty array if valid.
+ *
+ * @example
+ * ```typescript
+ * const conflicts = validateFieldIdConflicts(config.blockFieldExtensions);
+ * if (conflicts.length > 0) {
+ *   throw new Error(conflicts.map(c => c.message).join('\n'));
+ * }
+ * ```
+ */
+declare function validateFieldIdConflicts(blockFieldExtensions?: BlockFieldExtensionsMap | null): {
+    blockId: string;
+    fieldId: string;
+    message: string;
+}[];
+/**
+ * Schema for SDK custom block definitions.
+ *
+ * Validates custom blocks defined in riverbank.config.ts.
+ * Reuses fieldSchema from @riverbankcms/blocks for field validation.
+ *
+ * Note: Explicit type annotation required due to recursive fieldSchema complexity.
+ */
+declare const sdkCustomBlockSchema: z.ZodType<SdkCustomBlock>;
+/**
+ * Schema for the complete SDK site configuration.
+ *
+ * Use this schema to validate configuration fetched from SDK sites
+ * before storing in the database.
+ *
+ * @example
+ * ```typescript
+ * import { riverbankSiteConfigSchema } from '@riverbankcms/sdk/config/validation';
+ *
+ * const rawConfig = await response.json();
+ * const config = riverbankSiteConfigSchema.parse(rawConfig);
+ * ```
+ */
+declare const riverbankSiteConfigSchema: z.ZodType<RiverbankSiteConfig>;
+/**
+ * Type inferred from the validation schema.
+ * This should match the RiverbankSiteConfig type from ./types.ts
+ */
+type ValidatedRiverbankSiteConfig = z.infer<typeof riverbankSiteConfigSchema>;
+/**
+ * Type for a validated SDK custom block.
+ */
+type ValidatedSdkCustomBlock = z.infer<typeof sdkCustomBlockSchema>;
+
+export { sdkLoaderEndpointSchema as A, loaderParamBindingSchema as B, type ContentConfigInput as C, loaderParamValueSchema as D, sdkConfigLoaderSchema as E, sdkDataLoadersSchema as F, validateFieldIdConflicts as G, type ValidatedRiverbankSiteConfig as V, sectionBackgroundSchema as a, sectionSpacingSchema as b, containerMaxWidthSchema as c, containerAlignmentSchema as d, sectionOptionsSchema as e, containerOptionsSchema as f, sdkThemeConfigSchema as g, sdkThemePaletteSchema as h, sdkCustomBlockSchema as i, fieldSelectOptionSchema as j, blockFieldConfigSchema as k, blockFieldOptionsSchema as l, blockFieldExtensionSchema as m, blockFieldExtensionsSchema as n, contentConfigSchema as o, contentTypeConfigSchema as p, pageConfigSchema as q, riverbankSiteConfigSchema as r, siteStyleConfigSchema as s, entryConfigSchema as t, navigationMenuConfigSchema as u, navigationItemConfigSchema as v, siteSettingsConfigSchema as w, blockConfigSchema as x, type ValidatedSdkCustomBlock as y, type ContentConfigOutput as z };