@lemonadecms/client 0.0.0-stage → 0.1.1

package/bin/codegen/python.mjs

@@ -0,0 +1,125 @@
+import { definitions } from './definitions.mjs';
+const quote = JSON.stringify;
+
+export function generatePython(schema) {
+  const { records, names } = definitions(schema);
+  function type(field) {
+    switch (field.type) {
+      case 'number':
+        return 'float';
+      case 'boolean':
+        return 'bool';
+      case 'choice':
+        return `Literal[${field.options.map(quote).join(', ')}]`;
+      case 'choices':
+        return `list[Literal[${field.options.map(quote).join(', ')}]]`;
+      case 'reference':
+        return `ContentReference[${names.get(field.target)}]`;
+      case 'references':
+        return `list[ContentReference[${names.get(field.target)}]]`;
+      case 'image':
+      case 'file':
+        return 'ContentAsset';
+      case 'rich_text':
+        return 'ContentRichText';
+      case 'component':
+        return field.variants[0].name;
+      case 'components':
+      case 'blocks':
+        return `list[${field.variants.map((v) => v.name).join(' | ')}]`;
+      default:
+        return 'str';
+    }
+  }
+  const models = records
+    .map((record) => {
+      const entries = record.fields
+        .map((field) => `    ${quote(field.key)}: ${quote(`${type(field)} | None`)},`)
+        .join('\n');
+      const fields = `${record.name}Fields`;
+      if (record.component)
+        return `${fields} = TypedDict(${quote(fields)}, {\n${entries}\n}, total=False)\n\nclass ${record.name}(TypedDict):\n    id: str\n    type: Literal[${quote(record.key)}]\n    fields: ${fields}\n`;
+      return `${record.name} = TypedDict(${quote(record.name)}, {\n${entries}\n}, total=False)\n`;
+    })
+    .join('\n');
+  return `# Generated by Lemonade CMS. Do not edit. Python 3.11+; standard library only.
+# All model fields allow historical absence/null, including publication-required fields.
+# TypedDict describes JSON dictionaries; it does not validate untrusted JSON at runtime.
+from __future__ import annotations
+from typing import Generic, Literal, NotRequired, TypeVar, TypedDict
+
+TFields = TypeVar("TFields")
+
+class ContentReference(TypedDict, Generic[TFields]):
+    id: str
+    fields: NotRequired[TFields]
+    published_at: NotRequired[str | None]
+
+class ContentRendition(TypedDict):
+    key: str
+    preset: Literal["hero", "card", "social"]
+    width: int
+    height: int
+    content_type: str
+    url: str
+
+class FocalPoint(TypedDict):
+    x: float
+    y: float
+
+class AssetMetadata(TypedDict, total=False):
+    title: str
+    alt: str
+    description: str
+    focal_point: FocalPoint
+
+class ContentAsset(TypedDict):
+    id: str
+    url: str
+    content_type: str
+    byte_size: int
+    metadata: AssetMetadata
+    renditions: NotRequired[list[ContentRendition]]
+
+# Rich-text documents retain their versioned JSON structure. Node/target validation
+# belongs to the CMS; these transport types deliberately do not claim validation.
+class RichTextNode(TypedDict):
+    type: str
+    text: NotRequired[str]
+    attrs: NotRequired[dict[str, object]]
+    marks: NotRequired[list[dict[str, object]]]
+    content: NotRequired[list[RichTextNode]]
+    resource: NotRequired[ContentAsset | ContentReference[dict[str, object]] | None]
+
+class RichTextDocument(TypedDict):
+    type: Literal["doc"]
+    content: NotRequired[list[RichTextNode]]
+
+class ContentRichText(TypedDict):
+    version: Literal[1]
+    document: RichTextDocument
+
+class ContentEntry(TypedDict, Generic[TFields]):
+    id: str
+    fields: TFields
+    published_at: str | None
+    remote: NotRequired[dict[str, object] | None]
+
+class PageMeta(TypedDict):
+    next_cursor: str | None
+    limit: int
+    page: NotRequired[int]
+    page_size: NotRequired[int]
+    previous_cursor: NotRequired[str | None]
+    has_next_page: NotRequired[bool]
+    has_previous_page: NotRequired[bool]
+
+class ContentPage(TypedDict, Generic[TFields]):
+    data: list[ContentEntry[TFields]]
+    meta: PageMeta
+
+${models}
+# Stable API model keys map to the generated field dictionaries above.
+Models = TypedDict("Models", {${[...names].map(([key, name]) => `${quote(key)}: ${quote(name)}`).join(', ')}})
+`;
+}

