@liiift-studio/sanity-visitor-insights 0.1.0

package/src/server/auth.ts

@@ -0,0 +1,133 @@
+/**
+ * Request authentication and CORS for the report handler.
+ *
+ * The Studio forwards its own Sanity session token and this verifies it against Sanity. A shared
+ * secret was the obvious alternative and is the wrong one: the Studio bundle is served publicly, so
+ * any secret compiled into it is extractable, which moves the bar from "know the URL" to "open
+ * devtools". Verifying a session token instead proves the caller is a logged-in project user, and
+ * gives a real identity to log rather than an anonymous caller who read a constant.
+ *
+ * This mirrors the pattern already in production on Darden's order-action endpoints.
+ */
+
+/** Minimal shape this module needs from a Next.js API request. */
+export interface HandlerRequest {
+	method?: string
+	url?: string
+	headers: Record<string, string | string[] | undefined>
+	query?: Record<string, string | string[] | undefined>
+}
+
+/** Minimal shape this module needs from a Next.js API response. */
+export interface HandlerResponse {
+	setHeader(name: string, value: string): void
+	status(code: number): HandlerResponse
+	json(body: unknown): void
+	end(): void
+}
+
+/** A verified Sanity Studio user. */
+export interface StudioUser {
+	id: string
+	name?: string
+	email?: string
+	roles?: Array<{ name: string }>
+}
+
+/** Outcome of verifying a request's Studio token. */
+export type VerifyResult =
+	| { ok: true; user: StudioUser }
+	| { ok: false; reason: string }
+
+/** Read a header that may arrive as a string or an array. */
+function header(req: HandlerRequest, name: string): string | undefined {
+	const raw = req.headers[name] ?? req.headers[name.toLowerCase()]
+	return Array.isArray(raw) ? raw[0] : raw
+}
+
+/**
+ * Verify that a request carries a valid Sanity user token for this project.
+ *
+ * @param req - the incoming request
+ * @param sanityProjectId - project the token must belong to
+ * @returns ok with the resolved user, or a reason suitable for logging but never for the response
+ */
+export async function verifyStudioRequest(req: HandlerRequest, sanityProjectId: string): Promise<VerifyResult> {
+	const authorization = header(req, 'authorization') ?? ''
+	const token = authorization.startsWith('Bearer ') ? authorization.slice(7).trim() : null
+
+	if (!token) return { ok: false, reason: 'no-token' }
+	if (!sanityProjectId) {
+		// Fail closed rather than silently authorising everything if the env is misconfigured.
+		console.error('Visitor insights: Sanity project id not configured — cannot verify Studio requests')
+		return { ok: false, reason: 'not-configured' }
+	}
+
+	try {
+		const response = await fetch(`https://${sanityProjectId}.api.sanity.io/v2021-06-07/users/me`, {
+			headers: { Authorization: `Bearer ${token}` },
+		})
+		if (!response.ok) return { ok: false, reason: `sanity-${response.status}` }
+
+		const user = (await response.json()) as StudioUser | null
+		// Sanity answers 200 with a null id for an unauthenticated request rather than a 401.
+		if (!user || !user.id) return { ok: false, reason: 'no-user' }
+
+		return { ok: true, user }
+	} catch (e) {
+		console.error('Visitor insights: Studio token verification failed:', (e as Error).message)
+		return { ok: false, reason: 'verify-error' }
+	}
+}
+
+/**
+ * Apply CORS headers for a Studio-originated request and answer the preflight.
+ *
+ * Echoes one allow-listed origin rather than sending `*`. A wildcard is acceptable for public HTML
+ * but not for an endpoint that takes an Authorization header and returns business data.
+ *
+ * @param req - the incoming request
+ * @param res - the response to decorate
+ * @param allowedOrigins - exact origins permitted to call cross-origin
+ * @returns true when the request was a preflight and is now fully answered
+ */
+export function applyCors(req: HandlerRequest, res: HandlerResponse, allowedOrigins: readonly string[]): boolean {
+	const origin = header(req, 'origin')
+
+	if (origin && allowedOrigins.includes(origin)) {
+		res.setHeader('Access-Control-Allow-Origin', origin)
+		// The response varies by origin, so caches must not serve one origin's response to another.
+		res.setHeader('Vary', 'Origin')
+		res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS')
+		res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type')
+		res.setHeader('Access-Control-Max-Age', '600')
+	}
+
+	if (req.method === 'OPTIONS') {
+		// A disallowed origin gets 204 without allow headers; the browser rejects it on its own,
+		// so there is no need to reveal whether the origin is known.
+		res.status(204).end()
+		return true
+	}
+
+	return false
+}
+
+/**
+ * Guard a report endpoint. Responds 401 and returns null when the caller cannot be verified.
+ *
+ * @returns the verified user, or null when the request has already been answered with a 401
+ */
+export async function requireStudioUser(
+	req: HandlerRequest,
+	res: HandlerResponse,
+	sanityProjectId: string,
+): Promise<StudioUser | null> {
+	const result = await verifyStudioRequest(req, sanityProjectId)
+
+	if (result.ok) return result.user
+
+	console.error(`Visitor insights: rejected unauthenticated request (${result.reason}) on ${req.url ?? 'unknown'}`)
+	res.status(401).json({ error: 'Not authorised. Sign in to the Studio and try again.' })
+	return null
+}

