includio-cms 0.21.0 → 0.23.0

package/dist/email-nodemailer/index.d.ts

@@ -10,9 +10,21 @@ interface Options {
  *
  * `nodemailer` is an **optional peer dependency** — install it in your project
  * (`pnpm add nodemailer`) when using this adapter. The SDK loads lazily on first
- * `sendMail()`; missing peer throws a clear error.
+ * `sendMail()`; a missing peer throws a clear error.
  *
+ * @param options - SMTP transport options + default From address/name.
+ * @returns An `EmailAdapter` ready to use in `defineConfig({ email })`.
  * @public
+ * @example
+ * ```ts
+ * import { nodemailerAdapter } from 'includio-cms/email-nodemailer';
+ *
+ * const email = nodemailerAdapter({
+ *   defaultFromAddress: 'no-reply@example.com',
+ *   defaultFromName: 'Example',
+ *   transportOptions: { host: 'smtp.example.com', port: 587 }
+ * });
+ * ```
  */
 export declare function nodemailerAdapter(options: Options): EmailAdapter;
 export {};

package/dist/email-nodemailer/index.js

@@ -3,9 +3,21 @@
  *
  * `nodemailer` is an **optional peer dependency** — install it in your project
  * (`pnpm add nodemailer`) when using this adapter. The SDK loads lazily on first
- * `sendMail()`; missing peer throws a clear error.
+ * `sendMail()`; a missing peer throws a clear error.
  *
+ * @param options - SMTP transport options + default From address/name.
+ * @returns An `EmailAdapter` ready to use in `defineConfig({ email })`.
  * @public
+ * @example
+ * ```ts
+ * import { nodemailerAdapter } from 'includio-cms/email-nodemailer';
+ *
+ * const email = nodemailerAdapter({
+ *   defaultFromAddress: 'no-reply@example.com',
+ *   defaultFromName: 'Example',
+ *   transportOptions: { host: 'smtp.example.com', port: 587 }
+ * });
+ * ```
  */
 export function nodemailerAdapter(options) {
     let transporter = null;

package/dist/entity/index.d.ts

@@ -8,8 +8,23 @@ interface CreateOptions {
     sortOrder?: number;
 }
 /**
- * Creates a high-level Entity API (CRUD + publish/archive) bound to a CMS instance and a user.
+ * Creates a high-level Entity API (CRUD + publish/archive) bound to a CMS
+ * instance and a user. Use it from scripts, migrations, webhooks, or anywhere
+ * server-side that needs programmatic content access.
+ *
+ * @param cms - The CMS instance (typically from `getCMS()`).
+ * @param opts - Optional. `userId` is recorded as the `createdBy` for every
+ *   write (default: `'system'`).
+ * @returns An object with `create`, `update`, `publish`, `unpublish`,
+ *   `archive`, `unarchive`, `delete`, `list`, and `createAndPublish` methods.
  * @public
+ * @example
+ * ```ts
+ * import { getCMS, createEntityAPI } from 'includio-cms';
+ *
+ * const api = createEntityAPI(getCMS(), { userId: 'migration-script' });
+ * await api.createAndPublish('posts', { title: { en: 'Hello' } });
+ * ```
  */
 export declare function createEntityAPI(cms: CMS, opts?: EntityAPIOptions): {
     create(slug: string, data?: EntryData, options?: CreateOptions & {

package/dist/entity/index.js

@@ -2,8 +2,23 @@ import { generateZodSchemaFromFields } from '../core/fields/fieldSchemaToTs.js';
 import { getFieldsFromConfig } from '../core/fields/layoutUtils.js';
 import { _getRawEntries as getRawEntries } from '../core/server/entries/operations/get.js';
 /**
- * Creates a high-level Entity API (CRUD + publish/archive) bound to a CMS instance and a user.
+ * Creates a high-level Entity API (CRUD + publish/archive) bound to a CMS
+ * instance and a user. Use it from scripts, migrations, webhooks, or anywhere
+ * server-side that needs programmatic content access.
+ *
+ * @param cms - The CMS instance (typically from `getCMS()`).
+ * @param opts - Optional. `userId` is recorded as the `createdBy` for every
+ *   write (default: `'system'`).
+ * @returns An object with `create`, `update`, `publish`, `unpublish`,
+ *   `archive`, `unarchive`, `delete`, `list`, and `createAndPublish` methods.
  * @public
+ * @example
+ * ```ts
+ * import { getCMS, createEntityAPI } from 'includio-cms';
+ *
+ * const api = createEntityAPI(getCMS(), { userId: 'migration-script' });
+ * await api.createAndPublish('posts', { title: { en: 'Hello' } });
+ * ```
  */
 export function createEntityAPI(cms, opts) {
     const db = cms.databaseAdapter;

package/dist/files-local/index.d.ts

@@ -6,7 +6,18 @@ export interface LocalFilesConfig {
     ffprobePath?: string;
 }
 /**
- * Local-disk files adapter. Stores uploads under `./static/uploads` (dev) or `/data/uploads` (prod).
+ * Local-disk files adapter. Stores uploads under `./static/uploads` (dev) or
+ * `/data/uploads` (prod, switched on `NODE_ENV`).
+ *
+ * @param config - Optional. Override `ffmpegPath` / `ffprobePath` if the
+ *   binaries are not on `PATH`.
+ * @returns A `FilesAdapter` for local filesystem uploads.
  * @public
+ * @example
+ * ```ts
+ * import { local } from 'includio-cms/files-local';
+ *
+ * const files = local();
+ * ```
  */
 export declare function local(config?: LocalFilesConfig): FilesAdapter;

package/dist/files-local/index.js

@@ -21,8 +21,19 @@ async function ensureDir(dir) {
     }
 }
 /**
- * Local-disk files adapter. Stores uploads under `./static/uploads` (dev) or `/data/uploads` (prod).
+ * Local-disk files adapter. Stores uploads under `./static/uploads` (dev) or
+ * `/data/uploads` (prod, switched on `NODE_ENV`).
+ *
+ * @param config - Optional. Override `ffmpegPath` / `ffprobePath` if the
+ *   binaries are not on `PATH`.
+ * @returns A `FilesAdapter` for local filesystem uploads.
  * @public
+ * @example
+ * ```ts
+ * import { local } from 'includio-cms/files-local';
+ *
+ * const files = local();
+ * ```
  */
 export function local(config) {
     if (config?.ffmpegPath || config?.ffprobePath) {

package/dist/paraglide/messages/_index.d.ts

@@ -1,36 +1,3 @@
-export function hello_world(inputs: {
-    name: NonNullable<unknown>;
-}, options?: {
-    locale?: "en" | "pl";
-}): string;
-/**
-* This function has been compiled by [Paraglide JS](https://inlang.com/m/gerre34r).
-*
-* - Changing this function will be over-written by the next build.
-*
-* - If you want to change the translations, you can either edit the source files e.g. `en.json`, or
-* use another inlang app like [Fink](https://inlang.com/m/tdozzpar) or the [VSCode extension Sherlock](https://inlang.com/m/r7kp499g).
-*
-* @param {{}} inputs
-* @param {{ locale?: "en" | "pl" }} options
-* @returns {string}
-*/
-declare function login_hello(inputs?: {}, options?: {
-    locale?: "en" | "pl";
-}): string;
-/**
-* This function has been compiled by [Paraglide JS](https://inlang.com/m/gerre34r).
-*
-* - Changing this function will be over-written by the next build.
-*
-* - If you want to change the translations, you can either edit the source files e.g. `en.json`, or
-* use another inlang app like [Fink](https://inlang.com/m/tdozzpar) or the [VSCode extension Sherlock](https://inlang.com/m/r7kp499g).
-*
-* @param {{}} inputs
-* @param {{ locale?: "en" | "pl" }} options
-* @returns {string}
-*/
-declare function login_please_login(inputs?: {}, options?: {
-    locale?: "en" | "pl";
-}): string;
-export { login_hello as login.hello, login_please_login as login.please_login };
+export * from "./hello_world.js";
+export * from "./login_hello.js";
+export * from "./login_please_login.js";

package/dist/paraglide/messages/_index.js

@@ -1,72 +1,4 @@
 /* eslint-disable */
-import { getLocale, trackMessageCall, experimentalMiddlewareLocaleSplitting, isServer } from "../runtime.js"
-import * as en from "./en.js"
-import * as pl from "./pl.js"
-/**
-* This function has been compiled by [Paraglide JS](https://inlang.com/m/gerre34r).
-*
-* - Changing this function will be over-written by the next build.
-*
-* - If you want to change the translations, you can either edit the source files e.g. `en.json`, or
-* use another inlang app like [Fink](https://inlang.com/m/tdozzpar) or the [VSCode extension Sherlock](https://inlang.com/m/r7kp499g).
-* 
-* @param {{ name: NonNullable<unknown> }} inputs
-* @param {{ locale?: "en" | "pl" }} options
-* @returns {string}
-*/
-/* @__NO_SIDE_EFFECTS__ */
-export const hello_world = (inputs, options = {}) => {
-	if (experimentalMiddlewareLocaleSplitting && isServer === false) {
-		return /** @type {any} */ (globalThis).__paraglide_ssr.hello_world(inputs) 
-	}
-	const locale = options.locale ?? getLocale()
-	trackMessageCall("hello_world", locale)
-	if (locale === "en") return en.hello_world(inputs)
-	return pl.hello_world(inputs)
-};
-/**
-* This function has been compiled by [Paraglide JS](https://inlang.com/m/gerre34r).
-*
-* - Changing this function will be over-written by the next build.
-*
-* - If you want to change the translations, you can either edit the source files e.g. `en.json`, or
-* use another inlang app like [Fink](https://inlang.com/m/tdozzpar) or the [VSCode extension Sherlock](https://inlang.com/m/r7kp499g).
-* 
-* @param {{}} inputs
-* @param {{ locale?: "en" | "pl" }} options
-* @returns {string}
-*/
-/* @__NO_SIDE_EFFECTS__ */
-const login_hello = (inputs = {}, options = {}) => {
-	if (experimentalMiddlewareLocaleSplitting && isServer === false) {
-		return /** @type {any} */ (globalThis).__paraglide_ssr.login_hello(inputs) 
-	}
-	const locale = options.locale ?? getLocale()
-	trackMessageCall("login_hello", locale)
-	if (locale === "en") return en.login_hello(inputs)
-	return pl.login_hello(inputs)
-};
-export { login_hello as "login.hello" }
-/**
-* This function has been compiled by [Paraglide JS](https://inlang.com/m/gerre34r).
-*
-* - Changing this function will be over-written by the next build.
-*
-* - If you want to change the translations, you can either edit the source files e.g. `en.json`, or
-* use another inlang app like [Fink](https://inlang.com/m/tdozzpar) or the [VSCode extension Sherlock](https://inlang.com/m/r7kp499g).
-* 
-* @param {{}} inputs
-* @param {{ locale?: "en" | "pl" }} options
-* @returns {string}
-*/
-/* @__NO_SIDE_EFFECTS__ */
-const login_please_login = (inputs = {}, options = {}) => {
-	if (experimentalMiddlewareLocaleSplitting && isServer === false) {
-		return /** @type {any} */ (globalThis).__paraglide_ssr.login_please_login(inputs) 
-	}
-	const locale = options.locale ?? getLocale()
-	trackMessageCall("login_please_login", locale)
-	if (locale === "en") return en.login_please_login(inputs)
-	return pl.login_please_login(inputs)
-};
-export { login_please_login as "login.please_login" }
+export * from './hello_world.js'
+export * from './login_hello.js'
+export * from './login_please_login.js'

package/dist/paraglide/messages/hello_world.d.ts

@@ -0,0 +1,5 @@
+export function hello_world(inputs: {
+    name: NonNullable<unknown>;
+}, options?: {
+    locale?: "en" | "pl";
+}): string;

package/dist/paraglide/messages/hello_world.js

@@ -0,0 +1,33 @@
+/* eslint-disable */
+import { getLocale, trackMessageCall, experimentalMiddlewareLocaleSplitting, isServer } from '../runtime.js';
+
+const en_hello_world = /** @type {(inputs: { name: NonNullable<unknown> }) => string} */ (i) => {
+	return `Hello, ${i.name} from en!`
+};
+
+const pl_hello_world = /** @type {(inputs: { name: NonNullable<unknown> }) => string} */ (i) => {
+	return `Hello, ${i.name} from pl!`
+};
+
+/**
+* This function has been compiled by [Paraglide JS](https://inlang.com/m/gerre34r).
+*
+* - Changing this function will be over-written by the next build.
+*
+* - If you want to change the translations, you can either edit the source files e.g. `en.json`, or
+* use another inlang app like [Fink](https://inlang.com/m/tdozzpar) or the [VSCode extension Sherlock](https://inlang.com/m/r7kp499g).
+* 
+* @param {{ name: NonNullable<unknown> }} inputs
+* @param {{ locale?: "en" | "pl" }} options
+* @returns {string}
+*/
+/* @__NO_SIDE_EFFECTS__ */
+export const hello_world = (inputs, options = {}) => {
+	if (experimentalMiddlewareLocaleSplitting && isServer === false) {
+		return /** @type {any} */ (globalThis).__paraglide_ssr.hello_world(inputs) 
+	}
+	const locale = options.locale ?? getLocale()
+	trackMessageCall("hello_world", locale)
+	if (locale === "en") return en_hello_world(inputs)
+	return pl_hello_world(inputs)
+};

package/dist/paraglide/messages/login_hello.d.ts

@@ -0,0 +1,16 @@
+export { login_hello as login.hello };
+/**
+* This function has been compiled by [Paraglide JS](https://inlang.com/m/gerre34r).
+*
+* - Changing this function will be over-written by the next build.
+*
+* - If you want to change the translations, you can either edit the source files e.g. `en.json`, or
+* use another inlang app like [Fink](https://inlang.com/m/tdozzpar) or the [VSCode extension Sherlock](https://inlang.com/m/r7kp499g).
+*
+* @param {{}} inputs
+* @param {{ locale?: "en" | "pl" }} options
+* @returns {string}
+*/
+declare function login_hello(inputs?: {}, options?: {
+    locale?: "en" | "pl";
+}): string;

package/dist/paraglide/messages/login_hello.js

@@ -0,0 +1,34 @@
+/* eslint-disable */
+import { getLocale, trackMessageCall, experimentalMiddlewareLocaleSplitting, isServer } from '../runtime.js';
+
+const en_login_hello = /** @type {(inputs: {}) => string} */ () => {
+	return `Welcome back`
+};
+
+const pl_login_hello = /** @type {(inputs: {}) => string} */ () => {
+	return `Witaj ponownie`
+};
+
+/**
+* This function has been compiled by [Paraglide JS](https://inlang.com/m/gerre34r).
+*
+* - Changing this function will be over-written by the next build.
+*
+* - If you want to change the translations, you can either edit the source files e.g. `en.json`, or
+* use another inlang app like [Fink](https://inlang.com/m/tdozzpar) or the [VSCode extension Sherlock](https://inlang.com/m/r7kp499g).
+* 
+* @param {{}} inputs
+* @param {{ locale?: "en" | "pl" }} options
+* @returns {string}
+*/
+/* @__NO_SIDE_EFFECTS__ */
+const login_hello = (inputs = {}, options = {}) => {
+	if (experimentalMiddlewareLocaleSplitting && isServer === false) {
+		return /** @type {any} */ (globalThis).__paraglide_ssr.login_hello(inputs) 
+	}
+	const locale = options.locale ?? getLocale()
+	trackMessageCall("login_hello", locale)
+	if (locale === "en") return en_login_hello(inputs)
+	return pl_login_hello(inputs)
+};
+export { login_hello as "login.hello" }

package/dist/paraglide/messages/login_please_login.d.ts

@@ -0,0 +1,16 @@
+export { login_please_login as login.please_login };
+/**
+* This function has been compiled by [Paraglide JS](https://inlang.com/m/gerre34r).
+*
+* - Changing this function will be over-written by the next build.
+*
+* - If you want to change the translations, you can either edit the source files e.g. `en.json`, or
+* use another inlang app like [Fink](https://inlang.com/m/tdozzpar) or the [VSCode extension Sherlock](https://inlang.com/m/r7kp499g).
+*
+* @param {{}} inputs
+* @param {{ locale?: "en" | "pl" }} options
+* @returns {string}
+*/
+declare function login_please_login(inputs?: {}, options?: {
+    locale?: "en" | "pl";
+}): string;

package/dist/paraglide/messages/login_please_login.js

@@ -0,0 +1,34 @@
+/* eslint-disable */
+import { getLocale, trackMessageCall, experimentalMiddlewareLocaleSplitting, isServer } from '../runtime.js';
+
+const en_login_please_login = /** @type {(inputs: {}) => string} */ () => {
+	return `Login to your account`
+};
+
+const pl_login_please_login = /** @type {(inputs: {}) => string} */ () => {
+	return `Zaloguj się na swoje konto`
+};
+
+/**
+* This function has been compiled by [Paraglide JS](https://inlang.com/m/gerre34r).
+*
+* - Changing this function will be over-written by the next build.
+*
+* - If you want to change the translations, you can either edit the source files e.g. `en.json`, or
+* use another inlang app like [Fink](https://inlang.com/m/tdozzpar) or the [VSCode extension Sherlock](https://inlang.com/m/r7kp499g).
+* 
+* @param {{}} inputs
+* @param {{ locale?: "en" | "pl" }} options
+* @returns {string}
+*/
+/* @__NO_SIDE_EFFECTS__ */
+const login_please_login = (inputs = {}, options = {}) => {
+	if (experimentalMiddlewareLocaleSplitting && isServer === false) {
+		return /** @type {any} */ (globalThis).__paraglide_ssr.login_please_login(inputs) 
+	}
+	const locale = options.locale ?? getLocale()
+	trackMessageCall("login_please_login", locale)
+	if (locale === "en") return en_login_please_login(inputs)
+	return pl_login_please_login(inputs)
+};
+export { login_please_login as "login.please_login" }

package/dist/server/auth.d.ts

@@ -1,5 +1,16 @@
 /**
  * Returns the underlying `better-auth` instance from the initialized CMS.
+ * Use it to integrate with custom auth flows or read session data.
+ *
+ * @returns The `better-auth` instance configured by the CMS.
+ * @throws {Error} when the CMS was started without `auth` config.
  * @public
+ * @example
+ * ```ts
+ * import { getAuth } from 'includio-cms/sveltekit/server';
+ *
+ * const auth = getAuth();
+ * const session = await auth.api.getSession({ headers: request.headers });
+ * ```
  */
 export declare function getAuth(): import("better-auth", { with: { "resolution-mode": "require" } }).Auth<import("better-auth", { with: { "resolution-mode": "require" } }).BetterAuthOptions>;

package/dist/server/auth.js

@@ -1,7 +1,18 @@
 import { getCMS } from '../core/cms.js';
 /**
  * Returns the underlying `better-auth` instance from the initialized CMS.
+ * Use it to integrate with custom auth flows or read session data.
+ *
+ * @returns The `better-auth` instance configured by the CMS.
+ * @throws {Error} when the CMS was started without `auth` config.
  * @public
+ * @example
+ * ```ts
+ * import { getAuth } from 'includio-cms/sveltekit/server';
+ *
+ * const auth = getAuth();
+ * const session = await auth.api.getSession({ headers: request.headers });
+ * ```
  */
 export function getAuth() {
     return getCMS().auth;

package/dist/sveltekit/config.d.ts

@@ -14,27 +14,90 @@ type SingleInput = Omit<SingleConfig, 'fields'> & {
 };
 /**
  * Defines the root CMS configuration. Pass to `includioCMS()` in `hooks.server.ts`.
+ *
+ * Runs strict runtime validation: invalid configs throw a `ConfigValidationError`
+ * (extends `CmsError`) listing every issue with a path and a fix hint, e.g.
+ *   `languages[0].code: must be a 2-letter ISO code (e.g. 'en')`
+ *
+ * @param config - The CMSConfig (collections, singles, forms, adapters, languages, ...).
+ * @returns The same config, parsed and frozen against typos.
+ * @throws {ConfigValidationError} when validation fails — message aggregates all issues.
  * @public
+ * @example
+ * ```ts
+ * import { defineConfig } from 'includio-cms';
+ * export default defineConfig({
+ *   languages: [{ code: 'en', default: true }],
+ *   db, files,
+ *   collections: [postsCollection]
+ * });
+ * ```
  */
 export declare function defineConfig(config: CMSConfig): CMSConfig;
 /**
- * Defines a collection (multi-entry content type).
+ * Defines a collection (multi-entry content type, e.g. blog posts, products).
+ *
+ * @param config - Collection config with slug, fields, and optional layout/labels/icon.
+ * @returns A typed `CollectionConfig` ready to drop into `defineConfig({ collections: [...] })`.
  * @public
+ * @example
+ * ```ts
+ * export const posts = defineCollection({
+ *   slug: 'posts',
+ *   labels: { singular: 'Post', plural: 'Posts' },
+ *   fields: [{ slug: 'title', type: 'text', required: true }]
+ * });
+ * ```
  */
 export declare function defineCollection(config: CollectionInput): CollectionConfig;
 /**
- * Defines a singleton (single-entry content type, e.g. site settings).
+ * Defines a singleton (single-entry content type, e.g. site settings, homepage).
+ *
+ * @param config - Single config with slug, fields, and optional label/layout.
+ * @returns A typed `SingleConfig` ready to drop into `defineConfig({ singles: [...] })`.
  * @public
+ * @example
+ * ```ts
+ * export const settings = defineSingle({
+ *   slug: 'settings',
+ *   fields: [{ slug: 'siteName', type: 'text' }]
+ * });
+ * ```
  */
 export declare function defineSingle(config: SingleInput): SingleConfig;
 /**
- * Defines a public form (submitted via `/api/forms/[slug]/submit`).
+ * Defines a public form (submitted via `POST /api/forms/[slug]/submit`).
+ *
+ * @param config - Form config with slug, label, fields, and optional notification emails.
+ * @returns The `FormConfig` ready to drop into `defineConfig({ forms: [...] })`.
  * @public
+ * @example
+ * ```ts
+ * export const contact = defineForm({
+ *   slug: 'contact',
+ *   label: 'Contact us',
+ *   fields: [{ slug: 'email', type: 'email', required: true }]
+ * });
+ * ```
  */
 export declare function defineForm(config: FormConfig): FormConfig;
 /**
- * Defines a reusable object field (nested record). Use inside `fields[]`.
+ * Defines a reusable object field (nested record). Use inline inside `fields[]`
+ * or as an entry in a `blocks` field.
+ *
+ * @param config - Object field shape sans the `type` discriminator.
+ * @returns The full `ObjectField` (with `type: 'object'` injected).
  * @public
+ * @example
+ * ```ts
+ * const cta = defineObject({
+ *   slug: 'cta',
+ *   fields: [
+ *     { slug: 'label', type: 'text' },
+ *     { slug: 'href', type: 'url' }
+ *   ]
+ * });
+ * ```
  */
 export declare function defineObject(config: Omit<ObjectField, 'type'>): ObjectField;
 export {};

package/dist/sveltekit/config.js

@@ -1,34 +1,103 @@
+import { cmsConfigSchema } from '../types/cms.schema.js';
+import { formatConfigError } from '../core/errors.js';
 /**
  * Defines the root CMS configuration. Pass to `includioCMS()` in `hooks.server.ts`.
+ *
+ * Runs strict runtime validation: invalid configs throw a `ConfigValidationError`
+ * (extends `CmsError`) listing every issue with a path and a fix hint, e.g.
+ *   `languages[0].code: must be a 2-letter ISO code (e.g. 'en')`
+ *
+ * @param config - The CMSConfig (collections, singles, forms, adapters, languages, ...).
+ * @returns The same config, parsed and frozen against typos.
+ * @throws {ConfigValidationError} when validation fails — message aggregates all issues.
  * @public
+ * @example
+ * ```ts
+ * import { defineConfig } from 'includio-cms';
+ * export default defineConfig({
+ *   languages: [{ code: 'en', default: true }],
+ *   db, files,
+ *   collections: [postsCollection]
+ * });
+ * ```
  */
 export function defineConfig(config) {
+    const result = cmsConfigSchema.safeParse(config);
+    if (!result.success) {
+        throw formatConfigError(result.error);
+    }
     return config;
 }
 /**
- * Defines a collection (multi-entry content type).
+ * Defines a collection (multi-entry content type, e.g. blog posts, products).
+ *
+ * @param config - Collection config with slug, fields, and optional layout/labels/icon.
+ * @returns A typed `CollectionConfig` ready to drop into `defineConfig({ collections: [...] })`.
  * @public
+ * @example
+ * ```ts
+ * export const posts = defineCollection({
+ *   slug: 'posts',
+ *   labels: { singular: 'Post', plural: 'Posts' },
+ *   fields: [{ slug: 'title', type: 'text', required: true }]
+ * });
+ * ```
  */
 export function defineCollection(config) {
     return config;
 }
 /**
- * Defines a singleton (single-entry content type, e.g. site settings).
+ * Defines a singleton (single-entry content type, e.g. site settings, homepage).
+ *
+ * @param config - Single config with slug, fields, and optional label/layout.
+ * @returns A typed `SingleConfig` ready to drop into `defineConfig({ singles: [...] })`.
  * @public
+ * @example
+ * ```ts
+ * export const settings = defineSingle({
+ *   slug: 'settings',
+ *   fields: [{ slug: 'siteName', type: 'text' }]
+ * });
+ * ```
  */
 export function defineSingle(config) {
     return config;
 }
 /**
- * Defines a public form (submitted via `/api/forms/[slug]/submit`).
+ * Defines a public form (submitted via `POST /api/forms/[slug]/submit`).
+ *
+ * @param config - Form config with slug, label, fields, and optional notification emails.
+ * @returns The `FormConfig` ready to drop into `defineConfig({ forms: [...] })`.
  * @public
+ * @example
+ * ```ts
+ * export const contact = defineForm({
+ *   slug: 'contact',
+ *   label: 'Contact us',
+ *   fields: [{ slug: 'email', type: 'email', required: true }]
+ * });
+ * ```
  */
 export function defineForm(config) {
     return config;
 }
 /**
- * Defines a reusable object field (nested record). Use inside `fields[]`.
+ * Defines a reusable object field (nested record). Use inline inside `fields[]`
+ * or as an entry in a `blocks` field.
+ *
+ * @param config - Object field shape sans the `type` discriminator.
+ * @returns The full `ObjectField` (with `type: 'object'` injected).
  * @public
+ * @example
+ * ```ts
+ * const cta = defineObject({
+ *   slug: 'cta',
+ *   fields: [
+ *     { slug: 'label', type: 'text' },
+ *     { slug: 'href', type: 'url' }
+ *   ]
+ * });
+ * ```
  */
 export function defineObject(config) {
     return { ...config, type: 'object' };

package/dist/sveltekit/server/handle.d.ts

@@ -1,7 +1,21 @@
 import { type Handle } from '@sveltejs/kit';
 import type { CMSConfig } from '../../types/cms.js';
 /**
- * SvelteKit `Handle[]` array that initializes the CMS, generates runtime artifacts, wires auth/admin guards, and exposes `event.locals.cmsContext`. Compose with `sequence()` in `hooks.server.ts`.
+ * SvelteKit `Handle[]` array that initializes the CMS, generates runtime
+ * artifacts, wires auth/admin guards, and exposes `event.locals.cmsContext`.
+ * Compose with `sequence()` in `hooks.server.ts`.
+ *
+ * @param cmsConfig - The output of `defineConfig({ ... })`.
+ * @returns An array of `Handle` middlewares. Pass to `sequence()`.
  * @public
+ * @example
+ * ```ts
+ * // src/hooks.server.ts
+ * import { sequence } from '@sveltejs/kit/hooks';
+ * import { includioCMS } from 'includio-cms/sveltekit/server';
+ * import cmsConfig from '../../cms/cms.config';
+ *
+ * export const handle = sequence(...includioCMS(cmsConfig));
+ * ```
  */
 export declare function includioCMS(cmsConfig: CMSConfig): Handle[];