@orion-studios/cms 0.5.8 → 0.5.10

package/dist/analytics/react.js

@@ -171,6 +171,10 @@ function Analytics({
         const value = params.get(`utm_${key}`);
         if (value) utm[key] = value;
       }
+      if (params.has("gclid") && !utm.source) {
+        utm.source = "google";
+        utm.medium = "cpc";
+      }
       if (Object.keys(utm).length > 0) event.utm = utm;
     }
     track(event);

package/dist/server/index.d.ts

@@ -77,6 +77,8 @@ type CmsRoutesOptions = {
     projectRef?: string;
     /** Purpose-specific secret for analytics visitor and session hashing. */
     analyticsSecret?: string;
+    /** IANA timezone used for analytics dates and hourly buckets. Defaults to UTC. */
+    analyticsTimeZone?: string;
     /** Purpose-specific secret for auto-reply recipient hashing. */
     autoReplyHashSecret?: string;
     /** Cloudflare Turnstile secret — when set, public submits must include a valid `_turnstileToken`. */
@@ -204,6 +206,7 @@ type StoredEvent = {
 };
 /** Minimal authoritative form record used by aggregate analytics. */
 type StoredFormSubmission = {
+    id?: number | string;
     form: string;
     session_key: string;
     created_at: string;
@@ -221,8 +224,11 @@ type AnalyticsKpis = {
     portalClicks: number;
     conversions: number;
     conversionRate: number;
+    attributedSubmits: number;
+    unattributedSubmits: number;
 };
 type AnalyticsSummary = {
+    timeZone: string;
     range: {
         from: string;
         to: string;
@@ -273,7 +279,7 @@ type AnalyticsSummary = {
 declare function aggregateAnalytics(events: StoredEvent[], previousEvents: StoredEvent[], range: {
     from: string;
     to: string;
-}, submissions?: StoredFormSubmission[], previousSubmissions?: StoredFormSubmission[]): AnalyticsSummary;
+}, submissions?: StoredFormSubmission[], previousSubmissions?: StoredFormSubmission[], timeZone?: string): AnalyticsSummary;
 
 /**
  * Server-side analytics ingest: validation, bot filtering, and the
@@ -307,7 +313,7 @@ type AnalyticsEventRow = {
  * Daily-rotating visitor hash: same visitor+day → same key, next day → a new
  * unrelated key. Orders one visit into a path; can't track anyone over time.
  */
-declare function sessionKeyFor(ip: string, userAgent: string, secret: string, now?: Date): string;
+declare function sessionKeyFor(ip: string, userAgent: string, secret: string, now?: Date, timeZone?: string): string;
 /** One-way server hash for a consented first-party visitor cookie. */
 declare function visitorKeyFor(visitorId: unknown, secret: string): string;
 /** True when the request looks like an automated client, not a visitor. */

package/dist/server/index.js

@@ -1,3 +1,6 @@
+import {
+  CONTENT_CACHE_TAG
+} from "../chunk-NSAZCP4I.js";
 import {
   createMemoryRateLimitStore,
   getAutoReplyEmailFields,
@@ -5,30 +8,162 @@ import {
   processSubmission,
   resolveAutoReplyEmailField
 } from "../chunk-CFZP7674.js";
-import {
-  CONTENT_CACHE_TAG
-} from "../chunk-NSAZCP4I.js";
 
 // src/server/routes.ts
 import { createHash as createHash3, createHmac as createHmac3, randomUUID, timingSafeEqual as timingSafeEqual2 } from "crypto";
 
+// src/analytics/time.ts
+var datePartsFormatter = (timeZone) => new Intl.DateTimeFormat("en-US", {
+  timeZone,
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+  hour: "2-digit",
+  minute: "2-digit",
+  second: "2-digit",
+  hourCycle: "h23"
+});
+function isValidTimeZone(timeZone) {
+  try {
+    datePartsFormatter(timeZone).format(/* @__PURE__ */ new Date(0));
+    return true;
+  } catch {
+    return false;
+  }
+}
+function normalizeTimeZone(timeZone) {
+  const value = timeZone?.trim() || "UTC";
+  if (!isValidTimeZone(value)) {
+    throw new Error(`Invalid analytics time zone: ${value}. Use an IANA name such as America/Chicago.`);
+  }
+  return value;
+}
+function localParts(date, timeZone) {
+  const values = new Map(
+    datePartsFormatter(timeZone).formatToParts(date).filter((part) => part.type !== "literal").map((part) => [part.type, Number(part.value)])
+  );
+  return {
+    year: values.get("year") || 0,
+    month: values.get("month") || 0,
+    day: values.get("day") || 0,
+    hour: values.get("hour") || 0,
+    minute: values.get("minute") || 0,
+    second: values.get("second") || 0,
+    millisecond: date.getUTCMilliseconds()
+  };
+}
+function dateKey(parts) {
+  return `${String(parts.year).padStart(4, "0")}-${String(parts.month).padStart(2, "0")}-${String(parts.day).padStart(2, "0")}`;
+}
+function dateKeyInTimeZone(value, timeZone) {
+  const date = value instanceof Date ? value : new Date(value);
+  return dateKey(localParts(date, timeZone));
+}
+function hourInTimeZone(value, timeZone) {
+  const date = value instanceof Date ? value : new Date(value);
+  return localParts(date, timeZone).hour;
+}
+function addDays(key, days) {
+  const [year, month, day] = key.split("-").map(Number);
+  const date = new Date(Date.UTC(year, month - 1, day + days));
+  return date.toISOString().slice(0, 10);
+}
+function localDateTimeUtc(parts, timeZone) {
+  const desired = Date.UTC(
+    parts.year,
+    parts.month - 1,
+    parts.day,
+    parts.hour,
+    parts.minute,
+    parts.second,
+    parts.millisecond
+  );
+  let instant = desired;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const observed = localParts(new Date(instant), timeZone);
+    const observedAsUtc = Date.UTC(
+      observed.year,
+      observed.month - 1,
+      observed.day,
+      observed.hour,
+      observed.minute,
+      observed.second,
+      observed.millisecond
+    );
+    instant += desired - observedAsUtc;
+  }
+  return new Date(instant);
+}
+function localMidnightUtc(key, timeZone) {
+  const [year, month, day] = key.split("-").map(Number);
+  return localDateTimeUtc({ year, month, day, hour: 0, minute: 0, second: 0, millisecond: 0 }, timeZone);
+}
+function shiftLocalDays(date, days, timeZone) {
+  const current = localParts(date, timeZone);
+  const shifted = new Date(Date.UTC(
+    current.year,
+    current.month - 1,
+    current.day + days,
+    current.hour,
+    current.minute,
+    current.second,
+    current.millisecond
+  ));
+  return localDateTimeUtc({
+    year: shifted.getUTCFullYear(),
+    month: shifted.getUTCMonth() + 1,
+    day: shifted.getUTCDate(),
+    hour: shifted.getUTCHours(),
+    minute: shifted.getUTCMinutes(),
+    second: shifted.getUTCSeconds(),
+    millisecond: shifted.getUTCMilliseconds()
+  }, timeZone);
+}
+function calendarRange(days, timeZone, now = /* @__PURE__ */ new Date()) {
+  if (!Number.isInteger(days) || days < 1 || days > 370) {
+    throw new Error("Analytics days must be an integer from 1 through 370.");
+  }
+  const today = dateKeyInTimeZone(now, timeZone);
+  const fromKey = addDays(today, -(days - 1));
+  const previousFromKey = addDays(fromKey, -days);
+  const fromDate = localMidnightUtc(fromKey, timeZone);
+  return {
+    from: fromDate.toISOString(),
+    to: now.toISOString(),
+    previousFrom: localMidnightUtc(previousFromKey, timeZone).toISOString(),
+    previousTo: shiftLocalDays(now, -days, timeZone).toISOString()
+  };
+}
+function dateKeysInRange(from, to, timeZone) {
+  const first = dateKeyInTimeZone(from, timeZone);
+  const last = dateKeyInTimeZone(to, timeZone);
+  const keys = [];
+  for (let key = first; key <= last && keys.length <= 370; key = addDays(key, 1)) keys.push(key);
+  return keys;
+}
+
 // src/analytics/aggregate.ts
 var CONVERSION_NAMES = /* @__PURE__ */ new Set(["call", "email"]);
-function normalizeSource(utmSource, referrer) {
+function normalizeSource(utmSource, referrer, utmMedium = "") {
   const tag = utmSource.trim().toLowerCase();
+  const medium = utmMedium.trim().toLowerCase();
   if (tag) {
     if (["gbp", "gmb", "google-business", "google_business", "business.google.com"].includes(tag)) {
       return "Google Business Profile";
     }
-    if (tag === "google") return "Google";
+    if (tag === "google") {
+      if (["cpc", "ppc", "paid", "paidsearch", "paid-search"].includes(medium)) return "Google Ads";
+      if (medium === "organic") return "Google search";
+      return "Google (unclassified)";
+    }
     if (tag === "facebook" || tag === "fb") return "Facebook";
     if (tag === "instagram" || tag === "ig") return "Instagram";
     return utmSource.trim();
   }
   const host = referrer.trim().toLowerCase();
-  if (!host) return "direct";
+  if (!host) return "No referrer / direct";
   if (host === "business.google.com") return "Google Business Profile";
-  if (host.includes("google.")) return "Google search";
+  if (host.includes("google.")) return "Google (unclassified)";
   if (host.includes("bing.")) return "Bing";
   if (host.includes("duckduckgo.")) return "DuckDuckGo";
   if (host.includes("yahoo.")) return "Yahoo";
@@ -45,8 +180,6 @@ var isConversion = (event) => event.server_verified === true && (event.type ===
 var top = (map, limit, by) => [...map.entries()].sort((a, b) => by(b[1]) - by(a[1])).slice(0, limit);
 function computeKpis(events, submissions) {
   const sessions = /* @__PURE__ */ new Set();
-  const visitors = /* @__PURE__ */ new Set();
-  const visitorSessions = /* @__PURE__ */ new Map();
   const converting = /* @__PURE__ */ new Set();
   let pageviews = 0;
   let calls = 0;
@@ -55,13 +188,6 @@ function computeKpis(events, submissions) {
   let portalClicks = 0;
   for (const event of events) {
     if (event.session_key) sessions.add(event.session_key);
-    const identity = event.visitor_key || event.session_key;
-    if (identity) visitors.add(identity);
-    if (event.visitor_key && event.session_key) {
-      const keys = visitorSessions.get(event.visitor_key) || /* @__PURE__ */ new Set();
-      keys.add(event.session_key);
-      visitorSessions.set(event.visitor_key, keys);
-    }
     if (event.type === "pageview") pageviews += 1;
     if (event.type === "click" && event.name === "call") calls += 1;
     if (event.type === "click" && event.name === "email") emails += 1;
@@ -74,50 +200,107 @@ function computeKpis(events, submissions) {
       converting.add(submission.session_key);
     }
   }
+  const attributedSubmits = (submissions || []).filter(
+    (submission) => Boolean(submission.session_key && sessions.has(submission.session_key))
+  ).length;
   const conversions = events.filter(isConversion).length + (submissions?.length ?? 0);
-  const returningVisitors = [...visitorSessions.values()].filter((keys) => keys.size > 1).length;
+  const visitorMetrics = computeVisitorMetrics(events);
   return {
-    visitors: visitors.size,
-    identifiedVisitors: visitorSessions.size,
-    returningVisitors,
+    visitors: visitorMetrics.visitors,
+    identifiedVisitors: visitorMetrics.identifiedVisitors,
+    returningVisitors: visitorMetrics.returningVisitors,
     sessions: sessions.size,
     pageviews,
-    pagesPerVisitor: visitors.size > 0 ? pageviews / visitors.size : 0,
+    pagesPerVisitor: visitorMetrics.visitors > 0 ? pageviews / visitorMetrics.visitors : 0,
     calls,
     formSubmits: submissions?.length ?? formSubmits,
     emails,
     portalClicks,
     conversions,
-    conversionRate: sessions.size > 0 ? converting.size / sessions.size : 0
+    conversionRate: sessions.size > 0 ? converting.size / sessions.size : 0,
+    attributedSubmits,
+    unattributedSubmits: (submissions?.length ?? 0) - attributedSubmits
   };
 }
-function aggregateAnalytics(events, previousEvents, range, submissions, previousSubmissions) {
+function computeVisitorMetrics(events) {
+  const parents = /* @__PURE__ */ new Map();
+  const ensure = (node) => {
+    if (!parents.has(node)) parents.set(node, node);
+  };
+  const find = (node) => {
+    const parent = parents.get(node) || node;
+    if (parent === node) return node;
+    const root = find(parent);
+    parents.set(node, root);
+    return root;
+  };
+  const union = (left, right) => {
+    ensure(left);
+    ensure(right);
+    const leftRoot = find(left);
+    const rightRoot = find(right);
+    if (leftRoot !== rightRoot) parents.set(rightRoot, leftRoot);
+  };
+  const sessionNodes = /* @__PURE__ */ new Set();
+  const visitorNodes = /* @__PURE__ */ new Set();
+  for (const event of events) {
+    const sessionNode = event.session_key ? `session:${event.session_key}` : "";
+    const visitorNode = event.visitor_key ? `visitor:${event.visitor_key}` : "";
+    if (sessionNode) {
+      ensure(sessionNode);
+      sessionNodes.add(sessionNode);
+    }
+    if (visitorNode) {
+      ensure(visitorNode);
+      visitorNodes.add(visitorNode);
+    }
+    if (sessionNode && visitorNode) union(sessionNode, visitorNode);
+  }
+  const roots = new Set([...parents.keys()].map(find));
+  const identifiedRoots = new Set([...visitorNodes].map(find));
+  const sessionsPerRoot = /* @__PURE__ */ new Map();
+  for (const sessionNode of sessionNodes) {
+    const root = find(sessionNode);
+    sessionsPerRoot.set(root, (sessionsPerRoot.get(root) || 0) + 1);
+  }
+  const returningVisitors = [...identifiedRoots].filter(
+    (root) => (sessionsPerRoot.get(root) || 0) > 1
+  ).length;
+  return {
+    visitors: roots.size,
+    identifiedVisitors: identifiedRoots.size,
+    returningVisitors
+  };
+}
+function aggregateAnalytics(events, previousEvents, range, submissions, previousSubmissions, timeZone = "UTC") {
   const trafficEvents = submissions === void 0 ? events : events.filter((event) => !isFormSubmitEvent(event));
   const previousTrafficEvents = previousSubmissions === void 0 ? previousEvents : previousEvents.filter((event) => !isFormSubmitEvent(event));
   const kpis = computeKpis(trafficEvents, submissions);
   const previous = computeKpis(previousTrafficEvents, previousSubmissions);
   const byDay = /* @__PURE__ */ new Map();
-  const dayOf = (iso) => iso.slice(0, 10);
+  const summaryTimeZone = normalizeTimeZone(timeZone);
+  const dayOf = (iso) => dateKeyInTimeZone(iso, summaryTimeZone);
   for (const event of trafficEvents) {
     const day = dayOf(event.created_at);
-    const entry = byDay.get(day) || { visitors: /* @__PURE__ */ new Set(), conversions: 0 };
-    const identity = event.visitor_key || event.session_key;
-    if (identity) entry.visitors.add(identity);
+    const entry = byDay.get(day) || { events: [], conversions: 0 };
+    entry.events.push(event);
     if (isConversion(event)) entry.conversions += 1;
     byDay.set(day, entry);
   }
   for (const submission of submissions || []) {
     const day = dayOf(submission.created_at);
-    const entry = byDay.get(day) || { visitors: /* @__PURE__ */ new Set(), conversions: 0 };
+    const entry = byDay.get(day) || { events: [], conversions: 0 };
     entry.conversions += 1;
     byDay.set(day, entry);
   }
   const trend = [];
-  for (let cursor = /* @__PURE__ */ new Date(`${dayOf(range.from)}T00:00:00Z`); cursor.toISOString().slice(0, 10) <= dayOf(range.to); cursor.setUTCDate(cursor.getUTCDate() + 1)) {
-    const day = cursor.toISOString().slice(0, 10);
+  for (const day of dateKeysInRange(range.from, range.to, summaryTimeZone)) {
     const entry = byDay.get(day);
-    trend.push({ day, visitors: entry?.visitors.size ?? 0, conversions: entry?.conversions ?? 0 });
-    if (trend.length > 370) break;
+    trend.push({
+      day,
+      visitors: entry ? computeVisitorMetrics(entry.events).visitors : 0,
+      conversions: entry?.conversions ?? 0
+    });
   }
   const bySession = /* @__PURE__ */ new Map();
   for (const event of trafficEvents) {
@@ -158,7 +341,7 @@ function aggregateAnalytics(events, previousEvents, range, submissions, previous
   const sources = /* @__PURE__ */ new Map();
   for (const [sessionKey, list] of bySession.entries()) {
     const first = list.find((event) => event.type === "pageview");
-    const label = normalizeSource(first?.utm?.source || "", first?.referrer || "");
+    const label = normalizeSource(first?.utm?.source || "", first?.referrer || "", first?.utm?.medium || "");
     const entry = sources.get(label) || { sessions: 0, conversions: 0 };
     entry.sessions += 1;
     if (convertedSessionKeys.has(sessionKey)) entry.conversions += 1;
@@ -175,7 +358,7 @@ function aggregateAnalytics(events, previousEvents, range, submissions, previous
   const hours = new Array(24).fill(0);
   for (const event of trafficEvents) {
     if (event.type !== "pageview") continue;
-    const hour = new Date(event.created_at).getUTCHours();
+    const hour = hourInTimeZone(event.created_at, summaryTimeZone);
     if (Number.isFinite(hour)) hours[hour] += 1;
   }
   const pathCounts = /* @__PURE__ */ new Map();
@@ -194,27 +377,46 @@ function aggregateAnalytics(events, previousEvents, range, submissions, previous
     pathCounts.set(key, entry);
   }
   const forms = /* @__PURE__ */ new Map();
+  const formEvidence = (form, sessionKey) => {
+    const sessions = forms.get(form) || /* @__PURE__ */ new Map();
+    forms.set(form, sessions);
+    const evidence = sessions.get(sessionKey) || { viewed: false, start: false, submit: false };
+    sessions.set(sessionKey, evidence);
+    return evidence;
+  };
   for (const event of trafficEvents) {
     if (event.type !== "form") continue;
     const [slug, stage] = event.name.split(":");
     if (!slug || !stage) continue;
     if (stage !== "viewed" && stage !== "start" && stage !== "submit") continue;
-    const entry = forms.get(slug) || { views: 0, starts: 0, submits: 0 };
-    if (stage === "viewed") entry.views += 1;
-    if (stage === "start") entry.starts += 1;
-    if (stage === "submit" && event.server_verified === true) entry.submits += 1;
-    forms.set(slug, entry);
-  }
-  for (const submission of submissions || []) {
-    const entry = forms.get(submission.form) || { views: 0, starts: 0, submits: 0 };
-    entry.submits += 1;
-    forms.set(submission.form, entry);
+    const sessionKey = event.session_key || `event:${String(event.id ?? event.created_at)}`;
+    const evidence = formEvidence(slug, sessionKey);
+    if (stage === "viewed") evidence.viewed = true;
+    if (stage === "start") evidence.start = true;
+    if (stage === "submit" && event.server_verified === true) evidence.submit = true;
+  }
+  for (const [index, submission] of (submissions || []).entries()) {
+    const sessionKey = submission.session_key || `submission:${String(submission.id ?? index)}`;
+    formEvidence(submission.form, sessionKey).submit = true;
+  }
+  const formSummary = [];
+  for (const [form, sessions] of forms.entries()) {
+    let views = 0;
+    let starts = 0;
+    let submits = 0;
+    for (const evidence of sessions.values()) {
+      if (evidence.viewed || evidence.start || evidence.submit) views += 1;
+      if (evidence.start || evidence.submit) starts += 1;
+      if (evidence.submit) submits += 1;
+    }
+    formSummary.push({ form, views, starts, submits });
   }
   const notFound = /* @__PURE__ */ new Map();
   for (const event of trafficEvents) {
     if (event.type === "not_found") notFound.set(event.path, (notFound.get(event.path) || 0) + 1);
   }
   return {
+    timeZone: summaryTimeZone,
     range,
     kpis,
     previous,
@@ -228,7 +430,7 @@ function aggregateAnalytics(events, previousEvents, range, submissions, previous
       path: key.split(" \u2192 "),
       ...data
     })),
-    forms: [...forms.entries()].map(([form, data]) => ({ form, ...data })),
+    forms: formSummary,
     notFound: top(notFound, 20, (count) => count).map(([path, count]) => ({ path, count }))
   };
 }
@@ -239,8 +441,8 @@ var EVENT_TYPES = ["pageview", "click", "form", "not_found"];
 var MAX_EVENTS_PER_BATCH = 20;
 var MAX_TEXT = 300;
 var MAX_META_JSON = 1e3;
-function sessionKeyFor(ip, userAgent, secret, now = /* @__PURE__ */ new Date()) {
-  const day = now.toISOString().slice(0, 10);
+function sessionKeyFor(ip, userAgent, secret, now = /* @__PURE__ */ new Date(), timeZone = "UTC") {
+  const day = dateKeyInTimeZone(now, normalizeTimeZone(timeZone));
   return createHash("sha256").update(`${secret}|${day}|${ip}|${userAgent}`).digest("hex").slice(0, 24);
 }
 function visitorKeyFor(visitorId, secret) {
@@ -1200,6 +1402,7 @@ function createCmsRoutes(options) {
   };
   const previewProjectRef = options.projectRef || (options.memoryMode ? "memory" : "");
   const analyticsSecret = options.analyticsSecret || (options.memoryMode ? "orion-memory-analytics-secret" : "");
+  const analyticsTimeZone = normalizeTimeZone(options.analyticsTimeZone);
   const autoReplyHashSecret = options.autoReplyHashSecret || (options.memoryMode ? "orion-memory-auto-reply-secret" : "");
   const analyticsLimit = (max, windowMs, bucket) => options.memoryMode ? createMemoryRateLimitStore({ max, windowMs }) : createDurableRateLimitStore(db, { max, windowMs, bucket, failClosed: true });
   const autoReplyLimit = (max, windowMs, bucket) => options.memoryMode ? createMemoryRateLimitStore({ max, windowMs }) : createDurableRateLimitStore(db, { max, windowMs, bucket, failClosed: true });
@@ -1282,7 +1485,13 @@ function createCmsRoutes(options) {
   const analyticsRetentionDays = options.analyticsRetentionDays ?? 90;
   const requestSessionKey = (request) => {
     if (!analyticsSecret) return "";
-    return sessionKeyFor(clientKey(request), request.headers.get("user-agent") || "", analyticsSecret);
+    return sessionKeyFor(
+      clientKey(request),
+      request.headers.get("user-agent") || "",
+      analyticsSecret,
+      /* @__PURE__ */ new Date(),
+      analyticsTimeZone
+    );
   };
   const guard = async (request, action) => {
     if (hostedMemoryMode) return errors.unauthorized();
@@ -2261,10 +2470,12 @@ function createCmsRoutes(options) {
         }
       }
       try {
-        await db().from("cms_events").insert(
+        const { error } = await db().from("cms_events").insert(
           rows.map((row) => ({ ...row, server_verified: false }))
         );
+        if (error) console.error("CMS analytics ingest failed.");
       } catch {
+        console.error("CMS analytics ingest failed.");
       }
     }
     return json({ success: true });
@@ -2273,31 +2484,33 @@ function createCmsRoutes(options) {
     const all = [];
     let cursor = 0;
     for (let page = 0; page < 60; page += 1) {
-      const { data, error } = await db().from("cms_events").select("id, session_key, type, name, path, referrer, utm, device, region, city, meta, server_verified, created_at").gte("created_at", fromIso).lte("created_at", toIso).gt("id", cursor).order("id", { ascending: true }).limit(1e3);
-      if (error || !data || data.length === 0) break;
+      const { data, error } = await db().from("cms_events").select("id, session_key, visitor_key, type, name, path, referrer, utm, device, region, city, meta, server_verified, created_at").gte("created_at", fromIso).lte("created_at", toIso).gt("id", cursor).order("id", { ascending: true }).limit(1e3);
+      if (error) throw new Error("Analytics event read failed.");
+      if (!data || data.length === 0) return all;
       all.push(...data);
       cursor = Number(data[data.length - 1].id);
-      if (data.length < 1e3) break;
+      if (data.length < 1e3) return all;
     }
-    return all;
+    throw new Error("Analytics event read exceeded the supported row limit.");
   };
   const fetchFormSubmissions = async (fromIso, toIso) => {
     const all = [];
     let cursor = 0;
     for (let page = 0; page < 60; page += 1) {
       const { data, error } = await db().from("cms_form_submissions").select("id, form_id, session_key, created_at").gte("created_at", fromIso).lte("created_at", toIso).gt("id", cursor).order("id", { ascending: true }).limit(1e3);
-      if (error) return all.length === 0 ? null : all;
-      if (!data || data.length === 0) break;
+      if (error) throw new Error("Analytics submission read failed.");
+      if (!data || data.length === 0) return all;
       all.push(...data);
       cursor = Number(data[data.length - 1].id);
-      if (data.length < 1e3) break;
+      if (data.length < 1e3) return all;
     }
-    return all;
+    throw new Error("Analytics submission read exceeded the supported row limit.");
   };
   const fetchFormSlugs = async () => {
     const { data, error } = await db().from("cms_forms").select("id, slug").limit(1e3);
     const slugs = /* @__PURE__ */ new Map();
-    if (error || !data) return slugs;
+    if (error) throw new Error("Analytics form label read failed.");
+    if (!data) return slugs;
     for (const form of data) {
       const id = String(form.id || "");
       const slug = String(form.slug || "");
@@ -2309,32 +2522,60 @@ function createCmsRoutes(options) {
     const auth = await guard(request, "analytics.read");
     if (auth instanceof Response) return auth;
     const url = new URL(request.url);
-    const toMs = Date.parse(url.searchParams.get("to") || "") || Date.now();
-    const defaultFrom = toMs - 30 * 864e5;
-    const fromMs = Math.min(Date.parse(url.searchParams.get("from") || "") || defaultFrom, toMs);
-    const windowMs = Math.max(toMs - fromMs, 864e5);
-    const from = new Date(fromMs).toISOString();
-    const to = new Date(toMs).toISOString();
-    const previousFrom = new Date(fromMs - windowMs).toISOString();
-    const [events, previousEvents, submissionRows, formSlugs] = await Promise.all([
-      fetchEvents(from, to),
-      fetchEvents(previousFrom, from),
-      fetchFormSubmissions(previousFrom, to),
-      fetchFormSlugs()
-    ]);
-    const submissions = submissionRows?.map((submission) => ({
+    const requestedDays = Number(url.searchParams.get("days") || "");
+    let from;
+    let to;
+    let previousFrom;
+    let previousTo;
+    if (Number.isInteger(requestedDays) && requestedDays >= 1 && requestedDays <= 370) {
+      ({ from, to, previousFrom, previousTo } = calendarRange(requestedDays, analyticsTimeZone));
+    } else {
+      const toMs = Date.parse(url.searchParams.get("to") || "") || Date.now();
+      const defaultFrom = toMs - 30 * 864e5;
+      const fromMs2 = Math.min(Date.parse(url.searchParams.get("from") || "") || defaultFrom, toMs);
+      const windowMs = Math.max(toMs - fromMs2, 864e5);
+      from = new Date(fromMs2).toISOString();
+      to = new Date(toMs).toISOString();
+      previousFrom = new Date(fromMs2 - windowMs).toISOString();
+      previousTo = new Date(fromMs2 - 1).toISOString();
+    }
+    let events;
+    let previousEvents;
+    let submissionRows;
+    let formSlugs;
+    try {
+      [events, previousEvents, submissionRows, formSlugs] = await Promise.all([
+        fetchEvents(from, to),
+        fetchEvents(previousFrom, previousTo),
+        fetchFormSubmissions(previousFrom, to),
+        fetchFormSlugs()
+      ]);
+    } catch {
+      console.error("CMS analytics summary read failed.");
+      return json({ error: "Analytics data is temporarily unavailable. No partial totals were shown." }, 503);
+    }
+    const fromMs = Date.parse(from);
+    const submissions = submissionRows.map((submission) => ({
+      id: submission.id,
       form: formSlugs.get(String(submission.form_id)) || String(submission.form_id),
       session_key: String(submission.session_key || ""),
       created_at: String(submission.created_at)
     }));
-    const currentSubmissions = submissions?.filter(
+    const currentSubmissions = submissions.filter(
       (submission) => Date.parse(submission.created_at) >= fromMs
     );
-    const previousSubmissions = submissions?.filter(
-      (submission) => Date.parse(submission.created_at) < fromMs
+    const previousSubmissions = submissions.filter(
+      (submission) => Date.parse(submission.created_at) <= Date.parse(previousTo)
     );
     return json(
-      aggregateAnalytics(events, previousEvents, { from, to }, currentSubmissions, previousSubmissions)
+      aggregateAnalytics(
+        events,
+        previousEvents,
+        { from, to },
+        currentSubmissions,
+        previousSubmissions,
+        analyticsTimeZone
+      )
     );
   };
   const pruneEvents = async () => {

package/dist/studio/index.d.ts

@@ -164,8 +164,11 @@ type AnalyticsKpis = {
     portalClicks: number;
     conversions: number;
     conversionRate: number;
+    attributedSubmits: number;
+    unattributedSubmits: number;
 };
 type AnalyticsSummary = {
+    timeZone: string;
     range: {
         from: string;
         to: string;
@@ -514,6 +517,7 @@ declare function createStudioApi(options: {
     analytics: (params?: {
         from?: string;
         to?: string;
+        days?: number;
     }) => Promise<AnalyticsSummary>;
     listUsers: () => Promise<{
         users: StudioUser[];

package/dist/studio/index.js

@@ -8,7 +8,7 @@ import {
 import "../chunk-DPKXKG2S.js";
 
 // src/studio/Studio.tsx
-import { useCallback as useCallback5, useEffect as useEffect11, useMemo as useMemo5, useState as useState12 } from "react";
+import { useCallback as useCallback5, useEffect as useEffect11, useMemo as useMemo4, useState as useState12 } from "react";
 
 // src/studio/api.ts
 var StudioApiError = class extends Error {
@@ -122,6 +122,7 @@ function createStudioApi(options) {
     listActivity: () => call("GET", "/activity"),
     analytics: (params) => {
       const query = new URLSearchParams();
+      if (params?.days) query.set("days", String(params.days));
       if (params?.from) query.set("from", params.from);
       if (params?.to) query.set("to", params.to);
       const suffix = query.toString() ? `?${query.toString()}` : "";
@@ -383,7 +384,7 @@ function LoginView({ siteName, logoUrl }) {
 }
 
 // src/studio/views/AnalyticsView.tsx
-import { useEffect as useEffect2, useMemo as useMemo2, useState as useState3 } from "react";
+import { useEffect as useEffect2, useState as useState3 } from "react";
 import { Fragment, jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
 var RANGES = [
   { key: "7", label: "7 days", days: 7 },
@@ -460,7 +461,8 @@ function TrendChart({ trend }) {
 }
 function BarList({
   rows,
-  max
+  max,
+  emptyMessage = "Nothing recorded yet."
 }) {
   const top = max ?? Math.max(1, ...rows.map((row) => row.value));
   return /* @__PURE__ */ jsxs3("div", { className: "ost-barlist", children: [
@@ -475,7 +477,7 @@ function BarList({
         ] }) : null
       ] })
     ] }, row.label)),
-    rows.length === 0 ? /* @__PURE__ */ jsx3("p", { className: "ost-muted", children: "Nothing recorded yet." }) : null
+    rows.length === 0 ? /* @__PURE__ */ jsx3("p", { className: "ost-muted", children: emptyMessage }) : null
   ] });
 }
 function AnalyticsView({ api }) {
@@ -484,22 +486,22 @@ function AnalyticsView({ api }) {
   const [error, setError] = useState3("");
   useEffect2(() => {
     const range = RANGES.find((entry) => entry.key === rangeKey) ?? RANGES[1];
-    const to = /* @__PURE__ */ new Date();
-    const from = new Date(to.getTime() - range.days * 864e5);
+    let active = true;
     setData(null);
-    api.analytics({ from: from.toISOString(), to: to.toISOString() }).then(
-      setData,
-      (e) => setError(e.message)
+    setError("");
+    api.analytics({ days: range.days }).then(
+      (summary) => {
+        if (active) setData(summary);
+      },
+      (e) => {
+        if (active) setError(e.message);
+      }
     );
+    return () => {
+      active = false;
+    };
   }, [api, rangeKey]);
-  const localHours = useMemo2(() => {
-    if (!data) return [];
-    const offset = Math.round((/* @__PURE__ */ new Date()).getTimezoneOffset() / -60);
-    return data.hours.map((_, hour) => ({
-      hour,
-      count: data.hours[((hour - offset) % 24 + 24) % 24]
-    }));
-  }, [data]);
+  const localHours = data?.hours.map((count, hour) => ({ hour, count })) ?? [];
   if (error) return /* @__PURE__ */ jsx3("div", { className: "ost-view", children: /* @__PURE__ */ jsx3("div", { className: "ost-error", children: error }) });
   const kpis = data?.kpis ?? null;
   const previous = data?.previous;
@@ -552,7 +554,7 @@ function AnalyticsView({ api }) {
         /* @__PURE__ */ jsx3(
           Kpi,
           {
-            label: "Returning visitors",
+            label: "Repeat-day visitors",
             previous: previous ? { current: kpis.returningVisitors, prior: previous.returningVisitors } : void 0,
             value: String(kpis.returningVisitors)
           }
@@ -574,7 +576,7 @@ function AnalyticsView({ api }) {
           }
         ),
         /* @__PURE__ */ jsx3(Kpi, { label: "Pages per visitor", value: kpis.pagesPerVisitor.toFixed(1) }),
-        /* @__PURE__ */ jsx3(Kpi, { label: "Conversion rate", value: pct(kpis.conversionRate) }),
+        /* @__PURE__ */ jsx3(Kpi, { label: "Attributed visit conversion rate", value: pct(kpis.conversionRate) }),
         /* @__PURE__ */ jsx3(
           Kpi,
           {
@@ -585,15 +587,17 @@ function AnalyticsView({ api }) {
         )
       ] }),
       /* @__PURE__ */ jsxs3("p", { className: "ost-muted ost-analytics-note", children: [
-        "Returning visitors and cross-day totals use the pseudonymous cookie only after the visitor accepts analytics.",
-        kpis.visitors > 0 ? ` ${kpis.identifiedVisitors} of ${kpis.visitors} visitors in this range were cookie-identified.` : ""
+        "Traffic counts cover consented tracked visits. Requests sent includes every stored submission. Repeat-day visitors use the pseudonymous cookie only after the visitor accepts analytics.",
+        kpis.visitors > 0 ? ` ${kpis.identifiedVisitors} of ${kpis.visitors} visitors in this range were cookie-identified.` : "",
+        ` ${kpis.attributedSubmits} of ${kpis.formSubmits} requests were linked to a tracked visit.`,
+        ` Ranges use site-local calendar days including today. Dates and hours use ${data.timeZone}.`
       ] }),
       /* @__PURE__ */ jsxs3("section", { className: "ost-card ost-analytics-section", children: [
         /* @__PURE__ */ jsxs3("h3", { children: [
           "Daily visitors ",
           /* @__PURE__ */ jsxs3("span", { className: "ost-trend-key", children: [
             "\u25A0 visitors ",
-            /* @__PURE__ */ jsx3("em", { children: "\u25A0 conversions" })
+            /* @__PURE__ */ jsx3("em", { children: "\u25A0 verified actions" })
           ] })
         ] }),
         /* @__PURE__ */ jsx3(TrendChart, { trend: data.trend })
@@ -607,27 +611,27 @@ function AnalyticsView({ api }) {
               rows: data.pages.slice(0, 12).map((page) => ({
                 label: page.path === "/" ? "Home" : page.path,
                 value: page.views,
-                detail: page.conversions > 0 ? `\xB7 ${page.conversions} conv` : void 0
+                detail: page.conversions > 0 ? `\xB7 ${page.conversions} linked actions` : void 0
               }))
             }
           )
         ] }),
         /* @__PURE__ */ jsxs3("section", { className: "ost-card ost-analytics-section", children: [
-          /* @__PURE__ */ jsx3("h3", { children: "Where visitors come from" }),
+          /* @__PURE__ */ jsx3("h3", { children: "Where tracked visits come from" }),
           /* @__PURE__ */ jsx3(
             BarList,
             {
               rows: data.sources.map((source) => ({
                 label: source.source,
                 value: source.sessions,
-                detail: source.conversions > 0 ? `\xB7 ${source.conversions} conv` : void 0
+                detail: source.conversions > 0 ? `\xB7 ${source.conversions} linked actions` : void 0
               }))
             }
           )
         ] }),
         /* @__PURE__ */ jsxs3("section", { className: "ost-card ost-analytics-section", children: [
           /* @__PURE__ */ jsx3("h3", { children: "Form funnel" }),
-          /* @__PURE__ */ jsx3("p", { className: "ost-muted", children: "A view requires the first field to remain 75% visible for 2 seconds, or direct field interaction. Legacy form loads are excluded." }),
+          /* @__PURE__ */ jsx3("p", { className: "ost-muted", children: "Each step counts unique tracked visits, not raw events. A view requires the first field to remain 75% visible for 2 seconds, or direct field interaction. Starts and submissions supply the minimum when a view event is unavailable. Legacy form loads are excluded." }),
           data.forms.length === 0 ? /* @__PURE__ */ jsx3("p", { className: "ost-muted", children: "No form activity yet." }) : null,
           data.forms.map((form) => /* @__PURE__ */ jsxs3("div", { className: "ost-funnel", children: [
             /* @__PURE__ */ jsx3("strong", { children: form.form }),
@@ -645,7 +649,7 @@ function AnalyticsView({ api }) {
           ] }, form.form))
         ] }),
         /* @__PURE__ */ jsxs3("section", { className: "ost-card ost-analytics-section", children: [
-          /* @__PURE__ */ jsx3("h3", { children: "Visitor locations" }),
+          /* @__PURE__ */ jsx3("h3", { children: "Tracked visit locations" }),
           /* @__PURE__ */ jsx3(
             BarList,
             {
@@ -678,7 +682,11 @@ function AnalyticsView({ api }) {
             ": ",
             device.sessions
           ] }, device.device)) }),
-          /* @__PURE__ */ jsx3("h4", { className: "ost-analytics-subhead", children: "Busiest hours" }),
+          /* @__PURE__ */ jsxs3("h4", { className: "ost-analytics-subhead", children: [
+            "Busiest hours (",
+            data.timeZone,
+            ")"
+          ] }),
           /* @__PURE__ */ jsx3("div", { className: "ost-hours", children: localHours.map((entry) => {
             const max = Math.max(1, ...localHours.map((h) => h.count));
             return /* @__PURE__ */ jsx3(
@@ -686,14 +694,19 @@ function AnalyticsView({ api }) {
               {
                 className: "ost-hour-bar",
                 style: { height: `${Math.max(entry.count / max * 100, 4)}%` },
-                title: `${entry.hour}:00 \u2014 ${entry.count} views`
+                title: `${entry.hour}:00, ${entry.count} views`
               },
               entry.hour
             );
           }) }),
           /* @__PURE__ */ jsx3("h4", { className: "ost-analytics-subhead", children: "Broken links (404s)" }),
-          data.notFound.length === 0 ? /* @__PURE__ */ jsx3("p", { className: "ost-muted", children: "None \u2014 nice." }) : null,
-          /* @__PURE__ */ jsx3(BarList, { rows: data.notFound.slice(0, 8).map((entry) => ({ label: entry.path, value: entry.count })) })
+          /* @__PURE__ */ jsx3(
+            BarList,
+            {
+              emptyMessage: "No broken links recorded.",
+              rows: data.notFound.slice(0, 8).map((entry) => ({ label: entry.path, value: entry.count }))
+            }
+          )
         ] })
       ] })
     ] }) : null
@@ -741,9 +754,7 @@ function DashboardView({
   useEffect3(() => {
     api.dashboard().then(setData, (e) => setError(e.message));
     if (canReadAnalytics) {
-      const to = /* @__PURE__ */ new Date();
-      const from = new Date(to.getTime() - 7 * 864e5);
-      api.analytics({ from: from.toISOString(), to: to.toISOString() }).then(
+      api.analytics({ days: 7 }).then(
         (summary) => setWeek({
           visitors: summary.kpis.visitors,
           calls: summary.kpis.calls,
@@ -1447,7 +1458,7 @@ function FieldEditor({
 }
 
 // src/studio/views/PageEditor.tsx
-import { useCallback as useCallback2, useEffect as useEffect6, useMemo as useMemo3, useRef, useState as useState7 } from "react";
+import { useCallback as useCallback2, useEffect as useEffect6, useMemo as useMemo2, useRef, useState as useState7 } from "react";
 
 // src/studio/inline.ts
 function collectInlineTargets(definition, data) {
@@ -2175,7 +2186,7 @@ function PageEditor({
   const selectedIndex = selectedId ? layout.findIndex((block) => block.id === selectedId) : -1;
   const selected = selectedIndex >= 0 ? layout[selectedIndex] : null;
   const selectedDefinition = selected ? registry.get(selected.type) : void 0;
-  const changedSincePublish = useMemo3(() => {
+  const changedSincePublish = useMemo2(() => {
     if (!page) return false;
     if (page.status !== "published") return true;
     return dirty || title !== (page.published_title ?? "") || JSON.stringify(seo) !== JSON.stringify(page.published_seo ?? {}) || JSON.stringify(layout) !== JSON.stringify(page.published_layout ?? []);
@@ -2348,7 +2359,7 @@ function PageEditor({
     setDirty(false);
     setMessage("Version restored into draft.");
   };
-  const palette = useMemo3(() => registry.palette(), [registry]);
+  const palette = useMemo2(() => registry.palette(), [registry]);
   const insertBlock = (type, at) => {
     const instance = registry.createInstance(type);
     const next = [...layout];
@@ -3314,7 +3325,7 @@ function UsersView({ api, meId }) {
 }
 
 // src/studio/views/views.tsx
-import { useEffect as useEffect10, useMemo as useMemo4, useState as useState11 } from "react";
+import { useEffect as useEffect10, useMemo as useMemo3, useState as useState11 } from "react";
 import { Fragment as Fragment3, jsx as jsx11, jsxs as jsxs11 } from "react/jsx-runtime";
 var pageStatus = (page) => {
   if (page.publish_at) return { label: "scheduled", live: false };
@@ -3401,7 +3412,7 @@ function MediaView({
   const [selected, setSelected] = useState11(null);
   const [search, setSearch] = useState11("");
   const [error, setError] = useState11("");
-  const visible = useMemo4(() => {
+  const visible = useMemo3(() => {
     const term = search.trim().toLowerCase();
     if (!term) return media;
     return media.filter(
@@ -3742,7 +3753,7 @@ var NAV = [
 ];
 function Studio({ registry, globals, siteName, logoUrl, supabaseUrl }) {
   const { session, loading, getToken, signOut } = useStudioSession();
-  const api = useMemo5(() => createStudioApi({ getToken }), [getToken]);
+  const api = useMemo4(() => createStudioApi({ getToken }), [getToken]);
   useEffect11(() => {
     try {
       localStorage.setItem("orion-analytics-exclude", "1");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orion-studios/cms",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "description": "Orion CMS v2 core engine \u2014 JSONB content model on Supabase primitives",
   "type": "module",
   "exports": {

package/sql/bootstrap.sql

@@ -164,6 +164,12 @@ where scheduled_version_id is not null
 
 create unique index if not exists cms_page_versions_page_id_id_idx
   on cms_page_versions (page_id, id);
+create index if not exists cms_pages_draft_version_fk_idx
+  on cms_pages (id, draft_version_id);
+create index if not exists cms_pages_published_version_fk_idx
+  on cms_pages (id, published_version_id);
+create index if not exists cms_pages_scheduled_version_fk_idx
+  on cms_pages (id, scheduled_version_id);
 create index if not exists cms_pages_scheduled_publish_due_idx
   on cms_pages (publish_at)
   where publish_at is not null and scheduled_version_id is not null;
@@ -1074,6 +1080,49 @@ begin
 end;
 $$;
 
+-- Aggregate-only visitor count for care-report sharing. The service role
+-- invokes it, and raw visitor and session identifiers never leave PostgreSQL.
+create or replace function public.cms_analytics_unique_visitors(
+  p_from timestamptz,
+  p_to timestamptz
+) returns bigint
+language sql
+stable
+security invoker
+set search_path = ''
+as $$
+  with session_identities as (
+    select
+      session_key,
+      max(nullif(visitor_key, '')) as visitor_key,
+      min(id) as first_event_id
+    from public.cms_events
+    where created_at >= p_from
+      and created_at <= p_to
+    group by session_key
+  )
+  select count(distinct coalesce(
+    visitor_key,
+    nullif(session_key, ''),
+    'event:' || first_event_id::text
+  ))::bigint
+  from session_identities;
+$$;
+
+revoke execute on function public.cms_analytics_unique_visitors(timestamptz, timestamptz) from public;
+do $analytics_aggregate_grants$
+begin
+  if exists (select 1 from pg_roles where rolname = 'anon') then
+    revoke execute on function public.cms_analytics_unique_visitors(timestamptz, timestamptz) from anon;
+  end if;
+  if exists (select 1 from pg_roles where rolname = 'authenticated') then
+    revoke execute on function public.cms_analytics_unique_visitors(timestamptz, timestamptz) from authenticated;
+  end if;
+  if exists (select 1 from pg_roles where rolname = 'service_role') then
+    grant execute on function public.cms_analytics_unique_visitors(timestamptz, timestamptz) to service_role;
+  end if;
+end $analytics_aggregate_grants$;
+
 -- 3) Row-level security -------------------------------------------------------
 -- Defense-in-depth. The app's API layer (service role) is the primary
 -- enforcement point; anonymous access is read-only and published-only.

package/sql/migrations/20260830143322_cms_analytics_unique_visitors.sql

@@ -0,0 +1,43 @@
+-- Aggregate-only visitor count for care-report sharing. Raw visitor and
+-- session identifiers stay inside PostgreSQL.
+create or replace function public.cms_analytics_unique_visitors(
+  p_from timestamptz,
+  p_to timestamptz
+) returns bigint
+language sql
+stable
+security invoker
+set search_path = ''
+as $$
+  with session_identities as (
+    select
+      session_key,
+      max(nullif(visitor_key, '')) as visitor_key,
+      min(id) as first_event_id
+    from public.cms_events
+    where created_at >= p_from
+      and created_at <= p_to
+    group by session_key
+  )
+  select count(distinct coalesce(
+    visitor_key,
+    nullif(session_key, ''),
+    'event:' || first_event_id::text
+  ))::bigint
+  from session_identities;
+$$;
+
+revoke execute on function public.cms_analytics_unique_visitors(timestamptz, timestamptz) from public;
+
+do $analytics_aggregate_grants$
+begin
+  if exists (select 1 from pg_roles where rolname = 'anon') then
+    revoke execute on function public.cms_analytics_unique_visitors(timestamptz, timestamptz) from anon;
+  end if;
+  if exists (select 1 from pg_roles where rolname = 'authenticated') then
+    revoke execute on function public.cms_analytics_unique_visitors(timestamptz, timestamptz) from authenticated;
+  end if;
+  if exists (select 1 from pg_roles where rolname = 'service_role') then
+    grant execute on function public.cms_analytics_unique_visitors(timestamptz, timestamptz) to service_role;
+  end if;
+end $analytics_aggregate_grants$;

package/sql/migrations/20260830202942_cms_page_version_fk_indexes.sql

@@ -0,0 +1,11 @@
+-- Cover the three composite foreign keys from cms_pages to cms_page_versions.
+-- PostgreSQL does not create indexes on the referencing columns automatically.
+
+create index if not exists cms_pages_draft_version_fk_idx
+  on cms_pages (id, draft_version_id);
+
+create index if not exists cms_pages_published_version_fk_idx
+  on cms_pages (id, published_version_id);
+
+create index if not exists cms_pages_scheduled_version_fk_idx
+  on cms_pages (id, scheduled_version_id);