@liiift-studio/sanity-visitor-insights 0.1.0

package/dist/server.js

@@ -0,0 +1,937 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server.ts
+var server_exports = {};
+__export(server_exports, {
+  DESIGN_INDUSTRY_SOURCES: () => DESIGN_INDUSTRY_SOURCES,
+  ENV_VARS: () => ENV_VARS,
+  GA4_PROCESSING_LAG_DAYS: () => GA4_PROCESSING_LAG_DAYS,
+  JOURNEY_STEPS: () => JOURNEY_STEPS,
+  PREEXISTING: () => PREEXISTING,
+  REPORT_NAMES: () => REPORT_NAMES,
+  applyCors: () => applyCors,
+  applyCoverage: () => applyCoverage,
+  assertValidSiteConfig: () => assertValidSiteConfig,
+  clearCache: () => clearCache,
+  coverageForRange: () => coverageForRange,
+  coverageNotices: () => coverageNotices,
+  createVisitorInsightsHandler: () => createVisitorInsightsHandler,
+  daysBetween: () => daysBetween,
+  formatInTimeZone: () => formatInTimeZone,
+  isReportName: () => isReportName,
+  isValidTimeZone: () => isValidTimeZone,
+  ok: () => ok,
+  partial: () => partial,
+  previousRange: () => previousRange,
+  provisionalDates: () => provisionalDates,
+  provisionalNotice: () => provisionalNotice,
+  requireStudioUser: () => requireStudioUser,
+  resolveRange: () => resolveRange,
+  shiftDays: () => shiftDays,
+  unavailable: () => unavailable,
+  validateSiteConfig: () => validateSiteConfig,
+  valueOrNull: () => valueOrNull,
+  verifyStudioRequest: () => verifyStudioRequest
+});
+module.exports = __toCommonJS(server_exports);
+
+// src/types.ts
+function ok(value) {
+  return { status: "ok", value };
+}
+function unavailable(reason, detail) {
+  return { status: "unavailable", reason, detail };
+}
+function partial(value, coveredFrom, note) {
+  return { status: "partial", value, coveredFrom, note };
+}
+function valueOrNull(metric) {
+  return metric.status === "unavailable" ? null : metric.value;
+}
+var REPORT_NAMES = [
+  "measurement-health",
+  "acquisition",
+  "journey",
+  "typeface-interest"
+];
+function isReportName(value) {
+  return typeof value === "string" && REPORT_NAMES.includes(value);
+}
+
+// src/core/siteConfig.ts
+function validateSiteConfig(config) {
+  const problems = [];
+  if (!config) {
+    return [{ field: "config", message: "No site config supplied" }];
+  }
+  if (!config.siteId) problems.push({ field: "siteId", message: "Required" });
+  if (!config.label) problems.push({ field: "label", message: "Required" });
+  if (config.ga4) {
+    const { propertyId, timezone } = config.ga4;
+    if (!propertyId) {
+      problems.push({ field: "ga4.propertyId", message: "Required when ga4 is configured" });
+    } else if (propertyId.startsWith("G-")) {
+      problems.push({
+        field: "ga4.propertyId",
+        message: `Looks like a measurement id ("${propertyId}"). The Data API needs the numeric property id from GA4 Admin instead.`
+      });
+    } else if (!/^\d+$/.test(propertyId)) {
+      problems.push({ field: "ga4.propertyId", message: "Must be the numeric GA4 property id" });
+    }
+    if (!timezone) {
+      problems.push({ field: "ga4.timezone", message: "Required \u2014 ranges are anchored to it" });
+    } else if (!isValidTimeZone(timezone)) {
+      problems.push({ field: "ga4.timezone", message: `Not a recognised IANA timezone: ${timezone}` });
+    }
+  }
+  if (config.vercel && !config.vercel.projectId) {
+    problems.push({ field: "vercel.projectId", message: "Required when vercel is configured" });
+  }
+  if (!config.orders?.documentType) {
+    problems.push({ field: "orders.documentType", message: "Required" });
+  }
+  if (!config.eventCutovers) {
+    problems.push({ field: "eventCutovers", message: "Required \u2014 omit events the site does not have" });
+  }
+  for (const origin of config.allowedStudioOrigins ?? []) {
+    if (!/^https?:\/\//.test(origin)) {
+      problems.push({ field: "allowedStudioOrigins", message: `Must be a full origin including scheme: ${origin}` });
+    }
+    if (origin.endsWith("/")) {
+      problems.push({ field: "allowedStudioOrigins", message: `Must not have a trailing slash: ${origin}` });
+    }
+  }
+  return problems;
+}
+function isValidTimeZone(timeZone) {
+  try {
+    new Intl.DateTimeFormat("en-CA", { timeZone });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function assertValidSiteConfig(config) {
+  const problems = validateSiteConfig(config);
+  if (problems.length > 0) {
+    const detail = problems.map((p) => `  ${p.field}: ${p.message}`).join("\n");
+    throw new Error(`Invalid visitor-insights site config:
+${detail}`);
+  }
+}
+
+// src/core/cutover.ts
+var PREEXISTING = "preexisting";
+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 };
+  return { status: "full" };
+}
+function applyCoverage(count, coverage) {
+  if (coverage.status === "none") {
+    return unavailable(
+      coverage.reason === "before_cutover" ? "before_cutover" : "not_instrumented",
+      coverage.cutover ? `Instrumented from ${coverage.cutover}` : void 0
+    );
+  }
+  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`);
+  }
+  return { status: "ok", value: count };
+}
+function coverageNotices(cutovers, eventNames, range) {
+  const notices = [];
+  for (const name of eventNames) {
+    const coverage = coverageForRange(cutovers, name, range);
+    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 === "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") {
+      notices.push(`${name} did not exist during this range; it was instrumented on ${coverage.cutover}.`);
+    }
+  }
+  return notices;
+}
+
+// src/core/ranges.ts
+var GA4_PROCESSING_LAG_DAYS = 2;
+function formatInTimeZone(date, timeZone) {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit"
+  }).formatToParts(date);
+  const get = (type) => parts.find((p) => p.type === type)?.value ?? "";
+  return `${get("year")}-${get("month")}-${get("day")}`;
+}
+function shiftDays(isoDate, days) {
+  const time = Date.parse(`${isoDate}T00:00:00Z`);
+  if (Number.isNaN(time)) throw new Error(`Invalid ISO date: ${isoDate}`);
+  return new Date(time + days * 864e5).toISOString().slice(0, 10);
+}
+function daysBetween(start, end) {
+  return Math.round((Date.parse(`${end}T00:00:00Z`) - Date.parse(`${start}T00:00:00Z`)) / 864e5) + 1;
+}
+var RANGE_DAYS = {
+  week: 7,
+  quarter: 91,
+  year: 365
+};
+function resolveRange(key, timezone, now = /* @__PURE__ */ new Date()) {
+  const end = formatInTimeZone(now, timezone);
+  const start = shiftDays(end, -(RANGE_DAYS[key] - 1));
+  return { key, start, end, timezone };
+}
+function previousRange(range) {
+  const span = daysBetween(range.start, range.end);
+  return {
+    key: range.key,
+    start: shiftDays(range.start, -span),
+    end: shiftDays(range.end, -span),
+    timezone: range.timezone
+  };
+}
+function provisionalDates(range, now = /* @__PURE__ */ new Date()) {
+  const today = formatInTimeZone(now, range.timezone);
+  const dates = [];
+  for (let i = 0; i < GA4_PROCESSING_LAG_DAYS; i += 1) {
+    const date = shiftDays(today, -i);
+    if (date >= range.start && date <= range.end) dates.push(date);
+  }
+  return dates.sort();
+}
+function provisionalNotice(range, now = /* @__PURE__ */ new Date()) {
+  const dates = provisionalDates(range, now);
+  if (dates.length === 0) return null;
+  const from = dates[0];
+  return `GA4 has not finished processing ${from} onwards; those figures are provisional and will rise.`;
+}
+
+// src/server/auth.ts
+function header(req, name) {
+  const raw = req.headers[name] ?? req.headers[name.toLowerCase()];
+  return Array.isArray(raw) ? raw[0] : raw;
+}
+async function verifyStudioRequest(req, sanityProjectId) {
+  const authorization = header(req, "authorization") ?? "";
+  const token = authorization.startsWith("Bearer ") ? authorization.slice(7).trim() : null;
+  if (!token) return { ok: false, reason: "no-token" };
+  if (!sanityProjectId) {
+    console.error("Visitor insights: Sanity project id not configured \u2014 cannot verify Studio requests");
+    return { ok: false, reason: "not-configured" };
+  }
+  try {
+    const response = await fetch(`https://${sanityProjectId}.api.sanity.io/v2021-06-07/users/me`, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    if (!response.ok) return { ok: false, reason: `sanity-${response.status}` };
+    const user = await response.json();
+    if (!user || !user.id) return { ok: false, reason: "no-user" };
+    return { ok: true, user };
+  } catch (e) {
+    console.error("Visitor insights: Studio token verification failed:", e.message);
+    return { ok: false, reason: "verify-error" };
+  }
+}
+function applyCors(req, res, allowedOrigins) {
+  const origin = header(req, "origin");
+  if (origin && allowedOrigins.includes(origin)) {
+    res.setHeader("Access-Control-Allow-Origin", origin);
+    res.setHeader("Vary", "Origin");
+    res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type");
+    res.setHeader("Access-Control-Max-Age", "600");
+  }
+  if (req.method === "OPTIONS") {
+    res.status(204).end();
+    return true;
+  }
+  return false;
+}
+async function requireStudioUser(req, res, sanityProjectId) {
+  const result = await verifyStudioRequest(req, sanityProjectId);
+  if (result.ok) return result.user;
+  console.error(`Visitor insights: rejected unauthenticated request (${result.reason}) on ${req.url ?? "unknown"}`);
+  res.status(401).json({ error: "Not authorised. Sign in to the Studio and try again." });
+  return null;
+}
+
+// src/server/googleAuth.ts
+var import_node_crypto = require("crypto");
+var ANALYTICS_READONLY_SCOPE = "https://www.googleapis.com/auth/analytics.readonly";
+var TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+var ASSERTION_TTL_SECONDS = 3600;
+var REFRESH_MARGIN_SECONDS = 60;
+var tokenCache = /* @__PURE__ */ new Map();
+function base64url(input) {
+  return Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function parseServiceAccountKey(raw) {
+  if (!raw) return null;
+  let text = raw.trim();
+  if (!text.startsWith("{")) {
+    try {
+      text = Buffer.from(text, "base64").toString("utf8");
+    } catch {
+      return null;
+    }
+  }
+  try {
+    const parsed = JSON.parse(text);
+    if (!parsed.client_email || !parsed.private_key) return null;
+    return {
+      client_email: parsed.client_email,
+      // Escaped newlines survive most env-var round trips; real newlines do not always.
+      private_key: parsed.private_key.replace(/\\n/g, "\n")
+    };
+  } catch {
+    return null;
+  }
+}
+async function getAccessToken(key) {
+  const now = Math.floor(Date.now() / 1e3);
+  const cached = tokenCache.get(key.client_email);
+  if (cached && cached.expiresAt - REFRESH_MARGIN_SECONDS > now) {
+    return cached.token;
+  }
+  const header2 = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const claims = base64url(
+    JSON.stringify({
+      iss: key.client_email,
+      scope: ANALYTICS_READONLY_SCOPE,
+      aud: TOKEN_ENDPOINT,
+      exp: now + ASSERTION_TTL_SECONDS,
+      iat: now
+    })
+  );
+  const signer = (0, import_node_crypto.createSign)("RSA-SHA256");
+  signer.update(`${header2}.${claims}`);
+  const signature = base64url(signer.sign(key.private_key));
+  const assertion = `${header2}.${claims}.${signature}`;
+  const response = await fetch(TOKEN_ENDPOINT, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+      assertion
+    })
+  });
+  if (!response.ok) {
+    throw new Error(`Google token exchange failed with ${response.status}`);
+  }
+  const body = await response.json();
+  if (!body.access_token) throw new Error("Google token exchange returned no access token");
+  tokenCache.set(key.client_email, {
+    token: body.access_token,
+    expiresAt: now + (body.expires_in ?? ASSERTION_TTL_SECONDS)
+  });
+  return body.access_token;
+}
+
+// src/server/ga4.ts
+var DATA_API_BASE = "https://analyticsdata.googleapis.com/v1beta";
+function toMetricNumber(raw) {
+  if (raw === void 0 || raw === "") return Number.NaN;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : Number.NaN;
+}
+function parseReport(raw) {
+  const rows = (raw.rows ?? []).map((row) => ({
+    dimensions: (row.dimensionValues ?? []).map((d) => d.value ?? ""),
+    metrics: (row.metricValues ?? []).map((m) => toMetricNumber(m.value))
+  }));
+  return {
+    rows,
+    thresholded: raw.metadata?.subjectToThresholding === true,
+    sampled: Array.isArray(raw.metadata?.samplingMetadatas) && raw.metadata.samplingMetadatas.length > 0,
+    rowCount: raw.rowCount ?? rows.length
+  };
+}
+function createGa4Client(propertyId, key) {
+  async function post(path, body) {
+    const token = await getAccessToken(key);
+    const response = await fetch(`${DATA_API_BASE}/properties/${propertyId}:${path}`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      throw new Error(`GA4 ${path} failed with ${response.status}`);
+    }
+    return await response.json();
+  }
+  return {
+    async runReport(request) {
+      const raw = await post("runReport", request);
+      return parseReport(raw);
+    },
+    /**
+     * Run several reports in one call. Preferred over parallel runReport calls: it is one
+     * quota-charged request and one round trip rather than N of each.
+     */
+    async batchRunReports(requests) {
+      if (requests.length === 0) return [];
+      const raw = await post("batchRunReports", { requests });
+      return (raw.reports ?? []).map(parseReport);
+    }
+  };
+}
+function eventNameFilter(eventName) {
+  return {
+    filter: {
+      fieldName: "eventName",
+      stringFilter: { matchType: "EXACT", value: eventName }
+    }
+  };
+}
+function sumFirstMetric(report) {
+  return report.rows.reduce((total, row) => {
+    const value = row.metrics[0];
+    return value !== void 0 && Number.isFinite(value) ? total + value : total;
+  }, 0);
+}
+
+// src/server/vercel.ts
+var API_BASE = "https://api.vercel.com";
+function createVercelClient(projectId, token, teamId) {
+  return {
+    async pageviews(start, end) {
+      const params = new URLSearchParams({
+        projectId,
+        since: `${start}T00:00:00.000Z`,
+        until: `${end}T23:59:59.999Z`
+      });
+      if (teamId) params.set("teamId", teamId);
+      const response = await fetch(`${API_BASE}/v1/web-analytics/timeseries?${params.toString()}`, {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (!response.ok) {
+        throw new Error(`Vercel Web Analytics failed with ${response.status}`);
+      }
+      const body = await response.json();
+      const byDate = {};
+      let total = 0;
+      for (const point of body.data ?? []) {
+        if (!point.key) continue;
+        const date = point.key.slice(0, 10);
+        const count = typeof point.total === "number" ? point.total : 0;
+        byDate[date] = (byDate[date] ?? 0) + count;
+        total += count;
+      }
+      return { byDate, total };
+    }
+  };
+}
+
+// src/server/cache.ts
+var DEFAULT_TTL_MS = 5 * 60 * 1e3;
+var MAX_ENTRIES = 200;
+var store = /* @__PURE__ */ new Map();
+function cacheKey(parts) {
+  return parts.map((p) => String(p ?? "")).join("|");
+}
+function getCached(key) {
+  const entry = store.get(key);
+  if (!entry) return void 0;
+  if (entry.expiresAt <= Date.now()) {
+    store.delete(key);
+    return void 0;
+  }
+  return entry.value;
+}
+function setCached(key, value, ttlMs = DEFAULT_TTL_MS) {
+  if (store.size >= MAX_ENTRIES && !store.has(key)) {
+    const oldest = store.keys().next().value;
+    if (oldest !== void 0) store.delete(oldest);
+  }
+  store.set(key, { value, expiresAt: Date.now() + ttlMs });
+}
+async function withCache(key, ttlMs, compute) {
+  const hit = getCached(key);
+  if (hit !== void 0) return hit;
+  const value = await compute();
+  setCached(key, value, ttlMs);
+  return value;
+}
+function clearCache() {
+  store.clear();
+}
+
+// src/server/orders.ts
+var SAFE_ORDER_PROJECTION = "{ _createdAt, orderStatus }";
+function orderFilter(documentType, excludeFilter) {
+  const clauses = [
+    `_type == $documentType`,
+    `_createdAt >= $start`,
+    `_createdAt <= $end`
+  ];
+  if (excludeFilter) clauses.push(`(${excludeFilter})`);
+  return clauses.join(" && ");
+}
+async function countOrders(client, documentType, start, end, excludeFilter) {
+  const query = `*[${orderFilter(documentType, excludeFilter)}]${SAFE_ORDER_PROJECTION}`;
+  const orders = await client.fetch(query, {
+    documentType,
+    start: `${start}T00:00:00Z`,
+    end: `${end}T23:59:59Z`
+  });
+  const byDate = {};
+  for (const order of orders) {
+    const date = order._createdAt.slice(0, 10);
+    byDate[date] = (byDate[date] ?? 0) + 1;
+  }
+  return { byDate, total: orders.length };
+}
+async function countOrdersByTypeface(client, documentType, typefacesField, start, end, excludeFilter) {
+  if (!typefacesField) return null;
+  const query = `*[${orderFilter(documentType, excludeFilter)}]{
+		"typefaces": ${typefacesField}[]->{ title }
+	}`;
+  const orders = await client.fetch(query, {
+    documentType,
+    start: `${start}T00:00:00Z`,
+    end: `${end}T23:59:59Z`
+  });
+  const byTypeface = {};
+  let total = 0;
+  for (const order of orders) {
+    for (const typeface of order.typefaces ?? []) {
+      const title = typeface?.title;
+      if (!title) continue;
+      byTypeface[title] = (byTypeface[title] ?? 0) + 1;
+      total += 1;
+    }
+  }
+  return { byTypeface, total };
+}
+
+// src/server/reports/measurementHealth.ts
+var CONSENT_EVENT = "consent_granted";
+function interpret(ga4Views, vercelViews, shortfall, consent) {
+  if (ga4Views.status === "unavailable" && vercelViews.status === "unavailable") {
+    return "Neither source answered, so nothing can be said about coverage for this range.";
+  }
+  if (shortfall === null) {
+    return "Only one pageview source answered, so the two cannot be compared for this range.";
+  }
+  const percent = Math.round(Math.abs(shortfall) * 100);
+  if (Math.abs(shortfall) < 0.05) {
+    return `GA4 and Vercel agree to within ${percent}% on pageviews. Nothing here suggests a measurement problem.`;
+  }
+  const direction = shortfall > 0 ? "fewer" : "more";
+  const base = `GA4 recorded ${percent}% ${direction} pageviews than Vercel.`;
+  if (consent.status === "unavailable") {
+    return `${base} How much of that is consent refusal cannot be measured until the consent_granted event is instrumented, so the difference is currently unexplained rather than attributed.`;
+  }
+  const consentPercent = Math.round((1 - consent.value / 100) * 100);
+  return `${base} Around ${consentPercent}% of sessions did not grant analytics consent, which accounts for part of it. The remainder is unexplained \u2014 ad-blocking and bot filtering are plausible but are not separately measurable.`;
+}
+async function measurementHealth(input) {
+  const { config, range, ga4, vercel, sanity } = input;
+  let ga4Pageviews = unavailable("source_error", "GA4 not configured");
+  let ga4Sessions = unavailable("source_error", "GA4 not configured");
+  let consentRate = unavailable("not_instrumented");
+  if (ga4) {
+    try {
+      const [views, sessions, consent] = await ga4.batchRunReports([
+        {
+          metrics: [{ name: "screenPageViews" }],
+          dateRanges: [{ startDate: range.start, endDate: range.end }]
+        },
+        {
+          metrics: [{ name: "sessions" }],
+          dateRanges: [{ startDate: range.start, endDate: range.end }]
+        },
+        {
+          metrics: [{ name: "eventCount" }],
+          dimensions: [{ name: "eventName" }],
+          dateRanges: [{ startDate: range.start, endDate: range.end }],
+          dimensionFilter: {
+            filter: {
+              fieldName: "eventName",
+              stringFilter: { matchType: "EXACT", value: CONSENT_EVENT }
+            }
+          }
+        }
+      ]);
+      if (views) ga4Pageviews = ok(sumFirstMetric(views));
+      if (sessions) ga4Sessions = ok(sumFirstMetric(sessions));
+      const consentCoverage = coverageForRange(config.eventCutovers, CONSENT_EVENT, range);
+      if (consentCoverage.status === "full" && consent && ga4Sessions.status === "ok" && ga4Sessions.value > 0) {
+        const rate = Math.min(100, sumFirstMetric(consent) / ga4Sessions.value * 100);
+        consentRate = ok(Math.round(rate * 10) / 10);
+      } else if (consentCoverage.status === "partial") {
+        consentRate = unavailable("before_cutover", `Instrumented from ${consentCoverage.cutover}`);
+      }
+    } catch (e) {
+      console.error("Visitor insights: GA4 measurement-health query failed:", e.message);
+      ga4Pageviews = unavailable("source_error");
+      ga4Sessions = unavailable("source_error");
+    }
+  }
+  let vercelPageviews = unavailable("source_error", "Vercel not configured");
+  if (vercel) {
+    try {
+      const result = await vercel.pageviews(range.start, range.end);
+      vercelPageviews = ok(result.total);
+    } catch (e) {
+      console.error("Visitor insights: Vercel query failed:", e.message);
+      vercelPageviews = unavailable("source_error");
+    }
+  }
+  let orders = unavailable("source_error", "Sanity not configured");
+  if (sanity) {
+    try {
+      const counts = await countOrders(
+        sanity,
+        config.orders.documentType,
+        range.start,
+        range.end,
+        config.orders.excludeFilter
+      );
+      orders = ok(counts.total);
+    } catch (e) {
+      console.error("Visitor insights: order count failed:", e.message);
+      orders = unavailable("source_error");
+    }
+  }
+  const shortfallRatio = ga4Pageviews.status !== "unavailable" && vercelPageviews.status !== "unavailable" && vercelPageviews.value > 0 ? (vercelPageviews.value - ga4Pageviews.value) / vercelPageviews.value : null;
+  return {
+    ga4Pageviews,
+    vercelPageviews,
+    shortfallRatio,
+    ga4Sessions,
+    orders,
+    consentRate,
+    interpretation: interpret(ga4Pageviews, vercelPageviews, shortfallRatio, consentRate)
+  };
+}
+
+// src/server/reports/acquisition.ts
+var DESIGN_INDUSTRY_SOURCES = [
+  "fontsinuse.com",
+  "typewolf.com",
+  "typographica.org",
+  "fonts.google.com",
+  "behance.net",
+  "dribbble.com",
+  "itsnicethat.com"
+];
+function isUnattributed(source) {
+  const normalised = source.toLowerCase();
+  return normalised === "(not set)" || normalised === "(direct)" || normalised === "(none)" || normalised === "";
+}
+function isDesignIndustry(source) {
+  const normalised = source.toLowerCase();
+  return DESIGN_INDUSTRY_SOURCES.some((known) => normalised === known || normalised.endsWith(`.${known}`));
+}
+async function acquisition(ga4, range, limit = 25) {
+  const report = await ga4.runReport({
+    dimensions: [{ name: "sessionSource" }, { name: "sessionDefaultChannelGroup" }],
+    metrics: [{ name: "sessions" }],
+    dateRanges: [{ startDate: range.start, endDate: range.end }],
+    orderBys: [{ metric: { metricName: "sessions" }, desc: true }],
+    limit
+  });
+  const rows = report.rows.map((row) => {
+    const source = row.dimensions[0] ?? "(not set)";
+    const sessions = row.metrics[0];
+    return {
+      source,
+      channel: row.dimensions[1] ?? "Unassigned",
+      sessions: Number.isFinite(sessions) ? sessions : 0,
+      designIndustry: isDesignIndustry(source),
+      unattributed: isUnattributed(source)
+    };
+  });
+  const totalSessions = sumFirstMetric(report);
+  const sumWhere = (predicate) => rows.filter(predicate).reduce((total, row) => total + row.sessions, 0);
+  return {
+    rows,
+    totalSessions,
+    designIndustryShare: totalSessions > 0 ? sumWhere((r) => r.designIndustry) / totalSessions : null,
+    unattributedShare: totalSessions > 0 ? sumWhere((r) => r.unattributed) / totalSessions : null,
+    rowsWithheld: report.thresholded
+  };
+}
+
+// src/server/reports/journey.ts
+var JOURNEY_STEPS = [
+  { key: "landed", label: "Landed", event: "page_view" },
+  { key: "viewed_typeface", label: "Viewed a typeface", event: "view_item" },
+  { key: "tested", label: "Used the type tester", event: "tester_engaged" },
+  { key: "added_to_cart", label: "Added to cart", event: "add_to_cart" },
+  { key: "began_checkout", label: "Began checkout", event: "begin_checkout" },
+  { key: "purchased", label: "Purchased", event: "purchase" }
+];
+var APPROXIMATION_NOTE = "These are independent per-step totals, not tracked journeys. GA4 cannot report the actual path a visitor took, so a visitor counted at one step is not necessarily the same visitor counted at the next.";
+async function journey(config, ga4, range) {
+  const coverages = JOURNEY_STEPS.map((step) => ({
+    step,
+    coverage: coverageForRange(config.eventCutovers, step.event, range)
+  }));
+  const queryable = coverages.filter((entry) => entry.coverage.status !== "none");
+  const reports = await ga4.batchRunReports(
+    queryable.map((entry) => ({
+      metrics: [{ name: "eventCount" }],
+      dateRanges: [{ startDate: range.start, endDate: range.end }],
+      dimensionFilter: eventNameFilter(entry.step.event)
+    }))
+  );
+  const countsByEvent = /* @__PURE__ */ new Map();
+  queryable.forEach((entry, index) => {
+    const report = reports[index];
+    if (report) countsByEvent.set(entry.step.event, sumFirstMetric(report));
+  });
+  const steps = [];
+  let previousMeasurable = null;
+  for (const { step, coverage } of coverages) {
+    const raw = countsByEvent.has(step.event) ? countsByEvent.get(step.event) : null;
+    const count = applyCoverage(raw, coverage);
+    const current = count.status === "unavailable" ? null : count.value;
+    const conversionFromPrevious = previousMeasurable !== null && current !== null && previousMeasurable > 0 ? current / previousMeasurable : null;
+    steps.push({ key: step.key, label: step.label, event: step.event, count, conversionFromPrevious });
+    if (current !== null) previousMeasurable = current;
+  }
+  let topExitPages = [];
+  try {
+    const exits = await ga4.runReport({
+      dimensions: [{ name: "pagePath" }],
+      metrics: [{ name: "exits" }],
+      dateRanges: [{ startDate: range.start, endDate: range.end }],
+      orderBys: [{ metric: { metricName: "exits" }, desc: true }],
+      limit: 10
+    });
+    topExitPages = exits.rows.map((row) => ({
+      path: row.dimensions[0] ?? "(unknown)",
+      exits: Number.isFinite(row.metrics[0]) ? row.metrics[0] : 0
+    }));
+  } catch (e) {
+    console.error("Visitor insights: exit-page query failed:", e.message);
+  }
+  return { steps, topExitPages, approximate: true, approximationNote: APPROXIMATION_NOTE };
+}
+
+// src/server/reports/typefaceInterest.ts
+var VIEW_EVENT = "view_item";
+var TEST_EVENT = "tester_engaged";
+var INTERPRETATION_NOTE = "Aggregate interest per family, not individual journeys. The person who tests a typeface is often not the person who buys it, and may buy months later \u2014 so a low tested-to-bought ratio is not necessarily a conversion problem.";
+async function countsByItem(config, ga4, range, eventName) {
+  if (coverageForRange(config.eventCutovers, eventName, range).status === "none") return null;
+  const report = await ga4.runReport({
+    dimensions: [{ name: "itemName" }],
+    metrics: [{ name: "eventCount" }],
+    dateRanges: [{ startDate: range.start, endDate: range.end }],
+    dimensionFilter: eventNameFilter(eventName),
+    orderBys: [{ metric: { metricName: "eventCount" }, desc: true }],
+    limit: 100
+  });
+  const counts = /* @__PURE__ */ new Map();
+  for (const row of report.rows) {
+    const name = row.dimensions[0];
+    const value = row.metrics[0];
+    if (name && Number.isFinite(value)) counts.set(name, value);
+  }
+  return counts;
+}
+async function typefaceInterest(input) {
+  const { config, range, ga4, sanity } = input;
+  const [viewed, tested] = await Promise.all([
+    countsByItem(config, ga4, range, VIEW_EVENT),
+    countsByItem(config, ga4, range, TEST_EVENT)
+  ]);
+  let bought = null;
+  if (sanity) {
+    try {
+      const counts = await countOrdersByTypeface(
+        sanity,
+        config.orders.documentType,
+        config.orders.typefacesField,
+        range.start,
+        range.end,
+        config.orders.excludeFilter
+      );
+      if (counts) bought = new Map(Object.entries(counts.byTypeface));
+    } catch (e) {
+      console.error("Visitor insights: per-typeface order count failed:", e.message);
+    }
+  }
+  const families = /* @__PURE__ */ new Set([
+    ...viewed?.keys() ?? [],
+    ...tested?.keys() ?? [],
+    ...bought?.keys() ?? []
+  ]);
+  const metric = (counts, family, missingReason) => counts === null ? unavailable(missingReason) : ok(counts.get(family) ?? 0);
+  const rows = [...families].map((family) => {
+    const viewedMetric = metric(viewed, family, "not_instrumented");
+    const testedMetric = metric(tested, family, "not_instrumented");
+    const boughtMetric = bought === null ? unavailable("not_applicable", "Orders do not resolve to typefaces on this site") : ok(bought.get(family) ?? 0);
+    const testRate = viewedMetric.status !== "unavailable" && testedMetric.status !== "unavailable" && viewedMetric.value > 0 ? testedMetric.value / viewedMetric.value : null;
+    return { typeface: family, viewed: viewedMetric, tested: testedMetric, bought: boughtMetric, testRate };
+  });
+  rows.sort((a, b) => {
+    const av = a.viewed.status === "unavailable" ? -1 : a.viewed.value;
+    const bv = b.viewed.status === "unavailable" ? -1 : b.viewed.value;
+    return bv - av;
+  });
+  return { rows, interpretationNote: INTERPRETATION_NOTE, rowsWithheld: false };
+}
+
+// src/server/createHandler.ts
+var ENV_VARS = {
+  /** Service-account JSON (raw or base64) with Viewer on the GA4 property. */
+  googleServiceAccount: "VISITOR_INSIGHTS_GA4_SERVICE_ACCOUNT",
+  /** Vercel API token with read access to the project. */
+  vercelToken: "VISITOR_INSIGHTS_VERCEL_TOKEN"
+};
+var RANGE_KEYS = ["week", "quarter", "year"];
+function param(req, name) {
+  const raw = req.query?.[name];
+  return Array.isArray(raw) ? raw[0] : raw;
+}
+function createVisitorInsightsHandler(options) {
+  assertValidSiteConfig(options.config);
+  const config = options.config;
+  const ttl = options.cacheTtlMs ?? DEFAULT_TTL_MS;
+  return async function handler(req, res) {
+    if (applyCors(req, res, config.allowedStudioOrigins ?? [])) return;
+    if (req.method !== "GET") {
+      res.status(405).json({ error: "Method not allowed" });
+      return;
+    }
+    const sanityProjectId = options.sanityProjectId ?? process.env.SANITY_STUDIO_PROJECT_ID ?? "";
+    const user = await requireStudioUser(req, res, sanityProjectId);
+    if (!user) return;
+    const reportName = param(req, "report");
+    if (!isReportName(reportName)) {
+      res.status(400).json({ error: "Unknown report" });
+      return;
+    }
+    const rangeKey = param(req, "range") ?? "week";
+    if (!RANGE_KEYS.includes(rangeKey)) {
+      res.status(400).json({ error: "Unknown range" });
+      return;
+    }
+    const timezone = config.ga4?.timezone ?? "UTC";
+    const range = resolveRange(rangeKey, timezone);
+    const sources = {};
+    const serviceAccount = parseServiceAccountKey(process.env[ENV_VARS.googleServiceAccount]);
+    let ga4 = null;
+    if (!config.ga4) {
+      sources.ga4 = { status: "unconfigured" };
+    } else if (!serviceAccount) {
+      sources.ga4 = { status: "error", message: "Service account missing or unparseable" };
+    } else {
+      ga4 = createGa4Client(config.ga4.propertyId, serviceAccount);
+      sources.ga4 = { status: "ok" };
+    }
+    const vercelToken = process.env[ENV_VARS.vercelToken];
+    let vercel = null;
+    if (!config.vercel) {
+      sources.vercel = { status: "unconfigured" };
+    } else if (!vercelToken) {
+      sources.vercel = { status: "error", message: "Vercel token missing" };
+    } else {
+      vercel = createVercelClient(config.vercel.projectId, vercelToken, config.vercel.teamId);
+      sources.vercel = { status: "ok" };
+    }
+    const sanity = options.sanityClient ?? null;
+    sources.sanity = sanity ? { status: "ok" } : { status: "unconfigured" };
+    try {
+      const key = cacheKey(["vi", config.siteId, reportName, range.key, range.start, range.end]);
+      const envelope = await withCache(key, ttl, async () => {
+        const notices = [];
+        const provisional = provisionalNotice(range);
+        if (provisional) notices.push(provisional);
+        const data = await runReport(reportName, { config, range, ga4, vercel, sanity, notices });
+        return { report: reportName, range, sources, notices, data };
+      });
+      res.status(200).json(envelope);
+    } catch (e) {
+      console.error(`Visitor insights: report "${reportName}" failed:`, e.message);
+      res.status(502).json({ error: "Report failed", report: reportName });
+    }
+  };
+}
+async function runReport(report, ctx) {
+  const { config, range, ga4, vercel, sanity, notices } = ctx;
+  switch (report) {
+    case "measurement-health":
+      return measurementHealth({ config, range, ga4, vercel, sanity });
+    case "acquisition":
+      if (!ga4) throw new Error("GA4 is required for the acquisition report");
+      return acquisition(ga4, range);
+    case "journey": {
+      if (!ga4) throw new Error("GA4 is required for the journey report");
+      notices.push(...coverageNotices(config.eventCutovers, JOURNEY_STEPS.map((s) => s.event), range));
+      return journey(config, ga4, range);
+    }
+    case "typeface-interest":
+      if (!ga4) throw new Error("GA4 is required for the typeface-interest report");
+      return typefaceInterest({ config, range, ga4, sanity });
+    default:
+      throw new Error(`Unhandled report: ${report}`);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DESIGN_INDUSTRY_SOURCES,
+  ENV_VARS,
+  GA4_PROCESSING_LAG_DAYS,
+  JOURNEY_STEPS,
+  PREEXISTING,
+  REPORT_NAMES,
+  applyCors,
+  applyCoverage,
+  assertValidSiteConfig,
+  clearCache,
+  coverageForRange,
+  coverageNotices,
+  createVisitorInsightsHandler,
+  daysBetween,
+  formatInTimeZone,
+  isReportName,
+  isValidTimeZone,
+  ok,
+  partial,
+  previousRange,
+  provisionalDates,
+  provisionalNotice,
+  requireStudioUser,
+  resolveRange,
+  shiftDays,
+  unavailable,
+  validateSiteConfig,
+  valueOrNull,
+  verifyStudioRequest
+});
+//# sourceMappingURL=server.js.map