package/bin/generate-types.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+import { writeFile, mkdir, realpath } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const identifier = /^[a-z][a-z0-9_]{0,47}$/;
+export function generateTypes(schema) {
+  if (
+    schema?.format_version !== 1 ||
+    !Array.isArray(schema.models) ||
+    schema.models.length > 256 ||
+    !schema.models.every(
+      (model) =>
+        identifier.test(model.key) &&
+        Array.isArray(model.fields) &&
+        model.fields.length <= 24 &&
+        model.fields.every((field) => identifier.test(field.key)),
+    )
+  )
+    throw new Error('Invalid schema export.');
+  const keys = new Set(schema.models.map((model) => model.key));
+  function type(field) {
+    switch (field.type) {
+      case 'component':
+      case 'components':
+      case 'blocks': {
+        if (
+          !Array.isArray(field.components) ||
+          field.components.length < 1 ||
+          field.components.length > 12 ||
+          (field.type !== 'blocks' && field.components.length !== 1)
+        )
+          throw new Error('Invalid component definitions.');
+        const variants = field.components
+          .map((component) => {
+            if (
+              !identifier.test(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),
+              )
+            )
+              throw new Error('Invalid component fields.');
+            const fields = component.fields
+              .map((child) => `${JSON.stringify(child.key)}?: ${type(child)} | null`)
+              .join('; ');
+            return `{ id: string; type: ${JSON.stringify(component.key)}; fields: { ${fields} } }`;
+          })
+          .join(' | ');
+        return field.type === 'component' ? variants : `(${variants})[]`;
+      }
+      case 'rich_text': {
+        if (
+          !Array.isArray(field.targets || []) ||
+          (field.targets || []).length > 12 ||
+          !(field.targets || []).every((target) => keys.has(target))
+        )
+          throw new Error('Invalid rich-text targets.');
+        const targets =
+          (field.targets || []).map((target) => JSON.stringify(target)).join(' | ') ||
+          'never';
+        return `ContentRichText<${targets}>`;
+      }
+      case 'number':
+        return 'number';
+      case 'boolean':
+        return 'boolean';
+      case 'choice':
+      case 'choices':
+        if (
+          !Array.isArray(field.options) ||
+          !field.options.every((v) => typeof v === 'string')
+        )
+          throw new Error('Invalid choices.');
+        {
+          const option =
+            field.options.map((v) => JSON.stringify(v)).join(' | ') || 'never';
+          return field.type === 'choices' ? `(${option})[]` : option;
+        }
+      case 'reference':
+      case 'references':
+        if (!keys.has(field.target)) throw new Error('Unknown reference target.');
+        return `ContentReference<Models[${JSON.stringify(field.target)}]>${field.type === 'references' ? '[]' : ''}`;
+      case 'image':
+      case 'file':
+        return 'ContentAsset';
+      case 'text':
+      case 'long_text':
+      case 'markdown':
+      case 'color':
+      case 'date':
+      case 'datetime':
+        return 'string';
+      default:
+        throw new Error('Unsupported field type.');
+    }
+  }
+  const models = [...schema.models]
+    .sort((a, b) => a.key.localeCompare(b.key))
+    .map(
+      (model) =>
+        `  ${JSON.stringify(model.key)}: {\n${model.fields.map((field) => `    ${JSON.stringify(field.key)}?: ${type(field)} | null;`).join('\n')}\n  };`,
+    )
+    .join('\n');
+  const seoModels = Object.fromEntries(
+    schema.models.map((model) => {
+      const mappings = {};
+      function add(field, path) {
+        if (!field.seo) return;
+        const roles =
+          field.type === 'image'
+            ? ['image', 'image_fallback']
+            : ['text', 'long_text'].includes(field.type)
+              ? ['title', 'description', 'title_fallback', 'description_fallback']
+              : [];
+        if (!roles.includes(field.seo) || Object.hasOwn(mappings, field.seo))
+          throw new Error('Invalid or duplicate SEO role.');
+        mappings[field.seo] = path;
+      }
+      for (const field of model.fields) {
+        if (field.type === 'component') {
+          for (const child of field.components[0].fields)
+            add(child, [field.key, child.key]);
+        } else if (!['components', 'blocks'].includes(field.type))
+          add(field, [field.key]);
+      }
+      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`;
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes('--help')) {
+    console.log(
+      'cms-codegen --url URL --project UUID --out FILE\nCredentials: CMS_PUBLIC_KEY or CMS_SECRET_KEY environment variable.',
+    );
+    return;
+  }
+  const options = {};
+  for (let i = 0; i < args.length; i += 2) {
+    if (!['--url', '--project', '--out'].includes(args[i]) || !args[i + 1])
+      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');
+  if (
+    !['http:', 'https:'].includes(url.protocol) ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash
+  )
+    throw new Error('Use an HTTP(S) CMS URL without credentials or query.');
+  const project = options.project || process.env.CMS_PROJECT_ID;
+  if (
+    !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
+      project || '',
+    )
+  )
+    throw new Error('A workspace UUID is required.');
+  const key = process.env.CMS_PUBLIC_KEY || process.env.CMS_SECRET_KEY;
+  if (
+    !/^(pk|sk)_[A-Za-z0-9_-]{43}$/.test(key || '') &&
+    !/^lmd_(pk|sk)_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.[A-Za-z0-9_-]{43}$/.test(
+      key || '',
+    )
+  )
+    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`,
+    {
+      headers: { Accept: 'application/json', Authorization: `Bearer ${key}` },
+      credentials: 'omit',
+      redirect: 'error',
+      cache: 'no-store',
+      signal: AbortSignal.timeout(15000),
+    },
+  );
+  if (!response.ok) throw new Error(`Schema export failed (${response.status}).`);
+  const output = generateTypes(await response.json());
+  const path = resolve(options.out);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, output);
+  console.log(`Generated ${path}`);
+}
+// npm exposes executables through .bin symlinks; compare their real target while
+// keeping generateTypes importable without running the CLI.
+const invokedPath = process.argv[1]
+  ? await realpath(resolve(process.argv[1])).catch(() => undefined)
+  : undefined;
+if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href)
+  main().catch(() => {
+    console.error(
+      'Code generation failed. Check schema, URL, workspace, credentials and output path; use --help.',
+    );
+    process.exitCode = 1;
+  });

