@lemonadecms/client 0.1.0 → 0.1.1

package/dist/transport.js

@@ -3,16 +3,24 @@
 // 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";
+import { CMSConfigurationError, CMSRequestError, CMSResponseError, CMSTimeoutError, CMSNotFoundError } 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";
+const localeTag = /^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$/;
 // Narrow unknown JSON to an object before accessing properties. Arrays and null
 // are not valid objects for the API envelope even though typeof reports object.
 function record(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function readOptions(value, allowed, method) {
+    const controls = ["limit", "page", "pageSize", "after", "before", "maxPages", "select", "sort", "filters", "includeRemote", "ids", "search"];
+    if (!record(value) || Object.keys(value).some(key => !allowed.includes(key)) ||
+        controls.some(key => !allowed.includes(key) && key in value)) {
+        throw new TypeError(`${method} supports ${allowed.join(", ")}.`);
+    }
+}
 // 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
@@ -61,9 +69,50 @@ function withinDeadline(timeoutMs, callerSignal, execute) {
         }
     });
 }
+function validateFilters(value) {
+    let nodes = 0, leaves = 0, stringUnits = 0;
+    const scalar = (v) => {
+        if (typeof v === "string") {
+            stringUnits += v.length;
+            return stringUnits <= 4096 && !v.includes("\0");
+        }
+        return typeof v === "boolean" || typeof v === "number" && Number.isFinite(v);
+    };
+    const walk = (node, depth) => {
+        if (!record(node) || depth > 4 || ++nodes > 31)
+            return false;
+        const keys = Object.keys(node);
+        if (keys.length === 1 && ["and", "or", "not"].includes(keys[0])) {
+            const group = keys[0];
+            if (group === "not")
+                return walk(node.not, depth + 1);
+            const children = node[group];
+            return Array.isArray(children) && children.length >= 1 && children.length <= 10 && Array.from(children).every(child => walk(child, depth + 1));
+        }
+        if (++leaves > 10 || keys.sort().join(",") !== "field,op,value" || typeof node.field !== "string" ||
+            !identifier.test(node.field) || typeof node.op !== "string")
+            return false;
+        const v = node.value;
+        if (["eq", "ne"].includes(node.op))
+            return v === null || scalar(v);
+        if (["in", "not_in"].includes(node.op))
+            return Array.isArray(v) && v.length >= 1 && v.length <= 100 && Array.from(v).every(scalar);
+        if (["contains_any", "contains_all"].includes(node.op))
+            return Array.isArray(v) && v.length >= 1 && v.length <= 100 && new Set(v).size === v.length &&
+                Array.from(v).every(option => typeof option === "string" && option.trim().length > 0 && scalar(option));
+        if (["gt", "gte", "lt", "lte"].includes(node.op))
+            return (typeof v === "string" || typeof v === "number") && scalar(v);
+        if (["eqi", "contains", "containsi", "starts_with", "starts_withi", "ends_with", "ends_withi"].includes(node.op))
+            return typeof v === "string" && (node.op === "eqi" || v.length > 0) && scalar(v);
+        return false;
+    };
+    const valid = Array.isArray(value) ? value.length <= 10 && Array.from(value).every(node => walk(node, 0)) : walk(value, 0);
+    if (!valid)
+        throw new TypeError("filters require valid conditions or nonempty and/or/not groups, at most ten leaves, 31 nodes and depth four.");
+}
 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.");
+    if (!record(options) || Object.keys(options).some(key => !["select", "limit", "page", "pageSize", "after", "before", "signal", "locale", "filters", "sort", "search", "includeRemote"].includes(key))) {
+        throw new TypeError("Supported list options are select, limit, page, pageSize, after, before, locale, filters, sort, search, includeRemote and signal.");
     }
     const params = new URLSearchParams();
     if (options.includeRemote !== undefined) {
@@ -95,7 +144,7 @@ function query(options) {
         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)) {
+        if (typeof options.locale !== "string" || !localeTag.test(options.locale)) {
             throw new TypeError("locale must be a language code such as en, es or pt-BR.");
         }
         params.set("locale", options.locale);
@@ -113,23 +162,30 @@ function query(options) {
         }
     }
     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.");
-        }
+        validateFilters(options.filters);
         const encoded = JSON.stringify(options.filters);
         if (new TextEncoder().encode(encoded).length > 4096)
