@growth-labs/cms 0.8.20 → 0.8.23

package/src/foundry-emit.ts

@@ -0,0 +1,255 @@
+// @growth-labs/cms/foundry-emit — the one v2 schema for the Foundry machine
+// article route, shared by the route (routes/foundry-publish.ts) and by every
+// producer that emits into it, plus a pure mapper from the archive-import item
+// shape (ContentArchiveItem, as the channel repos' compiler.mjs builds it) to a
+// v2 body.
+//
+// This module must stay importable in pure Node: zod, the pure slug helpers and
+// type-only imports. Nothing here touches D1, the network or `cloudflare:*`.
+
+import { sha256Hex } from '@growth-labs/foundry-signing'
+import { z } from 'zod'
+import type { ContentArchiveItem } from './engine/publication.js'
+import { slugify } from './engine/slug.js'
+
+export const FOUNDRY_ARTICLE_SCHEMA_VERSION = 2 as const
+
+/** The machine route's own source namespace; an adoption never targets it. */
+export const FOUNDRY_SOURCE_PREFIX = 'foundry:'
+
+/** Upper bound the publication kernel accepts for a revision's slug. */
+export const FOUNDRY_SLUG_MAX_LENGTH = 512
+
+/**
+ * The engine's slug rule, applied verbatim: a v2 slug is accepted only when it
+ * is already canonical (`slugify(slug) === slug`), because the route never
+ * derives, rewrites or suffixes a v2 slug.
+ */
+export function isCanonicalSlug(value: string): boolean {
+	return value.length >= 3 && value.length <= FOUNDRY_SLUG_MAX_LENGTH && slugify(value) === value
+}
+
+const HERO_IMAGE_KEY = /^[A-Za-z0-9][A-Za-z0-9._\-/]*$/
+
+export const FoundryArticleV2Schema = z
+	.object({
+		schemaVersion: z.literal(FOUNDRY_ARTICLE_SCHEMA_VERSION),
+		slug: z.string().refine(isCanonicalSlug, {
+			message: 'slug must already be canonical: lowercase a-z, 0-9 and single hyphens, 3-512 chars',
+		}),
+		title: z.string().trim().min(3),
+		body_html: z.string().min(1),
+		hero_image_key: z
+			.string()
+			.min(1)
+			.max(1024)
+			.refine((key) => HERO_IMAGE_KEY.test(key) && !key.split('/').includes('..'), {
+				message: 'hero_image_key must be a relative object key',
+			})
+			.optional(),
+		hero_image_url: z
+			.string()
+			.url()
+			.refine((url) => url.startsWith('https://'), { message: 'hero_image_url must be https' })
+			.optional(),
+		publishAt: z.string().datetime({ offset: true }).optional(),
+		author: z.string().trim().min(1).max(200).optional(),
+		desk: z.string().trim().min(1).max(100).optional(),
+		tags: z.array(z.string().trim().min(1).max(100)).max(50).optional(),
+		description: z.string().trim().min(1).optional(),
+		visibility: z.enum(['free', 'premium']).optional(),
+		adoptSourceId: z
+			.string()
+			.min(1)
+			.max(256)
+			.refine((value) => value === value.trim() && !value.startsWith(FOUNDRY_SOURCE_PREFIX), {
+				message: 'adoptSourceId must be a trimmed bridge source id, never a foundry: id',
+			})
+			.optional(),
+	})
+	.strict()
+	.refine((body) => !(body.hero_image_key && body.hero_image_url), {
+		message: 'send hero_image_key or hero_image_url, not both',
+		path: ['hero_image_key'],
+	})
+
+export type FoundryArticleV2 = z.output<typeof FoundryArticleV2Schema>
+
+export class FoundryEmitError extends Error {
+	readonly code: string
+
+	constructor(code: string, message: string) {
+		super(message)
+		this.name = 'FoundryEmitError'
+		this.code = code
+	}
+}
+
+export interface FoundryEmitOptions {
+	/**
+	 * Overrides the publication time. Omitted: the item's `publishedAt` (unix
+	 * seconds) is used when present. `null`: no publishAt, so the route writes a
+	 * draft only.
+	 */
+	publishAt?: string | null
+}
+
+function present(value: string | null | undefined): value is string {
+	return typeof value === 'string' && value.trim().length > 0
+}
+
+/**
+ * Map one archive-import item to a v2 route body. Pure: the same item always
+ * yields the same body, and the result is parsed by the route's own schema, so
+ * a body this function returns is one the route accepts.
+ */
+export function toFoundryArticleV2(
+	item: ContentArchiveItem,
+	options: FoundryEmitOptions = {},
+): FoundryArticleV2 {
+	if (item.type !== undefined && item.type !== 'article') {
+		throw new FoundryEmitError('unsupported_type', `only articles are emitted, got ${item.type}`)
+	}
+	if (!present(item.slug)) throw new FoundryEmitError('slug_missing', 'archive item has no slug')
+	if (!present(item.title)) throw new FoundryEmitError('title_missing', 'archive item has no title')
+	if (!present(item.bodyHtml)) {
+		throw new FoundryEmitError('body_html_missing', 'archive item has no rendered bodyHtml')
+	}
+
+	let publishAt: string | undefined
+	if (options.publishAt !== undefined) {
+		publishAt = options.publishAt ?? undefined
+	} else if (typeof item.publishedAt === 'number' && Number.isFinite(item.publishedAt)) {
+		publishAt = new Date(item.publishedAt * 1_000).toISOString()
+	}
+
+	const hero = present(item.heroImageId) ? item.heroImageId.trim() : null
+	const author = present(item.byline) ? item.byline : present(item.authorId) ? item.authorId : null
+	const description = present(item.description)
+		? item.description
+		: present(item.excerpt)
+			? item.excerpt
+			: null
+
+	const body: Record<string, unknown> = {
+		schemaVersion: FOUNDRY_ARTICLE_SCHEMA_VERSION,
+		slug: item.slug,
+		title: item.title,
+		body_html: item.bodyHtml,
+		...(hero
+			? /^https?:\/\//i.test(hero)
+				? { hero_image_url: hero }
+				: { hero_image_key: hero }
+			: {}),
+		...(publishAt ? { publishAt } : {}),
+		...(author ? { author } : {}),
+		...(present(item.primaryCategory) ? { desk: item.primaryCategory } : {}),
+		...(item.tags && item.tags.length > 0 ? { tags: [...item.tags] } : {}),
+		...(description ? { description } : {}),
+		...(item.visibility ? { visibility: item.visibility } : {}),
+		...(present(item.sourceId) ? { adoptSourceId: item.sourceId } : {}),
+	}
+	return FoundryArticleV2Schema.parse(body)
+}
+
+// --- content-emit.json: the whole archive as the exact PUT bodies foundryd sends ---
+
+export const CONTENT_EMIT_SCHEMA_VERSION = 1 as const
+
+/** An item the producer retires (frontmatter `status: archived`): no request is sent. */
+export interface ContentEmitRetireItem {
+	path: string
+	videoId: string | null
+	retire: true
+}
+
+/**
+ * An item to PUT. `request` is the exact PUT body as a JSON STRING, never a
+ * nested object, so re-indenting the envelope cannot change its bytes;
+ * `requestSha256` is the lowercase hex SHA-256 of its UTF-8 bytes, which is the
+ * `request_sha256` the route stores and echoes for that PUT.
+ */
+export interface ContentEmitPutItem {
+	path: string
+	videoId: string | null
+	retire: false
+	requestSha256: string
+	request: string
+}
+
+export type ContentEmitItem = ContentEmitRetireItem | ContentEmitPutItem
+
+export interface ContentEmit {
+	schemaVersion: typeof CONTENT_EMIT_SCHEMA_VERSION
+	app: string
+	sourceSha: string
+	items: ContentEmitItem[]
+}
+
+const APP_ID = /^[a-z0-9][a-z0-9-]{0,63}$/
+const SOURCE_SHA = /^[0-9a-f]{7,64}$/
+
+/** Lowercase hex SHA-256 of a string's UTF-8 bytes (the shared implementation). */
+export { sha256Hex }
+
+function archivePath(item: ContentArchiveItem, index: number): string {
+	const sourceId = item.sourceId
+	const separator = typeof sourceId === 'string' ? sourceId.indexOf(':') : -1
+	if (!sourceId || separator < 1 || separator === sourceId.length - 1) {
+		throw new FoundryEmitError(
+			'source_id_missing',
+			`archive item ${index} has no "<ns>:<relpath>" sourceId`,
+		)
+	}
+	return sourceId.slice(separator + 1)
+}
+
+/**
+ * Build content-emit.json for a WHOLE archive. Every item is either retired
+ * (`metadata.originalStatus === 'archived'`, the compiler's carry of frontmatter
+ * `status: archived`) or carries its exact v2 PUT body. Any item that cannot be
+ * emitted fails the whole build: a partial emit would silently drop articles.
+ */
+export async function buildContentEmit(
+	archive: { items?: ContentArchiveItem[] },
+	options: { app: string; sourceSha: string },
+): Promise<ContentEmit> {
+	if (!APP_ID.test(options.app)) {
+		throw new FoundryEmitError('app_invalid', 'app must be a lowercase id (a-z, 0-9, -)')
+	}
+	if (!SOURCE_SHA.test(options.sourceSha)) {
+		throw new FoundryEmitError('source_sha_invalid', 'sourceSha must be a lowercase hex commit')
+	}
+	if (!Array.isArray(archive.items)) {
+		throw new FoundryEmitError('archive_invalid', 'archive has no items array')
+	}
+	const seen = new Set<string>()
+	const items: ContentEmitItem[] = []
+	for (const [index, item] of archive.items.entries()) {
+		const path = archivePath(item, index)
+		if (seen.has(path)) throw new FoundryEmitError('path_duplicate', `duplicate path ${path}`)
+		seen.add(path)
+		const videoId =
+			typeof item.metadata?.videoId === 'string' && item.metadata.videoId
+				? item.metadata.videoId
+				: null
+		if (item.metadata?.originalStatus === 'archived') {
+			items.push({ path, videoId, retire: true })
+			continue
+		}
+		let request: string
+		try {
+			request = JSON.stringify(toFoundryArticleV2(item))
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error)
+			throw new FoundryEmitError('item_invalid', `${path}: ${detail}`)
+		}
+		items.push({ path, videoId, retire: false, requestSha256: await sha256Hex(request), request })
+	}
+	return {
+		schemaVersion: CONTENT_EMIT_SCHEMA_VERSION,
+		app: options.app,
+		sourceSha: options.sourceSha,
+		items,
+	}
+}

