@growth-labs/cms 0.3.1 → 0.4.0

package/src/engine/published-content.ts

@@ -0,0 +1,581 @@
+import type { ContentType } from '../schema/types.js'
+import {
+	type ContentMetadata,
+	ContentMetadataError,
+	parseContentMetadata,
+} from './content-metadata.js'
+import type { D1Database } from './d1.js'
+import type { ContentRevisionPayload } from './revisions.js'
+
+const CONTENT_TYPES = new Set<ContentType>(['article', 'video', 'podcast', 'newsletter', 'page'])
+const CONTENT_STATUSES = new Set(['draft', 'scheduled', 'review', 'published', 'archived'])
+const CONTENT_VISIBILITIES = new Set(['free', 'premium'])
+const LIST_OPTION_KEYS = new Set(['type', 'channel', 'limit', 'cursor'])
+const CURSOR_KEYS = new Set(['publishedAt', 'contentId'])
+
+export const MAX_PUBLISHED_CONTENT_PAGE_SIZE = 100
+export const MAX_PUBLISHED_CONTENT_PAYLOAD_BYTES = 4 * 1024 * 1024
+export const MAX_PUBLISHED_CONTENT_PAGE_BYTES = 4 * 1024 * 1024
+
+export type PublishedContentReadErrorCode =
+	| 'published_content_input_invalid'
+	| 'published_revision_missing'
+	| 'published_revision_mismatch'
+	| 'published_payload_invalid'
+	| 'published_payload_limit_exceeded'
+	| 'published_slug_ambiguous'
+	| 'published_read_failed'
+
+export class PublishedContentReadError extends Error {
+	constructor(
+		readonly code: PublishedContentReadErrorCode,
+		message: string,
+		options?: ErrorOptions,
+	) {
+		super(message, options)
+		this.name = 'PublishedContentReadError'
+	}
+}
+
+export interface PublishedContent {
+	contentId: string
+	revisionId: string
+	slug: string
+	type: ContentType
+	publishedAt: number
+	updatedAt: number
+	payload: ContentRevisionPayload
+	metadata: ContentMetadata
+}
+
+export interface PublishedContentCursor {
+	publishedAt: number
+	contentId: string
+}
+
+export interface ListPublishedContentOptions {
+	type?: ContentType
+	channel?: string
+	limit?: number
+	cursor?: PublishedContentCursor | null
+}
+
+export interface PublishedContentPage {
+	items: PublishedContent[]
+	nextCursor: PublishedContentCursor | null
+}
+
+interface PublishedContentRow {
+	content_id: string
+	pointer_revision_id: string
+	canonical_published_at: number
+	revision_id: string | null
+	revision_content_id: string | null
+	payload_json: string | null
+	payload_bytes: number | null
+}
+
+interface PublishedContentOutlineRow {
+	content_id: string
+	pointer_revision_id: string
+	canonical_published_at: number
+	payload_bytes: number
+}
+
+const SELECT_PUBLISHED_CONTENT = `
+SELECT
+  ci.id AS content_id,
+  ci.published_revision_id AS pointer_revision_id,
+  ci.published_at AS canonical_published_at,
+  cr.id AS revision_id,
+  cr.content_id AS revision_content_id,
+  CASE
+    WHEN length(CAST(cr.payload_json AS BLOB)) <= ${MAX_PUBLISHED_CONTENT_PAYLOAD_BYTES}
+    THEN cr.payload_json
+    ELSE NULL
+  END AS payload_json,
+  length(CAST(cr.payload_json AS BLOB)) AS payload_bytes
+FROM content_items ci
+`
+
+const SELECT_PUBLISHED_CONTENT_OUTLINE = `
+SELECT
+  ci.id AS content_id,
+  ci.published_revision_id AS pointer_revision_id,
+  ci.published_at AS canonical_published_at,
+  length(CAST(cr.payload_json AS BLOB)) AS payload_bytes
+FROM content_items ci
+`
+
+const SELECT_PUBLISHED_CONTENT_BY_SLUG = `
+SELECT
+  ci.id AS content_id,
+  ci.published_revision_id AS pointer_revision_id,
+  ci.published_at AS canonical_published_at,
+  cr.id AS revision_id,
+  cr.content_id AS revision_content_id,
+  CASE
+    WHEN length(CAST(cr.payload_json AS BLOB)) <= ${MAX_PUBLISHED_CONTENT_PAYLOAD_BYTES}
+    THEN cr.payload_json
+    ELSE NULL
+  END AS payload_json,
+  length(CAST(cr.payload_json AS BLOB)) AS payload_bytes
+FROM content_revisions cr INDEXED BY idx_content_revisions_published_slug
+JOIN content_items ci
+  ON ci.published_revision_id = cr.id
+ AND cr.content_id = ci.id
+`
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+	const prototype = Object.getPrototypeOf(value)
+	return prototype === Object.prototype || prototype === null
+}
+
+function byteLength(value: string): number {
+	return new TextEncoder().encode(value).byteLength
+}
+
+function invalidPayload(message: string): never {
+	throw new PublishedContentReadError('published_payload_invalid', message)
+}
+
+function validatePayload(raw: string, row: PublishedContentRow): ContentRevisionPayload {
+	if (byteLength(raw) > MAX_PUBLISHED_CONTENT_PAYLOAD_BYTES) {
+		throw new PublishedContentReadError(
+			'published_payload_limit_exceeded',
+			`published revision payload exceeds ${MAX_PUBLISHED_CONTENT_PAYLOAD_BYTES} bytes`,
+		)
+	}
+
+	let decoded: unknown
+	try {
+		decoded = JSON.parse(raw)
+	} catch {
+		return invalidPayload('published revision payload is not valid JSON')
+	}
+	if (!isPlainRecord(decoded)) return invalidPayload('published revision payload must be an object')
+	if (!isPlainRecord(decoded.item))
+		return invalidPayload('published revision item must be an object')
+	if (decoded.content !== null && !isPlainRecord(decoded.content)) {
+		return invalidPayload('published revision content must be an object or null')
+	}
+	if (!Array.isArray(decoded.tags) || !decoded.tags.every((tag) => typeof tag === 'string')) {
+		return invalidPayload('published revision tags must be strings')
+	}
+	if (
+		decoded.tags.length > 10 ||
+		decoded.tags.some((tag) => tag.length === 0 || tag.length > 256)
+	) {
+		return invalidPayload('published revision tags exceed their canonical bounds')
+	}
+	if (
+		!Array.isArray(decoded.related) ||
+		decoded.related.length > 100 ||
+		!decoded.related.every(
+			(relation) =>
+				isPlainRecord(relation) &&
+				typeof relation.related_id === 'string' &&
+				relation.related_id.length > 0 &&
+				relation.related_id.length <= 256 &&
+				Number.isSafeInteger(relation.rank) &&
+				(relation.rank as number) >= 0 &&
+				(relation.reason === null || typeof relation.reason === 'string'),
+		)
+	) {
+		return invalidPayload('published revision relations are malformed')
+	}
+
+	const item = decoded.item
+	if (item.id !== row.content_id) {
+		throw new PublishedContentReadError(
+			'published_revision_mismatch',
+			'published revision item does not belong to the canonical content item',
+		)
+	}
+	if (typeof item.slug !== 'string' || item.slug.length === 0) {
+		return invalidPayload('published revision slug is invalid')
+	}
+	if (item.slug.length > 512) return invalidPayload('published revision slug is too long')
+	if (typeof item.type !== 'string' || !CONTENT_TYPES.has(item.type as ContentType)) {
+		return invalidPayload('published revision type is invalid')
+	}
+	if (typeof item.title !== 'string' || !item.title.trim() || item.title.length > 1_024) {
+		return invalidPayload('published revision title is invalid')
+	}
+	if (typeof item.status !== 'string' || !CONTENT_STATUSES.has(item.status)) {
+		return invalidPayload('published revision status is invalid')
+	}
+	if (typeof item.visibility !== 'string' || !CONTENT_VISIBILITIES.has(item.visibility)) {
+		return invalidPayload('published revision visibility is invalid')
+	}
+	if (!Number.isSafeInteger(item.updated_at) || (item.updated_at as number) < 0) {
+		return invalidPayload('published revision updated_at is invalid')
+	}
+	if (item.metadata_json !== undefined && typeof item.metadata_json !== 'string') {
+		return invalidPayload('published revision metadata must be JSON text')
+	}
+	const content = decoded.content
+	if (!content) return invalidPayload('published revision content is missing')
+	if (
+		['article', 'newsletter', 'page'].includes(item.type as string) &&
+		typeof content.body_markdown !== 'string'
+	) {
+		return invalidPayload('published revision body Markdown is invalid')
+	}
+	if (item.type === 'video' && typeof content.video_id !== 'string') {
+		return invalidPayload('published revision video ID is invalid')
+	}
+	if (item.type === 'podcast' && typeof content.audio_r2_key !== 'string') {
+		return invalidPayload('published revision podcast audio key is invalid')
+	}
+
+	return decoded as unknown as ContentRevisionPayload
+}
+
+function decodePublishedContent(row: PublishedContentRow): PublishedContent {
+	if (!row.revision_id || !row.revision_content_id || row.payload_bytes === null) {
+		throw new PublishedContentReadError(
+			'published_revision_missing',
+			'canonical publication pointer does not resolve to a revision',
+		)
+	}
+	if (!Number.isSafeInteger(row.payload_bytes) || row.payload_bytes < 1) {
+		throw new PublishedContentReadError(
+			'published_payload_invalid',
+			'published revision payload length is invalid',
+		)
+	}
+	if (row.payload_bytes > MAX_PUBLISHED_CONTENT_PAYLOAD_BYTES) {
+		throw new PublishedContentReadError(
+			'published_payload_limit_exceeded',
+			`published revision payload exceeds ${MAX_PUBLISHED_CONTENT_PAYLOAD_BYTES} bytes`,
+		)
+	}
+	if (row.payload_json === null || byteLength(row.payload_json) !== row.payload_bytes) {
+		throw new PublishedContentReadError(
+			'published_read_failed',
+			'published revision changed during its bounded read',
+		)
+	}
+	if (row.pointer_revision_id !== row.revision_id || row.revision_content_id !== row.content_id) {
+		throw new PublishedContentReadError(
+			'published_revision_mismatch',
+			'canonical publication pointer resolves to a revision owned by another item',
+		)
+	}
+	if (!Number.isSafeInteger(row.canonical_published_at) || row.canonical_published_at < 0) {
+		throw new PublishedContentReadError(
+			'published_payload_invalid',
+			'canonical published_at is invalid',
+		)
+	}
+
+	const payload = validatePayload(row.payload_json, row)
+	const item = payload.item
+	let metadata: ContentMetadata
+	try {
+		metadata = parseContentMetadata(
+			typeof item.metadata_json === 'undefined' ? '{}' : item.metadata_json,
+		)
+	} catch (error) {
+		if (error instanceof ContentMetadataError) {
+			throw new PublishedContentReadError(
+				'published_payload_invalid',
+				`published revision metadata is invalid: ${error.message}`,
+			)
+		}
+		throw error
+	}
+
+	return {
+		contentId: row.content_id,
+		revisionId: row.revision_id,
+		slug: item.slug as string,
+		type: item.type as ContentType,
+		publishedAt: row.canonical_published_at,
+		updatedAt: item.updated_at as number,
+		payload,
+		metadata,
+	}
+}
+
+function assertLookupValue(
+	value: unknown,
+	field: string,
+	maxLength: number,
+): asserts value is string {
+	if (typeof value !== 'string' || !value || value.length > maxLength) {
+		throw new PublishedContentReadError(
+			'published_content_input_invalid',
+			`${field} must be between 1 and ${maxLength} characters`,
+		)
+	}
+}
+
+function wrapReadError(error: unknown): never {
+	if (error instanceof PublishedContentReadError) throw error
+	throw new PublishedContentReadError(
+		'published_read_failed',
+		'published content could not be read safely',
+		{ cause: error },
+	)
+}
+
+export async function getPublishedContentById(
+	db: D1Database,
+	contentId: string,
+): Promise<PublishedContent | null> {
+	assertLookupValue(contentId, 'contentId', 256)
+	try {
+		const row = await db
+			.prepare(
+				`${SELECT_PUBLISHED_CONTENT}
+LEFT JOIN content_revisions cr
+  ON cr.id = ci.published_revision_id
+WHERE ci.id = ?
+  AND ci.status = 'published'
+  AND ci.deleted_at IS NULL
+  AND ci.published_revision_id IS NOT NULL
+  AND ci.published_at IS NOT NULL
+LIMIT 1`,
+			)
+			.bind(contentId)
+			.first<PublishedContentRow>()
+		return row ? decodePublishedContent(row) : null
+	} catch (error) {
+		return wrapReadError(error)
+	}
+}
+
+export async function getPublishedContentBySlug(
+	db: D1Database,
+	slug: string,
+): Promise<PublishedContent | null> {
+	assertLookupValue(slug, 'slug', 512)
+	try {
+		const result = await db
+			.prepare(
+				`${SELECT_PUBLISHED_CONTENT_BY_SLUG}
+WHERE ci.status = 'published'
+  AND ci.deleted_at IS NULL
+  AND ci.published_revision_id IS NOT NULL
+  AND ci.published_at IS NOT NULL
+  AND json_extract(cr.payload_json, '$.item.slug') = ?
+ORDER BY ci.id DESC
+LIMIT 2`,
+			)
+			.bind(slug)
+			.all<PublishedContentRow>()
+		const rows = result.results ?? []
+		if (rows.length === 0) return null
+		if (rows.length > 1) {
+			throw new PublishedContentReadError(
+				'published_slug_ambiguous',
+				'published slug resolves to more than one canonical content item',
+			)
+		}
+		return decodePublishedContent(rows[0] as PublishedContentRow)
+	} catch (error) {
+		return wrapReadError(error)
+	}
+}
+
+function normalizeListOptions(options: unknown): {
+	limit: number
+	type?: ContentType
+	channel?: string
+	cursor?: PublishedContentCursor
+} {
+	if (!isPlainRecord(options)) {
+		throw new PublishedContentReadError(
+			'published_content_input_invalid',
+			'published content options must be an object',
+		)
+	}
+	if (Object.keys(options).some((key) => !LIST_OPTION_KEYS.has(key))) {
+		throw new PublishedContentReadError(
+			'published_content_input_invalid',
+			'published content options contain an unsupported field',
+		)
+	}
+	const limit = options.limit ?? 20
+	if (
+		typeof limit !== 'number' ||
+		!Number.isSafeInteger(limit) ||
+		limit < 1 ||
+		limit > MAX_PUBLISHED_CONTENT_PAGE_SIZE
+	) {
+		throw new PublishedContentReadError(
+			'published_content_input_invalid',
+			`limit must be between 1 and ${MAX_PUBLISHED_CONTENT_PAGE_SIZE}`,
+		)
+	}
+	let type: ContentType | undefined
+	if (options.type !== undefined) {
+		if (typeof options.type !== 'string' || !CONTENT_TYPES.has(options.type as ContentType)) {
+			throw new PublishedContentReadError(
+				'published_content_input_invalid',
+				'unknown published content type',
+			)
+		}
+		type = options.type as ContentType
+	}
+	let channel: string | undefined
+	if (options.channel !== undefined) {
+		assertLookupValue(options.channel, 'channel', 128)
+		channel = options.channel
+	}
+	let cursor: PublishedContentCursor | undefined
+	if (options.cursor !== undefined && options.cursor !== null) {
+		if (
+			!isPlainRecord(options.cursor) ||
+			Object.keys(options.cursor).some((key) => !CURSOR_KEYS.has(key))
+		) {
+			throw new PublishedContentReadError(
+				'published_content_input_invalid',
+				'published content cursor is malformed',
+			)
+		}
+		if (
+			typeof options.cursor.publishedAt !== 'number' ||
+			!Number.isSafeInteger(options.cursor.publishedAt) ||
+			options.cursor.publishedAt < 0
+		) {
+			throw new PublishedContentReadError(
+				'published_content_input_invalid',
+				'cursor publishedAt must be a non-negative integer',
+			)
+		}
+		assertLookupValue(options.cursor.contentId, 'cursor contentId', 256)
+		cursor = {
+			publishedAt: options.cursor.publishedAt,
+			contentId: options.cursor.contentId,
+		}
+	}
+	return {
+		limit,
+		type,
+		channel,
+		cursor,
+	}
+}
+
+export async function listPublishedContent(
+	db: D1Database,
+	options: ListPublishedContentOptions = {},
+): Promise<PublishedContentPage> {
+	const normalized = normalizeListOptions(options)
+	const predicates = [
+		"ci.status = 'published'",
+		'ci.deleted_at IS NULL',
+		'ci.published_revision_id IS NOT NULL',
+		'ci.published_at IS NOT NULL',
+	]
+	const values: unknown[] = []
+	if (normalized.type) {
+		predicates.push("json_extract(cr.payload_json, '$.item.type') = ?")
+		values.push(normalized.type)
+	}
+	if (normalized.channel) {
+		predicates.push("json_extract(cr.payload_json, '$.item.channel') = ?")
+		values.push(normalized.channel)
+	}
+	if (normalized.cursor) {
+		predicates.push('(ci.published_at < ? OR (ci.published_at = ? AND ci.id < ?))')
+		values.push(
+			normalized.cursor.publishedAt,
+			normalized.cursor.publishedAt,
+			normalized.cursor.contentId,
+		)
+	}
+	try {
+		const outlineResult = await db
+			.prepare(
+				`${SELECT_PUBLISHED_CONTENT_OUTLINE}
+JOIN content_revisions cr ON cr.id = ci.published_revision_id
+WHERE ${predicates.join('\n  AND ')}
+ORDER BY ci.published_at DESC, ci.id DESC
+LIMIT ?`,
+			)
+			.bind(...values, normalized.limit + 1)
+			.all<PublishedContentOutlineRow>()
+		const outlines = outlineResult.results ?? []
+		const selected: PublishedContentOutlineRow[] = []
+		let selectedBytes = 0
+		for (const outline of outlines.slice(0, normalized.limit)) {
+			if (
+				typeof outline.content_id !== 'string' ||
+				typeof outline.pointer_revision_id !== 'string' ||
+				!Number.isSafeInteger(outline.canonical_published_at) ||
+				outline.canonical_published_at < 0 ||
+				!Number.isSafeInteger(outline.payload_bytes) ||
+				outline.payload_bytes < 1
+			) {
+				throw new PublishedContentReadError(
+					'published_payload_invalid',
+					'published revision outline is malformed',
+				)
+			}
+			if (outline.payload_bytes > MAX_PUBLISHED_CONTENT_PAYLOAD_BYTES) {
+				throw new PublishedContentReadError(
+					'published_payload_limit_exceeded',
+					`published revision payload exceeds ${MAX_PUBLISHED_CONTENT_PAYLOAD_BYTES} bytes`,
+				)
+			}
+			if (
+				selected.length > 0 &&
+				selectedBytes + outline.payload_bytes > MAX_PUBLISHED_CONTENT_PAGE_BYTES
+			) {
+				break
+			}
+			selected.push(outline)
+			selectedBytes += outline.payload_bytes
+		}
+		if (selected.length === 0) return { items: [], nextCursor: null }
+
+		const selectedPredicates = selected.map(() => '(ci.id = ? AND ci.published_revision_id = ?)')
+		const selectedValues = selected.flatMap((outline) => [
+			outline.content_id,
+			outline.pointer_revision_id,
+		])
+		const result = await db
+			.prepare(
+				`${SELECT_PUBLISHED_CONTENT}
+JOIN content_revisions cr ON cr.id = ci.published_revision_id
+WHERE ci.status = 'published'
+  AND ci.deleted_at IS NULL
+  AND (${selectedPredicates.join(' OR ')})`,
+			)
+			.bind(...selectedValues)
+			.all<PublishedContentRow>()
+		const rows = result.results ?? []
+		const rowsByPointer = new Map(
+			rows.map((row) => [`${row.content_id}\0${row.pointer_revision_id}`, row]),
+		)
+		const items = selected.map((outline) => {
+			const row = rowsByPointer.get(`${outline.content_id}\0${outline.pointer_revision_id}`)
+			if (
+				!row ||
+				row.canonical_published_at !== outline.canonical_published_at ||
+				row.payload_json === null ||
+				byteLength(row.payload_json) !== outline.payload_bytes
+			) {
+				throw new PublishedContentReadError(
+					'published_read_failed',
+					'published revision changed during its bounded read',
+				)
+			}
+			return decodePublishedContent(row)
+		})
+		const hasMore = outlines.length > selected.length
+		const last = items.at(-1)
+		return {
+			items,
+			nextCursor:
+				hasMore && last ? { publishedAt: last.publishedAt, contentId: last.contentId } : null,
+		}
+	} catch (error) {
+		return wrapReadError(error)
+	}
+}