@riverbankcms/sdk 0.1.0

package/dist/server/types-Bbo01M7P.d.mts

@@ -0,0 +1,76 @@
+/**
+ * Code-based data loader types for SDK custom blocks.
+ *
+ * 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.
+ *
+ * Contains block metadata and page context for making informed
+ * data fetching decisions.
+ */
+interface DataLoaderContext {
+    /** Site ID from page context */
+    siteId: string;
+    /** Page ID from page context */
+    pageId: string;
+    /** Unique block instance ID */
+    blockId: string;
+    /** Block kind (e.g., 'custom.featured-products') */
+    blockKind: string;
+    /**
+     * The block's CMS content.
+     * Use this to access field values for parameterizing API calls.
+     */
+    content: Record<string, unknown>;
+    /** Whether fetching preview/draft content */
+    previewStage: 'published' | 'preview';
+}
+/**
+ * A code-based data loader function.
+ *
+ * Receives context about the block and returns fetched data.
+ * Runs server-side during `loadPage()`.
+ *
+ * @example
+ * ```typescript
+ * const productsLoader: DataLoaderFn = async (ctx) => {
+ *   const categoryId = ctx.content.categoryId;
+ *   const response = await fetch(`https://api.shop.com/products?category=${categoryId}`);
+ *   return response.json();
+ * };
+ * ```
+ */
+type DataLoaderFn = (context: DataLoaderContext) => Promise<unknown>;
+/**
+ * Map of loader key to loader function for a block kind.
+ *
+ * Keys become the property names in the `data` prop passed to the component.
+ */
+type BlockLoaderMap = Record<string, DataLoaderFn>;
+/**
+ * Registry of code-based data loaders.
+ *
+ * Keys are block kinds (e.g., 'custom.featured-products').
+ * Values are maps of loader keys to loader functions.
+ *
+ * @example
+ * ```typescript
+ * const dataLoaderOverrides: DataLoaderOverrides = {
+ *   'custom.featured-products': {
+ *     products: async (ctx) => {
+ *       return fetchProducts(ctx.content.categoryId);
+ *     },
+ *   },
+ *   'custom.instagram-feed': {
+ *     posts: async (ctx) => {
+ *       return fetchInstagramPosts(ctx.content.accessToken);
+ *     },
+ *   },
+ * };
+ * ```
+ */
+type DataLoaderOverrides = Record<string, BlockLoaderMap>;
+
+export type { BlockLoaderMap as B, DataLoaderOverrides as D, DataLoaderContext as a, DataLoaderFn as b };

package/dist/server/types-Bbo01M7P.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Code-based data loader types for SDK custom blocks.
+ *
+ * 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.
+ *
+ * Contains block metadata and page context for making informed
+ * data fetching decisions.
+ */
+interface DataLoaderContext {
+    /** Site ID from page context */
+    siteId: string;
+    /** Page ID from page context */
+    pageId: string;
+    /** Unique block instance ID */
+    blockId: string;
+    /** Block kind (e.g., 'custom.featured-products') */
+    blockKind: string;
+    /**
+     * The block's CMS content.
+     * Use this to access field values for parameterizing API calls.
+     */
+    content: Record<string, unknown>;
+    /** Whether fetching preview/draft content */
+    previewStage: 'published' | 'preview';
+}
+/**
+ * A code-based data loader function.
+ *
+ * Receives context about the block and returns fetched data.
+ * Runs server-side during `loadPage()`.
+ *
+ * @example
+ * ```typescript
+ * const productsLoader: DataLoaderFn = async (ctx) => {
+ *   const categoryId = ctx.content.categoryId;
+ *   const response = await fetch(`https://api.shop.com/products?category=${categoryId}`);
+ *   return response.json();
+ * };
+ * ```
+ */
+type DataLoaderFn = (context: DataLoaderContext) => Promise<unknown>;
+/**
+ * Map of loader key to loader function for a block kind.
+ *
+ * Keys become the property names in the `data` prop passed to the component.
+ */
+type BlockLoaderMap = Record<string, DataLoaderFn>;
+/**
+ * Registry of code-based data loaders.
+ *
+ * Keys are block kinds (e.g., 'custom.featured-products').
+ * Values are maps of loader keys to loader functions.
+ *
+ * @example
+ * ```typescript
+ * const dataLoaderOverrides: DataLoaderOverrides = {
+ *   'custom.featured-products': {
+ *     products: async (ctx) => {
+ *       return fetchProducts(ctx.content.categoryId);
+ *     },
+ *   },
+ *   'custom.instagram-feed': {
+ *     posts: async (ctx) => {
+ *       return fetchInstagramPosts(ctx.content.accessToken);
+ *     },
+ *   },
+ * };
+ * ```
+ */
+type DataLoaderOverrides = Record<string, BlockLoaderMap>;
+
+export type { BlockLoaderMap as B, DataLoaderOverrides as D, DataLoaderContext as a, DataLoaderFn as b };