package/src/server/cache.ts

@@ -0,0 +1,75 @@
+/**
+ * A small in-memory TTL cache for report responses.
+ *
+ * Without this, every panel render and every range toggle is a live fan-out to GA4, Vercel and
+ * Sanity. GA4's standard quota is finite per property per day and shared with anything else
+ * querying it, so an editor idly switching ranges could exhaust it. Reports also change slowly —
+ * GA4 does not finalise the last two days at all — so serving a few minutes stale costs nothing.
+ *
+ * Deliberately per-instance rather than a shared store: it is a quota guard and a latency
+ * smoother, not a source of truth, and a cold serverless instance simply repopulates it.
+ */
+
+/** How long a cached report stays fresh. */
+export const DEFAULT_TTL_MS = 5 * 60 * 1000
+
+interface Entry<T> {
+	value: T
+	expiresAt: number
+}
+
+/** Bound the cache so a long-lived instance cannot grow without limit. */
+const MAX_ENTRIES = 200
+
+const store = new Map<string, Entry<unknown>>()
+
+/** Build a stable cache key from the parts that determine a response. */
+export function cacheKey(parts: Array<string | number | undefined>): string {
+	return parts.map((p) => String(p ?? '')).join('|')
+}
+
+/**
+ * Read a fresh cached value, or undefined when absent or stale.
+ * Stale entries are evicted on read so expiry does not depend on a sweep.
+ */
+export function getCached<T>(key: string): T | undefined {
+	const entry = store.get(key)
+	if (!entry) return undefined
+
+	if (entry.expiresAt <= Date.now()) {
+		store.delete(key)
+		return undefined
+	}
+
+	return entry.value as T
+}
+
+/** Store a value with a TTL, evicting the oldest entry when full. */
+export function setCached<T>(key: string, value: T, ttlMs: number = DEFAULT_TTL_MS): void {
+	if (store.size >= MAX_ENTRIES && !store.has(key)) {
+		// Map preserves insertion order, so the first key is the oldest.
+		const oldest = store.keys().next().value
+		if (oldest !== undefined) store.delete(oldest)
+	}
+
+	store.set(key, { value, expiresAt: Date.now() + ttlMs })
+}
+
+/**
+ * Return a cached value or compute, cache and return it.
+ * Concurrent callers may both compute on a cold key; that is acceptable here and avoids the
+ * complexity of an in-flight promise registry for a cache this small.
+ */
+export async function withCache<T>(key: string, ttlMs: number, compute: () => Promise<T>): Promise<T> {
+	const hit = getCached<T>(key)
+	if (hit !== undefined) return hit
+
+	const value = await compute()
+	setCached(key, value, ttlMs)
+	return value
+}
+
+/** Empty the cache. Test seam, and useful after a config change. */
+export function clearCache(): void {
+	store.clear()
+}

package/src/server/createHandler.ts

