@beechcms/core 0.6.0-preview.4 → 0.6.0

package/dist/engine/validation/index.d.ts

@@ -0,0 +1,115 @@
+import type { Seed } from '../types.js';
+import type { IIdGenerator } from '../../common/id-generator.js';
+export { resolveFileOptions } from './file-branch.js';
+/**
+ * @module Engine/Validation
+ *
+ * Provides schema-driven validation and sanitization utilities for seed payloads
+ * within BeechCMS. This module handles type checks, required fields, text limits,
+ * rich text sanitization, relational key checks, and format constraints using Zod schemas.
+ */
+/**
+ * Represents a single validation error detail returned when a seed payload field fails validation.
+ */
+export interface ValidationDetail {
+    /** The name of the alias or field that failed validation. */
+    field: string;
+    /** The expected type, format, or constraint (e.g., `'string'`, `'number(min:1)'`, `'required-field'`). */
+    expected: string;
+    /** The type or status of the value actually received (e.g., `'null'`, `'array'`, `'missing'`). */
+    received: string;
+    /** A human-readable error message explaining why validation failed. */
+    message: string;
+}
+/**
+ * Options to configure the validation and sanitization behavior of the seed payload.
+ */
+export interface ValidateSeedPayloadOptions {
+    /**
+     * Whether to allow fields to be explicitly `null`.
+     * @default false
+     */
+    allowNull?: boolean;
+    /**
+     * The type of operation being validated, which determines whether `requiredOnCreate`
+     * or `requiredOnUpdate` branch constraints are applied.
+     * @default 'create'
+     */
+    operation?: 'create' | 'update';
+    /**
+     * If true, validation will fail if the resulting data payload contains no valid fields.
+     * @default true
+     */
+    requireAtLeastOneValidField?: boolean;
+    /**
+     * Whether to enforce validation of required fields (`requiredOnCreate` or `requiredOnUpdate`).
+     * @default true
+     */
+    enforceRequiredFields?: boolean;
+    /**
+     * The maximum allowed length (in characters/bytes) for text and rich text fields.
+     * @default 50000
+     */
+    maxTextLength?: number;
+    /**
+     * Required when the seed has branches of type `'relation'`.
+     * Must be the same `IIdGenerator` instance used for id generation so that
+     * swapping implementations (e.g. ULIDs) automatically updates validation.
+     * Do NOT pass a concrete class — inject via the middleware / factory.
+     */
+    idGenerator?: IIdGenerator;
+}
+/**
+ * The structured result returned by the seed payload validation process.
+ */
+export interface ValidateSeedPayloadResult {
+    /**
+     * The successfully validated and sanitized fields.
+     * Only contains valid fields that matched the seed branches.
+     */
+    data: Record<string, unknown>;
+    /** Detailed information about all validation errors or unrecognized fields. */
+    details: ValidationDetail[];
+    /** List of field aliases that were present in the payload but are not defined in the seed. */
+    unknownAliases: string[];
+    /** List of fields containing potentially dangerous rich text content (e.g. XSS vectors). */
+    dangerousFields: string[];
+    /** List of required fields that were missing or effectively empty. */
+    requiredFieldsMissing: string[];
+    /** Flag indicating if the validated data payload contains at least one valid field. */
+    hasAnyValidField: boolean;
+}
+/**
+ * Internal representation of fully resolved validation options with default values applied.
+ */
+export type ResolvedOptions = {
+    allowNull: boolean;
+    operation: 'create' | 'update';
+    requireAtLeastOneValidField: boolean;
+    enforceRequiredFields: boolean;
+    maxTextLength: number;
+    idGenerator: IIdGenerator | undefined;
+};
+/** Set of valid content status values. */
+declare const STATUS_VALUES: readonly ['draft', 'review', 'published'];
+/**
+ * Validates and sanitizes a seed payload against its schema definition.
+ *
+ * This is the public entry point for seed payload validation. It strips unknown
+ * aliases, coerces types, checks required fields on create/update, checks limits,
+ * and performs rich text XSS checks without throwing exceptions.
+ *
+ * @param seed - The seed definition containing field/branch definitions.
+ * @param payload - The raw payload values to validate and sanitize.
+ * @param options - Validation settings to override defaults.
+ * @returns A structured validation result containing parsed data, details of any issues, and flags.
+ */
+export declare function validateAndSanitizeSeedPayload(seed: Seed, payload: Record<string, unknown>, options?: ValidateSeedPayloadOptions): ValidateSeedPayloadResult;
+/**
+ * Type-guard validating if a value is a valid content status ('draft', 'review', or 'published').
+ *
+ * @param value - The value to check.
+ * @returns True if the value is a valid content status, false otherwise.
+ */
+export declare function isValidContentStatus(value: unknown): value is (typeof STATUS_VALUES)[number];
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/validation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAOhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAErD;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb,0GAA0G;IAC1G,QAAQ,EAAE,MAAM,CAAA;IAChB,kGAAkG;IAClG,QAAQ,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC/B;;;OAGG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAA;IACrC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,YAAY,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,+EAA+E;IAC/E,OAAO,EAAE,gBAAgB,EAAE,CAAA;IAC3B,8FAA8F;IAC9F,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,4FAA4F;IAC5F,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,sEAAsE;IACtE,qBAAqB,EAAE,MAAM,EAAE,CAAA;IAC/B,uFAAuF;IACvF,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,OAAO,CAAA;IAClB,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC9B,2BAA2B,EAAE,OAAO,CAAA;IACpC,qBAAqB,EAAE,OAAO,CAAA;IAC9B,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,YAAY,GAAG,SAAS,CAAA;CACtC,CAAA;AAKD,0CAA0C;AAC1C,QAAA,MAAM,aAAa,YAAI,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAU,CAAA;AAkR/D;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,GAAE,0BAA+B,GACvC,yBAAyB,CAqD3B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAE5F"}

