@liiift-studio/sanity-visitor-insights 0.1.0 → 0.2.0

package/README.md

@@ -17,6 +17,7 @@ only as a conversion anchor and a count; no revenue, and no customer data.
 | **Acquisition** | Where do visitors come from, and how many are design-industry referrals? |
 | **Journey** | How far do visitors get, and where do they stop? |
 | **Typeface interest** | Which families get viewed, tested and bought? |
+| **Diagnostics** | What to fix before trusting any of the above? |
 
 Each panel offers a week, quarter or year range.
 
@@ -60,6 +61,53 @@ aggregate statistics into personal-data processing.
 
 ---
 
+## Diagnostics — run this first
+
+The panels are only as trustworthy as the property behind them, and the ways a GA4 property
+quietly produces wrong numbers are not visible from the numbers themselves. The Diagnostics panel
+measures them:
+
+- **GA4 reachable** — distinguishes a bad service-account key from missing Viewer access.
+- **Timezone matches config** — a mismatch shifts day and week boundaries, so GA4, Vercel and
+  Sanity stop agreeing which period an event belongs to.
+- **Retention covers a year** — probes a window beyond the 2-month default rather than asking you
+  to read the Admin screen. This is the check most likely to explain an empty year range.
+- **Configured events fire** — catches a cutover map claiming an event is live when GA4 has never
+  seen it, which otherwise produces figures that look real but are not.
+- **Purchases carry `transaction_id`** — without it a GA4 purchase cannot be reconciled against a
+  Sanity order at all.
+- **GA4 purchases match orders** — a large divergence usually means `purchase` fires on a page some
+  buyers never reach, fires twice, or is being blocked.
+
+It is also the one panel that still says something useful with nothing configured, so it is worth
+opening the moment credentials land. Available in the Studio, or headless:
+
+```ts
+import { runDiagnostics } from '@liiift-studio/sanity-visitor-insights/server'
+
+const report = await runDiagnostics({ config, ga4, vercel, sanity })
+console.log(report.verdict, report.checks)
+```
+
+---
+
+## Testing without credentials
+
+Test doubles ship from a separate subpath, so a consuming site can exercise these reports before
+it has anything to point at:
+
+```ts
+import { createFakeGa4Client, makeGa4Total } from '@liiift-studio/sanity-visitor-insights/testing'
+
+const ga4 = createFakeGa4Client({ batch: () => [makeGa4Total(800), makeGa4Total(300), makeGa4Total(0)] })
+const data = await measurementHealth({ config, range, ga4, vercel: null, sanity: null })
+```
+
+The fakes record what they were asked, so a test can assert on the GROQ that ran — which is how
+this package proves no customer field is ever projected.
+
+---
+
 ## Installing
 
 ```bash

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as sanity from 'sanity';
 import React from 'react';
-import { R as ReportEnvelope, a as ReportName, b as RangeKey, M as MetricValue } from './ranges-D6AZwpmm.mjs';
-export { C as Coverage, D as DateRange, E as EventCutover, P as PREEXISTING, c as REPORT_NAMES, d as ReportError, S as SiteAnalyticsConfig, e as SourceName, f as SourceStatus, U as UnavailableReason, g as coverageForRange, i as isReportName, o as ok, p as partial, h as previousRange, r as resolveRange, u as unavailable, v as validateSiteConfig, j as valueOrNull } from './ranges-D6AZwpmm.mjs';
+import { R as ReportEnvelope, a as ReportName, b as RangeKey, M as MetricValue, A as AcquisitionData, D as DiagnosticReport, J as JourneyData, c as MeasurementHealthData, T as TypefaceInterestData } from './ranges-DSFapooC.mjs';
+export { C as Coverage, d as DateRange, E as EventCutover, P as PREEXISTING, e as REPORT_NAMES, f as ReportError, S as SiteAnalyticsConfig, g as SourceName, h as SourceStatus, U as UnavailableReason, i as coverageForRange, j as isReportName, o as ok, p as partial, k as previousRange, r as resolveRange, u as unavailable, v as validateSiteConfig, l as valueOrNull } from './ranges-DSFapooC.mjs';
 
 /**
  * The Visitor Insights Studio tool.
@@ -110,6 +110,45 @@ interface NoticeListProps {
  */
 declare function NoticeList({ notices }: NoticeListProps): React.ReactElement | null;
 
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+declare function MeasurementHealthPanel({ data }: {
+    data: MeasurementHealthData;
+}): React.ReactElement;
+/** Acquisition — where visitors came from, with design-industry referrers called out. */
+declare function AcquisitionPanel({ data }: {
+    data: AcquisitionData;
+}): React.ReactElement;
+/** Journey — per-step totals with adjacent drop-off, explicitly not a tracked path. */
+declare function JourneyPanel({ data }: {
+    data: JourneyData;
+}): React.ReactElement;
+/** Typeface interest — viewed, tested and bought per family. */
+declare function TypefaceInterestPanel({ data }: {
+    data: TypefaceInterestData;
+}): React.ReactElement;
+/**
+ * Diagnostics — what to fix before trusting anything else here.
+ *
+ * Deliberately the panel that still works with nothing configured: on a site without credentials
+ * it is the only one that can say something useful, and it is the first thing worth opening once
+ * credentials land.
+ */
+declare function DiagnosticsPanel({ data }: {
+    data: DiagnosticReport;
+}): React.ReactElement;
+
 /**
  * Studio entry point — browser only.
  *
@@ -152,4 +191,4 @@ interface VisitorInsightsPluginOptions {
  */
 declare const visitorInsights: sanity.Plugin<VisitorInsightsPluginOptions>;
 
-export { ComparisonBar, MetricFigure, MetricValue, NoticeList, RangeKey, ReportEnvelope, ReportName, type ReportState, type UseReportOptions, type VisitorInsightsPluginOptions, VisitorInsightsTool, type VisitorInsightsToolProps, visitorInsights as default, formatCount, formatPercent, useReport, visitorInsights };
+export { AcquisitionPanel, ComparisonBar, DiagnosticsPanel, JourneyPanel, MeasurementHealthPanel, MetricFigure, MetricValue, NoticeList, RangeKey, ReportEnvelope, ReportName, type ReportState, TypefaceInterestPanel, type UseReportOptions, type VisitorInsightsPluginOptions, VisitorInsightsTool, type VisitorInsightsToolProps, visitorInsights as default, formatCount, formatPercent, useReport, visitorInsights };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as sanity from 'sanity';
 import React from 'react';
-import { R as ReportEnvelope, a as ReportName, b as RangeKey, M as MetricValue } from './ranges-D6AZwpmm.js';
-export { C as Coverage, D as DateRange, E as EventCutover, P as PREEXISTING, c as REPORT_NAMES, d as ReportError, S as SiteAnalyticsConfig, e as SourceName, f as SourceStatus, U as UnavailableReason, g as coverageForRange, i as isReportName, o as ok, p as partial, h as previousRange, r as resolveRange, u as unavailable, v as validateSiteConfig, j as valueOrNull } from './ranges-D6AZwpmm.js';
+import { R as ReportEnvelope, a as ReportName, b as RangeKey, M as MetricValue, A as AcquisitionData, D as DiagnosticReport, J as JourneyData, c as MeasurementHealthData, T as TypefaceInterestData } from './ranges-DSFapooC.js';
+export { C as Coverage, d as DateRange, E as EventCutover, P as PREEXISTING, e as REPORT_NAMES, f as ReportError, S as SiteAnalyticsConfig, g as SourceName, h as SourceStatus, U as UnavailableReason, i as coverageForRange, j as isReportName, o as ok, p as partial, k as previousRange, r as resolveRange, u as unavailable, v as validateSiteConfig, l as valueOrNull } from './ranges-DSFapooC.js';
 
 /**
  * The Visitor Insights Studio tool.
@@ -110,6 +110,45 @@ interface NoticeListProps {
  */
 declare function NoticeList({ notices }: NoticeListProps): React.ReactElement | null;
 
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+declare function MeasurementHealthPanel({ data }: {
+    data: MeasurementHealthData;
+}): React.ReactElement;
+/** Acquisition — where visitors came from, with design-industry referrers called out. */
+declare function AcquisitionPanel({ data }: {
+    data: AcquisitionData;
+}): React.ReactElement;
+/** Journey — per-step totals with adjacent drop-off, explicitly not a tracked path. */
+declare function JourneyPanel({ data }: {
+    data: JourneyData;
+}): React.ReactElement;
+/** Typeface interest — viewed, tested and bought per family. */
+declare function TypefaceInterestPanel({ data }: {
+    data: TypefaceInterestData;
+}): React.ReactElement;
+/**
+ * Diagnostics — what to fix before trusting anything else here.
+ *
+ * Deliberately the panel that still works with nothing configured: on a site without credentials
+ * it is the only one that can say something useful, and it is the first thing worth opening once
+ * credentials land.
+ */
+declare function DiagnosticsPanel({ data }: {
+    data: DiagnosticReport;
+}): React.ReactElement;
+
 /**
  * Studio entry point — browser only.
  *
@@ -152,4 +191,4 @@ interface VisitorInsightsPluginOptions {
  */
 declare const visitorInsights: sanity.Plugin<VisitorInsightsPluginOptions>;
 
-export { ComparisonBar, MetricFigure, MetricValue, NoticeList, RangeKey, ReportEnvelope, ReportName, type ReportState, type UseReportOptions, type VisitorInsightsPluginOptions, VisitorInsightsTool, type VisitorInsightsToolProps, visitorInsights as default, formatCount, formatPercent, useReport, visitorInsights };
+export { AcquisitionPanel, ComparisonBar, DiagnosticsPanel, JourneyPanel, MeasurementHealthPanel, MetricFigure, MetricValue, NoticeList, RangeKey, ReportEnvelope, ReportName, type ReportState, TypefaceInterestPanel, type UseReportOptions, type VisitorInsightsPluginOptions, VisitorInsightsTool, type VisitorInsightsToolProps, visitorInsights as default, formatCount, formatPercent, useReport, visitorInsights };

package/dist/index.js

@@ -20,11 +20,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AcquisitionPanel: () => AcquisitionPanel,
   ComparisonBar: () => ComparisonBar,
+  DiagnosticsPanel: () => DiagnosticsPanel,
+  JourneyPanel: () => JourneyPanel,
+  MeasurementHealthPanel: () => MeasurementHealthPanel,
   MetricFigure: () => MetricFigure,
   NoticeList: () => NoticeList,
   PREEXISTING: () => PREEXISTING,
   REPORT_NAMES: () => REPORT_NAMES,
+  TypefaceInterestPanel: () => TypefaceInterestPanel,
   VisitorInsightsTool: () => VisitorInsightsTool,
   coverageForRange: () => coverageForRange,
   default: () => index_default,
@@ -313,6 +318,34 @@ function TypefaceInterestPanel({ data }) {
     ] }) })
   ] });
 }
+var CHECK_TONE = {
+  pass: "positive",
+  warn: "caution",
+  fail: "critical",
+  skipped: "default"
+};
+var CHECK_WORD = {
+  pass: "Pass",
+  warn: "Check",
+  fail: "Fail",
+  skipped: "Skipped"
+};
+function DiagnosticsPanel({ data }) {
+  const failing = data.checks.filter((c) => c.status === "fail").length;
+  const warning = data.checks.filter((c) => c.status === "warn").length;
+  const summary = data.verdict === "pass" ? "Everything checked out. The figures in the other panels can be taken at face value." : `${failing} failing, ${warning} worth a look. Panels depending on these will be wrong or incomplete until they are resolved.`;
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_sanity_ui_compat2.Stack, { space: 4, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_sanity_ui_compat2.Card, { padding: 3, radius: 2, tone: CHECK_TONE[data.verdict], border: true, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_sanity_ui_compat2.Text, { size: 1, children: summary }) }),
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_sanity_ui_compat2.Stack, { space: 3, children: data.checks.map((item) => /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_sanity_ui_compat2.Card, { padding: 3, radius: 2, tone: "transparent", border: true, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_sanity_ui_compat2.Stack, { space: 3, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_sanity_ui_compat2.Flex, { align: "center", justify: "space-between", gap: 3, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_sanity_ui_compat2.Text, { size: 1, weight: "semibold", children: item.label }),
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_sanity_ui_compat2.Card, { padding: 2, radius: 2, tone: CHECK_TONE[item.status], children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_sanity_ui_compat2.Text, { size: 0, weight: "medium", children: CHECK_WORD[item.status] }) })
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_sanity_ui_compat2.Text, { size: 1, muted: true, children: item.detail }),
+      item.remedy && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_sanity_ui_compat2.Text, { size: 1, children: item.remedy })
+    ] }) }, item.id)) })
+  ] });
+}
 
 // src/studio/VisitorInsightsTool.tsx
 var import_jsx_runtime3 = require("react/jsx-runtime");
@@ -325,7 +358,8 @@ var PANELS = [
   { report: "measurement-health", label: "Measurement health", blurb: "How much of reality each source actually sees" },
   { report: "acquisition", label: "Acquisition", blurb: "Where visitors come from" },
   { report: "journey", label: "Journey", blurb: "How far visitors get, and where they stop" },
-  { report: "typeface-interest", label: "Typeface interest", blurb: "Viewed, tested and bought, by family" }
+  { report: "typeface-interest", label: "Typeface interest", blurb: "Viewed, tested and bought, by family" },
+  { report: "diagnostics", label: "Diagnostics", blurb: "What to fix before trusting the numbers above" }
 ];
 function RangeSelector({ value, onChange }) {
   const refs = (0, import_react2.useRef)([]);
@@ -430,6 +464,7 @@ function ReportPanel({ report, apiBaseUrl, range }) {
       report === "acquisition" && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(AcquisitionPanel, { data: state.envelope.data }),
       report === "journey" && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(JourneyPanel, { data: state.envelope.data }),
       report === "typeface-interest" && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(TypefaceInterestPanel, { data: state.envelope.data }),
+      report === "diagnostics" && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(DiagnosticsPanel, { data: state.envelope.data }),
       /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_sanity_ui_compat3.Text, { size: 0, muted: true, children: [
         state.envelope.range.start,
         " to ",
@@ -488,7 +523,8 @@ var REPORT_NAMES = [
   "measurement-health",
   "acquisition",
   "journey",
-  "typeface-interest"
+  "typeface-interest",
+  "diagnostics"
 ];
 function isReportName(value) {
   return typeof value === "string" && REPORT_NAMES.includes(value);
@@ -629,11 +665,16 @@ var visitorInsights = (0, import_sanity2.definePlugin)((options) => {
 var index_default = visitorInsights;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AcquisitionPanel,
   ComparisonBar,
+  DiagnosticsPanel,
+  JourneyPanel,
+  MeasurementHealthPanel,
   MetricFigure,
   NoticeList,
   PREEXISTING,
   REPORT_NAMES,
+  TypefaceInterestPanel,
   VisitorInsightsTool,
   coverageForRange,
   formatCount,