@liiift-studio/sanity-visitor-insights 0.1.0

package/src/core/cutover.ts

@@ -0,0 +1,109 @@
+/**
+ * Event instrumentation cutovers.
+ *
+ * GA4 cannot backfill events: data from before an event was instrumented does not exist and never
+ * will. A range spanning a cutover therefore mixes two measurement regimes, and a chart drawn
+ * across it reads as a change in visitor behaviour when it is really a change in what was counted.
+ *
+ * This lives in the package rather than in each site repo so all three foundries share one model
+ * and one set of semantics, and so the Studio panel and the server handler agree by construction.
+ */
+
+import type { DateRange, MetricValue } from '../types'
+import { unavailable, partial } from '../types'
+
+/** An event that predates this work — long-running, with no discontinuity to mark. */
+export const PREEXISTING = 'preexisting' as const
+
+/**
+ * When an event began firing on a site.
+ * `PREEXISTING` = live before this work began. `null` = planned, not yet deployed.
+ * An ISO `YYYY-MM-DD` string = the deploy date, set in the commit that ships the event.
+ */
+export type EventCutover = typeof PREEXISTING | string | null
+
+/** How completely an event covers a requested range. */
+export type Coverage =
+	| { status: 'full' }
+	| { status: 'partial'; cutover: string }
+	| { status: 'none'; reason: 'not_instrumented' | 'before_cutover' | 'unknown_event'; cutover?: string }
+
+/**
+ * Determine how well an event covers a date range.
+ *
+ * @param cutovers - the site's event cutover map
+ * @param eventName - GA4 event name to look up
+ * @param range - the requested range
+ */
+export function coverageForRange(
+	cutovers: Readonly<Record<string, EventCutover>>,
+	eventName: string,
+	range: Pick<DateRange, 'start' | 'end'>,
+): Coverage {
+	if (!(eventName in cutovers)) return { status: 'none', reason: 'unknown_event' }
+
+	const cutover = cutovers[eventName]
+	// `in` proved the key exists, so undefined here means an explicitly undefined value.
+	if (cutover === null || cutover === undefined) return { status: 'none', reason: 'not_instrumented' }
+	if (cutover === PREEXISTING) return { status: 'full' }
+
+	const cutoverTime = Date.parse(cutover)
+	// An unparseable date is a config error; treat it as unknown rather than silently trusting it.
+	if (Number.isNaN(cutoverTime)) return { status: 'none', reason: 'unknown_event' }
+
+	if (Date.parse(range.end) < cutoverTime) return { status: 'none', reason: 'before_cutover', cutover }
+	if (Date.parse(range.start) < cutoverTime) return { status: 'partial', cutover }
+
+	return { status: 'full' }
+}
+
+/**
+ * Wrap a raw count in a MetricValue that reflects the event's coverage of the range.
+ *
+ * Call this instead of returning a bare number, so a value that only covers part of the range
+ * carries that fact with it all the way to the renderer.
+ *
+ * @param count - the number GA4 returned, or null if the query could not run
+ * @param coverage - result of coverageForRange for the same event and range
+ */
+export function applyCoverage(count: number | null, coverage: Coverage): MetricValue {
+	if (coverage.status === 'none') {
+		return unavailable(
+			coverage.reason === 'before_cutover' ? 'before_cutover' : 'not_instrumented',
+			coverage.cutover ? `Instrumented from ${coverage.cutover}` : undefined,
+		)
+	}
+
+	if (count === null) return unavailable('source_error')
+
+	if (coverage.status === 'partial') {
+		return partial(count, coverage.cutover, `Only counted from ${coverage.cutover}, when this event was added`)
+	}
+
+	return { status: 'ok', value: count }
+}
+
+/**
+ * Human-readable notices for every event in a range that is not fully covered.
+ * Surfaced in the report envelope so the panel can show caveats without recomputing them.
+ */
+export function coverageNotices(
+	cutovers: Readonly<Record<string, EventCutover>>,
+	eventNames: readonly string[],
+	range: Pick<DateRange, 'start' | 'end'>,
+): string[] {
+	const notices: string[] = []
+
+	for (const name of eventNames) {
+		const coverage = coverageForRange(cutovers, name, range)
+		if (coverage.status === 'partial') {
+			notices.push(`${name} was instrumented on ${coverage.cutover}; figures before that date are missing, not zero.`)
+		} else if (coverage.status === 'none' && coverage.reason === 'not_instrumented') {
+			notices.push(`${name} is not instrumented on this site, so it cannot be reported for any range.`)
+		} else if (coverage.status === 'none' && coverage.reason === 'before_cutover') {
+			notices.push(`${name} did not exist during this range; it was instrumented on ${coverage.cutover}.`)
+		}
+	}
+
+	return notices
+}