package/dist/engine/validation/index.js

@@ -0,0 +1,333 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { z } from 'zod';
+import { isRichtextEnvelopeV1 } from '../../content/richtext/richtext.js';
+import { cleanString, isPlainObject } from './primitives.js';
+import { isRichtextDocEmpty } from './richtext-sanitizer.js';
+import { compileSeedSchema } from './cache.js';
+// Re-export the public file-branch symbol so the barrel surface stays complete.
+export { resolveFileOptions } from './file-branch.js';
+/** Default maximum character length allowed for text and rich text branches. */
+const DEFAULT_MAX_TEXT_LENGTH = 50_000;
+/** Set of valid content status values. */
+const STATUS_VALUES = ['draft', 'review', 'published'];
+/** Zod schema for content status enum validation. */
+const statusSchema = z.enum(STATUS_VALUES);
+/**
+ * Checks if a value is effectively empty (e.g. null, undefined, empty string, empty array, or empty rich text).
+ *
+ * @param value - The value to check.
+ * @returns True if effectively empty, false otherwise.
+ */
+function isEffectivelyEmpty(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === 'string')
+        return cleanString(value).length === 0;
+    if (Array.isArray(value))
+        return value.length === 0;
+    if (isPlainObject(value)) {
+        if (isRichtextEnvelopeV1(value))
+            return isRichtextDocEmpty(value.doc);
+        if (isRichtextDocEmpty(value))
+            return true;
+        return Object.keys(value).length === 0;
+    }
+    return false;
+}
+/**
+ * Detects missing or empty required fields based on whether the operation is create or update.
+ *
+ * @param seed - The seed definition.
+ * @param rawPayload - Raw inputs provided to validation.
+ * @param filtered - Payload with unknown aliases stripped.
+ * @param parsedData - Parsed and validated data fields.
+ * @param parseSucceeded - Whether Zod parsing succeeded.
+ * @param options - The resolved validation options.
+ * @returns An object containing lists of missing fields and structured validation details.
+ */
+function detectMissingRequired(seed, rawPayload, filtered, parsedData, parseSucceeded, options) {
+    const missing = [];
+    const details = [];
+    const op = options.operation;
+    for (const branch of seed.branches) {
+        const isRequired = op === 'create' ? branch.requiredOnCreate : branch.requiredOnUpdate;
+        if (!isRequired)
+            continue;
+        if (!Object.hasOwn(rawPayload, branch.alias)) {
+            missing.push(branch.alias);
+            details.push({
+                field: branch.alias,
+                expected: 'required-field',
+                received: 'missing',
+                message: `Field '${branch.alias}' is required for ${op}`,
+            });
+            continue;
+        }
+        const candidate = parseSucceeded ? parsedData[branch.alias] : filtered[branch.alias];
+        if (isEffectivelyEmpty(candidate)) {
+            missing.push(branch.alias);
+            details.push({
+                field: branch.alias,
+                expected: 'required-field',
+                received: 'empty',
+                message: `Field '${branch.alias}' cannot be empty for ${op}`,
+            });
+        }
+    }
+    return { missing, details };
+}
+/**
+ * Returns a string representing the runtime type of a value for error reporting.
+ *
+ * @param value - The value to describe.
+ * @returns A string description of the value type (e.g. 'null', 'array', 'string').
+ */
+function describeReceivedType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/**
+ * Builds a dotted/bracketed field path from a Zod issue path (e.g. 'items[0].name').
+ *
+ * @param path - Zod issue path segments.
+ * @returns The full field path as a string, or 'payload' if the path is empty.
+ */
+function buildFieldPath(path) {
+    if (path.length === 0)
+        return 'payload';
+    return path.reduce((result, segment, index) => {
+        if (index === 0)
+            return String(segment);
+        return typeof segment === 'number' ? `${result}[${segment}]` : `${result}.${String(segment)}`;
+    }, '');
+}
+/**
+ * Navigates a payload object by a Zod issue path to find the actual value that failed validation.
+ *
+ * @param filtered - Payload with unknown aliases stripped.
+ * @param path - Zod issue path segments.
+ * @returns The value found at the path, or undefined if unreachable.
+ */
+function resolveByPath(filtered, path) {
+    let current = filtered;
+    for (const segment of path) {
+        if (current === null || current === undefined)
+            return current;
+        if (typeof segment === 'number') {
+            if (!Array.isArray(current))
+                return undefined;
+            current = current[segment];
+        }
+        else {
+            if (typeof current !== 'object')
+                return undefined;
+            current = current[segment];
+        }
+    }
+    return current;
+}
+/**
+ * Formats expected error messages based on validation failure details.
+ *
+ * Zod v4 native `invalid_type` issues carry the expected type on `issue.expected`
+ * directly. Custom `.refine`/`ctx.addIssue` checks in this codebase still encode
+ * it as an `"Expected <type>"` message prefix, so that convention is kept as a fallback.
+ *
+ * @param issue - The Zod issue to derive the expected type from.
+ * @returns The expected type format string.
+ */
+function expectedFromIssue(issue) {
+    if (issue.code === 'invalid_type')
+        return issue.expected;
+    const message = issue.message;
+    if (typeof message !== 'string')
+        return 'valid-field-value';
+    return message.startsWith('Expected ') ? message.slice('Expected '.length) : 'valid-field-value';
+}
+/**
+ * Separates known fields (present in seed definition) from unknown fields in a raw payload.
+ *
+ * @param seed - The seed definition.
+ * @param payload - The raw payload.
+ * @returns An object with filtered payload, array of unknown keys, and detail issues.
+ */
+function splitUnknownAliases(seed, payload) {
+    const knownAliases = new Set(seed.branches.map((branch) => branch.alias));
+    const filtered = {};
+    const unknown = [];
+    const details = [];
+    for (const alias of Object.keys(payload)) {
+        if (knownAliases.has(alias)) {
+            filtered[alias] = payload[alias];
+            continue;
+        }
+        unknown.push(alias);
+        details.push({
+            field: alias,
+            expected: 'known-seed-alias',
+            received: 'unknown-alias',
+            message: `Field '${alias}' is not defined in seed '${seed.slug}'`,
+        });
+    }
+    return { filtered, unknown, details };
+}
+/**
+ * Recursively flattens Zod union validation issues to report underlying errors.
+ *
+ * @param issues - Raw Zod issues.
+ * @param parentPath - Path context for nested structures.
+ * @returns Flattened array of Zod issues.
+ */
+function flattenZodIssues(issues, parentPath = []) {
+    const result = [];
+    for (const issue of issues) {
+        const issuePath = issue.path;
+        const currentPath = [...parentPath, ...issuePath];
+        if (issue.code === 'invalid_union' && 'errors' in issue) {
+            const unionErrors = issue.errors;
+            for (const subIssues of unionErrors) {
+                result.push(...flattenZodIssues(subIssues, currentPath));
+            }
+        }
+        else {
+            result.push({
+                ...issue,
+                path: currentPath,
+            });
+        }
+    }
+    return result;
+}
+/**
+ * Map Zod issues into structured ValidationDetail objects, identifying dangerous or unknown fields.
+ *
+ * @param seed - The seed definition.
+ * @param issues - Raw Zod issues.
+ * @param filtered - Payload with unknown aliases stripped.
+ * @param options - The resolved validation options.
+ * @returns Structured details, unknown lists, and dangerous lists.
+ */
+function processZodIssues(seed, issues, filtered, options) {
+    const details = [];
+    const unknown = [];
+    const dangerous = [];
+    const flatIssues = flattenZodIssues(issues);
+    for (const issue of flatIssues) {
+        if (issue.code === 'unrecognized_keys') {
+            for (const alias of issue.keys) {
+                unknown.push(alias);
+                details.push({
+                    field: alias,
+                    expected: 'known-seed-alias',
+                    received: 'unknown-alias',
+                    message: `Field '${alias}' is not defined in seed '${seed.slug}'`,
+                });
+            }
+            continue;
+        }
+        const issuePath = issue.path;
+        // detectMissingRequired() already reports top-level required-and-missing branches;
+        // skip the redundant native invalid_type/undefined issue Zod v4 raises for the same field.
+        if (issue.code === 'invalid_type' &&
+            options.enforceRequiredFields &&
+            issuePath.length === 1 &&
+            resolveByPath(filtered, issuePath) === undefined) {
+            continue;
+        }
+        const field = buildFieldPath(issuePath);
+        const params = issue.params;
+        if (params?.dangerous === true) {
+            dangerous.push(field);
+        }
+        const expected = expectedFromIssue(issue);
+        const received = describeReceivedType(resolveByPath(filtered, issuePath));
+        let message = `Field '${field}' expects type '${expected}' but received '${received}'`;
+        if (received === 'string' && typeof issue.message === 'string' && issue.message.startsWith('Expected ')) {
+            if (expected.includes('url') || expected.includes('string') || expected.includes('date') || expected.includes('file')) {
+                message = `Field '${field}' has invalid format. Expected '${expected}' but received a non-matching string.`;
+            }
+        }
+        details.push({
+            field,
+            expected,
+            received,
+            message,
+        });
+    }
+    return { details, unknown, dangerous };
+}
+/**
+ * Validates and sanitizes a seed payload against its schema definition.
+ *
+ * This is the public entry point for seed payload validation. It strips unknown
+ * aliases, coerces types, checks required fields on create/update, checks limits,
+ * and performs rich text XSS checks without throwing exceptions.
+ *
+ * @param seed - The seed definition containing field/branch definitions.
+ * @param payload - The raw payload values to validate and sanitize.
+ * @param options - Validation settings to override defaults.
+ * @returns A structured validation result containing parsed data, details of any issues, and flags.
+ */
+export function validateAndSanitizeSeedPayload(seed, payload, options = {}) {
+    const resolved = {
+        allowNull: options.allowNull ?? false,
+        operation: options.operation ?? 'create',
+        requireAtLeastOneValidField: options.requireAtLeastOneValidField ?? true,
+        enforceRequiredFields: options.enforceRequiredFields ?? true,
+        maxTextLength: options.maxTextLength ?? DEFAULT_MAX_TEXT_LENGTH,
+        idGenerator: options.idGenerator,
+    };
+    const { filtered, unknown: preUnknown, details: preDetails } = splitUnknownAliases(seed, payload);
+    const schema = compileSeedSchema(seed, resolved);
+    const parsed = schema.safeParse(filtered);
+    const accumulatedDetails = [...preDetails];
+    const unknownAliases = new Set(preUnknown);
+    const dangerousFields = new Set();
+    let data = {};
+    if (parsed.success) {
+        data = { ...parsed.data };
+    }
+    else {
+        const zodOutcome = processZodIssues(seed, parsed.error.issues, filtered, resolved);
+        accumulatedDetails.push(...zodOutcome.details);
+        for (const alias of zodOutcome.unknown)
+            unknownAliases.add(alias);
+        for (const field of zodOutcome.dangerous)
+            dangerousFields.add(field);
+    }
+    let requiredFieldsMissing = [];
+    if (resolved.enforceRequiredFields) {
+        const requiredOutcome = detectMissingRequired(seed, payload, filtered, data, parsed.success, resolved);
+        requiredFieldsMissing = requiredOutcome.missing;
+        accumulatedDetails.push(...requiredOutcome.details);
+    }
+    if (resolved.requireAtLeastOneValidField && Object.keys(data).length === 0) {
+        accumulatedDetails.push({
+            field: 'data',
+            expected: 'at-least-one-valid-field',
+            received: 'empty',
+            message: 'Payload does not contain any valid fields for this operation',
+        });
+    }
+    return {
+        data,
+        details: accumulatedDetails,
+        unknownAliases: [...unknownAliases],
+        dangerousFields: [...dangerousFields],
+        requiredFieldsMissing,
+        hasAnyValidField: Object.keys(data).length > 0,
+    };
+}
+/**
+ * Type-guard validating if a value is a valid content status ('draft', 'review', or 'published').
+ *
+ * @param value - The value to check.
+ * @returns True if the value is a valid content status, false otherwise.
+ */
+export function isValidContentStatus(value) {
+    return statusSchema.safeParse(value).success;
+}

