@growth-labs/cms 0.1.0

package/src/routes/context.ts

@@ -0,0 +1,146 @@
+// The framework-agnostic request surface the CMS route handlers operate over
+// (WS7-07). The package ships mountable handlers — pure
+// `(ctx: RouteContext) => Promise<Response>` functions — so any site (Astro,
+// Workers, Hono, …) can wire them in with a thin adapter. NOTHING here binds
+// Fronts' Astro `APIContext`, `cloudflare:workers` `env`, or
+// `context.locals.user`/`isAdmin`. Auth/authz is INJECTED via {@link Authz};
+// the D1 binding + R2 bucket are passed on the context.
+//
+// See the Fronts adapter (the site supplies the glue): each Astro route does
+//   export const POST = (c) => createContentRoutes(config).create(toCtx(c))
+// where `toCtx` maps the Astro `APIContext` (+ `env.SITE_DB`, `env.PUBLIC_MEDIA`,
+// and the site's own authz impl) onto a RouteContext.
+
+import type { D1Database } from '../engine/d1.js'
+import type { CmsRole } from '../schema/types.js'
+
+export type { CmsRole }
+
+/**
+ * Capability tokens used by the 5-role permission matrix (authz-matrix.ts).
+ * Defined here so the Authz interface can reference them without a circular
+ * import — authz-matrix.ts re-exports this type from context.ts.
+ */
+export type Capability =
+	| 'publish_article'
+	| 'publish_video'
+	| 'edit_own_draft'
+	| 'publish_others_draft'
+	| 'submit_for_review'
+	| 'media_pipeline'
+	| 'manage_team'
+	| 'manage_settings'
+	| 'manage_api_keys'
+	| 'manage_webhooks'
+	// Subscriber-PII export (CSV/JSON of member emails). Gated to owner +
+	// senior_editor — NOT editor (editors keep full editorial but no PII).
+	| 'export_subscribers'
+
+export interface CmsUser {
+	subject: string
+	email: string | null
+	role: CmsRole
+	name?: string | null
+}
+
+/**
+ * The minimal R2 surface the media routes use. Declared structurally (the real
+ * workerd `R2Bucket` is assignable) so the package does not depend on
+ * `@cloudflare/workers-types`. The video-multipart routes need the multipart
+ * methods; image/podcast uploads need only `put`.
+ */
+export interface R2UploadedPart {
+	partNumber: number
+	etag: string
+}
+
+export interface R2MultipartUpload {
+	readonly key: string
+	readonly uploadId: string
+	uploadPart(partNumber: number, value: ArrayBuffer | ArrayBufferView): Promise<R2UploadedPart>
+	abort(): Promise<void>
+	complete(uploadedParts: R2UploadedPart[]): Promise<unknown>
+}
+
+export interface R2HeadResult {
+	size: number
+}
+
+export interface R2BucketLike {
+	put(
+		key: string,
+		value: ArrayBuffer | ArrayBufferView | ReadableStream | string | null,
+		options?: {
+			httpMetadata?: { contentType?: string; cacheControl?: string }
+			customMetadata?: Record<string, string>
+		},
+	): Promise<unknown>
+	delete(key: string | string[]): Promise<void>
+	head?(key: string): Promise<R2HeadResult | null>
+	createMultipartUpload?(
+		key: string,
+		options?: {
+			httpMetadata?: { contentType?: string; cacheControl?: string }
+			customMetadata?: Record<string, string>
+		},
+	): Promise<R2MultipartUpload>
+	resumeMultipartUpload?(key: string, uploadId: string): R2MultipartUpload
+}
+
+/**
+ * The authz contract the consuming site supplies. The package NEVER decides who
+ * is an admin/publisher — it asks the site. A guard returns `null` when the
+ * caller is authorized, or a `Response` (typically 401) to short-circuit the
+ * handler. This mirrors the Fronts `requireAdmin`/`requirePublisher` shape
+ * (admin-api.ts) without baking in `ADMIN_EMAILS`/`context.locals.user`.
+ */
+export interface Authz {
+	/** Gate for destructive/operational routes (e.g. cron publish). */
+	requireAdmin(ctx: RouteContext): Response | null | Promise<Response | null>
+	/** Gate for the publishing surface (content/authors/media CRUD). */
+	requirePublisher(ctx: RouteContext): Response | null | Promise<Response | null>
+	/** OPTIONAL (Masthead role layer — lands fully in P7). Resolve the current user. */
+	getUser?(ctx: RouteContext): Promise<CmsUser | null> | CmsUser | null
+	/** OPTIONAL. Gate a route by capability; null = allowed, Response = short-circuit (401/403). */
+	requireRole?(cap: Capability, ctx: RouteContext): Response | null | Promise<Response | null>
+}
+
+/**
+ * Everything a handler needs, framework-agnostic. The site's adapter builds
+ * this from its own request object + bindings + authz impl.
+ */
+export interface RouteContext {
+	/** The inbound request (standard Fetch `Request`). */
+	request: Request
+	/** Route params (e.g. `{ id }` for `/content/[id]`). */
+	params: Record<string, string | undefined>
+	/** The site's D1 binding. */
+	db: D1Database
+	/** The site's R2 media bucket (required for the media upload routes). */
+	bucket?: R2BucketLike
+	/**
+	 * Identity of the actor, for revision authorship (`content_revisions.created_by`).
+	 * The site resolves this from its own session; the package only reads it.
+	 */
+	userId?: string | null
+	/**
+	 * Arbitrary site env/config the injected hooks may need (e.g. the Foundry
+	 * dispatch hook reads FOUNDRY_URL from here). The package itself does not
+	 * read secrets from this — it only forwards it to injected hooks.
+	 */
+	env?: Record<string, unknown>
+}
+
+export function json(body: unknown, status = 200): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { 'Content-Type': 'application/json' },
+	})
+}
+
+/** Resolve the route param `id`, returning a 400 response when absent. */
+export function requireId(ctx: RouteContext): { id: string } | { error: Response } {
+	const id = ctx.params.id
+	if (!id) return { error: json({ error: 'Missing id' }, 400) }
+	return { id }
+}

