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

package/dist/{ranges-DSFapooC.d.ts → ranges-Bh9WCyYL.d.ts}

@@ -11,6 +11,8 @@ 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). */
@@ -220,39 +222,71 @@ interface TypefaceInterestData {
 }
 
 /**
- * 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.
  */
 
-/** 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. */
 declare const PREEXISTING: "preexisting";
 /**
- * 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.
+ */
+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. */
+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.
  */
-type EventCutover = typeof PREEXISTING | string | null;
+type EventCutover = typeof PREEXISTING | string | null | EventHistory;
 /** How completely an event covers a requested range. */
 type Coverage = {
     status: 'full';
 } | {
     status: 'partial';
-    cutover: string;
+    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';
+    reason: 'not_instrumented' | 'before_cutover' | 'unknown_event' | 'outage';
     cutover?: string;
+    /** Present when the whole range fell inside an outage. */
+    outages?: EventOutage[];
 };
 /**
  * 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
  */
@@ -267,6 +301,8 @@ declare function coverageForRange(cutovers: Readonly<Record<string, EventCutover
  * @param coverage - result of coverageForRange for the same event and range
  */
 declare function applyCoverage(count: number | null, coverage: Coverage): MetricValue;
+/** One-line description of an outage, for display beside an affected figure. */
+declare function describeOutage(outage: EventOutage | undefined): string;
 /**
  * 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.
@@ -393,4 +429,4 @@ declare function provisionalDates(range: DateRange, now?: Date): string[];
  */
 declare function provisionalNotice(range: DateRange, now?: Date): string | null;
 
-export { type AcquisitionData as A, assertValidSiteConfig as B, type Coverage as C, type DiagnosticReport as D, type EventCutover as E, coverageNotices as F, GA4_PROCESSING_LAG_DAYS as G, daysBetween as H, formatInTimeZone as I, type JourneyData as J, isValidTimeZone as K, provisionalDates as L, type MetricValue as M, provisionalNotice as N, type OrdersConfig as O, PREEXISTING as P, shiftDays as Q, type ReportEnvelope as R, type SiteAnalyticsConfig as S, type TypefaceInterestData as T, type UnavailableReason as U, type VercelConfig as V, type ReportName as a, type RangeKey as b, type MeasurementHealthData as c, type DateRange as d, REPORT_NAMES as e, type ReportError as f, type SourceName as g, type SourceStatus as h, coverageForRange as i, isReportName as j, previousRange as k, valueOrNull as l, type CheckStatus as m, type ConfigProblem as n, ok as o, partial as p, type DiagnosticCheck as q, resolveRange as r, type ExitPage as s, type Ga4Config as t, unavailable as u, validateSiteConfig as v, type JourneyStep as w, type SourceRow as x, type TypefaceInterestRow as y, applyCoverage as z };
+export { type AcquisitionData as A, type TypefaceInterestRow as B, type Coverage as C, type DiagnosticReport as D, type EventCutover as E, applyCoverage as F, GA4_PROCESSING_LAG_DAYS as G, assertValidSiteConfig as H, coverageNotices as I, type JourneyData as J, daysBetween as K, describeOutage as L, type MetricValue as M, formatInTimeZone as N, type OrdersConfig as O, PREEXISTING as P, isValidTimeZone as Q, type ReportEnvelope as R, type SiteAnalyticsConfig as S, type TypefaceInterestData as T, type UnavailableReason as U, type VercelConfig as V, provisionalDates as W, provisionalNotice as X, shiftDays as Y, type ReportName as a, type RangeKey as b, type MeasurementHealthData as c, type DateRange as d, REPORT_NAMES as e, type ReportError as f, type SourceName as g, type SourceStatus as h, coverageForRange as i, isReportName as j, previousRange as k, valueOrNull as l, type CheckStatus as m, type ConfigProblem as n, ok as o, partial as p, type DiagnosticCheck as q, resolveRange as r, type EventHistory as s, type EventOutage as t, unavailable as u, validateSiteConfig as v, type ExitPage as w, type Ga4Config as x, type JourneyStep as y, type SourceRow as z };

package/dist/server.d.mts

@@ -1,7 +1,7 @@
-import { S as SiteAnalyticsConfig, D as DiagnosticReport } from './ranges-DSFapooC.mjs';
-export { A as AcquisitionData, m as CheckStatus, n as ConfigProblem, C as Coverage, d as DateRange, q as DiagnosticCheck, E as EventCutover, s as ExitPage, G as GA4_PROCESSING_LAG_DAYS, t as Ga4Config, J as JourneyData, w as JourneyStep, c as MeasurementHealthData, M as MetricValue, O as OrdersConfig, P as PREEXISTING, e as REPORT_NAMES, b as RangeKey, R as ReportEnvelope, f as ReportError, a as ReportName, g as SourceName, x as SourceRow, h as SourceStatus, T as TypefaceInterestData, y as TypefaceInterestRow, U as UnavailableReason, V as VercelConfig, z as applyCoverage, B as assertValidSiteConfig, i as coverageForRange, F as coverageNotices, H as daysBetween, I as formatInTimeZone, j as isReportName, K as isValidTimeZone, o as ok, p as partial, k as previousRange, L as provisionalDates, N as provisionalNotice, r as resolveRange, Q as shiftDays, u as unavailable, v as validateSiteConfig, l as valueOrNull } from './ranges-DSFapooC.mjs';
-import { S as SanityQueryClient, G as Ga4Client, V as VercelClient } from './vercel-BMEO-Jcw.mjs';
-export { a as Ga4Report, b as Ga4ReportRequest, c as ServiceAccountKey, d as VercelPageviews, e as createGa4Client, f as createVercelClient, p as parseServiceAccountKey } from './vercel-BMEO-Jcw.mjs';
+import { S as SiteAnalyticsConfig, D as DiagnosticReport } from './ranges-Bh9WCyYL.mjs';
+export { A as AcquisitionData, m as CheckStatus, n as ConfigProblem, C as Coverage, d as DateRange, q as DiagnosticCheck, E as EventCutover, s as EventHistory, t as EventOutage, w as ExitPage, G as GA4_PROCESSING_LAG_DAYS, x as Ga4Config, J as JourneyData, y as JourneyStep, c as MeasurementHealthData, M as MetricValue, O as OrdersConfig, P as PREEXISTING, e as REPORT_NAMES, b as RangeKey, R as ReportEnvelope, f as ReportError, a as ReportName, g as SourceName, z as SourceRow, h as SourceStatus, T as TypefaceInterestData, B as TypefaceInterestRow, U as UnavailableReason, V as VercelConfig, F as applyCoverage, H as assertValidSiteConfig, i as coverageForRange, I as coverageNotices, K as daysBetween, L as describeOutage, N as formatInTimeZone, j as isReportName, Q as isValidTimeZone, o as ok, p as partial, k as previousRange, W as provisionalDates, X as provisionalNotice, r as resolveRange, Y as shiftDays, u as unavailable, v as validateSiteConfig, l as valueOrNull } from './ranges-Bh9WCyYL.mjs';
+import { S as SanityQueryClient, G as Ga4Client, V as VercelClient } from './vercel-B6d1Ng48.mjs';
+export { a as Ga4Report, b as Ga4ReportRequest, c as ServiceAccountKey, d as VercelPageviews, e as createGa4Client, f as createVercelClient, g as eventNameFilter, p as parseServiceAccountKey, s as sumFirstMetric } from './vercel-B6d1Ng48.mjs';
 
 /**
  * Request authentication and CORS for the report handler.

package/dist/server.d.ts

@@ -1,7 +1,7 @@
-import { S as SiteAnalyticsConfig, D as DiagnosticReport } from './ranges-DSFapooC.js';
-export { A as AcquisitionData, m as CheckStatus, n as ConfigProblem, C as Coverage, d as DateRange, q as DiagnosticCheck, E as EventCutover, s as ExitPage, G as GA4_PROCESSING_LAG_DAYS, t as Ga4Config, J as JourneyData, w as JourneyStep, c as MeasurementHealthData, M as MetricValue, O as OrdersConfig, P as PREEXISTING, e as REPORT_NAMES, b as RangeKey, R as ReportEnvelope, f as ReportError, a as ReportName, g as SourceName, x as SourceRow, h as SourceStatus, T as TypefaceInterestData, y as TypefaceInterestRow, U as UnavailableReason, V as VercelConfig, z as applyCoverage, B as assertValidSiteConfig, i as coverageForRange, F as coverageNotices, H as daysBetween, I as formatInTimeZone, j as isReportName, K as isValidTimeZone, o as ok, p as partial, k as previousRange, L as provisionalDates, N as provisionalNotice, r as resolveRange, Q as shiftDays, u as unavailable, v as validateSiteConfig, l as valueOrNull } from './ranges-DSFapooC.js';
-import { S as SanityQueryClient, G as Ga4Client, V as VercelClient } from './vercel-BMEO-Jcw.js';
-export { a as Ga4Report, b as Ga4ReportRequest, c as ServiceAccountKey, d as VercelPageviews, e as createGa4Client, f as createVercelClient, p as parseServiceAccountKey } from './vercel-BMEO-Jcw.js';
+import { S as SiteAnalyticsConfig, D as DiagnosticReport } from './ranges-Bh9WCyYL.js';
+export { A as AcquisitionData, m as CheckStatus, n as ConfigProblem, C as Coverage, d as DateRange, q as DiagnosticCheck, E as EventCutover, s as EventHistory, t as EventOutage, w as ExitPage, G as GA4_PROCESSING_LAG_DAYS, x as Ga4Config, J as JourneyData, y as JourneyStep, c as MeasurementHealthData, M as MetricValue, O as OrdersConfig, P as PREEXISTING, e as REPORT_NAMES, b as RangeKey, R as ReportEnvelope, f as ReportError, a as ReportName, g as SourceName, z as SourceRow, h as SourceStatus, T as TypefaceInterestData, B as TypefaceInterestRow, U as UnavailableReason, V as VercelConfig, F as applyCoverage, H as assertValidSiteConfig, i as coverageForRange, I as coverageNotices, K as daysBetween, L as describeOutage, N as formatInTimeZone, j as isReportName, Q as isValidTimeZone, o as ok, p as partial, k as previousRange, W as provisionalDates, X as provisionalNotice, r as resolveRange, Y as shiftDays, u as unavailable, v as validateSiteConfig, l as valueOrNull } from './ranges-Bh9WCyYL.js';
+import { S as SanityQueryClient, G as Ga4Client, V as VercelClient } from './vercel-B6d1Ng48.js';
+export { a as Ga4Report, b as Ga4ReportRequest, c as ServiceAccountKey, d as VercelPageviews, e as createGa4Client, f as createVercelClient, g as eventNameFilter, p as parseServiceAccountKey, s as sumFirstMetric } from './vercel-B6d1Ng48.js';
 
 /**
  * Request authentication and CORS for the report handler.

package/dist/server.js

@@ -36,6 +36,8 @@ __export(server_exports, {
   createVercelClient: () => createVercelClient,
   createVisitorInsightsHandler: () => createVisitorInsightsHandler,
   daysBetween: () => daysBetween,
+  describeOutage: () => describeOutage,
+  eventNameFilter: () => eventNameFilter,
   formatInTimeZone: () => formatInTimeZone,
   isReportName: () => isReportName,
   isValidTimeZone: () => isValidTimeZone,
@@ -49,6 +51,7 @@ __export(server_exports, {
   resolveRange: () => resolveRange,
   runDiagnostics: () => runDiagnostics,
   shiftDays: () => shiftDays,
+  sumFirstMetric: () => sumFirstMetric,
   unavailable: () => unavailable,
   validateSiteConfig: () => validateSiteConfig,
   valueOrNull: () => valueOrNull,
@@ -144,19 +147,41 @@ ${detail}`);
 
 // src/core/cutover.ts
 var PREEXISTING = "preexisting";
+function toHistory(cutover) {
+  if (cutover === null || cutover === void 0) return null;
+  if (typeof cutover === "string") return { from: cutover };
+  if (!cutover.from) return null;
+  return cutover;
+}
+function overlaps(aStart, aEnd, bStart, bEnd) {
+  return aStart <= bEnd && (aEnd === null || aEnd >= bStart);
+}
 function coverageForRange(cutovers, eventName, range) {
   if (!(eventName in cutovers)) return { status: "none", reason: "unknown_event" };
-  const cutover = cutovers[eventName];
-  if (cutover === null || cutover === void 0) return { status: "none", reason: "not_instrumented" };
-  if (cutover === PREEXISTING) return { status: "full" };
-  const cutoverTime = Date.parse(cutover);
-  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 };
+  const history = toHistory(cutovers[eventName]);
+  if (!history) return { status: "none", reason: "not_instrumented" };
+  let cutover;
+  let startsBeforeCutover = false;
+  if (history.from !== PREEXISTING) {
+    const cutoverTime = Date.parse(history.from);
+    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;
+  }
+  const hit = (history.outages ?? []).filter((o) => overlaps(o.start, o.until, range.start, range.end));
+  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" };
 }
 function applyCoverage(count, coverage) {
   if (coverage.status === "none") {
+    if (coverage.reason === "outage") {
+      const outage = coverage.outages?.[0];
+      return unavailable("outage", outage ? describeOutage(outage) : void 0);
+    }
     return unavailable(
       coverage.reason === "before_cutover" ? "before_cutover" : "not_instrumented",
       coverage.cutover ? `Instrumented from ${coverage.cutover}` : void 0
@@ -164,16 +189,31 @@ function applyCoverage(count, coverage) {
   }
   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];
+      const from2 = outage?.until ?? outage?.start ?? coverage.cutover ?? "";
+      return partial(count, from2, `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 };
 }
+function describeOutage(outage) {
+  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}`;
+}
 function coverageNotices(cutovers, eventNames, range) {
   const notices = [];
   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 \u2014 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") {
@@ -1210,6 +1250,8 @@ async function runReport(report, ctx) {
   createVercelClient,
   createVisitorInsightsHandler,
   daysBetween,
+  describeOutage,
+  eventNameFilter,
   formatInTimeZone,
   isReportName,
   isValidTimeZone,
@@ -1223,6 +1265,7 @@ async function runReport(report, ctx) {
   resolveRange,
   runDiagnostics,
   shiftDays,
+  sumFirstMetric,
   unavailable,
   validateSiteConfig,
   valueOrNull,