package/dist/engine/validation/primitives.d.ts

@@ -0,0 +1,33 @@
+/** Matches standard control characters that should be stripped. */
+export declare const CONTROL_CHARS_REGEX: RegExp;
+/**
+ * Strips non-printable and dangerous control characters from a string.
+ *
+ * @param input - The string to clean.
+ * @returns The cleaned string.
+ */
+export declare function stripControlChars(input: string): string;
+/**
+ * Cleans a string by stripping control characters and trimming leading/trailing whitespace.
+ *
+ * @param input - The string to clean.
+ * @returns The cleaned and trimmed string.
+ */
+export declare function cleanString(input: string): string;
+/**
+ * Type-guard checking if a value is a plain object (excluding arrays and null).
+ *
+ * @param input - The value to check.
+ * @returns True if the value is a plain object, false otherwise.
+ */
+export declare function isPlainObject(input: unknown): input is Record<string, unknown>;
+/**
+ * Measures the real UTF-8 byte length of a string, not UTF-16 code units.
+ * `.length` undercounts multi-byte chars (CJK, emoji) by up to 4x, which matters
+ * for size limits meant to bound storage (D1/SQLite is byte-addressed).
+ *
+ * @param input - The string to measure.
+ * @returns The UTF-8 byte length.
+ */
+export declare function byteLength(input: string): number;
+//# sourceMappingURL=primitives.d.ts.map

