@liiift-studio/sanity-visitor-insights 0.1.0

package/src/studio/panels.tsx

@@ -0,0 +1,233 @@
+/**
+ * The four report panels.
+ *
+ * Every panel renders a table or labelled bars rather than a chart, and every one surfaces its own
+ * caveats inline. Tables are the accessible representation as well as the visual one, so there is
+ * no separate "view as data" toggle that could drift out of sync with what is displayed.
+ */
+
+import React from 'react'
+import { Box, Card, Flex, Heading, Stack, Text } from '@liiift-studio/sanity-ui-compat'
+import { ComparisonBar, MetricFigure, NoticeList, formatCount, formatPercent } from './Figure'
+import type {
+	AcquisitionData,
+	JourneyData,
+	MeasurementHealthData,
+	TypefaceInterestData,
+} from '../reportData'
+import type { MetricValue } from '../types'
+
+/** Largest available value across metrics, for scaling bars. */
+function maxOf(metrics: MetricValue[]): number {
+	return metrics.reduce((max, metric) => (metric.status === 'unavailable' ? max : Math.max(max, metric.value)), 0)
+}
+
+/** Shared table styling — scrolls inside its own container so the panel never scrolls sideways. */
+const tableWrap: React.CSSProperties = { overflowX: 'auto', width: '100%' }
+const table: React.CSSProperties = { width: '100%', borderCollapse: 'collapse', minWidth: 420 }
+const cell: React.CSSProperties = { padding: '8px 12px', textAlign: 'left', borderBottom: '1px solid var(--card-border-color)' }
+const numericCell: React.CSSProperties = { ...cell, textAlign: 'right' }
+
+/**
+ * Measurement Health — how much of reality each source sees.
+ * Compares pageviews to pageviews. Sessions and orders sit alongside as context and are never
+ * subtracted from a pageview count.
+ */
+export function MeasurementHealthPanel({ data }: { data: MeasurementHealthData }): React.ReactElement {
+	const pageviewMax = maxOf([data.ga4Pageviews, data.vercelPageviews])
+
+	return (
+		<Stack space={4}>
+			<Stack space={3}>
+				<Heading size={1}>Pageviews, source against source</Heading>
+				<Text size={1} muted>
+					The same unit on both sides. Vercel is cookieless and ungated; GA4 is consent-gated and
+					blockable, so GA4 seeing fewer is expected.
+				</Text>
+				<ComparisonBar label="Vercel pageviews" metric={data.vercelPageviews} max={pageviewMax} tone="primary" />
+				<ComparisonBar label="GA4 pageviews" metric={data.ga4Pageviews} max={pageviewMax} tone="default" />
+			</Stack>
+
+			{data.shortfallRatio !== null && (
+				<Card padding={3} radius={2} tone="transparent" border>
+					<Stack space={2}>
+						<Text size={1} weight="semibold">
+							GA4 shortfall: {formatPercent(Math.abs(data.shortfallRatio), 1)}
+						</Text>
+						<Text size={1} muted>{data.interpretation}</Text>
+					</Stack>
+				</Card>
+			)}
+
+			<Stack space={3}>
+				<Heading size={1}>Context</Heading>
+				<Text size={1} muted>
+					Different units to the figures above, and to each other. Shown for scale, never differenced.
+				</Text>
+				<Flex gap={4} wrap="wrap">
+					<Stack space={2}>
+						<Text size={1} muted>GA4 sessions</Text>
+						<MetricFigure metric={data.ga4Sessions} label="GA4 sessions" />
+					</Stack>
+					<Stack space={2}>
+						<Text size={1} muted>Orders</Text>
+						<MetricFigure metric={data.orders} label="Orders" />
+					</Stack>
+					<Stack space={2}>
+						<Text size={1} muted>Consent granted</Text>
+						<MetricFigure metric={data.consentRate} label="Consent granted, percent of sessions" />
+					</Stack>
+				</Flex>
+			</Stack>
+		</Stack>
+	)
+}
+
+/** Acquisition — where visitors came from, with design-industry referrers called out. */
+export function AcquisitionPanel({ data }: { data: AcquisitionData }): React.ReactElement {
+	return (
+		<Stack space={4}>
+			<Flex gap={4} wrap="wrap">
+				<Stack space={2}>
+					<Text size={1} muted>Sessions</Text>
+					<Text size={4}>{formatCount(data.totalSessions)}</Text>
+				</Stack>
+				{data.designIndustryShare !== null && (
+					<Stack space={2}>
+						<Text size={1} muted>From design-industry referrers</Text>
+						<Text size={4}>{formatPercent(data.designIndustryShare, 1)}</Text>
+					</Stack>
+				)}
+				{data.unattributedShare !== null && (
+					<Stack space={2}>
+						<Text size={1} muted>Unattributed</Text>
+						<Text size={4}>{formatPercent(data.unattributedShare, 1)}</Text>
+					</Stack>
+				)}
+			</Flex>
+
+			<Box style={tableWrap}>
+				<table style={table}>
+					<caption style={{ textAlign: 'left', paddingBottom: 8 }}>
+						<Text size={1} muted>Traffic sources by sessions</Text>
+					</caption>
+					<thead>
+						<tr>
+							<th scope="col" style={cell}><Text size={1} weight="semibold">Source</Text></th>
+							<th scope="col" style={cell}><Text size={1} weight="semibold">Channel</Text></th>
+							<th scope="col" style={numericCell}><Text size={1} weight="semibold">Sessions</Text></th>
+						</tr>
+					</thead>
+					<tbody>
+						{data.rows.map((row) => (
+							<tr key={`${row.source}-${row.channel}`}>
+								<th scope="row" style={cell}>
+									<Flex gap={2} align="center">
+										<Text size={1}>{row.source}</Text>
+										{row.designIndustry && <Text size={0} muted>· design industry</Text>}
+										{row.unattributed && <Text size={0} muted>· unattributed</Text>}
+									</Flex>
+								</th>
+								<td style={cell}><Text size={1} muted>{row.channel}</Text></td>
+								<td style={numericCell}><Text size={1}>{formatCount(row.sessions)}</Text></td>
+							</tr>
+						))}
+					</tbody>
+				</table>
+			</Box>
+
+			{data.rowsWithheld && (
+				<NoticeList notices={['GA4 withheld some low-traffic rows for privacy, so this list is shorter than reality.']} />
+			)}
+		</Stack>
+	)
+}
+
+/** Journey — per-step totals with adjacent drop-off, explicitly not a tracked path. */
+export function JourneyPanel({ data }: { data: JourneyData }): React.ReactElement {
+	const max = maxOf(data.steps.map((step) => step.count))
+
+	return (
+		<Stack space={4}>
+			<Card padding={3} radius={2} tone="caution" border>
+				<Text size={1}>{data.approximationNote}</Text>
+			</Card>
+
+			<Stack space={3}>
+				{data.steps.map((step) => (
+					<Stack space={2} key={step.key}>
+						<ComparisonBar label={step.label} metric={step.count} max={max} tone="primary" />
+						{step.conversionFromPrevious !== null && (
+							<Text size={0} muted>{formatPercent(step.conversionFromPrevious, 1)} of the previous measurable step</Text>
+						)}
+					</Stack>
+				))}
+			</Stack>
+
+			{data.topExitPages.length > 0 && (
+				<Stack space={3}>
+					<Heading size={1}>Where sessions ended</Heading>
+					<Box style={tableWrap}>
+						<table style={table}>
+							<thead>
+								<tr>
+									<th scope="col" style={cell}><Text size={1} weight="semibold">Page</Text></th>
+									<th scope="col" style={numericCell}><Text size={1} weight="semibold">Exits</Text></th>
+								</tr>
+							</thead>
+							<tbody>
+								{data.topExitPages.map((page) => (
+									<tr key={page.path}>
+										<th scope="row" style={cell}><Text size={1}>{page.path}</Text></th>
+										<td style={numericCell}><Text size={1}>{formatCount(page.exits)}</Text></td>
+									</tr>
+								))}
+							</tbody>
+						</table>
+					</Box>
+				</Stack>
+			)}
+		</Stack>
+	)
+}
+
+/** Typeface interest — viewed, tested and bought per family. */
+export function TypefaceInterestPanel({ data }: { data: TypefaceInterestData }): React.ReactElement {
+	return (
+		<Stack space={4}>
+			<Card padding={3} radius={2} tone="transparent" border>
+				<Text size={1} muted>{data.interpretationNote}</Text>
+			</Card>
+
+			<Box style={tableWrap}>
+				<table style={table}>
+					<caption style={{ textAlign: 'left', paddingBottom: 8 }}>
+						<Text size={1} muted>Engagement by typeface</Text>
+					</caption>
+					<thead>
+						<tr>
+							<th scope="col" style={cell}><Text size={1} weight="semibold">Typeface</Text></th>
+							<th scope="col" style={numericCell}><Text size={1} weight="semibold">Viewed</Text></th>
+							<th scope="col" style={numericCell}><Text size={1} weight="semibold">Tested</Text></th>
+							<th scope="col" style={numericCell}><Text size={1} weight="semibold">Bought</Text></th>
+							<th scope="col" style={numericCell}><Text size={1} weight="semibold">Test rate</Text></th>
+						</tr>
+					</thead>
+					<tbody>
+						{data.rows.map((row) => (
+							<tr key={row.typeface}>
+								<th scope="row" style={cell}><Text size={1}>{row.typeface}</Text></th>
+								<td style={numericCell}><MetricFigure metric={row.viewed} label={`${row.typeface} viewed`} size={1} /></td>
+								<td style={numericCell}><MetricFigure metric={row.tested} label={`${row.typeface} tested`} size={1} /></td>
+								<td style={numericCell}><MetricFigure metric={row.bought} label={`${row.typeface} bought`} size={1} /></td>
+								<td style={numericCell}>
+									<Text size={1} muted>{row.testRate === null ? '—' : formatPercent(row.testRate, 1)}</Text>
+								</td>
+							</tr>
+						))}
+					</tbody>
+				</table>
+			</Box>
+		</Stack>
+	)
+}