package/src/integration/index.ts

@@ -33,6 +33,10 @@ export default function growthLabsCms(userOptions: CmsIntegrationOptions): Astro
 					pattern: '/api/cms/foundry/articles/[external_id]/unpublish',
 					entrypoint: resolveEntrypoint('../ui/api/foundry/articles/[external_id]/unpublish'),
 				})
+				injectRoute({
+					pattern: '/api/cms/foundry/articles/[external_id]/publish',
+					entrypoint: resolveEntrypoint('../ui/api/foundry/articles/[external_id]/publish'),
+				})
 				// the SPA shell index (SSR, prerender=false)
 				injectRoute({ pattern: base, entrypoint: resolveAstro('../ui/pages/admin.astro') })
 				// the /admin/api/* JSON routes
@@ -270,6 +274,11 @@ export default function growthLabsCms(userOptions: CmsIntegrationOptions): Astro
 					pattern: `${base}/api/surveys/[surveyId]/responses.csv`,
 					entrypoint: resolveEntrypoint('../ui/api/surveys/[surveyId]/responses.csv'),
 				})
+				// Owner-only classification of a written answer (technical/general).
+				injectRoute({
+					pattern: `${base}/api/surveys/[surveyId]/answers/label`,
+					entrypoint: resolveEntrypoint('../ui/api/surveys/[surveyId]/answers/label'),
+				})
 				// Calendar
 				injectRoute({
 					pattern: `${base}/api/calendar`,

package/src/integration/options.ts

@@ -1,3 +1,4 @@
+import { isCanonicalHost } from '@growth-labs/foundry-signing'
 import { z } from 'zod'
 import { SurveyIdSchema } from '../surveys/schema.js'
 
@@ -124,6 +125,17 @@ const surveyResultsSchema = z
 	})
 	.strict()
 