package/dist/engine/validation/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/primitives.ts"],"names":[],"mappings":"AAGA,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,QAAoD,CAAA;AAEpF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAID;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/engine/validation/primitives.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/** Matches standard control characters that should be stripped. */
+export const CONTROL_CHARS_REGEX = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g;
+/**
+ * Strips non-printable and dangerous control characters from a string.
+ *
+ * @param input - The string to clean.
+ * @returns The cleaned string.
+ */
+export function stripControlChars(input) {
+    return input.replaceAll(CONTROL_CHARS_REGEX, '');
+}
+/**
+ * Cleans a string by stripping control characters and trimming leading/trailing whitespace.
+ *
+ * @param input - The string to clean.
+ * @returns The cleaned and trimmed string.
+ */
+export function cleanString(input) {
+    return stripControlChars(input).trim();
+}
+/**
+ * Type-guard checking if a value is a plain object (excluding arrays and null).
+ *
+ * @param input - The value to check.
+ * @returns True if the value is a plain object, false otherwise.
+ */
+export function isPlainObject(input) {
+    return typeof input === 'object' && input !== null && !Array.isArray(input);
+}
+const byteLengthEncoder = new TextEncoder();
+/**
+ * Measures the real UTF-8 byte length of a string, not UTF-16 code units.
+ * `.length` undercounts multi-byte chars (CJK, emoji) by up to 4x, which matters
+ * for size limits meant to bound storage (D1/SQLite is byte-addressed).
+ *
+ * @param input - The string to measure.
+ * @returns The UTF-8 byte length.
+ */
+export function byteLength(input) {
+    return byteLengthEncoder.encode(input).length;
+}

