@lemonadecms/client 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -2,7 +2,23 @@
 
 ## Unreleased
 
-## 0.1.1 — prepared release
+## 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
@@ -240,13 +240,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 +275,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 +303,16 @@ 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).

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/schema.mjs

@@ -73,7 +73,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 +85,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 ||
@@ -135,6 +135,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 +156,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 +207,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]);
       }
     }
   }

package/bin/generate-types.mjs

@@ -18,13 +18,15 @@ export function generateTypes(schema) {
   )
     throw new Error('Invalid schema export.');
   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 +35,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} } }`;
           })
@@ -146,7 +147,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 ||

package/dist/composer.d.ts

@@ -0,0 +1,27 @@
+/** Optional browser-only Composer bridge. Website code owns rendering.
+ * Enable only on an authenticated preview. No credentials or framework imports.
+ */
+export interface ComposerUpdate {
+    channel: string;
+    entry: string;
+    locale: string;
+    root: string;
+    fields: Record<string, unknown>;
+    model_version: number;
+    entry_version: number;
+    renderer_revision: string;
+}
+export interface VisualComposerOptions {
+    studioOrigin: string;
+    channel: string;
+    entry: string;
+    locale: string;
+    roots: readonly string[];
+    components: readonly string[];
+    rendererRevision: string;
+    root?: HTMLElement;
+    /** Return a synchronous commit function; the bridge calls it only for the
+     * latest successful render. Honor signal and keep DOM changes in commit. */
+    render: (update: ComposerUpdate, signal: AbortSignal) => Promise<() => void>;
+}
+export declare function enableVisualComposer(options: VisualComposerOptions): () => void;

package/dist/composer.js

@@ -0,0 +1,240 @@
+export function enableVisualComposer(options) {
+    const keyPattern = /^[a-z][a-z0-9_]{0,47}$/;
+    const idPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    const { studioOrigin, channel, entry, locale, roots, components, rendererRevision } = options;
+    let origin;
+    try {
+        origin = new URL(studioOrigin);
+    }
+    catch {
+        return () => { };
+    }
+    if (origin.origin !== studioOrigin || !['http:', 'https:'].includes(origin.protocol) ||
+        window.parent === window || !idPattern.test(channel) || !idPattern.test(entry) ||
+        !/^[a-zA-Z0-9-]{2,20}$/.test(locale) || !/^[a-f0-9]{64}$/.test(rendererRevision) ||
+        roots.length < 1 || roots.length > 24 || components.length < 1 || components.length > 128 ||
+        ![...roots, ...components].every(key => keyPattern.test(key)) || typeof options.render !== 'function') {
+        return () => { };
+    }
+    const root = options.root ?? document.body;
+    let active = true;
+    let enabled = false;
+    let selectedRoot = '';
+    let generation = '';
+    let latest = 0;
+    let busy = false;
+    let pending;
+    let controller;
+    const originals = new Map();
+    const send = (type, extra = {}) => window.parent.postMessage({ type, version: 1, channel, entry, locale, root: selectedRoot, ...extra }, studioOrigin);
+    const announce = (request) => send('lemonade:composer-ready', {
+        roots: [...roots], components: [...components], renderer_revision: rendererRevision,
+        ...(request ? { request } : {}),
+    });
+    const restore = () => {
+        for (const [element, attrs] of originals)
+            for (const [name, value] of attrs) {
+                if (value === null)
+                    element.removeAttribute(name);
+                else
+                    element.setAttribute(name, value);
+            }
+        originals.clear();
+    };
+    const enhance = () => {
+        restore();
+        if (!enabled)
+            return;
+        for (const element of Array.from(root.querySelectorAll('[data-lemonade-block]')).slice(0, 100)) {
+            const id = element.dataset.lemonadeBlock ?? '';
+            if (!idPattern.test(id))
+                continue;
+            const attrs = new Map();
+            for (const name of ['tabindex', 'role', 'aria-label', 'draggable', 'style'])
+                attrs.set(name, element.getAttribute(name));
+            originals.set(element, attrs);
+            if (!element.matches('a[href],button,input,textarea,select'))
+                element.setAttribute('role', 'button');
+            element.tabIndex = 0;
+            element.setAttribute('aria-label', `Edit ${element.dataset.lemonadeName ?? 'section'} in Studio`);
+            element.draggable = true;
+            element.style.outline = '1px dashed currentColor';
+            element.style.outlineOffset = '3px';
+        }
+    };
+    const run = async () => {
+        if (!active || !enabled || busy || !pending)
+            return;
+        const work = pending;
+        pending = undefined;
+        busy = true;
+        const abort = new AbortController();
+        controller = abort;
+        let timeout;
+        try {
+            const commit = await Promise.race([
+                options.render(work.update, abort.signal),
+                new Promise((_, reject) => { timeout = setTimeout(() => { abort.abort(); reject(new Error('Composer render timed out')); }, 10000); }),
+            ]);
+            if (active && enabled && !abort.signal.aborted && work.sequence === latest && work.generation === generation) {
+                if (typeof commit !== 'function')
+                    throw new Error('Composer renderer must return a commit function');
+                commit();
+                enhance();
+                send('lemonade:composer-rendered', { sequence: work.sequence, generation });
+            }
+        }
+        catch {
+            if (active && enabled && work.sequence === latest && work.generation === generation) {
+                send('lemonade:composer-error', { sequence: work.sequence, generation });
+            }
+        }
+        finally {
+            clearTimeout(timeout);
+            if (controller === abort)
+                controller = undefined;
+            busy = false;
+            void run();
+        }
+    };
+    const disable = () => {
+        enabled = false;
+        pending = undefined;
+        controller?.abort();
+        restore();
+    };
+    const receive = (event) => {
+        if (!active || event.source !== window.parent || event.origin !== studioOrigin || event.data?.channel !== channel)
+            return;
+        const data = event.data;
+        if (data.type === 'lemonade:preview-connect') {
+            if (typeof data.request === 'string' && data.request.length <= 64)
+                announce(data.request);
+            return;
+        }
+        if (data.version !== 1 || data.entry !== entry || data.locale !== locale)
+            return;
+        if (data.type === 'lemonade:composer-disable') {
+            disable();
+            return;
+        }
+        if (data.type === 'lemonade:composer-enable') {
+            if (!roots.includes(data.root) || typeof data.generation !== 'string' || data.generation.length > 64)
+                return;
+            if (generation !== data.generation) {
+                controller?.abort();
+                pending = undefined;
+                latest = 0;
+            }
+            enabled = true;
+            generation = data.generation;
+            selectedRoot = data.root;
+            enhance();
+            return;
+        }
+        if (!enabled || data.generation !== generation || data.root !== selectedRoot)
+            return;
+        if (data.type === 'lemonade:composer-highlight' && idPattern.test(data.id)) {
+            for (const element of originals.keys()) {
+                element.style.outlineWidth = element.dataset.lemonadeBlock === data.id ? '3px' : '1px';
+            }
+            return;
+        }
+        if (data.type === 'lemonade:composer-drop') {
+            if (!Number.isFinite(data.x) || !Number.isFinite(data.y) || data.x < 0 || data.y < 0 ||
+                data.x >= window.innerWidth || data.y >= window.innerHeight)
+                return;
+            const element = document.elementFromPoint(data.x, data.y);
+            if (element)
+                emitDrop(element, data.payload);
+            return;
+        }
+        if (data.type !== 'lemonade:composer-update' || !Number.isSafeInteger(data.sequence) || data.sequence <= latest ||
+            !data.fields || typeof data.fields !== 'object' || Array.isArray(data.fields) ||
+            data.renderer_revision !== rendererRevision || !Number.isSafeInteger(data.model_version) || !Number.isSafeInteger(data.entry_version))
+            return;
+        try {
+            if (new TextEncoder().encode(JSON.stringify(data.fields)).length > 65536)
+                return;
+        }
+        catch {
+            return;
+        }
+        latest = data.sequence;
+        pending = { update: { channel, entry, locale, root: selectedRoot, fields: data.fields,
+                model_version: data.model_version, entry_version: data.entry_version, renderer_revision: rendererRevision }, sequence: latest, generation };
+        controller?.abort();
+        void run();
+    };
+    const select = (event) => {
+        if (!enabled || !(event.target instanceof Element))
+            return;
+        if (event instanceof KeyboardEvent && !['Enter', ' '].includes(event.key))
+            return;
+        if (event instanceof MouseEvent && (event.button !== 0 || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey))
+            return;
+        const element = event.target.closest('[data-lemonade-block]');
+        if (!element || !originals.has(element))
+            return;
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        send('lemonade:composer-select', { id: element.dataset.lemonadeBlock, root: selectedRoot, generation });
+    };
+    const dragstart = (event) => {
+        if (!enabled || !(event.target instanceof Element))
+            return;
+        const element = event.target.closest('[data-lemonade-block]');
+        if (!element || !originals.has(element))
+            return;
+        event.dataTransfer?.setData('application/x-lemonade-composer', JSON.stringify({ id: element.dataset.lemonadeBlock, channel, root: selectedRoot }));
+    };
+    const dragover = (event) => {
+        if (enabled && event.target instanceof Element && event.target.closest('[data-lemonade-slot]'))
+            event.preventDefault();
+    };
+    const emitDrop = (element, data) => {
+        const slot = element.closest('[data-lemonade-slot]');
+        const path = slot?.dataset.lemonadeSlot;
+        if (!slot || !path || path.length > 512 || !root.contains(slot) || !data ||
+            !(idPattern.test(data.id ?? '') || keyPattern.test(data.component ?? '')))
+            return;
+        if (path !== selectedRoot && !path.startsWith(selectedRoot + '.'))
+            return;
+        const block = element.closest('[data-lemonade-block]');
+        send('lemonade:composer-action', { action: data.id ? 'move' : 'add', id: data.id, component: data.component,
+            target: path, before: block?.dataset.lemonadeBlock, root: selectedRoot, generation });
+    };
+    const drop = (event) => {
+        if (!enabled || !(event.target instanceof Element))
+            return;
+        try {
+            const raw = event.dataTransfer?.getData('application/x-lemonade-composer') ?? '';
+            if (raw.length > 1024)
+                return;
+            const data = JSON.parse(raw);
+            if (data.channel !== channel || data.root !== selectedRoot)
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            emitDrop(event.target, data);
+        }
+        catch { /* Foreign drag payloads are not composition commands. */ }
+    };
+    window.addEventListener('message', receive);
+    root.addEventListener('click', select, true);
+    root.addEventListener('keydown', select, true);
+    root.addEventListener('dragstart', dragstart);
+    root.addEventListener('dragover', dragover);
+    root.addEventListener('drop', drop);
+    announce();
+    return () => {
+        active = false;
+        disable();
+        window.removeEventListener('message', receive);
+        root.removeEventListener('click', select, true);
+        root.removeEventListener('keydown', select, true);
+        root.removeEventListener('dragstart', dragstart);
+        root.removeEventListener('dragover', dragover);
+        root.removeEventListener('drop', drop);
+    };
+}

package/dist/transport.js

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

package/dist/types.d.ts

@@ -4,7 +4,7 @@ export type ModelMap<Models> = {
 export type UntypedModels = Record<string, Record<string, unknown>>;
 export type FieldName<Fields> = Extract<keyof Fields, string>;
 export interface CMSBaseOptions {
-    /** Requests always use https://lemonadecms.com. Custom CMS hosts are unsupported. */
+    /** Requests always use https://api.lemonadecms.com. Custom CMS hosts are unsupported. */
     url?: never;
     projectId: string;
     /** Compatible transport for SSR, testing or polyfills; receives production URLs. */

package/package.json

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