@liiift-studio/sanity-visitor-insights 0.11.0 → 0.13.0

package/README.md

@@ -184,6 +184,7 @@ empty charts — pasting a measurement id here is caught by name.
 
 | Variable | Where | What |
 |---|---|---|
+| `VISITOR_INSIGHTS_ENABLED` | Site (server) | **Required.** Any truthy value switches the route on |
 | `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 |
@@ -191,6 +192,67 @@ empty charts — pasting a measurement id here is caught by name.
 The service account needs **Viewer** on each GA4 property. Nothing here is `NEXT_PUBLIC_`; none of
 it reaches the browser.
 
+#### Scoping to your own hostnames
+
+`ga4.hostnames` restricts every GA4 report to the hosts you name. A GA4 property is not necessarily
+one website — Darden's also receives `impactsport.ca`, an unrelated business, which was inside the
+headline session count, both percentages computed from it, and the funnel's entry rung. Omit the
+field to accept every hostname, which is the old behaviour.
+
+```js
+ga4: {
+  propertyId: '123456789',
+  timezone: 'America/Los_Angeles',
+  hostnames: ['www.dardenstudio.com', 'dardenstudio.com'],
+}
+```
+
+#### Orders: status and revenue
+
+`orders.countedStatuses` names the statuses that count as a real sale; everything else is excluded
+and reported separately. Leave it unset and test, failed, pending and refunded orders all count as
+sales — at seven orders a quarter, one test order is a 14% error. The status breakdown is always
+reported so you can see what vocabulary your own orders use before configuring this.
+
+`orders.totalField` turns on revenue. Without it a $30 web licence and a $400 multi-seat desktop
+licence are the same integer, so nothing can be ranked by what it is worth. An order total is not a
+customer field; the PII projection allow-list is unchanged.
+
+```js
+orders: {
+  documentType: 'order',
+  typefacesField: 'typefaces',
+  statusField: 'orderStatus',
+  countedStatuses: ['complete', 'paid'],
+  totalField: 'total',
+  currency: 'USD',
+}
+```
+
+#### Conversions that are not a sale
+
+`eventNames.enquiry`, `.subscribe` and `.assetDownload` surface outcomes the funnel used to score as
+drop-offs. A custom commission is worth many multiples of a licence, and the funnel ended at
+`purchase` — so the visitor who read three typeface pages and emailed was counted as a leak.
+
+```js
+eventNames: {
+  enquiry: ['enquiry_submit'],
+  subscribe: ['subscribe'],
+}
+```
+
+#### The master switch
+
+`VISITOR_INSIGHTS_ENABLED` is an explicit opt-in. Unset, the route answers `503` with
+`disabled: true` and does no Sanity or GA4 work, and the Studio tool shows a neutral "Switched off"
+card rather than an error. Set it to anything that is not `false`, `0`, `off`, `no`, `disabled` or
+empty — a word, a code, `true`, whatever the site's operator prefers.
+
+This is deliberately the opposite default to `SALES_PORTAL_ENABLED`, which is on unless the value
+is literally `"false"`. Mounting this route wires up analytics credentials, so it should not begin
+answering on a site where nobody chose to switch it on.
+
 ---
 
 ## Before it will show anything useful

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, A as AcquisitionData, D as DiagnosticReport, J as JourneyData, c as MeasurementHealthData, T as TypefaceInterestData } from './ranges-YGStz1nR.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-YGStz1nR.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-CiTnQEnz.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-CiTnQEnz.mjs';
 
 /**
  * The Visitor Insights Studio tool.
@@ -54,6 +54,7 @@ type ReportState<T> = {
 } | {
     status: 'error';
     message: string;
+    disabled?: boolean;
 };
 /** Options for useReport. */
 interface UseReportOptions {
@@ -92,7 +93,6 @@ declare function useReport<T>({ apiBaseUrl, report, range, custom }: UseReportOp
 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. */
@@ -167,8 +167,9 @@ declare function MeasurementHealthPanel({ data }: {
     data: MeasurementHealthData;
 }): React.ReactElement;
 /** Acquisition — where visitors came from, with design-industry referrers called out. */
-declare function AcquisitionPanel({ data }: {
+declare function AcquisitionPanel({ data, previous }: {
     data: AcquisitionData;
+    previous?: AcquisitionData;
 }): React.ReactElement;
 /** Journey — a funnel, drawn as a tracked sequence or as independent totals, whichever the report used. */
 declare function JourneyPanel({ data }: {

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, A as AcquisitionData, D as DiagnosticReport, J as JourneyData, c as MeasurementHealthData, T as TypefaceInterestData } from './ranges-YGStz1nR.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-YGStz1nR.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-CiTnQEnz.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-CiTnQEnz.js';
 
 /**
  * The Visitor Insights Studio tool.
@@ -54,6 +54,7 @@ type ReportState<T> = {
 } | {
     status: 'error';
     message: string;
+    disabled?: boolean;
 };
 /** Options for useReport. */
 interface UseReportOptions {
@@ -92,7 +93,6 @@ declare function useReport<T>({ apiBaseUrl, report, range, custom }: UseReportOp
 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. */
@@ -167,8 +167,9 @@ declare function MeasurementHealthPanel({ data }: {
     data: MeasurementHealthData;
 }): React.ReactElement;
 /** Acquisition — where visitors came from, with design-industry referrers called out. */
-declare function AcquisitionPanel({ data }: {
+declare function AcquisitionPanel({ data, previous }: {
     data: AcquisitionData;
+    previous?: AcquisitionData;
 }): React.ReactElement;
 /** Journey — a funnel, drawn as a tracked sequence or as independent totals, whichever the report used. */
 declare function JourneyPanel({ data }: {