package/dist/engine/validation/richtext-sanitizer.d.ts

@@ -0,0 +1,30 @@
+/** Result structure of the rich text sanitization function. */
+interface RichtextSanitizeResult {
+    /** The sanitized string or JSON object. */
+    value: unknown;
+    /** Flag indicating if any dangerous content was detected. */
+    dangerous: boolean;
+    /** Flag indicating if the overall structure is valid rich text. */
+    valid: boolean;
+    /** The size of the sanitized result. */
+    size: number;
+    oversize?: boolean;
+}
+/**
+ * Main entrance helper to sanitize rich text, handling both v1 envelope formats and raw JSON payloads.
+ * String-form input is rejected (JSON-only). Byte size is fail-fast checked before the sanitizing walk.
+ *
+ * @param raw - The raw rich text input.
+ * @param maxBytes - Maximum allowed serialized size, checked before the walk.
+ * @returns The sanitization result.
+ */
+export declare function sanitizeRichtext(raw: unknown, maxBytes: number): RichtextSanitizeResult;
+/**
+ * Checks if a rich text document is effectively empty (contains no text or LaTeX blocks).
+ *
+ * @param value - The rich text document structure.
+ * @returns True if empty, false otherwise.
+ */
+export declare function isRichtextDocEmpty(value: unknown): boolean;
+export {};
+//# sourceMappingURL=richtext-sanitizer.d.ts.map

package/dist/engine/validation/richtext-sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"richtext-sanitizer.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/richtext-sanitizer.ts"],"names":[],"mappings":"AA0BA,+DAA+D;AAC/D,UAAU,sBAAsB;IAC9B,2CAA2C;IAC3C,KAAK,EAAE,OAAO,CAAA;IACd,6DAA6D;IAC7D,SAAS,EAAE,OAAO,CAAA;IAClB,mEAAmE;IACnE,KAAK,EAAE,OAAO,CAAA;IACd,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAsGD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAgCvF;AAyBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAS1D"}