@iann29/rastro 0.1.0-alpha.9 → 0.1.0

package/src/component/localTime.ts

@@ -0,0 +1,167 @@
+import { DAY_MS, HOUR_MS } from "./constants.js";
+
+/**
+ * Local calendar days for a site's timezone. Aggregates are bucketed by UTC
+ * hour and UTC day; a site with a timezone also gets a `localDay` bucket per
+ * calendar day in that zone (see foldAggregates), so "yesterday" in São Paulo
+ * ends at midnight in São Paulo, not at 21:00. Every function here uses the
+ * runtime's Intl data — the same data `validateTimezone` relies on.
+ */
+
+const formatters = new Map<string, Intl.DateTimeFormat>();
+
+function formatter(timeZone: string): Intl.DateTimeFormat {
+  let cached = formatters.get(timeZone);
+  if (!cached) {
+    cached = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      hourCycle: "h23",
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+    });
+    formatters.set(timeZone, cached);
+  }
+  return cached;
+}
+
+type LocalParts = {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+};
+
+function localParts(timestamp: number, timeZone: string): LocalParts {
+  const parts: Partial<LocalParts> = {};
+  for (const part of formatter(timeZone).formatToParts(timestamp)) {
+    if (part.type === "literal") continue;
+    parts[part.type as keyof LocalParts] = Number(part.value);
+  }
+  return {
+    year: parts.year ?? 1970,
+    month: parts.month ?? 1,
+    day: parts.day ?? 1,
+    // Some engines print 24 for midnight even with hourCycle h23.
+    hour: (parts.hour ?? 0) % 24,
+    minute: parts.minute ?? 0,
+    second: parts.second ?? 0,
+  };
+}
+
+/** The zone's offset from UTC at `timestamp`, in milliseconds (east is positive). */
+export function localOffsetMs(timestamp: number, timeZone: string): number {
+  const parts = localParts(timestamp, timeZone);
+  const asUtc = Date.UTC(
+    parts.year,
+    parts.month - 1,
+    parts.day,
+    parts.hour,
+    parts.minute,
+    parts.second,
+  );
+  return asUtc - (timestamp - (((timestamp % 1000) + 1000) % 1000));
+}
+
+function localDateKey(timestamp: number, timeZone: string): number {
+  const parts = localParts(timestamp, timeZone);
+  return parts.year * 10_000 + parts.month * 100 + parts.day;
+}
+
+/**
+ * The first instant of the local calendar day that contains `timestamp`, as
+ * a UTC millisecond timestamp. Where a transition removes midnight (Chile
+ * springs forward at 00:00), the day starts at the first instant that exists.
+ */
+export function localDayStart(timestamp: number, timeZone: string): number {
+  const parts = localParts(timestamp, timeZone);
+  const target = parts.year * 10_000 + parts.month * 100 + parts.day;
+  const guess = Date.UTC(parts.year, parts.month - 1, parts.day);
+  // The offset in force at UTC midnight is usually the one at local midnight
+  // too; around a transition it is not, so a second and third candidate use
+  // the offset observed at the previous guess, and the earliest instant that
+  // still falls on the target date wins.
+  const first = guess - localOffsetMs(guess, timeZone);
+  const second = guess - localOffsetMs(first, timeZone);
+  const third = guess - localOffsetMs(second, timeZone);
+  const candidates = [first, second, third]
+    .filter((candidate) => localDateKey(candidate, timeZone) === target)
+    .sort((left, right) => left - right);
+  return candidates[0] ?? first;
+}
+
+/** The start of the local day after the one starting at `dayStart`. */
+export function nextLocalDayStart(dayStart: number, timeZone: string): number {
+  return localDayStart(dayStart + DAY_MS + 12 * HOUR_MS, timeZone);
+}
+
+/** The start of the local day before the one starting at `dayStart`. */
+export function previousLocalDayStart(
+  dayStart: number,
+  timeZone: string,
+): number {
+  return localDayStart(dayStart - 12 * HOUR_MS, timeZone);
+}
+
+/** Every local day start from `from` through `to`, when `from` is one. */
+export function localDayStarts(
+  from: number,
+  to: number,
+  timeZone: string,
+): number[] {
+  const starts: number[] = [];
+  let cursor = from;
+  while (cursor <= to) {
+    starts.push(cursor);
+    cursor = nextLocalDayStart(cursor, timeZone);
+  }
+  return starts;
+}
+
+/** Whether `[from, to]` covers whole local days in the zone, inclusively. */
+export function isLocalDayAligned(
+  from: number,
+  to: number,
+  timeZone: string,
+): boolean {
+  return (
+    localDayStart(from, timeZone) === from &&
+    localDayStart(to + 1, timeZone) === to + 1
+  );
+}
+
+/**
+ * A site's timezone when it needs its own day buckets: undefined for no
+ * timezone and for zones that never leave UTC, whose local days are the UTC
+ * days already kept.
+ */
+export function localDayTimezone(
+  timezone: string | undefined | null,
+): string | undefined {
+  if (!timezone) return undefined;
+  try {
+    const year = new Date().getUTCFullYear();
+    const january = Date.UTC(year, 0, 1);
+    const july = Date.UTC(year, 6, 1);
+    return localOffsetMs(january, timezone) === 0 &&
+      localOffsetMs(july, timezone) === 0
+      ? undefined
+      : timezone;
+  } catch {
+    return undefined;
+  }
+}
+
+/** One timezone shared by every site, or undefined when they differ. */
+export function sharedLocalTimezone(
+  timezones: Array<string | undefined>,
+): string | undefined {
+  const distinct = new Set(timezones);
+  if (distinct.size !== 1) return undefined;
+  return timezones[0];
+}

