@lemonadecms/client 0.2.0 → 0.2.2

package/dist/rich-text-v2.d.ts

@@ -0,0 +1,20 @@
+export type ExternalMediaProvider = 'youtube' | 'vimeo' | 'spotify' | 'soundcloud';
+export interface ExternalMediaDescriptor {
+    provider: ExternalMediaProvider;
+    url: string;
+    embedUrl: string;
+    title: string;
+    caption: string;
+    transcript: string;
+    poster: {
+        id: string;
+        url: string;
+        alt: string;
+    } | null;
+}
+/** The only relative URL accepted by first-party renderers is the private website asset proxy. */
+export declare function safeRichTextURL(value: unknown, image: boolean): string | null;
+/** Pure player metadata. This performs no fetches, creates no iframe and grants no playback consent. */
+export declare function externalMediaDescriptor(value: unknown): ExternalMediaDescriptor;
+/** Strict v2 validation protects renderers from silently dropping unknown future nodes. */
+export declare function assertRichTextV2(value: unknown): void;

package/dist/rich-text-v2.js

@@ -0,0 +1,242 @@
+import { CMSResponseError } from './errors.js';
+const encoder = new TextEncoder();
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+const identifier = /^[a-z][a-z0-9_]{0,47}$/;
+const imageTypes = ['image/jpeg', 'image/png', 'image/webp', 'image/gif'];
+const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const own = (value, keys) => Object.keys(value).every(key => keys.includes(key));
+function invalid() {
+    throw new CMSResponseError('Invalid or unsupported rich-text v2 document.');
+}
+const validString = (value, max, min = 0) => typeof value === 'string' && !/[\u0000\ud800-\udfff]/u.test(value) &&
+    encoder.encode(value).byteLength >= min && encoder.encode(value).byteLength <= max;
+/** The only relative URL accepted by first-party renderers is the private website asset proxy. */
+export function safeRichTextURL(value, image) {
+    if (typeof value !== 'string' || value.length > (image ? 4096 : 2048) ||
+        /[\s\\\u0000-\u0020\u007f-\u009f]/u.test(value))
+        return null;
+    if (image && /^\/lemonade\/preview\/assets\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}(?:\?[^#]+)?$/i.test(value)) {
+        const params = new URL(value, 'https://preview.invalid').searchParams;
+        const keys = [];
+        params.forEach((_value, key) => keys.push(key));
+        const recipes = ['hero-640', 'hero-1280', 'card-320', 'card-640', 'social-1200'];
+        if (keys.length > 4 || new Set(keys).size !== keys.length ||
+            keys.some(key => !['rendition', 'v', 'impact', 'composition'].includes(key)) ||
+            (params.has('rendition') && !recipes.includes(params.get('rendition'))) ||
+            (params.has('v') && !/^[A-Za-z0-9_-]{43}$/.test(params.get('v'))) ||
+            (params.has('impact') && !['before', 'after'].includes(params.get('impact'))) ||
+            (params.has('composition') && (params.get('composition').length > 2048 ||
+                !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(params.get('composition')))))
+            return null;
+        return value;
+    }
+    if (!/^https?:\/\//i.test(value) && (image || !/^mailto:/i.test(value)))
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.username || url.password)
+            return null;
+        if ((url.protocol === 'https:' || url.protocol === 'http:') && url.hostname)
+            return value;
+        return !image && url.protocol === 'mailto:' && url.pathname ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function external(attrs) {
+    if (!record(attrs) || !own(attrs, ['provider', 'url', 'title', 'caption', 'transcript', 'poster']) ||
+        !validString(attrs.title, 500, 1) || !/[^\p{White_Space}]/u.test(attrs.title) ||
+        !validString(attrs.caption, 2000) || !validString(attrs.transcript, 20_000) ||
+        !validString(attrs.url, 2048, 1) ||
+        (attrs.poster !== undefined && (typeof attrs.poster !== 'string' || !uuid.test(attrs.poster))))
+        invalid();
+    const { provider, url, title, caption, transcript } = attrs;
+    let embedUrl;
+    let match;
+    if (provider === 'youtube' && (match = url.match(/^https:\/\/www\.youtube\.com\/watch\?v=([A-Za-z0-9_-]{11})$/))) {
+        embedUrl = `https://www.youtube-nocookie.com/embed/${match[1]}`;
+    }
+    else if (provider === 'vimeo' && (match = url.match(/^https:\/\/vimeo\.com\/([1-9][0-9]{0,11})$/))) {
+        embedUrl = `https://player.vimeo.com/video/${match[1]}?dnt=1`;
+    }
+    else if (provider === 'spotify' && (match = url.match(/^https:\/\/open\.spotify\.com\/episode\/([A-Za-z0-9]{22})$/))) {
+        embedUrl = `https://open.spotify.com/embed/episode/${match[1]}`;
+    }
+    else if (provider === 'soundcloud' && (match = url.match(/^https:\/\/soundcloud\.com\/([A-Za-z0-9][A-Za-z0-9_-]{0,199})\/([A-Za-z0-9][A-Za-z0-9_-]{0,199})$/)) &&
+        !['sets', 'playlists', 'discover', 'charts', 'search', 'you'].includes(match[1].toLowerCase()) &&
+        !['sets', 'tracks', 'albums', 'reposts', 'likes', 'popular-tracks'].includes(match[2].toLowerCase())) {
+        embedUrl = `https://w.soundcloud.com/player/?url=${encodeURIComponent(url)}&auto_play=false`;
+    }
+    else
+        invalid();
+    return { provider: provider, url, embedUrl, title, caption, transcript };
+}
+/** Pure player metadata. This performs no fetches, creates no iframe and grants no playback consent. */
+export function externalMediaDescriptor(value) {
+    if (!record(value) || value.type !== 'externalMedia' || !own(value, ['type', 'attrs', 'resource']))
+        invalid();
+    const descriptor = external(value.attrs);
+    const attrs = value.attrs;
+    const resource = value.resource;
+    let poster = null;
+    if (typeof attrs.poster === 'string' && record(resource) && typeof resource.id === 'string' &&
+        attrs.poster.toLowerCase() === resource.id.toLowerCase() && typeof resource.content_type === 'string' && imageTypes.includes(resource.content_type)) {
+        const url = safeRichTextURL(resource.url, true);
+        const metadata = record(resource.metadata) ? resource.metadata : {};
+        if (url)
+            poster = { id: attrs.poster, url, alt: validString(metadata.alt, 2000) ? metadata.alt : '' };
+    }
+    return { ...descriptor, poster };
+}
+/** Strict v2 validation protects renderers from silently dropping unknown future nodes. */
+export function assertRichTextV2(value) {
+    if (!record(value) || value.version !== 2 || !own(value, ['version', 'document']))
+        invalid();
+    let remaining = 500, embeds = 20, bytes = 65_536;
+    const string = (value, max, min = 0) => {
+        if (!validString(value, max, min))
+            invalid();
+        bytes -= encoder.encode(value).byteLength;
+        if (bytes < 0)
+            invalid();
+        return value;
+    };
+    function node(value, context, depth) {
+        if (!record(value) || depth > 8 || --remaining < 0 || typeof value.type !== 'string')
+            invalid();
+        const children = (next, min = 0) => {
+            const list = value.content ?? [];
+            if (!Array.isArray(list) || list.length < min || list.length > 200)
+                invalid();
+            for (const child of list)
+                node(child, next, depth + 1);
+            return list;
+        };
+        if (context === 'inline' || context === 'code') {
+            if (context === 'inline' && value.type === 'hardBreak' && own(value, ['type']))
+                return;
+            if (value.type !== 'text' || !own(value, context === 'code' ? ['type', 'text'] : ['type', 'text', 'marks']))
+                invalid();
+            string(value.text, 20_000, 1);
+            if (context === 'code')
+                return;
+            const marks = value.marks ?? [];
+            if (!Array.isArray(marks) || marks.length > 6)
+                invalid();
+            const seen = new Set();
+            for (const mark of marks) {
+                if (!record(mark) || typeof mark.type !== 'string' || seen.has(mark.type))
+                    invalid();
+                seen.add(mark.type);
+                if (mark.type === 'link') {
+                    if (!own(mark, ['type', 'attrs']) || !record(mark.attrs) || !own(mark.attrs, ['href']) ||
+                        !safeRichTextURL(string(mark.attrs.href, 2048, 1), false))
+                        invalid();
+                }
+                else if (!['bold', 'italic', 'underline', 'strike', 'code'].includes(mark.type) || !own(mark, ['type']))
+                    invalid();
+            }
+            return;
+        }
+        if (context === 'root') {
+            if (value.type !== 'doc' || !own(value, ['type', 'content']))
+                invalid();
+            children('block');
+            return;
+        }
+        if (context === 'list') {
+            if (value.type !== 'listItem' || !own(value, ['type', 'content']) || !Array.isArray(value.content) ||
+                !record(value.content[0]) || value.content[0].type !== 'paragraph')
+                invalid();
+            children('item', 1);
+            return;
+        }
+        if (context === 'row' || context === 'headerRow') {
+            if (value.type !== (context === 'headerRow' ? 'tableHeader' : 'tableCell') ||
+                !own(value, ['type', 'content']) || !Array.isArray(value.content) || value.content.length !== 1)
+                invalid();
+            children('cell', 1);
+            return;
+        }
+        if (value.type === 'paragraph' && ['block', 'item', 'quote', 'cell'].includes(context)) {
+            if (!own(value, ['type', 'content']))
+                invalid();
+            children('inline');
+            return;
+        }
+        if (['bulletList', 'orderedList'].includes(value.type) && ['block', 'item'].includes(context)) {
+            if (!own(value, ['type', 'content', 'attrs']) ||
+                (value.attrs !== undefined && (!record(value.attrs) || !own(value.attrs, ['start']) ||
+                    Object.keys(value.attrs).length > 0 && (value.type !== 'orderedList' || value.attrs.start !== 1))))
+                invalid();
+            children('list', 1);
+            return;
+        }
+        if (context !== 'block')
+            invalid();
+        if (value.type === 'heading') {
+            if (!own(value, ['type', 'attrs', 'content']) || !record(value.attrs) ||
+                !own(value.attrs, ['level']) || typeof value.attrs.level !== 'number' || ![2, 3, 4].includes(value.attrs.level))
+                invalid();
+            children('inline');
+            return;
+        }
+        if (value.type === 'blockquote') {
+            if (!own(value, ['type', 'content']))
+                invalid();
+            children('quote', 1);
+            return;
+        }
+        if (value.type === 'codeBlock') {
+            if (!own(value, ['type', 'attrs', 'content']) || !record(value.attrs) || !own(value.attrs, ['language']))
+                invalid();
+            const language = string(value.attrs.language, 32);
+            if (language !== '' && !/^[A-Za-z][A-Za-z0-9_+.#-]{0,31}$/.test(language))
+                invalid();
+            children('code');
+            return;
+        }
+        if (value.type === 'table') {
+            if (!own(value, ['type', 'attrs', 'content']) || !record(value.attrs) ||
+                !own(value.attrs, ['caption', 'header']) || typeof value.attrs.header !== 'boolean' ||
+                !Array.isArray(value.content) || value.content.length < 1 || value.content.length > 20)
+                invalid();
+            string(value.attrs.caption, 500);
+            let columns = 0;
+            for (let index = 0; index < value.content.length; index++) {
+                const row = value.content[index];
+                if (!record(row) || --remaining < 0 || depth + 1 > 8 || row.type !== 'tableRow' ||
+                    !own(row, ['type', 'content']) || !Array.isArray(row.content) || row.content.length < 1 || row.content.length > 6)
+                    invalid();
+                columns ||= row.content.length;
+                if (row.content.length !== columns)
+                    invalid();
+                for (const cell of row.content)
+                    node(cell, index === 0 && value.attrs.header ? 'headerRow' : 'row', depth + 2);
+            }
+            return;
+        }
+        if (!['image', 'entry', 'externalMedia'].includes(value.type) || --embeds < 0)
+            invalid();
+        if (value.type === 'externalMedia') {
+            if (!own(value, ['type', 'attrs', 'resource']))
+                invalid();
+            external(value.attrs);
+            const attrs = value.attrs;
+            string(attrs.title, 500, 1);
+            string(attrs.caption, 2000);
+            string(attrs.transcript, 20_000);
+            return;
+        }
+        if (!own(value, ['type', 'attrs', 'resource']) || !record(value.attrs) ||
+            !own(value.attrs, value.type === 'image' ? ['id', 'alt'] : ['id', 'target']) ||
+            typeof value.attrs.id !== 'string' || !uuid.test(value.attrs.id))
+            invalid();
+        if (value.type === 'image')
+            string(value.attrs.alt, 2000);
+        else if (typeof value.attrs.target !== 'string' || !identifier.test(value.attrs.target))
+            invalid();
+    }
+    node(value.document, 'root', 0);
+}

package/dist/rich-text.d.ts

@@ -1,4 +1,6 @@
-/** Escaped HTML for rich-text v1, including safe expanded images/entry captions. */
+export { externalMediaDescriptor } from './rich-text-v2.js';
+export type { ExternalMediaDescriptor, ExternalMediaProvider } from './rich-text-v2.js';
+/** Escaped HTML; v2 rejects malformed/unknown nodes. External media remains a static card. */
 export declare function richTextToHtml(value: unknown): string;
 /** Authored text with block/hard-break newlines; excludes embeds and link URLs. */
 export declare function richTextToPlainText(value: unknown): string;

package/dist/rich-text.js

@@ -1,3 +1,9 @@
+// Pure presentation helpers for delivered Lemonade rich-text documents.
+// Values are deliberately unknown: generated types are not runtime validation.
+// Never follow resource fields recursively or infer routes/authorization from IDs.
+import { CMSResponseError } from './errors.js';
+import { assertRichTextV2, externalMediaDescriptor, safeRichTextURL } from './rich-text-v2.js';
+export { externalMediaDescriptor } from './rich-text-v2.js';
 const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
 const model = /^[a-z][a-z0-9_]{0,47}$/;
 const encoder = new TextEncoder();
@@ -20,29 +26,7 @@ function escape(value) {
         }
     });
 }
-function safeUrl(value, image) {
-    if (typeof value !== 'string' ||
-        value.length > (image ? 4096 : 2048) ||
-        /[\s\\\u0000-\u0020\u007f-\u009f]/u.test(value))
-        return null;
-    // Only the consuming-site preview proxy's fixed same-origin route is relative.
-    if (image &&
-        /^\/lemonade\/preview\/assets\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(value))
-        return value;
-    if (!/^https?:\/\//i.test(value) && (image || !/^mailto:/i.test(value)))
-        return null;
-    try {
-        const url = new URL(value);
-        if (url.username || url.password)
-            return null;
-        if ((url.protocol === 'https:' || url.protocol === 'http:') && url.hostname)
-            return value;
-        return !image && url.protocol === 'mailto:' && url.pathname ? value : null;
-    }
-    catch {
-        return null;
-    }
-}
+const safeUrl = safeRichTextURL;
 function matchingResource(node) {
     const attrs = node.attrs, resource = node.resource;
     if (!record(attrs) ||
@@ -57,8 +41,13 @@ function matchingResource(node) {
     return resource;
 }
 function convert(value, format) {
+    if (record(value) && value.version !== undefined && value.version !== 1 && value.version !== 2)
+        throw new CMSResponseError('Unsupported rich-text document version.');
+    const version2 = record(value) && value.version === 2;
+    if (version2)
+        assertRichTextV2(value);
     if (!record(value) ||
-        value.version !== 1 ||
+        (value.version !== 1 && value.version !== 2) ||
         !record(value.document) ||
         value.document.type !== 'doc')
         return '';
@@ -159,6 +148,38 @@ function convert(value, format) {
                 ? `<p>${content}</p>`
                 : content + (context === 'item' ? '\n' : '\n\n');
         }
+        if (version2 && value.type === 'blockquote' && context === 'block') {
+            const content = children('quote');
+            return format === 'html' ? `<blockquote>${content}</blockquote>` : content;
+        }
+        if (version2 && value.type === 'codeBlock' && context === 'block') {
+            const content = Array.isArray(value.content)
+                ? value.content.map(node => record(node) ? string(node.text) : '').join('') : '';
+            const language = record(value.attrs) && typeof value.attrs.language === 'string' ? value.attrs.language : '';
+            return format === 'html'
+                ? `<pre><code${language ? ` class="language-${escape(language)}"` : ''}>${escape(content)}</code></pre>`
+                : content + '\n\n';
+        }
+        if (version2 && value.type === 'table' && context === 'block') {
+            const caption = record(value.attrs) ? string(value.attrs.caption, 500) : '';
+            const header = record(value.attrs) && value.attrs.header === true;
+            const rows = Array.isArray(value.content) ? value.content.map((row, index) => {
+                const cells = record(row) && Array.isArray(row.content) ? row.content.map(cell => visit(cell, 'row', depth + 2)).join(format === 'html' ? '' : '\t') : '';
+                if (format !== 'html')
+                    return cells;
+                const rendered = `<tr>${cells}</tr>`;
+                return header && index === 0 ? `<thead>${rendered}</thead><tbody>` : rendered;
+            }) : [];
+            return format === 'html'
+                ? `<table><caption>${escape(caption)}</caption>${header ? '' : '<tbody>'}${rows.join('')}</tbody></table>`
+                : (caption ? caption + '\n' : '') + rows.join('\n') + '\n\n';
+        }
+        if (version2 && ['tableCell', 'tableHeader'].includes(String(value.type)) && context === 'row') {
+            const content = children('cell');
+            if (format === 'text')
+                return content.trimEnd();
+            return value.type === 'tableHeader' ? `<th scope="col">${content}</th>` : `<td>${content}</td>`;
+        }
         if (value.type === 'bulletList' || value.type === 'orderedList') {
             const content = children('list');
             const tag = value.type === 'bulletList' ? 'ul' : 'ol';
@@ -178,6 +199,18 @@ function convert(value, format) {
                 ? `<h${value.attrs.level}>${content}</h${value.attrs.level}>`
                 : content + '\n\n';
         }
+        if (version2 && value.type === 'externalMedia') {
+            if (--embeds < 0) {
+                exhausted = true;
+                return '';
+            }
+            const media = externalMediaDescriptor(value);
+            const title = string(media.title, 500), caption = string(media.caption, 2000), transcript = string(media.transcript);
+            if (format === 'text')
+                return [title, caption, transcript].filter(Boolean).join('\n') + '\n\n';
+            const poster = media.poster ? `<img src="${escape(string(media.poster.url, 4096))}" alt="${escape(string(media.poster.alt, 2000))}" loading="lazy" decoding="async">` : '';
+            return `<figure class="rich-text-external-media" data-lemonade-media-provider="${media.provider}" data-lemonade-media-url="${escape(string(media.url, 2048))}"><a href="${escape(media.url)}" rel="noopener noreferrer">${poster}<span data-lemonade-media-title>${escape(title)}</span><span class="rich-text-provider-link">Open on ${media.provider}</span></a><p class="rich-text-provider">External media: ${media.provider}</p>${caption ? `<figcaption>${escape(caption)}</figcaption>` : ''}${transcript ? `<div class="rich-text-transcript"><p class="rich-text-transcript-label">Transcript</p><p>${escape(transcript).replaceAll('\n', '<br>')}</p></div>` : ''}</figure>`;
+        }
         if (value.type !== 'image' && value.type !== 'entry')
             return '';
         if (--embeds < 0) {
@@ -216,9 +249,11 @@ function convert(value, format) {
             : '';
     }
     const output = visit(value.document, 'root', 0);
+    if (version2 && exhausted)
+        throw new CMSResponseError('Rich-text v2 exceeds the rendering budget.');
     return exhausted ? '' : format === 'text' ? output.trim() : output;
 }
-/** Escaped HTML for rich-text v1, including safe expanded images/entry captions. */
+/** Escaped HTML; v2 rejects malformed/unknown nodes. External media remains a static card. */
 export function richTextToHtml(value) {
     return convert(value, 'html');
 }

package/dist/server.d.ts

@@ -1,10 +1,11 @@
-import type { CMSClient, CMSPreviewOptions, ModelMap, PreviewModels, UntypedModels } from "./types.js";
+import type { CMSClient, CMSPreviewOptions, ModelMap, RelationshipMap, PreviewModels, UntypedModels } from "./types.js";
 export * from "./errors.js";
-export type { CountOptions, GetManyOptions, ContentSearch, SearchOptions, TextField } from "./types.js";
+export type { CMSQueryDefaults, RelationshipMap, CountOptions, GetManyOptions, ContentSearch, SearchOptions, TextField } from "./types.js";
 export type { CMSPreviewOptions, PreviewModels, ContentEntry, ContentPage, ContentTypeIdentity, ContentEnvironment, FindOneOptions } from "./types.js";
 /** Import only from server-owned code. Draft fields may be missing or null. */
-export declare function createCMSPreviewClient<Models extends ModelMap<Models> = UntypedModels>(options: CMSPreviewOptions): CMSClient<PreviewModels<Models>>;
+export declare function createCMSPreviewClient<Models extends ModelMap<Models> = UntypedModels, Relationships extends RelationshipMap<Models> = {}>(options: CMSPreviewOptions<Models>): CMSClient<PreviewModels<Models>, Relationships>;
 export { imageSrcSet } from "./images.js";
 export type { RemoteValue } from "./types.js";
 export type { ContentRendition } from "./images.js";
-export { richTextToHtml, richTextToPlainText } from "./rich-text.js";
+export { richTextToHtml, richTextToPlainText, externalMediaDescriptor } from "./rich-text.js";
+export type { ExternalMediaDescriptor, ExternalMediaProvider } from "./rich-text.js";

package/dist/server.js

@@ -14,4 +14,4 @@ export function createCMSPreviewClient(options) {
     return createTransport(options, options?.secretKey, "preview");
 }
 export { imageSrcSet } from "./images.js";
-export { richTextToHtml, richTextToPlainText } from "./rich-text.js";
+export { richTextToHtml, richTextToPlainText, externalMediaDescriptor } from "./rich-text.js";

package/dist/transport.d.ts

@@ -1,3 +1,6 @@
-import type { CMSBaseOptions, CMSClient, ModelMap } from "./types.js";
+import type { CMSBaseOptions, CMSClient, ModelMap, RelationshipMap } from "./types.js";
 /** Internal shared transport; public exports choose the credential and route. */
-export declare function createTransport<Models extends ModelMap<Models>>(options: CMSBaseOptions, key: unknown, mode: "content" | "preview"): CMSClient<Models>;
+export declare function createTransport<Models extends ModelMap<Models>, Relationships extends RelationshipMap<Models> = {}>(options: Omit<CMSBaseOptions, "defaults" | "collections"> & {
+    defaults?: unknown;
+    collections?: unknown;
+}, key: unknown, mode: "content" | "preview"): CMSClient<Models, Relationships>;

package/dist/transport.js

@@ -190,6 +190,55 @@ function query(options) {
     }
     return params;
 }
+function snapshotDefaults(value) {
+    if (value === undefined)
+        return {};
+    try {
+        readOptions(value, ["locale", "limit", "filters", "sort", "includeRemote", "maxPages"], "defaults");
+        const { maxPages, ...wire } = value;
+        if (maxPages !== undefined && (!Number.isInteger(maxPages) || maxPages < 1 || maxPages > 10000))
+            throw new TypeError();
+        query(wire);
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        throw new CMSConfigurationError("Invalid query defaults. Use locale, limit (1–100), filters, sort, includeRemote and maxPages (1–10000) within existing query limits.");
+    }
+}
+function mergeDefaults(global, collection, options, kind = "list") {
+    if (!record(options))
+        throw new TypeError("Query options must be an object.");
+    const result = { ...options };
+    const scalars = kind === "id" ? ["locale", "includeRemote"] :
+        kind === "statistic" ? ["locale"] : ["locale", "includeRemote", "limit", "sort"];
+    for (const key of scalars) {
+        if (result[key] === undefined) {
+            const fallback = collection[key] ?? global[key];
+            if (fallback !== undefined)
+                Object.assign(result, { [key]: fallback });
+        }
+    }
+    if (kind !== "id") {
+        const predicates = [global.filters, collection.filters, options.filters].filter(value => value !== undefined);
+        // Reject oversized/sparse request arrays before materializing a combined tree.
+        if (predicates.length > 1 && options.filters !== undefined)
+            validateFilters(options.filters);
+        if (predicates.length === 1)
+            result.filters = predicates[0];
+        else if (predicates.length > 1)
+            result.filters = predicates.flatMap(value => Array.isArray(value) ? Array.from(value) : [value]);
+    }
+    if (options.page !== undefined || options.pageSize !== undefined) {
+        // Explicit mixed modes remain invalid. Only inherited cursor size is mapped.
+        if (options.limit === undefined) {
+            const size = options.pageSize ?? collection.limit ?? global.limit;
+            if (size !== undefined)
+                result.pageSize = size;
+            delete result.limit;
+        }
+    }
+    return result;
+}
 // Network responses start as unknown even in TypeScript. Check structural
 // properties before returning them, and translate HTTP snake_case metadata into
 // SDK camelCase. This does not validate the caller-declared model field types.
@@ -299,8 +348,12 @@ export function createTransport(options, key, mode) {
         throw new CMSConfigurationError("CMS clients connect to https://api.lemonadecms.com. Remove custom URL configuration.");
     }
     const credential = mode === "content" ? "publicKey" : "secretKey";
-    if (Object.keys(options).some(option => !["projectId", credential, "fetch", "timeoutMs"].includes(option)) || "environment" in options) {
-        throw new CMSConfigurationError("Supported CMS options are projectId, the delivery key, fetch and timeoutMs. Select a content environment with its delivery key.");
+    if (Object.keys(options).some(option => !["projectId", credential, "fetch", "timeoutMs", "richTextVersion", "defaults", "collections"].includes(option)) || "environment" in options) {
+        throw new CMSConfigurationError("Supported CMS options are projectId, the delivery key, fetch, timeoutMs, richTextVersion, defaults and collections. Select a content environment with its delivery key.");
+    }
+    const richTextVersion = options.richTextVersion === undefined ? 1 : options.richTextVersion;
+    if (richTextVersion !== 1 && richTextVersion !== 2) {
+        throw new CMSConfigurationError("CMS richTextVersion must be 1 or 2.");
     }
     const timeoutMs = options.timeoutMs;
     if (timeoutMs !== undefined && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647)) {
@@ -326,6 +379,16 @@ export function createTransport(options, key, mode) {
     if (typeof fetcher !== "function") {
         throw new CMSConfigurationError("This environment needs fetch; supply a compatible fetch implementation.");
     }
+    const globalDefaults = snapshotDefaults(options.defaults);
+    const collectionDefaults = new Map();
+    if (options.collections !== undefined) {
+        if (!record(options.collections) || Object.keys(options.collections).length > 256 ||
+            Object.keys(options.collections).some(model => !identifier.test(model))) {
+            throw new CMSConfigurationError("collections must map at most 256 model identifiers to query defaults.");
+        }
+        for (const [model, defaults] of Object.entries(options.collections))
+            collectionDefaults.set(model, snapshotDefaults(defaults));
+    }
     const projectId = options.projectId;
     const endpoint = `${serviceURL}/api/v1/projects/${projectId}/${mode}`;
     return {
@@ -333,15 +396,37 @@ export function createTransport(options, key, mode) {
             if (typeof model !== "string" || !identifier.test(model)) {
                 throw new TypeError("Content type must be a lowercase model identifier.");
             }
+            const collectionDefaultsForModel = collectionDefaults.get(model) ?? {};
+            const effective = (request, kind = "list") => mergeDefaults(globalDefaults, collectionDefaultsForModel, request, kind);
             return {
+                async related(id, relation, options = {}) {
+                    if (typeof id !== "string" || !uuid.test(id))
+                        throw new TypeError("id must be an entry UUID.");
+                    if (typeof relation !== "string" || !identifier.test(relation))
+                        throw new TypeError("relation must be a lowercase relationship identifier.");
+                    options = mergeDefaults(globalDefaults, {}, options);
+                    const requestedLocale = options.locale;
+                    return await send(options, `/${id}/relations/${relation}`, body => {
+                        // Reverse lists return the source model, rather than the parent model.
+                        // New relationship endpoints always include its identity. Reuse ordinary
+                        // envelope checks and reject mixed-model pages or missing identities.
+                        if (!record(body) || !Array.isArray(body.data))
+                            throw new CMSResponseError("CMS returned an invalid related content page.");
+                        const source = body.data[0]?.content_type?.key;
+                        if (body.data.length && (typeof source !== "string" || !identifier.test(source) ||
+                            !body.data.every(entry => record(entry) && record(entry.content_type))))
+                            throw new CMSResponseError("CMS returned invalid related content-type metadata.");
+                        return decodePage(body, projectId, source ?? model, requestedLocale);
+                    });
+                },
                 async list(options = {}) {
-                    return await request(options);
+                    return await request(effective(options));
                 },
                 async search(text, options = {}) {
                     if (!record(options) || "search" in options)
                         throw new TypeError("search accepts a query string and list options with optional fields.");
                     const { fields, ...list } = options;
-                    return await request({ ...list, search: { query: text, ...(fields !== undefined ? { fields } : {}) } });
+                    return await request(effective({ ...list, search: { query: text, ...(fields !== undefined ? { fields } : {}) } }));
                 },
                 async findOne(options = {}) {
                     return await firstMatch(options);
@@ -363,6 +448,7 @@ export function createTransport(options, key, mode) {
                     if (!Array.isArray(ids) || ids.length > 100 || !Array.from(ids).every(id => typeof id === "string" && uuid.test(id))) {
                         throw new TypeError("getMany ids must contain at most 100 entry UUIDs.");
                     }
+                    options = effective(options, "id");
                     query(options);
                     options.signal?.throwIfAborted();
                     const ordered = ids.map(id => id.toLowerCase());
@@ -402,19 +488,19 @@ export function createTransport(options, key, mode) {
                         throw new TypeError("id must be an entry UUID.");
                     if (!record(options) || Object.keys(options).some(k => !["select", "locale", "signal", "includeRemote"].includes(k)))
                         throw new TypeError("get supports select, locale, includeRemote and signal.");
-                    return await request(options, id);
+                    return await request(effective(options, "id"), id);
                 },
             };
             async function firstMatch(options) {
                 readOptions(options, ["select", "locale", "filters", "sort", "search", "signal", "includeRemote"], "findOne/findOneOrThrow");
-                const page = await request({ ...options, limit: 1 });
+                const page = await request({ ...effective(options), limit: 1 });
                 if (page.meta.limit !== 1)
                     throw new CMSResponseError("CMS returned an invalid single-match page.");
                 return (page.data[0] ?? null);
             }
             async function statistic(operation, options) {
                 readOptions(options, ["locale", "filters", "search", "signal"], operation);
-                return await send(options, `/_${operation}`, body => {
+                return await send(effective(options, "statistic"), `/_${operation}`, body => {
                     if (!record(body) || !record(body.data))
                         throw new CMSResponseError("CMS returned an invalid statistic.");
                     const value = body.data[operation];
@@ -429,7 +515,8 @@ export function createTransport(options, key, mode) {
             async function* iteratePages(options = {}) {
                 if (!record(options) || "before" in options || "page" in options || "pageSize" in options)
                     throw new TypeError("pages/entries support forward traversal with after.");
-                const { maxPages = 1000, ...list } = options;
+                const { maxPages = collectionDefaultsForModel.maxPages ?? globalDefaults.maxPages ?? 1000, ...input } = options;
+                const list = effective(input);
                 if (!Number.isInteger(maxPages) || maxPages < 1 || maxPages > 10000)
                     throw new TypeError("maxPages must be an integer between 1 and 10000.");
                 query(list);
@@ -484,7 +571,8 @@ export function createTransport(options, key, mode) {
                     // propagate to the caller; this client does not silently retry a request.
                     const response = await fetcher(`${endpoint}/${model}${path}${suffix}`, {
                         method: "GET",
-                        headers: { Accept: "application/json", Authorization: `Bearer ${key}` },
+                        headers: { Accept: "application/json", Authorization: `Bearer ${key}`,
+                            ...(richTextVersion === 2 ? { "Lemonade-Accept-Content": "rich-text.v2" } : {}) },
                         credentials: "omit",
                         redirect: "error",
                         cache: "no-store",