package/src/core/ranges.ts

@@ -0,0 +1,103 @@
+/**
+ * Date-range resolution.
+ *
+ * Every range is resolved against one declared timezone — the GA4 property's — because the three
+ * sources bucket time differently: GA4 by the property timezone, Vercel by UTC, Sanity `_createdAt`
+ * by UTC. Without a single anchor, an order placed near midnight lands in different weeks depending
+ * on which source you ask, which corrupts exactly the cross-source comparison this tool exists for.
+ */
+
+import type { DateRange, RangeKey } from '../types'
+
+/** GA4 does not finalise the most recent days. Figures inside this window may still rise. */
+export const GA4_PROCESSING_LAG_DAYS = 2
+
+/** Format a Date as `YYYY-MM-DD` in the given IANA timezone. */
+export function formatInTimeZone(date: Date, timeZone: string): string {
+	// en-CA gives ISO-ordered parts, which is what we want to reassemble.
+	const parts = new Intl.DateTimeFormat('en-CA', {
+		timeZone,
+		year: 'numeric',
+		month: '2-digit',
+		day: '2-digit',
+	}).formatToParts(date)
+
+	const get = (type: string) => parts.find((p) => p.type === type)?.value ?? ''
+	return `${get('year')}-${get('month')}-${get('day')}`
+}
+
+/** Shift an ISO `YYYY-MM-DD` date by a whole number of days. */
+export function shiftDays(isoDate: string, days: number): string {
+	const time = Date.parse(`${isoDate}T00:00:00Z`)
+	if (Number.isNaN(time)) throw new Error(`Invalid ISO date: ${isoDate}`)
+	return new Date(time + days * 86_400_000).toISOString().slice(0, 10)
+}
+
+/** Inclusive whole days between two ISO dates. */
+export function daysBetween(start: string, end: string): number {
+	return Math.round((Date.parse(`${end}T00:00:00Z`) - Date.parse(`${start}T00:00:00Z`)) / 86_400_000) + 1
+}
+
+/** How many days each range key spans. */
+const RANGE_DAYS: Record<RangeKey, number> = {
+	week: 7,
+	quarter: 91,
+	year: 365,
+}
+
+/**
+ * Resolve a range key into concrete dates, anchored to `timezone` and ending today.
+ *
+ * @param key - week, quarter or year
+ * @param timezone - IANA timezone of the GA4 property this range will be queried against
+ * @param now - injectable clock, so tests are deterministic
+ */
+export function resolveRange(key: RangeKey, timezone: string, now: Date = new Date()): DateRange {
+	const end = formatInTimeZone(now, timezone)
+	const start = shiftDays(end, -(RANGE_DAYS[key] - 1))
+	return { key, start, end, timezone }
+}
+
+/**
+ * The equivalent range immediately before `range`, for period-over-period comparison.
+ *
+ * A bare count answers "how many", which on its own is not actionable; the comparison is what
+ * tells someone whether to do anything.
+ */
+export function previousRange(range: DateRange): DateRange {
+	const span = daysBetween(range.start, range.end)
+	return {
+		key: range.key,
+		start: shiftDays(range.start, -span),
+		end: shiftDays(range.end, -span),
+		timezone: range.timezone,
+	}
+}
+
+/**
+ * The trailing dates within a range whose GA4 figures are not yet settled.
+ * Returns an empty array when the range ends before the lag window.
+ */
+export function provisionalDates(range: DateRange, now: Date = new Date()): string[] {
+	const today = formatInTimeZone(now, range.timezone)
+	const dates: string[] = []
+
+	for (let i = 0; i < GA4_PROCESSING_LAG_DAYS; i += 1) {
+		const date = shiftDays(today, -i)
+		if (date >= range.start && date <= range.end) dates.push(date)
+	}
+
+	return dates.sort()
+}
+
+/**
+ * Notice text when a range includes days GA4 has not finished processing, or `null` when it does not.
+ * Without this a Monday-morning glance at "this week" reads the trailing dip as a real drop.
+ */
+export function provisionalNotice(range: DateRange, now: Date = new Date()): string | null {
+	const dates = provisionalDates(range, now)
+	if (dates.length === 0) return null
+
+	const from = dates[0]
+	return `GA4 has not finished processing ${from} onwards; those figures are provisional and will rise.`
+}

package/src/core/siteConfig.ts

