@riverbankcms/sdk 0.3.0 → 0.4.1

package/dist/server/{types-Ls6BkLKg.d.ts → types-CAnC529E.d.ts}

@@ -1,4 +1,4 @@
-import { A as APIEndpoints } from './types-Cc7lyPkN.js';
+import { A as APIEndpoints } from './types-5XdVD2J1.js';
 
 type SiteResponse = NonNullable<APIEndpoints['getSite']['response']>;
 type PageResponse = NonNullable<APIEndpoints['getContentByPath']['response']>;
@@ -7,6 +7,50 @@ type EntryResponse = NonNullable<APIEndpoints['getPublishedEntryPreview']['respo
 type PublicFormResponse = NonNullable<APIEndpoints['getPublicFormById']['response']>;
 type PublicBookingServicesResponse = NonNullable<APIEndpoints['getPublicBookingServices']['response']>;
 type PublicEventsResponse = NonNullable<APIEndpoints['listPublicEvents']['response']>;
+/**
+ * Pagination metadata returned when `includeMeta: true`
+ */
+interface PaginationMeta {
+    /** Total number of entries matching the query (estimated if hasMore is true) */
+    total: number;
+    /** Whether there are more entries after this page */
+    hasMore: boolean;
+    /** Number of entries per page */
+    limit: number;
+    /** Number of entries skipped (offset) */
+    offset: number;
+    /** Total number of pages (estimated if hasMore is true) */
+    totalPages: number;
+    /** Current page number (1-indexed) */
+    currentPage: number;
+}
+/**
+ * Response type when includeMeta is true - includes pagination metadata
+ */
+type EntriesResponseWithMeta = {
+    entries: EntriesResponse['entries'];
+} & PaginationMeta;
+/**
+ * Base parameters for getEntries - shared across all overloads
+ */
+interface GetEntriesBaseParams {
+    /** The site ID */
+    siteId: string;
+    /** The content type key (e.g., 'blog-post', 'product') */
+    contentType: string;
+    /** Maximum number of entries to return (default: 10, max: 50) */
+    limit?: number;
+    /** Number of entries to skip for pagination */
+    offset?: number;
+    /** Sort order for entries. 'order' uses custom ordering (default behavior). */
+    order?: 'newest' | 'oldest' | 'title' | 'order';
+    /** If true, includes draft entries (requires API key with site access) */
+    preview?: boolean;
+    /** Selection mode: 'query' for automatic, 'manual' for specific entry IDs */
+    mode?: 'query' | 'manual';
+    /** Entry IDs to fetch when mode is 'manual' */
+    entryIds?: string[];
+}
 /**
  * Configuration for creating a Riverbank CMS client
  */
@@ -66,11 +110,13 @@ interface RiverbankClient {
      *
      * @param params.siteId - The site ID
      * @param params.contentType - The content type key (e.g., 'blog-post', 'product')
-     * @param params.limit - Maximum number of entries to return
+     * @param params.limit - Maximum number of entries to return (default: 10, max: 50)
+     * @param params.offset - Number of entries to skip for pagination (default: 0)
      * @param params.order - Sort order: 'newest' (published_at desc) or 'oldest' (published_at asc)
      * @param params.preview - If true, includes draft entries (requires API key with site access)
      * @param params.mode - 'query' for automatic fetching, 'manual' for specific entry IDs
      * @param params.entryIds - Array of entry IDs to fetch (only used when mode is 'manual')
+     * @param params.includeMeta - If true, returns pagination metadata with the response
      *
      * @example
      * ```ts
@@ -82,12 +128,15 @@ interface RiverbankClient {
      *   order: 'newest',
      * });
      *
-     * // Fetch draft entries for preview
-     * const drafts = await client.getEntries({
+     * // Fetch page 3 with pagination metadata
+     * const page3 = await client.getEntries({
      *   siteId: 'site-id',
      *   contentType: 'blog-post',
-     *   preview: true,
+     *   limit: 10,
+     *   offset: 20,
+     *   includeMeta: true,
      * });
+     * // page3.entries, page3.total, page3.hasMore, page3.currentPage
      *
      * // Fetch specific entries by ID (manual mode)
      * const specific = await client.getEntries({
@@ -98,18 +147,17 @@ interface RiverbankClient {
      * });
      * ```
      */
-    getEntries(params: {
-        siteId: string;
-        contentType: string;
-        limit?: number;
-        /** Sort order for entries. 'order' uses custom ordering (default behavior). */
-        order?: 'newest' | 'oldest' | 'title' | 'order';
-        preview?: boolean;
-        /** Selection mode: 'query' for automatic, 'manual' for specific entry IDs */
-        mode?: 'query' | 'manual';
-        /** Entry IDs to fetch when mode is 'manual' */
-        entryIds?: string[];
+    getEntries(params: GetEntriesBaseParams & {
+        /** If true, returns pagination metadata with the response */
+        includeMeta?: false;
     }): Promise<EntriesResponse>;
+    getEntries(params: GetEntriesBaseParams & {
+        /** If true, returns pagination metadata with the response */
+        includeMeta: true;
+    }): Promise<EntriesResponseWithMeta>;
+    getEntries(params: GetEntriesBaseParams & {
+        includeMeta?: boolean;
+    }): Promise<EntriesResponse | EntriesResponseWithMeta>;
     /**
      * Fetch a specific content entry by slug
      */
@@ -147,4 +195,4 @@ interface RiverbankClient {
     clearCache(): void;
 }
 
-export type { EntriesResponse as E, PageResponse as P, RiverbankClient as R, SiteResponse as S, RiverbankClientConfig as a, EntryResponse as b };
+export type { EntriesResponse as E, PageResponse as P, RiverbankClient as R, SiteResponse as S, RiverbankClientConfig as a, EntryResponse as b, EntriesResponseWithMeta as c, PaginationMeta as d };

package/dist/server/{types-D-rqOU5I.d.ts → types-CMqVHYLG.d.ts}

@@ -1,4 +1,247 @@
-import { S as SdkCustomBlock, F as FieldDefinition } from './schema-Bpy9N5ZI.js';
+import { F as FieldDefinition, S as SdkCustomBlock } from './schema-Bpy9N5ZI.js';
+import { B as BlockKind } from './blockKinds-B6MWzNWp.js';
+
+/**
+ * SDK Content Scaffolding Types
+ *
+ * These types define the schema for SDK content configuration that allows
+ * SDK sites to define content types, pages, entries, and navigation in code.
+ */
+
+/**
+ * Content type definition for SDK config.
+ *
+ * Defines the structure of a content type that SDK sites can declare.
+ * When pushed, the dashboard will ensure this content type exists.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   key: 'testimonial',
+ *   name: 'Testimonial',
+ *   hasPages: false,
+ *   fields: [
+ *     { id: 'quote', type: 'richText', label: 'Quote', required: true },
+ *     { id: 'author', type: 'text', label: 'Author', required: true },
+ *   ],
+ * }
+ * ```
+ */
+interface ContentTypeConfig {
+    /** Unique key for this content type (e.g., 'post', 'event'). Must be lowercase with hyphens. */
+    key: string;
+    /** Display name shown in dashboard UI */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Whether entries of this type have routable pages */
+    hasPages: boolean;
+    /** Route pattern with {slug} placeholder. Required if hasPages=true. */
+    routePattern?: string;
+    /** Field definitions for this content type */
+    fields: FieldDefinition[];
+    /** Field ID to use as the entry title source */
+    titleField?: string;
+}
+/**
+ * Block content for page scaffolding.
+ *
+ * Represents initial block content that can be added to SDK-defined pages.
+ */
+interface BlockConfig {
+    /** Block kind (e.g., 'block.hero', 'block.bodyText', 'custom.myBlock') */
+    kind: BlockKind;
+    /** Block content data matching the block's field definitions */
+    content: Record<string, unknown>;
+    /** Order index (optional, defaults to array position) */
+    orderIndex?: number;
+}
+/**
+ * Page definition for SDK config.
+ *
+ * Defines a page that should exist on the site.
+ * When pushed, the dashboard will ensure this page exists.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   identifier: 'home',
+ *   title: 'Home',
+ *   path: '/',
+ *   status: 'published',
+ *   blocks: [
+ *     { kind: 'block.hero', content: { heading: 'Welcome' } },
+ *   ],
+ * }
+ * ```
+ */
+interface PageConfig {
+    /** Unique identifier for this page. Required for SDK sync. */
+    identifier: string;
+    /** Page title */
+    title: string;
+    /** URL path (e.g., '/', '/about', '/contact'). Must start with /. */
+    path: string;
+    /** Page purpose (default: 'content') */
+    purpose?: string;
+    /** Initial block content (optional) */
+    blocks?: BlockConfig[];
+    /** Status: 'draft' or 'published' (default: 'draft') */
+    status?: 'draft' | 'published';
+    /** SEO meta title */
+    metaTitle?: string;
+    /** SEO meta description */
+    metaDescription?: string;
+}
+/**
+ * Content entry definition for SDK config.
+ *
+ * Defines a content entry that should exist.
+ * When pushed, the dashboard will ensure this entry exists.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   identifier: 'testimonial-1',
+ *   contentType: 'testimonial',
+ *   title: 'First Testimonial',
+ *   status: 'published',
+ *   data: {
+ *     quote: '<p>Great product!</p>',
+ *     author: 'Jane Doe',
+ *   },
+ * }
+ * ```
+ */
+interface EntryConfig {
+    /** Unique identifier for this entry. Required for SDK sync. */
+    identifier: string;
+    /** Content type key this entry belongs to */
+    contentType: string;
+    /** Entry data matching the content type's field definitions */
+    data: Record<string, unknown>;
+    /** Status: 'draft' or 'published' (default: 'draft') */
+    status?: 'draft' | 'published';
+    /** Slug for routable entries. Defaults to identifier if content type hasPages. */
+    slug?: string;
+    /** Title for the entry (used in route metadata if routable) */
+    title?: string;
+    /** Summary/description */
+    summary?: string;
+    /** SEO meta title */
+    metaTitle?: string;
+    /** SEO meta description */
+    metaDescription?: string;
+}
+/**
+ * Navigation link types for menu items.
+ */
+type NavigationLinkType = {
+    kind: 'page';
+    identifier: string;
+} | {
+    kind: 'entry';
+    identifier: string;
+} | {
+    kind: 'external';
+    href: string;
+} | {
+    kind: 'dropdown';
+};
+/**
+ * Navigation item definition.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   label: 'Products',
+ *   link: { kind: 'dropdown' },
+ *   children: [
+ *     { label: 'Product 1', link: { kind: 'page', identifier: 'product-1' } },
+ *   ],
+ * }
+ * ```
+ */
+interface NavigationItemConfig {
+    /** Display label */
+    label: string;
+    /** Link configuration */
+    link: NavigationLinkType;
+    /** Is this a CTA button? */
+    isCta?: boolean;
+    /** Child items (for dropdown menus, max 1 level) */
+    children?: NavigationItemConfig[];
+}
+/**
+ * Navigation menu definition.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   identifier: 'main',
+ *   name: 'Main Navigation',
+ *   isPrimary: true,
+ *   items: [
+ *     { label: 'Home', link: { kind: 'page', identifier: 'home' } },
+ *     { label: 'About', link: { kind: 'page', identifier: 'about' } },
+ *   ],
+ * }
+ * ```
+ */
+interface NavigationMenuConfig {
+    /** Unique identifier for this menu */
+    identifier: string;
+    /** Menu display name */
+    name: string;
+    /** Is this the primary/main menu? */
+    isPrimary?: boolean;
+    /** Menu items */
+    items: NavigationItemConfig[];
+}
+/**
+ * Site settings for SDK config.
+ */
+interface SiteSettingsConfig {
+    /** Homepage path (default: '/') */
+    homepagePath?: string;
+    /** Site title (for SEO/metadata) */
+    siteTitle?: string;
+    /** Site description (for SEO/metadata) */
+    siteDescription?: string;
+    /** Default template ID per content type key */
+    defaultTemplates?: Record<string, string>;
+}
+/**
+ * Complete content configuration for SDK sites.
+ *
+ * This is imported into riverbank.config.ts via the `content` field.
+ *
+ * @example
+ * ```typescript
+ * // content.config.ts
+ * import { defineContentConfig } from '@riverbankcms/sdk/config';
+ *
+ * export const contentConfig = defineContentConfig({
+ *   contentTypes: [...],
+ *   pages: [...],
+ *   entries: [...],
+ *   navigationMenus: [...],
+ *   settings: {...},
+ * });
+ * ```
+ */
+interface ContentConfig {
+    /** Content type definitions */
+    contentTypes?: ContentTypeConfig[];
+    /** Content entries */
+    entries?: EntryConfig[];
+    /** Page definitions */
+    pages?: PageConfig[];
+    /** Navigation menus */
+    navigationMenus?: NavigationMenuConfig[];
+    /** Site settings */
+    settings?: SiteSettingsConfig;
+}
 
 /**
  * SDK Site Configuration Types
@@ -328,6 +571,25 @@ interface RiverbankSiteConfig {
      * ```
      */
     blockFieldExtensions?: BlockFieldExtensionsMap;
+    /**
+     * Content scaffolding configuration.
+     *
+     * Defines content types, pages, entries, and navigation menus that
+     * should exist on the site. When SDK config is pushed, the dashboard
+     * will ensure these items exist.
+     *
+     * @example
+     * ```typescript
+     * content: {
+     *   contentTypes: [...],
+     *   pages: [...],
+     *   entries: [...],
+     *   navigationMenus: [...],
+     *   settings: { homepagePath: '/' },
+     * }
+     * ```
+     */
+    content?: ContentConfig;
 }
 
-export type { BlockFieldConfig as B, ContainerOptionsConfig as C, FieldSelectOption as F, RiverbankSiteConfig as R, SiteStyleConfig as S, SectionBackground as a, SectionOptionsConfig as b, SectionSpacing as c, ContainerMaxWidth as d, ContainerAlignment as e, SdkThemeConfig as f, SdkThemePalette as g, BlockFieldOptionsMap as h, BlockFieldExtension as i, BlockFieldExtensionsMap as j };
+export type { BlockFieldConfig as B, ContentConfig as C, EntryConfig as E, FieldSelectOption as F, NavigationMenuConfig as N, PageConfig as P, RiverbankSiteConfig as R, SiteStyleConfig as S, SectionBackground as a, SectionOptionsConfig as b, ContainerOptionsConfig as c, SectionSpacing as d, ContainerMaxWidth as e, ContainerAlignment as f, SdkThemeConfig as g, SdkThemePalette as h, BlockFieldOptionsMap as i, BlockFieldExtension as j, BlockFieldExtensionsMap as k, ContentTypeConfig as l, BlockConfig as m, NavigationItemConfig as n, NavigationLinkType as o, SiteSettingsConfig as p };

package/dist/server/{types-Bq3520hK.d.mts → types-CYfHxUhe.d.mts}

@@ -1,4 +1,247 @@
-import { S as SdkCustomBlock, F as FieldDefinition } from './schema-Bpy9N5ZI.mjs';
+import { F as FieldDefinition, S as SdkCustomBlock } from './schema-Bpy9N5ZI.mjs';
+import { B as BlockKind } from './blockKinds-B6MWzNWp.mjs';
+
+/**
+ * SDK Content Scaffolding Types
+ *
+ * These types define the schema for SDK content configuration that allows
+ * SDK sites to define content types, pages, entries, and navigation in code.
+ */
+
+/**
+ * Content type definition for SDK config.
+ *
+ * Defines the structure of a content type that SDK sites can declare.
+ * When pushed, the dashboard will ensure this content type exists.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   key: 'testimonial',
+ *   name: 'Testimonial',
+ *   hasPages: false,
+ *   fields: [
+ *     { id: 'quote', type: 'richText', label: 'Quote', required: true },
+ *     { id: 'author', type: 'text', label: 'Author', required: true },
+ *   ],
+ * }
+ * ```
+ */
+interface ContentTypeConfig {
+    /** Unique key for this content type (e.g., 'post', 'event'). Must be lowercase with hyphens. */
+    key: string;
+    /** Display name shown in dashboard UI */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Whether entries of this type have routable pages */
+    hasPages: boolean;
+    /** Route pattern with {slug} placeholder. Required if hasPages=true. */
+    routePattern?: string;
+    /** Field definitions for this content type */
+    fields: FieldDefinition[];
+    /** Field ID to use as the entry title source */
+    titleField?: string;
+}
+/**
+ * Block content for page scaffolding.
+ *
+ * Represents initial block content that can be added to SDK-defined pages.
+ */
+interface BlockConfig {
+    /** Block kind (e.g., 'block.hero', 'block.bodyText', 'custom.myBlock') */
+    kind: BlockKind;
+    /** Block content data matching the block's field definitions */
+    content: Record<string, unknown>;
+    /** Order index (optional, defaults to array position) */
+    orderIndex?: number;
+}
+/**
+ * Page definition for SDK config.
+ *
+ * Defines a page that should exist on the site.
+ * When pushed, the dashboard will ensure this page exists.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   identifier: 'home',
+ *   title: 'Home',
+ *   path: '/',
+ *   status: 'published',
+ *   blocks: [
+ *     { kind: 'block.hero', content: { heading: 'Welcome' } },
+ *   ],
+ * }
+ * ```
+ */
+interface PageConfig {
+    /** Unique identifier for this page. Required for SDK sync. */
+    identifier: string;
+    /** Page title */
+    title: string;
+    /** URL path (e.g., '/', '/about', '/contact'). Must start with /. */
+    path: string;
+    /** Page purpose (default: 'content') */
+    purpose?: string;
+    /** Initial block content (optional) */
+    blocks?: BlockConfig[];
+    /** Status: 'draft' or 'published' (default: 'draft') */
+    status?: 'draft' | 'published';
+    /** SEO meta title */
+    metaTitle?: string;
+    /** SEO meta description */
+    metaDescription?: string;
+}
+/**
+ * Content entry definition for SDK config.
+ *
+ * Defines a content entry that should exist.
+ * When pushed, the dashboard will ensure this entry exists.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   identifier: 'testimonial-1',
+ *   contentType: 'testimonial',
+ *   title: 'First Testimonial',
+ *   status: 'published',
+ *   data: {
+ *     quote: '<p>Great product!</p>',
+ *     author: 'Jane Doe',
+ *   },
+ * }
+ * ```
+ */
+interface EntryConfig {
+    /** Unique identifier for this entry. Required for SDK sync. */
+    identifier: string;
+    /** Content type key this entry belongs to */
+    contentType: string;
+    /** Entry data matching the content type's field definitions */
+    data: Record<string, unknown>;
+    /** Status: 'draft' or 'published' (default: 'draft') */
+    status?: 'draft' | 'published';
+    /** Slug for routable entries. Defaults to identifier if content type hasPages. */
+    slug?: string;
+    /** Title for the entry (used in route metadata if routable) */
+    title?: string;
+    /** Summary/description */
+    summary?: string;
+    /** SEO meta title */
+    metaTitle?: string;
+    /** SEO meta description */
+    metaDescription?: string;
+}
+/**
+ * Navigation link types for menu items.
+ */
+type NavigationLinkType = {
+    kind: 'page';
+    identifier: string;
+} | {
+    kind: 'entry';
+    identifier: string;
+} | {
+    kind: 'external';
+    href: string;
+} | {
+    kind: 'dropdown';
+};
+/**
+ * Navigation item definition.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   label: 'Products',
+ *   link: { kind: 'dropdown' },
+ *   children: [
+ *     { label: 'Product 1', link: { kind: 'page', identifier: 'product-1' } },
+ *   ],
+ * }
+ * ```
+ */
+interface NavigationItemConfig {
+    /** Display label */
+    label: string;
+    /** Link configuration */
+    link: NavigationLinkType;
+    /** Is this a CTA button? */
+    isCta?: boolean;
+    /** Child items (for dropdown menus, max 1 level) */
+    children?: NavigationItemConfig[];
+}
+/**
+ * Navigation menu definition.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   identifier: 'main',
+ *   name: 'Main Navigation',
+ *   isPrimary: true,
+ *   items: [
+ *     { label: 'Home', link: { kind: 'page', identifier: 'home' } },
+ *     { label: 'About', link: { kind: 'page', identifier: 'about' } },
+ *   ],
+ * }
+ * ```
+ */
+interface NavigationMenuConfig {
+    /** Unique identifier for this menu */
+    identifier: string;
+    /** Menu display name */
+    name: string;
+    /** Is this the primary/main menu? */
+    isPrimary?: boolean;
+    /** Menu items */
+    items: NavigationItemConfig[];
+}
+/**
+ * Site settings for SDK config.
+ */
+interface SiteSettingsConfig {
+    /** Homepage path (default: '/') */
+    homepagePath?: string;
+    /** Site title (for SEO/metadata) */
+    siteTitle?: string;
+    /** Site description (for SEO/metadata) */
+    siteDescription?: string;
+    /** Default template ID per content type key */
+    defaultTemplates?: Record<string, string>;
+}
+/**
+ * Complete content configuration for SDK sites.
+ *
+ * This is imported into riverbank.config.ts via the `content` field.
+ *
+ * @example
+ * ```typescript
+ * // content.config.ts
+ * import { defineContentConfig } from '@riverbankcms/sdk/config';
+ *
+ * export const contentConfig = defineContentConfig({
+ *   contentTypes: [...],
+ *   pages: [...],
+ *   entries: [...],
+ *   navigationMenus: [...],
+ *   settings: {...},
+ * });
+ * ```
+ */
+interface ContentConfig {
+    /** Content type definitions */
+    contentTypes?: ContentTypeConfig[];
+    /** Content entries */
+    entries?: EntryConfig[];
+    /** Page definitions */
+    pages?: PageConfig[];
+    /** Navigation menus */
+    navigationMenus?: NavigationMenuConfig[];
+    /** Site settings */
+    settings?: SiteSettingsConfig;
+}
 
 /**
  * SDK Site Configuration Types
@@ -328,6 +571,25 @@ interface RiverbankSiteConfig {
      * ```
      */
     blockFieldExtensions?: BlockFieldExtensionsMap;
+    /**
+     * Content scaffolding configuration.
+     *
+     * Defines content types, pages, entries, and navigation menus that
+     * should exist on the site. When SDK config is pushed, the dashboard
+     * will ensure these items exist.
+     *
+     * @example
+     * ```typescript
+     * content: {
+     *   contentTypes: [...],
+     *   pages: [...],
+     *   entries: [...],
+     *   navigationMenus: [...],
+     *   settings: { homepagePath: '/' },
+     * }
+     * ```
+     */
+    content?: ContentConfig;
 }
 
-export type { BlockFieldConfig as B, ContainerOptionsConfig as C, FieldSelectOption as F, RiverbankSiteConfig as R, SiteStyleConfig as S, SectionBackground as a, SectionOptionsConfig as b, SectionSpacing as c, ContainerMaxWidth as d, ContainerAlignment as e, SdkThemeConfig as f, SdkThemePalette as g, BlockFieldOptionsMap as h, BlockFieldExtension as i, BlockFieldExtensionsMap as j };
+export type { BlockFieldConfig as B, ContentConfig as C, EntryConfig as E, FieldSelectOption as F, NavigationMenuConfig as N, PageConfig as P, RiverbankSiteConfig as R, SiteStyleConfig as S, SectionBackground as a, SectionOptionsConfig as b, ContainerOptionsConfig as c, SectionSpacing as d, ContainerMaxWidth as e, ContainerAlignment as f, SdkThemeConfig as g, SdkThemePalette as h, BlockFieldOptionsMap as i, BlockFieldExtension as j, BlockFieldExtensionsMap as k, ContentTypeConfig as l, BlockConfig as m, NavigationItemConfig as n, NavigationLinkType as o, SiteSettingsConfig as p };