package/src/routes/cron.ts

@@ -0,0 +1,27 @@
+// Scheduled-publish trigger route (WS7-07). Ported from fulcrum-labs/fronts
+// src/pages/api/v1/publisher/cron/publish.ts (inventory §3: extract). Calls the
+// already-extracted engine `runScheduledPublish`. Gated by the injected
+// `requireAdmin` (NOT requirePublisher — this is an operational trigger).
+
+import { runScheduledPublish } from '../engine/cron.js'
+import type { CmsRouteConfig } from './config.js'
+import { resolveConfig } from './config.js'
+import { json, type RouteContext } from './context.js'
+
+export interface CronRouteHandlers {
+	/** POST /cron/publish — run the scheduled-publish sweep. */
+	publish(ctx: RouteContext): Promise<Response>
+}
+
+export function createCronRoutes(config: CmsRouteConfig): CronRouteHandlers {
+	const resolved = resolveConfig(config)
+	return {
+		async publish(ctx) {
+			const denied = await resolved.authz.requireAdmin(ctx)
+			if (denied) return denied
+
+			const result = await runScheduledPublish(ctx.db, { createdBy: ctx.userId || null })
+			return json({ published: result.published.length })
+		},
+	}
+}

package/src/routes/dashboard.ts

@@ -0,0 +1,174 @@
+// src/routes/dashboard.ts — Dashboard summary route factory (P5 Task 4).
+// Returns first-party D1 data (needs-attention queue, published-7d count,
+// activity feed, top-content titles) plus provider-backed cards (reads/avg-time
+// from AnalyticsProvider, subscriber count from SubscriptionsProvider).
+// Every provider-backed field carries its ProviderResult {status, data} envelope.
+// First-party D1 fields are live (or empty when there are no rows).
+
+import { nullProviders } from '../providers/null.js'
+import type { CmsProviders } from '../providers/types.js'
+import type { Authz, RouteContext } from './context.js'
+import { json } from './context.js'
+
+export interface DashboardRouteConfig {
+	authz: Authz
+	activeWorkspaceId?: string
+	providers?: Partial<CmsProviders>
+}
+
+export interface DashboardRouteHandlers {
+	summary(ctx: RouteContext): Promise<Response>
+}
+
+export function createDashboardRoutes(config: DashboardRouteConfig): DashboardRouteHandlers {
+	const providers: CmsProviders = { ...nullProviders, ...(config.providers ?? {}) }
+	const workspaceId = config.activeWorkspaceId ?? 'default'
+
+	return {
+		async summary(ctx: RouteContext): Promise<Response> {
+			const denied = await config.authz.requirePublisher(ctx)
+			if (denied) return denied
+
+			const now = Math.floor(Date.now() / 1000)
+			const sevenDaysAgo = now - 7 * 24 * 60 * 60
+
+			// Default date range for provider calls (last 30 days)
+			const range = { from: now - 30 * 24 * 60 * 60, to: now }
+
+			// Run first-party D1 queries and provider calls in parallel
+			const [
+				attnResult,
+				publishedCountResult,
+				activityResult,
+				topContentD1Result,
+				readsResult,
+				subscribersResult,
+				topContentProviderResult,
+			] = await Promise.all([
+				// Needs-attention: draft + review + scheduled + mid-processing (not deleted/archived)
+				ctx.db
+					.prepare(
+						`SELECT c.id, c.type, c.status, c.slug, c.title, c.publish_at, c.updated_at,
+							vc.processing_state
+						FROM content_items c
+						LEFT JOIN video_content vc ON vc.content_id = c.id
+						WHERE c.deleted_at IS NULL
+							AND c.status != 'archived'
+							AND (c.status IN ('draft','review','scheduled')
+								OR (vc.processing_state IS NOT NULL
+									AND vc.processing_state NOT IN ('ready','failed')))
+						ORDER BY c.updated_at DESC
+						LIMIT 50`,
+					)
+					.all<{
+						id: string
+						type: string
+						status: string
+						slug: string
+						title: string
+						publish_at: number | null
+						updated_at: number | null
+						processing_state: string | null
+					}>(),
+
+				// Published in last 7 days count
+				ctx.db
+					.prepare(
+						`SELECT COUNT(*) AS cnt
+						FROM content_items
+						WHERE deleted_at IS NULL
+							AND status = 'published'
+							AND published_at >= ?`,
+					)
+					.bind(sevenDaysAgo)
+					.first<{ cnt: number }>(),
+
+				// Activity feed: last 12 rows for this workspace
+				ctx.db
+					.prepare(
+						`SELECT id, user_id, action, target_id, target_title, type, created_at
+						FROM cms_activity_log
+						WHERE workspace_id = ?
+						ORDER BY created_at DESC
+						LIMIT 12`,
+					)
+					.bind(workspaceId)
+					.all<{
+						id: string
+						user_id: string | null
+						action: string
+						target_id: string | null
+						target_title: string | null
+						type: string | null
+						created_at: number
+					}>(),
+
+				// Top content titles from D1 (ids only; reads come from provider)
+				ctx.db
+					.prepare(
+						`SELECT id, title
+						FROM content_items
+						WHERE deleted_at IS NULL AND status = 'published'
+						ORDER BY published_at DESC
+						LIMIT 20`,
+					)
+					.all<{ id: string; title: string }>(),
+
+				// Provider: analytics KPIs (reads / avg-time)
+				providers.analytics.getKpis(range),
+
+				// Provider: subscriptions KPIs (active subscriber count)
+				providers.subscriptions.getKpis(),
+
+				// Provider: top content by reads
+				providers.analytics.getTopContent(range),
+			])
+
+			// Map D1 snake_case rows → camelCase NeedsAttentionRow shape so the
+			// render-state helper (splitNeedsAttention) can safely reference processingState
+			// and publishAt without a structural cast silently swallowing the mismatch.
+			const attnRows = (attnResult.results ?? []).map((r) => ({
+				id: r.id,
+				type: r.type,
+				status: r.status,
+				slug: r.slug,
+				title: r.title,
+				publishAt: r.publish_at != null ? String(r.publish_at) : null,
+				processingState: r.processing_state,
+			}))
+			const publishedCount = publishedCountResult?.cnt ?? 0
+
+			const activityRows = activityResult.results ?? []
+			const activity =
+				activityRows.length > 0
+					? { status: 'live' as const, data: activityRows }
+					: { status: 'empty' as const, data: [] as typeof activityRows }
+
+			// Build a titles-by-id map from first-party D1
+			const titlesById: Record<string, string> = {}
+			for (const row of topContentD1Result.results ?? []) {
+				titlesById[row.id] = row.title
+			}
+
+			// Hydrate provider top-content with D1 titles where available
+			const providerTopItems = topContentProviderResult.data ?? []
+			const topContentData = providerTopItems.map((item) => ({
+				...item,
+				title: titlesById[item.id] ?? item.title,
+			}))
+			const topContent = {
+				status: topContentProviderResult.status,
+				data: topContentData,
+			}
+
+			return json({
+				needsAttention: attnRows,
+				publishedCount,
+				activity,
+				reads: readsResult,
+				subscribers: subscribersResult,
+				topContent,
+			})
+		},
+	}
+}

