@lemonadecms/client 0.0.0-stage → 0.1.0

package/dist/transport.js

@@ -0,0 +1,351 @@
+// Shared, framework-independent HTTP implementation behind the fluent SDK.
+// Configuration and query options are validated before sending a request. The
+// selected factory supplies the credential and route; callers cannot switch modes
+// through list options. Responses are checked as unknown data before their envelope
+// is converted from API snake_case to SDK camelCase. No automatic retries occur.
+import { CMSConfigurationError, CMSRequestError, CMSResponseError, CMSTimeoutError } from "./errors.js";
+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";
+// 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.
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Only configured deadlines need a local controller/race. Keep the default
+// fetch signal unchanged, while rejecting already-cancelled work before I/O.
+// Native composition preserves fetch-style cancellation even when another caller
+// listener suppresses the caller's abort event. Reject the new timeout+signal
+// combination when that capability is absent rather than weaken cancellation.
+// One cleanup path releases the timer and private listener regardless of outcome.
+// The attached fulfillment/rejection handlers also consume late custom-fetch
+// completions when a transport ignores cancellation; they cannot settle twice.
+function withinDeadline(timeoutMs, callerSignal, execute) {
+    callerSignal?.throwIfAborted();
+    if (timeoutMs === undefined)
+        return execute(callerSignal);
+    if (callerSignal && typeof AbortSignal.any !== "function") {
+        throw new CMSConfigurationError("Combining timeoutMs and signal requires AbortSignal.any support.");
+    }
+    const controller = new AbortController();
+    const requestSignal = callerSignal ? AbortSignal.any([callerSignal, controller.signal]) : controller.signal;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        const finish = (complete) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            requestSignal.removeEventListener("abort", cancel);
+            complete();
+        };
+        const cancel = () => {
+            const reason = requestSignal.reason;
+            finish(() => reject(reason));
+            controller.abort(reason);
+        };
+        requestSignal.addEventListener("abort", cancel, { once: true });
+        timer = setTimeout(() => {
+            const error = requestSignal.aborted ? requestSignal.reason : callerSignal?.aborted ? callerSignal.reason : new CMSTimeoutError(timeoutMs);
+            finish(() => reject(error));
+            controller.abort(error);
+        }, timeoutMs);
+        try {
+            execute(requestSignal).then(value => finish(() => resolve(value)), error => finish(() => reject(error)));
+        }
+        catch (error) {
+            finish(() => reject(error));
+        }
+    });
+}
+function query(options) {
+    if (!record(options) || Object.keys(options).some(key => !["select", "limit", "page", "pageSize", "after", "before", "signal", "locale", "filters", "sort", "includeRemote"].includes(key))) {
+        throw new TypeError("Supported list options are select, limit, page, pageSize, after, before, locale, filters, sort and signal.");
+    }
+    const params = new URLSearchParams();
+    if (options.includeRemote !== undefined) {
+        if (typeof options.includeRemote !== "boolean")
+            throw new TypeError("includeRemote must be a boolean.");
+        params.set("includeRemote", String(options.includeRemote));
+    }
+    if (options.select !== undefined) {
+        if (!Array.isArray(options.select) || options.select.length < 1 || options.select.length > 24 ||
+            new Set(options.select).size !== options.select.length ||
+            !options.select.every(key => typeof key === "string" && identifier.test(key))) {
+            throw new TypeError("select must contain 1–24 unique field identifiers.");
+        }
+        params.set("select", options.select.join(","));
+    }
+    if (options.page !== undefined || options.pageSize !== undefined) {
+        if (options.limit !== undefined || options.after !== undefined || options.before !== undefined)
+            throw new TypeError("Use page/pageSize or limit/after/before, never both modes.");
+        const page = options.page ?? 1, size = options.pageSize ?? 25;
+        if (!Number.isSafeInteger(page) || page < 1 || !Number.isInteger(size) || size < 1 || size > 100 || (page - 1) * size > 10000)
+            throw new TypeError("page must be positive, pageSize 1–100, and skipped rows at most 10000.");
+        params.set("page", String(page));
+        params.set("pageSize", String(size));
+    }
+    if (options.limit !== undefined) {
+        if (typeof options.limit !== "number" || !Number.isInteger(options.limit) || options.limit < 1 || options.limit > 100) {
+            throw new TypeError("limit must be an integer between 1 and 100.");
+        }
+        params.set("limit", String(options.limit));
+    }
+    if (options.locale !== undefined) {
+        if (typeof options.locale !== "string" || !/^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$/.test(options.locale)) {
+            throw new TypeError("locale must be a language code such as en, es or pt-BR.");
+        }
+        params.set("locale", options.locale);
+    }
+    if (options.after !== undefined && options.before !== undefined) {
+        throw new TypeError("Use either after or before, never both.");
+    }
+    for (const direction of ["after", "before"]) {
+        const boundary = options[direction];
+        if (boundary !== undefined) {
+            if (typeof boundary !== "string" || !cursor(boundary)) {
+                throw new TypeError(`${direction} must be a cursor returned by the CMS.`);
+            }
+            params.set(direction, boundary);
+        }
+    }
+    if (options.filters !== undefined) {
+        const scalar = (v) => typeof v === "string" && v.length <= 20000 || typeof v === "boolean" || typeof v === "number" && Number.isFinite(v);
+        const choices = (value) => Array.isArray(value) && value.length >= 1 && value.length <= 100 &&
+            new Set(value).size === value.length && value.every(option => typeof option === "string" && option.trim().length > 0 && option.length <= 20000);
+        if (!Array.isArray(options.filters) || options.filters.length > 10 || !options.filters.every(clause => record(clause) && Object.keys(clause).sort().join(",") === "field,op,value" && typeof clause.field === "string" && identifier.test(clause.field) &&
+            (clause.op === "eq" ? clause.value === null || scalar(clause.value) : clause.op === "in" ? Array.isArray(clause.value) && clause.value.length >= 1 && clause.value.length <= 100 && clause.value.every(scalar) :
+                ["contains_any", "contains_all"].includes(String(clause.op)) ? choices(clause.value) :
+                    ["gt", "gte", "lt", "lte"].includes(String(clause.op)) && (typeof clause.value === "string" || typeof clause.value === "number" && Number.isFinite(clause.value))))) {
+            throw new TypeError("filters must contain at most ten valid scalar or multiple-choice AND clauses.");
+        }
+        const encoded = JSON.stringify(options.filters);
+        if (new TextEncoder().encode(encoded).length > 4096)
+            throw new TypeError("filters exceed 4 KB.");
+        params.set("filters", encoded);
+    }
+    if (options.sort !== undefined) {
+        if (!record(options.sort) || Object.keys(options.sort).sort().join(",") !== "direction,field" || !identifier.test(String(options.sort.field)) || !["asc", "desc"].includes(String(options.sort.direction)))
+            throw new TypeError("sort requires a scalar field and asc/desc direction.");
+        params.set("sort", JSON.stringify(options.sort));
+    }
+    return params;
+}
+// Network responses start as unknown even in TypeScript. Check structural
+// properties before returning them, and translate HTTP snake_case metadata into
+// SDK camelCase. This does not validate the caller-declared model field types.
+function decodePage(value) {
+    if (!record(value) || !Array.isArray(value.data) || !record(value.meta) ||
+        typeof value.meta.limit !== "number" || !Number.isInteger(value.meta.limit) ||
+        value.meta.limit < 1 || value.meta.limit > 100 || value.data.length > value.meta.limit ||
+        !(value.meta.next_cursor === null || (typeof value.meta.next_cursor === "string" && cursor(value.meta.next_cursor)))) {
+        throw new CMSResponseError("CMS returned an invalid content page.");
+    }
+    const data = value.data.map(decodeEntry);
+    const meta = { limit: value.meta.limit, nextCursor: value.meta.next_cursor };
+    if (value.meta.page !== undefined || value.meta.page_size !== undefined) {
+        if (typeof value.meta.page !== "number" || !Number.isInteger(value.meta.page) || value.meta.page < 1 || value.meta.page_size !== value.meta.limit || (value.meta.page - 1) * value.meta.limit > 10000)
+            throw new CMSResponseError("CMS returned invalid numbered pagination metadata.");
+        meta.page = value.meta.page;
+        meta.pageSize = value.meta.limit;
+    }
+    // Additive metadata is optional for older installations. When supplied, check
+    // it rather than silently treating a malformed boundary as the end of a list.
+    if (value.meta.previous_cursor !== undefined) {
+        if (!(value.meta.previous_cursor === null || typeof value.meta.previous_cursor === "string" && cursor(value.meta.previous_cursor)))
+            throw new CMSResponseError("CMS returned an invalid previous cursor.");
+        meta.previousCursor = value.meta.previous_cursor;
+    }
+    for (const [wire, sdk] of [["has_next_page", "hasNextPage"], ["has_previous_page", "hasPreviousPage"]]) {
+        if (value.meta[wire] !== undefined) {
+            if (typeof value.meta[wire] !== "boolean")
+                throw new CMSResponseError("CMS returned invalid pagination metadata.");
+            meta[sdk] = value.meta[wire];
+        }
+    }
+    if (meta.hasNextPage !== undefined && meta.hasNextPage !== (meta.nextCursor !== null) ||
+        meta.hasPreviousPage !== undefined && meta.previousCursor !== undefined && meta.hasPreviousPage !== (meta.previousCursor !== null)) {
+        throw new CMSResponseError("CMS returned inconsistent pagination metadata.");
+    }
+    return { data, meta };
+}
+function decodeEntry(entry) {
+    if (!record(entry) || typeof entry.id !== "string" || !uuid.test(entry.id) || !record(entry.fields) ||
+        !(entry.published_at === null || typeof entry.published_at === "string"))
+        throw new CMSResponseError("CMS returned an invalid content entry.");
+    const result = { id: entry.id, fields: entry.fields, publishedAt: entry.published_at };
+    if (entry.remote !== undefined) {
+        const remote = entry.remote;
+        if (remote === null)
+            result.remote = null;
+        else {
+            if (!record(remote) || !["available", "error", "disabled", "not_linked"].includes(String(remote.status)) ||
+                remote.read_only !== true || typeof remote.stale !== "boolean" || typeof remote.source !== "string" ||
+                !(remote.error === null || typeof remote.error === "string") ||
+                !(remote.fetched_at === null || typeof remote.fetched_at === "string") ||
+                !(remote.expires_at === null || typeof remote.expires_at === "string") ||
+                !(remote.data === null || record(remote.data) && Object.values(remote.data).every(v => v === null ||
+                    typeof v === "string" || typeof v === "boolean" || typeof v === "number" && Number.isFinite(v)))) {
+                throw new CMSResponseError("CMS returned invalid remote metadata.");
+            }
+            result.remote = { source: remote.source, status: remote.status,
+                readOnly: true, stale: remote.stale, data: remote.data,
+                error: remote.error, fetchedAt: remote.fetched_at, expiresAt: remote.expires_at };
+        }
+    }
+    return result;
+}
+/** Internal shared transport; public exports choose the credential and route. */
+export function createTransport(options, key, mode) {
+    if (!record(options)) {
+        throw new CMSConfigurationError("CMS client options must be an object.");
+    }
+    // Reject old host configuration rather than silently sending a developer's
+    // 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.");
+    }
+    const credential = mode === "content" ? "publicKey" : "secretKey";
+    if (Object.keys(options).some(option => !["projectId", credential, "fetch", "timeoutMs"].includes(option)) || "environment" in options) {
+        throw new CMSConfigurationError("Supported CMS options are projectId, the delivery key, fetch and timeoutMs. Select a content environment with its delivery key.");
+    }
+    const timeoutMs = options.timeoutMs;
+    if (timeoutMs !== undefined && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647)) {
+        throw new CMSConfigurationError("CMS timeoutMs must be an integer between 1 and 2147483647 milliseconds.");
+    }
+    if (typeof options.projectId !== "string" || !uuid.test(options.projectId)) {
+        throw new CMSConfigurationError("CMS projectId is required and must be a UUID.");
+    }
+    // Each factory chooses its credential kind. Prefix and length detect mistakes
+    // early; only the backend can verify whether the credential is currently valid.
+    const prefix = mode === "content" ? "pk" : "sk";
+    // Named tokens retain a visible public/preview distinction. The server owns
+    // scope and revocation checks; the browser factory still rejects preview keys.
+    const scoped = new RegExp(`^lmd_${prefix}_[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}$`);
+    if (typeof key !== "string" || (!new RegExp(`^${prefix}_[A-Za-z0-9_-]{43}$`).test(key) && !scoped.test(key))) {
+        throw new CMSConfigurationError(mode === "content"
+            ? "A valid publicKey (pk_ or lmd_pk_) is required. Never pass a secret key to the browser client."
+            : "A valid secretKey (sk_ or lmd_sk_) is required for the server preview client.");
+    }
+    // Dependency injection supports framework server contexts and deterministic tests
+    // without coupling the client to Vue, React, or a particular HTTP library.
+    const fetcher = options.fetch ?? globalThis.fetch?.bind(globalThis);
+    if (typeof fetcher !== "function") {
+        throw new CMSConfigurationError("This environment needs fetch; supply a compatible fetch implementation.");
+    }
+    const endpoint = `${serviceURL}/api/v1/projects/${options.projectId}/${mode}`;
+    return {
+        content(model) {
+            if (typeof model !== "string" || !identifier.test(model)) {
+                throw new TypeError("Content type must be a lowercase model identifier.");
+            }
+            return {
+                async list(options = {}) {
+                    return await request(options);
+                },
+                pages(options = {}) {
+                    return iteratePages(options);
+                },
+                async *entries(options = {}) {
+                    const signal = options?.signal;
+                    for await (const page of iteratePages(options)) {
+                        for (const entry of page.data) {
+                            signal?.throwIfAborted();
+                            yield entry;
+                        }
+                    }
+                },
+                async get(id, options = {}) {
+                    if (typeof id !== "string" || !uuid.test(id))
+                        throw new TypeError("id must be an entry UUID.");
+                    if (!record(options) || Object.keys(options).some(k => !["select", "locale", "signal", "includeRemote"].includes(k)))
+                        throw new TypeError("get supports select, locale, includeRemote and signal.");
+                    return await request(options, id);
+                },
+            };
+            // No eager fetch or prefetch: the iterator asks for a page only after the
+            // previous yield is consumed. A break/error closes it without more requests.
+            async function* iteratePages(options = {}) {
+                if (!record(options) || "before" in options || "page" in options || "pageSize" in options)
+                    throw new TypeError("pages/entries support forward traversal with after.");
+                const { maxPages = 1000, ...list } = options;
+                if (!Number.isInteger(maxPages) || maxPages < 1 || maxPages > 10000)
+                    throw new TypeError("maxPages must be an integer between 1 and 10000.");
+                query(list);
+                // Freeze query semantics at first consumption; callers can reuse/mutate
+                // their form state without changing a traversal halfway through.
+                const { signal, ...serializable } = list;
+                const snapshot = { ...JSON.parse(JSON.stringify(serializable)), ...(signal ? { signal } : {}) };
+                let after = snapshot.after;
+                const seen = new Set(after ? [after] : []);
+                for (let count = 0; count < maxPages; count++) {
+                    signal?.throwIfAborted();
+                    const page = await request({ ...snapshot, ...(after ? { after } : {}) });
+                    const next = page.meta.nextCursor;
+                    if (next !== null && seen.has(next))
+                        throw new CMSResponseError("CMS returned a repeated pagination cursor.");
+                    yield page;
+                    if (next === null)
+                        return;
+                    if (count + 1 === maxPages)
+                        throw new RangeError("Pagination reached maxPages; resume with the last nextCursor or raise the limit.");
+                    seen.add(next);
+                    after = next;
+                }
+            }
+            async function request(options, id) {
+                const params = query(options);
+                const suffix = params.size ? `?${params}` : "";
+                return withinDeadline(timeoutMs, options.signal, async (signal) => {
+                    const checkCancellation = () => {
+                        signal?.throwIfAborted();
+                        options.signal?.throwIfAborted();
+                    };
+                    checkCancellation();
+                    // Use only bearer authorization: omit browser cookies, refuse redirects that
+                    // could change the destination, and request fresh data. Abort and network errors
+                    // propagate to the caller; this client does not silently retry a request.
+                    const response = await fetcher(`${endpoint}/${model}${id ? `/${id}` : ""}${suffix}`, {
+                        method: "GET",
+                        headers: { Accept: "application/json", Authorization: `Bearer ${key}` },
+                        credentials: "omit",
+                        redirect: "error",
+                        cache: "no-store",
+                        ...(signal ? { signal } : {}),
+                    });
+                    checkCancellation();
+                    let body;
+                    try {
+                        body = await response.json();
+                    }
+                    catch (error) {
+                        checkCancellation();
+                        if (error instanceof Error && error.name === "AbortError")
+                            throw error;
+                        if (response.ok)
+                            throw new CMSResponseError("CMS returned invalid JSON.");
+                    }
+                    checkCancellation();
+                    // An unsuccessful HTTP status becomes CMSRequestError, even if the response
+                    // was not JSON. A successful response with malformed JSON instead signals a
+                    // response-contract error. Consumers can distinguish these failure categories.
+                    if (!response.ok) {
+                        throw new CMSRequestError(record(body) && typeof body.error === "string" ? body.error : `CMS request failed (${response.status}).`, response.status, record(body) && typeof body.code === "string" ? body.code : "http_error");
+                    }
+                    // Validate the envelope at runtime. Model field types are the caller's
+                    // declaration until schema-generated types/runtime validators exist.
+                    if (id) {
+                        if (!record(body))
+                            throw new CMSResponseError("CMS returned an invalid content item.");
+                        return decodeEntry(body.data);
+                    }
+                    return decodePage(body);
+                });
+            }
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,139 @@
+export type ModelMap<Models> = {
+    [Key in keyof Models]: object;
+};
+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. */
+    url?: never;
+    projectId: string;
+    /** Compatible transport for SSR, testing or polyfills; receives production URLs. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Optional per-request deadline, including JSON reading: 1–2147483647 ms.
+     * No default deadline. Combining with a caller signal requires AbortSignal.any.
+     */
+    timeoutMs?: number;
+}
+export interface CMSClientOptions extends CMSBaseOptions {
+    publicKey: string;
+}
+export interface CMSPreviewOptions extends CMSBaseOptions {
+    secretKey: string;
+}
+type Scalar = string | number | boolean;
+export type ScalarField<Fields> = {
+    [Key in FieldName<Fields>]: unknown extends Fields[Key] ? Key : NonNullable<Fields[Key]> extends Scalar ? Key : never;
+}[FieldName<Fields>];
+type ScalarContentFilter<Fields> = {
+    [Key in ScalarField<Fields>]: {
+        field: Key;
+        op: "eq";
+        value: Extract<Fields[Key], Scalar> | (unknown extends Fields[Key] ? Scalar : never) | null;
+    } | {
+        field: Key;
+        op: "in";
+        value: readonly (Extract<Fields[Key], Scalar> | (unknown extends Fields[Key] ? Scalar : never))[];
+    } | (NonNullable<Fields[Key]> extends boolean ? never : {
+        field: Key;
+        op: "gt" | "gte" | "lt" | "lte";
+        value: Extract<Fields[Key], string | number> | (unknown extends Fields[Key] ? string | number : never);
+    });
+}[ScalarField<Fields>];
+type ChoicesField<Fields> = {
+    [Key in FieldName<Fields>]: unknown extends Fields[Key] ? Key : NonNullable<Fields[Key]> extends readonly string[] ? Key : never;
+}[FieldName<Fields>];
+type ChoicesValue<Value> = NonNullable<Value> extends readonly (infer Option extends string)[] ? Option : string;
+type ChoicesContentFilter<Fields> = {
+    [Key in ChoicesField<Fields>]: {
+        field: Key;
+        op: "contains_any" | "contains_all";
+        value: readonly ChoicesValue<Fields[Key]>[];
+    };
+}[ChoicesField<Fields>];
+export type ContentFilter<Fields> = ScalarContentFilter<Fields> | ChoicesContentFilter<Fields>;
+export interface ContentSort<Fields> {
+    field: ScalarField<Fields>;
+    direction: "asc" | "desc";
+}
+interface BaseListOptions<Key extends string, Fields> {
+    select?: readonly Key[];
+    locale?: string;
+    limit?: number;
+    /** Up to ten AND clauses, validated against the workspace schema by the server. */
+    filters?: readonly ContentFilter<Fields>[];
+    sort?: ContentSort<Fields>;
+    signal?: AbortSignal;
+    /** Explicit live enrichment, independently cached from the saved publication. */
+    includeRemote?: boolean;
+}
+/** Follow a returned boundary in exactly one direction; or request a numbered page; modes cannot be combined. */
+export type ListOptions<Key extends string = string, Fields = Record<string, unknown>> = BaseListOptions<Key, Fields> & ({
+    after?: string;
+    before?: never;
+    page?: never;
+    pageSize?: never;
+} | {
+    before?: string;
+    after?: never;
+    page?: never;
+    pageSize?: never;
+} | {
+    page?: number;
+    pageSize?: number;
+    limit?: never;
+    after?: never;
+    before?: never;
+});
+/** Lazy forward traversal, capped at 1,000 pages by default (maximum 10,000). */
+export type PaginationOptions<Key extends string = string, Fields = Record<string, unknown>> = Omit<ListOptions<Key, Fields>, "before" | "page" | "pageSize"> & {
+    page?: never;
+    pageSize?: never;
+    maxPages?: number;
+};
+export interface ContentEntry<Fields> {
+    id: string;
+    fields: Fields;
+    publishedAt: string | null;
+    remote?: RemoteValue | null;
+}
+export interface RemoteValue<Data = Record<string, string | number | boolean | null>> {
+    source: string;
+    status: "available" | "error" | "disabled" | "not_linked";
+    readOnly: true;
+    stale: boolean;
+    data: Data | null;
+    error: string | null;
+    fetchedAt: string | null;
+    expiresAt: string | null;
+}
+export interface ContentPage<Fields> {
+    data: ContentEntry<Fields>[];
+    meta: {
+        nextCursor: string | null;
+        limit: number;
+        page?: number;
+        pageSize?: number;
+        previousCursor?: string | null;
+        hasNextPage?: boolean;
+        hasPreviousPage?: boolean;
+    };
+}
+export interface ContentCollection<Fields extends object> {
+    list<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: ListOptions<Key, Fields>): Promise<ContentPage<Pick<Fields, Key>>>;
+    /** Fetch only as the caller requests another page. Breaking stops network work. */
+    pages<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: PaginationOptions<Key, Fields>): AsyncIterableIterator<ContentPage<Pick<Fields, Key>>>;
+    /** Flatten pages lazily, retaining at most one page of entries. */
+    entries<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: PaginationOptions<Key, Fields>): AsyncIterableIterator<ContentEntry<Pick<Fields, Key>>>;
+    get<const Key extends FieldName<Fields> = FieldName<Fields>>(id: string, options?: Pick<ListOptions<Key, Fields>, "select" | "locale" | "signal" | "includeRemote">): Promise<ContentEntry<Pick<Fields, Key>>>;
+}
+export interface CMSClient<Models extends ModelMap<Models> = UntypedModels> {
+    content<Model extends Extract<keyof Models, string>>(model: Model): ContentCollection<Models[Model]>;
+}
+/** A draft may omit required fields or contain nulls until it is published. */
+export type PreviewModels<Models> = {
+    [Model in keyof Models]: {
+        [Field in keyof Models[Model]]?: Models[Model][Field] | null;
+    };
+};
+export {};

package/dist/types.js

@@ -0,0 +1,6 @@
+// TypeScript contracts for configuration, fluent queries, and returned pages.
+// A caller can supply a model map to get checked model names and selected fields.
+// These types disappear at runtime: they are not schema discovery or validation
+// of arbitrary model payloads. transport.ts validates the response envelope;
+// the CMS backend validates stored field values when they are written/published.
+export {};

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@lemonadecms/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Framework-independent content delivery and developer tooling for Lemonade CMS",
+  "license": "MIT",
+  "homepage": "https://lemonadecms.com/guides/sdk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ilara-booqself/lemonadecms.git",
+    "directory": "packages/cms-client"
+  },
+  "bugs": {
+    "url": "https://github.com/ilara-booqself/lemonadecms/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "bin/*.mjs",
+    "bin/cli/*.mjs",
+    "bin/codegen/*.mjs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "browser": "./dist/server.browser.js",
+      "default": "./dist/server.js"
+    },
+    "./preview": {
+      "types": "./dist/preview.d.ts",
+      "default": "./dist/preview.js"
+    }
+  },
+  "bin": {
+    "cms-codegen": "bin/generate-types.mjs",
+    "lemonade": "bin/lemonade.mjs"
+  },
+  "private": false
+}