@growth-labs/cms 0.3.1 → 0.4.0

package/src/engine/publisher.ts

@@ -20,6 +20,7 @@
 // duplicate is NOT re-queued to Foundry. Any future `content_items` column
 // addition requires a matching edit here or the duplicate silently drops it.
 import type { ContentType } from '../schema/types.js'
+import { type ContentMetadata, serializeContentMetadata } from './content-metadata.js'
 import type { D1Database } from './d1.js'
 import { evaluateArticleBody, type PublishGuardOutcome } from './publish-guard.js'
 import { slugify } from './slug.js'
@@ -95,6 +96,8 @@ export interface BaseContentInput {
 	tags?: string[]
 	/** The SEO focus keyword for this content item (migration 0004 column). */
 	seoFocusKeyword?: string | null
+	/** Declared site-specific JSON values retained in every immutable revision. */
+	metadata?: ContentMetadata
 }
 
 export interface ArticleInput extends BaseContentInput {
@@ -154,12 +157,23 @@ export interface PageInput extends BaseContentInput {
 	}
 }
 
-export type CreateContentInput =
+export type CreateContentInput = (
 	| ArticleInput
 	| VideoInput
 	| PodcastInput
 	| NewsletterInput
 	| PageInput
+) & {
+	/** Optional namespaced archive key. New copies deliberately do not inherit it. */
+	sourceId?: string | null
+	/** Initial historical values for archive ingestion; normal creates omit this. */
+	initialTimestamps?: {
+		publishedAt?: number | null
+		createdAt?: number | null
+		updatedAt?: number | null
+		publishTz?: string | null
+	}
+}
 
 type BodyBackedContentInput = ArticleInput | NewsletterInput | PageInput
 
@@ -215,10 +229,57 @@ export interface ContentItemRecord {
 	ai_locked_fields: string | null
 	published_revision_id: string | null
 	seo_focus_keyword: string | null
+	metadata_json: string
+	source_id: string | null
 	created_at: number | null
 	updated_at: number | null
 }
 
