@lemonadecms/client 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## Unreleased
 
+## 0.2.2
+
+- Correct the npm-specific README with global/collection defaults, direct
+  reference-ID filtering, authorization limits and accurate 0.2.1 feature
+  availability. No SDK runtime, CLI or dependency changes from 0.2.1.
+
+## 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

@@ -30,7 +30,7 @@ runtime library or framework dependency is required.
 
 ## Configure and read content
 
-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
+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.2 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.
@@ -85,6 +85,64 @@ environment override. Ask your Owner for a credential belonging to the intended
 environment. The server rechecks current access, expiry and revocation on every
 request.
 
+## Global and collection defaults (0.2.1+)
+
+Use `defaults` for shared locale, limit, filters, sort, includeRemote and maxPages.
+Use `collections` for typed per-model settings. Request values override collection
+values, then global values. Global, collection and request filters combine with
+AND; `filters: []` does not remove configured predicates. Configuration is copied
+at client construction. No schema fetch, retry or runtime dependency is added.
+
+The example assumes generated `article` and `product` models, each with a top-level
+Reference field named `tenant`. Filter directly by the linked entry UUID; a
+separate `tenant_id` text field is unnecessary. Regenerate your model types after
+adding the relation. Relation predicates require the matching CMS backend.
+
+```ts
+import { createCMSClient } from '@lemonadecms/client';
+import type { Models } from './cms-models';
+
+type TenantContent = Pick<Models, 'article' | 'product'>;
+const tenantId = 'YOUR_TENANT_ENTRY_UUID';
+const cms = createCMSClient<TenantContent>({
+  projectId: 'YOUR_WORKSPACE_UUID',
+  publicKey: 'YOUR_PUBLIC_DELIVERY_KEY',
+  defaults: {
+    locale: 'en',
+    limit: 25,
+    filters: [{ field: 'tenant', op: 'eq', value: tenantId }],
+  },
+});
+const articles = await cms.content('article').list({ limit: 10 });
+```
+
+`tenantId` must come from your application's intended tenant entry UUID. Global
+fields must exist on every queried model; use collection defaults when only some
+models have the relation. Use another client for the tenant directory itself.
+
+| Field | Operators | Values |
+| --- | --- | --- |
+| Reference | `eq`, `ne` | Linked entry UUID or `null` |
+| Reference | `in`, `not_in` | 1–100 UUIDs |
+| References | `contains_any`, `contains_all` | 1–100 unique UUIDs |
+
+IDs are compared case-insensitively in the requested published or saved-draft
+snapshot. These filters do not fetch or traverse target fields. Both source and
+target models must be accessible in the requested language. Dotted `tenant.id`,
+nested relations, reverse-list predicates and relation sorting are unsupported.
+Existing ten-leaf, depth-four, 31-node and 4 KiB filter limits still apply.
+
+Defaults are query conveniences, **not tenant authorization**. `get()`/`getMany()`
+inherit locale/includeRemote only and do not inherit filters. Reference expansion
+is not constrained by defaults. A shared public key can read every record it
+permits. Use separate workspace credentials for hard isolation, or trusted server
+authorization for every entry and referenced resource. Never rely on a caller's
+unverified tenant ID as authorization.
+
+Statistics inherit locale/filters; `findOne()` keeps limit 1. Related reads inherit
+global defaults only, never the parent collection's settings. Traversal snapshots
+its effective query and honors maxPages (default 1,000; maximum 10,000).
+
 ## Find one entry
 
 In the updated source build, `findOne()` returns the first matching complete
@@ -195,18 +253,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.
+
+SDK 0.2.1 and later support 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 and website renderer, together with
+SDK 0.2.1 or later. Earlier packages do not contain these advanced formats.
+
+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 +391,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).
+
+
+## Reverse relationships (0.2.1+)
+
+SDK 0.2.1 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 SDK 0.2.1 or later. Installing npm does not deploy the backend.
+The 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";