@@ -0,0 +1,150 @@
+/**
+ * Per-site adapter configuration.
+ *
+ * The three foundries differ in ways that cannot be abstracted away: different GA4 event coverage,
+ * different order schemas, different flows that exist on one site and not another. Rather than
+ * branching on a site id inside the reports — which would mean editing this package to onboard a
+ * fourth foundry — each site describes itself through this config and the reports stay generic.
+ */
+
+import type { EventCutover } from './cutover'
+
+/** GA4 connection for one site. */
+export interface Ga4Config {
+	/** Numeric GA4 property id. NOT the `G-XXXXXXX` measurement id, which is the client-side one. */
+	propertyId: string
+	/** IANA timezone the property is configured with. Every range is anchored to this. */
+	timezone: string
+}
+
+/** Vercel Web Analytics connection for one site. */
+export interface VercelConfig {
+	projectId: string
+	teamId?: string
+}
+
+/** Where to count orders, and what they are called on this site. */
+export interface OrdersConfig {
+	/** Document type holding orders. */
+	documentType: string
+	/**
+	 * Field holding the typeface references on an order, if the site has one.
+	 * Null where orders do not resolve to typefaces in a usable way.
+	 */
+	typefacesField: string | null
+	/**
+	 * GROQ filter appended to exclude non-typeface orders, e.g. merch-only orders on Darden.
+	 * Merch inflates a family's apparent purchase count if not excluded.
+	 */
+	excludeFilter?: string
+}
+
+/** One site's complete description of itself. */
+export interface SiteAnalyticsConfig {
+	/** Stable machine id, e.g. `darden`. */
+	siteId: string
+	/** Human label shown in the Studio UI. */
+	label: string
+	/** Null when GA4 is not wired up for this site — reports degrade rather than fail. */
+	ga4: Ga4Config | null
+	/** Null when Vercel Web Analytics is unavailable, e.g. on a plan tier without API access. */
+	vercel: VercelConfig | null
+	orders: OrdersConfig
+	/**
+	 * When each GA4 event began firing here. Events absent from this map report as `unknown_event`,
+	 * which is the honest answer for a flow the site does not have — distinct from `not_instrumented`,
+	 * which implies it is merely pending.
+	 */
+	eventCutovers: Record<string, EventCutover>
+	/** Origins allowed to call this site's handler cross-origin, e.g. a separately deployed Studio. */
+	allowedStudioOrigins?: string[]
+}
+
+/** A problem found while validating a site config. */
+export interface ConfigProblem {
+	field: string
+	message: string
+}
+
+/**
+ * Validate a site config at runtime.
+ *
+ * Compile-time types do not survive into a consuming site's `sanity.config.js`, which is plain
+ * JavaScript — so a typo'd property id or a measurement id pasted where a numeric property id
+ * belongs would otherwise surface as an empty chart rather than an error.
+ *
+ * @param config - the candidate config
+ * @returns the problems found; an empty array means the config is usable
+ */
+export function validateSiteConfig(config: Partial<SiteAnalyticsConfig> | undefined): ConfigProblem[] {
+	const problems: ConfigProblem[] = []
+
+	if (!config) {
+		return [{ field: 'config', message: 'No site config supplied' }]
+	}
+
+	if (!config.siteId) problems.push({ field: 'siteId', message: 'Required' })
+	if (!config.label) problems.push({ field: 'label', message: 'Required' })
+
+	if (config.ga4) {
+		const { propertyId, timezone } = config.ga4
+		if (!propertyId) {
+			problems.push({ field: 'ga4.propertyId', message: 'Required when ga4 is configured' })
+		} else if (propertyId.startsWith('G-')) {
+			problems.push({
+				field: 'ga4.propertyId',
+				message: `Looks like a measurement id ("${propertyId}"). The Data API needs the numeric property id from GA4 Admin instead.`,
+			})
+		} else if (!/^\d+$/.test(propertyId)) {
+			problems.push({ field: 'ga4.propertyId', message: 'Must be the numeric GA4 property id' })
+		}
+
+		if (!timezone) {
+			problems.push({ field: 'ga4.timezone', message: 'Required — ranges are anchored to it' })
+		} else if (!isValidTimeZone(timezone)) {
+			problems.push({ field: 'ga4.timezone', message: `Not a recognised IANA timezone: ${timezone}` })
+		}
+	}
+
+	if (config.vercel && !config.vercel.projectId) {
+		problems.push({ field: 'vercel.projectId', message: 'Required when vercel is configured' })
+	}
+
+	if (!config.orders?.documentType) {
+		problems.push({ field: 'orders.documentType', message: 'Required' })
+	}
+
+	if (!config.eventCutovers) {
+		problems.push({ field: 'eventCutovers', message: 'Required — omit events the site does not have' })
+	}
+
+	for (const origin of config.allowedStudioOrigins ?? []) {
+		if (!/^https?:\/\//.test(origin)) {
+			problems.push({ field: 'allowedStudioOrigins', message: `Must be a full origin including scheme: ${origin}` })
+		}
+		if (origin.endsWith('/')) {
+			problems.push({ field: 'allowedStudioOrigins', message: `Must not have a trailing slash: ${origin}` })
+		}
+	}
+
+	return problems
+}
+
+/** Whether a string is an IANA timezone this runtime recognises. */
+export function isValidTimeZone(timeZone: string): boolean {
+	try {
+		new Intl.DateTimeFormat('en-CA', { timeZone })
+		return true
+	} catch {
+		return false
+	}
+}
+
+/** Throw if a config is unusable, naming every problem at once rather than one per run. */
+export function assertValidSiteConfig(config: Partial<SiteAnalyticsConfig> | undefined): asserts config is SiteAnalyticsConfig {
+	const problems = validateSiteConfig(config)
+	if (problems.length > 0) {
+		const detail = problems.map((p) => `  ${p.field}: ${p.message}`).join('\n')
+		throw new Error(`Invalid visitor-insights site config:\n${detail}`)
+	}
+}

