@lemonadecms/client 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## Unreleased
 
+## 0.2.1
+
+- Filter top-level Reference fields by linked entry UUID with eq/ne/in/not_in,
+  and References fields with contains_any/contains_all, including typed global
+  and per-collection defaults. Requires the matching CMS deployment.
+
+- Add optional typed global and collection query defaults, immutable configuration,
+  AND-composed filters and bounded default traversal. ID reads inherit locale/remote
+  options only; related reads never inherit the parent collection's defaults.
+- Keep fixed API URLs, explicit credentials, existing method contracts and zero
+  runtime dependencies.
+
+- Negotiate `unique-identifiers.v1` schema metadata for declared shared-text
+  identifiers. Capture, drift and compatible migration additions retain the
+  declaration; generated delivery fields stay strings and legacy exports retain
+  their shape. Requires an updated backend.
+- Add explicit `richTextVersion: 2` delivery negotiation and opt-in rich-text v2
+  quotations, escaped code blocks and accessible rectangular tables. V1 fields
+  retain their existing types and values; malformed/unknown v2 nodes and future
+  versions raise `CMSResponseError` instead of silently dropping content.
+- Add pure `externalMediaDescriptor` and safe static rich-text cards for supported
+  public YouTube/Vimeo videos, Spotify episodes and SoundCloud tracks. Rendering
+  does not fetch metadata or start a player; playback consent belongs to the site.
+- Request `relationships.v1,rich-text.v2` schema extensions together, validate and
+  round-trip field capabilities, and generate opt-in TypeScript/Python/C# types.
+  These capabilities require the matching backend deployment.
+- Add on-demand `related(parentId, relationship, options)` reads for explicitly
+  configured reverse collections, including server previews. Optional generated
+  `Relationships` types check relation names and source-field selections without
+  changing existing `createCMSClient<Models>` calls or entry fields.
+- Negotiate the versioned relationship schema extension for type generation and
+  drift checks, retaining legacy schemas. Requires the updated backend. No runtime dependencies.
+
 ## 0.2.0
 
 - Use `https://api.lemonadecms.com` for new SDK/CLI defaults. The server's strict

package/README.md

