@lemonadecms/client 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0 — initial npm candidate (unpublished)
+
+- Framework-independent ESM client and TypeScript declarations for published REST
+  collection/item reads, field selection, bounded pagination, filters, sorting,
+  localization, references and media helpers.
+- Separate server-only draft-preview client with browser import/runtime guards.
+- Schema-based model generation and the `lemonade` / `cms-codegen` commands.
+- Fixed `https://lemonadecms.com` destination for customer reads; configure the
+  workspace ID and appropriately scoped credential. URL/host/environment overrides
+  fail before I/O. The credential selects the content environment.
+- Optional request deadlines and cancellation. No automatic cache or retry policy.
+- MIT license for this client package. This does not license the rest of the repository.
+
+New applications import `@lemonadecms/client`. Existing local `@cms/client` imports
+can use the documented file alias to the same archive. No package has been
+published by this preparation; registry availability and scope ownership are
+separate release gates.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lemonade CMS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# @lemonadecms/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-independent JavaScript and TypeScript SDK for reading Lemonade CMS
+content. Published-content requests use REST. The package includes TypeScript
+declarations, schema type generation and the `lemonade` developer CLI.
+
+## Install
+
+For a version that has been published to npm:
+
+```sh
+npm install @lemonadecms/client
+# or
+pnpm add @lemonadecms/client
+```
+
+Before a version is published, install its reviewed candidate archive instead.
+Check the supplied `SHA256SUMS`, then use the actual archive path:
+
+```sh
+npm install --ignore-scripts /absolute/path/to/lemonadecms-client-0.1.0.tgz
+# or
+pnpm add /absolute/path/to/lemonadecms-client-0.1.0.tgz
+```
+
+The package uses ESM and declares Node.js 22+. TypeScript consumers need
+TypeScript 5+. Browser reads require standard `fetch`, `URL`, `URLSearchParams`
+and `AbortController`; browser builds must use public credentials only. No
+runtime library or framework dependency is required.
+
+## Configure and read content
+
+The SDK connects to `https://lemonadecms.com` automatically. 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.
+
+Replace the workspace and key placeholders with values from your Lemonade workspace. Replace `content_item` and `title` with your content type and field
+API identifiers, and publish an entry before fetching it.
+
+```js
+import { createCMSClient } from '@lemonadecms/client';
+
+const cms = createCMSClient({
+  projectId: 'YOUR_WORKSPACE_UUID',
+  publicKey: 'YOUR_PUBLIC_DELIVERY_KEY',
+});
+
+const page = await cms.content('content_item').list({
+  select: ['title'],
+  limit: 10,
+});
+
+for (const entry of page.data) {
+  console.log(entry.id, entry.fields.title);
+}
+
+const first = page.data[0];
+if (first) {
+  const entry = await cms.content('content_item').get(first.id);
+  console.log(entry.fields, entry.publishedAt);
+}
+```
+
+Entry values are under `fields`; metadata includes `id` and `publishedAt`.
+An empty collection is `data: []`. Historical or selected fields can be missing
+or `null`, so handle both when rendering. Continue a collection using
+`page.meta.nextCursor` as the next request's `after` value while keeping the
+other query options unchanged.
+
+Use an existing `pk_` public delivery key or an `lmd_pk_` application token with
+the required published-content grants. Anyone with that credential can read
+the content it permits. Browser login cookies do not authorize SDK requests.
+The credential selects the content environment; there is no separate SDK
+environment override. Ask your Owner for a credential belonging to the intended
+environment. The server rechecks current access, expiry and revocation on every
+request.
+
+## Types, queries and framework examples
+
+The [SDK guide](https://lemonadecms.com/guides/sdk) covers generated `Models`,
+field selection, filtering, sorting, localization, cursor and numbered
+pagination, errors, cancellation, images, and JavaScript/React/Vue/Nuxt examples.
+Generate types from your own authorized schema and regenerate them after model
+changes. Types help at compile time; they do not authenticate a request or
+validate every field at runtime.
+
+There is no automatic caching or retry policy. Your application owns rendering,
+loading and error states, cache invalidation and safe HTML handling. Pass an
+`AbortSignal` to cancel a read. Optional `timeoutMs` sets a per-request deadline;
+combining a timeout with a caller signal requires `AbortSignal.any`.
+
+## Private previews
+
+For draft reads, use `createCMSPreviewClient` from
+`@lemonadecms/client/server` in trusted server code with a server-only
+`secretKey`. Authenticate and authorize the requesting user in your application
+before fetching or returning drafts. Do not create an anonymous preview proxy.
+Never put preview credentials or private responses in browser bundles, public
+environment variables, shared caches, static output or logs. The server export
+rejects browser use; that guard does not replace your application's authorization.
+
+`@lemonadecms/client/preview` is a separate optional click-to-edit helper for an
+already authorized website preview. It provides no preview credential or draft
+fetch client.
+
+## Guides
+
+- [Getting started](https://lemonadecms.com/guides)
+- [SDK reference and examples](https://lemonadecms.com/guides/sdk)
+- [Troubleshooting](https://lemonadecms.com/guides/troubleshooting)
+- [Repository](https://github.com/ilara-booqself/lemonadecms)
+
+## License
+
+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.

package/bin/cli/config.mjs

@@ -0,0 +1,254 @@
+import { access } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { readText, parseJSON } from './io.mjs';
+import { fail } from './errors.mjs';
+import { languages } from '../codegen/definitions.mjs';
+export const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const record = (value) =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+const environmentKey = /^[a-z][a-z0-9_-]{0,31}$/;
+const envName = /^[A-Z][A-Z0-9_]{0,127}$/;
+const options = [
+  'config',
+  'target',
+  'url',
+  'workspace',
+  'environment',
+  'credential-env',
+  'file',
+  'out',
+  'plan',
+  'confirm',
+  'before',
+  'language',
+  'baseline',
+  'status',
+  'id',
+];
+const flags = ['json', 'check', 'help', 'version'];
+export function parseArgs(args) {
+  const opts = {},
+    words = [];
+  for (let i = 0; i < args.length; i++) {
+    const word = args[i];
+    if (!word.startsWith('-')) {
+      words.push(word);
+      continue;
+    }
+    const key = word.slice(2);
+    if (
+      !word.startsWith('--') ||
+      (!options.includes(key) && !flags.includes(key)) ||
+      Object.hasOwn(opts, key)
+    )
+      fail(2, 'Unknown or repeated option. Use lemonade --help.');
+    if (flags.includes(key)) opts[key] = true;
+    else {
+      const value = args[++i];
+      if (!value || value.startsWith('--')) fail(2, 'An option value is missing.');
+      opts[key] = value;
+    }
+  }
+  const command = words.join(' ');
+  const allowed = {
+    check: [],
+    'schema inspect': [],
+    'schema pull': ['out'],
+    'schema export': ['out'],
+    'schema validate': ['file'],
+    'schema diff': ['file'],
+    'types generate': ['file', 'out', 'check', 'language'],
+    'schema migrate status': ['before'],
+    'schema migrate create': ['file', 'baseline', 'status', 'id', 'out'],
+    'schema migrate plan': ['file', 'out'],
+    'schema migrate apply': ['file', 'plan', 'confirm'],
+  };
+  if (opts.help || opts.version) {
+    if (
+      words.length ||
+      Object.keys(opts).some((key) => !['help', 'version', 'json'].includes(key)) ||
+      (opts.help && opts.version)
+    )
+      fail(2, 'Use lemonade --help or lemonade --version on its own.');
+  } else {
+    if (!Object.hasOwn(allowed, command))
+      fail(2, 'Unknown command. Use lemonade --help.');
+    for (const key of [
+      'file',
+      'out',
+      'check',
+      'plan',
+      'confirm',
+      'before',
+      'language',
+      'baseline',
+      'status',
+      'id',
+    ])
+      if (Object.hasOwn(opts, key) && !allowed[command].includes(key))
+        fail(2, 'Option is not supported by this command.');
+    if (opts.language && !languages.includes(opts.language))
+      fail(2, 'Choose typescript, csharp or python as the output language.');
+    if (
+      (command === 'schema validate' ||
+        command === 'schema migrate create' ||
+        (command === 'types generate' && opts.file)) &&
+      ['config', 'target', 'url', 'workspace', 'environment', 'credential-env'].some(
+        (key) => Object.hasOwn(opts, key),
+      )
+    )
+      fail(2, 'Offline file commands do not accept connection options.');
+    if (
+      [
+        'schema pull',
+        'schema export',
+        'types generate',
+        'schema migrate plan',
+        'schema migrate create',
+      ].includes(command) &&
+      !opts.out
+    )
+      fail(2, '--out is required.');
+    if (
+      [
+        'schema validate',
+        'schema diff',
+        'schema migrate plan',
+        'schema migrate apply',
+        'schema migrate create',
+      ].includes(command) &&
+      !opts.file
+    )
+      fail(2, '--file is required.');
+    if (
+      command === 'schema migrate create' &&
+      (!opts.baseline ||
+        !opts.status ||
+        !/^[0-9]{14}_[a-z][a-z0-9_]{0,63}$/.test(opts.id || ''))
+    )
+      fail(
+        2,
+        'Creating requires --baseline, --status, --id YYYYMMDDHHMMSS_description, --file and --out.',
+      );
+  }
+  if (
+    command === 'schema migrate apply' &&
+    (!opts.plan || !/^[a-f0-9]{64}$/.test(opts.confirm || ''))
+  )
+    fail(2, 'Applying requires --file, --plan and --confirm REVIEWED_CHECKSUM.');
+  return { command, opts };
+}
+export async function connection(opts, env, cwd, management = false) {
+  const configPath = resolve(cwd, opts.config || 'lemonade.config.json');
+  let config = {};
+  let found = true;
+  try {
+    await access(configPath);
+  } catch (error) {
+    if (error.code !== 'ENOENT' || opts.config)
+      fail(2, 'Could not open project configuration.');
+    found = false;
+  }
+  if (found) {
+    try {
+      config = parseJSON(await readText(configPath, 65536));
+    } catch {
+      fail(2, 'Could not read valid project configuration.');
+    }
+    if (
+      !record(config) ||
+      config.version !== 1 ||
+      !record(config.targets) ||
+      Object.keys(config).some((key) => !['version', 'targets'].includes(key)) ||
+      Object.keys(config.targets).length > 20
+    )
+      fail(2, 'Invalid project configuration.');
+    for (const [name, target] of Object.entries(config.targets)) {
+      if (
+        !environmentKey.test(name) ||
+        !record(target) ||
+        Object.keys(target).some(
+          (key) => !['url', 'workspace', 'environment', 'credentialEnv'].includes(key),
+        ) ||
+        Object.values(target).some((value) => typeof value !== 'string') ||
+        !uuid.test(target.workspace || '') ||
+        !(
+          uuid.test(target.environment || '') ||
+          environmentKey.test(target.environment || '')
+        ) ||
+        (target.credentialEnv !== undefined && !envName.test(target.credentialEnv))
+      )
+        fail(
+          2,
+          'Invalid target configuration; keep credentials in environment variables.',
+        );
+      safeURL(target.url);
+    }
+  }
+  const name = opts.target || env.LEMONADE_TARGET;
+  const target = name ? config.targets?.[name] : {};
+  if (name && !target) fail(2, 'Selected target is not configured.');
+  const selected = {
+    url: opts.url || target.url || env.LEMONADE_URL || 'https://lemonadecms.com',
+    workspace: opts.workspace || target.workspace || env.LEMONADE_WORKSPACE,
+    environment: opts.environment || target.environment || env.LEMONADE_ENVIRONMENT,
+    credentialEnv:
+      opts['credential-env'] ||
+      target.credentialEnv ||
+      (management ? 'LEMONADE_MANAGEMENT_TOKEN' : 'LEMONADE_TOKEN'),
+    configPath,
+  };
+  if (
+    !uuid.test(selected.workspace || '') ||
+    !(
+      uuid.test(selected.environment || '') ||
+      environmentKey.test(selected.environment || '')
+    ) ||
+    !envName.test(selected.credentialEnv)
+  )
+    fail(
+      2,
+      'Set an explicit workspace UUID, environment key/UUID and credential environment-variable name.',
+    );
+  if (management && !uuid.test(selected.environment || ''))
+    fail(2, 'Schema management requires an explicit environment UUID.');
+  const url = safeURL(selected.url);
+  const key = env[selected.credentialEnv];
+  if (
+    typeof key !== 'string' ||
+    !(
+      management
+        ? /^lmd_mgmt_[0-9a-f-]{36}\.[A-Za-z0-9_-]{43}$/
+        : /^(?:(?:pk|sk)_[A-Za-z0-9_-]{43}|lmd_(?:pk|sk)_[0-9a-f-]{36}\.[A-Za-z0-9_-]{43})$/
+    ).test(key)
+  )
+    fail(
+      2,
+      'Set a valid command-specific credential in the configured environment variable.',
+    );
+  selected.url = url.href.replace(/\/+$/, '');
+  return { ...selected, key };
+}
+
+function safeURL(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    fail(2, 'Set a valid CMS URL.');
+  }
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+  if (
+    !['https:', 'http:'].includes(url.protocol) ||
+    (url.protocol === 'http:' && !loopback) ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash
+  )
+    fail(
+      2,
+      'Use HTTPS (HTTP only on loopback), without URL credentials, query or fragment.',
+    );
+  return url;
+}

package/bin/cli/create-migration.mjs

@@ -0,0 +1,157 @@
+import { resolve } from 'node:path';
+import { validateSchema, canonical } from './schema.mjs';
+import { parseJSON, readText, writeOutput } from './io.mjs';
+import { record } from './config.mjs';
+import { fail } from './errors.mjs';
+
+const equal = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+const rejected = () =>
+  fail(
+    5,
+    'Only new models and appended optional fields are supported. Existing definitions, languages and remote bindings must remain unchanged.',
+  );
+function migrationFields(fields, adding = false) {
+  for (const field of fields) {
+    if (
+      ['component', 'components', 'blocks'].includes(field.type) ||
+      Object.hasOwn(field, 'default') ||
+      Object.hasOwn(field, 'seo') ||
+      (adding && field.required)
+    )
+      rejected();
+  }
+}
+
+function orderedOperations(operations, existingKeys) {
+  const sorted = [...operations].sort((a, b) =>
+    a.key < b.key ? -1 : a.key > b.key ? 1 : 0,
+  );
+  const pending = sorted.filter((operation) => operation.op === 'create_model');
+  const available = new Set(existingKeys);
+  const ordered = [];
+  while (pending.length) {
+    const index = pending.findIndex((operation) =>
+      operation.fields.every((field) => {
+        const targets = ['reference', 'references'].includes(field.type)
+          ? [field.target]
+          : field.type === 'rich_text'
+            ? field.targets || []
+            : [];
+        return targets.every(
+          (target) => target === operation.key || available.has(target),
+        );
+      }),
+    );
+    if (index < 0)
+      fail(
+        5,
+        'New-model reference cycles require separate reviewed additions. No output was written.',
+      );
+    const [next] = pending.splice(index, 1);
+    ordered.push(next);
+    available.add(next.key);
+  }
+  return [...ordered, ...sorted.filter((operation) => operation.op === 'add_fields')];
+}
+
+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 status = parseJSON(await readText(paths[2]));
+  const environment = baseline.environment?.id || baseline.project_id;
+  const modelSummary = (schema) =>
+    schema.models
+      .map((model) => ({
+        key: model.key,
+        ...(model.singleton ? { singleton: true } : {}),
+        fields: model.fields.map(({ key, type }) => ({ key, type })),
+      }))
+      .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  if (
+    !record(status) ||
+    status.ok !== true ||
+    status.workspace !== baseline.project_id ||
+    status.environment !== environment ||
+    status.revision !== baseline.schema_revision ||
+    !/^[a-f0-9]{64}$/.test(status.schema_hash || '') ||
+    !(
+      status.latest === null ||
+      /^[0-9]{14}_[a-z][a-z0-9_]{0,63}$/.test(status.latest || '')
+    ) ||
+    (status.latest !== null && opts.id <= status.latest) ||
+    !Array.isArray(status.models) ||
+    !equal(
+      [...status.models].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0)),
+      modelSummary(baseline),
+    )
+  )
+    fail(
+      5,
+      'Status and baseline identity, revision or model summary do not match. Capture fresh inputs.',
+    );
+  // Require an exact portable editing baseline. Never turn unsupported edits into
+  // omissions, removals, or a blind desired-state replacement.
+  const withoutModels = ({ models, ...rest }) => rest;
+  if (!equal(withoutModels(baseline), withoutModels(desired))) rejected();
+  const operations = [];
+  const prior = new Map(baseline.models.map((model) => [model.key, model]));
+  for (const model of desired.models) {
+    const before = prior.get(model.key);
+    if (!before) {
+      if (model.remote) rejected();
+      migrationFields(model.fields);
+      operations.push({
+        op: 'create_model',
+        ...(model.singleton ? { singleton: true } : {}),
+        key: model.key,
+        name: model.name,
+        fields: model.fields,
+      });
+    } else {
+      if (
+        !equal({ ...before, fields: [] }, { ...model, fields: [] }) ||
+        model.fields.length < before.fields.length ||
+        !equal(before.fields, model.fields.slice(0, before.fields.length))
+      )
+        rejected();
+      const added = model.fields.slice(before.fields.length);
+      if (added.length) {
+        if (model.remote) rejected();
+        migrationFields(added, true);
+        operations.push({ op: 'add_fields', key: model.key, fields: added });
+      }
+      prior.delete(model.key);
+    }
+  }
+  if (prior.size) rejected();
+  if (!operations.length || operations.length > 16)
+    fail(5, 'Create between 1 and 16 supported model operations per migration.');
+  const migration = {
+    format_version: 1,
+    id: opts.id,
+    previous: status.latest,
+    from: status.schema_hash,
+    operations: orderedOperations(
+      operations,
+      baseline.models.map((model) => model.key),
+    ),
+  };
+  const text = JSON.stringify(migration, null, 2) + '\n';
+  if (Buffer.byteLength(text) > 262144)
+    fail(5, 'Migration exceeds the supported size.');
+  await writeOutput(resolve(cwd, opts.out), text, [
+    ...paths,
+    resolve(cwd, 'lemonade.config.json'),
+  ]);
+  return {
+    ok: true,
+    command: 'schema migrate create',
+    written: true,
+    operations: operations.length,
+    publication: 'unchanged',
+    requiresReview: true,
+  };
+}

package/bin/cli/errors.mjs

@@ -0,0 +1,9 @@
+export class CLIError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+export function fail(code, message) {
+  throw new CLIError(code, message);
+}

package/bin/cli/io.mjs

@@ -0,0 +1,70 @@
+import { open, mkdir, rename, unlink, realpath } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fail } from './errors.mjs';
+
+export const MAX_SCHEMA_BYTES = 8 * 1024 * 1024;
+export async function readText(path, max = MAX_SCHEMA_BYTES) {
+  let file;
+  try {
+    file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    const stat = await file.stat();
+    if (!stat.isFile() || stat.size > max)
+      fail(5, 'Input must be a bounded regular file.');
+    const buffer = Buffer.alloc(max + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const { bytesRead } = await file.read(buffer, size, buffer.length - size, null);
+      if (!bytesRead) break;
+      size += bytesRead;
+    }
+    if (size > max) fail(5, 'Input exceeds the supported size.');
+    return new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, size));
+  } catch (error) {
+    if (error.code === 5) throw error;
+    fail(5, 'Could not read the input file.');
+  } finally {
+    await file?.close();
+  }
+}
+export function parseJSON(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    fail(5, 'Input is not valid JSON.');
+  }
+}
+export async function writeOutput(path, text, protectedPaths = []) {
+  const destination = resolve(path);
+  const existingDestination = await realpath(destination).catch(() => destination);
+  const existingProtected = await Promise.all(
+    protectedPaths
+      .filter(Boolean)
+      .map((value) => realpath(resolve(value)).catch(() => resolve(value))),
+  );
+  if (
+    existingProtected.includes(existingDestination) ||
+    protectedPaths.some((value) => value && resolve(value) === destination) ||
+    /^(?:\.env(?:\..*)?|lemonade\.config\.json)$/i.test(
+      destination.split(/[\\/]/).pop(),
+    )
+  ) {
+    fail(2, 'Output must not replace configuration, credentials or the input schema.');
+  }
+  const temp = `${destination}.${randomUUID()}.tmp`;
+  try {
+    await mkdir(dirname(destination), { recursive: true });
+    const file = await open(temp, 'wx', 0o600);
+    try {
+      await file.writeFile(text);
+    } finally {
+      await file.close();
+    }
+    await rename(temp, destination);
+  } catch {
+    fail(6, 'Could not write the output file.');
+  } finally {
+    await unlink(temp).catch(() => {});
+  }
+}