@growth-labs/cms 0.3.0 → 0.4.0

package/src/engine/publication.ts

@@ -2,7 +2,14 @@ import type {
 	ContentPublicationAttemptRow,
 	ContentPublicationAttemptState,
 	ContentType,
+	ContentVisibility,
 } from '../schema/types.js'
+import {
+	type ContentMetadata,
+	ContentMetadataError,
+	MAX_CONTENT_METADATA_BYTES,
+	serializeContentMetadata,
+} from './content-metadata.js'
 import type { D1Database, D1Result } from './d1.js'
 import { evaluateArticleBody } from './publish-guard.js'
 import {
@@ -65,6 +72,8 @@ export interface PublicationReconciler {
 export interface PublishOneInput {
 	contentId: string
 	now?: number
+	/** Explicit historical publication time for a staged archive item. */
+	publishedAt?: number
 	createdBy?: string | null
 	surfaces?: PublicationReconciler[]
 	allowNoSurfaces?: boolean
@@ -134,6 +143,7 @@ export interface PublicationAttempt {
 	contentId: string
 	revisionId: string
 	previousRevisionId: string | null
+	targetPublishedAt: number | null
 	state: PublicationAttemptState
 	surfaceNames: string[]
 	pendingSurfaceNames: string[]
@@ -229,14 +239,32 @@ export interface ContentArchiveInput {
 }
 
 export interface ContentArchiveItem {
+	sourceId?: string
 	type?: ContentType
 	slug?: string
 	title?: string
+	seoTitle?: string | null
+	description?: string | null
 	excerpt?: string | null
+	byline?: string | null
 	primaryCategory?: string | null
 	primaryTopic?: string | null
+	featured?: boolean
+	visibility?: ContentVisibility
+	authorId?: string | null
+	heroImageId?: string | null
+	heroImageAlt?: string | null
+	heroImageCaption?: string | null
+	socialImageId?: string | null
+	canonicalUrl?: string | null
 	tags?: string[]
 	bodyMarkdown?: string
+	bodyHtml?: string | null
+	metadata?: ContentMetadata
+	publishedAt?: number | null
+	createdAt?: number | null
+	updatedAt?: number | null
+	publishTz?: string | null
 }
 
 export interface ImportContentArchiveOptions {
@@ -253,6 +281,7 @@ export interface ImportedArchiveItem {
 	id: string
 	slug: string
 	type: 'article' | 'newsletter' | 'page'
+	sourceId?: string
 }
 
 export interface SkippedArchiveItem {
@@ -261,6 +290,7 @@ export interface SkippedArchiveItem {
 	title: string | null
 	slug?: string | null
 	existingId?: string | null
+	sourceId?: string
 }
 
 export interface ImportContentArchiveResult {
@@ -292,10 +322,37 @@ export class ContentArchiveImportLimitError extends Error {
 	}
 }
 
+export class PublicationInputError extends Error {
+	constructor(
+		readonly code: 'published_at_invalid',
+		message: string,
+	) {
+		super(message)
+		this.name = 'PublicationInputError'
+	}
+}
+
 function nowSeconds(): number {
 	return Math.floor(Date.now() / 1000)
 }
 
+function normalizePublishedAt(value: number | undefined, now: number): number {
+	const publishedAt = value ?? now
+	if (
+		!Number.isSafeInteger(now) ||
+		now < 0 ||
+		!Number.isSafeInteger(publishedAt) ||
+		publishedAt < 0 ||
+		publishedAt > now
+	) {
+		throw new PublicationInputError(
+			'published_at_invalid',
+			'publishedAt must be a non-negative epoch second no later than now',
+		)
+	}
+	return publishedAt
+}
+
 export const DEFAULT_PUBLICATION_SURFACE_HOOK_TIMEOUT_MS = 10_000
 export const MAX_PUBLICATION_SURFACE_HOOK_TIMEOUT_MS = 30_000
 export const DEFAULT_PENDING_PUBLICATION_ATTEMPT_LIMIT = 100
@@ -450,6 +507,7 @@ function decodeAttempt(row: ContentPublicationAttemptRow): PublicationAttempt {
 		contentId: row.content_id,
 		revisionId: row.revision_id,
 		previousRevisionId: row.previous_revision_id,
+		targetPublishedAt: row.target_published_at,
 		state: row.state,
 		surfaceNames: parseStringArray(row.surface_names_json, 'surface_names_json'),
 		pendingSurfaceNames: parseStringArray(
@@ -489,6 +547,7 @@ function decodeAttemptForEnumeration(row: ContentPublicationAttemptRow): Publica
 			contentId: row.content_id,
 			revisionId: row.revision_id,
 			previousRevisionId: row.previous_revision_id,
+			targetPublishedAt: row.target_published_at,
 			state: row.state,
 			surfaceNames: recoverStringArray(row.surface_names_json),
 			pendingSurfaceNames: recoverStringArray(row.pending_surface_names_json),
@@ -510,7 +569,8 @@ async function getPublicationAttempt(
 ): Promise<PublicationAttempt> {
 	const row = await db
 		.prepare(
-			`SELECT id, operation, content_id, revision_id, previous_revision_id, state,
+			`SELECT id, operation, content_id, revision_id, previous_revision_id,
+			        target_published_at, state,
 			        surface_names_json, pending_surface_names_json,
 			        prepared_surface_names_json, receipts_json, version,
 			        package_version, last_error, created_at, updated_at
@@ -548,7 +608,8 @@ export async function listPendingPublicationAttempts(
 	const cursorClause = cursor ? 'AND (updated_at > ? OR (updated_at = ? AND id > ?))' : ''
 	const result = await db
 		.prepare(
-			`SELECT id, operation, content_id, revision_id, previous_revision_id, state,
+			`SELECT id, operation, content_id, revision_id, previous_revision_id,
+			        target_published_at, state,
 			        CASE WHEN length(CAST(surface_names_json AS BLOB)) <= ${MAX_PUBLICATION_ATTEMPT_JSON_BYTES}
 			             THEN surface_names_json ELSE 'null' END AS surface_names_json,
 			        CASE WHEN length(CAST(pending_surface_names_json AS BLOB)) <= ${MAX_PUBLICATION_ATTEMPT_JSON_BYTES}
@@ -587,6 +648,7 @@ async function createPublicationAttempt(
 		contentId: string
 		revisionId: string
 		previousRevisionId: string | null
+		targetPublishedAt: number | null
 		surfaceNames: string[]
 		packageVersion: string | null
 		now: number
@@ -605,6 +667,7 @@ function publicationAttemptInsert(
 		contentId: string
 		revisionId: string
 		previousRevisionId: string | null
+		targetPublishedAt: number | null
 		surfaceNames: string[]
 		packageVersion: string | null
 		now: number
@@ -613,11 +676,12 @@ function publicationAttemptInsert(
 	return db
 		.prepare(
 			`INSERT INTO content_publication_attempts (
-			   id, operation, content_id, revision_id, previous_revision_id, state,
+			   id, operation, content_id, revision_id, previous_revision_id,
+			   target_published_at, state,
 			   surface_names_json, pending_surface_names_json,
 			   prepared_surface_names_json, receipts_json,
 			   package_version, created_at, updated_at
-			 ) VALUES (?, ?, ?, ?, ?, 'preparing', ?, ?, '[]', '[]', ?, ?, ?)`,
+			 ) VALUES (?, ?, ?, ?, ?, ?, 'preparing', ?, ?, '[]', '[]', ?, ?, ?)`,
 		)
 		.bind(
 			id,
@@ -625,6 +689,7 @@ function publicationAttemptInsert(
 			input.contentId,
 			input.revisionId,
 			input.previousRevisionId,
+			input.targetPublishedAt,
 			JSON.stringify(input.surfaceNames),
 			JSON.stringify(input.surfaceNames),
 			input.packageVersion,
@@ -692,6 +757,7 @@ async function createRevisionAndPublicationAttempt(
 	input: {
 		contentId: string
 		previousRevisionId: string | null
+		targetPublishedAt: number
 		surfaceNames: string[]
 		packageVersion: string | null
 		now: number
@@ -724,6 +790,7 @@ async function createRevisionAndPublicationAttempt(
 			contentId: input.contentId,
 			revisionId,
 			previousRevisionId: input.previousRevisionId,
+			targetPublishedAt: input.targetPublishedAt,
 			surfaceNames: input.surfaceNames,
 			packageVersion: input.packageVersion,
 			now: input.now,
@@ -1511,6 +1578,35 @@ async function movePointerAndBeginCommit(
 	attempt: PublicationAttempt,
 	now: number,
 ): Promise<void> {
+	if (
+		attempt.operation === 'publish' &&
+		(!Number.isSafeInteger(attempt.targetPublishedAt) || (attempt.targetPublishedAt as number) < 0)
+	) {
+		throw new PublicationInputError(
+			'published_at_invalid',
+			'publication attempt has an invalid target publication time',
+		)
+	}
+	const targetRevisionSlugAvailable = `EXISTS (
+		SELECT 1
+		FROM content_revisions target_revision
+		WHERE target_revision.id = ?
+		  AND target_revision.content_id = ?
+		  AND json_type(target_revision.payload_json, '$.item.slug') = 'text'
+		  AND length(json_extract(target_revision.payload_json, '$.item.slug')) BETWEEN 1 AND 512
+		  AND NOT EXISTS (
+		    SELECT 1
+		    FROM content_items other_item
+		    JOIN content_revisions other_revision
+		      ON other_revision.id = other_item.published_revision_id
+		     AND other_revision.content_id = other_item.id
+		    WHERE other_item.id <> ?
+		      AND other_item.status = 'published'
+		      AND other_item.deleted_at IS NULL
+		      AND json_extract(other_revision.payload_json, '$.item.slug') =
+		          json_extract(target_revision.payload_json, '$.item.slug')
+		  )
+	)`
 	const pointerStatement =
 		attempt.operation === 'publish'
 			? db
@@ -1523,16 +1619,20 @@ async function movePointerAndBeginCommit(
 						   AND EXISTS (
 						     SELECT 1 FROM content_publication_attempts
 						     WHERE id = ? AND state = 'prepared' AND revision_id = ? AND content_id = ?
-						   )`,
+						   )
+						   AND ${targetRevisionSlugAvailable}`,
 					)
 					.bind(
-						now,
+						attempt.targetPublishedAt,
 						attempt.revisionId,
 						attempt.contentId,
 						attempt.previousRevisionId ?? '',
 						attempt.id,
 						attempt.revisionId,
 						attempt.contentId,
+						attempt.revisionId,
+						attempt.contentId,
+						attempt.contentId,
 					)
 			: db
 					.prepare(
@@ -1544,7 +1644,8 @@ async function movePointerAndBeginCommit(
 						   AND EXISTS (
 						     SELECT 1 FROM content_publication_attempts
 						     WHERE id = ? AND state = 'prepared' AND revision_id = ? AND content_id = ?
-						   )`,
+						   )
+						   AND ${targetRevisionSlugAvailable}`,
 					)
 					.bind(
 						attempt.revisionId,
@@ -1553,6 +1654,9 @@ async function movePointerAndBeginCommit(
 						attempt.id,
 						attempt.revisionId,
 						attempt.contentId,
+						attempt.revisionId,
+						attempt.contentId,
+						attempt.contentId,
 					)
 	const attemptStatement = db
 		.prepare(
@@ -1695,6 +1799,7 @@ export async function publishOne(
 	input: PublishOneInput,
 ): Promise<PublishOneReceipt> {
 	const now = input.now ?? nowSeconds()
+	const targetPublishedAt = normalizePublishedAt(input.publishedAt, now)
 	const surfaceHookTimeoutMs = normalizeSurfaceHookTimeoutMs(input.surfaceHookTimeoutMs)
 	const surfaces = normalizeSurfaces(input)
 	const item = await getContentItem(db, input.contentId)
@@ -1703,6 +1808,7 @@ export async function publishOne(
 	const { revisionId, snapshot, attempt } = await createRevisionAndPublicationAttempt(db, {
 		contentId: input.contentId,
 		previousRevisionId,
+		targetPublishedAt,
 		surfaceNames: surfaces.map((surface) => surface.name),
 		packageVersion: input.packageVersion ?? null,
 		now,
@@ -1754,7 +1860,7 @@ export async function publishOne(
 		contentId: input.contentId,
 		revisionId,
 		previousRevisionId,
-		publishedAt: now,
+		publishedAt: targetPublishedAt,
 		surfaceStatus,
 		surfaces: committed.receipts,
 		packageVersion: input.packageVersion ?? null,
@@ -1790,6 +1896,7 @@ export async function rollbackPublication(
 		contentId: input.contentId,
 		revisionId: input.targetRevisionId,
 		previousRevisionId,
+		targetPublishedAt: null,
 		surfaceNames: surfaces.map((surface) => surface.name),
 		packageVersion: input.packageVersion ?? null,
 		now,
@@ -2033,6 +2140,18 @@ async function findContentBySlug(
 	return { id: row.id, slug: row.slug, type }
 }
 
+async function findContentBySourceId(
+	db: D1Database,
+	sourceId: string,
+): Promise<{ id: string; slug: string; type: ContentType } | null> {
+	const row = await db
+		.prepare('SELECT id, slug, type FROM content_items WHERE source_id = ? LIMIT 1')
+		.bind(sourceId)
+		.first<{ id: string; slug: string; type: ContentType }>()
+	if (!row) return null
+	return row
+}
+
 function createInputForArchiveItem(
 	item: ContentArchiveItem,
 	type: 'article' | 'newsletter' | 'page',
@@ -2042,13 +2161,33 @@ function createInputForArchiveItem(
 	const base = {
 		type,
 		slug,
+		sourceId: item.sourceId ?? null,
 		title: item.title ?? 'Untitled',
+		seoTitle: item.seoTitle ?? null,
+		description: item.description ?? null,
 		excerpt: item.excerpt ?? null,
+		byline: item.byline ?? null,
 		primaryCategory: item.primaryCategory ?? options.defaultPrimaryCategory ?? 'analysis',
 		primaryTopic: item.primaryTopic ?? options.defaultPrimaryTopic ?? null,
+		featured: item.featured ?? false,
+		visibility: item.visibility ?? 'free',
+		authorId: item.authorId ?? null,
+		heroImageId: item.heroImageId ?? null,
+		heroImageAlt: item.heroImageAlt ?? null,
+		heroImageCaption: item.heroImageCaption ?? null,
+		socialImageId: item.socialImageId ?? null,
+		canonicalUrl: item.canonicalUrl ?? null,
 		tags: item.tags ?? [],
+		metadata: item.metadata,
+		initialTimestamps: {
+			publishedAt: item.publishedAt ?? null,
+			createdAt: item.createdAt ?? null,
+			updatedAt: item.updatedAt ?? null,
+			publishTz: item.publishTz ?? null,
+		},
 		content: {
 			bodyMarkdown: item.bodyMarkdown ?? ' ',
+			bodyHtml: item.bodyHtml ?? null,
 		},
 	}
 	if (type === 'article') return { ...base, type: 'article' }
@@ -2056,6 +2195,164 @@ function createInputForArchiveItem(
 	return { ...base, type: 'page' }
 }
 
+function assertArchiveTimestamp(field: string, value: number | null | undefined): void {
+	if (value === null || value === undefined) return
+	if (!Number.isSafeInteger(value) || value < 0) {
+		throw new ContentArchiveImportLimitError(
+			'archive_timestamp_invalid',
+			`${field} must be a non-negative epoch second`,
+			Number.MAX_SAFE_INTEGER,
+			value,
+		)
+	}
+}
+
+function validateArchiveItem(item: ContentArchiveItem, maxBodyBytes: number): void {
+	const optionalStrings: Array<[string, unknown]> = [
+		['slug', item.slug],
+		['seo_title', item.seoTitle],
+		['description', item.description],
+		['excerpt', item.excerpt],
+		['byline', item.byline],
+		['primary_category', item.primaryCategory],
+		['primary_topic', item.primaryTopic],
+		['author_id', item.authorId],
+		['hero_image_id', item.heroImageId],
+		['hero_image_alt', item.heroImageAlt],
+		['hero_image_caption', item.heroImageCaption],
+		['social_image_id', item.socialImageId],
+		['canonical_url', item.canonicalUrl],
+	]
+	for (const [field, value] of optionalStrings) {
+		if (value !== null && value !== undefined && typeof value !== 'string') {
+			throw new ContentArchiveImportLimitError(
+				`archive_${field}_invalid`,
+				`${field} must be a string or null`,
+				0,
+				-1,
+			)
+		}
+	}
+	if (item.featured !== undefined && typeof item.featured !== 'boolean') {
+		throw new ContentArchiveImportLimitError(
+			'archive_featured_invalid',
+			'featured must be a boolean',
+			0,
+			-1,
+		)
+	}
+	if (item.visibility !== undefined && !['free', 'premium'].includes(item.visibility)) {
+		throw new ContentArchiveImportLimitError(
+			'archive_visibility_invalid',
+			'visibility must be free or premium',
+			0,
+			-1,
+		)
+	}
+	if (
+		item.tags !== undefined &&
+		(!Array.isArray(item.tags) ||
+			item.tags.length > 10 ||
+			!item.tags.every((tag) => typeof tag === 'string'))
+	) {
+		throw new ContentArchiveImportLimitError(
+			'archive_tags_invalid',
+			'tags must contain at most 10 strings',
+			10,
+			Array.isArray(item.tags) ? item.tags.length : -1,
+		)
+	}
+	if (item.bodyMarkdown !== undefined && typeof item.bodyMarkdown !== 'string') {
+		throw new ContentArchiveImportLimitError(
+			'archive_body_invalid',
+			'archive item Markdown body must be a string',
+			maxBodyBytes,
+			-1,
+		)
+	}
+	if (item.bodyHtml !== null && item.bodyHtml !== undefined && typeof item.bodyHtml !== 'string') {
+		throw new ContentArchiveImportLimitError(
+			'archive_body_html_invalid',
+			'archive item rendered HTML must be a string or null',
+			maxBodyBytes,
+			-1,
+		)
+	}
+	const bodyMarkdown = item.bodyMarkdown ?? ' '
+	assertLimit(
+		'archive_body_limit_exceeded',
+		'archive item body exceeds the configured import limit',
+		maxBodyBytes,
+		textBytes(bodyMarkdown),
+	)
+	if (item.bodyHtml !== null && item.bodyHtml !== undefined) {
+		assertLimit(
+			'archive_body_html_limit_exceeded',
+			'archive item rendered HTML exceeds the configured import limit',
+			maxBodyBytes,
+			textBytes(item.bodyHtml),
+		)
+	}
+	try {
+		serializeContentMetadata(item.metadata)
+	} catch (error) {
+		if (!(error instanceof ContentMetadataError)) throw error
+		throw new ContentArchiveImportLimitError(
+			error.code === 'content_metadata_limit_exceeded'
+				? 'archive_metadata_limit_exceeded'
+				: 'archive_metadata_invalid',
+			'archive item metadata is invalid or exceeds its configured limit',
+			MAX_CONTENT_METADATA_BYTES,
+			-1,
+		)
+	}
+	assertArchiveTimestamp('publishedAt', item.publishedAt)
+	assertArchiveTimestamp('createdAt', item.createdAt)
+	assertArchiveTimestamp('updatedAt', item.updatedAt)
+	if (
+		item.publishTz !== null &&
+		item.publishTz !== undefined &&
+		typeof item.publishTz !== 'string'
+	) {
+		throw new ContentArchiveImportLimitError(
+			'archive_publish_tz_invalid',
+			'archive item publishTz must be a string or null',
+			64,
+			-1,
+		)
+	}
+	if (
+		typeof item.publishTz === 'string' &&
+		(!item.publishTz.trim() || item.publishTz.length > 64)
+	) {
+		throw new ContentArchiveImportLimitError(
+			'archive_publish_tz_invalid',
+			'archive item publishTz must be a non-empty string of at most 64 characters',
+			64,
+			item.publishTz.length,
+		)
+	}
+	if (item.sourceId !== undefined && typeof item.sourceId !== 'string') {
+		throw new ContentArchiveImportLimitError(
+			'archive_source_id_invalid',
+			'archive item sourceId must be a string',
+			256,
+			-1,
+		)
+	}
+	if (
+		typeof item.sourceId === 'string' &&
+		(!item.sourceId.trim() || item.sourceId !== item.sourceId.trim() || item.sourceId.length > 256)
+	) {
+		throw new ContentArchiveImportLimitError(
+			'archive_source_id_invalid',
+			'archive item sourceId must be a trimmed non-empty string of at most 256 characters',
+			256,
+			item.sourceId.length,
+		)
+	}
+}
+
 export async function importContentArchive(
 	db: D1Database,
 	archive: ContentArchiveInput,
@@ -2098,6 +2395,20 @@ export async function importContentArchive(
 		)
 	}
 	const end = Math.min(items.length, cursor + batchSize)
+	// Validate the complete selected batch before the first write. D1's injected
+	// structural surface has no transaction callback, so preflight prevents a
+	// malformed later item from leaving earlier drafts partially imported.
+	for (let index = cursor; index < end; index += 1) {
+		const item = items[index]
+		if (
+			!item ||
+			!bodyBackedArchiveType(item.type) ||
+			typeof item.title !== 'string' ||
+			!item.title.trim()
+		)
+			continue
+		validateArchiveItem(item, maxBodyBytes)
+	}
 	for (let index = cursor; index < end; index += 1) {
 		const item = items[index]
 		if (!item) continue
@@ -2106,20 +2417,14 @@ export async function importContentArchive(
 			skipped.push({ index, reason: 'unsupported_type', title: item.title ?? null })
 			continue
 		}
-		if (!item.title?.trim()) {
+		if (typeof item.title !== 'string' || !item.title.trim()) {
 			skipped.push({ index, reason: 'missing_title', title: null })
 			continue
 		}
 		const requestedSlug = item.slug?.trim() || item.title
 		const baseSlug = slugify(requestedSlug)
-		const bodyMarkdown = item.bodyMarkdown ?? ' '
-		assertLimit(
-			'archive_body_limit_exceeded',
-			'archive item body exceeds the configured import limit',
-			maxBodyBytes,
-			textBytes(bodyMarkdown),
-		)
-		const existing = await findContentBySlug(db, baseSlug)
+		const existingBySource = item.sourceId ? await findContentBySourceId(db, item.sourceId) : null
+		const existing = existingBySource ?? (await findContentBySlug(db, baseSlug))
 		if (existing) {
 			skipped.push({
 				index,
@@ -2127,12 +2432,18 @@ export async function importContentArchive(
 				title: item.title,
 				slug: existing.slug,
 				existingId: existing.id,
+				sourceId: item.sourceId,
 			})
 			continue
 		}
 		const slug = await ensureUniqueSlug(db, requestedSlug)
 		const result = await createContent(db, createInputForArchiveItem(item, type, slug, options))
-		created.push({ id: result.id, slug: result.slug, type })
+		created.push({
+			id: result.id,
+			slug: result.slug,
+			type,
+			...(item.sourceId ? { sourceId: item.sourceId } : {}),
+		})
 	}
 	const nextCursor = end >= items.length ? null : end
 	return {