@@ -0,0 +1,199 @@
+/**
+ * The mountable Next.js API-route handler.
+ *
+ * Ships from this package rather than being copy-pasted into each site so the three foundries
+ * cannot drift apart: a fix applied here reaches all of them on a version bump, instead of being
+ * applied to one repo and forgotten in the other two. A consuming site's route is then:
+ *
+ *   // pages/api/visitor-insights/[report].js
+ *   import { createVisitorInsightsHandler } from '@liiift-studio/sanity-visitor-insights/server'
+ *   export default createVisitorInsightsHandler({ config: mySiteConfig })
+ *
+ * Credentials are read from the environment inside this module and never leave the server.
+ */
+
+import {
+	isReportName,
+	type DateRange,
+	type RangeKey,
+	type ReportEnvelope,
+	type SourceName,
+	type SourceStatus,
+} from '../types'
+import { assertValidSiteConfig, type SiteAnalyticsConfig } from '../core/siteConfig'
+import { coverageNotices } from '../core/cutover'
+import { resolveRange, provisionalNotice } from '../core/ranges'
+import { applyCors, requireStudioUser, type HandlerRequest, type HandlerResponse } from './auth'
+import { createGa4Client, type Ga4Client } from './ga4'
+import { createVercelClient, type VercelClient } from './vercel'
+import { parseServiceAccountKey } from './googleAuth'
+import { cacheKey, withCache, DEFAULT_TTL_MS } from './cache'
+import type { SanityQueryClient } from './orders'
+import { measurementHealth } from './reports/measurementHealth'
+import { acquisition } from './reports/acquisition'
+import { journey } from './reports/journey'
+import { typefaceInterest } from './reports/typefaceInterest'
+import { JOURNEY_STEPS } from './reports/journey'
+
+/** Environment variables this handler reads. Names are fixed so all three sites match. */
+export const ENV_VARS = {
+	/** Service-account JSON (raw or base64) with Viewer on the GA4 property. */
+	googleServiceAccount: 'VISITOR_INSIGHTS_GA4_SERVICE_ACCOUNT',
+	/** Vercel API token with read access to the project. */
+	vercelToken: 'VISITOR_INSIGHTS_VERCEL_TOKEN',
+} as const
+
+/** Options for building a handler. */
+export interface HandlerOptions {
+	/** This site's description of itself. */
+	config: SiteAnalyticsConfig
+	/**
+	 * Sanity client used for order counts. Supply the site's existing server-side client so this
+	 * package does not need its own Sanity credentials.
+	 */
+	sanityClient?: SanityQueryClient
+	/** Sanity project id used to verify Studio tokens. Defaults to `SANITY_STUDIO_PROJECT_ID`. */
+	sanityProjectId?: string
+	/** Cache lifetime for report responses. */
+	cacheTtlMs?: number
+}
+
+/** Valid range keys, as an allow-list for the query parameter. */
+const RANGE_KEYS: RangeKey[] = ['week', 'quarter', 'year']
+
+/** Read a query parameter that may arrive as a string or an array. */
+function param(req: HandlerRequest, name: string): string | undefined {
+	const raw = req.query?.[name]
+	return Array.isArray(raw) ? raw[0] : raw
+}
+
+/**
+ * Build the API-route handler for a site.
+ *
+ * @param options - the site config and its Sanity client
+ * @returns a Next.js Pages Router API handler
+ */
+export function createVisitorInsightsHandler(options: HandlerOptions) {
+	// Fail at construction rather than per-request, so a misconfiguration surfaces on deploy.
+	assertValidSiteConfig(options.config)
+
+	const config = options.config
+	const ttl = options.cacheTtlMs ?? DEFAULT_TTL_MS
+
+	return async function handler(req: HandlerRequest, res: HandlerResponse): Promise<void> {
+		if (applyCors(req, res, config.allowedStudioOrigins ?? [])) return
+
+		if (req.method !== 'GET') {
+			res.status(405).json({ error: 'Method not allowed' })
+			return
+		}
+
+		const sanityProjectId = options.sanityProjectId ?? process.env.SANITY_STUDIO_PROJECT_ID ?? ''
+		const user = await requireStudioUser(req, res, sanityProjectId)
+		if (!user) return
+
+		// Strict allow-list. The report name selects from a fixed set and is never used to build
+		// an upstream request path or to look up code dynamically.
+		const reportName = param(req, 'report')
+		if (!isReportName(reportName)) {
+			res.status(400).json({ error: 'Unknown report' })
+			return
+		}
+
+		const rangeKey = param(req, 'range') ?? 'week'
+		if (!RANGE_KEYS.includes(rangeKey as RangeKey)) {
+			res.status(400).json({ error: 'Unknown range' })
+			return
+		}
+
+		// Ranges are anchored to the GA4 property's timezone so all three sources agree on
+		// where a day begins. Falls back to UTC only when GA4 is not configured at all.
+		const timezone = config.ga4?.timezone ?? 'UTC'
+		const range = resolveRange(rangeKey as RangeKey, timezone)
+
+		const sources: Partial<Record<SourceName, SourceStatus>> = {}
+
+		const serviceAccount = parseServiceAccountKey(process.env[ENV_VARS.googleServiceAccount])
+		let ga4: Ga4Client | null = null
+		if (!config.ga4) {
+			sources.ga4 = { status: 'unconfigured' }
+		} else if (!serviceAccount) {
+			sources.ga4 = { status: 'error', message: 'Service account missing or unparseable' }
+		} else {
+			ga4 = createGa4Client(config.ga4.propertyId, serviceAccount)
+			sources.ga4 = { status: 'ok' }
+		}
+
+		const vercelToken = process.env[ENV_VARS.vercelToken]
+		let vercel: VercelClient | null = null
+		if (!config.vercel) {
+			sources.vercel = { status: 'unconfigured' }
+		} else if (!vercelToken) {
+			sources.vercel = { status: 'error', message: 'Vercel token missing' }
+		} else {
+			vercel = createVercelClient(config.vercel.projectId, vercelToken, config.vercel.teamId)
+			sources.vercel = { status: 'ok' }
+		}
+
+		const sanity = options.sanityClient ?? null
+		sources.sanity = sanity ? { status: 'ok' } : { status: 'unconfigured' }
+
+		try {
+			const key = cacheKey(['vi', config.siteId, reportName, range.key, range.start, range.end])
+
+			const envelope = await withCache<ReportEnvelope<unknown>>(key, ttl, async () => {
+				const notices: string[] = []
+
+				const provisional = provisionalNotice(range)
+				if (provisional) notices.push(provisional)
+
+				const data = await runReport(reportName, { config, range, ga4, vercel, sanity, notices })
+
+				return { report: reportName, range, sources, notices, data }
+			})
+
+			res.status(200).json(envelope)
+		} catch (e) {
+			// Upstream messages can echo request detail, so only a generic message crosses the wire.
+			console.error(`Visitor insights: report "${reportName}" failed:`, (e as Error).message)
+			res.status(502).json({ error: 'Report failed', report: reportName })
+		}
+	}
+}
+
+/** Arguments shared by every report. */
+interface RunContext {
+	config: SiteAnalyticsConfig
+	range: DateRange
+	ga4: Ga4Client | null
+	vercel: VercelClient | null
+	sanity: SanityQueryClient | null
+	notices: string[]
+}
+
+/** Dispatch to a report by name. A plain switch, so the set of reachable code paths is closed. */
+async function runReport(report: string, ctx: RunContext): Promise<unknown> {
+	const { config, range, ga4, vercel, sanity, notices } = ctx
+
+	switch (report) {
+		case 'measurement-health':
+			return measurementHealth({ config, range, ga4, vercel, sanity })
+
+		case 'acquisition':
+			if (!ga4) throw new Error('GA4 is required for the acquisition report')
+			return acquisition(ga4, range)
+
+		case 'journey': {
+			if (!ga4) throw new Error('GA4 is required for the journey report')
+			notices.push(...coverageNotices(config.eventCutovers, JOURNEY_STEPS.map((s) => s.event), range))
+			return journey(config, ga4, range)
+		}
+
+		case 'typeface-interest':
+			if (!ga4) throw new Error('GA4 is required for the typeface-interest report')
+			return typefaceInterest({ config, range, ga4, sanity })
+
+		default:
+			throw new Error(`Unhandled report: ${report}`)
+	}
+}

