@lemonadecms/client 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -2,7 +2,56 @@
 
 ## Unreleased
 
-## 0.1.1 — prepared release
+## 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
+  hostname mode intentionally returns 404 for old main-domain API URLs; upgrade
+  installed clients and configured targets before using that deployment.
+  Explicit CLI flags and environment precedence remain unchanged.
+  Studio/preview message origins stay separate; no redirect, fallback retry or
+  runtime dependency. Package publication and server deployment are separate.
+
+- Add the optional zero-dependency `@lemonadecms/client/composer` browser bridge:
+  versioned website capabilities, stable section/slot locators, selection and
+  arrangement commands, cancellable serial rendering and latest-only commits.
+  Requires an explicitly opted-in private CMS destination and website renderer.
+- Generate three-level nested component unions and localized text leaves in
+  TypeScript, Python and C#, retaining legacy flat schemas and CLI behavior.
+
+## 0.1.1 — published package
 
 - Add a native terminal environment picker for online `types generate` using
   validated configured targets and their credential variables. Explicit settings,

package/README.md

@@ -30,7 +30,7 @@ runtime library or framework dependency is required.
 
 ## Configure and read content
 
-The SDK connects to `https://lemonadecms.com` automatically. Configure your
+Version 0.2.0 connects to `https://api.lemonadecms.com` automatically. Strict hostname routing returns 404 for API URLs on `https://lemonadecms.com`. Upgrade earlier clients to 0.2.0 and change explicit CLI/configured-target URLs to `https://api.lemonadecms.com`. Explicit CLI settings still take precedence; no redirect or fallback is attempted. Configure your
 workspace and delivery key; there is no URL or local CMS option. Your website
 can run locally while reading content from Lemonade production. Installing the
 package does not create an account, workspace or delivery key.