package/bin/lemonade.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+if (Number(process.versions.node.split('.')[0]) < 22) {
+  const error = 'The Lemonade CLI requires Node.js 22 or later.';
+  if (process.argv.includes('--json'))
+    process.stdout.write(JSON.stringify({ ok: false, code: 2, error }) + '\n');
+  else process.stderr.write(error + '\n');
+  process.exitCode = 2;
+} else {
+  const { run } = await import('./cli/run.mjs');
+  process.exitCode = await run(process.argv.slice(2));
+}

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+export declare class CMSConfigurationError extends TypeError {
+    readonly name = "CMSConfigurationError";
+}
+export declare class CMSRequestError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly name = "CMSRequestError";
+    constructor(message: string, status: number, code: string);
+}
+export declare class CMSResponseError extends Error {
+    readonly name = "CMSResponseError";
+}
+/** A successful findOneOrThrow query had no matching entry. */
+export declare class CMSNotFoundError extends Error {
+    readonly model: string;
+    readonly name = "CMSNotFoundError";
+    constructor(model: string);
+}
+/** The configured request deadline expired, including response-body reading. */
+export declare class CMSTimeoutError extends Error {
+    readonly timeoutMs: number;
+    readonly name = "CMSTimeoutError";
+    constructor(timeoutMs: number);
+}

