@growth-labs/cms 0.8.20 → 0.8.24

package/src/ui/screens/SurveyResponsesScreen.tsx

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import type { CmsRole } from '../../schema/types.js'
-import { canViewSurveyVerbatims } from '../../surveys/access.js'
+import { canLabelSurveyAnswers, canViewSurveyVerbatims } from '../../surveys/access.js'
 import {
 	isSurveyErrorCode,
 	SURVEY_ERROR_CODE_HEADER,
@@ -8,6 +8,7 @@ import {
 	type SurveyErrorCode,
 } from '../../surveys/errors.js'
 import {
+	type SurveyAnswerLabel,
 	type SurveyQuestion,
 	type SurveyResults,
 	SurveyResultsSchema,
@@ -58,6 +59,7 @@ const PAGE_SIZE = 100
 export function SurveyResponsesScreen({ surveyId }: { surveyId: string }) {
 	const [state, setState] = useState<SurveyResponsesState>({ kind: 'loading' })
 	const [offset, setOffset] = useState(0)
+	const [labelSaveFailed, setLabelSaveFailed] = useState(false)
 	const load = useCallback(
 		async (nextOffset: number) => {
 			setState({ kind: 'loading' })
@@ -73,6 +75,40 @@ export function SurveyResponsesScreen({ surveyId }: { surveyId: string }) {
 		[surveyId],
 	)
 
+	// Owner-only classification toggle: on success the label is applied to the
+	// already-loaded page (no refetch); on failure the toggle stays honest on
+	// its old value and a note says the save did not land.
+	const setLabel = useCallback(
+		async (responseId: string, questionId: string, label: SurveyAnswerLabel) => {
+			setLabelSaveFailed(false)
+			try {
+				const response = await fetch(
+					`/admin/api/surveys/${encodeURIComponent(surveyId)}/answers/label`,
+					{
+						method: 'POST',
+						headers: { 'Content-Type': 'application/json' },
+						body: JSON.stringify({ responseId, questionId, label }),
+					},
+				)
+				if (!response.ok) {
+					setLabelSaveFailed(true)
+					return
+				}
+				setState((previous) =>
+					previous.kind === 'ready'
+						? {
+								kind: 'ready',
+								data: withAnswerLabel(previous.data, responseId, questionId, label),
+							}
+						: previous,
+				)
+			} catch {
+				setLabelSaveFailed(true)
+			}
+		},
+		[surveyId],
+	)
+
 	useEffect(() => {
 		void load(offset)
 	}, [load, offset])
@@ -87,10 +123,30 @@ export function SurveyResponsesScreen({ surveyId }: { surveyId: string }) {
 			role={workspace.user?.role ?? null}
 			onRetry={() => void load(offset)}
 			onOffsetChange={setOffset}
+			onSetLabel={setLabel}
+			labelSaveFailed={labelSaveFailed}
 		/>
 	)
 }
 
+function withAnswerLabel(
+	data: SurveyResults,
+	responseId: string,
+	questionId: string,
+	label: SurveyAnswerLabel,
+): SurveyResults {
+	return {
+		...data,
+		freeText: data.freeText.map((entry) =>
+			entry.responseId === responseId && entry.questionId === questionId
+				? // A successful owner save stores source 'owner' server-side; the
+					// optimistic copy reflects that instead of a stale 'auto' badge.
+					{ ...entry, label, labelSource: 'owner' }
+				: entry,
+		),
+	}
+}
+
 export function SurveyResponsesBody({
 	surveyId,
 	state,
@@ -98,6 +154,8 @@ export function SurveyResponsesBody({
 	role = null,
 	onRetry,
 	onOffsetChange,
+	onSetLabel,
+	labelSaveFailed = false,
 }: {
 	surveyId: string
 	state: SurveyResponsesState
@@ -105,8 +163,11 @@ export function SurveyResponsesBody({
 	role?: CmsRole | null
 	onRetry?: () => void
 	onOffsetChange?: (offset: number) => void
+	onSetLabel?: (responseId: string, questionId: string, label: SurveyAnswerLabel) => void
+	labelSaveFailed?: boolean
 }) {
 	const canSeeVerbatims = canViewSurveyVerbatims(role)
+	const canLabel = canLabelSurveyAnswers(role)
 
 	if (state.kind === 'loading') return <StatusPage title="Loading survey responses…" />
 	if (state.kind === 'forbidden')
@@ -172,7 +233,24 @@ export function SurveyResponsesBody({
 					<HeadlineScale questions={data.questions} />
 
 					{canSeeVerbatims ? (
-						<VerbatimFeed data={data} />
+						<>
+							{canLabel && (data.unlabeledCount ?? 0) > 0 ? (
+								<p className="page-sub" role="status" style={{ marginTop: 24 }}>
+									{unlabeledAnswersNotice(data.unlabeledCount ?? 0)}
+								</p>
+							) : null}
+							{canLabel && (data.personalDetailsCount ?? 0) > 0 ? (
+								<p className="page-sub" role="status" style={{ marginTop: 24 }}>
+									{personalDetailsNotice(data.personalDetailsCount ?? 0)}
+								</p>
+							) : null}
+							{labelSaveFailed && canLabel ? (
+								<p className="page-sub" role="alert" style={{ marginTop: 24 }}>
+									The last label change could not be saved. Try again.
+								</p>
+							) : null}
+							<VerbatimFeed data={data} canLabel={canLabel} onSetLabel={onSetLabel} />
+						</>
 					) : (
 						<div className="card" role="status" style={{ marginTop: 24 }}>
 							<h2 className="card-title">Individual answers are restricted</h2>
@@ -215,7 +293,7 @@ export function SurveyResponsesBody({
 // distribution keeps one harsh verbatim from setting the tone of a readout.
 function HeadlineScale({ questions }: { questions: SurveyResults['questions'] }) {
 	const scale = questions.find((question) => question.kind === 'scale')
-	if (!scale || scale.kind !== 'scale' || scale.answerCount === 0) return null
+	if (scale?.kind !== 'scale' || scale.answerCount === 0) return null
 	const midpoint = (scale.options.min + scale.options.max) / 2
 	const favourable = Object.entries(scale.distribution)
 		.filter(([value]) => Number(value) > midpoint)
@@ -234,23 +312,75 @@ function HeadlineScale({ questions }: { questions: SurveyResults['questions'] })
 	)
 }
 
-function VerbatimFeed({ data }: { data: SurveyResults }) {
+type WrittenAnswer = SurveyResults['freeText'][number]
+
+// The owner's loud surface for answers auto-labeling has not placed yet
+// (publishing #24): everything unlabeled is hidden from the team, so he sees
+// the backlog instead of a silent one-warn in the logs.
+function unlabeledAnswersNotice(count: number): string {
+	return `${
+		count === 1
+			? '1 written answer on this page isn’t labeled yet.'
+			: `${count} written answers on this page aren’t labeled yet.`
+	} They’re hidden from the team until labeled. Automatic labeling runs in the background; reload in a minute, or label them yourself.`
+}
+
+// The subset the personal-details pre-filter will never dispatch: only the
+// owner can label these, so he is told directly rather than left a backlog.
+function personalDetailsNotice(count: number): string {
+	return count === 1
+		? '1 answer contains personal details and needs your label.'
+		: `${count} answers contain personal details and need your label.`
+}
+
+function VerbatimFeed({
+	data,
+	canLabel,
+	onSetLabel,
+}: {
+	data: SurveyResults
+	canLabel: boolean
+	onSetLabel?: (responseId: string, questionId: string, label: SurveyAnswerLabel) => void
+}) {
+	const [labelFilter, setLabelFilter] = useState<'all' | 'general' | 'technical'>('all')
 	const textQuestionIds = new Set(
 		data.questions.filter((question) => question.kind === 'text').map((question) => question.id),
 	)
 	const promptById = new Map(data.questions.map((question) => [question.id, question.prompt]))
-	const freeTextByResponse = new Map<string, string[]>()
-	for (const entry of data.freeText) {
+	// Non-owners never receive technical or unlabeled entries (the route filters
+	// server-side), so for them this feed is already the general thread.
+	const visibleFreeText =
+		labelFilter === 'all' ? data.freeText : data.freeText.filter((e) => e.label === labelFilter)
+	const freeTextByResponse = new Map<string, WrittenAnswer[]>()
+	for (const entry of visibleFreeText) {
 		const entries = freeTextByResponse.get(entry.responseId) ?? []
-		entries.push(entry.value)
+		entries.push(entry)
 		freeTextByResponse.set(entry.responseId, entries)
 	}
 
 	return (
 		<section aria-labelledby="survey-verbatims" style={{ marginTop: 24 }}>
-			<h2 className="page-title" id="survey-verbatims" style={{ fontSize: 22 }}>
-				Responses
-			</h2>
+			<div className="page-head">
+				<h2 className="page-title" id="survey-verbatims" style={{ fontSize: 22 }}>
+					Responses
+				</h2>
+				{canLabel ? (
+					// biome-ignore lint/a11y/useSemanticElements: chip-row is a flex div throughout the admin UI; a fieldset would import UA border/padding with no reset in the publication CSS, while role="group" + aria-label keeps the grouping semantics
+					<div className="chip-row" role="group" aria-label="Filter written answers">
+						{(['all', 'general', 'technical'] as const).map((option) => (
+							<button
+								className="chip"
+								key={option}
+								type="button"
+								aria-pressed={labelFilter === option}
+								onClick={() => setLabelFilter(option)}
+							>
+								{option === 'all' ? 'All' : option === 'general' ? 'General' : 'Technical'}
+							</button>
+						))}
+					</div>
+				) : null}
+			</div>
 			<div style={{ marginTop: 12 }}>
 				{data.responses.map((response) => {
 					const written = freeTextByResponse.get(response.id) ?? []
@@ -266,9 +396,45 @@ function VerbatimFeed({ data }: { data: SurveyResults }) {
 							{written.length === 0 ? (
 								<p className="page-sub">No written answer.</p>
 							) : (
-								written.map((value, index) => (
-									// biome-ignore lint/suspicious/noArrayIndexKey: values are free text with no stable id
-									<blockquote key={`${response.id}:${index}`}>{value}</blockquote>
+								written.map((entry) => (
+									<div key={`${response.id}:${entry.questionId}`}>
+										<blockquote>{entry.value}</blockquote>
+										{canLabel && onSetLabel ? (
+											// biome-ignore lint/a11y/useSemanticElements: chip-row is a flex div throughout the admin UI; a fieldset would import UA border/padding with no reset in the publication CSS, while role="group" + aria-label keeps the grouping semantics
+											<div
+												className="chip-row"
+												role="group"
+												aria-label={`Classify the written answer from ${response.id}`}
+											>
+												<button
+													className="chip"
+													type="button"
+													aria-pressed={entry.label === 'technical'}
+													onClick={() =>
+														onSetLabel(entry.responseId, entry.questionId, 'technical')
+													}
+												>
+													Technical
+												</button>
+												<button
+													className="chip"
+													type="button"
+													aria-pressed={entry.label === 'general'}
+													onClick={() => onSetLabel(entry.responseId, entry.questionId, 'general')}
+												>
+													General
+												</button>
+												{entry.labelSource === 'auto' ? (
+													<span
+														className="chip"
+														title="Labeled automatically — your choice overrides it"
+													>
+														auto
+													</span>
+												) : null}
+											</div>
+										) : null}
+									</div>
 								))
 							)}
 							<div className="chip-row">

package/src/ui/screens/analytics-data.ts

@@ -18,6 +18,24 @@ export interface AnalyticsData {
 	trafficSources: ProviderResult<TrafficSource[]>
 }
 
+/**
+ * Caption for the traffic-sources panel: the metric is sessions summed from
+ * fact_content_source_daily, which only covers content pages — not the whole
+ * site (report P0-1).
+ */
+export const TRAFFIC_SOURCES_CAPTION = 'sessions by source — content pages only'
+
+/**
+ * Label for the unique-visitors KPI tile (report P0-2). Ranges inside the
+ * ~90-day WAE retention window report true range uniques ("Unique
+ * visitors"); longer ranges report sum ÷ days, which the screen must never
+ * present as uniques. The 90 here mirrors the provider's
+ * RANGE_UNIQUES_MAX_DAYS.
+ */
+export function uniqueVisitorsKpiLabel(rangeDays: number): string {
+	return Number.isFinite(rangeDays) && rangeDays > 90 ? 'Avg daily visitors' : 'Unique visitors'
+}
+
 type ProviderStatus = ProviderResult<unknown>['status']
 
 function providerStatus(value: unknown): ProviderStatus {

package/src/ui/screens/podcast-listening-data.ts

@@ -0,0 +1,114 @@
+import type { PodcastListening, PodcastListeningEpisode } from '../../providers/types.js'
+
+export type PodcastSortKey =
+	| 'episode'
+	| 'plays'
+	| 'listeners'
+	| 'reached10'
+	| 'reached25'
+	| 'reached50'
+	| 'reached75'
+	| 'reached90'
+	| 'completes'
+	| 'completionRate'
+	| 'totalListeningSeconds'
+
+/** Defensive read of one metric: a non-finite value renders as 0, not NaN. */
+function num(value: unknown): number {
+	const n = typeof value === 'number' ? value : Number(value)
+	return Number.isFinite(n) ? n : 0
+}
+
+function normalizeEpisode(input: unknown): PodcastListeningEpisode | null {
+	if (!input || typeof input !== 'object') return null
+	const row = input as Record<string, unknown>
+	const slug = typeof row.slug === 'string' ? row.slug : ''
+	const hasListening = typeof row.totalListeningSeconds === 'number'
+	const listening = hasListening ? num(row.totalListeningSeconds) : null
+	const listeners = num(row.listeners)
+	return {
+		slug,
+		...(typeof row.title === 'string' && row.title.length > 0 ? { title: row.title } : {}),
+		plays: num(row.plays),
+		listeners,
+		reached10: num(row.reached10),
+		reached25: num(row.reached25),
+		reached50: num(row.reached50),
+		reached75: num(row.reached75),
+		reached90: num(row.reached90),
+		completes: num(row.completes),
+		completionRate: num(row.completionRate),
+		totalListeningSeconds: listening,
+		avgListeningSecondsPerListener:
+			listening !== null && listeners > 0 ? listening / listeners : null,
+	}
+}
+
+/**
+ * Normalize the GET /admin/api/analytics?type=podcastListening body. The route
+ * returns the provider's PodcastListening verbatim; this keeps a malformed
+ * host payload from crashing the screen — broken rows drop, broken numbers
+ * read as 0, and a body that is not a PodcastListening at all yields null
+ * (rendered as the explicit unavailable state, never silent zeros).
+ */
+export function normalizePodcastListening(input: unknown): PodcastListening | null {
+	if (!input || typeof input !== 'object') return null
+	const body = input as Record<string, unknown>
+	if (!Array.isArray(body.episodes)) return null
+	const episodes = body.episodes
+		.map(normalizeEpisode)
+		.filter((e): e is PodcastListeningEpisode => e !== null)
+	const totalsRow = body.totals as Record<string, unknown> | undefined
+	const totals = totalsRow ?? {}
+	const rangeRow = body.range as Record<string, unknown> | undefined
+	return {
+		episodes,
+		totals: {
+			episodes: num(totals.episodes),
+			plays: num(totals.plays),
+			listeners: num(totals.listeners),
+			completes: num(totals.completes),
+			completionRate: num(totals.completionRate),
+			totalListeningSeconds:
+				typeof totals.totalListeningSeconds === 'number' ? num(totals.totalListeningSeconds) : null,
+		},
+		range: {
+			from: typeof rangeRow?.from === 'string' ? rangeRow.from : '',
+			to: typeof rangeRow?.to === 'string' ? rangeRow.to : '',
+		},
+	}
+}
+
+/**
+ * Sort episodes for the table. `episode` sorts by display title then slug;
+ * every metric sorts descending-first (the interesting end), then ascending on
+ * the second click.
+ */
+export function sortEpisodes(
+	episodes: readonly PodcastListeningEpisode[],
+	key: PodcastSortKey,
+	dir: 'asc' | 'desc',
+): PodcastListeningEpisode[] {
+	const factor = dir === 'asc' ? 1 : -1
+	return [...episodes].sort((a, b) => {
+		if (key === 'episode') {
+			const cmp = episodeLabel(a).localeCompare(episodeLabel(b))
+			return factor * cmp
+		}
+		const av = a[key]
+		const bv = b[key]
+		// Unmeasured listening time always sinks to the bottom regardless of
+		// direction — it is an unknown, not a small number.
+		if (av === null && bv === null) return episodeLabel(a).localeCompare(episodeLabel(b))
+		if (av === null) return 1
+		if (bv === null) return -1
+		if (av === bv) return episodeLabel(a).localeCompare(episodeLabel(b))
+		return factor * (av - bv)
+	})
+}
+
+/** The table's display name: the D1 title, the slug, or the unattributed label. */
+export function episodeLabel(episode: Pick<PodcastListeningEpisode, 'slug' | 'title'>): string {
+	if (episode.slug === 'unattributed') return '(unattributed episodes)'
+	return episode.title && episode.title.length > 0 ? episode.title : episode.slug
+}

package/src/ui/screens/registry.tsx

@@ -21,6 +21,7 @@ import { ContentInsightsScreen } from './ContentInsightsScreen.js'
 import { ContentRoute } from './ContentRoute.js'
 import { DashboardScreen } from './DashboardScreen.js'
 import { MediaScreen } from './MediaScreen.js'
+import { PodcastListeningScreen } from './PodcastListeningScreen.js'
 import { SettingsScreen } from './SettingsScreen.js'
 import { SocialShareScreen } from './SocialShareScreen.js'
 import { SubscriptionsScreen } from './SubscriptionsScreen.js'
@@ -67,6 +68,7 @@ export function createCmsScreens({
 		calendar: () => <CalendarRoute />,
 		media: () => <MediaScreen />,
 		analytics: () => <AnalyticsScreen />,
+		podcasts: () => <PodcastListeningScreen />,
 		authors: () => <AuthorsScreen />,
 		topics: () => <TopicsScreen />,
 		subscriptions: () => <SubscriptionsScreen />,