@growth-labs/cms 0.3.0 → 0.4.0

package/src/engine/content-metadata.ts

@@ -0,0 +1,122 @@
+export type ContentMetadataPrimitive = string | number | boolean | null
+export type ContentMetadataValue =
+	| ContentMetadataPrimitive
+	| ContentMetadataValue[]
+	| { [key: string]: ContentMetadataValue }
+export type ContentMetadata = Record<string, ContentMetadataValue>
+
+export const MAX_CONTENT_METADATA_BYTES = 32 * 1024
+const MAX_CONTENT_METADATA_DEPTH = 8
+const MAX_CONTENT_METADATA_NODES = 1_024
+const UNSAFE_METADATA_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+export class ContentMetadataError extends Error {
+	constructor(
+		readonly code: 'content_metadata_invalid' | 'content_metadata_limit_exceeded',
+		message: string,
+	) {
+		super(message)
+		this.name = 'ContentMetadataError'
+	}
+}
+
+function byteLength(value: string): number {
+	return new TextEncoder().encode(value).byteLength
+}
+
+function assertMetadataValue(value: unknown, depth: number, nodes: { count: number }): void {
+	nodes.count += 1
+	if (nodes.count > MAX_CONTENT_METADATA_NODES) {
+		throw new ContentMetadataError(
+			'content_metadata_limit_exceeded',
+			`content metadata exceeds ${MAX_CONTENT_METADATA_NODES} values`,
+		)
+	}
+	if (depth > MAX_CONTENT_METADATA_DEPTH) {
+		throw new ContentMetadataError(
+			'content_metadata_limit_exceeded',
+			`content metadata exceeds depth ${MAX_CONTENT_METADATA_DEPTH}`,
+		)
+	}
+	if (value === null || typeof value === 'string' || typeof value === 'boolean') return
+	if (typeof value === 'number') {
+		if (!Number.isFinite(value)) {
+			throw new ContentMetadataError(
+				'content_metadata_invalid',
+				'content metadata numbers must be finite',
+			)
+		}
+		return
+	}
+	if (Array.isArray(value)) {
+		for (const item of value) assertMetadataValue(item, depth + 1, nodes)
+		return
+	}
+	if (typeof value !== 'object') {
+		throw new ContentMetadataError(
+			'content_metadata_invalid',
+			'content metadata must contain only JSON values',
+		)
+	}
+	const prototype = Object.getPrototypeOf(value)
+	if (prototype !== Object.prototype && prototype !== null) {
+		throw new ContentMetadataError(
+			'content_metadata_invalid',
+			'content metadata objects must use a plain object prototype',
+		)
+	}
+	for (const [key, child] of Object.entries(value)) {
+		if (!key || UNSAFE_METADATA_KEYS.has(key)) {
+			throw new ContentMetadataError(
+				'content_metadata_invalid',
+				'content metadata contains an unsafe key',
+			)
+		}
+		assertMetadataValue(child, depth + 1, nodes)
+	}
+}
+
+export function serializeContentMetadata(value: ContentMetadata | undefined): string {
+	const metadata = value ?? {}
+	if (typeof metadata !== 'object' || metadata === null || Array.isArray(metadata)) {
+		throw new ContentMetadataError(
+			'content_metadata_invalid',
+			'content metadata must be a JSON object',
+		)
+	}
+	assertMetadataValue(metadata, 0, { count: 0 })
+	const encoded = JSON.stringify(metadata)
+	if (byteLength(encoded) > MAX_CONTENT_METADATA_BYTES) {
+		throw new ContentMetadataError(
+			'content_metadata_limit_exceeded',
+			`content metadata exceeds ${MAX_CONTENT_METADATA_BYTES} bytes`,
+		)
+	}
+	return encoded
+}
+
+export function parseContentMetadata(raw: unknown): ContentMetadata {
+	if (typeof raw !== 'string') {
+		throw new ContentMetadataError(
+			'content_metadata_invalid',
+			'stored content metadata must be JSON text',
+		)
+	}
+	if (byteLength(raw) > MAX_CONTENT_METADATA_BYTES) {
+		throw new ContentMetadataError(
+			'content_metadata_limit_exceeded',
+			`stored content metadata exceeds ${MAX_CONTENT_METADATA_BYTES} bytes`,
+		)
+	}
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(raw)
+	} catch {
+		throw new ContentMetadataError(
+			'content_metadata_invalid',
+			'stored content metadata is not valid JSON',
+		)
+	}
+	serializeContentMetadata(parsed as ContentMetadata)
+	return parsed as ContentMetadata
+}

package/src/engine/index.ts

@@ -39,6 +39,16 @@ export {
 	type VerifyApiKeyResult,
 	verifyCmsApiKey,
 } from './api-keys.js'
+// Bounded site-specific metadata retained in immutable content revisions.
+export {
+	type ContentMetadata,
+	ContentMetadataError,
+	type ContentMetadataPrimitive,
+	type ContentMetadataValue,
+	MAX_CONTENT_METADATA_BYTES,
+	parseContentMetadata,
+	serializeContentMetadata,
+} from './content-metadata.js'
 // content_contributors engine — list/replace co-authors (P3 Task 3).
 export {
 	type ContributorInput,
@@ -121,6 +131,7 @@ export {
 	MAX_PUBLICATION_SURFACE_HOOK_TIMEOUT_MS,
 	type PublicationAttempt,
 	type PublicationAttemptState,
+	PublicationInputError,
 	PublicationNotFoundError,
 	type PublicationOperation,
 	PublicationPointerMoveError,
@@ -150,6 +161,21 @@ export {
 	type PublishGuardOutcome,
 	publishGuardResponseOrNull,
 } from './publish-guard.js'
+// Bounded, pointer-selected public content read model.
+export {
+	getPublishedContentById,
+	getPublishedContentBySlug,
+	type ListPublishedContentOptions,
+	listPublishedContent,
+	MAX_PUBLISHED_CONTENT_PAGE_BYTES,
+	MAX_PUBLISHED_CONTENT_PAGE_SIZE,
+	MAX_PUBLISHED_CONTENT_PAYLOAD_BYTES,
+	type PublishedContent,
+	type PublishedContentCursor,
+	type PublishedContentPage,
+	PublishedContentReadError,
+	type PublishedContentReadErrorCode,
+} from './published-content.js'
 // The publishing engine — content data-access core.
 export {
 	type ArticleInput,