@lemonadecms/client 0.1.0 → 0.1.1

package/bin/cli/run.mjs

@@ -2,7 +2,13 @@ import { resolve } from 'node:path';
 import { createRequire } from 'node:module';
 const { version } = createRequire(import.meta.url)('../../package.json');
 import { access } from 'node:fs/promises';
-import { parseArgs, connection } from './config.mjs';
+import {
+  parseArgs,
+  connection,
+  typeGenerationEnv,
+  readConfiguration,
+} from './config.mjs';
+import { canPickTarget, pickTarget } from './picker.mjs';
 import { CLIError, fail } from './errors.mjs';
 import { parseJSON, readText, writeOutput, MAX_SCHEMA_BYTES } from './io.mjs';
 import {
@@ -23,7 +29,7 @@ lemonade schema pull --out schema.json [connection options]
 lemonade schema export --out schema.json [connection options]
 lemonade schema validate --file schema.json
 lemonade schema diff --file schema.json [connection options]
-lemonade types generate [--file schema.json | connection options] --out FILE [--language typescript|csharp|python] [--check]
+lemonade types generate [--file schema.json | connection options] [--out FILE] [--language typescript|csharp|python] [--check]
 
 lemonade schema migrate status [--before MIGRATION_ID] [connection options]
 lemonade schema migrate create --baseline current.json --file desired.json --status status.json --id YYYYMMDDHHMMSS_description --out migration.json
@@ -36,9 +42,17 @@ Migration commands require an environment UUID and a separate management credent
 Connection: --config FILE --target NAME, or --url URL --workspace UUID --environment KEY_OR_UUID
 Credential: --credential-env ENV_NAME (default LEMONADE_TOKEN). Never pass a token value.
 Targets live in lemonade.config.json. URL/workspace/environment also accept LEMONADE_* environment variables.
+Types generate: loads cwd/.env (process values win); workspace falls back to CMS_PROJECT_ID,
+environment to CMS_ENVIRONMENT or production, credential to CMS_PUBLIC_KEY when LEMONADE_TOKEN is unset.
+Default output: src/types/cms-models.ts (csharp: cms-models.cs; python: cms_models.py).
+Explicit options, named targets and existing LEMONADE_* settings take precedence. --out is a file path.
+Offline generation and other commands do not load .env. Use the selected environment's credential.
+Interactive types generate offers configured targets (production first) when no connection selection is explicit.
+Use arrows/Enter to choose; Escape/Ctrl+C/EOF cancels without network or output-file writes.
+CI, --json, --check, piped input/output, --file and explicit connection/environment settings never prompt.
 All commands: --json. Informational: --help, --version.
-Exit codes: 0 success, 2 usage/config, 3 drift, 4 connection/auth/context, 5 invalid schema/input, 6 output failure.
-Only schema migrate apply writes compatible schema additions or reviewed missing-draft backfills. No content publication, prompts, automatic retries or credential persistence. Node.js 22+ required.
+Exit codes: 0 success, 2 usage/config, 3 drift, 4 connection/auth/context, 5 invalid schema/input, 6 output failure, 130 selection cancelled.
+Only schema migrate apply writes compatible schema additions or reviewed missing-draft backfills. No content publication, automatic retries or credential persistence. Node.js 22+ required.
 `;
 export async function run(
   args,
@@ -48,6 +62,11 @@ export async function run(
     fetcher = fetch,
     stdout = (text) => process.stdout.write(text),
     stderr = (text) => process.stderr.write(text),
+    terminal = {
+      input: process.stdin,
+      output: process.stderr,
+      stdoutIsTTY: process.stdout.isTTY,
+    },
   } = {},
 ) {
   let opts = {},
@@ -94,7 +113,37 @@ export async function run(
     const inputPath = opts.file && resolve(cwd, opts.file);
     const readSchema = async () => validateSchema(parseJSON(await readText(inputPath)));
     const remote = async () => {
-      const target = await connection(opts, env, cwd);
+      const generation = command === 'types generate';
+      const selectedEnv = generation ? await typeGenerationEnv(env, cwd) : env;
+      const defaults = generation
+        ? {
+            workspace: selectedEnv.CMS_PROJECT_ID,
+            environment: selectedEnv.CMS_ENVIRONMENT || 'production',
+            credentialEnv: Object.hasOwn(selectedEnv, 'LEMONADE_TOKEN')
+              ? 'LEMONADE_TOKEN'
+              : 'CMS_PUBLIC_KEY',
+          }
+        : {};
+      const configuration = await readConfiguration(opts, cwd);
+      let selected = opts;
+      if (
+        generation &&
+        canPickTarget(opts, selectedEnv, terminal) &&
+        Object.keys(configuration.targets).length
+      ) {
+        selected = {
+          ...opts,
+          target: await pickTarget(configuration.targets, terminal),
+        };
+      }
+      const target = await connection(
+        selected,
+        selectedEnv,
+        cwd,
+        false,
+        defaults,
+        configuration,
+      );
       key = target.key;
       return fetchSchema(target, fetcher);
     };
@@ -167,6 +216,7 @@ export async function run(
         await writeOutput(path, output, [
           inputPath,
           resolve(cwd, opts.config || 'lemonade.config.json'),
+          resolve(cwd, '.env'),
         ]);
         result.written = true;
         human = `Types generated successfully (${language}).`;

package/bin/generate-types.mjs

@@ -130,7 +130,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 }\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>[] } }\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);

package/dist/errors.d.ts

@@ -10,6 +10,12 @@ export declare class CMSRequestError extends Error {
 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;

package/dist/errors.js

@@ -19,6 +19,15 @@ export class CMSRequestError extends Error {
 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;

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 import type { CMSClient, CMSClientOptions, ModelMap, UntypedModels } from "./types.js";
 export * from "./errors.js";
 export type { RemoteValue } from "./types.js";
-export type { CMSClient, CMSClientOptions, ContentCollection, ContentEntry, ContentPage, ListOptions, PaginationOptions, ContentFilter, ContentSort } 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

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

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;

package/dist/rich-text.js

@@ -0,0 +1,228 @@
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+const model = /^[a-z][a-z0-9_]{0,47}$/;
+const encoder = new TextEncoder();
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function escape(value) {
+    return value.replace(/[&<>"']/g, (character) => {
+        switch (character) {
+            case '&':
+                return '&amp;';
+            case '<':
+                return '&lt;';
+            case '>':
+                return '&gt;';
+            case '"':
+                return '&quot;';
+            default:
+                return '&#39;';
+        }
+    });
+}
+function safeUrl(value, image) {
+    if (typeof value !== 'string' ||
+        value.length > (image ? 4096 : 2048) ||
+        /[\s\\\u0000-\u0020\u007f-\u009f]/u.test(value))
+        return null;
+    // Only the consuming-site preview proxy's fixed same-origin route is relative.
+    if (image &&
+        /^\/lemonade\/preview\/assets\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(value))
+        return value;
+    if (!/^https?:\/\//i.test(value) && (image || !/^mailto:/i.test(value)))
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.username || url.password)
+            return null;
+        if ((url.protocol === 'https:' || url.protocol === 'http:') && url.hostname)
+            return value;
+        return !image && url.protocol === 'mailto:' && url.pathname ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function matchingResource(node) {
+    const attrs = node.attrs, resource = node.resource;
+    if (!record(attrs) ||
+        !record(resource) ||
+        typeof attrs.id !== 'string' ||
+        attrs.id.length !== 36 ||
+        !uuid.test(attrs.id) ||
+        typeof resource.id !== 'string' ||
+        resource.id.length !== 36 ||
+        attrs.id.toLowerCase() !== resource.id.toLowerCase())
+        return null;
+    return resource;
+}
+function convert(value, format) {
+    if (!record(value) ||
+        value.version !== 1 ||
+        !record(value.document) ||
+        value.document.type !== 'doc')
+        return '';
+    // The CMS bounds the authored document. Apply independent bounds to unknown
+    // consumer input and expanded strings as well; exhaustion discards all output.
+    let remaining = 500, embeds = 20, bytes = 65_536, exhausted = false;
+    function string(value, maximum = 20_000) {
+        if (typeof value !== 'string')
+            return '';
+        if (value.length > maximum) {
+            exhausted = true;
+            return '';
+        }
+        const size = encoder.encode(value).byteLength;
+        bytes -= size;
+        if (size > maximum || bytes < 0) {
+            exhausted = true;
+            return '';
+        }
+        return value;
+    }
+    function visit(value, context, depth) {
+        if (exhausted)
+            return '';
+        if (depth > 8 || --remaining < 0) {
+            exhausted = true;
+            return '';
+        }
+        if (!record(value))
+            return '';
+        const children = (next) => {
+            if (value.content === undefined)
+                return '';
+            if (!Array.isArray(value.content) || value.content.length > 200) {
+                exhausted = true;
+                return '';
+            }
+            return value.content.map((child) => visit(child, next, depth + 1)).join('');
+        };
+        if (context === 'inline') {
+            if (value.type === 'hardBreak')
+                return format === 'html' ? '<br>' : '\n';
+            if (value.type !== 'text')
+                return '';
+            const source = string(value.text);
+            if (format === 'text')
+                return source;
+            let text = escape(source);
+            const marks = value.marks;
+            if (marks !== undefined && (!Array.isArray(marks) || marks.length > 6)) {
+                exhausted = true;
+                return '';
+            }
+            const seen = new Set();
+            for (const mark of Array.isArray(marks) ? marks : []) {
+                if (!record(mark) ||
+                    typeof mark.type !== 'string' ||
+                    mark.type.length > 9 ||
+                    seen.has(mark.type))
+                    continue;
+                seen.add(mark.type);
+                switch (mark.type) {
+                    case 'bold':
+                        text = `<strong>${text}</strong>`;
+                        break;
+                    case 'italic':
+                        text = `<em>${text}</em>`;
+                        break;
+                    case 'underline':
+                        text = `<u>${text}</u>`;
+                        break;
+                    case 'strike':
+                        text = `<s>${text}</s>`;
+                        break;
+                    case 'code':
+                        text = `<code>${text}</code>`;
+                        break;
+                    case 'link': {
+                        const href = safeUrl(record(mark.attrs) ? mark.attrs.href : null, false);
+                        if (href)
+                            text = `<a href="${escape(string(href, 2048))}" rel="noopener noreferrer">${text}</a>`;
+                    }
+                }
+            }
+            return text;
+        }
+        if (context === 'root')
+            return value.type === 'doc' ? children('block') : '';
+        if (context === 'list') {
+            if (value.type !== 'listItem')
+                return '';
+            const content = children('item');
+            return format === 'html' ? `<li>${content}</li>` : content.trimEnd() + '\n';
+        }
+        if (value.type === 'paragraph') {
+            const content = children('inline');
+            return format === 'html'
+                ? `<p>${content}</p>`
+                : content + (context === 'item' ? '\n' : '\n\n');
+        }
+        if (value.type === 'bulletList' || value.type === 'orderedList') {
+            const content = children('list');
+            const tag = value.type === 'bulletList' ? 'ul' : 'ol';
+            return format === 'html'
+                ? `<${tag}>${content}</${tag}>`
+                : content + (context === 'item' ? '' : '\n');
+        }
+        if (context !== 'block')
+            return '';
+        if (value.type === 'heading') {
+            if (!record(value.attrs) ||
+                typeof value.attrs.level !== 'number' ||
+                ![2, 3, 4].includes(value.attrs.level))
+                return '';
+            const content = children('inline');
+            return format === 'html'
+                ? `<h${value.attrs.level}>${content}</h${value.attrs.level}>`
+                : content + '\n\n';
+        }
+        if (value.type !== 'image' && value.type !== 'entry')
+            return '';
+        if (--embeds < 0) {
+            exhausted = true;
+            return '';
+        }
+        if (format === 'text')
+            return '';
+        const resource = matchingResource(value);
+        if (!resource || !record(value.attrs))
+            return '';
+        if (value.type === 'image') {
+            if (typeof resource.content_type !== 'string' ||
+                !['image/jpeg', 'image/png', 'image/webp', 'image/gif'].includes(resource.content_type))
+                return '';
+            const src = safeUrl(resource.url, true);
+            if (!src)
+                return '';
+            const metadata = record(resource.metadata) ? resource.metadata : {};
+            const alt = typeof value.attrs.alt === 'string' ? value.attrs.alt : metadata.alt;
+            return `<figure><img src="${escape(string(src, 4096))}" alt="${escape(string(alt, 2000))}" loading="lazy" decoding="async"></figure>`;
+        }
+        if (typeof value.attrs.target !== 'string' ||
+            value.attrs.target.length > 48 ||
+            model.exec(value.attrs.target)?.[0] !== value.attrs.target ||
+            (resource.content_type !== undefined &&
+                (!record(resource.content_type) ||
+                    resource.content_type.key !== value.attrs.target)) ||
+            !record(resource.fields))
+            return '';
+        const caption = typeof resource.fields.title === 'string'
+            ? resource.fields.title
+            : resource.fields.name;
+        return typeof caption === 'string'
+            ? `<aside class="rich-text-reference"><p>${escape(string(caption))}</p></aside>`
+            : '';
+    }
+    const output = visit(value.document, 'root', 0);
+    return exhausted ? '' : format === 'text' ? output.trim() : output;
+}
+/** Escaped HTML for rich-text v1, including safe expanded images/entry captions. */
+export function richTextToHtml(value) {
+    return convert(value, 'html');
+}
+/** Authored text with block/hard-break newlines; excludes embeds and link URLs. */
+export function richTextToPlainText(value) {
+    return convert(value, 'text');
+}

package/dist/server.d.ts

@@ -1,8 +1,10 @@
 import type { CMSClient, CMSPreviewOptions, ModelMap, PreviewModels, UntypedModels } from "./types.js";
 export * from "./errors.js";
-export type { CMSPreviewOptions, PreviewModels } from "./types.js";
+export type { CountOptions, GetManyOptions, ContentSearch, SearchOptions, TextField } from "./types.js";
+export type { CMSPreviewOptions, PreviewModels, ContentEntry, ContentPage, ContentTypeIdentity, ContentEnvironment, FindOneOptions } from "./types.js";
 /** Import only from server-owned code. Draft fields may be missing or null. */
 export declare function createCMSPreviewClient<Models extends ModelMap<Models> = UntypedModels>(options: CMSPreviewOptions): CMSClient<PreviewModels<Models>>;
 export { imageSrcSet } from "./images.js";
 export type { RemoteValue } from "./types.js";
 export type { ContentRendition } from "./images.js";
+export { richTextToHtml, richTextToPlainText } from "./rich-text.js";

package/dist/server.js

@@ -14,3 +14,4 @@ export function createCMSPreviewClient(options) {
     return createTransport(options, options?.secretKey, "preview");
 }
 export { imageSrcSet } from "./images.js";
+export { richTextToHtml, richTextToPlainText } from "./rich-text.js";