+const surveysOptionsSchema = z
+	.object({
+		// Automatic technical/general labeling of new written survey answers
+		// through the host's LlmDispatch (2026-10-02, packet 08), scheduled off
+		// the survey results request via waitUntil. Off by default: a site
+		// opts in, and only a site that wired the LlmDispatch seam pays for
+		// the background dispatches.
+		autoLabel: z.boolean().default(false),
+	})
+	.default({})
+
 export const cmsIntegrationOptionsSchema = z
 	.object({
 		workspaces: z.array(workspaceSchema).min(1, 'at least one workspace is required'),
@@ -143,6 +155,17 @@ export const cmsIntegrationOptionsSchema = z
 		theme: themeSchema,
 		socialSharing: socialSharingSchema,
 		surveyResults: surveyResultsSchema.optional(),
+		surveys: surveysOptionsSchema,
+		// This publication's canonical host for the Foundry machine route
+		// (/api/cms/foundry/*), e.g. `warfronts.pub`. Declared, the route verifies
+		// only the host-bound foundry-cms-v2 signature on every request and never
+		// the legacy form, whatever the per-request hooks set.
+		foundryCanonicalHost: z
+			.string()
+			.refine(isCanonicalHost, {
+				message: 'foundryCanonicalHost must be a lowercase host with no scheme or port',
+			})
+			.optional(),
 	})
 	.transform((o) => ({ ...o, activeWorkspaceId: o.activeWorkspaceId ?? o.workspaces[0].id }))
 