package/src/component/reports.ts

@@ -39,6 +39,13 @@ import {
   type VisitorSketch,
 } from "./cardinality.js";
 import { fail } from "./errors.js";
+import {
+  isLocalDayAligned,
+  localDayStart,
+  localDayStarts,
+  localDayTimezone,
+  sharedLocalTimezone,
+} from "./localTime.js";
 import {
   compareJourneyEvents,
   hydrateEventContexts,
@@ -96,6 +103,18 @@ const liveSessionDocumentValidator = v.object({
   eventCount: v.number(),
   previousPath: v.optional(v.string()),
   movedAt: v.optional(v.number()),
+  entryPath: v.optional(v.string()),
+  returning: v.optional(v.boolean()),
+  utmCampaign: v.optional(v.string()),
+  affiliateSlug: v.optional(v.string()),
+  conversionCount: v.optional(v.number()),
+  funnel: v.optional(
+    v.object({
+      funnelId: v.id("funnels"),
+      step: v.number(),
+      steps: v.number(),
+    }),
+  ),
 });
 const conversionDocumentValidator = v.object({
   _id: v.id("conversions"),
@@ -126,6 +145,12 @@ const metricTotalsValidator = v.object({
   visitors: v.number(),
   conversions: v.number(),
   revenueCents: v.number(),
+  // Engagement: summed session duration, sessions that reached a second
+  // pageview, and first-ever sessions of a visitor. Zero for buckets older
+  // than the counters; metadata.engagement says whether the range is covered.
+  durationMs: v.number(),
+  continuedSessions: v.number(),
+  newVisitors: v.number(),
 });
 const timePointValidator = metricTotalsValidator.extend({
   timestamp: v.number(),
@@ -135,6 +160,14 @@ const topItemValidator = v.object({
   count: v.number(),
   revenueCents: v.number(),
 });
+// What a breakdown's `count` is: pageviews for pages and sessions for the
+// other dimensions once every bucket in the range carries those counters,
+// raw event volume for ranges that reach back before they existed.
+const breakdownBasisValidator = v.union(
+  v.literal("pageviews"),
+  v.literal("sessions"),
+  v.literal("eventVolume"),
+);
 const coverageStateValidator = v.union(
   v.literal("complete"),
   v.literal("partial"),
@@ -152,7 +185,8 @@ const rangeSemanticsValidator = v.object({
   from: v.number(),
   to: v.number(),
   boundary: v.literal("inclusive"),
-  timezone: v.literal("UTC"),
+  // "UTC", or the site timezone whose calendar days a daily overview used.
+  timezone: v.string(),
 });
 const reportMetadataValidator = v.object({
   basis: v.union(v.literal("dailyRollup"), v.literal("boundedLegacy")),
@@ -182,6 +216,10 @@ export const overview = query({
     topBrowsers: v.array(topItemValidator),
     topEvents: v.array(topItemValidator),
     topGoals: v.array(topItemValidator),
+    // The session's lowercase utm_medium, ranked like campaigns.
+    topMediums: v.array(topItemValidator),
+    // Destination hosts of outbound clicks, ranked by clicks.
+    topOutbound: v.array(topItemValidator),
     metadata: v.object({
       visitors: v.object({
         basis: v.union(
@@ -194,15 +232,25 @@ export const overview = query({
         precision: v.union(v.number(), v.null()),
       }),
       breakdowns: v.object({
-        topSources: v.literal("eventVolume"),
-        topCampaigns: v.literal("eventVolume"),
-        topPages: v.literal("eventVolume"),
-        topCountries: v.literal("eventVolume"),
-        topDevices: v.literal("eventVolume"),
-        topBrowsers: v.literal("eventVolume"),
+        topSources: breakdownBasisValidator,
+        topCampaigns: breakdownBasisValidator,
+        topPages: breakdownBasisValidator,
+        topCountries: breakdownBasisValidator,
+        topDevices: breakdownBasisValidator,
+        topBrowsers: breakdownBasisValidator,
         topEvents: v.literal("eventVolume"),
         topGoals: v.literal("goalCompletionVolume"),
+        topMediums: breakdownBasisValidator,
+        topOutbound: v.literal("eventVolume"),
       }),
+      // Since when every site in the request records the medium and outbound
+      // slots; null while one of them has not stamped it. A range that starts
+      // earlier ranks those two breakdowns from partial data.
+      dimensionsSince: v.union(v.number(), v.null()),
+      // "counted" when every bucket in the range carries the engagement
+      // counters, so bounce rate, duration, pages per session and new
+      // visitors can be derived from the totals; "unavailable" otherwise.
+      engagement: v.union(v.literal("counted"), v.literal("unavailable")),
       coverage: resultCoverageValidator,
       range: rangeSemanticsValidator,
       features: v.object({
@@ -216,11 +264,13 @@ export const overview = query({
   handler: async (ctx, args) => {
     const siteIds = validateSiteIds(args.siteIds);
     const currencies = new Set<string>();
+    const siteTimezones: Array<string | undefined> = [];
     for (const siteId of siteIds) {
       const site = await ctx.db.get("sites", siteId);
       if (!site)
         fail("NOT_FOUND", "site not found", { siteId: String(siteId) });
       currencies.add(site.currency ?? "USD");
+      siteTimezones.push(localDayTimezone(site.timezone));
     }
     if (currencies.size !== 1) {
       fail("CURRENCY_MISMATCH", "overview sites must use the same currency", {
@@ -238,10 +288,64 @@ export const overview = query({
       fail("INVALID_ARGUMENT", "hourly reports are limited to 24 hours");
     }
     const intervalMs = interval === "hour" ? HOUR_MS : DAY_MS;
-    requireAlignedRange(from, to, intervalMs, `${interval} overview`);
-    const firstBucket = Math.floor(from / intervalMs) * intervalMs;
-    const lastBucket = Math.floor(to / intervalMs) * intervalMs;
-    const bucketCount = Math.floor((lastBucket - firstBucket) / intervalMs) + 1;
+    // Sites that share a timezone answer a daily range that covers whole
+    // calendar days in that zone from their local-day buckets; any other
+    // daily range must cover whole UTC days, as before.
+    const siteTimezone =
+      interval === "day" ? sharedLocalTimezone(siteTimezones) : undefined;
+    const localDays =
+      siteTimezone !== undefined && isLocalDayAligned(from, to, siteTimezone);
+    if (!localDays) {
+      requireAlignedRange(
+        from,
+        to,
+        intervalMs,
+        `${interval} overview`,
+        siteTimezone,
+      );
+    }
+    const granularity: "hour" | "day" | "localDay" = localDays
+      ? "localDay"
+      : interval;
+    const controls = await Promise.all(
+      siteIds.map((siteId) =>
+        ctx.db
+          .query("analyticsCoverage")
+          .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
+          .unique(),
+      ),
+    );
+    // Local-day buckets are complete from each site's stamp (its first ingest
+    // after the upgrade or after a timezone change, plus the safety delay).
+    // Buckets before it belong to another zone's days or to no complete day
+    // and are left out; the coverage says since when the days are whole.
+    let localDaysFrom = Number.POSITIVE_INFINITY;
+    if (localDays) {
+      localDaysFrom = controls.reduce(
+        (latest, control) =>
+          control?.localDaySince === undefined
+            ? Number.POSITIVE_INFINITY
+            : Math.max(latest, control.localDaySince),
+        0,
+      );
+    }
+    const bucketStarts = localDays
+      ? localDayStarts(from, to, siteTimezone!)
+      : [];
+    const bucketStartSet = new Set(bucketStarts);
+    const localDaysFirstBucket =
+      localDays && Number.isFinite(localDaysFrom)
+        ? localDayStart(localDaysFrom, siteTimezone!)
+        : Number.POSITIVE_INFINITY;
+    const firstBucket = localDays
+      ? bucketStarts[0]!
+      : Math.floor(from / intervalMs) * intervalMs;
+    const lastBucket = localDays
+      ? bucketStarts[bucketStarts.length - 1]!
+      : Math.floor(to / intervalMs) * intervalMs;
+    const bucketCount = localDays
+      ? bucketStarts.length
+      : Math.floor((lastBucket - firstBucket) / intervalMs) + 1;
     const perSiteLimit =
       bucketCount *
       (interval === "hour" ? HOURLY_AGGREGATE_SHARDS : AGGREGATE_SHARDS);
@@ -260,12 +364,20 @@ export const overview = query({
     let visitorsComplete = true;
     const dimensions = new Map<
       string,
-      { value: string; count: number; revenueCents: number }
+      {
+        value: string;
+        count: number;
+        revenueCents: number;
+        pageviews: number;
+        sessions: number;
+      }
     >();
     const overviewDataset =
-      interval === "hour"
+      granularity === "hour"
         ? ("overviewHour" as const)
-        : ("overviewDay" as const);
+        : granularity === "day"
+          ? ("overviewDay" as const)
+          : ("overviewLocalDay" as const);
 
     await assertSourceAvailable(ctx, siteIds, [overviewDataset], from);
 
@@ -275,13 +387,20 @@ export const overview = query({
         .withIndex("by_siteId_and_granularity_and_bucketStart", (range) =>
           range
             .eq("siteId", siteId)
-            .eq("granularity", interval)
+            .eq("granularity", granularity)
             .gte("bucketStart", firstBucket)
             .lte("bucketStart", lastBucket),
         )
         .take(perSiteLimit + 1);
       failIfIncomplete(buckets, perSiteLimit, "overview aggregate buckets");
       for (const bucket of buckets) {
+        if (
+          localDays &&
+          (!bucketStartSet.has(bucket.bucketStart) ||
+            bucket.bucketStart < localDaysFirstBucket)
+        ) {
+          continue;
+        }
         addMetrics(totals, bucket);
         const point = points.get(bucket.bucketStart) ?? emptyTotals();
         addMetrics(point, bucket);
@@ -308,18 +427,48 @@ export const overview = query({
             value: dimension.value,
             count: 0,
             revenueCents: 0,
+            pageviews: 0,
+            sessions: 0,
           };
           current.count += dimension.count;
           current.revenueCents += dimension.revenueCents;
+          current.pageviews += dimension.pageviews ?? 0;
+          current.sessions += dimension.sessions ?? 0;
           dimensions.set(key, current);
         }
       }
     }
 
-    const top = (type: string) =>
+    // Pages rank by pageviews and the other dimensions by sessions once every
+    // site's counters are proven for the whole range; before that stamp a
+    // bucket may hold slots without them, so the ranking stays event volume.
+    const countersProven = controls.every(
+      (control) =>
+        control?.countersSince !== undefined && from >= control.countersSince,
+    );
+    const pageBasis = countersProven
+      ? ("pageviews" as const)
+      : ("eventVolume" as const);
+    const sessionBasis = countersProven
+      ? ("sessions" as const)
+      : ("eventVolume" as const);
+    const top = (
+      type: string,
+      basis: "pageviews" | "sessions" | "eventVolume",
+    ) =>
       [...dimensions.entries()]
         .filter(([key]) => key.startsWith(`${type}:`))
-        .map(([, value]) => value)
+        .map(([, item]) => ({
+          value: item.value,
+          count:
+            basis === "pageviews"
+              ? item.pageviews
+              : basis === "sessions"
+                ? item.sessions
+                : item.count,
+          revenueCents: item.revenueCents,
+        }))
+        .filter((item) => item.count > 0 || item.revenueCents > 0)
         .sort(
           (left, right) =>
             right.count - left.count || left.value.localeCompare(right.value),
@@ -337,6 +486,19 @@ export const overview = query({
       datasets: [overviewDataset],
       complete: visitorsComplete,
     });
+    if (localDays) {
+      // The stamp, not the oldest row, says where the site's days begin.
+      const availableFrom = Number.isFinite(localDaysFrom)
+        ? Math.max(coverage.availableFrom ?? 0, localDaysFrom)
+        : null;
+      coverage.availableFrom = availableFrom;
+      if (
+        coverage.state === "complete" &&
+        (availableFrom === null || from < availableFrom)
+      ) {
+        coverage.state = availableFrom === null ? "unavailable" : "partial";
+      }
+    }
     const visitorBasis: "estimatedUnique" | "bucketOccurrences" =
       visitorsComplete ? "estimatedUnique" : "bucketOccurrences";
     return {
@@ -348,14 +510,16 @@ export const overview = query({
       timeSeries: [...points.entries()]
         .sort(([left], [right]) => left - right)
         .map(([timestamp, metrics]) => ({ timestamp, ...metrics })),
-      topSources: top("source"),
-      topCampaigns: top("campaign"),
-      topPages: top("page"),
-      topCountries: top("country"),
-      topDevices: top("device"),
-      topBrowsers: top("browser"),
-      topEvents: top("event"),
-      topGoals: top("goal"),
+      topSources: top("source", sessionBasis),
+      topCampaigns: top("campaign", sessionBasis),
+      topPages: top("page", pageBasis),
+      topCountries: top("country", sessionBasis),
+      topDevices: top("device", sessionBasis),
+      topBrowsers: top("browser", sessionBasis),
+      topEvents: top("event", "eventVolume"),
+      topGoals: top("goal", "eventVolume"),
+      topMediums: top("medium", sessionBasis),
+      topOutbound: top("outbound", "eventVolume"),
       metadata: {
         visitors: {
           basis: visitorBasis,
@@ -365,17 +529,27 @@ export const overview = query({
           precision: visitorsComplete ? 6 : null,
         },
         breakdowns: {
-          topSources: "eventVolume" as const,
-          topCampaigns: "eventVolume" as const,
-          topPages: "eventVolume" as const,
-          topCountries: "eventVolume" as const,
-          topDevices: "eventVolume" as const,
-          topBrowsers: "eventVolume" as const,
+          topSources: sessionBasis,
+          topCampaigns: sessionBasis,
+          topPages: pageBasis,
+          topCountries: sessionBasis,
+          topDevices: sessionBasis,
+          topBrowsers: sessionBasis,
           topEvents: "eventVolume" as const,
           topGoals: "goalCompletionVolume" as const,
+          topMediums: sessionBasis,
+          topOutbound: "eventVolume" as const,
         },
+        dimensionsSince: controls.every(
+          (control) => control?.dimensionsSince !== undefined,
+        )
+          ? Math.max(...controls.map((control) => control!.dimensionsSince!))
+          : null,
+        engagement: countersProven
+          ? ("counted" as const)
+          : ("unavailable" as const),
         coverage,
-        range: rangeSemantics(from, to),
+        range: rangeSemantics(from, to, localDays ? siteTimezone : "UTC"),
         features: {
           sessionReplay: "unsupported" as const,
           errorInsights: "unsupported" as const,
@@ -447,6 +621,14 @@ export const liveVisitors = query({
         eventCount: row.eventCount,
         ...(row.previousPath ? { previousPath: row.previousPath } : {}),
         ...(row.movedAt !== undefined ? { movedAt: row.movedAt } : {}),
+        ...(row.entryPath ? { entryPath: row.entryPath } : {}),
+        ...(row.returning !== undefined ? { returning: row.returning } : {}),
+        ...(row.utmCampaign ? { utmCampaign: row.utmCampaign } : {}),
+        ...(row.affiliateSlug ? { affiliateSlug: row.affiliateSlug } : {}),
+        ...(row.conversionCount !== undefined
+          ? { conversionCount: row.conversionCount }
+          : {}),
+        ...(row.funnel ? { funnel: row.funnel } : {}),
       }));
   },
 });
@@ -1523,6 +1705,7 @@ export const vitalsReport = query({
 const coverageDatasetValidator = v.union(
   v.literal("overviewHour"),
   v.literal("overviewDay"),
+  v.literal("overviewLocalDay"),
   v.literal("events"),
   v.literal("sessions"),
   v.literal("conversions"),
@@ -1555,6 +1738,7 @@ export const dataCoverage = query({
     const datasets = [
       "overviewHour",
       "overviewDay",
+      "overviewLocalDay",
       "events",
       "sessions",
       "conversions",
@@ -1948,6 +2132,7 @@ async function siteMapDatasetCoverage(
 type PublicCoverageDataset =
   | "overviewHour"
   | "overviewDay"
+  | "overviewLocalDay"
   | "events"
   | "sessions"
   | "conversions"
@@ -1960,6 +2145,7 @@ type PublicCoverageDataset =
 type CoverageSource =
   | "overviewHour"
   | "overviewDay"
+  | "overviewLocalDay"
   | "events"
   | "sessions"
   | "conversions"
@@ -1993,9 +2179,17 @@ async function sourceRange(
   siteId: Id<"sites">,
   source: CoverageSource,
 ): Promise<SourceRange | null> {
-  if (source === "overviewHour" || source === "overviewDay") {
+  if (
+    source === "overviewHour" ||
+    source === "overviewDay" ||
+    source === "overviewLocalDay"
+  ) {
     const granularity =
-      source === "overviewHour" ? ("hour" as const) : ("day" as const);
+      source === "overviewHour"
+        ? ("hour" as const)
+        : source === "overviewDay"
+          ? ("day" as const)
+          : ("localDay" as const);
     const [first, last] = await Promise.all([
       ctx.db
         .query("aggregateBuckets")
@@ -2144,6 +2338,9 @@ type MetricTotals = {
   visitors: number;
   conversions: number;
   revenueCents: number;
+  durationMs: number;
+  continuedSessions: number;
+  newVisitors: number;
 };
 
 function emptyTotals(): MetricTotals {
@@ -2157,10 +2354,23 @@ function emptyTotals(): MetricTotals {
     visitors: 0,
     conversions: 0,
     revenueCents: 0,
+    durationMs: 0,
+    continuedSessions: 0,
+    newVisitors: 0,
   };
 }
 
-function addMetrics(target: MetricTotals, source: MetricTotals) {
+function addMetrics(
+  target: MetricTotals,
+  source: Omit<
+    MetricTotals,
+    "durationMs" | "continuedSessions" | "newVisitors"
+  > & {
+    durationMs?: number;
+    continuedSessions?: number;
+    newVisitors?: number;
+  },
+) {
   target.events += source.events;
   target.pageviews += source.pageviews;
   target.clicks += source.clicks;
@@ -2170,6 +2380,9 @@ function addMetrics(target: MetricTotals, source: MetricTotals) {
   target.visitors += source.visitors;
   target.conversions += source.conversions;
   target.revenueCents += source.revenueCents;
+  target.durationMs += source.durationMs ?? 0;
+  target.continuedSessions += source.continuedSessions ?? 0;
+  target.newVisitors += source.newVisitors ?? 0;
 }
 
 function validateSiteIds<T>(siteIds: T[]): T[] {
@@ -2212,22 +2425,31 @@ function requireAlignedRange(
   to: number,
   intervalMs: number,
   report: string,
+  siteTimezone?: string,
 ) {
   if (!isAlignedRange(from, to, intervalMs)) {
     fail(
       "REPORT_INCOMPLETE",
-      `${report} requires complete inclusive UTC bucket boundaries`,
-      { from, to, intervalMs, timezone: "UTC" },
+      siteTimezone
+        ? `${report} requires complete inclusive UTC bucket boundaries, or whole calendar days in ${siteTimezone}`
+        : `${report} requires complete inclusive UTC bucket boundaries`,
+      {
+        from,
+        to,
+        intervalMs,
+        timezone: "UTC",
+        siteTimezone: siteTimezone ?? null,
+      },
     );
   }
 }
 
-function rangeSemantics(from: number, to: number) {
+function rangeSemantics(from: number, to: number, timezone = "UTC") {
   return {
     from,
     to,
     boundary: "inclusive" as const,
-    timezone: "UTC" as const,
+    timezone,
   };
 }