@@ -63,7 +63,7 @@ if (first) {
 ```
 
 Entry values are under `fields`; metadata includes `id` and `publishedAt`.
-Unreleased source builds also expose `contentType` (ID/key/name), `projectId`,
+The client also exposes `contentType` (ID/key/name), `projectId`,
 `environment` (ID/key) and resolved `locale`. Field projections retain metadata.
 For older CMS responses, the SDK derives only the request's model key/workspace
 and explicit locale; unavailable metadata stays absent. Metadata properties are
@@ -104,7 +104,7 @@ console.log(entry?.fields.title ?? 'No matching content');
 
 ## Counts, existence and bulk reads
 
-These unreleased methods require the updated SDK and CMS backend. They are
+These methods require the current SDK and CMS backend. They are
 available in both published and server preview clients:
 
 ```js
@@ -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.
 
@@ -240,13 +257,13 @@ placeholders with your workspace UUID; the target labels distinguish environment
   "version": 1,
   "targets": {
     "production": {
-      "url": "https://lemonadecms.com",
+      "url": "https://api.lemonadecms.com",
       "workspace": "YOUR_WORKSPACE_UUID",
       "environment": "production",
       "credentialEnv": "CMS_PUBLIC_KEY"
     },
     "dev": {
-      "url": "https://lemonadecms.com",
+      "url": "https://api.lemonadecms.com",
       "workspace": "YOUR_WORKSPACE_UUID",
       "environment": "dev",
       "credentialEnv": "CMS_DEV_PUBLIC_KEY"
@@ -275,7 +292,7 @@ Without configured targets, existing defaults remain unchanged. For automation:
 npx lemonade types generate --target dev --check
 ```
 
-This requires the updated source package; published 0.1.0 lacks the picker.
+Version 0.2.0 includes the picker; historical 0.1.0 does not.
 It uses native Node APIs and retains zero runtime, peer or optional dependencies.
 
 ## Private previews
@@ -303,3 +320,33 @@ fetch client.
 
 This SDK package is licensed under the [MIT License](LICENSE). Its license does
 not grant a license to the entire CMS repository or the separate native clients.
+
+
+## Visual Composer
+
+The optional Visual Composer adds approved nested sections, inspector editing and
+private live updates. A developer connects the website registry and explicitly
+enables unsaved projection on its trusted preview destination. Save draft and
+Publish remain separate. Component text can be translated by stable block ID;
+each language keeps its live tree until explicitly published. Existing form and
+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/config.mjs

@@ -229,7 +229,7 @@ export async function connection(
     fail(2, 'Selected target is not configured.');
   const target = name ? targets[name] : {};
   const selected = {
-    url: opts.url || target.url || env.LEMONADE_URL || 'https://lemonadecms.com',
+    url: opts.url || target.url || env.LEMONADE_URL || 'https://api.lemonadecms.com',
     workspace:
       opts.workspace ||
       target.workspace ||

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}$/;
@@ -73,7 +76,7 @@ function bounded(value) {
   let nodes = 0;
   while (stack.length) {
     const [item, depth] = stack.pop();
-    if (++nodes > 150000 || depth > 16) invalid();
+    if (++nodes > 150000 || depth > 24) invalid();
     if (
       typeof item === 'string' &&
       /(?:pk|sk)_[A-Za-z0-9_-]{43}|lmd_(?:pk|sk|mgmt)_[0-9a-f-]{36}\.[A-Za-z0-9_-]{43}/.test(
@@ -85,7 +88,7 @@ function bounded(value) {
       for (const child of Object.values(item)) stack.push([child, depth + 1]);
   }
 }
-function fields(values, keys, component = false) {
+function fields(values, keys, component = false, ancestors = []) {
   if (
     !Array.isArray(values) ||
     values.length > 24 ||
@@ -107,7 +110,7 @@ function fields(values, keys, component = false) {
         : ['reference', 'references'].includes(field.type)
           ? ['target']
           : field.type === 'rich_text'
-            ? ['images', 'targets']
+            ? ['images', 'targets', 'document_version', 'features']
             : composed.includes(field.type)
               ? ['components']
               : [];
@@ -135,6 +138,7 @@ function fields(values, keys, component = false) {
         'help_text',
         'validation',
         ...(!component ? ['group'] : []),
+        ...(!component && field.type === 'blocks' ? ['composer'] : []),
         ...extra,
         ...seo,
         ...(field.type === 'text' && !component ? ['slug'] : []),
@@ -155,8 +159,7 @@ function fields(values, keys, component = false) {
           !['text', 'long_text', 'markdown', 'rich_text'].includes(field.type)))
     )
       invalid();
-    if (component && (composed.includes(field.type) || field.localized === true))
-      invalid();
+    if (Object.hasOwn(field, 'composer') && typeof field.composer !== 'boolean') invalid();
     if (Object.hasOwn(field, 'default')) {
       const value = field.default;
       if (field.type === 'choices' && value === null) invalid();
@@ -207,12 +210,12 @@ function fields(values, keys, component = false) {
       for (const definition of field.components) {
         if (
           !own(definition, ['key', 'name', 'fields']) ||
-          !apiKey(definition.key) ||
+          !apiKey(definition.key) || ancestors.includes(definition.key) || ancestors.length >= 3 ||
           !string(definition.name, 80) ||
           !definition.fields?.length
         )
           invalid();
-        fields(definition.fields, keys, true);
+        fields(definition.fields, keys, true, [...ancestors, definition.key]);
       }
     }
   }
@@ -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,14 +20,19 @@ 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));
-  function type(field) {
+  let fieldNodes = 0;
+  function type(field, ancestors = []) {
+    if (++fieldNodes > 150000) throw new Error('Schema exceeds generation budget.');
     switch (field.type) {
       case 'component':
       case 'components':
       case 'blocks': {
         if (
-          !Array.isArray(field.components) ||
+          ancestors.length >= 3 || !Array.isArray(field.components) ||
           field.components.length < 1 ||
           field.components.length > 12 ||
           (field.type !== 'blocks' && field.components.length !== 1)
@@ -33,19 +41,18 @@ export function generateTypes(schema) {
         const variants = field.components
           .map((component) => {
             if (
-              !identifier.test(component.key) ||
+              !identifier.test(component.key) || ancestors.includes(component.key) ||
               !Array.isArray(component.fields) ||
               component.fields.length < 1 ||
               component.fields.length > 24 ||
               component.fields.some(
                 (child) =>
-                  !identifier.test(child.key) ||
-                  ['component', 'components', 'blocks'].includes(child.type),
+                  !identifier.test(child.key),
               )
             )
               throw new Error('Invalid component fields.');
             const fields = component.fields
-              .map((child) => `${JSON.stringify(child.key)}?: ${type(child)} | null`)
+              .map((child) => `${JSON.stringify(child.key)}?: ${type(child, [...ancestors, component.key])} | null`)
               .join('; ');
             return `{ id: string; type: ${JSON.stringify(component.key)}; fields: { ${fields} } }`;
           })
@@ -62,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';
@@ -105,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 = {};
@@ -130,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);
@@ -146,7 +161,7 @@ async function main() {
       throw new Error('Use --help for codegen options.');
     options[args[i].slice(2)] = args[i + 1];
   }
-  const url = new URL(options.url || process.env.CMS_URL || 'https://lemonadecms.com');
+  const url = new URL(options.url || process.env.CMS_URL || 'https://api.lemonadecms.com');
   if (
     !['http:', 'https:'].includes(url.protocol) ||
     url.username ||
@@ -172,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`;
+}