package/dist/errors.js

@@ -0,0 +1,39 @@
+// Error categories callers can distinguish with instanceof.
+// Configuration errors happen locally before a request. Request errors contain an
+// HTTP status and stable API code. Response errors mean a successful HTTP response
+// did not match the expected JSON envelope. An opt-in deadline has its own error;
+// network errors and caller cancellation reasons pass through unchanged.
+export class CMSConfigurationError extends TypeError {
+    name = "CMSConfigurationError";
+}
+export class CMSRequestError extends Error {
+    status;
+    code;
+    name = "CMSRequestError";
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+export class CMSResponseError extends Error {
+    name = "CMSResponseError";
+}
+/** A successful findOneOrThrow query had no matching entry. */
+export class CMSNotFoundError extends Error {
+    model;
+    name = "CMSNotFoundError";
+    constructor(model) {
+        super("No content entry matched the query.");
+        this.model = model;
+    }
+}
+/** The configured request deadline expired, including response-body reading. */
+export class CMSTimeoutError extends Error {
+    timeoutMs;
+    name = "CMSTimeoutError";
+    constructor(timeoutMs) {
+        super("CMS request exceeded its configured deadline.");
+        this.timeoutMs = timeoutMs;
+    }
+}

package/dist/images.d.ts

@@ -0,0 +1,11 @@
+export interface ContentRendition {
+    key: string;
+    preset: 'hero' | 'card' | 'social';
+    width: number;
+    height: number;
+    url: string;
+}
+/** Build a width-descriptor srcset from one compatible crop family. */
+export declare function imageSrcSet(asset: {
+    renditions?: readonly ContentRendition[];
+} | null | undefined, preset: ContentRendition['preset']): string | undefined;

package/dist/images.js

@@ -0,0 +1,10 @@
+/** Build a width-descriptor srcset from one compatible crop family. */
+export function imageSrcSet(asset, preset) {
+    const images = asset?.renditions?.filter((image) => image.preset === preset);
+    if (!images?.length)
+        return undefined;
+    return [...images]
+        .sort((left, right) => left.width - right.width)
+        .map((image) => `${image.url} ${image.width}w`)
+        .join(', ');
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { CMSClient, CMSClientOptions, ModelMap, 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 { 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 { imageSrcSet } from "./images.js";
+export type { ContentRendition } from "./images.js";
+export { richTextToHtml, richTextToPlainText } from "./rich-text.js";

package/dist/index.js

@@ -0,0 +1,17 @@
+// Public package entry point for browser-safe published-content reads.
+// Vue, React, plain JavaScript, and server callers pass configuration explicitly;
+// this module does not know how any framework loads its environment variables.
+// The factory selects the public-key route, while transport.ts handles HTTP.
+// There are intentionally no management/write or preview methods on this client.
+import { createTransport } from "./transport.js";
+import { CMSConfigurationError } from "./errors.js";
+export * from "./errors.js";
+/** Published content only. Framework environment variables must be passed explicitly. */
+export function createCMSClient(options) {
+    if (options && typeof options === "object" && "secretKey" in options) {
+        throw new CMSConfigurationError("Use the server entry point for secret keys.");
+    }
+    return createTransport(options, options?.publicKey, "content");
+}
+export { imageSrcSet } from "./images.js";
+export { richTextToHtml, richTextToPlainText } from "./rich-text.js";

package/dist/preview.d.ts

@@ -0,0 +1,11 @@
+/** Optional browser editing bridge. Call only inside an authenticated preview.
+ * Annotations identify top-level fields on the current entry; they confer no access.
+ * This module imports no client runtime, renderer, framework or server credentials.
+ */
+export declare function enablePreviewEditing(options: {
+    studioOrigin: string;
+    channel: string;
+    entry: string;
+    locale: string;
+    root?: HTMLElement;
+}): () => void;

package/dist/preview.js

@@ -0,0 +1,92 @@
+/** Optional browser editing bridge. Call only inside an authenticated preview.
+ * Annotations identify top-level fields on the current entry; they confer no access.
+ * This module imports no client runtime, renderer, framework or server credentials.
+ */
+export function enablePreviewEditing(options) {
+    const root = options.root ?? document.body;
+    const { studioOrigin, channel, entry, locale } = options;
+    const origin = new URL(studioOrigin);
+    if (origin.origin !== studioOrigin || !['http:', 'https:'].includes(origin.protocol) ||
+        window.parent === window || ![channel, entry, locale].every(value => typeof value === 'string' && value.length > 0 && value.length <= 64)) {
+        return () => { };
+    }
+    let enabled = false;
+    const originals = new Map();
+    const attribute = 'data-lemonade-field';
+    const send = (type, extra = {}) => window.parent.postMessage({ type, channel, ...extra }, studioOrigin);
+    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 activate = () => {
+        restore();
+        if (!enabled)
+            return;
+        // Bound enhancements; delegated activation also works after framework rerenders.
+        for (const element of Array.from(root.querySelectorAll(`[${attribute}]`)).slice(0, 500)) {
+            const field = element.getAttribute(attribute) ?? '';
+            if (!/^[a-z][a-z0-9_]{0,63}$/.test(field))
+                continue;
+            const attrs = new Map();
+            for (const name of ['tabindex', 'role', 'aria-label', 'title', 'style'])
+                attrs.set(name, element.getAttribute(name));
+            originals.set(element, attrs);
+            // Preserve native semantic roles for links/buttons. No contenteditable is added.
+            if (!element.matches('a[href],button,input,textarea,select'))
+                element.setAttribute('role', 'button');
+            element.setAttribute('tabindex', '0');
+            element.setAttribute('aria-label', `Edit ${field.replaceAll('_', ' ')} in Studio`);
+            element.setAttribute('title', 'Edit in Studio');
+            element.style.outline = '2px dashed currentColor';
+            element.style.outlineOffset = '4px';
+            element.style.cursor = 'pointer';
+        }
+    };
+    const receive = (event) => {
+        if (event.source !== window.parent || event.origin !== studioOrigin || event.data?.channel !== channel)
+            return;
+        if (event.data.type === 'lemonade:preview-connect' && typeof event.data.request === 'string' && event.data.request.length <= 64) {
+            send('lemonade:preview-editing-ready', { request: event.data.request });
+            return;
+        }
+        if (event.data.type !== 'lemonade:preview-editing' || typeof event.data.enabled !== 'boolean')
+            return;
+        enabled = event.data.enabled;
+        activate();
+    };
+    const select = (event) => {
+        if (!enabled || !(event.target instanceof Element))
+            return;
+        if (event instanceof KeyboardEvent && (event.key !== 'Enter' && event.key !== ' '))
+            return;
+        if (event instanceof MouseEvent && (event.button !== 0 || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey))
+            return;
+        const element = event.target.closest(`[${attribute}]`);
+        if (!element || !originals.has(element))
+            return;
+        const field = element.getAttribute(attribute);
+        if (!field || !/^[a-z][a-z0-9_]{0,63}$/.test(field))
+            return;
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        send('lemonade:preview-select', { entry, locale, field });
+    };
+    window.addEventListener('message', receive);
+    root.addEventListener('click', select, true);
+    root.addEventListener('keydown', select, true);
+    send('lemonade:preview-editing-ready');
+    return () => {
+        enabled = false;
+        window.removeEventListener('message', receive);
+        root.removeEventListener('click', select, true);
+        root.removeEventListener('keydown', select, true);
+        restore();
+    };
+}

package/dist/rich-text.d.ts

@@ -0,0 +1,4 @@
+/** Escaped HTML for rich-text v1, including safe expanded images/entry captions. */
+export declare function richTextToHtml(value: unknown): string;
+/** Authored text with block/hard-break newlines; excludes embeds and link URLs. */
+export declare function richTextToPlainText(value: unknown): string;