package/src/server/ga4.ts

@@ -0,0 +1,149 @@
+/**
+ * GA4 Data API client.
+ *
+ * Only `runReport` and `batchRunReports` are used. `runFunnelReport` is deliberately not called:
+ * it is an alpha surface with its own stricter quota, and it returns step-conversion marginals
+ * rather than observed paths — drawing a flow diagram from it would imply co-occurrence that was
+ * never measured. The journey report approximates instead, and says so.
+ */
+
+import { getAccessToken, type ServiceAccountKey } from './googleAuth'
+
+const DATA_API_BASE = 'https://analyticsdata.googleapis.com/v1beta'
+
+/** A GA4 report request, narrowed to the fields this package sets. */
+export interface Ga4ReportRequest {
+	dimensions?: Array<{ name: string }>
+	metrics?: Array<{ name: string }>
+	dateRanges: Array<{ startDate: string; endDate: string }>
+	dimensionFilter?: unknown
+	orderBys?: unknown
+	limit?: number
+	keepEmptyRows?: boolean
+}
+
+/** A parsed report row: dimension values and metric values, positionally aligned to the request. */
+export interface Ga4Row {
+	dimensions: string[]
+	metrics: number[]
+}
+
+/** A parsed GA4 report. */
+export interface Ga4Report {
+	rows: Ga4Row[]
+	/** True when GA4 withheld rows for privacy thresholding — totals are then incomplete. */
+	thresholded: boolean
+	/** True when GA4 answered from a sample rather than the full data set. */
+	sampled: boolean
+	/** Total row count GA4 reports, which may exceed rows returned when a limit applied. */
+	rowCount: number
+}
+
+/** Raw Data API response shape, narrowed to what is read here. */
+interface RawReport {
+	rows?: Array<{
+		dimensionValues?: Array<{ value?: string }>
+		metricValues?: Array<{ value?: string }>
+	}>
+	rowCount?: number
+	metadata?: { subjectToThresholding?: boolean; samplingMetadatas?: unknown[] }
+	propertyQuota?: unknown
+}
+
+/**
+ * Coerce a GA4 metric cell to a number.
+ *
+ * The Data API returns every value as a string, and returns an empty string for suppressed cells.
+ * `Number('')` is 0, which would turn a withheld row into a real-looking zero — so empty is
+ * treated as NaN and filtered by the caller rather than silently becoming a data point.
+ */
+function toMetricNumber(raw: string | undefined): number {
+	if (raw === undefined || raw === '') return Number.NaN
+	const parsed = Number(raw)
+	return Number.isFinite(parsed) ? parsed : Number.NaN
+}
+
+/** Parse a raw Data API report into the shape the reports consume. */
+function parseReport(raw: RawReport): Ga4Report {
+	const rows: Ga4Row[] = (raw.rows ?? []).map((row) => ({
+		dimensions: (row.dimensionValues ?? []).map((d) => d.value ?? ''),
+		metrics: (row.metricValues ?? []).map((m) => toMetricNumber(m.value)),
+	}))
+
+	return {
+		rows,
+		thresholded: raw.metadata?.subjectToThresholding === true,
+		sampled: Array.isArray(raw.metadata?.samplingMetadatas) && raw.metadata.samplingMetadatas.length > 0,
+		rowCount: raw.rowCount ?? rows.length,
+	}
+}
+
+/** A GA4 client bound to one property. */
+export interface Ga4Client {
+	runReport(request: Ga4ReportRequest): Promise<Ga4Report>
+	batchRunReports(requests: Ga4ReportRequest[]): Promise<Ga4Report[]>
+}
+
+/**
+ * Build a GA4 client for one property.
+ *
+ * @param propertyId - numeric GA4 property id
+ * @param key - service-account key with Viewer on that property
+ */
+export function createGa4Client(propertyId: string, key: ServiceAccountKey): Ga4Client {
+	async function post<T>(path: string, body: unknown): Promise<T> {
+		const token = await getAccessToken(key)
+
+		const response = await fetch(`${DATA_API_BASE}/properties/${propertyId}:${path}`, {
+			method: 'POST',
+			headers: {
+				Authorization: `Bearer ${token}`,
+				'Content-Type': 'application/json',
+			},
+			body: JSON.stringify(body),
+		})
+
+		if (!response.ok) {
+			// GA4 error bodies can echo the request; keep only the status for the caller's log.
+			throw new Error(`GA4 ${path} failed with ${response.status}`)
+		}
+
+		return (await response.json()) as T
+	}
+
+	return {
+		async runReport(request) {
+			const raw = await post<RawReport>('runReport', request)
+			return parseReport(raw)
+		},
+
+		/**
+		 * Run several reports in one call. Preferred over parallel runReport calls: it is one
+		 * quota-charged request and one round trip rather than N of each.
+		 */
+		async batchRunReports(requests) {
+			if (requests.length === 0) return []
+
+			const raw = await post<{ reports?: RawReport[] }>('batchRunReports', { requests })
+			return (raw.reports ?? []).map(parseReport)
+		},
+	}
+}
+
+/** Build a dimension filter matching a single event name. */
+export function eventNameFilter(eventName: string): unknown {
+	return {
+		filter: {
+			fieldName: 'eventName',
+			stringFilter: { matchType: 'EXACT', value: eventName },
+		},
+	}
+}
+
+/** Sum a report's first metric across all rows, ignoring suppressed cells. */
+export function sumFirstMetric(report: Ga4Report): number {
+	return report.rows.reduce((total, row) => {
+		const value = row.metrics[0]
+		return value !== undefined && Number.isFinite(value) ? total + value : total
+	}, 0)
+}

