@growth-labs/cms 0.1.0

package/src/schema/types.ts

@@ -0,0 +1,576 @@
+// TypeScript row types for the CMS D1 contract.
+//
+// These mirror the prod-verified schema in migrations/0001_create_cms_tables.sql
+// column-for-column, including the deliberate timestamp divergence: content-side
+// tables store INTEGER unix epoch seconds; `media_assets` stores TEXT
+// `datetime('now')` strings. The types encode that divergence so callers cannot
+// silently normalize it.
+//
+// Nullability: a column declared NOT NULL maps to a required, non-nullable
+// field; a nullable column maps to `T | null` (D1 returns SQL NULL as JS null).
+
+/** content_items.type CHECK domain (includes 'newsletter' per prod 0024). */
+export type ContentType = 'article' | 'video' | 'podcast' | 'newsletter'
+
+/** content_items.status CHECK domain. */
+export type ContentStatus = 'draft' | 'scheduled' | 'review' | 'published' | 'archived'
+
+/** content_items.visibility CHECK domain. */
+export type ContentVisibility = 'free' | 'premium'
+
+/** video_content.processing_state CHECK domain (bead 08 state machine). */
+export type VideoProcessingState =
+	| 'pending'
+	| 'queued'
+	| 'fetching'
+	| 'transcribing'
+	| 'transcoding'
+	| 'ready'
+	| 'failed'
+
+/** A core content record. Timestamps are INTEGER unix epoch seconds. */
+export interface ContentItemRow {
+	id: string
+	type: ContentType
+	status: ContentStatus
+	visibility: ContentVisibility
+	slug: string
+	title: string
+	seo_title: string | null
+	description: string | null
+	excerpt: string | null
+	byline: string | null
+	/** Theme-token taxonomy (site-supplied vocabulary). */
+	channel: string | null
+	/** Theme-token taxonomy (site-supplied vocabulary). */
+	primary_topic: string | null
+	featured: number
+	author_id: string | null
+	hero_image_id: string | null
+	hero_image_alt: string | null
+	hero_image_caption: string | null
+	social_image_id: string | null
+	canonical_url: string | null
+	publish_at: number | null
+	published_at: number | null
+	created_at: number
+	updated_at: number
+	/** Theme-token default ('Europe/Paris' in prod). */
+	publish_tz: string
+	/** JSON-encoded string array. */
+	ai_locked_fields: string
+	published_revision_id: string | null
+	/** Unix epoch seconds; NULL when not soft-deleted (migration 0002). */
+	deleted_at: number | null
+	/** Editorial board sort position (migration 0002). */
+	board_position: number | null
+	/** SEO quality score 0–100 (migration 0004). */
+	seo_score: number | null
+	/** SEO focus keyword for scoring/hints (migration 0004). */
+	seo_focus_keyword: string | null
+	/** AI-generated OG image asset id (migration 0004). */
+	ai_og_image_id: string | null
+}
+
+/** Standalone topic taxonomy row. Counts are derived from content_items.primary_topic. */
+export interface CmsTopicRow {
+	slug: string
+	label: string
+	created_at: number
+	updated_at: number
+}
+
+/** Article body + Hermes-fed takeaways/FAQ metadata (KEPT per OD-EST1). */
+export interface ArticleContentRow {
+	content_id: string
+	body_markdown: string
+	body_html: string | null
+	word_count: number | null
+	read_time_minutes: number | null
+	subtitle: string | null
+	ai_takeaways: string | null
+	ai_takeaways_at: number | null
+	ai_takeaways_model: string | null
+	editor_takeaways: string | null
+	ai_takeaways_correlation_id: string | null
+	faq_correlation_id: string | null
+	faq_generated_at: number | null
+	faq_model: string | null
+	/** JSON-encoded FAQ entries (migration 0004). */
+	faq_json: string | null
+}
+
+/**
+ * Video body + processing state machine. NOTE the prod column is `video_id`
+ * (renamed from `stream_uid` in migration 0018) — do not reintroduce stream_uid.
+ */
+export interface VideoContentRow {
+	content_id: string
+	script: string
+	video_id: string
+	duration_seconds: number | null
+	thumbnail_image_id: string | null
+	processing_state: VideoProcessingState
+	processing_correlation_id: string | null
+	processing_started_at: number | null
+	processing_completed_at: number | null
+	processing_last_event_at: number | null
+	processing_error: string | null
+	processing_source_url: string | null
+	processing_source_kind: string | null
+	source_fetched: number
+	transcript_ready: number
+	hls_ready: number
+	transcript_url: string | null
+	hls_manifest_url: string | null
+	hls_poster_url: string | null
+	/** Idempotency token for re-triggering processing (migration 0006). */
+	processing_trigger_token: string | null
+}
+
+export interface PodcastContentRow {
+	content_id: string
+	transcript: string
+	audio_r2_key: string
+	duration_seconds: number | null
+	/** Idempotency token for re-triggering processing (migration 0006). */
+	processing_trigger_token: string | null
+}
+
+/** A version-history snapshot. payload_json is a JSON-encoded content payload. */
+export interface ContentRevisionRow {
+	id: string
+	content_id: string
+	payload_json: string
+	created_at: number
+	created_by: string | null
+	/** Net word additions vs prior revision (migration 0005). */
+	words_added: number | null
+	/** Net word removals vs prior revision (migration 0005). */
+	words_removed: number | null
+	/** Human or autosave label, e.g. 'autosave' | 'manual' | 'restore' (migration 0005). */
+	tag: string | null
+}
+
+export interface ContentTagRow {
+	id: string
+	slug: string
+	label: string
+}
+
+export interface ContentTagLinkRow {
+	content_id: string
+	tag_id: string
+}
+
+export interface ContentRelationRow {
+	content_id: string
+	related_id: string
+	rank: number
+	reason: string | null
+}
+
+/**
+ * A media asset. IMPORTANT: created_at/updated_at are TEXT `datetime('now')`
+ * strings here, NOT INTEGER unix seconds like the content tables. This
+ * divergence is intentional and matches prod — do not normalize.
+ */
+export interface MediaAssetRow {
+	id: string
+	/** Theme-token default ('fronts' in prod). */
+	site_id: string
+	asset_type: string
+	source_type: string | null
+	original_filename: string | null
+	status: string
+	object_key: string | null
+	public_url: string | null
+	url: string | null
+	width: number | null
+	height: number | null
+	/** JSON-encoded variant map. */
+	variants_json: string | null
+	r2_binding: string | null
+	/** TEXT `datetime('now')` — NOT a unix epoch integer. */
+	created_at: string
+	/** TEXT `datetime('now')` — NOT a unix epoch integer. */
+	updated_at: string
+	pinned: number
+}
+
+/** A CMS author. Timestamps are INTEGER unix seconds (strftime('%s','now')). */
+export interface AuthorRow {
+	id: string
+	name: string
+	slug: string
+	bio: string | null
+	avatar: string | null
+	email: string | null
+	/** JSON-encoded social links. */
+	social: string | null
+	created_at: number
+	updated_at: number
+}
+
+/** Foundry HMAC-callback dedupe record (takeaways/faq/hls; bead 08). */
+export interface FoundryCallbackEventRow {
+	event_id: string
+	event_kind: string
+	correlation_id: string
+	received_at: number
+}
+
+/** Multi-byline contributor record linking authors to content with a role (migration 0003). */
+export interface ContentContributorRow {
+	content_id: string
+	author_id: string
+	role: string | null
+	position: number
+}
+
+/** Redirect record mapping old slugs to content items (migration 0007). */
+export interface ContentSlugRedirectRow {
+	old_slug: string
+	content_id: string
+	created_at: number
+}
+
+// ---------------------------------------------------------------------------
+// Masthead platform tables (migrations 0008–0011)
+// ---------------------------------------------------------------------------
+
+/**
+ * Role union for workspace members (migration 0009).
+ * NOTE: this must stay in sync with CmsRole in src/routes/context.ts — one is
+ * re-exported from the other to keep a single source of truth.
+ */
+export type CmsRole = 'owner' | 'senior_editor' | 'editor' | 'contributor' | 'producer'
+
+/** Per-workspace publication settings (migration 0008). */
+export interface WorkspaceSettingsRow {
+	workspace_id: string
+	publication_name: string | null
+	tagline: string | null
+	language: string
+	timezone: string
+	require_review: number
+	auto_seo: number
+	scheduled_publish: number
+	premium_default: number
+	accent_color: string | null
+	display_typeface: string | null
+	logo_r2_key: string | null
+	created_at: number
+	updated_at: number
+}
+
+/**
+ * Mirror of the OpenAuth subject for profile/name caching (migration 0009).
+ * INTEGER timestamps per content convention (diverges from inbox's TEXT).
+ */
+export interface MastheadUserRow {
+	id: string
+	email: string
+	name: string | null
+	image: string | null
+	last_login_at: number | null
+	created_at: number
+	updated_at: number
+}
+
+/** Workspace membership keyed on OpenAuth subject (migration 0009). */
+export interface WorkspaceMembershipRow {
+	workspace_id: string
+	user_id: string
+	role: CmsRole
+	invited_by: string | null
+	invited_at: number | null
+	accepted_at: number | null
+	created_at: number
+	updated_at: number
+}
+
+/** Pending workspace invitation (migration 0009). */
+export interface WorkspaceInviteRow {
+	id: string
+	workspace_id: string
+	email: string
+	role: CmsRole
+	invited_by: string
+	token_hash: string
+	expires_at: number
+	accepted_at: number | null
+	created_at: number
+}
+
+/**
+ * CMS API key. key_hash is a SHA-256 hex of the raw key. The raw key is
+ * NEVER stored here — only shown once on creation (migration 0010).
+ * key_prefix stores a safe display hint (e.g. 'mk_live_••••ab12') added
+ * in migration 0014 so the masked list can show prefix + last-4 chars.
+ */
+export interface CmsApiKeyRow {
+	id: string
+	workspace_id: string
+	name: string
+	key_hash: string
+	/** JSON-encoded string array of scope identifiers. */
+	scopes: string
+	created_at: number
+	last_used: number | null
+	/** Display hint: '<prefix>••••<last4>' — stored on create, never the raw key. */
+	key_prefix: string | null
+}
+
+/**
+ * Outbound webhook registration. HMAC secret lives in the Secrets Store, NEVER
+ * in D1 (spec §12 + risk 7) — there is deliberately no secret column here
+ * (migration 0010).
+ */
+export interface CmsWebhookRow {
+	id: string
+	workspace_id: string
+	event_type: string
+	url: string
+	last_status: string | null
+	last_fired_at: number | null
+	created_at: number
+}
+
+/** In-app notification for a workspace member (migration 0011). */
+export interface CmsNotificationRow {
+	id: string
+	workspace_id: string
+	user_id: string
+	kind: string
+	body: string | null
+	read_at: number | null
+	created_at: number
+}
+
+/** Audit/activity log entry (migration 0011). */
+export interface CmsActivityLogRow {
+	id: string
+	workspace_id: string
+	user_id: string | null
+	action: string
+	target_id: string | null
+	target_title: string | null
+	type: string | null
+	created_at: number
+}
+
+// ---------------------------------------------------------------------------
+// Content import staging (migration 0012)
+// ---------------------------------------------------------------------------
+
+/**
+ * Staged import record for content ingested from an external source (e.g.
+ * RSS, Ghost export, Substack). status: 'pending' | 'processing' | 'done' |
+ * 'error'. payload_json holds the raw import data before normalization.
+ */
+export interface ContentImportRow {
+	id: string
+	workspace_id: string
+	source: string
+	status: string
+	payload_json: string | null
+	created_at: number
+}
+
+// ---------------------------------------------------------------------------
+// Media normalization notes (migration 0013 — non-destructive, index only)
+// ---------------------------------------------------------------------------
+//
+// MediaAssetRow.asset_type reconciliation (spec §4/§13.8):
+//   - 'podcast' = published podcast episode audio asset
+//   - 'audio'   = any other audio asset (music, SFX, general audio)
+// Both values are valid and must remain queryable. Media pickers query both.
+// public_url is the canonical delivery URL (migration 0013 adds an index on
+// it for fast lookup by URL). Do NOT normalize 'podcast' → 'audio'.
+//
+// See migration 0013_media_normalization.sql for the idx_media_assets_public_url
+// index creation (IF NOT EXISTS — safe on any existing DB).
+
+// ---------------------------------------------------------------------------
+// Content Insights shared types (migration 0016)
+// ---------------------------------------------------------------------------
+// Shared Content Insights TS types — imported/mirrored by BOTH the Foundry
+// capability (discover.content_insights) and the CMS package (@growth-labs/cms).
+// Row types mirror migration 0016 column-for-column: a NOT NULL column maps to a
+// required non-nullable field; a nullable column maps to `T | null` (D1 returns
+// SQL NULL as JS null) — the same convention as the content tables above.
+
+/** content_insights.suggestion_type CHECK domain. */
+export type InsightSuggestionType = 'cluster' | 'tracker'
+
+/** content_insights.signal_type CHECK domain. */
+export type InsightSignalType = 'demand' | 'opportunity'
+
+/** content_insight_runs.status CHECK domain. */
+export type InsightRunStatus = 'running' | 'completed' | 'partial' | 'failed'
+
+/** Beat facet — secondary topical facet (geographic theater lives in desk). */
+export type InsightBeat = 'defense' | 'intelligence' | 'diplomacy' | 'analysis'
+
+/** Demand evidence chip (signal_type='demand'): the real GSC metric. */
+export interface InsightEvidenceDemand {
+	query: string
+	impressions: number
+	clicks: number
+	/** Click-through rate, 0..1. */
+	ctr: number
+	/** Average GSC position (lower is better; permission zone ~5..20). */
+	position: number
+	/** Impression delta vs the prior window (signed). */
+	trend: number
+}
+
+/** Opportunity evidence chip (signal_type='opportunity'): validated-research basis. */
+export interface InsightEvidenceOpportunity {
+	/** One-line statement of the validated editorial basis. */
+	basis: string
+	/** Count of cite-or-cut validated sources backing the idea. */
+	source_count: number
+}
+
+/** content_insights.evidence — JSON stored as TEXT NOT NULL, zod-validated. */
+export type InsightEvidence = InsightEvidenceDemand | InsightEvidenceOpportunity
+
+/** Which open-web discovery stream produced an opportunity row (theater split). */
+export type DiscoveryKind = 'competitor' | 'audience_question'
+
+/** One recent competitor article — the COMPETITOR-WATCH pulse evidence. */
+export interface InsightCompetitorArticle {
+	title: string
+	url: string
+	outlet?: string
+	published?: string
+	/** true → the article's topic is already in our pipeline (flagged, NOT dropped). */
+	covered?: boolean
+}
+
+/** content_insights.brief — JSON stored as TEXT NOT NULL, zod-validated. */
+export interface InsightBrief {
+	why_now: string
+	angle: string
+	cluster: {
+		canonical: string
+		spokes: string[]
+	}
+	sources: Array<{ title: string; url: string }>
+	/**
+	 * Which open-web discovery STREAM produced this opportunity row (the theater
+	 * split): 'competitor' (RSS competitor-watch) vs 'audience_question' (Google
+	 * PAA reader questions). Optional + back-compat (an old opportunity row renders
+	 * as the legacy single Opportunity stream). Lives in the opaque brief TEXT blob
+	 * — no DB migration — but the ingest zod schema MUST mirror it (Zod strips
+	 * unknown brief keys), or the board never sees it.
+	 */
+	discoveryKind?: DiscoveryKind
+	/** COMPETITOR-WATCH pulse: the recent rival articles per theater (raw signal). */
+	competitor_articles?: InsightCompetitorArticle[]
+}
+
+/**
+ * A content_insights row (the suggestion). `evidence` and `brief` are TEXT
+ * columns in D1; this is the DECODED, in-memory shape after JSON.parse +
+ * zod validation. The wire/DB string forms are decoded at the route boundary.
+ */
+export interface ContentInsightRow {
+	id: string
+	site_id: string
+	run_id: string
+	/** YYYY-MM-DD. */
+	run_date: string
+	/** primary_topic desk slug. */
+	desk: string
+	suggestion_type: InsightSuggestionType
+	signal_type: InsightSignalType
+	/** 0 | 1. */
+	is_best_bet: number
+	/** Cross-desk Best Bets rank; NULL when not a best bet. */
+	best_bet_rank: number | null
+	/** Within-desk display order. */
+	desk_rank: number
+	/** The question/headline. */
+	headline: string
+	/** Decoded evidence chip (TEXT column in D1). */
+	evidence: InsightEvidence
+	/** Decoded mini-brief (TEXT column in D1). */
+	brief: InsightBrief
+	/** Stable dedup/dismissal key — see deriveIntentKey. */
+	intent_key: string
+	/** Secondary topical facet (geographic theater lives in desk). */
+	beat: InsightBeat | null
+	/** Unix epoch seconds. */
+	created_at: number
+}
+
+/** A content_insight_runs row (per-(site_id, run_date) replay guard, UNIQUE). */
+export interface ContentInsightRunRow {
+	id: string
+	site_id: string
+	run_date: string
+	status: InsightRunStatus
+	/** Dedupe key (mirrors foundry_callback_events.event_id). */
+	event_id: string
+	/** Monotonic; the stale-replay guard rejects equal-or-lower. */
+	run_attempt: number
+	/** Unix epoch seconds the board was generated. */
+	generated_at: number
+	/** Content hash of the board for change detection. */
+	content_hash: string
+	demand_count: number
+	opportunity_count: number
+	started_at: number | null
+	completed_at: number | null
+	error: string | null
+}
+
+/** A content_insight_dismissals row (PK (site_id, intent_key)). */
+export interface ContentInsightDismissalRow {
+	site_id: string
+	intent_key: string
+	dismissed_at: number
+	dismissed_by: string | null
+}
+
+/**
+ * Schema version for the intent_key derivation. Bump ONLY on a breaking change
+ * to the canonical-cluster-id semantics; bumping rotates every intent_key (and
+ * therefore drops every existing dismissal) so treat as a migration event.
+ */
+export const INTENT_KEY_VERSION = 1
+
+/** Stable inputs to the intent_key hash. NOT headline-based. */
+export interface IntentKeyInput {
+	/** Canonical cluster/intent id (the stable identity of the topic). */
+	canonicalClusterId: string
+	/** primary_topic desk slug. */
+	desk: string
+	signalType: InsightSignalType
+	/** Defaults to INTENT_KEY_VERSION. */
+	version?: number
+}
+
+/**
+ * intent_key = stable hash of (canonicalClusterId + desk + signalType +
+ * version). The canonical string is the lowercased, ''-joined tuple; the
+ * hash is lowercase hex SHA-256 (Web Crypto). BOTH sides MUST derive it
+ * identically — rephrasing a headline must not lose a dismissal, and the same
+ * headline across distinct intents must not collide.
+ */
+export async function deriveIntentKey(input: IntentKeyInput): Promise<string> {
+	const version = input.version ?? INTENT_KEY_VERSION
+	const canonical = [
+		input.canonicalClusterId.trim().toLowerCase(),
+		input.desk.trim().toLowerCase(),
+		input.signalType,
+		String(version),
+	].join('')
+	const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonical))
+	return Array.from(new Uint8Array(digest))
+		.map((b) => b.toString(16).padStart(2, '0'))
+		.join('')
+}

