@liiift-studio/sanity-visitor-insights 0.2.2 → 0.3.0

package/dist/testing.d.mts

@@ -1,4 +1,4 @@
-import { G as Ga4Client, b as Ga4ReportRequest, S as SanityQueryClient, a as Ga4Report, d as VercelPageviews, V as VercelClient } from './vercel-BMEO-Jcw.mjs';
+import { G as Ga4Client, b as Ga4ReportRequest, S as SanityQueryClient, a as Ga4Report, d as VercelPageviews, V as VercelClient } from './vercel-B6d1Ng48.mjs';
 
 /**
  * Test doubles and fixture builders for the report layer.

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { G as Ga4Client, b as Ga4ReportRequest, S as SanityQueryClient, a as Ga4Report, d as VercelPageviews, V as VercelClient } from './vercel-BMEO-Jcw.js';
+import { G as Ga4Client, b as Ga4ReportRequest, S as SanityQueryClient, a as Ga4Report, d as VercelPageviews, V as VercelClient } from './vercel-B6d1Ng48.js';
 
 /**
  * Test doubles and fixture builders for the report layer.

package/dist/{vercel-BMEO-Jcw.d.mts → vercel-B6d1Ng48.d.mts}

@@ -85,6 +85,10 @@ interface Ga4Client {
  * @param key - service-account key with Viewer on that property
  */
 declare function createGa4Client(propertyId: string, key: ServiceAccountKey): Ga4Client;
+/** Build a dimension filter matching a single event name. */
+declare function eventNameFilter(eventName: string): unknown;
+/** Sum a report's first metric across all rows, ignoring suppressed cells. */
+declare function sumFirstMetric(report: Ga4Report): number;
 
 /**
  * Vercel Web Analytics client.
@@ -120,4 +124,4 @@ interface VercelClient {
  */
 declare function createVercelClient(projectId: string, token: string, teamId?: string): VercelClient;
 
-export { type Ga4Client as G, type SanityQueryClient as S, type VercelClient as V, type Ga4Report as a, type Ga4ReportRequest as b, type ServiceAccountKey as c, type VercelPageviews as d, createGa4Client as e, createVercelClient as f, parseServiceAccountKey as p };
+export { type Ga4Client as G, type SanityQueryClient as S, type VercelClient as V, type Ga4Report as a, type Ga4ReportRequest as b, type ServiceAccountKey as c, type VercelPageviews as d, createGa4Client as e, createVercelClient as f, eventNameFilter as g, parseServiceAccountKey as p, sumFirstMetric as s };

package/dist/{vercel-BMEO-Jcw.d.ts → vercel-B6d1Ng48.d.ts}