package/dist/server/types-C6gmRHLe.d.mts

@@ -0,0 +1,150 @@
+import { APIEndpoints } from '@riverbankcms/api';
+
+type SiteResponse = NonNullable<APIEndpoints['getSite']['response']>;
+type PageResponse = NonNullable<APIEndpoints['getContentByPath']['response']>;
+type EntriesResponse = NonNullable<APIEndpoints['listPublishedEntries']['response']>;
+type EntryResponse = NonNullable<APIEndpoints['getPublishedEntryPreview']['response']>;
+type PublicFormResponse = NonNullable<APIEndpoints['getPublicFormById']['response']>;
+type PublicBookingServicesResponse = NonNullable<APIEndpoints['getPublicBookingServices']['response']>;
+type PublicEventsResponse = NonNullable<APIEndpoints['listPublicEvents']['response']>;
+/**
+ * Configuration for creating a Riverbank CMS client
+ */
+interface RiverbankClientConfig {
+    /**
+     * API key for authentication (format: bld_live_... or bld_test_...)
+     */
+    apiKey: string;
+    /**
+     * Base URL for the Riverbank CMS API (required; e.g. https://dashboard.example.com/api)
+     */
+    baseUrl: string;
+    /**
+     * Cache configuration
+     */
+    cache?: {
+        /**
+         * Enable caching (default: true)
+         */
+        enabled?: boolean;
+        /**
+         * Time-to-live for cached responses in seconds
+         * @default 300 (5 minutes)
+         */
+        ttl?: number;
+        /**
+         * Maximum number of cached responses
+         * @default 100
+         */
+        maxSize?: number;
+    };
+}
+/**
+ * Riverbank CMS client interface
+ */
+interface RiverbankClient {
+    /**
+     * Fetch site data by slug, domain, or ID
+     */
+    getSite(params: {
+        slug?: string;
+        domain?: string;
+        id?: string;
+    }): Promise<SiteResponse>;
+    /**
+     * Fetch a specific page by path
+     *
+     * @param params.preview - If true, returns draft content instead of published content (requires API key with site access)
+     */
+    getPage(params: {
+        siteId: string;
+        path: string;
+        preview?: boolean;
+    }): Promise<PageResponse>;
+    /**
+     * Fetch published content entries with optional pagination, sorting, and preview mode
+     *
+     * @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.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')
+     *
+     * @example
+     * ```ts
+     * // Fetch latest 10 blog posts
+     * const entries = await client.getEntries({
+     *   siteId: 'site-id',
+     *   contentType: 'blog-post',
+     *   limit: 10,
+     *   order: 'newest',
+     * });
+     *
+     * // Fetch draft entries for preview
+     * const drafts = await client.getEntries({
+     *   siteId: 'site-id',
+     *   contentType: 'blog-post',
+     *   preview: true,
+     * });
+     *
+     * // Fetch specific entries by ID (manual mode)
+     * const specific = await client.getEntries({
+     *   siteId: 'site-id',
+     *   contentType: 'blog-post',
+     *   mode: 'manual',
+     *   entryIds: ['uuid-1', 'uuid-2'],
+     * });
+     * ```
+     */
+    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[];
+    }): Promise<EntriesResponse>;
+    /**
+     * Fetch a specific content entry by slug
+     */
+    getEntry(params: {
+        siteId: string;
+        contentType: string;
+        slug: string;
+    }): Promise<EntryResponse>;
+    /**
+     * Fetch a public form definition by ID
+     */
+    getPublicFormById(params: {
+        formId: string;
+    }): Promise<PublicFormResponse>;
+    /**
+     * Fetch public booking services for a site
+     */
+    getPublicBookingServices(params: {
+        siteId: string;
+        ids?: string;
+    }): Promise<PublicBookingServicesResponse>;
+    /**
+     * List public events for a site (optionally time-filtered)
+     */
+    listPublicEvents(params: {
+        siteId: string;
+        limit?: number;
+        from?: string;
+        to?: string;
+        stage?: string;
+    }): Promise<PublicEventsResponse>;
+    /**
+     * Force clear the cache
+     */
+    clearCache(): void;
+}
+
+export type { EntriesResponse as E, PageResponse as P, RiverbankClient as R, SiteResponse as S, RiverbankClientConfig as a, EntryResponse as b };