package/src/server/googleAuth.ts

@@ -0,0 +1,139 @@
+/**
+ * Service-account access tokens for the GA4 Data API.
+ *
+ * Implemented directly against Google's OAuth2 token endpoint rather than through `googleapis`,
+ * which is a very large dependency to pull into a package that only needs one grant type. Signing
+ * a JWT with node:crypto keeps the dependency surface at zero and removes any risk of a
+ * credential-bearing SDK being reachable from the Studio entry point.
+ */
+
+import { createSign } from 'node:crypto'
+
+/** Read-only scope for the GA4 Data API — the least privilege this package needs. */
+const ANALYTICS_READONLY_SCOPE = 'https://www.googleapis.com/auth/analytics.readonly'
+
+/** Google's OAuth2 token endpoint for the JWT bearer grant. */
+const TOKEN_ENDPOINT = 'https://oauth2.googleapis.com/token'
+
+/** Seconds an assertion stays valid. Google caps this at one hour. */
+const ASSERTION_TTL_SECONDS = 3600
+
+/** Refresh this many seconds before actual expiry, so a token never expires mid-flight. */
+const REFRESH_MARGIN_SECONDS = 60
+
+/** The parts of a service-account JSON key this module uses. */
+export interface ServiceAccountKey {
+	client_email: string
+	private_key: string
+}
+
+interface CachedToken {
+	token: string
+	expiresAt: number
+}
+
+/** Access tokens are cached per service account for their lifetime. */
+const tokenCache = new Map<string, CachedToken>()
+
+/** Base64url without padding, as JWT requires. */
+function base64url(input: string | Buffer): string {
+	return Buffer.from(input).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+/**
+ * Parse a service-account key from an environment variable.
+ *
+ * Accepts either raw JSON or base64-encoded JSON, because multi-line JSON with embedded newlines
+ * is awkward to set in some dashboards and gets mangled often enough to be worth tolerating both.
+ *
+ * @param raw - the environment variable's value
+ * @returns the parsed key, or null when unset or unparseable
+ */
+export function parseServiceAccountKey(raw: string | undefined): ServiceAccountKey | null {
+	if (!raw) return null
+
+	let text = raw.trim()
+
+	// Base64 payloads contain no braces; JSON always starts with one.
+	if (!text.startsWith('{')) {
+		try {
+			text = Buffer.from(text, 'base64').toString('utf8')
+		} catch {
+			return null
+		}
+	}
+
+	try {
+		const parsed = JSON.parse(text) as Partial<ServiceAccountKey>
+		if (!parsed.client_email || !parsed.private_key) return null
+
+		return {
+			client_email: parsed.client_email,
+			// Escaped newlines survive most env-var round trips; real newlines do not always.
+			private_key: parsed.private_key.replace(/\\n/g, '\n'),
+		}
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Get an access token for the GA4 Data API, minting one only when the cached token is near expiry.
+ *
+ * @param key - the service-account key
+ * @returns a bearer token
+ * @throws when Google rejects the assertion
+ */
+export async function getAccessToken(key: ServiceAccountKey): Promise<string> {
+	const now = Math.floor(Date.now() / 1000)
+	const cached = tokenCache.get(key.client_email)
+
+	if (cached && cached.expiresAt - REFRESH_MARGIN_SECONDS > now) {
+		return cached.token
+	}
+
+	const header = base64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }))
+	const claims = base64url(
+		JSON.stringify({
+			iss: key.client_email,
+			scope: ANALYTICS_READONLY_SCOPE,
+			aud: TOKEN_ENDPOINT,
+			exp: now + ASSERTION_TTL_SECONDS,
+			iat: now,
+		}),
+	)
+
+	const signer = createSign('RSA-SHA256')
+	signer.update(`${header}.${claims}`)
+	const signature = base64url(signer.sign(key.private_key))
+	const assertion = `${header}.${claims}.${signature}`
+
+	const response = await fetch(TOKEN_ENDPOINT, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+		body: new URLSearchParams({
+			grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+			assertion,
+		}),
+	})
+
+	if (!response.ok) {
+		// Deliberately does not include the response body, which can echo parts of the assertion.
+		throw new Error(`Google token exchange failed with ${response.status}`)
+	}
+
+	const body = (await response.json()) as { access_token?: string; expires_in?: number }
+	if (!body.access_token) throw new Error('Google token exchange returned no access token')
+
+	tokenCache.set(key.client_email, {
+		token: body.access_token,
+		expiresAt: now + (body.expires_in ?? ASSERTION_TTL_SECONDS),
+	})
+
+	return body.access_token
+}
+
+/** Clear the token cache. Test seam. */
+export function resetTokenCache(): void {
+	tokenCache.clear()
+}