-            throw new TypeError("filters exceed 4 KB.");
+            throw new TypeError("filters exceed 4 KiB.");
         params.set("filters", encoded);
     }
+    if (options.search !== undefined) {
+        const search = options.search;
+        if (!record(search) || Object.keys(search).some(key => !["query", "fields"].includes(key)) ||
+            typeof search.query !== "string" || search.query.includes("\0") ||
+            new TextEncoder().encode(search.query).length > 512 || Array.from(search.query.trim()).length < 1 ||
+            Array.from(search.query.trim()).length > 200 || search.query.trim().split(/\s+/u).length > 16 ||
+            search.fields !== undefined && (!Array.isArray(search.fields) || search.fields.length < 1 || search.fields.length > 24 ||
+                new Set(search.fields).size !== search.fields.length || !Array.from(search.fields).every(key => typeof key === "string" && identifier.test(key)))) {
+            throw new TypeError("search requires 1–200 characters/512 UTF-8 bytes, at most 16 terms, and optionally 1–24 unique text field keys.");
+        }
+        params.set("search", JSON.stringify({ query: search.query.trim(), ...(search.fields !== undefined ? { fields: search.fields } : {}) }));
+    }
     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.");
+        const orders = Array.isArray(options.sort) ? options.sort : [options.sort];
+        if (orders.length < 1 || orders.length > 3 || !Array.from(orders).every(order => record(order) && Object.keys(order).sort().join(",") === "direction,field" &&
+            typeof order.field === "string" && identifier.test(order.field) && ["asc", "desc"].includes(String(order.direction))) ||
+            new Set(orders.map(order => order.field)).size !== orders.length)
+            throw new TypeError("sort requires 1–3 unique scalar fields and asc/desc directions.");
         params.set("sort", JSON.stringify(options.sort));
     }
     return params;
@@ -137,14 +193,14 @@ function query(options) {
 // 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) {
+function decodePage(value, projectId, model, locale) {
     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 data = value.data.map(entry => decodeEntry(entry, projectId, model, locale));
     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)
@@ -172,11 +228,44 @@ function decodePage(value) {
     }
     return { data, meta };
 }
