@cms0/cms0 0.0.9 → 0.0.11

package/dist/esm/index.js

@@ -1,44 +1,639 @@
 import { schemaDescriptor } from "@cms0/cms0/schema-descriptors";
-import * as Shared from "@cms0/shared";
-/**
- * Initializes the CMS SDK for a given schema.
- * @param config configuration including API base URL or database URL.
- * @returns an object with typed accessors matching the schema.
- */
-export function cms0(config) {
-    const baseUrl = config.apiConfig?.baseUrl?.replace(/\/$/, "") ?? "";
-    const apiKey = config.apiConfig?.key;
-    return new Proxy({}, {
-        get(target, prop) {
-            if (!(prop in schemaDescriptor.roots)) {
-                throw new Error(`Unknown schema key '${prop}'`);
+import { buildZodSchemasFromDescriptor, } from "@cms0/shared";
+const COLLECTION_SHAPE_ERROR = "Invalid collection response. Expected array or { items, total }.";
+function toPlainText(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (!value || typeof value !== "object")
+        return "";
+    const node = value;
+    if (typeof node.text === "string")
+        return node.text;
+    if ("value" in node)
+        return toPlainText(node.value);
+    if (Array.isArray(node.content)) {
+        return node.content
+            .map((child) => toPlainText(child))
+            .filter(Boolean)
+            .join(" ")
+            .trim();
+    }
+    return "";
+}
+function coerceRichTextValue(value) {
+    const source = value && typeof value === "object" ? value : {};
+    const nested = source.value && typeof source.value === "object"
+        ? source.value
+        : null;
+    const normalizedValue = source.value !== undefined ? source.value : value ?? {};
+    const html = typeof source.html === "string"
+        ? source.html
+        : typeof nested?.html === "string"
+            ? nested.html
+            : "";
+    return {
+        value: normalizedValue ?? {},
+        html,
+    };
+}
+function shouldKeepLocalizedEntry(source, locale, defaultLocale) {
+    if (locale === "all")
+        return true;
+    const rowLocale = typeof source.locale === "string" ? source.locale : "";
+    if (locale) {
+        return rowLocale === locale;
+    }
+    if (defaultLocale) {
+        return rowLocale === defaultLocale;
+    }
+    return true;
+}
+function coerceLocalizedStringValue(value, locale, defaultLocale) {
+    const rows = Array.isArray(value) ? value : [];
+    return rows
+        .map((row) => {
+        const source = row && typeof row === "object" ? row : {};
+        return {
+            ...source,
+            locale: typeof source.locale === "string" ? source.locale : "",
+            isDefault: source.isDefault === true,
+            value: toPlainText(source.value),
+        };
+    })
+        .filter((row) => shouldKeepLocalizedEntry(row, locale, defaultLocale));
+}
+function coerceLocalizedRichTextValue(value, locale, defaultLocale) {
+    const rows = Array.isArray(value) ? value : [];
+    return rows
+        .map((row) => {
+        const source = row && typeof row === "object" ? row : {};
+        const rawValue = source.value;
+        const nested = rawValue && typeof rawValue === "object" ? rawValue : null;
+        const normalizedValue = nested && "value" in nested && nested.value !== undefined
+            ? nested.value
+            : rawValue ?? {};
+        const html = typeof source.html === "string"
+            ? source.html
+            : typeof nested?.html === "string"
+                ? nested.html
+                : "";
+        return {
+            ...source,
+            locale: typeof source.locale === "string" ? source.locale : "",
+            isDefault: source.isDefault === true,
+            value: normalizedValue ?? {},
+            html,
+        };
+    })
+        .filter((row) => shouldKeepLocalizedEntry(row, locale, defaultLocale));
+}
+function coerceCustomTypeValue(descriptor, value, options) {
+    const customType = descriptor.customType;
+    if (!customType)
+        return value;
+    if (customType === "RichText")
+        return coerceRichTextValue(value);
+    if (customType === "LocalizedString") {
+        return coerceLocalizedStringValue(value, options?.locale, options?.defaultLocale);
+    }
+    if (customType === "LocalizedRichText") {
+        return coerceLocalizedRichTextValue(value, options?.locale, options?.defaultLocale);
+    }
+    return value;
+}
+function isPrimitiveDescriptor(desc) {
+    return desc.kind === "primitive";
+}
+function isModelRefDescriptor(desc) {
+    return desc.kind === "modelRef";
+}
+function isObjectDescriptor(desc) {
+    return desc.type === "object" && !!desc.properties;
+}
+function isArrayDescriptor(desc) {
+    return desc.type === "array" && !!desc.items;
+}
+function asModelObjectDescriptor(modelName, descriptor) {
+    const model = descriptor.models?.[modelName];
+    if (!model) {
+        throw new Error(`Unknown model '${modelName}' in schema descriptor.`);
+    }
+    return {
+        type: "object",
+        properties: model.properties,
+        optional: false,
+        nullable: false,
+    };
+}
+function normalizeBaseUrl(baseUrl) {
+    const cleaned = baseUrl?.trim().replace(/\/$/, "") ?? "";
+    if (!cleaned) {
+        throw new Error("cms0: apiConfig.baseUrl is required to consume API resources.");
+    }
+    return cleaned;
+}
+function resolveIncludeIdMode(includeId) {
+    if (includeId === true)
+        return "all";
+    if (includeId === false)
+        return "none";
+    return "collections";
+}
+function shouldIncludeObjectId(mode, isCollectionItem) {
+    if (mode === "all")
+        return true;
+    if (mode === "collections")
+        return isCollectionItem;
+    return false;
+}
+function buildSearchParams(query) {
+    const params = new URLSearchParams();
+    if (!query)
+        return params;
+    for (const [key, rawValue] of Object.entries(query)) {
+        if (rawValue === undefined || rawValue === null)
+            continue;
+        if (Array.isArray(rawValue)) {
+            rawValue.forEach((value) => {
+                if (value === undefined || value === null)
+                    return;
+                params.append(key, String(value));
+            });
+            continue;
+        }
+        params.set(key, String(rawValue));
+    }
+    return params;
+}
+function ensureCollectionEnvelope(data, path) {
+    if (Array.isArray(data)) {
+        return { items: data, total: data.length };
+    }
+    if (data && typeof data === "object" && Array.isArray(data.items)) {
+        return {
+            items: data.items,
+            total: Number(data.total ?? data.items.length ?? 0),
+        };
+    }
+    throw new Error(`${COLLECTION_SHAPE_ERROR} Path: '${path}'.`);
+}
+function extractId(value) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (value && typeof value === "object" && typeof value.id === "string") {
+        return value.id;
+    }
+    return null;
+}
+function capitalize(input) {
+    return input ? input[0].toUpperCase() + input.slice(1) : input;
+}
+function lowerFirst(input) {
+    return input ? input[0].toLowerCase() + input.slice(1) : input;
+}
+function camelCaseModelIdKey(modelName) {
+    return `${lowerFirst(modelName)}Id`;
+}
+function snakeCaseModelIdKey(modelName) {
+    const snake = modelName
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/\s+/g, "_")
+        .toLowerCase();
+    return `${snake}_id`;
+}
+function extractModelRefId(raw, modelName, options) {
+    if (typeof raw === "string")
+        return raw;
+    if (!raw || typeof raw !== "object")
+        return null;
+    const object = raw;
+    const prop = options?.propertyName ?? "";
+    const candidates = [
+        camelCaseModelIdKey(modelName),
+        snakeCaseModelIdKey(modelName),
+        prop ? `${prop}Id` : "",
+        prop
+            ? `${prop.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase()}_id`
+            : "",
+        "value",
+    ].filter(Boolean);
+    for (const key of candidates) {
+        const found = extractId(object[key]);
+        if (found)
+            return found;
+    }
+    const byId = extractId(object);
+    if (byId)
+        return byId;
+    return null;
+}
+function formatValidationError(name, error) {
+    const payload = error && typeof error === "object" && "format" in error
+        ? error.format()
+        : error;
+    return `Invalid data received for '${name}': ${JSON.stringify(payload)}`;
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (!a.length)
+        return b.length;
+    if (!b.length)
+        return a.length;
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    const matrix = Array.from({ length: rows }, () => new Array(cols).fill(0));
+    for (let i = 0; i < rows; i++)
+        matrix[i][0] = i;
+    for (let j = 0; j < cols; j++)
+        matrix[0][j] = j;
+    for (let i = 1; i < rows; i++) {
+        for (let j = 1; j < cols; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+        }
+    }
+    return matrix[rows - 1][cols - 1];
+}
+function unknownKeyError(key, roots, models) {
+    const candidates = [...roots, ...models];
+    const normalized = key.toLowerCase();
+    const suggestions = candidates
+        .map((candidate) => ({
+        candidate,
+        distance: levenshtein(normalized, candidate.toLowerCase()),
+    }))
+        .sort((a, b) => a.distance - b.distance)
+        .slice(0, 3)
+        .map((entry) => entry.candidate);
+    const suggestionText = suggestions.length
+        ? ` Did you mean: ${suggestions.join(", ")}?`
+        : "";
+    const rootsText = `Available roots: [${roots.join(", ")}]`;
+    const modelsText = models.length
+        ? `, models (under data.models.*): [${models.join(", ")}]`
+        : "";
+    throw new Error(`Unknown schema key '${key}'. ${rootsText}${modelsText}.${suggestionText}`);
+}
+async function normalizeModelRef(modelName, id, context, trail, isCollectionItem) {
+    if (!id)
+        return null;
+    if (!context.options.resolveModelRefs)
+        return id;
+    const nodeKey = `${modelName}:${id}`;
+    if (trail.has(nodeKey)) {
+        return shouldIncludeObjectId(context.options.includeIdMode, isCollectionItem)
+            ? { id }
+            : id;
+    }
+    const modelDescriptor = context.modelDescriptors.get(modelName);
+    if (!modelDescriptor) {
+        return id;
+    }
+    const cached = context.modelCache.get(nodeKey);
+    if (cached) {
+        return cached;
+    }
+    const nextTrail = new Set(trail);
+    nextTrail.add(nodeKey);
+    const promise = (async () => {
+        const rawModel = await context.requestJson(`models/${modelName}/${id}`, {
+            query: {
+                raw: 1,
+                ...(context.options.locale ? { locale: context.options.locale } : {}),
+            },
+        });
+        return normalizeField(modelDescriptor, `models/${modelName}/${encodeURIComponent(id)}`, rawModel, context, nextTrail, isCollectionItem);
+    })().catch((error) => {
+        context.modelCache.delete(nodeKey);
+        throw error;
+    });
+    context.modelCache.set(nodeKey, promise);
+    return promise;
+}
+async function normalizeObjectField(descriptor, path, raw, context, trail, isCollectionItem) {
+    const source = raw && typeof raw === "object" ? raw : {};
+    const output = {};
+    for (const [propertyName, propertyDescriptor] of Object.entries(descriptor.properties)) {
+        if (isPrimitiveDescriptor(propertyDescriptor)) {
+            output[propertyName] = coerceCustomTypeValue(propertyDescriptor, source[propertyName], {
+                locale: context.options.locale,
+                defaultLocale: context.options.defaultLocale,
+            });
+            continue;
+        }
+        if (isModelRefDescriptor(propertyDescriptor)) {
+            const refId = extractModelRefId(source, propertyDescriptor.model, {
+                propertyName,
+            });
+            output[propertyName] = await normalizeModelRef(propertyDescriptor.model, refId, context, trail, false);
+            continue;
+        }
+        if (isArrayDescriptor(propertyDescriptor)) {
+            const childPath = `${path}/${propertyName}`;
+            const childRaw = await context.requestJson(childPath, {
+                query: {
+                    raw: 1,
+                    ...(context.options.locale ? { locale: context.options.locale } : {}),
+                },
+            });
+            const normalizedChild = await normalizeArrayField(propertyDescriptor, childPath, childRaw, context, trail);
+            output[propertyName] = coerceCustomTypeValue(propertyDescriptor, normalizedChild, {
+                locale: context.options.locale,
+                defaultLocale: context.options.defaultLocale,
+            });
+            continue;
+        }
+        if (isObjectDescriptor(propertyDescriptor)) {
+            const childPath = `${path}/${propertyName}`;
+            const childRaw = await context.requestJson(childPath, {
+                query: {
+                    raw: 1,
+                    ...(context.options.locale ? { locale: context.options.locale } : {}),
+                },
+            });
+            const normalizedChild = await normalizeObjectField(propertyDescriptor, childPath, childRaw, context, trail, false);
+            output[propertyName] = coerceCustomTypeValue(propertyDescriptor, normalizedChild, {
+                locale: context.options.locale,
+                defaultLocale: context.options.defaultLocale,
+            });
+        }
+    }
+    if (shouldIncludeObjectId(context.options.includeIdMode, isCollectionItem)) {
+        const rowId = extractId(source);
+        if (rowId)
+            output.id = rowId;
+    }
+    return output;
+}
+async function normalizeArrayField(descriptor, path, raw, context, trail) {
+    const envelope = ensureCollectionEnvelope(raw, path);
+    const itemDescriptor = descriptor.items;
+    if (isPrimitiveDescriptor(itemDescriptor)) {
+        return envelope.items.map((row) => {
+            const value = row && typeof row === "object" && "value" in row
+                ? row.value
+                : row;
+            if (context.options.includeIdMode !== "all") {
+                return value;
             }
-            return async () => {
-                const url = `${baseUrl}/${prop}`;
-                const res = await fetch(url, {
-                    method: "GET",
-                    headers: {
-                        "Content-Type": "application/json",
-                        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
-                    },
-                });
-                if (!res.ok) {
-                    throw new Error(`Request failed for '${prop}' with status ${res.status}: ${res.statusText}`);
-                }
-                const data = await res.json();
-                // Validate via Zod
-                const { zodSchemas } = Shared.buildZodSchemasFromDescriptor(schemaDescriptor);
-                const schema = zodSchemas[prop];
-                if (!schema) {
-                    // If no schema found, return the raw data
-                    return data;
-                }
-                const result = schema.safeParse(data);
-                if (!result.success) {
-                    throw new Error(`Invalid data received for '${prop}': ${JSON.stringify(result.error.format())}`);
-                }
-                return result.data;
+            const id = extractId(row);
+            return id ? { id, value } : value;
+        });
+    }
+    if (isModelRefDescriptor(itemDescriptor)) {
+        const resolved = await Promise.all(envelope.items.map(async (row) => {
+            const refId = extractModelRefId(row, itemDescriptor.model);
+            return normalizeModelRef(itemDescriptor.model, refId, context, trail, true);
+        }));
+        return resolved;
+    }
+    if (isObjectDescriptor(itemDescriptor)) {
+        return Promise.all(envelope.items.map(async (row) => {
+            const rowId = extractId(row);
+            const rowPath = rowId
+                ? `${path}/${encodeURIComponent(rowId)}`
+                : path;
+            return normalizeObjectField(itemDescriptor, rowPath, row, context, trail, true);
+        }));
+    }
+    return envelope.items;
+}
+async function normalizeField(descriptor, path, raw, context, trail, isCollectionItem) {
+    if (isPrimitiveDescriptor(descriptor)) {
+        const value = raw && typeof raw === "object" && "value" in raw
+            ? raw.value
+            : raw;
+        return coerceCustomTypeValue(descriptor, value, {
+            locale: context.options.locale,
+            defaultLocale: context.options.defaultLocale,
+        });
+    }
+    if (isModelRefDescriptor(descriptor)) {
+        const refId = extractModelRefId(raw, descriptor.model);
+        return normalizeModelRef(descriptor.model, refId, context, trail, isCollectionItem);
+    }
+    if (isArrayDescriptor(descriptor)) {
+        const normalized = await normalizeArrayField(descriptor, path, raw, context, trail);
+        return coerceCustomTypeValue(descriptor, normalized, {
+            locale: context.options.locale,
+            defaultLocale: context.options.defaultLocale,
+        });
+    }
+    if (isObjectDescriptor(descriptor)) {
+        const normalized = await normalizeObjectField(descriptor, path, raw, context, trail, isCollectionItem);
+        return coerceCustomTypeValue(descriptor, normalized, {
+            locale: context.options.locale,
+            defaultLocale: context.options.defaultLocale,
+        });
+    }
+    return raw;
+}
+function createResourceRegistry(descriptor) {
+    const roots = new Map();
+    const rootsCaseInsensitive = new Map();
+    for (const [key, rootDescriptor] of Object.entries(descriptor.roots ?? {})) {
+        const entry = {
+            kind: "root",
+            key,
+            path: key,
+            descriptor: rootDescriptor,
+            isCollection: isArrayDescriptor(rootDescriptor),
+        };
+        roots.set(key, entry);
+        rootsCaseInsensitive.set(key.toLowerCase(), entry);
+    }
+    const models = new Map();
+    const modelsCaseInsensitive = new Map();
+    for (const modelName of Object.keys(descriptor.models ?? {})) {
+        const entry = {
+            kind: "model",
+            key: modelName,
+            path: `models/${modelName}`,
+            descriptor: asModelObjectDescriptor(modelName, descriptor),
+            isCollection: true,
+            modelName,
+        };
+        models.set(modelName, entry);
+        modelsCaseInsensitive.set(modelName.toLowerCase(), entry);
+    }
+    return {
+        roots,
+        rootsCaseInsensitive,
+        models,
+        modelsCaseInsensitive,
+    };
+}
+async function requestJson(baseUrl, apiKey, path, options) {
+    const params = buildSearchParams(options?.query);
+    const url = `${baseUrl}/${path}${params.toString() ? `?${params.toString()}` : ""}`;
+    const response = await fetch(url, {
+        method: "GET",
+        signal: options?.signal,
+        headers: {
+            ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Request failed for '${path}' with status ${response.status}: ${response.statusText}`);
+    }
+    return response.json();
+}
+function validateResult(resource, result, descriptor, includeIdMode, zodSchemas, modelZodSchemas) {
+    if (includeIdMode === "all")
+        return;
+    if (resource.kind === "root") {
+        const schema = zodSchemas[resource.key];
+        if (!schema)
+            return;
+        const parsed = schema.safeParse(result);
+        if (!parsed.success) {
+            throw new Error(formatValidationError(resource.key, parsed.error));
+        }
+        return;
+    }
+    const modelName = resource.modelName;
+    if (!modelName)
+        return;
+    const modelSchema = modelZodSchemas[modelName];
+    if (!modelSchema)
+        return;
+    if (Array.isArray(result)) {
+        const parsed = modelSchema.array().safeParse(result);
+        if (!parsed.success) {
+            throw new Error(formatValidationError(modelName, parsed.error));
+        }
+        return;
+    }
+    if (result === null || result === undefined)
+        return;
+    const parsed = modelSchema.safeParse(result);
+    if (!parsed.success) {
+        throw new Error(formatValidationError(modelName, parsed.error));
+    }
+}
+async function runResource(resource, descriptor, baseUrl, apiKey, defaultLocale, zodSchemas, modelZodSchemas, options, byId) {
+    const responseMode = options?.response ?? "normalized";
+    const includeIdMode = resolveIncludeIdMode(options?.includeId);
+    const resolveModelRefs = options?.resolveModelRefs !== false;
+    const locale = options?.locale ??
+        (typeof options?.query?.locale === "string"
+            ? options.query.locale
+            : defaultLocale);
+    const query = {
+        ...(options?.query ?? {}),
+    };
+    const shouldNormalize = responseMode !== "raw";
+    if (shouldNormalize && query.raw === undefined) {
+        query.raw = 1;
+    }
+    if (locale && query.locale === undefined) {
+        query.locale = locale;
+    }
+    const resourcePath = byId
+        ? `${resource.path}/${encodeURIComponent(byId)}`
+        : resource.path;
+    const rawData = await requestJson(baseUrl, apiKey, resourcePath, {
+        query,
+        signal: options?.signal,
+    });
+    if (!shouldNormalize) {
+        return rawData;
+    }
+    const modelDescriptors = new Map();
+    for (const modelName of Object.keys(descriptor.models ?? {})) {
+        modelDescriptors.set(modelName, asModelObjectDescriptor(modelName, descriptor));
+    }
+    const context = {
+        requestJson: (path, requestOptions) => requestJson(baseUrl, apiKey, path, {
+            ...requestOptions,
+            signal: options?.signal,
+        }),
+        modelDescriptors,
+        modelCache: new Map(),
+        options: {
+            includeIdMode,
+            resolveModelRefs,
+            locale,
+            defaultLocale,
+        },
+    };
+    if (resource.isCollection && !byId) {
+        const envelope = ensureCollectionEnvelope(rawData, resource.path);
+        const descriptorForCollection = resource.kind === "root" && isArrayDescriptor(resource.descriptor)
+            ? resource.descriptor
+            : {
+                type: "array",
+                items: resource.descriptor,
+                optional: false,
+                nullable: false,
+            };
+        const normalizedItems = await normalizeArrayField(descriptorForCollection, resource.path, envelope, context, new Set());
+        if (responseMode === "envelope") {
+            validateResult(resource, normalizedItems, descriptor, includeIdMode, zodSchemas, modelZodSchemas);
+            return {
+                items: normalizedItems,
+                total: envelope.total,
             };
+        }
+        validateResult(resource, normalizedItems, descriptor, includeIdMode, zodSchemas, modelZodSchemas);
+        return normalizedItems;
+    }
+    const normalized = await normalizeField(resource.descriptor, resourcePath, rawData, context, new Set(), false);
+    validateResult(resource, normalized, descriptor, includeIdMode, zodSchemas, modelZodSchemas);
+    return normalized;
+}
+export function createCmsClient(descriptor, config) {
+    const baseUrl = normalizeBaseUrl(config.apiConfig?.baseUrl);
+    const apiKey = config.apiConfig?.key;
+    const registry = createResourceRegistry(descriptor);
+    const rootKeys = Array.from(registry.roots.keys());
+    const modelKeys = Array.from(registry.models.keys());
+    const { zodSchemas, modelZodSchemas } = buildZodSchemasFromDescriptor(descriptor);
+    const buildModelAccessor = (entry) => {
+        const accessor = (async (options) => runResource(entry, descriptor, baseUrl, apiKey, config.defaultLocale, zodSchemas, modelZodSchemas, options));
+        accessor.byId = async (id, options) => runResource(entry, descriptor, baseUrl, apiKey, config.defaultLocale, zodSchemas, modelZodSchemas, options, id);
+        return accessor;
+    };
+    const modelsProxy = new Proxy({}, {
+        get(_target, property) {
+            if (typeof property !== "string")
+                return undefined;
+            if (property === "then")
+                return undefined;
+            const modelEntry = registry.models.get(property) ??
+                registry.modelsCaseInsensitive.get(property.toLowerCase());
+            if (!modelEntry) {
+                unknownKeyError(property, [], modelKeys);
+            }
+            return buildModelAccessor(modelEntry);
         },
     });
+    const rootProxy = new Proxy({}, {
+        get(_target, property) {
+            if (typeof property !== "string")
+                return undefined;
+            if (property === "then")
+                return undefined;
+            if (property === "models")
+                return modelsProxy;
+            const entry = registry.roots.get(property) ??
+                registry.rootsCaseInsensitive.get(property.toLowerCase());
+            if (!entry) {
+                unknownKeyError(property, rootKeys, []);
+            }
+            return async (options) => runResource(entry, descriptor, baseUrl, apiKey, config.defaultLocale, zodSchemas, modelZodSchemas, options);
+        },
+    });
+    return rootProxy;
+}
+/**
+ * Initializes the CMS SDK for a given schema.
+ * @param config configuration including API base URL and API key.
+ * @returns typed accessors for root resources and model resources.
+ */
+export function cms0(config) {
+    return createCmsClient(schemaDescriptor, config);
 }