package/dist/server/types-C6gmRHLe.d.ts

@@ -0,0 +1,150 @@
+import { APIEndpoints } from '@riverbankcms/api';
+
+type SiteResponse = NonNullable<APIEndpoints['getSite']['response']>;
+type PageResponse = NonNullable<APIEndpoints['getContentByPath']['response']>;
+type EntriesResponse = NonNullable<APIEndpoints['listPublishedEntries']['response']>;
+type EntryResponse = NonNullable<APIEndpoints['getPublishedEntryPreview']['response']>;
+type PublicFormResponse = NonNullable<APIEndpoints['getPublicFormById']['response']>;
+type PublicBookingServicesResponse = NonNullable<APIEndpoints['getPublicBookingServices']['response']>;
+type PublicEventsResponse = NonNullable<APIEndpoints['listPublicEvents']['response']>;
+/**
+ * Configuration for creating a Riverbank CMS client
+ */
+interface RiverbankClientConfig {
+    /**
+     * API key for authentication (format: bld_live_... or bld_test_...)
+     */
+    apiKey: string;
+    /**
+     * Base URL for the Riverbank CMS API (required; e.g. https://dashboard.example.com/api)
+     */
+    baseUrl: string;
+    /**
+     * Cache configuration
+     */
+    cache?: {
+        /**
+         * Enable caching (default: true)
+         */
+        enabled?: boolean;
+        /**
+         * Time-to-live for cached responses in seconds
+         * @default 300 (5 minutes)
+         */
+        ttl?: number;
+        /**
+         * Maximum number of cached responses
+         * @default 100
+         */
+        maxSize?: number;
+    };
+}
+/**
+ * Riverbank CMS client interface
+ */
+interface RiverbankClient {
+    /**
+     * Fetch site data by slug, domain, or ID
+     */
+    getSite(params: {
+        slug?: string;
+        domain?: string;
+        id?: string;
+    }): Promise<SiteResponse>;
+    /**
+     * Fetch a specific page by path
+     *
+     * @param params.preview - If true, returns draft content instead of published content (requires API key with site access)
+     */
+    getPage(params: {
+        siteId: string;
+        path: string;
+        preview?: boolean;
+    }): Promise<PageResponse>;
+    /**
+     * Fetch published content entries with optional pagination, sorting, and preview mode
+     *
+     * @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.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')
+     *
+     * @example
+     * ```ts
+     * // Fetch latest 10 blog posts
+     * const entries = await client.getEntries({
+     *   siteId: 'site-id',
+     *   contentType: 'blog-post',
+     *   limit: 10,
+     *   order: 'newest',
+     * });
+     *
+     * // Fetch draft entries for preview
+     * const drafts = await client.getEntries({
+     *   siteId: 'site-id',
+     *   contentType: 'blog-post',
+     *   preview: true,
+     * });
+     *
+     * // Fetch specific entries by ID (manual mode)
+     * const specific = await client.getEntries({
+     *   siteId: 'site-id',
+     *   contentType: 'blog-post',
+     *   mode: 'manual',
+     *   entryIds: ['uuid-1', 'uuid-2'],
+     * });
+     * ```
+     */
+    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[];
+    }): Promise<EntriesResponse>;
+    /**
+     * Fetch a specific content entry by slug
+     */
+    getEntry(params: {
+        siteId: string;
+        contentType: string;
+        slug: string;
+    }): Promise<EntryResponse>;
+    /**
+     * Fetch a public form definition by ID
+     */
+    getPublicFormById(params: {
+        formId: string;
+    }): Promise<PublicFormResponse>;
+    /**
+     * Fetch public booking services for a site
+     */
+    getPublicBookingServices(params: {
+        siteId: string;
+        ids?: string;
+    }): Promise<PublicBookingServicesResponse>;
+    /**
+     * List public events for a site (optionally time-filtered)
+     */
+    listPublicEvents(params: {
+        siteId: string;
+        limit?: number;
+        from?: string;
+        to?: string;
+        stage?: string;
+    }): Promise<PublicEventsResponse>;
+    /**
+     * Force clear the cache
+     */
+    clearCache(): void;
+}
+
+export type { EntriesResponse as E, PageResponse as P, RiverbankClient as R, SiteResponse as S, RiverbankClientConfig as a, EntryResponse as b };

package/package.json