@@ -195,18 +195,35 @@ const html = richTextToHtml(richEntry?.fields.rich_body);
 const plainText = richTextToPlainText(richEntry?.fields.rich_body);
 ```
 
-Both accept nullable/unknown version-1 rich-text JSON and work in browsers or
-servers without a framework or DOM. HTML escapes text/attributes and renders only
+Both accept nullable/unknown rich-text JSON and work in browsers or servers
+without a framework or DOM. HTML escapes text/attributes and renders only
 supported nodes/marks, safe links and matching expanded image/entry-caption
 resources. Unavailable embeds are omitted; entry routes are never invented.
-Plain text retains authored text with block/list/hard-break newlines, omitting
-embeds and link URLs. Plain text is not escaped HTML: use text interpolation.
+Plain text retains authored text with block/list/hard-break newlines. Plain text
+is not escaped HTML: use text interpolation.
+
+The source SDK also supports opt-in v2 quotations, escaped code blocks, accessible
+rectangular tables and external-media cards. Configure the field's
+`document_version: 2` and enabled features, then set `richTextVersion: 2` on the
+published or server preview client. This explicitly sends
+`Lemonade-Accept-Content: rich-text.v2`; default reads remain v1. The updated type
+generator requests `relationships.v1,rich-text.v2,unique-identifiers.v1` schema extensions.
+These additions require the updated backend, SDK and website renderer; published
+0.2.0 does not contain them.
+
+External-media HTML stays static: no iframe, autoplay or provider request is
+created by these helpers. `externalMediaDescriptor(node)` returns validated,
+fixed provider URLs without I/O so a website can add an explicit click-to-load
+player. The Astro source reference demonstrates disclosure, constrained frames,
+timeout recovery and a transcript that remains available.
 
 Traversal is bounded to 500 nodes, depth 8, 200 children per node, 20 embeds,
 20,000 UTF-8 bytes per text and 64 KiB of rendered source strings. Unsupported
-versions, invalid roots/containers or exhausted budgets return empty strings;
-unsupported parts are omitted. No raw HTML, resource-field recursion, I/O or
-automatic Markdown conversion is performed. HTML URL/alt bounds and exact
+legacy roots/containers or exhausted legacy budgets return empty strings;
+unsupported legacy parts are omitted. Unknown/future versions and malformed or
+unsupported v2 documents throw `CMSResponseError`; handle the error explicitly.
+No raw HTML, resource-field recursion, I/O or automatic Markdown conversion is
+performed. HTML URL/alt bounds and exact
 preview-image conventions are documented in the SDK guide. The helpers are also
 exported from the server entry; preview authorization remains your responsibility.
 
@@ -316,3 +333,20 @@ saved-draft previews remain supported. The browser helper is the dependency-free
 `@lemonadecms/client/composer` export.
 
 See [setup, editor workflow, Astro reference and protocol](https://github.com/ilara-booqself/lemonadecms/blob/main/docs/visual-composer.md).
+
+
+## Source additions awaiting a release
+
+The source checkout adds opt-in rich-text v2 (described above) and on-demand
+reverse collections through
+`cms.content('author').related(authorId, 'articles', {limit: 10})`. Updated
+`lemonade types generate` negotiates the relationship extension and generates a
+separate `Relationships` map for `createCMSClient<Models, Relationships>`.
+Ordinary entries and `fields` retain their shape. This requires the updated
+backend and a separately published package beyond 0.2.0; deployment and npm
+publication are separate gates. The source SDK retains zero runtime dependencies.
+
+Management migrations configuring a reverse list need both source and target
+model keys and actions in the management credential, independently of the
+actor's grants. Existing targets require `model.update`; targets created in the
+same migration require `model.create`. See the [reviewed migration guide](https://github.com/ilara-booqself/lemonadecms/blob/main/docs/schema-migrations.md).

package/bin/cli/create-migration.mjs

@@ -3,6 +3,8 @@ import { validateSchema, canonical } from './schema.mjs';
 import { parseJSON, readText, writeOutput } from './io.mjs';
 import { record } from './config.mjs';
 import { fail } from './errors.mjs';
+import { modelsWithRelationships } from '../relationships.mjs';
+import { modelsWithUniqueIdentifiers } from '../unique-identifiers.mjs';
 
 const equal = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
 const rejected = () =>
@@ -58,8 +60,13 @@ export async function createMigration(opts, cwd) {
   const paths = [opts.baseline, opts.file, opts.status].map((name) =>
     resolve(cwd, name),
   );
-  const baseline = validateSchema(parseJSON(await readText(paths[0])));
-  const desired = validateSchema(parseJSON(await readText(paths[1])));
+  const baselineSchema = validateSchema(parseJSON(await readText(paths[0])));
+  const desiredSchema = validateSchema(parseJSON(await readText(paths[1])));
+  // Materialize opted-in definitions only in management operations. Published
+  // schema fields retain their legacy shape; unsupported edits still reject.
+  const managementModels = schema => modelsWithRelationships({...schema, models: modelsWithUniqueIdentifiers(schema)});
+  const baseline = {...baselineSchema, models: managementModels(baselineSchema)};
+  const desired = {...desiredSchema, models: managementModels(desiredSchema)};
   const status = parseJSON(await readText(paths[2]));
   const environment = baseline.environment?.id || baseline.project_id;
   const modelSummary = (schema) =>
@@ -94,7 +101,7 @@ export async function createMigration(opts, cwd) {
     );
   // Require an exact portable editing baseline. Never turn unsupported edits into
   // omissions, removals, or a blind desired-state replacement.
-  const withoutModels = ({ models, ...rest }) => rest;
+  const withoutModels = ({ models, extensions, ...rest }) => rest;
   if (!equal(withoutModels(baseline), withoutModels(desired))) rejected();
   const operations = [];
   const prior = new Map(baseline.models.map((model) => [model.key, model]));

package/bin/cli/network.mjs

@@ -33,7 +33,7 @@ export async function fetchSchema(target, fetcher = fetch) {
   const schema = validateSchema(
     await requestJSON(
       target,
-      `/api/v1/projects/${target.workspace}/schema`,
+      `/api/v1/projects/${target.workspace}/schema?extensions=${schemaExtensions}`,
       {},
       fetcher,
     ),
@@ -132,3 +132,4 @@ export async function requestJSON(
     } catch {}
   }
 }
+import { schemaExtensions } from '../rich-text-schema.mjs';

package/bin/cli/schema.mjs

@@ -1,4 +1,7 @@
 import { generateTypes } from '../generate-types.mjs';
+import { relationshipDefinitions } from '../relationships.mjs';
+import { uniqueIdentifierDefinitions } from '../unique-identifiers.mjs';
+import { validateRichTextExtension } from '../rich-text-schema.mjs';
 import { record, uuid } from './config.mjs';
 import { fail } from './errors.mjs';
 const identifier = /^[a-z][a-z0-9_]{0,47}$/;
@@ -107,7 +110,7 @@ function fields(values, keys, component = false, ancestors = []) {
         : ['reference', 'references'].includes(field.type)
           ? ['target']
           : field.type === 'rich_text'
-            ? ['images', 'targets']
+            ? ['images', 'targets', 'document_version', 'features']
             : composed.includes(field.type)
               ? ['components']
               : [];
@@ -259,6 +262,7 @@ export function validateSchema(schema) {
       'default_locale',
       'models',
       'environment',
+      'extensions',
     ]) ||
     schema.format_version !== 1 ||
     !uuid.test(schema.project_id || '') ||
@@ -318,6 +322,7 @@ export function validateSchema(schema) {
         invalid();
     }
   }
+  try { relationshipDefinitions(schema); validateRichTextExtension(schema); uniqueIdentifierDefinitions(schema); } catch { invalid(); }
   // One type generator remains authoritative for delivery types, references and SEO roles.
   try {
     generateTypes(schema);
@@ -341,6 +346,12 @@ export function serialize(schema) {
     JSON.stringify(
       canonical({
         ...schema,
+        ...(schema.extensions ? {extensions: {...schema.extensions, ...(schema.extensions.relationships ? {relationships: {...schema.extensions.relationships,
+          definitions: [...schema.extensions.relationships.definitions].sort((a, b) =>
+            `${a.model}.${a.key}`.localeCompare(`${b.model}.${b.key}`))}} : {}),
+          ...(schema.extensions.unique_identifiers ? {unique_identifiers: {...schema.extensions.unique_identifiers,
+            definitions: [...schema.extensions.unique_identifiers.definitions].sort((a, b) =>
+              `${a.model}.${a.field}`.localeCompare(`${b.model}.${b.field}`))}} : {})}} : {}),
         models: [...schema.models].sort((a, b) =>
           a.key < b.key ? -1 : a.key > b.key ? 1 : 0,
         ),
@@ -393,5 +404,11 @@ export function compareSchemas(baseline, current) {
       ]),
     );
   compare(modelMap(baseline), modelMap(current), 'models');
+  const relationshipMap = schema => Object.fromEntries(relationshipDefinitions(schema).map(definition =>
+    [`${definition.model}.${definition.key}`, definition]));
+  compare(relationshipMap(baseline), relationshipMap(current), 'relationships');
+  const identifierMap = schema => Object.fromEntries(uniqueIdentifierDefinitions(schema).map(definition =>
+    [`${definition.model}.${definition.field}`, definition]));
+  compare(identifierMap(baseline), identifierMap(current), 'unique_identifiers');
   return changes;
 }

package/bin/codegen/csharp.mjs

@@ -27,7 +27,7 @@ export function generateCSharp(schema) {
       case 'file':
         return 'ContentAsset';
       case 'rich_text':
-        return 'ContentRichText';
+        return field.document_version === 2 ? 'ContentRichTextV2' : 'ContentRichText';
       case 'component':
         return field.variants[0].name;
       case 'components':
@@ -147,6 +147,11 @@ ${property('id', 'string', 'Id', ' = "";')}${property('url', 'string', 'Url', '
 public sealed record ContentRichText
 {
 ${property('version', 'int', 'Version')}${property('document', 'JsonElement', 'Document')}}
+${schema.extensions?.rich_text ? `// This opt-in field can retain historical v1 or authored v2 documents.
+public sealed record ContentRichTextV2
+{
+${property('version', 'int', 'Version')}${property('document', 'JsonElement', 'Document')}}
+` : ''}
 public sealed record ContentEntry<TFields>
 {
 ${property('id', 'string', 'Id', ' = "";')}${property('fields', 'TFields?', 'Fields')}${property('published_at', 'string?', 'PublishedAt')}${property('remote', 'JsonElement?', 'Remote')}}

package/bin/codegen/python.mjs

@@ -21,7 +21,7 @@ export function generatePython(schema) {
       case 'file':
         return 'ContentAsset';
       case 'rich_text':
-        return 'ContentRichText';
+        return field.document_version === 2 ? 'ContentRichTextV2' : 'ContentRichText';
       case 'component':
         return field.variants[0].name;
       case 'components':
@@ -98,6 +98,11 @@ class RichTextDocument(TypedDict):
 class ContentRichText(TypedDict):
     version: Literal[1]
     document: RichTextDocument
+${schema.extensions?.rich_text ? `
+class ContentRichTextV2(TypedDict):
+    version: Literal[1, 2]
+    document: RichTextDocument
+` : ''}
 
 class ContentEntry(TypedDict, Generic[TFields]):
     id: str

package/bin/generate-types.mjs

@@ -2,6 +2,9 @@
 import { writeFile, mkdir, realpath } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { relationshipDefinitions } from './relationships.mjs';
+import { uniqueIdentifierDefinitions } from './unique-identifiers.mjs';
+import { richTextSettings, richTextV2Types, validateRichTextExtension, schemaExtensions } from './rich-text-schema.mjs';
 const identifier = /^[a-z][a-z0-9_]{0,47}$/;
 export function generateTypes(schema) {
   if (
@@ -17,6 +20,9 @@ export function generateTypes(schema) {
     )
   )
     throw new Error('Invalid schema export.');
+  const relationships = relationshipDefinitions(schema);
+  uniqueIdentifierDefinitions(schema);
+  validateRichTextExtension(schema);
   const keys = new Set(schema.models.map((model) => model.key));
   let fieldNodes = 0;
   function type(field, ancestors = []) {
@@ -63,7 +69,10 @@ export function generateTypes(schema) {
         const targets =
           (field.targets || []).map((target) => JSON.stringify(target)).join(' | ') ||
           'never';
-        return `ContentRichText<${targets}>`;
+        const settings = richTextSettings(field);
+        return settings.version === 2
+          ? `ContentRichTextV2<${targets}, ${settings.features.map(JSON.stringify).join(' | ') || 'never'}>`
+          : `ContentRichText<${targets}>`;
       }
       case 'number':
         return 'number';
@@ -106,6 +115,11 @@ export function generateTypes(schema) {
         `  ${JSON.stringify(model.key)}: {\n${model.fields.map((field) => `    ${JSON.stringify(field.key)}?: ${type(field)} | null;`).join('\n')}\n  };`,
     )
     .join('\n');
+  const relationshipMap = [...schema.models].sort((a, b) => a.key.localeCompare(b.key)).map(model => {
+    const fields = relationships.filter(relation => relation.model === model.key).sort((a, b) => a.key.localeCompare(b.key))
+      .map(relation => `    ${JSON.stringify(relation.key)}: ${JSON.stringify(relation.source_model)};`).join('\n');
+    return `  ${JSON.stringify(model.key)}: {${fields ? `\n${fields}\n  ` : ''}};`;
+  }).join('\n');
   const seoModels = Object.fromEntries(
     schema.models.map((model) => {
       const mappings = {};
@@ -131,7 +145,7 @@ export function generateTypes(schema) {
       return [model.key, mappings];
     }),
   );
-  return `// Generated by @lemonadecms/client codegen. Do not edit.\n// Every field allows historical absence/null; previews may be incomplete.\nexport interface ContentReference<Fields> { id: string; fields?: Fields; published_at?: string | null; content_type?: { id: string; key: string; name: string }; project_id?: string; environment?: { id: string; key: string }; locale?: string }\nexport interface ContentRendition { key: string; preset: "hero" | "card" | "social"; width: number; height: number; content_type: string; url: string }\nexport interface ContentAsset { id: string; url: string; content_type: string; byte_size: number; metadata: { title?: string; alt?: string; description?: string; focal_point?: { x: number; y: number } }; renditions?: ContentRendition[] }\nexport type RichTextMark = { type: 'bold' | 'italic' | 'underline' | 'strike' | 'code' } | { type: 'link'; attrs: { href: string } };\nexport type RichTextInline = { type: 'text'; text: string; marks?: RichTextMark[] } | { type: 'hardBreak' };\nexport type RichTextEntry<Target extends keyof Models> = { [K in Target]: { type: 'entry'; attrs: { id: string; target: K }; resource?: ContentReference<Models[K]> | null } }[Target];\nexport type RichTextBlock<Target extends keyof Models = keyof Models> = { type: 'paragraph'; content?: RichTextInline[] } | { type: 'heading'; attrs: { level: 2 | 3 | 4 }; content?: RichTextInline[] } | { type: 'bulletList' | 'orderedList'; attrs?: { start: 1 }; content: { type: 'listItem'; content: RichTextBlock<Target>[] }[] } | { type: 'image'; attrs: { id: string; alt: string }; resource?: ContentAsset | null } | RichTextEntry<Target>;\nexport interface ContentRichText<Target extends keyof Models = keyof Models> { version: 1; document: { type: 'doc'; content?: RichTextBlock<Target>[] } }\nexport interface Models {\n${models}\n}\n\n// Presentation roles, refreshed by codegen after schema changes.\nexport const seoModels = ${JSON.stringify(seoModels, null, 2)} as const;\n`;
+  return `// Generated by @lemonadecms/client codegen. Do not edit.\n// Every field allows historical absence/null; previews may be incomplete.\nexport interface ContentReference<Fields> { id: string; fields?: Fields; published_at?: string | null; content_type?: { id: string; key: string; name: string }; project_id?: string; environment?: { id: string; key: string }; locale?: string }\nexport interface ContentRendition { key: string; preset: "hero" | "card" | "social"; width: number; height: number; content_type: string; url: string }\nexport interface ContentAsset { id: string; url: string; content_type: string; byte_size: number; metadata: { title?: string; alt?: string; description?: string; focal_point?: { x: number; y: number } }; renditions?: ContentRendition[] }\nexport type RichTextMark = { type: 'bold' | 'italic' | 'underline' | 'strike' | 'code' } | { type: 'link'; attrs: { href: string } };\nexport type RichTextInline = { type: 'text'; text: string; marks?: RichTextMark[] } | { type: 'hardBreak' };\nexport type RichTextEntry<Target extends keyof Models> = { [K in Target]: { type: 'entry'; attrs: { id: string; target: K }; resource?: ContentReference<Models[K]> | null } }[Target];\nexport type RichTextBlock<Target extends keyof Models = keyof Models> = { type: 'paragraph'; content?: RichTextInline[] } | { type: 'heading'; attrs: { level: 2 | 3 | 4 }; content?: RichTextInline[] } | { type: 'bulletList' | 'orderedList'; attrs?: { start: 1 }; content: { type: 'listItem'; content: RichTextBlock<Target>[] }[] } | { type: 'image'; attrs: { id: string; alt: string }; resource?: ContentAsset | null } | RichTextEntry<Target>;\nexport interface ContentRichText<Target extends keyof Models = keyof Models> { version: 1; document: { type: 'doc'; content?: RichTextBlock<Target>[] } }\n${richTextV2Types(schema)}export interface Models {\n${models}\n}\n\n// Opt-in read-only reverse collections: parent model -> relation -> source model.\nexport interface Relationships {\n${relationshipMap}\n}\n\n// Presentation roles, refreshed by codegen after schema changes.\nexport const seoModels = ${JSON.stringify(seoModels, null, 2)} as const;\n`;
 }
 async function main() {
   const args = process.argv.slice(2);
@@ -173,7 +187,7 @@ async function main() {
     throw new Error('Set CMS_PUBLIC_KEY or CMS_SECRET_KEY.');
   if (!options.out) throw new Error('--out is required.');
   const response = await fetch(
-    `${url.href.replace(/\/+$/, '')}/api/v1/projects/${project}/schema`,
+    `${url.href.replace(/\/+$/, '')}/api/v1/projects/${project}/schema?extensions=${schemaExtensions}`,
     {
       headers: { Accept: 'application/json', Authorization: `Bearer ${key}` },
       credentials: 'omit',

package/bin/relationships.mjs

@@ -0,0 +1,87 @@
+// Versioned, explicitly requested delivery metadata. It never adds stored fields
+// or forward-reference edges and is validated before generating or persisting it.
+import {schemaExtensionKeys} from './schema-extensions.mjs';
+const identifier = /^[a-z][a-z0-9_]{0,47}$/;
+const record = (value) =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+const exact = (value, keys) =>
+  record(value) &&
+  Object.keys(value).length === keys.length &&
+  keys.every((key) => Object.hasOwn(value, key));
+const invalid = () => {
+  throw new Error('Invalid relationship extension.');
+};
+function validLabel(value) {
+  return (
+    typeof value === 'string' &&
+    !/^\p{White_Space}|\p{White_Space}$/u.test(value) &&
+    Buffer.byteLength(value) >= 1 &&
+    Buffer.byteLength(value) <= 80 &&
+    !/[\u0000\r\n\ud800-\udfff]/u.test(value)
+  );
+}
+export function relationshipDefinitions(schema) {
+  if (!Object.hasOwn(schema, 'extensions')) return [];
+  if (!record(schema.extensions) || Object.keys(schema.extensions).length === 0 ||
+      Object.keys(schema.extensions).some(key => !schemaExtensionKeys.includes(key))) invalid();
+  if (!Object.hasOwn(schema.extensions, 'relationships')) return [];
+  const extension = schema.extensions.relationships;
+  if (
+    !exact(extension, ['version', 'definitions']) ||
+    extension.version !== 1 ||
+    !Array.isArray(extension.definitions) ||
+    extension.definitions.length > 6144
+  )
+    invalid();
+  const models = new Map(schema.models.map((model) => [model.key, model]));
+  const seen = new Set();
+  const sourceFields = new Set();
+  for (const definition of extension.definitions) {
+    if (
+      !exact(definition, ['model', 'key', 'label', 'source_model', 'source_field']) ||
+      !['model', 'key', 'source_model', 'source_field'].every(
+        (key) =>
+          typeof definition[key] === 'string' && identifier.test(definition[key]),
+      ) ||
+      !validLabel(definition.label)
+    )
+      invalid();
+    const parent = models.get(definition.model);
+    const source = models.get(definition.source_model);
+    const field = source?.fields.find((field) => field.key === definition.source_field);
+    const identity = `${definition.model}:${definition.key}`;
+    const origin = `${definition.source_model}:${definition.source_field}`;
+    if (
+      !parent ||
+      !field ||
+      !['reference', 'references'].includes(field.type) ||
+      field.target !== definition.model ||
+      parent.fields.some((field) => field.key === definition.key) ||
+      seen.has(identity) ||
+      sourceFields.has(origin)
+    )
+      invalid();
+    seen.add(identity);
+    sourceFields.add(origin);
+  }
+  return extension.definitions;
+}
+
+export function modelsWithRelationships(schema) {
+  const definitions = relationshipDefinitions(schema);
+  const bySource = new Map(
+    definitions.map((definition) => [
+      `${definition.source_model}:${definition.source_field}`,
+      definition,
+    ]),
+  );
+  return schema.models.map((model) => ({
+    ...model,
+    fields: model.fields.map((field) => {
+      const reverse = bySource.get(`${model.key}:${field.key}`);
+      return reverse
+        ? { ...field, reverse: { key: reverse.key, label: reverse.label } }
+        : field;
+    }),
+  }));
+}

package/bin/rich-text-schema.mjs

@@ -0,0 +1,54 @@
+// Explicit schema capability metadata, separate from ordinary delivery fields.
+import {schemaExtensionKeys} from './schema-extensions.mjs';
+export {schemaExtensions} from './schema-extensions.mjs';
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const features = ['blockquote', 'code_block', 'table', 'external_media'];
+const invalid = () => { throw new Error('Invalid rich-text schema extension.'); };
+export function richTextSettings(field) {
+  if ((Object.hasOwn(field, 'document_version') || Object.hasOwn(field, 'features')) && field.type !== 'rich_text') invalid();
+  if (!Object.hasOwn(field, 'document_version') || field.document_version === 1) {
+    if (Object.hasOwn(field, 'features')) invalid();
+    return {version: 1, features: []};
+  }
+  const enabled = Object.hasOwn(field, 'features') ? field.features : [];
+  if (field.type !== 'rich_text' || field.document_version !== 2 || !Array.isArray(enabled) ||
+      enabled.length > features.length || new Set(enabled).size !== enabled.length ||
+      !enabled.every(feature => features.includes(feature))) invalid();
+  return {version: 2, features: enabled};
+}
+
+export function validateRichTextExtension(schema) {
+  if (Object.hasOwn(schema, 'extensions')) {
+    if (!record(schema.extensions) || Object.keys(schema.extensions).length === 0 ||
+        Object.keys(schema.extensions).some(key => !schemaExtensionKeys.includes(key))) invalid();
+    if (Object.hasOwn(schema.extensions, 'rich_text')) {
+      const extension = schema.extensions.rich_text;
+      if (!record(extension) || Object.keys(extension).length !== 1 || extension.version !== 2) invalid();
+    }
+  }
+  function fields(values) {
+    for (const field of values) {
+      const settings = richTextSettings(field);
+      if (settings.version === 2 && schema.extensions?.rich_text?.version !== 2) invalid();
+      for (const definition of field.components || []) fields(definition.fields);
+    }
+  }
+  for (const model of schema.models) fields(model.fields);
+}
+
+export function richTextV2Types(schema) {
+  if (!schema.extensions?.rich_text) return '';
+  return `\n// V2 is explicitly enabled per field; historical v1 values remain valid.
+export type RichTextFeature = 'blockquote' | 'code_block' | 'table' | 'external_media';
+export type RichTextParagraph = { type: 'paragraph'; content?: RichTextInline[] };
+export type RichTextCodeBlock = { type: 'codeBlock'; attrs: { language: string }; content?: { type: 'text'; text: string }[] };
+export type RichTextTable = { type: 'table'; attrs: { caption: string; header: boolean }; content: { type: 'tableRow'; content: { type: 'tableCell' | 'tableHeader'; content: [RichTextParagraph] }[] }[] };
+export type RichTextExternalMedia = { type: 'externalMedia'; attrs: { provider: 'youtube' | 'vimeo' | 'spotify' | 'soundcloud'; url: string; title: string; caption: string; transcript: string; poster?: string }; resource?: ContentAsset | null };
+export type RichTextAdvanced<Features extends RichTextFeature> =
+  ('blockquote' extends Features ? { type: 'blockquote'; content: RichTextParagraph[] } : never) |
+  ('code_block' extends Features ? RichTextCodeBlock : never) |
+  ('table' extends Features ? RichTextTable : never) |
+  ('external_media' extends Features ? RichTextExternalMedia : never);
+export type RichTextBlockV2<Target extends keyof Models, Features extends RichTextFeature> = RichTextBlock<Target> | RichTextAdvanced<Features>;
+export type ContentRichTextV2<Target extends keyof Models = keyof Models, Features extends RichTextFeature = RichTextFeature> = ContentRichText<Target> | { version: 2; document: { type: 'doc'; content?: RichTextBlockV2<Target, Features>[] } };\n`;
+}

package/bin/schema-extensions.mjs

@@ -0,0 +1,6 @@
+// Negotiation affects schema tooling only; ordinary delivery/SDK reads retain
+// their existing response contract and zero runtime dependency boundary.
+export const schemaExtensionKeys = Object.freeze([
+  'relationships', 'rich_text', 'unique_identifiers',
+]);
+export const schemaExtensions = 'relationships.v1,rich-text.v2,unique-identifiers.v1';

package/bin/unique-identifiers.mjs

@@ -0,0 +1,50 @@
+import {schemaExtensionKeys} from './schema-extensions.mjs';
+
+const identifier = /^[a-z][a-z0-9_]{0,47}$/;
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const exact = (value, keys) => record(value) && Object.keys(value).length === keys.length &&
+  keys.every(key => Object.hasOwn(value, key));
+const invalid = () => { throw new Error('Invalid unique-identifier schema extension.'); };
+
+export function uniqueIdentifierDefinitions(schema) {
+  // Inline declarations belong to management definitions, never portable
+  // delivery exports. Requiring the extension prevents silently lost metadata.
+  let nodes = 0;
+  function fields(values, depth = 0) {
+    if (!Array.isArray(values) || values.length > 24 || depth > 3) invalid();
+    for (const field of values) {
+      if (++nodes > 150000 || !record(field) || Object.hasOwn(field, 'unique')) invalid();
+      const components = field.components || [];
+      if (!Array.isArray(components) || components.length > 12) invalid();
+      for (const component of components) {
+        if (!record(component)) invalid();
+        fields(component.fields, depth + 1);
+      }
+    }
+  }
+  for (const model of schema.models) fields(model.fields);
+  if (!Object.hasOwn(schema, 'extensions')) return [];
+  if (!record(schema.extensions) || Object.keys(schema.extensions).length === 0 ||
+      Object.keys(schema.extensions).some(key => !schemaExtensionKeys.includes(key))) invalid();
+  if (!Object.hasOwn(schema.extensions, 'unique_identifiers')) return [];
+  const extension = schema.extensions.unique_identifiers;
+  if (!exact(extension, ['version', 'definitions']) || extension.version !== 1 ||
+      !Array.isArray(extension.definitions) || extension.definitions.length > 6144) invalid();
+  const models = new Map(schema.models.map(model => [model.key, model]));
+  const seen = new Set();
+  for (const definition of extension.definitions) {
+    if (!exact(definition, ['model', 'field']) ||
+        !['model', 'field'].every(key => typeof definition[key] === 'string' && identifier.test(definition[key]))) invalid();
+    const field = models.get(definition.model)?.fields.find(field => field.key === definition.field);
+    const identity = `${definition.model}.${definition.field}`;
+    if (!field || field.type !== 'text' || field.localized === true || seen.has(identity)) invalid();
+    seen.add(identity);
+  }
+  return extension.definitions;
+}
+
+export function modelsWithUniqueIdentifiers(schema) {
+  const definitions = new Set(uniqueIdentifierDefinitions(schema).map(value => `${value.model}.${value.field}`));
+  return schema.models.map(model => ({...model, fields: model.fields.map(field =>
+    definitions.has(`${model.key}.${field.key}`) ? {...field, unique: true} : field)}));
+}

package/dist/index.d.ts

@@ -1,10 +1,11 @@
-import type { CMSClient, CMSClientOptions, ModelMap, UntypedModels } from "./types.js";
+import type { CMSClient, CMSClientOptions, ModelMap, RelationshipMap, UntypedModels } from "./types.js";
 export * from "./errors.js";
 export type { RemoteValue } from "./types.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 { CMSClient, CMSClientOptions, ContentCollection, ContentEntry, ContentPage, ContentTypeIdentity, ContentEnvironment, ListOptions, FindOneOptions, PaginationOptions, ContentFilter, ContentSort } from "./types.js";
 /** Published content only. Framework environment variables must be passed explicitly. */
-export declare function createCMSClient<Models extends ModelMap<Models> = UntypedModels>(options: CMSClientOptions): CMSClient<Models>;
+export declare function createCMSClient<Models extends ModelMap<Models> = UntypedModels, Relationships extends RelationshipMap<Models> = {}>(options: CMSClientOptions<Models>): CMSClient<Models, Relationships>;
 export { imageSrcSet } from "./images.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/index.js

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

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;