package/src/providers/null.ts

@@ -69,6 +69,12 @@ export const nullAnalytics: AnalyticsProvider = {
 			},
 		})
 	},
+	// Podcast listening analytics is a host opt-in: null (not an empty
+	// envelope) so the route 404s and the panel reports "not available"
+	// instead of rendering silent zeros for a site that has none.
+	async getPodcastListening() {
+		return null
+	},
 }
 
 export const nullSubscriptions: SubscriptionsProvider = {

package/src/providers/types.ts

@@ -89,6 +89,51 @@ export interface ArticleAnalyticsDetail {
 	funnel?: ArticleFunnelStages
 }
 
+export interface PodcastListeningEpisode {
+	slug: string
+	title?: string
+	/** Real press-play attempts (user-initiated audio_play; autoplay excluded). */
+	plays: number
+	/** Distinct sessions that played this episode. */
+	listeners: number
+	reached10: number
+	reached25: number
+	reached50: number
+	reached75: number
+	reached90: number
+	completes: number
+	/** completes / plays; 0 when plays is 0. */
+	completionRate: number
+	/**
+	 * Total seconds actually listened. Null means NOT MEASURED — no
+	 * `audio_played` rows exist for this episode in the range — and the UI
+	 * must render "—", never a silent zero.
+	 */
+	totalListeningSeconds: number | null
+	/** totalListeningSeconds / listeners; null when either input is unmeasured. */
+	avgListeningSecondsPerListener: number | null
+}
+
+export interface PodcastListening {
+	episodes: PodcastListeningEpisode[]
+	totals: {
+		/** Episodes with at least one real play in the range. */
+		episodes: number
+		plays: number
+		/**
+		 * Distinct sessions across every episode, deduplicated — never the sum
+		 * of per-episode listeners, which would double-count a session that
+		 * listened to two episodes.
+		 */
+		listeners: number
+		completes: number
+		completionRate: number
+		totalListeningSeconds: number | null
+	}
+	/** Echo of the requested window, ISO 8601 instants. */
+	range: { from: string; to: string }
+}
+
 export interface AnalyticsProvider {
 	getKpis(range: DateRange): Promise<ProviderResult<Record<string, number | null>>>
 	getReadsTimeSeries(range: DateRange): Promise<ProviderResult<Array<{ t: number; reads: number }>>>
@@ -99,6 +144,13 @@ export interface AnalyticsProvider {
 		range: DateRange,
 	): Promise<ProviderResult<Array<{ source: string; sessions: number }>>>
 	getArticleDetail(slug: string, range: DateRange): Promise<ProviderResult<ArticleAnalyticsDetail>>
+	/**
+	 * Per-episode podcast listening analytics. Null means this site has no
+	 * podcast listening analytics at all (the null provider) — the CMS hides
+	 * the panel. A site that implements it but fails to read its source
+	 * throws, so the route surfaces a loud error instead of zeros.
+	 */
+	getPodcastListening(input: { from: string; to: string }): Promise<PodcastListening | null>
 }
 
 export interface SubscriptionMember {

package/src/routes/ai.ts

@@ -23,7 +23,12 @@ import {
 } from '../engine/ai-prompts.js'
 import { applyAiWrite, parseLockedFields } from '../engine/ai-writeback.js'
 import { buildOgCardSpec } from '../engine/og-render.js'
-import { type ContentItemRecord, getContentItem } from '../engine/publisher.js'
+import {
+	type ContentItemRecord,
+	canonicalEditStatement,
+	getContentItem,
+	updateContentItem,
+} from '../engine/publisher.js'
 import type { LlmDispatchResult } from '../providers/types.js'
 import { canPerformContentAction } from './authz-matrix.js'
 import type { CmsRouteConfig } from './config.js'
@@ -207,6 +212,8 @@ export function createAiRoutes(config: CmsRouteConfig): AiRouteHandlers {
 		if (result.status === 'unavailable') {
 			return llmUnavailableResponse({ reason: result.reason }, { dek: null, written: false })
 		}
+		// An editor-triggered dek is a human-initiated canonical change.
+		if (result.written) await canonicalEditStatement(ctx.db, idResult.id).run()
 		return json({
 			dek: result.dek,
 			written: result.written,
@@ -322,16 +329,19 @@ export function createAiRoutes(config: CmsRouteConfig): AiRouteHandlers {
 
 		if (writeResult.written) {
 			const now = Math.floor(Date.now() / 1000)
-			await ctx.db
-				.prepare(
-					`UPDATE article_content
+			// An editor-triggered write-back is a human-initiated canonical change.
+			await ctx.db.batch([
+				ctx.db
+					.prepare(
+						`UPDATE article_content
 					SET ai_takeaways = ?,
 						ai_takeaways_at = ?,
 						ai_takeaways_model = ?
 					WHERE content_id = ?`,
-				)
-				.bind(JSON.stringify(takeaways), now, 'llm-dispatch', id)
-				.run()
+					)
+					.bind(JSON.stringify(takeaways), now, 'llm-dispatch', id),
+				canonicalEditStatement(ctx.db, id),
+			])
 		}
 
 		return json({
@@ -392,10 +402,9 @@ export function createAiRoutes(config: CmsRouteConfig): AiRouteHandlers {
 		})
 
 		if (writeResult.written) {
-			await ctx.db
-				.prepare('UPDATE content_items SET description = ?, updated_at = unixepoch() WHERE id = ?')
-				.bind(description, id)
-				.run()
+			// Through the editor's own save path, so it is a canonical edit. The
+			// existing category is passed through so the save changes nothing else.
+			await updateContentItem(ctx.db, id, { description, primaryCategory: item.channel })
 		}
 
 		return json({
@@ -478,12 +487,15 @@ export function createAiRoutes(config: CmsRouteConfig): AiRouteHandlers {
 		})
 
 		if (writeResult.written) {
-			await ctx.db
-				.prepare(
-					'UPDATE content_items SET ai_og_image_id = ?, updated_at = unixepoch() WHERE id = ?',
-				)
-				.bind(imageKey, id)
-				.run()
+			// An editor-triggered write-back is a human-initiated canonical change.
+			await ctx.db.batch([
+				ctx.db
+					.prepare(
+						'UPDATE content_items SET ai_og_image_id = ?, updated_at = unixepoch() WHERE id = ?',
+					)
+					.bind(imageKey, id),
+				canonicalEditStatement(ctx.db, id),
+			])
 		}
 
 		return json({

package/src/routes/analytics.ts

@@ -21,6 +21,7 @@ export interface AnalyticsRouteHandlers {
 	topContent(ctx: RouteContext): Promise<Response>
 	trafficSources(ctx: RouteContext): Promise<Response>
 	articleDetail(ctx: RouteContext): Promise<Response>
+	podcastListening(ctx: RouteContext): Promise<Response>
 }
 
 /** Parse ?range=<Nd> from the request URL, defaulting to 30d. */
@@ -74,5 +75,25 @@ export function createAnalyticsRoutes(config: AnalyticsRouteConfig): AnalyticsRo
 			const slug = url.searchParams.get('slug') ?? ''
 			return json(await providers.analytics.getArticleDetail(slug, range))
 		},
+
+		// Podcast listening panel — same publisher gate and ?range=<Nd> window
+		// as the other analytics handlers, but NOT a ProviderResult envelope:
+		// the provider returns null when the site has no podcast listening
+		// analytics at all, which this route answers with a 404 the screen
+		// renders as an explicit "not available" state. A provider that is
+		// implemented but fails throws — the route 500s loudly, never zeros.
+		async podcastListening(ctx: RouteContext): Promise<Response> {
+			const denied = await config.authz.requirePublisher(ctx)
+			if (denied) return denied
+			const range = parseRange(ctx.request.url)
+			const listening = await providers.analytics.getPodcastListening({
+				from: new Date(range.from * 1000).toISOString(),
+				to: new Date(range.to * 1000).toISOString(),
+			})
+			if (!listening) {
+				return json({ error: 'podcast listening analytics is not available' }, 404)
+			}
+			return json(listening)
+		},
 	}
 }