@lemonadecms/client 0.1.1 → 0.2.1

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

@@ -7,7 +7,7 @@ import { CMSConfigurationError, CMSRequestError, CMSResponseError, CMSTimeoutErr
 const identifier = /^[a-z][a-z0-9_]{0,47}$/;
 const cursor = (value) => uuid.test(value) || (value.length <= 8192 && /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(value));
 const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const serviceURL = "https://lemonadecms.com";
+const serviceURL = "https://api.lemonadecms.com";
 const localeTag = /^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$/;
 // Narrow unknown JSON to an object before accessing properties. Arrays and null
 // are not valid objects for the API envelope even though typeof reports object.
@@ -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.
@@ -296,11 +345,15 @@ export function createTransport(options, key, mode) {
     // credentials to production. Check inherited options too: spreads and plain
     // JavaScript callers must receive the same migration error as TypeScript.
     if (["url", "baseURL", "baseUrl", "host", "endpoint"].some(option => option in options)) {
-        throw new CMSConfigurationError("CMS clients connect to https://lemonadecms.com. Remove custom URL configuration.");
+        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",

package/dist/types.d.ts

@@ -3,8 +3,15 @@ export type ModelMap<Models> = {
 };
 export type UntypedModels = Record<string, Record<string, unknown>>;
 export type FieldName<Fields> = Extract<keyof Fields, string>;
-export interface CMSBaseOptions {
-    /** Requests always use https://lemonadecms.com. Custom CMS hosts are unsupported. */
+/** Generated reverse names point to source model keys; no relationship data is fetched eagerly. */
+export type RelationshipMap<Models> = {
+    [Model in Extract<keyof Models, string>]?: Record<string, Extract<keyof Models, string>>;
+};
+export type RelationshipName<Relationships, Model extends string> = keyof Relationships extends never ? string : Model extends keyof Relationships ? Extract<keyof Relationships[Model], string> : never;
+export type RelatedModel<Models, Relationships, Model extends string, Relation extends string> = Model extends keyof Relationships ? Relation extends keyof Relationships[Model] ? Extract<Relationships[Model][Relation], Extract<keyof Models, string>> : never : string;
+export type RelatedFields<Models, Relationships, Model extends string, Relation extends string> = RelatedModel<Models, Relationships, Model, Relation> extends keyof Models ? Models[RelatedModel<Models, Relationships, Model, Relation>] : Record<string, unknown>;
+export interface CMSBaseOptions<Models extends ModelMap<Models> = {}> {
+    /** Requests always use https://api.lemonadecms.com. Custom CMS hosts are unsupported. */
     url?: never;
     projectId: string;
     /** Compatible transport for SSR, testing or polyfills; receives production URLs. */
@@ -14,11 +21,19 @@ export interface CMSBaseOptions {
      * No default deadline. Combining with a caller signal requires AbortSignal.any.
      */
     timeoutMs?: number;
+    /** Explicitly accept opt-in rich-text v2 documents. Defaults to the v1 contract. */
+    richTextVersion?: 1 | 2;
+    /** Query conveniences, never an authorization boundary. Filters combine with AND. */
+    defaults?: keyof Models extends never ? never : CMSQueryDefaults<Models[Extract<keyof Models, string>]>;
+    /** Checked model names and source fields; scalar values override global defaults. */
+    collections?: keyof Models extends never ? never : {
+        [Model in Extract<keyof Models, string>]?: CMSQueryDefaults<Models[Model]>;
+    };
 }
-export interface CMSClientOptions extends CMSBaseOptions {
+export interface CMSClientOptions<Models extends ModelMap<Models> = {}> extends CMSBaseOptions<Models> {
     publicKey: string;
 }
-export interface CMSPreviewOptions extends CMSBaseOptions {
+export interface CMSPreviewOptions<Models extends ModelMap<Models> = {}> extends CMSBaseOptions<Models> {
     secretKey: string;
 }
 type Scalar = string | number | boolean;
@@ -51,6 +66,30 @@ type ChoicesContentFilter<Fields> = {
         value: readonly ChoicesValue<Fields[Key]>[];
     };
 }[ChoicesField<Fields>];
+type ReferenceIdentity = {
+    id: string;
+    url?: never;
+};
+type ReferenceField<Fields, Many extends boolean> = {
+    [Key in FieldName<Fields>]: unknown extends Fields[Key] ? never : [NonNullable<Fields[Key]>] extends [never] ? never : NonNullable<Fields[Key]> extends (Many extends true ? readonly ReferenceIdentity[] : ReferenceIdentity) ? Key : never;
+}[FieldName<Fields>];
+type ReferenceContentFilter<Fields> = {
+    [Key in ReferenceField<Fields, false>]: {
+        field: Key;
+        op: "eq" | "ne";
+        value: string | null;
+    } | {
+        field: Key;
+        op: "in" | "not_in";
+        value: readonly string[];
+    };
+}[ReferenceField<Fields, false>] | {
+    [Key in ReferenceField<Fields, true>]: {
+        field: Key;
+        op: "contains_any" | "contains_all";
+        value: readonly string[];
+    };
+}[ReferenceField<Fields, true>];
 export type TextField<Fields> = {
     [Key in FieldName<Fields>]: unknown extends Fields[Key] ? Key : NonNullable<Fields[Key]> extends string ? Key : never;
 }[FieldName<Fields>];
@@ -61,7 +100,7 @@ type TextContentFilter<Fields> = {
         value: string;
     };
 }[TextField<Fields>];
-export type ContentFilter<Fields> = ScalarContentFilter<Fields> | ChoicesContentFilter<Fields> | TextContentFilter<Fields> | {
+export type ContentFilter<Fields> = ScalarContentFilter<Fields> | ChoicesContentFilter<Fields> | TextContentFilter<Fields> | ReferenceContentFilter<Fields> | {
     and: readonly ContentFilter<Fields>[];
 } | {
     or: readonly ContentFilter<Fields>[];
@@ -90,6 +129,14 @@ interface BaseListOptions<Key extends string, Fields> {
     /** Explicit live enrichment, independently cached from the saved publication. */
     includeRemote?: boolean;
 }
+/** Defaults never include projections, cursors, search text or cancellation signals.
+ * ID reads inherit locale/includeRemote only; statistics inherit locale/filters only.
+ * Global fields must be valid on every collection queried with those defaults.
+ */
+export type CMSQueryDefaults<Fields = Record<string, unknown>> = Pick<BaseListOptions<string, Fields>, "locale" | "limit" | "filters" | "sort" | "includeRemote"> & {
+    /** Forward traversal only. Default 1,000; maximum 10,000. */
+    maxPages?: number;
+};
 /** Follow a returned boundary in exactly one direction; or request a numbered page; modes cannot be combined. */
 export type ListOptions<Key extends string = string, Fields = Record<string, unknown>> = BaseListOptions<Key, Fields> & ({
     after?: string;
@@ -170,7 +217,9 @@ export interface ContentPage<Fields, Model extends string = string> {
         hasPreviousPage?: boolean;
     };
 }
-export interface ContentCollection<Fields extends object, Model extends string = string> {
+export interface ContentCollection<Fields extends object, Model extends string = string, Models extends ModelMap<Models> = UntypedModels, Relationships extends RelationshipMap<Models> = {}> {
+    /** Read one explicitly configured reverse collection; edit its source references in Studio. */
+    related<Relation extends RelationshipName<Relationships, Model>, const Key extends FieldName<RelatedFields<Models, Relationships, Model, Relation>> = FieldName<RelatedFields<Models, Relationships, Model, Relation>>>(id: string, relation: Relation, options?: ListOptions<Key, RelatedFields<Models, Relationships, Model, Relation>>): Promise<ContentPage<Pick<RelatedFields<Models, Relationships, Model, Relation>, Key>, RelatedModel<Models, Relationships, Model, Relation>>>;
     list<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: ListOptions<Key, Fields>): Promise<ContentPage<Pick<Fields, Key>, Model>>;
     /** One page of plain text matches; relevance order unless an explicit sort is supplied. */
     search<const Key extends FieldName<Fields> = FieldName<Fields>>(query: string, options?: SearchOptions<Key, Fields>): Promise<ContentPage<Pick<Fields, Key>, Model>>;
@@ -190,8 +239,8 @@ export interface ContentCollection<Fields extends object, Model extends string =
     entries<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: PaginationOptions<Key, Fields>): AsyncIterableIterator<ContentEntry<Pick<Fields, Key>, Model>>;
     get<const Key extends FieldName<Fields> = FieldName<Fields>>(id: string, options?: Pick<ListOptions<Key, Fields>, "select" | "locale" | "signal" | "includeRemote">): Promise<ContentEntry<Pick<Fields, Key>, Model>>;
 }
-export interface CMSClient<Models extends ModelMap<Models> = UntypedModels> {
-    content<Model extends Extract<keyof Models, string>>(model: Model): ContentCollection<Models[Model], Model>;
+export interface CMSClient<Models extends ModelMap<Models> = UntypedModels, Relationships extends RelationshipMap<Models> = {}> {
+    content<Model extends Extract<keyof Models, string>>(model: Model): ContentCollection<Models[Model], Model, Models, Relationships>;
 }
 /** A draft may omit required fields or contain nulls until it is published. */
 export type PreviewModels<Models> = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lemonadecms/client",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Framework-independent content delivery and developer tooling for Lemonade CMS",
   "license": "MIT",
   "homepage": "https://lemonadecms.com/guides/sdk",
@@ -44,6 +44,10 @@
     "./preview": {
       "types": "./dist/preview.d.ts",
       "default": "./dist/preview.js"
+    },
+    "./composer": {
+      "types": "./dist/composer.d.ts",
+      "default": "./dist/composer.js"
     }
   },
   "bin": {