@liiift-studio/sanity-visitor-insights 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liiift Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# @liiift-studio/sanity-visitor-insights
+
+Visitor-**behaviour** analytics inside Sanity Studio, for Darden, TDF and MCKL.
+
+This is not a sales tool and does not duplicate the sales portal. It reports what visitors do —
+where they come from, how far they get, which typefaces they engage with — and reconciles GA4
+against Vercel so you can see how much of that behaviour you are actually measuring. Orders appear
+only as a conversion anchor and a count; no revenue, and no customer data.
+
+---
+
+## What it reports
+
+| Panel | Question it answers |
+|---|---|
+| **Measurement health** | How much of reality does each source actually see? |
+| **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? |
+
+Each panel offers a week, quarter or year range.
+
+---
+
+## Design decisions worth knowing
+
+These are deliberate and load-bearing. Changing them changes whether the numbers are honest.
+
+**Pageviews are compared to pageviews.** An earlier design subtracted Vercel pageviews from GA4
+sessions and attributed the difference to consent, ad-blockers and bots. Sessions and pageviews are
+different units, so that difference is dominated by the unit mismatch rather than by anything
+missing — and GA4 exposes no signal separating those three causes anyway. The panel now compares
+like with like and labels the remainder unexplained.
+
+**Consent is measured, not inferred.** A `consent_granted` event turns the single largest cause of
+the GA4/Vercel gap into a real number. Until a site instruments it, the panel says so instead of
+guessing.
+
+**A missing metric is never zero.** Every figure is a `MetricValue` tagged union, so an
+uninstrumented event cannot silently coerce to `0` and be charted as a real trough. Unavailable
+figures render as an em dash with a stated reason.
+
+**The journey is a funnel, not a path.** GA4's Data API has no path-exploration endpoint, and
+`runFunnelReport` returns step-conversion marginals rather than observed sequences. Drawing a flow
+diagram from that would assert co-occurrence nobody measured. Steps are reported as independent
+totals and the response is flagged approximate.
+
+**Auth is the Studio's own session token.** The Studio forwards its Sanity token and the route
+verifies it against Sanity. A shared secret would be extractable from the public Studio bundle,
+moving the bar from "know the URL" to "open devtools", and would give no identity to audit.
+
+**No charting library.** These panels compare and rank a handful of values, which labelled bars and
+tables do as well as a chart — without a large Studio-bundle dependency or theme-token bridging for
+light and dark. Tables are the accessible representation *and* the visual one, so they cannot drift
+apart.
+
+**No customer data leaves Sanity.** Order queries project `{_createdAt, orderStatus}` and, for the
+interest panel, dereference only a typeface title. Joining behavioural data to order PII would turn
+aggregate statistics into personal-data processing.
+
+---
+
+## Installing
+
+```bash
+npm install @liiift-studio/sanity-visitor-insights
+```
+
+### 1. Studio
+
+```ts
+// sanity.config.ts
+import { visitorInsights } from '@liiift-studio/sanity-visitor-insights'
+
+export default defineConfig({
+  plugins: [
+    visitorInsights({
+      apiBaseUrl: 'https://dardenstudio.com',
+      siteLabel: 'Darden Studio',
+      roles: ['administrator'],
+    }),
+  ],
+})
+```
+
+Pass `apiBaseUrl: ''` when the Studio is served from the same origin as the site (Darden and TDF).
+MCKL's Studio deploys separately to `mckl.sanity.studio`, so it needs the full site URL.
+
+Omit `roles` to show the tool to every Studio user. These panels read order-derived conversion
+figures, so gating to administrators is usually right.
+
+### 2. Site API route
+
+```js
+// pages/api/visitor-insights/[report].js
+import { createVisitorInsightsHandler } from '@liiift-studio/sanity-visitor-insights/server'
+import { client } from '../../../lib/sanityClient'
+
+export default createVisitorInsightsHandler({
+  sanityClient: client,
+  config: {
+    siteId: 'darden',
+    label: 'Darden Studio',
+    ga4: { propertyId: '123456789', timezone: 'America/New_York' },
+    vercel: { projectId: 'prj_...' },
+    orders: { documentType: 'order', typefacesField: 'typefaces' },
+    eventCutovers: {
+      page_view: 'preexisting',
+      view_item: 'preexisting',
+      add_to_cart: 'preexisting',
+      begin_checkout: 'preexisting',
+      purchase: 'preexisting',
+      consent_granted: null,
+      tester_engaged: null,
+    },
+    // Only needed where the Studio is on a different origin.
+    allowedStudioOrigins: ['https://mckl.sanity.studio'],
+  },
+})
+```
+
+`propertyId` is the **numeric** GA4 property id from GA4 Admin, not the `G-XXXXXXX` measurement id.
+The config is validated at construction and will throw on deploy rather than silently returning
+empty charts — pasting a measurement id here is caught by name.
+
+### 3. Environment variables
+
+| Variable | Where | What |
+|---|---|---|
+| `VISITOR_INSIGHTS_GA4_SERVICE_ACCOUNT` | Site (server) | Service-account JSON, raw or base64 |
+| `VISITOR_INSIGHTS_VERCEL_TOKEN` | Site (server) | Vercel API token with project read access |
+| `SANITY_STUDIO_PROJECT_ID` | Site (server) | Already set; used to verify Studio tokens |
+
+The service account needs **Viewer** on each GA4 property. Nothing here is `NEXT_PUBLIC_`; none of
+it reaches the browser.
+
+---
+
+## Before it will show anything useful
+
+- **Set GA4 data retention to 14 months** on every property (Admin → Data Settings → Data
+  Retention). The default may be 2 months, which makes the year range return nothing for most of
+  its span. It does not backfill, so every day at the default is data lost permanently.
+- **Register custom dimensions before deploying the events that populate them.** A dimension only
+  reports from its registration date forward.
+- **Instrument `consent_granted` and `tester_engaged`.** Without them the measurement-health
+  residual stays unexplained and the journey funnel has a hole where the tester belongs.
+- **`tester_engaged` must require a change from the tester's default state** — custom text, or a
+  weight/size change. Firing on tester open counts every page load as a test and makes the
+  viewed-to-tested ratio meaningless.
+
+---
+
+## Development
+
+```bash
+npm install
+npm test          # pure logic plus the client/server boundary guard
+npm run build
+```
+
+The boundary test walks the real import graph from each entry point and fails if anything reachable
+from the Studio entry touches `src/server/`, `node:crypto` or `process.env`. That check exists
+because the failure it prevents — a credential-reading module shipped in a public Studio bundle —
+is invisible to type checking and to review.
+
+---
+
+## Architecture
+
+```
+src/
+  types.ts          MetricValue, ranges, report envelope
+  reportData.ts     Result shapes shared by server and panels, importing neither
+  core/             Pure logic: cutovers, range resolution, config validation
+  server/           Node only — GA4, Vercel, Sanity, auth, cache, handler factory
+  studio/           Browser only — the tool, panels and figure renderers
+```
+
+`core/` and `reportData.ts` are shared. Nothing in `studio/` may import from `server/`, which is
+what the split export subpaths and the boundary test enforce together.