package/src/studio/useReport.ts

@@ -0,0 +1,99 @@
+/**
+ * Data hook for the Studio panels.
+ *
+ * Forwards the Studio's own Sanity session token to the site's API route, which verifies it against
+ * Sanity. There is no shared secret: the Studio bundle is public, so anything compiled into it is
+ * extractable.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { useClient } from 'sanity'
+import type { RangeKey, ReportEnvelope, ReportName } from '../types'
+
+/** Sanity API version this tool pins. Fixed rather than "latest" so behaviour cannot drift. */
+const API_VERSION = '2024-03-01'
+
+/** Loading state for a report. */
+export type ReportState<T> =
+	| { status: 'idle' }
+	| { status: 'loading' }
+	| { status: 'ready'; envelope: ReportEnvelope<T> }
+	| { status: 'error'; message: string }
+
+/** Options for useReport. */
+export interface UseReportOptions {
+	/** Base URL of the site serving the reports, e.g. `https://dardenstudio.com`. */
+	apiBaseUrl: string
+	report: ReportName
+	range: RangeKey
+}
+
+/**
+ * Fetch a report, re-fetching when the range changes.
+ *
+ * @returns the current state plus a `reload` for manual refresh
+ */
+export function useReport<T>({ apiBaseUrl, report, range }: UseReportOptions): {
+	state: ReportState<T>
+	reload: () => void
+} {
+	const client = useClient({ apiVersion: API_VERSION })
+	const [state, setState] = useState<ReportState<T>>({ status: 'idle' })
+	const [nonce, setNonce] = useState(0)
+
+	// Lets an in-flight response from a previous range be discarded rather than overwriting a newer one.
+	const requestIdRef = useRef(0)
+
+	const reload = useCallback(() => setNonce((n) => n + 1), [])
+
+	useEffect(() => {
+		const requestId = requestIdRef.current + 1
+		requestIdRef.current = requestId
+
+		const controller = new AbortController()
+		setState({ status: 'loading' })
+
+		async function run() {
+			// The Studio client carries the session token under token-based auth. Under cookie-based
+			// auth it does not, and there is no way to forward credentials the browser will not
+			// expose — so say so plainly rather than failing with an opaque 401.
+			const token = client.config().token
+			if (!token) {
+				setState({
+					status: 'error',
+					message: 'No Sanity session token available in this Studio. Visitor Insights needs token-based auth to call the site API.',
+				})
+				return
+			}
+
+			try {
+				const url = `${apiBaseUrl.replace(/\/$/, '')}/api/visitor-insights/${report}?range=${range}`
+				const response = await fetch(url, {
+					headers: { Authorization: `Bearer ${token}` },
+					signal: controller.signal,
+				})
+
+				if (requestIdRef.current !== requestId) return
+
+				if (!response.ok) {
+					const detail = response.status === 401 ? 'Not authorised — sign in to the Studio again.' : `Request failed (${response.status})`
+					setState({ status: 'error', message: detail })
+					return
+				}
+
+				const envelope = (await response.json()) as ReportEnvelope<T>
+				if (requestIdRef.current !== requestId) return
+
+				setState({ status: 'ready', envelope })
+			} catch (e) {
+				if (controller.signal.aborted || requestIdRef.current !== requestId) return
+				setState({ status: 'error', message: (e as Error).message })
+			}
+		}
+
+		void run()
+		return () => controller.abort()
+	}, [client, apiBaseUrl, report, range, nonce])
+
+	return { state, reload }
+}

