@growth-labs/cms 0.1.0

package/src/engine/content-insights.ts

@@ -0,0 +1,198 @@
+import type { InsightsIngestPayload } from '../schema/insights-ingest.js'
+import type { ContentInsightRow, InsightBrief, InsightEvidence } from '../schema/types.js'
+import type { D1Database } from './d1.js'
+
+/** True when the error is a missing content_insights table (drift → 409 schema_not_ready). */
+export function isMissingInsightsTable(error: unknown): boolean {
+	return error instanceof Error && /no such table: content_insights/i.test(error.message)
+}
+
+interface RawInsightRow extends Omit<ContentInsightRow, 'evidence' | 'brief'> {
+	evidence: string
+	brief: string
+}
+
+function decodeRow(raw: RawInsightRow): ContentInsightRow {
+	return {
+		...raw,
+		evidence: JSON.parse(raw.evidence) as InsightEvidence,
+		brief: JSON.parse(raw.brief) as InsightBrief,
+	}
+}
+
+/**
+ * Read the current board for (site_id, run_date), EXCLUDING any (site_id, intent_key)
+ * present in content_insight_dismissals. Ordered best-bets first (by best_bet_rank),
+ * then by desk + desk_rank for the desk groups. evidence/brief are decoded from TEXT.
+ */
+export async function listInsightBoard(
+	db: D1Database,
+	siteId: string,
+	runDate: string,
+): Promise<ContentInsightRow[]> {
+	const result = await db
+		.prepare(
+			`SELECT i.* FROM content_insights i
+			 WHERE i.site_id = ? AND i.run_date = ?
+			   AND NOT EXISTS (
+			     SELECT 1 FROM content_insight_dismissals d
+			     WHERE d.site_id = i.site_id AND d.intent_key = i.intent_key
+			   )
+			 ORDER BY i.is_best_bet DESC, i.best_bet_rank ASC, i.desk ASC, i.desk_rank ASC`,
+		)
+		.bind(siteId, runDate)
+		.all<RawInsightRow>()
+	return (result.results || []).map(decodeRow)
+}
+
+/** Persist a dismissal for (site_id, intent_key). Idempotent via INSERT OR REPLACE on the PK. */
+export async function dismissInsight(
+	db: D1Database,
+	siteId: string,
+	intentKey: string,
+	dismissedBy: string | null,
+): Promise<void> {
+	await db
+		.prepare(
+			`INSERT OR REPLACE INTO content_insight_dismissals (site_id, intent_key, dismissed_at, dismissed_by)
+			 VALUES (?, ?, unixepoch(), ?)`,
+		)
+		.bind(siteId, intentKey, dismissedBy)
+		.run()
+}
+
+/** Clear a dismissal so the intent reappears on the next board read. */
+export async function undismissInsight(
+	db: D1Database,
+	siteId: string,
+	intentKey: string,
+): Promise<void> {
+	await db
+		.prepare('DELETE FROM content_insight_dismissals WHERE site_id = ? AND intent_key = ?')
+		.bind(siteId, intentKey)
+		.run()
+}
+
+export type ReplaceOutcome = 'applied' | 'duplicate' | 'stale'
+export interface ReplaceResult {
+	outcome: ReplaceOutcome
+	landedRunAttempt: number
+}
+
+/**
+ * Replay-safe replace of the board for (meta.site_id, meta.run_date).
+ *  - 'duplicate': meta.event_id already present in content_insight_runs.event_id → no-op.
+ *  - 'stale':     an equal-or-higher run_attempt already landed for (site_id, run_date) → no-op
+ *                 (HMAC authenticates the sender; run_attempt is the monotonic replay guard).
+ *  - 'applied':   DELETE the existing board scoped by (site_id, run_date), bulk-insert rows
+ *                 (mint id, run_id = meta.run_id, beat from payload, created_at = unixepoch()),
+ *                 upsert the run row.
+ * Dismissals are untouched — they live in their own table keyed (site_id, intent_key).
+ *
+ * The INSERT carries 16 columns (id, site_id, run_id, run_date, desk, suggestion_type,
+ * signal_type, is_best_bet, best_bet_rank, desk_rank, headline, evidence, brief,
+ * intent_key, beat, created_at) matching migration 0016 column order.
+ */
+export async function replaceInsightsBoard(
+	db: D1Database,
+	payload: InsightsIngestPayload,
+): Promise<ReplaceResult> {
+	const { meta, rows } = payload
+
+	// 1) event_id dedupe (mirrors foundry_callback_events).
+	const dupEvent = await db
+		.prepare('SELECT id FROM content_insight_runs WHERE event_id = ? LIMIT 1')
+		.bind(meta.event_id)
+		.first<{ id: string }>()
+	if (dupEvent) return { outcome: 'duplicate', landedRunAttempt: meta.run_attempt }
+
+	// 2) stale-replay guard: reject equal-or-lower run_attempt for (site_id, run_date).
+	const existing = await db
+		.prepare(
+			'SELECT id, run_attempt FROM content_insight_runs WHERE site_id = ? AND run_date = ? LIMIT 1',
+		)
+		.bind(meta.site_id, meta.run_date)
+		.first<{ id: string; run_attempt: number }>()
+	if (existing && meta.run_attempt <= existing.run_attempt) {
+		return { outcome: 'stale', landedRunAttempt: existing.run_attempt }
+	}
+
+	const now = Math.floor(Date.now() / 1000)
+
+	// 3) Scoped replace + bulk insert + run upsert in one D1 batch.
+	const statements = [
+		db
+			.prepare('DELETE FROM content_insights WHERE site_id = ? AND run_date = ?')
+			.bind(meta.site_id, meta.run_date),
+	]
+	for (const row of rows) {
+		// 16 columns: id, site_id, run_id, run_date, desk, suggestion_type, signal_type,
+		// is_best_bet, best_bet_rank, desk_rank, headline, evidence, brief,
+		// intent_key, beat, created_at
+		statements.push(
+			db
+				.prepare(
+					`INSERT INTO content_insights
+					 (id, site_id, run_id, run_date, desk, suggestion_type, signal_type, is_best_bet,
+					  best_bet_rank, desk_rank, headline, evidence, brief, intent_key, beat, created_at)
+					 VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+				)
+				.bind(
+					crypto.randomUUID(),
+					row.site_id,
+					meta.run_id,
+					row.run_date,
+					row.desk,
+					row.suggestion_type,
+					row.signal_type,
+					row.is_best_bet,
+					row.best_bet_rank,
+					row.desk_rank,
+					row.headline,
+					JSON.stringify(row.evidence),
+					JSON.stringify(row.brief),
+					row.intent_key,
+					row.beat,
+					now,
+				),
+		)
+	}
+	// Upsert the run row keyed on UNIQUE (site_id, run_date).
+	statements.push(
+		db
+			.prepare(
+				`INSERT INTO content_insight_runs
+				 (id, site_id, run_date, status, event_id, run_attempt, generated_at, content_hash,
+				  demand_count, opportunity_count, started_at, completed_at, error)
+				 VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)
+				 ON CONFLICT(site_id, run_date) DO UPDATE SET
+				   status = excluded.status,
+				   event_id = excluded.event_id,
+				   run_attempt = excluded.run_attempt,
+				   generated_at = excluded.generated_at,
+				   content_hash = excluded.content_hash,
+				   demand_count = excluded.demand_count,
+				   opportunity_count = excluded.opportunity_count,
+				   completed_at = excluded.completed_at,
+				   error = excluded.error`,
+			)
+			.bind(
+				existing?.id ?? crypto.randomUUID(),
+				meta.site_id,
+				meta.run_date,
+				meta.status,
+				meta.event_id,
+				meta.run_attempt,
+				meta.generated_at,
+				meta.content_hash,
+				meta.counts.demand_count,
+				meta.counts.opportunity_count,
+				now,
+				meta.status === 'completed' || meta.status === 'partial' ? now : null,
+				meta.error ?? null,
+			),
+	)
+
+	await db.batch(statements)
+	return { outcome: 'applied', landedRunAttempt: meta.run_attempt }
+}

package/src/engine/contributors.ts

@@ -0,0 +1,95 @@
+// content_contributors engine (P3 Task 3).
+//
+// Backs the Organize-tab co-authors list (spec §8 / §13.1).
+// The content_contributors table was created in migration 0003:
+//   content_id TEXT NOT NULL,
+//   author_id  TEXT NOT NULL,
+//   role       TEXT,
+//   position   INTEGER NOT NULL DEFAULT 0,
+//   PRIMARY KEY (content_id, author_id)
+//   FOREIGN KEY (content_id) REFERENCES content_items(id) ON DELETE CASCADE
+//   FOREIGN KEY (author_id)  REFERENCES authors(id)       ON DELETE CASCADE
+//
+// The ordering column is `position` (NOT `rank`) to match the live prod
+// fronts-data table and the Fronts public byline renderer, which read/ORDER BY
+// `position`. The package — column, TS field, and wire API — uses `position`
+// end-to-end so all three agree with prod.
+
+import type { D1Database } from './d1.js'
+
+export interface ContributorInput {
+	authorId: string
+	role: string | null
+	position: number
+}
+
+export interface ContributorRecord {
+	authorId: string
+	role: string | null
+	position: number
+	name: string | null
+	avatar: string | null
+}
+
+/**
+ * List contributors for a content item, ordered by position ASC.
+ * LEFT JOINs the authors table to surface name + avatar.
+ */
+export async function listContributors(
+	db: D1Database,
+	contentId: string,
+): Promise<ContributorRecord[]> {
+	const result = await db
+		.prepare(
+			`SELECT cc.author_id, cc.role, cc.position, a.name, a.avatar
+			 FROM content_contributors cc
+			 LEFT JOIN authors a ON a.id = cc.author_id
+			 WHERE cc.content_id = ?
+			 ORDER BY cc.position ASC, cc.author_id ASC`,
+		)
+		.bind(contentId)
+		.all<{
+			author_id: string
+			role: string | null
+			position: number
+			name: string | null
+			avatar: string | null
+		}>()
+
+	return (result.results || []).map((row) => ({
+		authorId: row.author_id,
+		role: row.role,
+		position: row.position,
+		name: row.name,
+		avatar: row.avatar,
+	}))
+}
+
+/**
+ * Replace the full contributor list for a content item (DELETE then INSERT),
+ * mirroring the setContentTags pattern. Passing an empty array clears all
+ * contributors.
+ */
+export async function setContributors(
+	db: D1Database,
+	contentId: string,
+	contributors: ContributorInput[],
+): Promise<void> {
+	// Delete all existing contributors for this content item.
+	await db.prepare('DELETE FROM content_contributors WHERE content_id = ?').bind(contentId).run()
+
+	// Insert each contributor in the new list. The LIVE prod fronts-data column is
+	// `role TEXT NOT NULL DEFAULT 'cohost'` (Fronts legacy migration 0035), so a
+	// NULL role would throw a NOT NULL constraint 500. Default to 'cohost' (prod's
+	// own DEFAULT) when role is omitted — this is the load-bearing guard; no
+	// contributor write path may bind NULL role.
+	for (const c of contributors) {
+		await db
+			.prepare(
+				`INSERT INTO content_contributors (content_id, author_id, role, position)
+				 VALUES (?, ?, ?, ?)`,
+			)
+			.bind(contentId, c.authorId, c.role ?? 'cohost', c.position)
+			.run()
+	}
+}

package/src/engine/cron.ts

@@ -0,0 +1,62 @@
+// Scheduled-publish sweep — the publisher cron.
+//
+// Ported verbatim from fulcrum-labs/fronts src/lib/publisher-cron.ts
+// (inventory §1: extract). Sweeps `content_items WHERE status='scheduled'`
+// whose `publish_at` has arrived, validates each body, publishes it, and
+// snapshots a revision. Pure engine — the route that triggers it (with authz
+// injected) lands in WS7-07.
+import type { D1Database } from './d1.js'
+import {
+	assertContentBodyValidForPublish,
+	claimScheduledForPublish,
+	createRevision,
+} from './publisher.js'
+
+interface RunScheduledPublishOptions {
+	createdBy?: string | null
+	now?: number
+}
+
+export interface ScheduledPublishResult {
+	published: string[]
+	failed: Array<{ id: string; error: string }>
+}
+
+function getErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error)
+}
+
+export async function runScheduledPublish(
+	db: D1Database,
+	options: RunScheduledPublishOptions = {},
+): Promise<ScheduledPublishResult> {
+	const now = options.now ?? Math.floor(Date.now() / 1_000)
+	const scheduled = await db
+		.prepare(
+			"SELECT id FROM content_items WHERE status = 'scheduled' AND publish_at IS NOT NULL AND publish_at <= ?",
+		)
+		.bind(now)
+		.all<{ id: string }>()
+
+	const result: ScheduledPublishResult = {
+		published: [],
+		failed: [],
+	}
+
+	for (const { id } of scheduled.results || []) {
+		try {
+			await assertContentBodyValidForPublish(db, id, 'publisher.cron')
+			// Conditional claim — only ONE concurrent run wins the scheduled→published
+			// transition. If a parallel sweep already published this row, claimed is
+			// false and we skip the duplicate publish + duplicate revision write.
+			const claimed = await claimScheduledForPublish(db, id, now)
+			if (!claimed) continue
+			await createRevision(db, id, options.createdBy ?? null)
+			result.published.push(id)
+		} catch (error) {
+			result.failed.push({ id, error: getErrorMessage(error) })
+		}
+	}
+
+	return result
+}

package/src/engine/d1.ts

@@ -0,0 +1,29 @@
+// Minimal structural D1 surface used by the publishing engine.
+//
+// The package deliberately does NOT depend on `@cloudflare/workers-types`
+// (the tsconfig pins `types: []`, matching @growth-labs/analytics): the
+// engine only needs the prepare/bind/first/all/run surface, so we declare it
+// structurally. The real workerd `D1Database` is structurally assignable to
+// this, so a site can pass `env.SITE_DB` directly with no cast.
+//
+// Keep this in sync with the subset of the D1 API the engine actually calls.
+// If a new engine function needs a method not listed here, add it here rather
+// than reaching for the full ambient types.
+
+export interface D1Result<T = Record<string, unknown>> {
+	results?: T[]
+	success?: boolean
+	meta?: Record<string, unknown>
+}
+
+export interface D1PreparedStatement {
+	bind(...values: unknown[]): D1PreparedStatement
+	first<T = Record<string, unknown>>(colName?: string): Promise<T | null>
+	all<T = Record<string, unknown>>(): Promise<D1Result<T>>
+	run<T = Record<string, unknown>>(): Promise<D1Result<T>>
+}
+
+export interface D1Database {
+	prepare(query: string): D1PreparedStatement
+	batch(statements: D1PreparedStatement[]): Promise<D1Result[]>
+}