@liiift-studio/sanity-visitor-insights 0.11.0 → 0.12.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,17 @@ 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.
 
+#### 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

@@ -54,6 +54,7 @@ type ReportState<T> = {
 } | {
     status: 'error';
     message: string;
+    disabled?: boolean;
 };
 /** Options for useReport. */
 interface UseReportOptions {

package/dist/index.d.ts

@@ -54,6 +54,7 @@ type ReportState<T> = {
 } | {
     status: 'error';
     message: string;
+    disabled?: boolean;
 };
 /** Options for useReport. */
 interface UseReportOptions {

package/dist/index.js

@@ -103,12 +103,14 @@ function useReport({ apiBaseUrl, report, range, custom }) {
         if (requestIdRef.current !== requestId) return;
         if (!response.ok) {
           let detail = response.status === 401 ? "Not authorised \u2014 sign in to the Studio again." : `Request failed (${response.status})`;
-          if (response.status === 400) {
+          let disabled = false;
+          if (response.status === 400 || response.status === 503) {
             const body = await response.json().catch(() => null);
             if (body?.error) detail = body.error;
+            disabled = body?.disabled === true;
           }
           if (requestIdRef.current !== requestId) return;
-          setState({ status: "error", message: detail });
+          setState({ status: "error", message: detail, disabled });
           return;
         }
         const envelope = await response.json();
@@ -1126,16 +1128,20 @@ function ReportPanel({
   custom
 }) {
   const { state, reload } = useReport({ apiBaseUrl, report, range, custom });
-  const liveMessage = state.status === "loading" ? "Loading report" : state.status === "ready" ? `${report} updated for ${range === "custom" ? `${custom.start} to ${custom.end}` : `the selected ${range}`}` : state.status === "error" ? `Report failed: ${state.message}` : "";
+  const liveMessage = state.status === "loading" ? "Loading report" : state.status === "ready" ? `${report} updated for ${range === "custom" ? `${custom.start} to ${custom.end}` : `the selected ${range}`}` : state.status === "error" ? state.disabled ? "Visitor insights is switched off for this site" : `Report failed: ${state.message}` : "";
   return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_sanity_ui_compat3.Stack, { space: 4, children: [
     /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_sanity_ui_compat3.Box, { "aria-live": "polite", style: { position: "absolute", width: 1, height: 1, overflow: "hidden", clip: "rect(0 0 0 0)" }, children: liveMessage }),
     state.status === "loading" && /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_sanity_ui_compat3.Flex, { align: "center", gap: 3, padding: 4, children: [
       /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_sanity_ui_compat3.Spinner, { muted: true }),
       /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_sanity_ui_compat3.Text, { size: 1, muted: true, children: "Loading\u2026" })
     ] }),
-    state.status === "error" && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_sanity_ui_compat3.Card, { padding: 4, radius: 2, tone: "critical", border: true, children: /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_sanity_ui_compat3.Stack, { space: 3, children: [
-      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_sanity_ui_compat3.Text, { size: 1, children: state.message }),
-      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_sanity_ui_compat3.Box, { children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_sanity_ui_compat3.Button, { text: "Try again", mode: "ghost", fontSize: 1, onClick: reload }) })
+    state.status === "error" && // A switched-off site is a configuration state, not a fault: it gets a neutral card
+    // and no retry, because retrying cannot change the answer. Everything else keeps
+    // the critical tone and the retry.
+    /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_sanity_ui_compat3.Card, { padding: 4, radius: 2, tone: state.disabled ? "transparent" : "critical", border: true, children: /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_sanity_ui_compat3.Stack, { space: 3, children: [
+      state.disabled && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_sanity_ui_compat3.Text, { size: 1, weight: "medium", children: "Switched off" }),
+      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_sanity_ui_compat3.Text, { size: 1, muted: state.disabled, children: state.message }),
+      !state.disabled && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_sanity_ui_compat3.Box, { children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_sanity_ui_compat3.Button, { text: "Try again", mode: "ghost", fontSize: 1, onClick: reload }) })
     ] }) }),
     state.status === "ready" && /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_sanity_ui_compat3.Stack, { space: 4, children: [
       /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(SourceStatusRow, { sources: state.envelope.sources }),