package/src/types.ts

@@ -0,0 +1,135 @@
+/** Shared contract types for the Studio plugin and the API-route handler it calls. */
+
+// ---------------------------------------------------------------------------
+// Metric values
+// ---------------------------------------------------------------------------
+
+/**
+ * Why a metric has no usable number. Kept distinct rather than collapsed into one flag, because
+ * the UI must say different things: "this site never tracked it" is permanent, "not yet at this
+ * date" resolves as time passes, and "GA4 withheld it" means the number exists but is hidden.
+ */
+export type UnavailableReason =
+	/** The event has never been instrumented on this site. Permanent for historical ranges. */
+	| 'not_instrumented'
+	/** Instrumented, but the requested range predates the cutover date. */
+	| 'before_cutover'
+	/** GA4 suppressed the row for privacy thresholding. A real number exists; we may not see it. */
+	| 'suppressed'
+	/** The upstream source errored or timed out. Retryable, unlike the others. */
+	| 'source_error'
+	/** The metric is not defined for this site at all (e.g. a flow that does not exist there). */
+	| 'not_applicable'
+
+/**
+ * A metric that may legitimately have no value.
+ *
+ * The whole point of this union is that there is no way to read a number without first handling
+ * the absent case — a missing metric can never silently coerce to 0 and be charted as a real
+ * trough. `partial` carries a number that is only valid for part of the requested range.
+ */
+export type MetricValue =
+	| { status: 'ok'; value: number }
+	| { status: 'partial'; value: number; coveredFrom: string; note: string }
+	| { status: 'unavailable'; reason: UnavailableReason; detail?: string }
+
+/** Construct an available metric. */
+export function ok(value: number): MetricValue {
+	return { status: 'ok', value }
+}
+
+/** Construct an unavailable metric. */
+export function unavailable(reason: UnavailableReason, detail?: string): MetricValue {
+	return { status: 'unavailable', reason, detail }
+}
+
+/**
+ * Construct a metric covering only part of the requested range.
+ *
+ * @param value - the number for the covered portion
+ * @param coveredFrom - ISO date from which the number is valid
+ * @param note - short human-readable reason, shown next to the figure
+ */
+export function partial(value: number, coveredFrom: string, note: string): MetricValue {
+	return { status: 'partial', value, coveredFrom, note }
+}
+
+/**
+ * Read a metric's number, or `null` when there isn't a usable one.
+ * Use at render time so the absent case has to be handled explicitly.
+ */
+export function valueOrNull(metric: MetricValue): number | null {
+	return metric.status === 'unavailable' ? null : metric.value
+}
+
+// ---------------------------------------------------------------------------
+// Date ranges
+// ---------------------------------------------------------------------------
+
+/** The range granularities offered in the UI. */
+export type RangeKey = 'week' | 'quarter' | 'year'
+
+/**
+ * A resolved date range. Both bounds are inclusive ISO `YYYY-MM-DD` dates in `timezone`.
+ *
+ * `timezone` is carried explicitly because GA4 buckets by the property's configured timezone,
+ * Vercel reports in UTC, and Sanity `_createdAt` is UTC — comparing them without a single declared
+ * anchor silently shifts events across day and week boundaries.
+ */
+export interface DateRange {
+	key: RangeKey
+	start: string
+	end: string
+	timezone: string
+}
+
+// ---------------------------------------------------------------------------
+// Reports
+// ---------------------------------------------------------------------------
+
+/** The report names this package serves. Used as a strict allow-list, never as dynamic dispatch. */
+export const REPORT_NAMES = [
+	'measurement-health',
+	'acquisition',
+	'journey',
+	'typeface-interest',
+] as const
+
+export type ReportName = (typeof REPORT_NAMES)[number]
+
+/** Narrow an untrusted string to a known report name. */
+export function isReportName(value: unknown): value is ReportName {
+	return typeof value === 'string' && (REPORT_NAMES as readonly string[]).includes(value)
+}
+
+/** Which upstreams a report consulted, and how each fared. */
+export type SourceStatus =
+	| { status: 'ok' }
+	| { status: 'unconfigured' }
+	| { status: 'error'; message: string }
+
+/** Upstream data sources this package can read. */
+export type SourceName = 'ga4' | 'vercel' | 'sanity'
+
+/**
+ * Envelope around every report response.
+ *
+ * `sources` is mandatory rather than optional because partial failure is the normal case here,
+ * not the exception: a panel comparing three sources must be able to distinguish "this source
+ * reported zero" from "this source never answered", which a bare payload cannot express.
+ */
+export interface ReportEnvelope<T> {
+	report: ReportName
+	range: DateRange
+	/** Per-source outcome. A report may succeed overall while one source is unconfigured. */
+	sources: Partial<Record<SourceName, SourceStatus>>
+	/** Caveats to surface in the UI, e.g. GA4 sampling or an instrumentation cutover in range. */
+	notices: string[]
+	data: T
+}
+
+/** Error shape returned by the handler. Never leaks upstream error text to the browser. */
+export interface ReportError {
+	error: string
+	report?: string
+}