@growth-labs/cms 0.1.0

package/src/ui/screens/media-upload.ts

@@ -0,0 +1,283 @@
+export type MediaUploadKind = 'image' | 'video' | 'podcast'
+
+export interface MediaUploadResult {
+	id: string
+	url: string | null
+	sourceKind?: string | null
+	processingStatus?: string | null
+	videoId?: string | null
+}
+
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>
+
+interface UploadMediaAssetInput {
+	kind: MediaUploadKind
+	file: File
+	slug?: string
+	fetchImpl?: FetchLike
+}
+
+interface VideoInitResponse {
+	uploadId?: string
+	key?: string
+	partSize?: number
+}
+
+interface VideoPartResponse {
+	part?: {
+		partNumber?: number
+		etag?: string
+	}
+}
+
+interface VideoCompleteResponse {
+	key?: string
+	sourceUrl?: string
+	sourceKind?: string
+	processingStatus?: string
+	videoId?: string
+}
+
+interface AudioInitResponse {
+	uploadId?: string
+	key?: string
+	partSize?: number
+}
+
+interface AudioPartResponse {
+	part?: {
+		partNumber?: number
+		etag?: string
+	}
+}
+
+interface AudioCompleteResponse {
+	key?: string
+	publicUrl?: string
+}
+
+export function buildMediaUploadSlug(fileName: string): string {
+	const basename = fileName.replace(/\.[^.]+$/, '')
+	const slug = basename
+		.toLowerCase()
+		.replace(/['"`]/g, '')
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+		.replace(/--+/g, '-')
+	return slug || 'media-upload'
+}
+
+async function readJson<T>(response: Response): Promise<T> {
+	return (await response.json().catch(() => ({}))) as T
+}
+
+async function assertOk<T>(response: Response, fallback: string): Promise<T> {
+	const body = await readJson<T & { error?: string }>(response)
+	if (!response.ok) {
+		throw new Error(body.error || fallback)
+	}
+	return body
+}
+
+function formDataFor(file: File, slug: string): FormData {
+	const formData = new FormData()
+	formData.set('file', file)
+	formData.set('slug', slug)
+	return formData
+}
+
+async function uploadFormMedia(
+	endpoint: string,
+	file: File,
+	slug: string,
+	fetchImpl: FetchLike,
+): Promise<Record<string, unknown>> {
+	const response = await fetchImpl(endpoint, {
+		method: 'POST',
+		body: formDataFor(file, slug),
+	})
+	return assertOk<Record<string, unknown>>(response, 'Media upload failed')
+}
+
+export async function uploadMediaAsset(input: UploadMediaAssetInput): Promise<MediaUploadResult> {
+	const fetchImpl = input.fetchImpl ?? fetch
+	const slug = input.slug?.trim() || buildMediaUploadSlug(input.file.name)
+
+	if (input.kind === 'image') {
+		const body = await uploadFormMedia('/admin/api/media/images', input.file, slug, fetchImpl)
+		const id = String(body.imageId || body.imageKey || body.publicUrl || input.file.name)
+		return {
+			id,
+			url:
+				typeof body.url === 'string'
+					? body.url
+					: typeof body.publicUrl === 'string'
+						? body.publicUrl
+						: null,
+		}
+	}
+
+	if (input.kind === 'podcast') {
+		if (input.file.size <= 0) {
+			throw new Error('Podcast audio file is empty')
+		}
+
+		let uploadId: string | null = null
+		let key: string | null = null
+		try {
+			const initResponse = await fetchImpl('/admin/api/media/podcast/init', {
+				method: 'POST',
+				headers: { 'content-type': 'application/json' },
+				body: JSON.stringify({
+					slug,
+					fileName: input.file.name,
+					contentType: input.file.type || null,
+					sizeBytes: input.file.size,
+				}),
+			})
+			const init = await assertOk<AudioInitResponse>(
+				initResponse,
+				'Could not start podcast audio upload',
+			)
+			uploadId = init.uploadId || null
+			key = init.key || null
+			const partSize = Number(init.partSize)
+			if (!uploadId || !key || !Number.isFinite(partSize) || partSize <= 0) {
+				throw new Error('Podcast audio upload did not return a valid multipart session')
+			}
+
+			const parts: Array<{ partNumber: number; etag: string }> = []
+			let partNumber = 1
+			for (let offset = 0; offset < input.file.size; offset += partSize) {
+				const chunk = await input.file.slice(offset, offset + partSize).arrayBuffer()
+				const partResponse = await fetchImpl(
+					`/admin/api/media/podcast/part?key=${encodeURIComponent(key)}&uploadId=${encodeURIComponent(uploadId)}&partNumber=${partNumber}`,
+					{ method: 'PUT', body: chunk },
+				)
+				const partBody = await assertOk<AudioPartResponse>(
+					partResponse,
+					'Could not upload podcast audio part',
+				)
+				const etag = partBody.part?.etag
+				const returnedPartNumber = partBody.part?.partNumber
+				if (!etag || returnedPartNumber !== partNumber) {
+					throw new Error('Podcast audio upload part response was invalid')
+				}
+				parts.push({ partNumber, etag })
+				partNumber += 1
+			}
+
+			const completeResponse = await fetchImpl('/admin/api/media/podcast/complete', {
+				method: 'POST',
+				headers: { 'content-type': 'application/json' },
+				body: JSON.stringify({
+					slug,
+					key,
+					uploadId,
+					fileName: input.file.name,
+					contentType: input.file.type || null,
+					sizeBytes: input.file.size,
+					parts,
+				}),
+			})
+			const complete = await assertOk<AudioCompleteResponse>(
+				completeResponse,
+				'Could not complete podcast audio upload',
+			)
+			return {
+				id: complete.key || key,
+				url: complete.publicUrl || null,
+			}
+		} catch (error) {
+			if (uploadId && key) {
+				await fetchImpl('/admin/api/media/podcast/abort', {
+					method: 'POST',
+					headers: { 'content-type': 'application/json' },
+					body: JSON.stringify({ key, uploadId }),
+				}).catch(() => undefined)
+			}
+			throw error
+		}
+	}
+
+	if (input.file.size <= 0) {
+		throw new Error('Video file is empty')
+	}
+
+	let uploadId: string | null = null
+	let key: string | null = null
+	try {
+		const initResponse = await fetchImpl('/admin/api/media/videos/init', {
+			method: 'POST',
+			headers: { 'content-type': 'application/json' },
+			body: JSON.stringify({
+				videoId: slug,
+				fileName: input.file.name,
+				contentType: input.file.type || null,
+				sizeBytes: input.file.size,
+			}),
+		})
+		const init = await assertOk<VideoInitResponse>(initResponse, 'Could not start video upload')
+		uploadId = init.uploadId || null
+		key = init.key || null
+		const partSize = Number(init.partSize)
+		if (!uploadId || !key || !Number.isFinite(partSize) || partSize <= 0) {
+			throw new Error('Video upload did not return a valid multipart session')
+		}
+
+		const parts: Array<{ partNumber: number; etag: string }> = []
+		let partNumber = 1
+		for (let offset = 0; offset < input.file.size; offset += partSize) {
+			const chunk = await input.file.slice(offset, offset + partSize).arrayBuffer()
+			const partResponse = await fetchImpl(
+				`/admin/api/media/videos/part?key=${encodeURIComponent(key)}&uploadId=${encodeURIComponent(uploadId)}&partNumber=${partNumber}`,
+				{ method: 'PUT', body: chunk },
+			)
+			const partBody = await assertOk<VideoPartResponse>(
+				partResponse,
+				'Could not upload video part',
+			)
+			const etag = partBody.part?.etag
+			const returnedPartNumber = partBody.part?.partNumber
+			if (!etag || returnedPartNumber !== partNumber) {
+				throw new Error('Video upload part response was invalid')
+			}
+			parts.push({ partNumber, etag })
+			partNumber += 1
+		}
+
+		const completeResponse = await fetchImpl('/admin/api/media/videos/complete', {
+			method: 'POST',
+			headers: { 'content-type': 'application/json' },
+			body: JSON.stringify({
+				key,
+				uploadId,
+				videoId: slug,
+				fileName: input.file.name,
+				contentType: input.file.type || null,
+				sizeBytes: input.file.size,
+				parts,
+			}),
+		})
+		const complete = await assertOk<VideoCompleteResponse>(
+			completeResponse,
+			'Could not complete video upload',
+		)
+		return {
+			id: complete.key || key,
+			url: complete.sourceUrl || null,
+			sourceKind: complete.sourceKind || 'http_url',
+			processingStatus: complete.processingStatus || 'processing',
+			videoId: complete.videoId || slug,
+		}
+	} catch (error) {
+		if (uploadId && key) {
+			await fetchImpl('/admin/api/media/videos/abort', {
+				method: 'POST',
+				headers: { 'content-type': 'application/json' },
+				body: JSON.stringify({ key, uploadId }),
+			}).catch(() => undefined)
+		}
+		throw error
+	}
+}

package/src/ui/screens/public-url.ts

@@ -0,0 +1,81 @@
+// src/ui/screens/public-url.ts — pure per-content public URL helper.
+//
+// Derives the Fronts public URL for a content item from its slug + type so the
+// per-content Share action can pre-fill `destinationUrl` in the Social Share
+// builder without knowing the live origin at build time.
+//
+// Path mapping is sourced from the confirmed Fronts page structure:
+//   article    → /article/<slug>       (src/pages/article/[slug].astro)
+//   podcast    → /podcast/<slug>       (src/pages/podcast/[slug].astro)
+//   video      → /video/<slug>         (src/pages/video/[slug].astro)
+//   newsletter → /warfronts-weekly/<slug>
+//                                      (src/pages/warfronts-weekly/[slug].astro)
+//
+// SOURCE OF TRUTH for the path scheme: the Fronts site page structure at
+//   /Users/zephyr/projects/fulcrum-labs/fronts/src/pages/
+// and Fronts lib/content.ts line ~779 (`/warfronts-weekly/${row.slug}/`).
+// If the Fronts path scheme changes, update CONTENT_PUBLIC_PATH below.
+//
+// The helper is pure: no DOM, no fetch, no `window`. `siteBase` is injected
+// by the caller (the SocialShareScreen / ShareModal reads it from workspace
+// config or defaults to a relative path). This keeps the function testable
+// under plain vitest.
+
+import type { ContentType } from '../../schema/types.js'
+
+// ---------------------------------------------------------------------------
+// Path table
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps each CMS `ContentType` to a function that returns its Fronts public
+ * path segment (WITHOUT a leading or trailing slash duplication risk — the
+ * helper always joins via `/${path}/${slug}`).
+ *
+ * Newsletter maps to the Fronts `warfronts-weekly` path, which is the
+ * site-specific canonical for the `newsletter` content type on Fronts.co.
+ * This is a one-line change if a future site uses a different newsletter path.
+ */
+const CONTENT_PUBLIC_PATH: Record<ContentType, (slug: string) => string> = {
+	article: (slug) => `/article/${slug}`,
+	podcast: (slug) => `/podcast/${slug}`,
+	video: (slug) => `/video/${slug}`,
+	// newsletter type maps to the warfronts-weekly path on Fronts.co.
+	// SOURCE: fronts/src/pages/warfronts-weekly/[slug].astro
+	//         fronts/src/lib/content.ts ~L779
+	newsletter: (slug) => `/warfronts-weekly/${slug}`,
+}
+
+// ---------------------------------------------------------------------------
+// publicUrlFor
+// ---------------------------------------------------------------------------
+
+/**
+ * Derives the Fronts public URL for a content item given its `type` and
+ * `slug`, optionally joined onto a `siteBase`.
+ *
+ * - **With `siteBase`** (e.g. `'https://fronts.co'`): returns the absolute
+ *   URL — any trailing slashes on `siteBase` are stripped before joining.
+ * - **Without `siteBase`** (or `undefined`): returns a relative path
+ *   (e.g. `'/article/my-piece'`) — still valid for pre-filling
+ *   `destinationUrl` once the operator corrects the origin after mount.
+ *
+ * Slugs that accidentally start with a slash are trimmed to avoid
+ * double-slash paths.
+ *
+ * @param row      - The content item (needs `type` and `slug`).
+ * @param siteBase - Optional absolute origin (e.g. `'https://fronts.co'`).
+ *                   Trailing slashes are stripped. Omit for a relative path.
+ * @returns The public URL string.
+ */
+export function publicUrlFor(row: { type: ContentType; slug: string }, siteBase?: string): string {
+	const cleanSlug = row.slug.replace(/^\/+/, '')
+	const path = CONTENT_PUBLIC_PATH[row.type](cleanSlug)
+
+	if (!siteBase) {
+		return path
+	}
+
+	const base = siteBase.replace(/\/+$/, '')
+	return `${base}${path}`
+}

package/src/ui/screens/registry.tsx

@@ -0,0 +1,53 @@
+// src/ui/screens/registry.tsx — the P1 ScreenRegistry supplied to <CmsApp/>.
+//
+// P5 adds dashboard/analytics/subscriptions/calendar entries.
+// P7 adds media/authors/topics/social-share/settings entries. Any route id
+// without an entry here resolves to EmptyRoute inside CmsApp.
+//
+// openDoc seam: DashboardScreen and CalendarScreen accept an `openDoc` prop
+// that lets users navigate to the content editor from within those screens.
+// The registry wraps them in thin components that navigate to #/content — a
+// navigate-to-content fallback that avoids coupling registry.tsx to CmsApp's
+// internal router state (which is not exported). The ContentRoute itself owns
+// the full open-doc reducer (which doc is open, new vs existing).
+
+import type { ScreenRegistry } from '../components/CmsApp.js'
+import { useHashRouter } from '../use-hash-router.js'
+import { AnalyticsScreen } from './AnalyticsScreen.js'
+import { AuthorsScreen } from './AuthorsScreen.js'
+import { CalendarScreen } from './CalendarScreen.js'
+import { ContentInsightsScreen } from './ContentInsightsScreen.js'
+import { ContentRoute } from './ContentRoute.js'
+import { DashboardScreen } from './DashboardScreen.js'
+import { MediaScreen } from './MediaScreen.js'
+import { SettingsScreen } from './SettingsScreen.js'
+import { SocialShareScreen } from './SocialShareScreen.js'
+import { SubscriptionsScreen } from './SubscriptionsScreen.js'
+import { TopicsScreen } from './TopicsScreen.js'
+
+// Thin wrappers that supply the openDoc seam for screens that need it.
+// On click, we navigate to the content route; the ContentRoute will handle
+// any subsequent doc-open action (e.g. the user picks a doc from the library).
+function DashboardRoute() {
+	const { navigate } = useHashRouter()
+	return <DashboardScreen openDoc={() => navigate('content')} />
+}
+
+function CalendarRoute() {
+	const { navigate } = useHashRouter()
+	return <CalendarScreen openDoc={() => navigate('content')} />
+}
+
+export const cmsScreens: ScreenRegistry = {
+	content: () => <ContentRoute />,
+	'content-insights': () => <ContentInsightsScreen />,
+	dashboard: () => <DashboardRoute />,
+	calendar: () => <CalendarRoute />,
+	media: () => <MediaScreen />,
+	analytics: () => <AnalyticsScreen />,
+	authors: () => <AuthorsScreen />,
+	topics: () => <TopicsScreen />,
+	subscriptions: () => <SubscriptionsScreen />,
+	'social-share': () => <SocialShareScreen />,
+	settings: () => <SettingsScreen />,
+}

package/src/ui/screens/render-state.ts

@@ -0,0 +1,228 @@
+// src/ui/screens/render-state.ts — pure render-state helpers for the inject screens.
+//
+// No React, no D1, no browser globals. Pure data-in / data-out helpers used by
+// the Dashboard, Analytics, Subscriptions, and Calendar screens to apply the
+// live/partial/empty + null→"pending" honesty convention.
+//
+// Helpers:
+//   selectKpiState    — extract the ProviderStatus from a ProviderResult
+//   formatKpi         — number|null → formatted string or { pending: true } sentinel
+//   mergeTopContent   — join analytics provider top-content ids with D1 titles
+//   splitNeedsAttention — group content rows into dashboard queue items with pill labels
+//   planMixToBars     — plan-mix buckets → bar segments with resolved names + pct
+
+import type { ProviderResult, ProviderStatus } from '../../providers/types.js'
+
+// ---------------------------------------------------------------------------
+// selectKpiState
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the ProviderStatus from a ProviderResult.
+ * Used by every card to branch on live/partial/empty rendering.
+ * Null-safe: a provider that returns a null/absent result is treated as
+ * 'empty' rather than throwing on `.status` (that crash blanked the whole
+ * analytics screen, which has no per-card boundary).
+ */
+export function selectKpiState<T>(result: ProviderResult<T> | null | undefined): ProviderStatus {
+	return result?.status ?? 'empty'
+}
+
+// ---------------------------------------------------------------------------
+// formatKpi
+// ---------------------------------------------------------------------------
+
+export type KpiFormat = 'num' | 'pct' | 'usd'
+
+/** Sentinel returned by formatKpi when the value is null. */
+export interface KpiPending {
+	pending: true
+}
+
+/**
+ * Format a KPI value for display.
+ *
+ * - `null` → `{ pending: true }` (renders as "— pending backfill", never as "0")
+ * - `'num'` (default) → comma-separated integer string (e.g. 2160 → "2,160")
+ * - `'pct'` → one-decimal percent (e.g. 0.021 → "2.1%")
+ * - `'usd'` → dollar-prefixed, no cents when whole (e.g. 186 → "$186"; 186.5 → "$186.50")
+ */
+export function formatKpi(value: number | null, fmt: KpiFormat = 'num'): string | KpiPending {
+	if (value === null) {
+		return { pending: true }
+	}
+
+	switch (fmt) {
+		case 'pct': {
+			return `${(value * 100).toFixed(1)}%`
+		}
+		case 'usd': {
+			const rounded = Math.round(value * 100) / 100
+			const isWhole = rounded === Math.floor(rounded)
+			return isWhole ? `$${rounded.toLocaleString('en-US')}` : `$${rounded.toFixed(2)}`
+		}
+		default: {
+			// 'num' — comma-separated, no decimals
+			return Math.round(value).toLocaleString('en-US')
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// mergeTopContent
+// ---------------------------------------------------------------------------
+
+/**
+ * A top-content item as returned by AnalyticsProvider.getTopContent.
+ * The title field is optional — some providers supply it, others only give ids.
+ */
+export interface TopContentProvider {
+	id: string
+	title?: string
+	reads: number
+}
+
+/** A merged top-content item with a D1-sourced title (or null when unavailable). */
+export interface TopContentMerged {
+	id: string
+	title: string | null
+	reads: number
+}
+
+/**
+ * Join analytics provider top-content items with a D1 titles map.
+ *
+ * The D1 title (from content_items) takes precedence when present.
+ * If neither the D1 map nor the provider supplies a title, the result is null
+ * (honest: the screen renders "—" or omits the title column).
+ *
+ * Order is preserved from `providerTop` (highest reads first, as ranked by provider).
+ */
+export function mergeTopContent(
+	providerTop: TopContentProvider[],
+	titlesById: Record<string, string>,
+): TopContentMerged[] {
+	return providerTop.map((item) => ({
+		id: item.id,
+		title: titlesById[item.id] ?? item.title ?? null,
+		reads: item.reads,
+	}))
+}
+
+// ---------------------------------------------------------------------------
+// splitNeedsAttention
+// ---------------------------------------------------------------------------
+
+/** Pill labels for the needs-attention queue. */
+export type AttentionPill = 'review' | 'processing' | 'scheduled' | 'draft'
+
+/**
+ * A content row as returned by the dashboard summary route's needsAttention array.
+ * Mirrors the server-side shape (same fields as LibraryRow minus visibility/featured/authorName).
+ */
+export interface NeedsAttentionRow {
+	id: string
+	type: string
+	status: string
+	slug: string
+	title: string
+	publishAt: string | null
+	processingState: string | null
+}
+
+/** A queue item with the resolved pill label for dashboard rendering. */
+export interface AttentionItem {
+	id: string
+	type: string
+	status: string
+	slug: string
+	title: string
+	publishAt: string | null
+	pill: AttentionPill
+}
+
+const NON_PROCESSING_STATES = new Set(['ready', 'failed'])
+
+/**
+ * Convert a flat list of content rows into dashboard queue items with pill labels.
+ *
+ * Rules:
+ * - published rows are excluded (they are fine, not attention-worthy)
+ * - a video row with a mid-flight processingState (not null/ready/failed) → pill = "processing"
+ * - otherwise pill mirrors the row status (review/scheduled/draft)
+ */
+export function splitNeedsAttention(rows: NeedsAttentionRow[]): AttentionItem[] {
+	const result: AttentionItem[] = []
+
+	for (const row of rows) {
+		if (row.status === 'published') continue
+
+		let pill: AttentionPill
+
+		const isMidFlight =
+			row.processingState !== null && !NON_PROCESSING_STATES.has(row.processingState)
+
+		if (isMidFlight) {
+			pill = 'processing'
+		} else if (row.status === 'review') {
+			pill = 'review'
+		} else if (row.status === 'scheduled') {
+			pill = 'scheduled'
+		} else {
+			// draft + archived + anything else — show as draft
+			pill = 'draft'
+		}
+
+		result.push({
+			id: row.id,
+			type: row.type,
+			status: row.status,
+			slug: row.slug,
+			title: row.title,
+			publishAt: row.publishAt,
+			pill,
+		})
+	}
+
+	return result
+}
+
+// ---------------------------------------------------------------------------
+// planMixToBars
+// ---------------------------------------------------------------------------
+
+/** A plan-mix bucket from SubscriptionsProvider.getPlanMix. */
+export interface PlanMixBucket {
+	plan: string
+	count: number
+}
+
+/** A resolved bar segment for the plan-mix chart. */
+export interface PlanMixBar {
+	name: string
+	count: number
+	/** Percentage of total subscribers (0–100, rounds to 2 dp). */
+	pct: number
+}
+
+/**
+ * Convert plan-mix provider buckets into bar segments with resolved display names and
+ * percentages.
+ *
+ * `resolvePlanName` is the sync resolver from SubscriptionsProvider (echoes the id
+ * when no map is configured — honest default until the Fronts impl ships).
+ *
+ * pct values sum to 100 (within floating-point tolerance).
+ */
+export function planMixToBars(
+	planMix: PlanMixBucket[],
+	resolvePlanName: (variantId: string) => string,
+): PlanMixBar[] {
+	const total = planMix.reduce((acc, b) => acc + b.count, 0)
+
+	return planMix.map((bucket) => ({
+		name: resolvePlanName(bucket.plan),
+		count: bucket.count,
+		pct: total === 0 ? 0 : (bucket.count / total) * 100,
+	}))
+}