package/src/routes/imports.ts

@@ -0,0 +1,190 @@
+// Import route handlers — two-step parse→confirm pipeline.
+//
+// Staging table: content_imports (0012). KV-session staging (from the
+// prototype design) is replaced by D1 rows — the package has D1, not KV.
+// This substitution is intentional and documented.
+//
+//   POST /content/import/parse   → stage a content_imports row (status=pending)
+//                                    + return a parsed preview
+//   POST /content/import/confirm → call createContent for each staged item,
+//                                    flip the import status to done
+
+import { z } from 'zod'
+import { parseGhost, parseMarkdown, parseSubstackCsv } from '../engine/import-parsers.js'
+import { createContent, ensureUniqueSlug } from '../engine/publisher.js'
+import type { CmsRouteConfig } from './config.js'
+import { resolveConfig } from './config.js'
+import { type Authz, type Capability, json, type RouteContext } from './context.js'
+
+/**
+ * Bulk content import stages + creates many (cross-author) items, so it gates on
+ * publish_others_draft (owner / senior_editor / editor — NOT contributor/
+ * producer) via requireRole when the host wires the role seam, falling back to
+ * the flat requirePublisher gate otherwise.
+ */
+async function importGuard(authz: Authz, ctx: RouteContext): Promise<Response | null> {
+	if (authz.requireRole) {
+		return authz.requireRole('publish_others_draft' satisfies Capability, ctx)
+	}
+	return authz.requirePublisher(ctx)
+}
+
+export interface ImportRouteHandlers {
+	/** POST /content/import/parse — parse payload, stage content_imports row, return preview. */
+	parse(ctx: RouteContext): Promise<Response>
+	/** POST /content/import/confirm — confirm a staged import: create content items + mark done. */
+	confirm(ctx: RouteContext): Promise<Response>
+}
+
+// Supported import sources
+const SOURCES = ['markdown', 'ghost', 'substack-csv'] as const
+type ImportSource = (typeof SOURCES)[number]
+
+const ParseSchema = z.object({
+	source: z.enum(SOURCES),
+	payload: z.string().min(1),
+})
+
+const ConfirmSchema = z.object({
+	importId: z.string().min(1),
+})
+
+function generateId(): string {
+	// crypto.randomUUID is available in workerd + Node 14.17+
+	if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+		return crypto.randomUUID()
+	}
+	// Fallback: timestamp + random
+	return `${Date.now()}-${Math.random().toString(36).slice(2)}`
+}
+
+async function readJson(ctx: RouteContext): Promise<unknown> {
+	return ctx.request.json().catch(() => null)
+}
+
+function parsePayload(source: ImportSource, payload: string) {
+	switch (source) {
+		case 'markdown':
+			return parseMarkdown(payload)
+		case 'ghost':
+			return parseGhost(payload)
+		case 'substack-csv':
+			return parseSubstackCsv(payload)
+	}
+}
+
+export function createImportRoutes(config: CmsRouteConfig): ImportRouteHandlers {
+	const resolved = resolveConfig(config)
+
+	return {
+		async parse(ctx: RouteContext): Promise<Response> {
+			const guard = await importGuard(resolved.authz, ctx)
+			if (guard) return guard
+
+			const body = await readJson(ctx)
+			const parsed = ParseSchema.safeParse(body)
+			if (!parsed.success) {
+				return json({ error: 'Invalid request', issues: parsed.error.issues }, 400)
+			}
+
+			const { source, payload } = parsed.data
+
+			const items = parsePayload(source, payload)
+
+			const importId = generateId()
+			const now = Math.floor(Date.now() / 1000)
+
+			// Workspace id — use userId as a proxy when no workspace in context
+			const workspaceId = (ctx.env?.workspaceId as string | undefined) ?? 'default'
+
+			// Stage the import row with the parsed items as payload_json
+			await ctx.db
+				.prepare(
+					'INSERT INTO content_imports (id, workspace_id, source, status, payload_json, created_at) VALUES (?, ?, ?, ?, ?, ?)',
+				)
+				.bind(importId, workspaceId, source, 'pending', JSON.stringify(items), now)
+				.run()
+
+			return json({
+				importId,
+				source,
+				items: items.map((item) => ({
+					title: item.title,
+					slug: item.slug,
+					excerpt: item.excerpt ?? null,
+					bodyLength: item.bodyMarkdown.length,
+				})),
+			})
+		},
+
+		async confirm(ctx: RouteContext): Promise<Response> {
+			const guard = await importGuard(resolved.authz, ctx)
+			if (guard) return guard
+
+			const body = await readJson(ctx)
+			const parsed = ConfirmSchema.safeParse(body)
+			if (!parsed.success) {
+				return json({ error: 'Invalid request', issues: parsed.error.issues }, 400)
+			}
+
+			const { importId } = parsed.data
+
+			// Look up the staged import
+			const importRow = await ctx.db
+				.prepare('SELECT id, source, status, payload_json FROM content_imports WHERE id = ?')
+				.bind(importId)
+				.first<{ id: string; source: string; status: string; payload_json: string | null }>()
+
+			if (!importRow) {
+				return json({ error: 'Import not found', importId }, 404)
+			}
+
+			let items: Array<{
+				title: string
+				slug: string
+				bodyMarkdown: string
+				excerpt?: string | null
+			}> = []
+			try {
+				items = JSON.parse(importRow.payload_json ?? '[]') as typeof items
+			} catch {
+				return json({ error: 'Corrupt import payload', importId }, 500)
+			}
+
+			const createdIds: string[] = []
+			const defaultCategory = resolved.defaultPrimaryCategory ?? 'analysis'
+			const defaultTopic = resolved.defaultPrimaryTopic
+
+			for (const item of items) {
+				// Ensure unique slug before creating
+				const slug = await ensureUniqueSlug(ctx.db, item.slug)
+
+				const result = await createContent(ctx.db, {
+					type: 'article',
+					slug,
+					title: item.title,
+					excerpt: item.excerpt ?? null,
+					primaryCategory: defaultCategory,
+					primaryTopic: defaultTopic ?? null,
+					visibility: 'free',
+					content: {
+						bodyMarkdown: item.bodyMarkdown || ' ',
+					},
+				})
+
+				createdIds.push(result.id)
+			}
+
+			// Mark import as done
+			await ctx.db
+				.prepare('UPDATE content_imports SET status = ? WHERE id = ?')
+				.bind('done', importId)
+				.run()
+
+			return json({
+				importId,
+				created: createdIds,
+			})
+		},
+	}
+}