@lemonadecms/client 0.1.0 → 0.2.0

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";

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 serviceURL = "https://api.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)
@@ -207,7 +296,7 @@ export function createTransport(options, key, mode) {
     // 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.");
+        throw new CMSConfigurationError("CMS clients connect to https://api.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) {
@@ -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);
                 });
             }
         },