-function decodeEntry(entry) {
+function decodeEntry(entry, projectId, model, locale) {
     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 };
+    const result = {
+        id: entry.id, fields: entry.fields, publishedAt: entry.published_at,
+        projectId, contentType: { key: model },
+    };
+    // Old servers omit this metadata. Retain only known request identity until
+    // the server supplies the rest; never infer an environment from a credential.
+    if (entry.project_id !== undefined &&
+        (typeof entry.project_id !== "string" || entry.project_id.toLowerCase() !== projectId.toLowerCase())) {
+        throw new CMSResponseError("CMS returned conflicting workspace metadata.");
+    }
+    if (entry.content_type !== undefined) {
+        const type = entry.content_type;
+        if (!record(type) || typeof type.id !== "string" || !uuid.test(type.id) ||
+            type.key !== model || typeof type.name !== "string" || !type.name.trim()) {
+            throw new CMSResponseError("CMS returned invalid content-type metadata.");
+        }
+        result.contentType = { id: type.id, key: model, name: type.name };
+    }
+    if (entry.environment !== undefined) {
+        const environment = entry.environment;
+        if (!record(environment) || typeof environment.id !== "string" || !uuid.test(environment.id) ||
+            typeof environment.key !== "string" || !/^[a-z][a-z0-9_-]{0,31}$/.test(environment.key)) {
+            throw new CMSResponseError("CMS returned invalid environment metadata.");
+        }
+        result.environment = { id: environment.id, key: environment.key };
+    }
+    if (entry.locale !== undefined) {
+        if (typeof entry.locale !== "string" || !localeTag.test(entry.locale) || locale !== undefined && entry.locale !== locale) {
+            throw new CMSResponseError("CMS returned invalid locale metadata.");
+        }
+        result.locale = entry.locale;
+    }
+    else if (locale !== undefined)
+        result.locale = locale;
     if (entry.remote !== undefined) {
         const remote = entry.remote;
         if (remote === null)
@@ -237,7 +326,8 @@ export function createTransport(options, key, mode) {
     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}`;
+    const projectId = options.projectId;
+    const endpoint = `${serviceURL}/api/v1/projects/${projectId}/${mode}`;
     return {
         content(model) {
             if (typeof model !== "string" || !identifier.test(model)) {
@@ -247,6 +337,54 @@ export function createTransport(options, key, mode) {
                 async list(options = {}) {
                     return await request(options);
                 },
+                async search(text, options = {}) {
+                    if (!record(options) || "search" in options)
+                        throw new TypeError("search accepts a query string and list options with optional fields.");
+                    const { fields, ...list } = options;
+                    return await request({ ...list, search: { query: text, ...(fields !== undefined ? { fields } : {}) } });
+                },
+                async findOne(options = {}) {
+                    return await firstMatch(options);
+                },
+                async findOneOrThrow(options = {}) {
+                    const entry = await firstMatch(options);
+                    if (entry === null)
+                        throw new CMSNotFoundError(model);
+                    return entry;
+                },
+                async count(options = {}) {
+                    return await statistic("count", options);
+                },
+                async exists(options = {}) {
+                    return await statistic("exists", options);
+                },
+                async getMany(ids, options = {}) {
+                    readOptions(options, ["select", "locale", "signal", "includeRemote"], "getMany");
+                    if (!Array.isArray(ids) || ids.length > 100 || !Array.from(ids).every(id => typeof id === "string" && uuid.test(id))) {
+                        throw new TypeError("getMany ids must contain at most 100 entry UUIDs.");
+                    }
+                    query(options);
+                    options.signal?.throwIfAborted();
+                    const ordered = ids.map(id => id.toLowerCase());
+                    if (ordered.length === 0)
+                        return [];
+                    const requested = new Set(ordered);
+                    const requestedLocale = options.locale;
+                    return await send(options, "/_many", body => {
+                        if (!record(body) || !Array.isArray(body.data) || body.data.length > requested.size) {
+                            throw new CMSResponseError("CMS returned an invalid bulk response.");
+                        }
+                        const entries = new Map();
+                        for (const value of body.data) {
+                            const entry = decodeEntry(value, projectId, model, requestedLocale);
+                            const id = entry.id.toLowerCase();
+                            if (!requested.has(id) || entries.has(id))
+                                throw new CMSResponseError("CMS returned unexpected or duplicate bulk entries.");
+                            entries.set(id, entry);
+                        }
+                        return ordered.map(id => entries.get(id) ?? null);
+                    }, [...requested]);
+                },
                 pages(options = {}) {
                     return iteratePages(options);
                 },
@@ -267,6 +405,25 @@ export function createTransport(options, key, mode) {
                     return await request(options, id);
                 },
             };
+            async function firstMatch(options) {
+                readOptions(options, ["select", "locale", "filters", "sort", "search", "signal", "includeRemote"], "findOne/findOneOrThrow");
+                const page = await request({ ...options, limit: 1 });
+                if (page.meta.limit !== 1)
+                    throw new CMSResponseError("CMS returned an invalid single-match page.");
+                return (page.data[0] ?? null);
+            }
+            async function statistic(operation, options) {
+                readOptions(options, ["locale", "filters", "search", "signal"], operation);
+                return await send(options, `/_${operation}`, body => {
+                    if (!record(body) || !record(body.data))
+                        throw new CMSResponseError("CMS returned an invalid statistic.");
+                    const value = body.data[operation];
+                    if (operation === "count" ? typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 : typeof value !== "boolean") {
+                        throw new CMSResponseError("CMS returned an invalid statistic.");
+                    }
+                    return value;
+                });
+            }
             // 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 = {}) {
@@ -298,7 +455,23 @@ export function createTransport(options, key, mode) {
                 }
             }
             async function request(options, id) {
+                const requestedLocale = options.locale;
+                return await send(options, id ? `/${id}` : "", body => {
+                    if (id) {
+                        if (!record(body))
+                            throw new CMSResponseError("CMS returned an invalid content item.");
+                        const entry = decodeEntry(body.data, projectId, model, requestedLocale);
+                        if (entry.id.toLowerCase() !== id.toLowerCase())
+                            throw new CMSResponseError("CMS returned a different entry than requested.");
+                        return entry;
+                    }
+                    return decodePage(body, projectId, model, requestedLocale);
+                });
+            }
+            async function send(options, path, decode, ids) {
                 const params = query(options);
+                if (ids)
+                    params.set("ids", ids.join(","));
                 const suffix = params.size ? `?${params}` : "";
                 return withinDeadline(timeoutMs, options.signal, async (signal) => {
                     const checkCancellation = () => {
@@ -309,7 +482,7 @@ export function createTransport(options, key, mode) {
                     // 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}`, {
+                    const response = await fetcher(`${endpoint}/${model}${path}${suffix}`, {
                         method: "GET",
                         headers: { Accept: "application/json", Authorization: `Bearer ${key}` },
                         credentials: "omit",
@@ -338,12 +511,7 @@ export function createTransport(options, key, mode) {
                     }
                     // 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);
+                    return decode(body);
                 });
             }
         },

package/dist/types.d.ts

@@ -28,11 +28,11 @@ export type ScalarField<Fields> = {
 type ScalarContentFilter<Fields> = {
     [Key in ScalarField<Fields>]: {
         field: Key;
-        op: "eq";
+        op: "eq" | "ne";
         value: Extract<Fields[Key], Scalar> | (unknown extends Fields[Key] ? Scalar : never) | null;
     } | {
         field: Key;
-        op: "in";
+        op: "in" | "not_in";
         value: readonly (Extract<Fields[Key], Scalar> | (unknown extends Fields[Key] ? Scalar : never))[];
     } | (NonNullable<Fields[Key]> extends boolean ? never : {
         field: Key;
@@ -51,7 +51,28 @@ type ChoicesContentFilter<Fields> = {
         value: readonly ChoicesValue<Fields[Key]>[];
     };
 }[ChoicesField<Fields>];
-export type ContentFilter<Fields> = ScalarContentFilter<Fields> | ChoicesContentFilter<Fields>;
+export type TextField<Fields> = {
+    [Key in FieldName<Fields>]: unknown extends Fields[Key] ? Key : NonNullable<Fields[Key]> extends string ? Key : never;
+}[FieldName<Fields>];
+type TextContentFilter<Fields> = {
+    [Key in TextField<Fields>]: {
+        field: Key;
+        op: "eqi" | "contains" | "containsi" | "starts_with" | "starts_withi" | "ends_with" | "ends_withi";
+        value: string;
+    };
+}[TextField<Fields>];
+export type ContentFilter<Fields> = ScalarContentFilter<Fields> | ChoicesContentFilter<Fields> | TextContentFilter<Fields> | {
+    and: readonly ContentFilter<Fields>[];
+} | {
+    or: readonly ContentFilter<Fields>[];
+} | {
+    not: ContentFilter<Fields>;
+};
+export interface ContentSearch<Fields = Record<string, unknown>> {
+    query: string;
+    /** Top-level text/long_text/markdown fields; the backend validates stored types. */
+    fields?: readonly TextField<Fields>[];
+}
 export interface ContentSort<Fields> {
     field: ScalarField<Fields>;
     direction: "asc" | "desc";
@@ -60,9 +81,11 @@ 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>;
+    /** Ten leaves, depth four, 31 nodes and 4 KiB. Arrays remain implicit AND. */
+    filters?: readonly ContentFilter<Fields>[] | ContentFilter<Fields>;
+    /** One object or 1–3 unique ordered fields; the UUID breaks remaining ties. */
+    sort?: ContentSort<Fields> | readonly ContentSort<Fields>[];
+    search?: ContentSearch<Fields>;
     signal?: AbortSignal;
     /** Explicit live enrichment, independently cached from the saved publication. */
     includeRemote?: boolean;
@@ -85,16 +108,44 @@ export type ListOptions<Key extends string = string, Fields = Record<string, unk
     after?: never;
     before?: never;
 });
+/** One first match, with no caller-controlled page size or boundary. */
+export type FindOneOptions<Key extends string = string, Fields = Record<string, unknown>> = Pick<BaseListOptions<Key, Fields>, "select" | "locale" | "filters" | "sort" | "search" | "signal" | "includeRemote">;
+/** Direct statistics have no pagination, projection, sorting or remote enrichment. */
+export type CountOptions<Fields = Record<string, unknown>> = Pick<BaseListOptions<string, Fields>, "locale" | "filters" | "search" | "signal">;
+export type GetManyOptions<Key extends string = string> = Pick<BaseListOptions<Key, Record<string, unknown>>, "select" | "locale" | "signal" | "includeRemote">;
+/** A paginated search; fields scopes matching, select projects the returned fields. */
+export type SearchOptions<Key extends string = string, Fields = Record<string, unknown>> = ListOptions<Key, Fields> & {
+    fields?: readonly TextField<Fields>[];
+    search?: 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> {
+/** Identity of the selected model; ID/name can be absent on older CMS responses. */
+export interface ContentTypeIdentity<Model extends string = string> {
+    key: Model;
+    id?: string;
+    name?: string;
+}
+export interface ContentEnvironment {
+    id: string;
+    key: string;
+}
+/** Metadata sits beside modeled fields and is retained by field projections. */
+export interface ContentEntry<Fields, Model extends string = string> {
     id: string;
     fields: Fields;
     publishedAt: string | null;
+    /** Optional in this interface to preserve existing manually constructed entries. */
+    contentType?: ContentTypeIdentity<Model>;
+    projectId?: string;
+    /** Resolved request locale; fallback fields can originate in the base language. */
+    locale?: string;
+    /** Absent when the CMS response predates environment metadata. */
+    environment?: ContentEnvironment;
     remote?: RemoteValue | null;
 }
 export interface RemoteValue<Data = Record<string, string | number | boolean | null>> {
@@ -107,8 +158,8 @@ export interface RemoteValue<Data = Record<string, string | number | boolean | n
     fetchedAt: string | null;
     expiresAt: string | null;
 }
-export interface ContentPage<Fields> {
-    data: ContentEntry<Fields>[];
+export interface ContentPage<Fields, Model extends string = string> {
+    data: ContentEntry<Fields, Model>[];
     meta: {
         nextCursor: string | null;
         limit: number;
@@ -119,16 +170,28 @@ export interface ContentPage<Fields> {
         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>>>;
+export interface ContentCollection<Fields extends object, Model extends string = string> {
+    list<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: ListOptions<Key, Fields>): Promise<ContentPage<Pick<Fields, Key>, Model>>;
+    /** One page of plain text matches; relevance order unless an explicit sort is supplied. */
+    search<const Key extends FieldName<Fields> = FieldName<Fields>>(query: string, options?: SearchOptions<Key, Fields>): Promise<ContentPage<Pick<Fields, Key>, Model>>;
+    /** First matching entry or null; all request and response errors still reject. */
+    findOne<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: FindOneOptions<Key, Fields>): Promise<ContentEntry<Pick<Fields, Key>, Model> | null>;
+    /** Required first match; CMSNotFoundError only for a successful empty query. */
+    findOneOrThrow<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: FindOneOptions<Key, Fields>): Promise<ContentEntry<Pick<Fields, Key>, Model>>;
+    /** Matching entries across all pages, counted by the backend without downloading fields. */
+    count(options?: CountOptions<Fields>): Promise<number>;
+    /** Whether any entry matches; backend stops after the first match. */
+    exists(options?: CountOptions<Fields>): Promise<boolean>;
+    /** At most 100 UUIDs in one request; preserves order/duplicates, missing entries become null. */
+    getMany<const Key extends FieldName<Fields> = FieldName<Fields>>(ids: readonly string[], options?: GetManyOptions<Key>): Promise<(ContentEntry<Pick<Fields, Key>, Model> | null)[]>;
     /** 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>>>;
+    pages<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: PaginationOptions<Key, Fields>): AsyncIterableIterator<ContentPage<Pick<Fields, Key>, Model>>;
     /** 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>>>;
+    entries<const Key extends FieldName<Fields> = FieldName<Fields>>(options?: PaginationOptions<Key, Fields>): AsyncIterableIterator<ContentEntry<Pick<Fields, Key>, Model>>;
+    get<const Key extends FieldName<Fields> = FieldName<Fields>>(id: string, options?: Pick<ListOptions<Key, Fields>, "select" | "locale" | "signal" | "includeRemote">): Promise<ContentEntry<Pick<Fields, Key>, Model>>;
 }
 export interface CMSClient<Models extends ModelMap<Models> = UntypedModels> {
-    content<Model extends Extract<keyof Models, string>>(model: Model): ContentCollection<Models[Model]>;
+    content<Model extends Extract<keyof Models, string>>(model: Model): ContentCollection<Models[Model], Model>;
 }
 /** A draft may omit required fields or contain nulls until it is published. */
 export type PreviewModels<Models> = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lemonadecms/client",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Framework-independent content delivery and developer tooling for Lemonade CMS",
   "license": "MIT",
   "homepage": "https://lemonadecms.com/guides/sdk",