+function normalizeSourceId(value: unknown): string | null {
+	if (value === null || value === undefined) return null
+	if (typeof value !== 'string' || !value || value !== value.trim() || value.length > 256) {
+		throw new TypeError('sourceId must be a trimmed non-empty string of at most 256 characters')
+	}
+	return value
+}
+
+function normalizeInitialTimestamps(value: CreateContentInput['initialTimestamps']): {
+	publishedAt: number | null
+	createdAt: number | null
+	updatedAt: number | null
+	publishTz: string | null
+} {
+	const timestamps = value ?? {}
+	for (const [field, candidate] of [
+		['publishedAt', timestamps.publishedAt],
+		['createdAt', timestamps.createdAt],
+		['updatedAt', timestamps.updatedAt],
+	] as const) {
+		if (candidate !== null && candidate !== undefined) {
+			if (!Number.isSafeInteger(candidate) || candidate < 0) {
+				throw new TypeError(`${field} must be a non-negative epoch second`)
+			}
+		}
+	}
+	const publishTz = timestamps.publishTz
+	if (
+		publishTz !== null &&
+		publishTz !== undefined &&
+		(typeof publishTz !== 'string' ||
+			!publishTz.trim() ||
+			publishTz !== publishTz.trim() ||
+			publishTz.length > 64)
+	) {
+		throw new TypeError('publishTz must be a trimmed non-empty string of at most 64 characters')
+	}
+	return {
+		publishedAt: timestamps.publishedAt ?? null,
+		createdAt: timestamps.createdAt ?? null,
+		updatedAt: timestamps.updatedAt ?? null,
+		publishTz: publishTz ?? null,
+	}
+}
+
 export async function ensureUniqueSlug(
 	db: D1Database,
 	slug: string,
@@ -229,12 +290,28 @@ export async function ensureUniqueSlug(
 	let suffix = 2
 
 	while (true) {
-		const row = await db
+		const draftRow = await db
 			.prepare('SELECT id FROM content_items WHERE slug = ? LIMIT 1')
 			.bind(candidate)
 			.first<{ id: string }>()
+		const publishedRow = await db
+			.prepare(
+				`SELECT ci.id
+				 FROM content_items ci
+				 JOIN content_revisions cr
+				   ON cr.id = ci.published_revision_id AND cr.content_id = ci.id
+				 WHERE ci.status = 'published'
+				   AND ci.deleted_at IS NULL
+				   AND json_extract(cr.payload_json, '$.item.slug') = ?
+				 LIMIT 1`,
+			)
+			.bind(candidate)
+			.first<{ id: string }>()
 
-		if (!row || (excludeId && row.id === excludeId)) {
+		const draftAvailable = !draftRow || (excludeId !== undefined && draftRow.id === excludeId)
+		const publishedAvailable =
+			!publishedRow || (excludeId !== undefined && publishedRow.id === excludeId)
+		if (draftAvailable && publishedAvailable) {
 			return candidate
 		}
 
@@ -343,6 +420,9 @@ export async function createContent(
 	const slug = await ensureUniqueSlug(db, input.slug)
 	const visibility = input.visibility || 'free'
 	const primaryCategory = input.primaryCategory || 'analysis'
+	const metadataJson = serializeContentMetadata(input.metadata)
+	const sourceId = normalizeSourceId(input.sourceId)
+	const initialTimestamps = normalizeInitialTimestamps(input.initialTimestamps)
 
 	await db
 		.prepare(
@@ -350,8 +430,10 @@ export async function createContent(
       INSERT INTO content_items (
         id, type, status, visibility, slug, title, seo_title, description, excerpt,
         byline, channel, primary_topic, featured, author_id, hero_image_id,
-        hero_image_alt, hero_image_caption, social_image_id, canonical_url
-      ) VALUES (?, ?, 'draft', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        hero_image_alt, hero_image_caption, social_image_id, canonical_url,
+        metadata_json, source_id, published_at, created_at, updated_at, publish_tz
+      ) VALUES (?, ?, 'draft', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?,
+                COALESCE(?, unixepoch()), COALESCE(?, unixepoch()), COALESCE(?, 'Europe/Paris'))
       `,
 		)
 		.bind(
@@ -373,6 +455,12 @@ export async function createContent(
 			input.heroImageCaption || null,
 			input.socialImageId || null,
 			input.canonicalUrl || null,
+			metadataJson,
+			sourceId,
+			initialTimestamps.publishedAt,
+			initialTimestamps.createdAt,
+			initialTimestamps.updatedAt,
+			initialTimestamps.publishTz,
 		)
 		.run()
 
@@ -505,6 +593,9 @@ export async function updateContentItem(
 	const seoFocusKeyword = hasOwn(input, 'seoFocusKeyword')
 		? (input.seoFocusKeyword ?? null)
 		: (existing.seo_focus_keyword ?? null)
+	const metadataJson = hasOwn(input, 'metadata')
+		? serializeContentMetadata(input.metadata)
+		: existing.metadata_json
 
 	await db
 		.prepare(
@@ -528,6 +619,7 @@ export async function updateContentItem(
         canonical_url = ?,
         ai_locked_fields = ?,
         seo_focus_keyword = ?,
+		metadata_json = ?,
         updated_at = unixepoch()
       WHERE id = ?
       `,
@@ -551,6 +643,7 @@ export async function updateContentItem(
 			canonicalUrl,
 			aiLockedFields,
 			seoFocusKeyword,
+			metadataJson,
 			id,
 		)
 		.run()
@@ -915,7 +1008,8 @@ export async function duplicateContentItem(
 	// DEFAULT (unixepoch()) timestamps; status forced to 'draft', featured to
 	// 0, publish_at/published_at/published_revision_id to NULL. (inventory §6)
 	//
-	// SEO carries over (seo_title, seo_focus_keyword, seo_score, ai_og_image_id)
+	// SEO and declared metadata carry over (seo_title, seo_focus_keyword,
+	// seo_score, ai_og_image_id, metadata_json)
 	// — a duplicate should keep the SEO work already done on the source. But
 	// board_position is the source item's slot in the editorial board ordering;
 	// a fresh draft copy must NOT inherit it, so it is reset to NULL.
@@ -927,7 +1021,8 @@ export async function duplicateContentItem(
 				hero_image_id, hero_image_alt, hero_image_caption, social_image_id,
 				canonical_url, publish_at, published_at,
 				publish_tz, ai_locked_fields, published_revision_id,
-				seo_focus_keyword, seo_score, ai_og_image_id, board_position
+				seo_focus_keyword, seo_score, ai_og_image_id, board_position,
+				metadata_json
 			)
 			SELECT
 				?, type, 'draft', visibility, ?, title || ' (Copy)', seo_title, description, excerpt,
@@ -935,7 +1030,8 @@ export async function duplicateContentItem(
 				hero_image_id, hero_image_alt, hero_image_caption, social_image_id,
 				canonical_url, NULL, NULL,
 				publish_tz, ai_locked_fields, NULL,
-				seo_focus_keyword, seo_score, ai_og_image_id, NULL
+				seo_focus_keyword, seo_score, ai_og_image_id, NULL,
+				metadata_json
 			FROM content_items
 			WHERE id = ?`,
 		)
@@ -1047,14 +1143,14 @@ export async function getContentSnapshot(
 
 	const tags = await db
 		.prepare(
-			'SELECT t.slug FROM content_tag_links l JOIN content_tags t ON t.id = l.tag_id WHERE l.content_id = ?',
+			'SELECT t.slug FROM content_tag_links l JOIN content_tags t ON t.id = l.tag_id WHERE l.content_id = ? ORDER BY t.slug ASC',
 		)
 		.bind(contentId)
 		.all<{ slug: string }>()
 
 	const related = await db
 		.prepare(
-			'SELECT related_id, rank, reason FROM content_relations WHERE content_id = ? ORDER BY rank ASC',
+			'SELECT related_id, rank, reason FROM content_relations WHERE content_id = ? ORDER BY rank ASC, related_id ASC',
 		)
 		.bind(contentId)
 		.all<{ related_id: string; rank: number; reason: string | null }>()

package/src/engine/revisions.ts

@@ -5,6 +5,7 @@
 // (words_added, words_removed, tag). Snapshot shape is formalized as
 // ContentRevisionPayload, aligned to getContentSnapshot's output.
 
+import { parseContentMetadata } from './content-metadata.js'
 import type { D1Database } from './d1.js'
 import { countWords, getContentItem, getContentSnapshot, updateContentItem } from './publisher.js'
 
@@ -233,6 +234,9 @@ export async function restoreRevision(
 		canonicalUrl: (item.canonical_url as string | null) ?? null,
 		// SEO focus keyword is part of the snapshot — restore it too.
 		seoFocusKeyword: (item.seo_focus_keyword as string | null) ?? null,
+		metadata: parseContentMetadata(
+			typeof item.metadata_json === 'string' ? item.metadata_json : '{}',
+		),
 		tags: target.payload.tags,
 		relations: target.payload.related.map((r) => ({
 			relatedId: r.related_id,

package/src/schema/migrations.ts

@@ -778,6 +778,30 @@ CREATE INDEX idx_cms_reader_state_export
   ON cms_reader_state(identity_user_id, site_id, created_at DESC, content_type, content_id);
 CREATE INDEX idx_cms_reader_state_saved
   ON cms_reader_state(identity_user_id, site_id, saved, updated_at DESC);
+`,
+	},
+	{
+		id: '0020_content_metadata_read_model',
+		sql: `
+ALTER TABLE content_items
+  ADD COLUMN metadata_json TEXT NOT NULL DEFAULT '{}';
+ALTER TABLE content_items
+  ADD COLUMN source_id TEXT;
+CREATE UNIQUE INDEX idx_content_items_source_id_unique
+  ON content_items(source_id)
+  WHERE source_id IS NOT NULL;
+ALTER TABLE content_publication_attempts
+  ADD COLUMN target_published_at INTEGER;
+UPDATE content_publication_attempts
+SET target_published_at = created_at
+WHERE operation = 'publish' AND target_published_at IS NULL;
+`,
+	},
+	{
+		id: '0021_published_revision_slug_index',
+		sql: `
+CREATE INDEX IF NOT EXISTS idx_content_revisions_published_slug
+  ON content_revisions(json_extract(payload_json, '$.item.slug'));
 `,
 	},
 ]

package/src/schema/types.ts

@@ -70,6 +70,10 @@ export interface ContentItemRow {
 	seo_focus_keyword: string | null
 	/** AI-generated OG image asset id (migration 0004). */
 	ai_og_image_id: string | null
+	/** Bounded JSON object for declared site-specific presentation metadata (migration 0020). */
+	metadata_json: string
+	/** Optional namespaced source key used for idempotent archive imports (migration 0020). */
+	source_id: string | null
 }
 
 /** Standalone topic taxonomy row. Counts are derived from content_items.primary_topic. */
@@ -555,6 +559,8 @@ export interface ContentPublicationAttemptRow {
 	content_id: string
 	revision_id: string
 	previous_revision_id: string | null
+	/** Explicit historical publication timestamp for crash-safe publish retries. */
+	target_published_at: number | null
 	state: ContentPublicationAttemptState
 	surface_names_json: string
 	pending_surface_names_json: string