package/src/index.ts

@@ -0,0 +1,86 @@
+/**
+ * Studio entry point — browser only.
+ *
+ * Must never import from `./server` or anything under `src/server/`, which reads credentials and
+ * uses node:crypto. The split export subpaths are what keep that guarantee enforceable.
+ */
+
+import { definePlugin } from 'sanity'
+import { resolveIcon } from '@liiift-studio/sanity-ui-compat/icons'
+import { VisitorInsightsTool, type VisitorInsightsToolProps } from './studio/VisitorInsightsTool'
+
+/** Chart glyph, resolved against whichever @sanity/icons major the Studio has installed. */
+const ChartIcon = resolveIcon('ChartUpwardIcon', 'chart-upward')
+
+/** Options for the Studio plugin. */
+export interface VisitorInsightsPluginOptions {
+	/**
+	 * Base URL of the site serving the reports, e.g. `https://dardenstudio.com`.
+	 * Same-origin studios can pass an empty string.
+	 */
+	apiBaseUrl: string
+	/** Label shown in the tool header. */
+	siteLabel: string
+	/** Tool name in the Studio URL. Defaults to `visitor-insights`. */
+	name?: string
+	/** Title in the Studio nav. Defaults to `Insights`. */
+	title?: string
+	/**
+	 * Restrict the tool to these Sanity roles. Omit to show it to every Studio user.
+	 * These panels read order-derived conversion figures, so gating to administrators is
+	 * usually right — matching how the deploy and utilities tools are already gated.
+	 */
+	roles?: string[]
+}
+
+/**
+ * Visitor Insights — visitor-behaviour analytics inside the Studio.
+ *
+ * @example
+ * ```ts
+ * plugins: [
+ *   visitorInsights({
+ *     apiBaseUrl: 'https://dardenstudio.com',
+ *     siteLabel: 'Darden Studio',
+ *     roles: ['administrator'],
+ *   }),
+ * ]
+ * ```
+ */
+export const visitorInsights = definePlugin<VisitorInsightsPluginOptions>((options) => {
+	const { apiBaseUrl, siteLabel, name = 'visitor-insights', title = 'Insights', roles } = options
+
+	return {
+		name: '@liiift-studio/sanity-visitor-insights',
+		tools: (prev, { currentUser }) => {
+			if (roles && roles.length > 0) {
+				const userRoles = currentUser?.roles?.map((role) => role.name) ?? []
+				const permitted = userRoles.some((role) => roles.includes(role))
+				if (!permitted) return prev
+			}
+
+			return [
+				...prev,
+				{
+					name,
+					title,
+					icon: ChartIcon,
+					component: VisitorInsightsTool,
+					options: { apiBaseUrl, siteLabel } satisfies VisitorInsightsToolProps,
+				},
+			]
+		},
+	}
+})
+
+export default visitorInsights
+
+export { VisitorInsightsTool, type VisitorInsightsToolProps } from './studio/VisitorInsightsTool'
+export { useReport, type ReportState, type UseReportOptions } from './studio/useReport'
+export { MetricFigure, ComparisonBar, NoticeList, formatCount, formatPercent } from './studio/Figure'
+
+// Shared contract types, safe in the browser — no server code reachable from here.
+export * from './types'
+export { PREEXISTING, coverageForRange, type EventCutover, type Coverage } from './core/cutover'
+export { validateSiteConfig, type SiteAnalyticsConfig } from './core/siteConfig'
+export { resolveRange, previousRange } from './core/ranges'