package/dist/index.d.mts

@@ -0,0 +1,155 @@
+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';
+
+/**
+ * The Visitor Insights Studio tool.
+ *
+ * One range control drives every panel, implemented once here as a proper radiogroup with
+ * roving tabindex — repeating a bespoke toggle per panel is how keyboard behaviour ends up
+ * inconsistent between them.
+ */
+
+/** Props supplied by the plugin config. */
+interface VisitorInsightsToolProps {
+    apiBaseUrl: string;
+    siteLabel: string;
+}
+/** The tool itself. */
+declare function VisitorInsightsTool({ apiBaseUrl, siteLabel }: VisitorInsightsToolProps): React.ReactElement;
+
+/**
+ * Data hook for the Studio panels.
+ *
+ * Forwards the Studio's own Sanity session token to the site's API route, which verifies it against
+ * Sanity. There is no shared secret: the Studio bundle is public, so anything compiled into it is
+ * extractable.
+ */
+
+/** Loading state for a report. */
+type ReportState<T> = {
+    status: 'idle';
+} | {
+    status: 'loading';
+} | {
+    status: 'ready';
+    envelope: ReportEnvelope<T>;
+} | {
+    status: 'error';
+    message: string;
+};
+/** Options for useReport. */
+interface UseReportOptions {
+    /** Base URL of the site serving the reports, e.g. `https://dardenstudio.com`. */
+    apiBaseUrl: string;
+    report: ReportName;
+    range: RangeKey;
+}
+/**
+ * Fetch a report, re-fetching when the range changes.
+ *
+ * @returns the current state plus a `reload` for manual refresh
+ */
+declare function useReport<T>({ apiBaseUrl, report, range }: UseReportOptions): {
+    state: ReportState<T>;
+    reload: () => void;
+};
+
+/**
+ * Shared renderers for metric values and comparison bars.
+ *
+ * Two rules are enforced here rather than left to each panel:
+ *
+ *   1. An unavailable metric renders as an em dash with a stated reason — never as "0". A missing
+ *      measurement and a measured zero mean opposite things, and must never look alike.
+ *   2. Nothing is distinguished by colour alone. Bars carry a text value, a percentage and an
+ *      accessible label, so the figure survives greyscale, colour blindness and both Studio themes.
+ */
+
+/** Format a number with thousands separators. */
+declare function formatCount(value: number): string;
+/** Format a 0–1 ratio as a percentage. */
+declare function formatPercent(ratio: number, digits?: number): string;
+/** Props for MetricFigure. */
+interface MetricFigureProps {
+    metric: MetricValue;
+    /** Accessible label describing what this number counts. */
+    label: string;
+    size?: number;
+}
+/**
+ * Render a metric value, handling the absent case visibly.
+ * Screen readers get the reason text rather than an unexplained dash.
+ */
+declare function MetricFigure({ metric, label, size }: MetricFigureProps): React.ReactElement;
+/** Props for ComparisonBar. */
+interface ComparisonBarProps {
+    label: string;
+    metric: MetricValue;
+    /** Largest value across the sibling bars, used to scale width. */
+    max: number;
+    /** Tone conveys category, but never carries meaning on its own. */
+    tone?: 'primary' | 'positive' | 'caution' | 'default';
+}
+/**
+ * A horizontal bar with its value printed alongside.
+ *
+ * Deliberately CSS rather than a charting library: these panels compare and rank a handful of
+ * values, which a labelled bar does as well as a chart while avoiding a large dependency in the
+ * Studio bundle and the theme-token bridging that a chart library would need for light and dark.
+ */
+declare function ComparisonBar({ label, metric, max, tone }: ComparisonBarProps): React.ReactElement;
+/** Props for NoticeList. */
+interface NoticeListProps {
+    notices: string[];
+}
+/**
+ * Caveats attached to a report — sampling, processing lag, instrumentation cutovers.
+ * Rendered in the panel rather than a README: a caveat nobody sees does not prevent a wrong read.
+ */
+declare function NoticeList({ notices }: NoticeListProps): React.ReactElement | null;
+
+/**
+ * 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.
+ */
+/** Options for the Studio plugin. */
+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'],
+ *   }),
+ * ]
+ * ```
+ */
+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 };

package/dist/index.d.ts

@@ -0,0 +1,155 @@
+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';
+
+/**
+ * The Visitor Insights Studio tool.
+ *
+ * One range control drives every panel, implemented once here as a proper radiogroup with
+ * roving tabindex — repeating a bespoke toggle per panel is how keyboard behaviour ends up
+ * inconsistent between them.
+ */
+
+/** Props supplied by the plugin config. */
+interface VisitorInsightsToolProps {
+    apiBaseUrl: string;
+    siteLabel: string;
+}
+/** The tool itself. */
+declare function VisitorInsightsTool({ apiBaseUrl, siteLabel }: VisitorInsightsToolProps): React.ReactElement;
+
+/**
+ * Data hook for the Studio panels.
+ *
+ * Forwards the Studio's own Sanity session token to the site's API route, which verifies it against
+ * Sanity. There is no shared secret: the Studio bundle is public, so anything compiled into it is
+ * extractable.
+ */
+
+/** Loading state for a report. */
+type ReportState<T> = {
+    status: 'idle';
+} | {
+    status: 'loading';
+} | {
+    status: 'ready';
+    envelope: ReportEnvelope<T>;
+} | {
+    status: 'error';
+    message: string;
+};
+/** Options for useReport. */
+interface UseReportOptions {
+    /** Base URL of the site serving the reports, e.g. `https://dardenstudio.com`. */
+    apiBaseUrl: string;
+    report: ReportName;
+    range: RangeKey;
+}
+/**
+ * Fetch a report, re-fetching when the range changes.
+ *
+ * @returns the current state plus a `reload` for manual refresh
+ */
+declare function useReport<T>({ apiBaseUrl, report, range }: UseReportOptions): {
+    state: ReportState<T>;
+    reload: () => void;
+};
+
+/**
+ * Shared renderers for metric values and comparison bars.
+ *
+ * Two rules are enforced here rather than left to each panel:
+ *
+ *   1. An unavailable metric renders as an em dash with a stated reason — never as "0". A missing
+ *      measurement and a measured zero mean opposite things, and must never look alike.
+ *   2. Nothing is distinguished by colour alone. Bars carry a text value, a percentage and an
+ *      accessible label, so the figure survives greyscale, colour blindness and both Studio themes.
+ */
+
+/** Format a number with thousands separators. */
+declare function formatCount(value: number): string;
+/** Format a 0–1 ratio as a percentage. */
+declare function formatPercent(ratio: number, digits?: number): string;
+/** Props for MetricFigure. */
+interface MetricFigureProps {
+    metric: MetricValue;
+    /** Accessible label describing what this number counts. */
+    label: string;
+    size?: number;
+}
+/**
+ * Render a metric value, handling the absent case visibly.
+ * Screen readers get the reason text rather than an unexplained dash.
+ */
+declare function MetricFigure({ metric, label, size }: MetricFigureProps): React.ReactElement;
+/** Props for ComparisonBar. */
+interface ComparisonBarProps {
+    label: string;
+    metric: MetricValue;
+    /** Largest value across the sibling bars, used to scale width. */
+    max: number;
+    /** Tone conveys category, but never carries meaning on its own. */
+    tone?: 'primary' | 'positive' | 'caution' | 'default';
+}
+/**
+ * A horizontal bar with its value printed alongside.
+ *
+ * Deliberately CSS rather than a charting library: these panels compare and rank a handful of
+ * values, which a labelled bar does as well as a chart while avoiding a large dependency in the
+ * Studio bundle and the theme-token bridging that a chart library would need for light and dark.
+ */
+declare function ComparisonBar({ label, metric, max, tone }: ComparisonBarProps): React.ReactElement;
+/** Props for NoticeList. */
+interface NoticeListProps {
+    notices: string[];
+}
+/**
+ * Caveats attached to a report — sampling, processing lag, instrumentation cutovers.
+ * Rendered in the panel rather than a README: a caveat nobody sees does not prevent a wrong read.
+ */
+declare function NoticeList({ notices }: NoticeListProps): React.ReactElement | null;
+
+/**
+ * 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.
+ */
+/** Options for the Studio plugin. */
+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'],
+ *   }),
+ * ]
+ * ```
+ */
+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 };