@@ -0,0 +1,147 @@
+{
+  "name": "@riverbankcms/sdk",
+  "version": "0.1.0",
+  "description": "Riverbank CMS SDK for headless content consumption",
+  "main": "./dist/server/index.js",
+  "module": "./dist/server/index.mjs",
+  "types": "./dist/server/index.d.ts",
+  "bin": {
+    "riverbankcms": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.mjs",
+      "require": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/client.d.ts",
+      "import": "./dist/client/client.mjs",
+      "require": "./dist/client/client.js"
+    },
+    "./server": {
+      "types": "./dist/server/server.d.ts",
+      "import": "./dist/server/server.mjs",
+      "require": "./dist/server/server.js"
+    },
+    "./components": {
+      "types": "./dist/server/components.d.ts",
+      "import": "./dist/server/components.mjs",
+      "require": "./dist/server/components.js"
+    },
+    "./rendering": {
+      "types": "./dist/server/rendering.d.ts",
+      "import": "./dist/server/rendering.mjs",
+      "require": "./dist/server/rendering.js"
+    },
+    "./rendering/client": {
+      "types": "./dist/client/rendering/client.d.ts",
+      "import": "./dist/client/rendering/client.mjs",
+      "require": "./dist/client/rendering/client.js"
+    },
+    "./rendering/server": {
+      "types": "./dist/server/rendering/server.d.ts",
+      "import": "./dist/server/rendering/server.mjs",
+      "require": "./dist/server/rendering/server.js"
+    },
+    "./theme": {
+      "types": "./dist/server/theme.d.ts",
+      "import": "./dist/server/theme.mjs",
+      "require": "./dist/server/theme.js"
+    },
+    "./hooks": {
+      "types": "./dist/client/hooks.d.ts",
+      "import": "./dist/client/hooks.mjs",
+      "require": "./dist/client/hooks.js"
+    },
+    "./data": {
+      "types": "./dist/server/data.d.ts",
+      "import": "./dist/server/data.mjs",
+      "require": "./dist/server/data.js"
+    },
+    "./metadata": {
+      "types": "./dist/server/metadata.d.ts",
+      "import": "./dist/server/metadata.mjs",
+      "require": "./dist/server/metadata.js"
+    },
+    "./routing": {
+      "types": "./dist/server/routing.d.ts",
+      "import": "./dist/server/routing.mjs",
+      "require": "./dist/server/routing.js"
+    },
+    "./analytics": {
+      "types": "./dist/client/analytics.d.ts",
+      "import": "./dist/client/analytics.mjs",
+      "require": "./dist/client/analytics.js"
+    },
+    "./config": {
+      "types": "./dist/server/config.d.ts",
+      "import": "./dist/server/config.mjs",
+      "require": "./dist/server/config.js"
+    },
+    "./config/validation": {
+      "types": "./dist/server/config-validation.d.ts",
+      "import": "./dist/server/config-validation.mjs",
+      "require": "./dist/server/config-validation.js"
+    },
+    "./bookings": {
+      "types": "./dist/client/bookings.d.ts",
+      "import": "./dist/client/bookings.mjs",
+      "require": "./dist/client/bookings.js"
+    },
+    "./theme-bridge": {
+      "types": "./dist/server/theme-bridge.d.ts",
+      "import": "./dist/server/theme-bridge.mjs",
+      "require": "./dist/server/theme-bridge.js"
+    },
+    "./styles.css": "./src/styles/index.css"
+  },
+  "files": [
+    "dist",
+    "src/styles",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "verify": "pnpm test"
+  },
+  "dependencies": {
+    "@riverbankcms/api": "workspace:*",
+    "@riverbankcms/blocks": "workspace:*",
+    "@riverbankcms/site-renderer": "workspace:*",
+    "commander": "^12.1.0",
+    "jiti": "^2.6.1",
+    "zod": "^4.1.1"
+  },
+  "peerDependencies": {
+    "react": "19.1.0",
+    "react-dom": "19.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "eslint": "^9.15.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^1.6.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/riverbankcms/riverbankcms.git",
+    "directory": "packages/sdk"
+  },
+  "keywords": [
+    "headless-cms",
+    "riverbankcms",
+    "cms",
+    "content",
+    "sdk"
+  ],
+  "license": "MIT",
+  "private": false
+}

package/src/styles/index.css

@@ -0,0 +1,10 @@
+/**
+ * Builder SDK Base Styles
+ *
+ * These styles are required for Builder blocks to render correctly.
+ * Import this in your app's global CSS file:
+ *
+ * @import "@riverbankcms/sdk/styles.css";
+ */
+
+@import '@riverbankcms/blocks/theme/index.css';