@@ -85,6 +85,10 @@ interface Ga4Client {
  * @param key - service-account key with Viewer on that property
  */
 declare function createGa4Client(propertyId: string, key: ServiceAccountKey): Ga4Client;
+/** Build a dimension filter matching a single event name. */
+declare function eventNameFilter(eventName: string): unknown;
+/** Sum a report's first metric across all rows, ignoring suppressed cells. */
+declare function sumFirstMetric(report: Ga4Report): number;
 
 /**
  * Vercel Web Analytics client.
@@ -120,4 +124,4 @@ interface VercelClient {
  */
 declare function createVercelClient(projectId: string, token: string, teamId?: string): VercelClient;
 
-export { type Ga4Client as G, type SanityQueryClient as S, type VercelClient as V, type Ga4Report as a, type Ga4ReportRequest as b, type ServiceAccountKey as c, type VercelPageviews as d, createGa4Client as e, createVercelClient as f, parseServiceAccountKey as p };
+export { type Ga4Client as G, type SanityQueryClient as S, type VercelClient as V, type Ga4Report as a, type Ga4ReportRequest as b, type ServiceAccountKey as c, type VercelPageviews as d, createGa4Client as e, createVercelClient as f, eventNameFilter as g, parseServiceAccountKey as p, sumFirstMetric as s };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@liiift-studio/sanity-visitor-insights",
-  "version": "0.2.2",
-  "description": "Visitor-behaviour analytics for type-foundry Sanity Studios — GA4, Vercel and order data reconciled honestly",
+  "version": "0.3.0",
+  "description": "Visitor-behaviour analytics for type-foundry Sanity Studios \u2014 GA4, Vercel and order data reconciled honestly",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/src/core/core.test.ts

@@ -49,7 +49,9 @@ describe('coverageForRange', () => {
 	it('reports partial coverage when the range straddles the cutover', () => {
 		expect(coverageForRange(cutovers, 'begin_checkout', { start: '2026-08-01', end: '2026-10-01' })).toEqual({
 			status: 'partial',
+			reason: 'spans_cutover',
 			cutover: '2026-09-01',
+			outages: [],
 		})
 	})
 
@@ -69,7 +71,7 @@ describe('applyCoverage', () => {
 	})
 
 	it('marks a straddling range as partial rather than complete', () => {
-		const metric = applyCoverage(120, { status: 'partial', cutover: '2026-09-01' })
+		const metric = applyCoverage(120, { status: 'partial', reason: 'spans_cutover', cutover: '2026-09-01', outages: [] })
 		expect(metric.status).toBe('partial')
 		expect(valueOrNull(metric)).toBe(120)
 	})
@@ -97,6 +99,68 @@ describe('coverageNotices', () => {
 	})
 })
 
+describe('outages', () => {
+	// Darden's real case: ecommerce events kept firing in code but stopped reaching GA4 for
+	// nine months. Every one of those days returns an honest zero from the API.
+	const withOutage: Record<string, EventCutover> = {
+		purchase: {
+			from: PREEXISTING,
+			outages: [{ start: '2025-11-20', until: '2026-08-30', reason: 'gtag loader moved to lazyOnload' }],
+		},
+		still_broken: {
+			from: PREEXISTING,
+			outages: [{ start: '2026-01-01', until: null }],
+		},
+	}
+
+	it('reports a range sitting entirely inside an outage as unavailable, not zero', () => {
+		const coverage = coverageForRange(withOutage, 'purchase', { start: '2026-01-01', end: '2026-03-01' })
+		expect(coverage.status).toBe('none')
+		expect(coverage).toMatchObject({ reason: 'outage' })
+
+		// The crucial assertion: a real GA4 zero must not become a charted zero.
+		const metric = applyCoverage(0, coverage)
+		expect(metric.status).toBe('unavailable')
+		expect(valueOrNull(metric)).toBeNull()
+	})
+
+	it('reports a range straddling the end of an outage as partial and undercounted', () => {
+		const coverage = coverageForRange(withOutage, 'purchase', { start: '2026-08-01', end: '2026-09-30' })
+		expect(coverage).toMatchObject({ status: 'partial', reason: 'spans_outage' })
+
+		const metric = applyCoverage(12, coverage)
+		expect(metric.status).toBe('partial')
+		if (metric.status === 'partial') expect(metric.note).toContain('Undercounted')
+	})
+
+	it('treats a range fully after the outage as complete', () => {
+		expect(coverageForRange(withOutage, 'purchase', { start: '2026-09-01', end: '2026-09-30' })).toEqual({ status: 'full' })
+	})
+
+	it('treats a range fully before the outage as complete', () => {
+		expect(coverageForRange(withOutage, 'purchase', { start: '2025-06-01', end: '2025-11-01' })).toEqual({ status: 'full' })
+	})
+
+	it('treats an unresolved outage as ongoing', () => {
+		const coverage = coverageForRange(withOutage, 'still_broken', { start: '2026-06-01', end: '2026-08-30' })
+		expect(coverage).toMatchObject({ status: 'none', reason: 'outage' })
+	})
+
+	it('still accepts the plain shorthand forms', () => {
+		expect(coverageForRange({ a: PREEXISTING }, 'a', { start: '2026-01-01', end: '2026-02-01' })).toEqual({ status: 'full' })
+		expect(coverageForRange({ a: null }, 'a', { start: '2026-01-01', end: '2026-02-01' })).toEqual({
+			status: 'none', reason: 'not_instrumented',
+		})
+	})
+
+	it('explains an outage in the notices rather than leaving a silent dip', () => {
+		const notices = coverageNotices(withOutage, ['purchase'], { start: '2026-08-01', end: '2026-09-30' })
+		expect(notices).toHaveLength(1)
+		expect(notices[0]).toContain('not a real decline')
+		expect(notices[0]).toContain('lazyOnload')
+	})
+})
+
 describe('ranges', () => {
 	it('anchors the range end to the property timezone, not the host timezone', () => {
 		// 02:00 UTC on the 26th is still the 25th in Los Angeles. A range anchored to UTC would

package/src/core/cutover.ts

@@ -1,10 +1,17 @@
 /**
- * Event instrumentation cutovers.
+ * Event instrumentation history — when an event started, and when it stopped.
  *
  * 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.
  *
+ * Outages are the same problem arriving from the other direction, and are easy to miss because the
+ * event still exists in the code. Darden is the worked example: its ecommerce events fired normally
+ * until a script-loading change on 2025-11-20 stopped them reaching GA4 for nine months. Every one
+ * of those days returns a real, honest zero from the API — a zero that means "not recorded", not
+ * "no sales". Without an outage recorded here, a yearly funnel would render that as a collapse in
+ * trade rather than as a gap in measurement.
+ *
  * 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.
  */
@@ -12,26 +19,74 @@
 import type { DateRange, MetricValue } from '../types'
 import { unavailable, partial } from '../types'
 
-/** An event that predates this work — long-running, with no discontinuity to mark. */
+/** An event that predates this work — long-running, with no start discontinuity to mark. */
 export const PREEXISTING = 'preexisting' as const
 
 /**
- * When an event began firing on a site.
+ * A period during which an event stopped reaching GA4 despite still existing in the code.
+ * `until: null` means it is still broken as of now.
+ */
+export interface EventOutage {
+	/** First ISO date with no data. */
+	start: string
+	/** ISO date it resumed, or null if unresolved. */
+	until: string | null
+	/** Short human-readable cause, shown in the UI next to the affected figure. */
+	reason?: string
+}
+
+/** An event with a start date and, optionally, periods where it stopped firing. */
+export interface EventHistory {
+	/** When it began firing: `PREEXISTING`, or an ISO `YYYY-MM-DD` deploy date. */
+	from: typeof PREEXISTING | string
+	/** Periods where it stopped. Order does not matter. */
+	outages?: EventOutage[]
+}
+
+/**
+ * When an event fired 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.
+ * An ISO `YYYY-MM-DD` string = the deploy date. An `EventHistory` adds outages.
  */
-export type EventCutover = typeof PREEXISTING | string | null
+export type EventCutover = typeof PREEXISTING | string | null | EventHistory
 
 /** 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 }
+	| {
+			status: 'partial'
+			reason: 'spans_cutover' | 'spans_outage'
+			/** Present when the range starts before the event was instrumented. */
+			cutover?: string
+			/** Outages overlapping the range. Empty for a pure cutover overlap. */
+			outages: EventOutage[]
+	  }
+	| {
+			status: 'none'
+			reason: 'not_instrumented' | 'before_cutover' | 'unknown_event' | 'outage'
+			cutover?: string
+			/** Present when the whole range fell inside an outage. */
+			outages?: EventOutage[]
+	  }
+
+/** Normalise the shorthand forms into an EventHistory, or null when not instrumented. */
+function toHistory(cutover: EventCutover | undefined): EventHistory | null {
+	if (cutover === null || cutover === undefined) return null
+	if (typeof cutover === 'string') return { from: cutover }
+	if (!cutover.from) return null
+	return cutover
+}
+
+/** Whether two inclusive date ranges overlap at all. */
+function overlaps(aStart: string, aEnd: string | null, bStart: string, bEnd: string): boolean {
+	// A null end means "ongoing", so it extends past any range end.
+	return aStart <= bEnd && (aEnd === null || aEnd >= bStart)
+}
 
 /**
  * Determine how well an event covers a date range.
  *
- * @param cutovers - the site's event cutover map
+ * @param cutovers - the site's event history map
  * @param eventName - GA4 event name to look up
  * @param range - the requested range
  */
@@ -42,17 +97,32 @@ export function coverageForRange(
 ): 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 history = toHistory(cutovers[eventName])
+	if (!history) return { status: 'none', reason: 'not_instrumented' }
 
-	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' }
+	// --- start date -----------------------------------------------------------
+	let cutover: string | undefined
+	let startsBeforeCutover = false
 
-	if (Date.parse(range.end) < cutoverTime) return { status: 'none', reason: 'before_cutover', cutover }
-	if (Date.parse(range.start) < cutoverTime) return { status: 'partial', cutover }
+	if (history.from !== PREEXISTING) {
+		const cutoverTime = Date.parse(history.from)
+		// 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' }
+
+		cutover = history.from
+		if (Date.parse(range.end) < cutoverTime) return { status: 'none', reason: 'before_cutover', cutover }
+		startsBeforeCutover = Date.parse(range.start) < cutoverTime
+	}
+
+	// --- outages --------------------------------------------------------------
+	const hit = (history.outages ?? []).filter((o) => overlaps(o.start, o.until, range.start, range.end))
+
+	// A range sitting entirely inside one outage has no usable data at all.
+	const swallowed = hit.find((o) => o.start <= range.start && (o.until === null || o.until > range.end))
+	if (swallowed) return { status: 'none', reason: 'outage', outages: [swallowed], cutover }
+
+	if (hit.length > 0) return { status: 'partial', reason: 'spans_outage', outages: hit, cutover }
+	if (startsBeforeCutover) return { status: 'partial', reason: 'spans_cutover', outages: [], cutover }
 
 	return { status: 'full' }
 }
@@ -68,6 +138,10 @@ export function coverageForRange(
  */
 export function applyCoverage(count: number | null, coverage: Coverage): MetricValue {
 	if (coverage.status === 'none') {
+		if (coverage.reason === 'outage') {
+			const outage = coverage.outages?.[0]
+			return unavailable('outage', outage ? describeOutage(outage) : undefined)
+		}
 		return unavailable(
 			coverage.reason === 'before_cutover' ? 'before_cutover' : 'not_instrumented',
 			coverage.cutover ? `Instrumented from ${coverage.cutover}` : undefined,
@@ -77,12 +151,27 @@ export function applyCoverage(count: number | null, coverage: Coverage): MetricV
 	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`)
+		if (coverage.reason === 'spans_outage') {
+			const outage = coverage.outages[0]
+			// coveredFrom is the outage end where known, since that is when data resumes.
+			const from = outage?.until ?? outage?.start ?? coverage.cutover ?? ''
+			return partial(count, from, `Undercounted: ${describeOutage(outage)}`)
+		}
+
+		const from = coverage.cutover ?? ''
+		return partial(count, from, `Only counted from ${from}, when this event was added`)
 	}
 
 	return { status: 'ok', value: count }
 }
 
+/** One-line description of an outage, for display beside an affected figure. */
+export function describeOutage(outage: EventOutage | undefined): string {
+	if (!outage) return 'an outage affected part of this range'
+	const period = outage.until ? `${outage.start} to ${outage.until}` : `${outage.start} onwards`
+	return outage.reason ? `not recorded ${period} (${outage.reason})` : `not recorded ${period}`
+}
+
 /**
  * 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.
@@ -96,8 +185,13 @@ export function coverageNotices(
 
 	for (const name of eventNames) {
 		const coverage = coverageForRange(cutovers, name, range)
-		if (coverage.status === 'partial') {
+
+		if (coverage.status === 'partial' && coverage.reason === 'spans_outage') {
+			notices.push(`${name} was ${describeOutage(coverage.outages[0])}, so figures for this range are too low — not a real decline.`)
+		} else 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 === 'outage') {
+			notices.push(`${name} was ${describeOutage(coverage.outages?.[0])}, covering this whole range. The figure is unavailable, 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') {

package/src/server.ts

@@ -23,7 +23,7 @@ export { runDiagnostics, type DiagnosticsInput } from './server/diagnostics'
 
 // Client constructors. Needed to call runDiagnostics headlessly, which the README documents —
 // without these exported that example could not actually be written.
-export { createGa4Client, type Ga4Client, type Ga4Report, type Ga4ReportRequest } from './server/ga4'
+export { createGa4Client, eventNameFilter, sumFirstMetric, type Ga4Client, type Ga4Report, type Ga4ReportRequest } from './server/ga4'
 export { createVercelClient, type VercelClient, type VercelPageviews } from './server/vercel'
 export { parseServiceAccountKey, type ServiceAccountKey } from './server/googleAuth'
 export type { CheckStatus, DiagnosticCheck, DiagnosticReport } from './reportData'

package/src/studio/Figure.tsx

@@ -18,6 +18,7 @@ const REASON_TEXT: Record<UnavailableReason, string> = {
 	not_instrumented: 'Not tracked on this site',
 	before_cutover: 'Not tracked during this period',
 	suppressed: 'Withheld by GA4 for privacy',
+	outage: 'Not recorded during part of this period',
 	source_error: 'Source did not respond',
 	not_applicable: 'Does not apply to this site',
 }

package/src/types.ts

@@ -16,6 +16,8 @@ export type UnavailableReason =
 	| 'before_cutover'
 	/** GA4 suppressed the row for privacy thresholding. A real number exists; we may not see it. */
 	| 'suppressed'
+	/** The event exists in the code but stopped reaching GA4 for this period. Not a real zero. */
+	| 'outage'
 	/** 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). */