package/src/ui/api/_authz.ts

@@ -0,0 +1,100 @@
+// src/ui/api/_authz.ts — default Authz builder for the package's own endpoint
+// adapters. Reads Astro.locals.user (populated by the host's auth middleware)
+// and maps the host session to a CmsUser.
+//
+// IMPORTANT: the real user subject must come from the host's OpenAuth integration
+// (e.g. @growth-labs/auth), never a placeholder id. This default reads whatever
+// the host populates on locals.user; the host overrides this at mount with its
+// own production authz/providers glue (spec §15).
+//
+// NOTE (P7 Task 12): the stale rank map (owner/admin/editor/author/viewer) has been
+// superseded. requireRole now resolves capability tokens against the 5-role matrix
+// (owner/senior_editor/editor/contributor/producer) via CAPABILITY_MATRIX + roleCan
+// from authz-matrix.ts. 'admin', 'author', 'viewer' are not valid CmsRole values.
+//
+// TODO(host): the Fronts cutover PR replaces this with src/lib/cms-providers.ts authz
+// which injects the real buildMatrixAuthz wired to the D1 workspace_memberships table.
+import type { APIContext } from 'astro'
+import { CAPABILITY_MATRIX, roleCan } from '../../routes/authz-matrix.js'
+import type { Authz, Capability, CmsRole, CmsUser, RouteContext } from '../../routes/context.js'
+
+interface LocalsUser {
+	subject?: string
+	email?: string
+	role?: string
+	name?: string
+}
+
+// Admin-level roles — owner only for destructive/operational gates.
+const ADMIN_ROLES: ReadonlySet<string> = new Set(['owner'])
+// Publisher-level roles — all 5 roles are workspace members and may publish (within their capability).
+const PUBLISHER_ROLES: ReadonlySet<string> = new Set([
+	'owner',
+	'senior_editor',
+	'editor',
+	'contributor',
+	'producer',
+])
+
+export function buildSiteAuthz(c: APIContext): Authz {
+	return {
+		requireAdmin(_ctx: RouteContext): Response | null {
+			const user = getLocalsUser(c)
+			if (!user || !ADMIN_ROLES.has(user.role ?? '')) {
+				return new Response(JSON.stringify({ error: 'Unauthorized' }), {
+					status: 401,
+					headers: { 'Content-Type': 'application/json' },
+				})
+			}
+			return null
+		},
+		requirePublisher(_ctx: RouteContext): Response | null {
+			const user = getLocalsUser(c)
+			if (!user || !PUBLISHER_ROLES.has(user.role ?? '')) {
+				return new Response(JSON.stringify({ error: 'Unauthorized' }), {
+					status: 401,
+					headers: { 'Content-Type': 'application/json' },
+				})
+			}
+			return null
+		},
+		async getUser(_ctx: RouteContext): Promise<CmsUser | null> {
+			const user = getLocalsUser(c)
+			if (!user?.subject) return null
+			// Only accept valid 5-role values — reject stale 'admin'/'author'/'viewer'.
+			if (!PUBLISHER_ROLES.has(user.role ?? '')) return null
+			return {
+				subject: user.subject,
+				email: user.email ?? null,
+				role: user.role as CmsRole,
+				name: user.name ?? null,
+			}
+		},
+		requireRole(cap: Capability, _ctx: RouteContext): Response | null {
+			const user = getLocalsUser(c)
+			if (!user?.subject || !PUBLISHER_ROLES.has(user.role ?? '')) {
+				return new Response(JSON.stringify({ error: 'Unauthorized' }), {
+					status: 401,
+					headers: { 'Content-Type': 'application/json' },
+				})
+			}
+			// Resolve via the 5-role capability matrix (supersedes the stale rank map).
+			const role = user.role as CmsRole
+			if (!roleCan(role, cap)) {
+				return new Response(JSON.stringify({ error: 'Forbidden', required: cap, role }), {
+					status: 403,
+					headers: { 'Content-Type': 'application/json' },
+				})
+			}
+			return null
+		},
+	}
+}
+
+function getLocalsUser(c: APIContext): LocalsUser | null {
+	const locals = c.locals as { user?: LocalsUser }
+	return locals.user ?? null
+}
+
+// Re-export CAPABILITY_MATRIX for convenience (host glue may need it for UI hints).
+export { CAPABILITY_MATRIX }