package/src/reportData.ts

@@ -0,0 +1,120 @@
+/**
+ * Report result shapes, shared by the server that produces them and the panels that render them.
+ *
+ * These live outside both entry points on purpose. If the panels imported them from
+ * `src/server/reports/*` — even as `import type`, which does erase at build time — the module
+ * graph would still contain a client-to-server edge, and the guarantee that credential-reading
+ * code cannot reach a Studio bundle would rest on a compiler detail rather than on structure.
+ */
+
+import type { MetricValue } from './types'
+
+// ---------------------------------------------------------------------------
+// Measurement health
+// ---------------------------------------------------------------------------
+
+/** How much of reality each source sees. Pageviews compare like with like; the rest is context. */
+export interface MeasurementHealthData {
+	/** GA4 pageviews — directly comparable to `vercelPageviews`. */
+	ga4Pageviews: MetricValue
+	/** Vercel pageviews — cookieless, not consent-gated. */
+	vercelPageviews: MetricValue
+	/**
+	 * Vercel minus GA4 pageviews, as a share of Vercel. Positive means GA4 saw less.
+	 * Null when either side is unavailable — never computed against a missing operand.
+	 */
+	shortfallRatio: number | null
+	/** GA4 sessions. Context only: a session is not a pageview and is never subtracted from one. */
+	ga4Sessions: MetricValue
+	/** Orders in range. Ground truth for conversions, shown as context. */
+	orders: MetricValue
+	/** Share of sessions that granted consent, where the event exists. */
+	consentRate: MetricValue
+	/** Plain-language reading of the numbers above, for a non-analyst audience. */
+	interpretation: string
+}
+
+// ---------------------------------------------------------------------------
+// Acquisition
+// ---------------------------------------------------------------------------
+
+/** One acquisition source. */
+export interface SourceRow {
+	/** GA4 `sessionSource` value. */
+	source: string
+	/** GA4 `sessionDefaultChannelGroup`, e.g. Organic Search. */
+	channel: string
+	sessions: number
+	/** True when this source is one of the design-industry referrers. */
+	designIndustry: boolean
+	/** True for GA4's `(not set)` / `(direct)` style buckets, which are not real sources. */
+	unattributed: boolean
+}
+
+/** Where visitors came from. */
+export interface AcquisitionData {
+	rows: SourceRow[]
+	totalSessions: number
+	/** Sessions from design-industry referrers, as a share of the total. */
+	designIndustryShare: number | null
+	/** Sessions GA4 could not attribute, as a share of the total. */
+	unattributedShare: number | null
+	/** True when GA4 withheld low-count rows, so the tail is shorter than reality. */
+	rowsWithheld: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Journey
+// ---------------------------------------------------------------------------
+
+/** One rung of the funnel. */
+export interface JourneyStep {
+	key: string
+	label: string
+	event: string
+	count: MetricValue
+	/**
+	 * Share of the previous measurable step that reached this one.
+	 * Null when either end is unavailable — a drop-off across an unmeasured step is meaningless.
+	 */
+	conversionFromPrevious: number | null
+}
+
+/** A page where sessions commonly ended. */
+export interface ExitPage {
+	path: string
+	exits: number
+}
+
+/** How far visitors get. Per-step totals, never an observed path. */
+export interface JourneyData {
+	steps: JourneyStep[]
+	topExitPages: ExitPage[]
+	/** Always true. The UI must not present these steps as a tracked journey. */
+	approximate: true
+	/** Why it is approximate, in words the panel can show directly. */
+	approximationNote: string
+}
+
+// ---------------------------------------------------------------------------
+// Typeface interest
+// ---------------------------------------------------------------------------
+
+/** One family's interest figures. */
+export interface TypefaceInterestRow {
+	typeface: string
+	viewed: MetricValue
+	tested: MetricValue
+	bought: MetricValue
+	/** Tested divided by viewed. Null unless both are real numbers. */
+	testRate: number | null
+}
+
+/** Viewed, tested and bought, by family. */
+export interface TypefaceInterestData {
+	rows: TypefaceInterestRow[]
+	/** Stated in the response so the UI cannot omit it. */
+	interpretationNote: string
+	/** True when GA4 withheld low-count rows, so quiet families may be missing entirely. */
+	rowsWithheld: boolean
+}